From 76f7f16eff3ace8b5fde13031417561fff85496d Mon Sep 17 00:00:00 2001 From: Bryan Ramos Date: Thu, 2 Apr 2026 07:58:41 -0400 Subject: [PATCH] fix: resolve review round 2 findings - CLAUDE.md: add missing message-schema and project to skill list - debugger, documenter: add qa-checklist to skills (worker-protocol references it) - message-schema: make moderate_count/minor_count required on review_verdict, make has_blockers required on plan_result, remove dangling format field - orchestrate: split blocked routing by type (plan_result vs worker_submission) - worker-protocol: remove stale migration note about freetext RFR - qa-checklist: add plan_result has_blockers hard rule - architect: remove dangling format field from plan_result envelope --- CLAUDE.md | 2 +- agents/architect.md | 1 - agents/debugger.md | 1 + agents/documenter.md | 1 + skills/message-schema/SKILL.md | 8 +++----- skills/orchestrate/SKILL.md | 3 ++- skills/qa-checklist/SKILL.md | 1 + skills/worker-protocol/SKILL.md | 2 +- 8 files changed, 10 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ea55f37..1e2879f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ # Global Claude Code Instructions Rules are modularized in `~/.claude/rules/` and loaded automatically. -Agent-team specific protocols live in skills (orchestrate, conventions, worker-protocol, qa-checklist). +Agent-team specific protocols live in skills (orchestrate, conventions, worker-protocol, qa-checklist, message-schema, project). diff --git a/agents/architect.md b/agents/architect.md index 9c4cfb5..6256132 100644 --- a/agents/architect.md +++ b/agents/architect.md @@ -104,7 +104,6 @@ After writing the plan file, return a `plan_result` envelope: type: plan_result signal: plan_complete | blocked plan_file: .claude/plans/kebab-case-title.md -format: brief | full wave_count: 3 step_count: 7 risk_tags: diff --git a/agents/debugger.md b/agents/debugger.md index 329fd5c..33fb7bc 100644 --- a/agents/debugger.md +++ b/agents/debugger.md @@ -9,6 +9,7 @@ skills: - conventions - worker-protocol - message-schema + - qa-checklist - project --- diff --git a/agents/documenter.md b/agents/documenter.md index 9e578b0..b68a41e 100644 --- a/agents/documenter.md +++ b/agents/documenter.md @@ -10,6 +10,7 @@ skills: - conventions - worker-protocol - message-schema + - qa-checklist - project --- diff --git a/skills/message-schema/SKILL.md b/skills/message-schema/SKILL.md index 63f993f..626bf52 100644 --- a/skills/message-schema/SKILL.md +++ b/skills/message-schema/SKILL.md @@ -90,8 +90,7 @@ ac_coverage: --- ``` -Required: `type`, `signal`, `critical_count`, `ac_coverage` -Optional: `moderate_count`, `minor_count` +Required: `type`, `signal`, `critical_count`, `moderate_count`, `minor_count`, `ac_coverage` **Hard rule:** `critical_count > 0` requires `signal: fail`. @@ -153,7 +152,6 @@ Emitted by: architect (Phase 2) type: plan_result signal: plan_complete | blocked plan_file: .claude/plans/kebab-case-title.md -format: brief | full wave_count: 3 step_count: 7 risk_tags: @@ -163,8 +161,8 @@ has_blockers: false --- ``` -Required: `type`, `signal`, `plan_file`, `wave_count`, `risk_tags` -Optional: `format`, `step_count`, `has_blockers` +Required: `type`, `signal`, `plan_file`, `wave_count`, `risk_tags`, `has_blockers` +Optional: `step_count` **Routing:** `has_blockers: true` triggers user escalation before worker dispatch. diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md index b789b0d..ac88039 100644 --- a/skills/orchestrate/SKILL.md +++ b/skills/orchestrate/SKILL.md @@ -228,7 +228,8 @@ All agent communication uses typed YAML frontmatter envelopes defined in the `me | `signal: triage_complete` | architect → you | Check `research_needed`, spawn researchers or resume architect | | `signal: plan_complete` | architect → you | Read plan file, begin wave dispatch | | `signal: research_complete` | researcher → you | Collect, assemble into Research Context | -| `signal: blocked` | architect/worker → you | If from `plan_result`: escalate to user before dispatching workers. Otherwise: investigate or unblock. | +| `signal: blocked` (`plan_result`) | architect → you | Escalate to user before dispatching workers | +| `signal: blocked` (`worker_submission`) | worker → you | Investigate blocker, unblock or reassign | | `signal: escalate` | any → you | Escalate to user with context | When dispatching agents, use the orchestrator→agent envelope types (`task_assignment`, `revision_request`, `approval`, `triage_request`, `architecture_request`, `research_request`) from the message-schema skill. diff --git a/skills/qa-checklist/SKILL.md b/skills/qa-checklist/SKILL.md index 3ebcf34..045e02f 100644 --- a/skills/qa-checklist/SKILL.md +++ b/skills/qa-checklist/SKILL.md @@ -48,6 +48,7 @@ Before returning your output, validate against every item below. If you find a v - Are hard rules satisfied? - `review_verdict`: `critical_count > 0` requires `signal: fail` - `audit_verdict`: `security_findings.critical > 0` or `build_status: fail` or `test_status: fail` requires `signal: fail` + - `plan_result`: `has_blockers: true` requires orchestrator escalation to user before worker dispatch ## After validation diff --git a/skills/worker-protocol/SKILL.md b/skills/worker-protocol/SKILL.md index 4a73b6f..e879158 100644 --- a/skills/worker-protocol/SKILL.md +++ b/skills/worker-protocol/SKILL.md @@ -51,7 +51,7 @@ Before returning your output, run the `qa-checklist` skill against your work. Fi ## Commits -Do not commit until your orchestrator sends `signal: lgtm`. Your output envelope's `signal: rfr` replaces the old freetext `RFR` — the envelope IS the signal. +Do not commit until your orchestrator sends `signal: lgtm`. - `signal: rfr` — you → orchestrator: work complete, ready for review - `signal: lgtm` — orchestrator → you: approved, commit now