| name | handoff-routing |
| description | Pipeline routing rules and handoff conditions between specialist agents: gates, recovery, and the root-applied procedures. Load when coordinating feature delivery, checking pipeline state, or determining which agent to invoke next. The writer side of the log lives in handoff-append. |
| compatibility | ["claude-code","github-copilot","opencode","junie-cli"] |
| metadata | {"version":"2.1","author":"team"} |
Agent Selection
| User Request | Agent | Shortcut Allowed |
|---|
| New feature or enhancement | product-requirements-expert (a root elicitation precedes the dispatch when the intent needs discussion) | No — full pipeline required |
| Discuss or explore feature idea | root — converse per agentic-harness.md § Conversations Stay in Root; dispatch product-requirements-expert to record the outcome | Yes — one recording dispatch after the conversation |
| Requirement clarification | root — same elicitation; product-requirements-expert records the PRD change | Yes — one recording dispatch after the conversation |
| Architecture question | root — same elicitation; system-design-expert records durable-memory changes | Yes — one recording dispatch after the conversation |
| Bug fix (known cause) | feature-implementer | Yes — skip PRD/design |
| Code review request | All reviewers in the roster | Yes — parallel invocation |
Skip agents for: git operations, answering questions, running one-off commands, summarizing an already-completed change. Formal review of a completed change routes to the reviewers in the roster per the table above.
Handoff Conditions
All transitions are gated on the latest record per (req_id, type) in .scratch/handoff.jsonl. The Handoff Conditions table is executable: python3 scripts/handoff.py route evaluates it and prints one JSON decision. The table itself, the gates' field checks, and the recovery steps live in route-spec.md — the normative spec route executes and scripts/tests/test_handoff.py pins rule by rule. No consumer re-derives it: root runs route after each dispatch returns and follows its decision.
Three decisions exist. dispatch names the next agent(s), the matched rule, and the prompt context. A failed gate is a dispatch of the upstream agent carrying the exact errors — the bounce, expressed as the re-dispatch it is. Root assembles each recovery dispatch's prompt from the section its rule maps to: reviewer-stall-retry from § Reviewer Stall Check; build-retry from route-spec.md § Build-Failure Recovery; truncation-continue from route-spec.md § Truncation Recovery, read on demand. blocked always halts for a human: a dirty log, a conflicting verdict, a stalled reviewer, a human-consultation, feature-complete. escalate marks a state the table does not decide; the pipeline-coordinator is dispatched only on escalate and for untriaged fresh-intake classification. Route is fail-closed: it never repairs a log and never guesses past a failed check. A process-findings decision with halt_after: true carries an escalate finding — root halts after that dispatch per § Blocking.
The escalate arm covers the judgment states: no active slice, refactor-first sibling ordering, truncation of an agent with no recovery row, an autofix-only findings round (autofix-only-round), and any state matching no table row. Both refactor-first log shapes escalate; refactor-resume then re-triages the original deterministically. A no-active-slice escalate on a pick the next skill already triaged is pre-resolved: root dispatches product-requirements-expert directly, skipping the coordinator.
Validation Gates
Each transition validates the inbound record(s) against a schema before dispatching the next specialist; malformed or missing records bounce back to the upstream agent without consuming a downstream dispatch. The gates are structural — required fields, types, patterns — and every check catches deterministically. route enforces them; the per-gate field checks are route-spec.md § Validation Gates. Content quality (are the acceptance criteria good?) is the consuming agent's judgement; cross-record consistency beyond req_id linkage is a consumer finding, not a gate check.
Gate 2b routes a consultation-response back to the requesting specialist, never forward (§ Mid-Implementation Consultation). Gate 5 resolves the pass roster from the review-plan the implementer appends at gate-pass. A low/high plan gates on its roster; a gray plan dispatches the review-planner to resolve it; a missing or invalid plan fails closed to the full battery (route-spec.md § Gate 5). Gate 4 then waits on that resolved roster — the four-reviewer floor plus declared extras is the default and the fail-closed fallback, defined in review-workflow § Review Phase. The feature is complete when every pass-roster reviewer is approved and every reviewer dispatched since the latest design-block holds a latest approved (route-spec.md § Gate 5). The change-grader is then dispatched (terminal, advisory; skipped when layout.toml [harness] auto_grade = false). On any changes_requested or blocked, findings split by artifact owner (the review-workflow skill's reference.md § Artifact Ownership) — except doc autofixes, which root applies per § Root-Applied Autofix on Doc Paths. An escalate-tagged finding halts per § Blocking.
Common Procedure
- Discover. Run
Glob .scratch/**/* to enumerate state files. Then Read .scratch/handoff.jsonl only if it appears in the Glob result. Do not Read directories.
- Gate. If
handoff.jsonl is missing or empty when a record is required, the gate fails — route back to the upstream agent.
- Filter. Records by
req_id and type. The latest record for each (req_id, type) is the active state.
- Check. Required fields, types, and pattern constraints per the schema.
- Decide. If every check passes: dispatch the next agent. If any check fails: bounce upstream —
route emits a dispatch of the producing agent carrying the errors; the coordinator names the failed check in a Blocked recommendation.
Blocking
If any gate fails, if a design-block record carries verdict: "conflicting", or if a review-feedback record carries a tag: "escalate" finding, stop the pipeline and resolve before continuing. For an escalate finding, the halt follows the findings-processing dispatch that records the entry in .scratch/escalations.md (Gate 4). On an approved verdict no findings-processing runs — root appends the entry before halting. route enforces the escalate halt twice: process-findings carries halt_after: true, and escalate-finding-halt blocks re-review until a reviewer record follows the human's decision.
Build-Failure Recovery
A failed quality gate (build error, test failure, format/lint failure) ends the implementer dispatch with a build-failure record carrying the error output and retry count. Schema: schemas/scratch/build-failure.schema.json. route executes the recovery deterministically; route-spec.md § Build-Failure Recovery is the normative definition. The shape:
- An
abort_reason short-circuits the retry counter: wrong-shape-slice → product-requirements-expert for re-split; design-mismatch (also a failed autofix audit on a design-doc record) → system-design-expert for re-triage; prd-mismatch (a failed autofix audit on a prd-autofix record) → product-requirements-expert for PRD reconciliation; prerequisite-missing → halt for the human. The record shape and trigger live in tdd-workflow § Wrong-Shape Slice Abort.
- Otherwise
retry < 3 re-dispatches the implementer with the error trail; retry == 3 re-triages via system-design-expert, whose superseding design-block resets the counter. build-failure records count only after the latest design-block; python3 scripts/handoff.py next-retry --req-id <id> implements the rule.
Truncation Recovery
A feature-implementer dispatch that ends without a build-pass or build-failure for the active req_id truncated before the quality gate. Truncation alone does not mean the slice is over-scoped: the Scoping Pre-Check re-scopes a multi-behavior slice before dispatch. A slice that reaches dispatch and then truncates is presumed correctly sized and simply long. The default recovery is to continue the same slice — up to 3 consecutive truncations, then re-triage via system-design-expert (non-convergence). Re-split is reserved for the Pre-Check's over-size branch and for non-convergence — and even there it is one outcome, not the first response. route executes the steps; route-spec.md § Truncation Recovery is the normative definition. It also defines the two partial-record paths (build-failure with partial: true; review-feedback carrying a truncation finding), which route through existing recovery instead.
Dispatch Truncation Detection
Every dispatched project-defined agent except pipeline-coordinator and the terminal change-grader appends a dispatch-start record as its first tool call. Schema: schemas/scratch/dispatch-start.schema.json. Detection is deterministic and reads .scratch/handoff.jsonl alone:
A dispatch-start record for (req_id, author) with no subsequent substantive record from the same (req_id, author) after that dispatch-start's line signals an interrupted dispatch. A pending consultation-request closes the dispatch for detection; it routes as a consultation instead.
Substantive records (closed enum): build-pass, build-failure, review-feedback, review-plan, prd-entry, design-block, consultation-response. Built-in agents not defined under .claude/agents/ (e.g. general-purpose, Explore) are out of scope for this contract; root carries the dispatch-discipline for those per CLAUDE.md § Tool-call budget.
Mid-Implementation Consultation
The feature-implementer may need a focused answer from product-requirements-expert or system-design-expert during TDD cycles when the inner loop discovers a question the triage didn't anticipate. The implementer appends a consultation-request targeting the specialist; route dispatches that specialist in consultation mode (consultation-dispatch); the specialist appends a consultation-response; route returns control to the implementer (consultation-return).
Consultations are substeps, not handoffs. They preserve the implementer's active state — the pipeline advances only when the implementer's own next handoff (build-pass or build-failure) appears.
Consult when another agent owns the answer. When only the human can decide, target the human: a consultation-request with target: "human" halts the pipeline (human-consultation) while root runs the conversation. Root appends the consultation-response (author: "human") and route resumes the requester — the elicitation pause of agentic-harness.md § Conversations Stay in Root. .scratch/escalations.md remains the surface for findings-driven escalations (§ Blocking) and external prerequisites. The test is who can unblock you.
Review Feedback Actions
See the review-workflow skill for feedback tag definitions and the review process. The two root-applied procedures — the reviewer stall check and doc autofixes — live below, because root executes them while routing.
Reviewer Stall Check (root)
route owns the detection and the ladder, deterministically: a reviewer with one silent dispatch-start since build-pass earns a single retry (reviewer-stall-retry); a second silent dispatch returns reviewer-stalled (blocked). Root's part is what a script cannot do. On reviewer-stall-retry, re-dispatch the named reviewer with this prompt: "Your previous run returned without appending a review-feedback record to .scratch/handoff.jsonl. Run the review now. Your only deliverable is that record — see Output Protocol in review-workflow." On reviewer-stalled, append an entry to .scratch/escalations.md naming the reviewer and stop — do not proceed to findings processing. Only root re-dispatches; specialists cannot.
Root-Applied Autofix on Doc Paths
To keep the owning experts' quality bar tight while removing ceremony from mechanical fixes, root may apply tag: "autofix" findings on the owned doc paths directly — without redispatching the owner. Two path classes exist, each with its own audit record and auditing expert:
| Path class | Owner | Record | Owner's audit home |
|---|
docs/system-design.md, docs/adr/*.md | system-design-expert | design-doc-autofix | design-validation § Autofix Audit |
docs/prd.md | product-requirements-expert | prd-autofix | prd-authoring § Autofix Audit |
The quality bar lives in the blocked and clarify paths (with clarify_target naming the owner), which still route to the owning expert. The PRD path exists so a doc-only fix resolves in the current review round: without it, the owner's only substantive record is a prd-entry, which re-enters the pipeline at design triage.
The eligibility rules live in the document-writing skill's stack overlay, review-checks.md — § Autofix on Design-Doc Paths and § Autofix on the PRD Path. Doc-reviewer is responsible for never tagging a finding as autofix on these paths unless every condition there holds (the review-workflow skill's reference.md § Root-Applied Autofix Eligibility). This section defines what root does once such a finding exists.
Apply Procedure
- Validate the finding statically. Confirm:
tag == "autofix"; location falls under an autofix-eligible doc path; fix field is present and is a literal replacement string (not a description). If any check fails, treat the finding as blocked and redispatch the owning expert instead.
- Apply via Edit. Use the Edit tool with the literal
fix string as new_string. Read the file to obtain the exact old_string. Do not paraphrase or "improve" the fix — root acts as a typewriter for the doc-reviewer's verbatim proposal.
- Re-check the bounds after the Edit. Confirm the change stays within the autofix allowlist — the conditions in the matching
review-checks.md section, the same list handoff.py audit-autofix re-validates at gate time. If any check fails, revert (Edit back) and redispatch the owning expert.
- Append the path class's record to
.scratch/handoff.jsonl carrying: the source finding (copied verbatim), the file path, the autofix category (writing-standards or structural), old_content, new_content, lines_changed, chars_changed. Schemas: schemas/scratch/design-doc-autofix.schema.json, schemas/scratch/prd-autofix.schema.json. Append per the handoff-append skill.
- Append-only discipline. Preserve every prior line in
handoff.jsonl verbatim.
Why The Record Matters
- Gate-time re-validation.
python3 scripts/handoff.py audit-autofix (the code-quality-gate skill's autofix audit) mechanically re-checks every design-doc-autofix and prd-autofix record against the allowlist bounds, so a mis-applied autofix fails the quality gate before merge.
- The owning expert audits on next dispatch. The
design-validation skill instructs the system-design-expert to judge all design-doc-autofix records since its last dispatch; the prd-authoring skill instructs the product-requirements-expert to judge all prd-autofix records since its last prd-entry. Each may reject any — the design side via an autofix-rejected finding on the next design-block, the PRD side via a corrective superseding prd-entry.
- Direct-edit detection. The same command fails if
docs/system-design.md or docs/adr/* has uncommitted changes that no design-doc-autofix or design-block record covers — catching any future bypass of the protocol. The scan is design-doc-scoped by decision: docs/prd.md stays outside it (the prd-autofix ADR records why).
What Root Does Not Do
- Root does NOT autofix on any path outside the two classes above — code-path findings route to the implementer regardless of tag.
- Root does NOT autofix any tag other than
autofix (blocked/clarify/escalate route as defined elsewhere).
- Root does NOT batch autofixes across artifacts — one record per finding, one Edit per finding.
State Files
| File | Created By | Consumed By |
|---|
.scratch/handoff.jsonl | product-requirements-expert, system-design-expert, feature-implementer, review-planner, the roster reviewers, change-grader, root (all append-only) | the router — route and, on escalate, the coordinator (validation gates); all consumer agents |
.scratch/implementation-plan.md | feature-implementer | feature-implementer (self-tracking) |
.scratch/escalations.md | feature-implementer (escalate-tag findings, mid-loop escalations); root on the router's blocked decision (prerequisite-missing aborts; reviewer stalls per § Reviewer Stall Check; escalate findings on an approved verdict per § Blocking) — never the coordinator itself | Human |
.scratch/handoff.jsonl is the append-only structured handoff log; one JSON object per line, each carrying a type discriminator. Record types:
Record type | Producer | Purpose |
|---|
prd-entry | product-requirements-expert (system-design-expert: the refactor-first sibling entry) | Active feature scope for system-design-expert and implementer. |
design-block | system-design-expert | Triage verdict and implementation guidance. |
consultation-request | any specialist mid-work | Focused question to another specialist that does not advance the pipeline. |
consultation-response | the consulted specialist | Focused answer; routes control back to the requester. |
review-feedback | each reviewer agent in the roster | Per-reviewer verdict and findings. |
build-failure | feature-implementer | Quality-gate failure with error context and retry counter. |
build-pass | feature-implementer | Quality-gate success marker. |
review-plan | grading.py review-plan (author review-plan-engine); review-planner for the gray zone | Names the reviewer roster and read scope for a review pass; fail-closed to the full battery when absent or invalid. |
design-doc-autofix | root | Audit trail for root-applied autofixes on design-doc paths (see § Root-Applied Autofix on Doc Paths). |
prd-autofix | root | Audit trail for root-applied autofixes on docs/prd.md (same section); keeps a doc-only PRD fix in the current review round. |
dispatch-start | every project-defined agent except pipeline-coordinator and change-grader (as its first tool call) | Half of the dispatch-event contract; "no subsequent substantive record from same (req_id, author)" is the deterministic truncation signal. Not substantive — does not satisfy the implicit stop. |
grader-features | change-grader (grading.py extract) | change-grader (the grading read). Deterministic structural row; advisory, terminal — does not route. |
grader-verdict | change-grader | Advisory facets + rationale + clear/concern verdict; surfaced to the session, recorded, never routed. Not substantive for truncation detection. |
Log Access
The coordinator never writes records — it only reads them for routing decisions. All writes to .scratch/handoff.jsonl go through scripts/handoff.py per the handoff-append skill, which holds the writer contract, the full command table, and the exit codes. Reading the whole log with the Read tool for context is fine; decisions that gate routing use the query subcommands below.
| Operation | Command |
|---|
| Routing decision | python3 scripts/handoff.py route [--req-id <id>] |
| Latest record for a gate | python3 scripts/handoff.py latest --type <type> [--req-id <id>] |
| Next retry counter | python3 scripts/handoff.py next-retry --req-id <id> |
| Whole-file check | python3 scripts/handoff.py validate |
route exits 0 whenever a decision was computed — including blocked and escalate; the decision field carries the state. The human-inspection surface (show, and view via the handoff-board skill) is listed in handoff-append § Writer Commands.
Human Checkpoints
Routing is deterministic: a passed gate names the next agent per the Handoff Conditions table, without waiting for approval. Human attention concentrates at four points — two advisory, two blocking:
- After PRD update (advisory) — Review that the requirement captures intent. The pipeline proceeds; to intervene, halt and route back to product-requirements-expert to append a superseding
prd-entry.
- After design notes (advisory) — Review the architectural approach. Same intervention path, via system-design-expert.
- After escalations (blocking) — The pipeline halts until the human decides each
[ESCALATE] item. A design-block with verdict: "conflicting" halts the same way (Handoff Conditions table).
- After feature complete (blocking) — The change-grader's verdict is advisory; only the human approves the merge.
Coordinator Output Format
The coordinator handles what route cannot: untriaged fresh-intake classification and every escalate decision; a next-triaged pick dispatches product-requirements-expert directly. Its recommendation follows the same table; route's JSON is the deterministic fast-path for the rows the table decides alone.
The pipeline coordinator responds with a structured recommendation:
## Pipeline State
[Current state based on .scratch/ files]
## Recommendation
**Action:** Invoke [agent-name]
**Prompt:** "[suggested prompt for the agent]"
**Shortcut:** Yes/No
**Reason:** [why this agent is next]
If blocked:
## Pipeline State
[Current state]
## Blocked
**Blocker:** [description]
**Resolution:** [what needs to happen]
Coordinator Rules
These rules bind the coordinator when it is dispatched — fresh intake and escalate states. On the routine path route applies the same table.
- Never skip pipeline stages for new features.
- Shortcuts are allowed only per the agent selection table above.
- If
.scratch/ contains stale state from a previous feature, recommend clearing it first.
- Report all
design-block records with verdict: "conflicting" and all review-feedback findings tagged escalate.
- Recovery ladders are
route's, never yours: build-failure retries (route-spec.md § Build-Failure Recovery) and implementer truncation (§ Truncation Recovery) are decided deterministically. What reaches your escalate arm is their degenerate states — abort-unknown, failure-without-design, truncation-before-design, and a truncated agent with no recovery row. Decide those; never re-decide a ladder rung.
- After every reviewer dispatched since the latest
design-block holds a latest "approved" verdict (route-spec.md § Gate 5), the feature is complete: recommend dispatching the change-grader agent (terminal, advisory). With layout.toml [harness] auto_grade = false, skip that recommendation — route reports feature-complete directly. The grader assesses how much human attention the passing change deserves; its clear/concern verdict is recorded and surfaced to the session, but it does not route and is not a merge or correctness gate. Do not consume its verdict for any routing decision.
