Subagent Orchestration

subagent-orchestration

When to use

• A task benefits from a second agent reviewing before apply — safety, regression risk, cross-layer change
• A plan has clear, independent slices that can be worked on in parallel — unrelated bug fixes, multi-file migrations
• A solution space is broad enough that multiple candidate implementations are worth producing and comparing
• The user explicitly asks "have a second agent review this" or "try this two different ways"

Do NOT use when:

• The task is small and the overhead of a second agent exceeds the value — single file, one-liner fix
• The user is still exploring — route to brainstorming / planning skills first
• Budget is the constraint — each subagent call multiplies cost; non-interactive bulk cohorts → batch/caching via the token-optimizer index branch
• The implementer and judge would be the same model on the same context — no added signal

Goal

Land a verified change (or set of changes) by combining implementer and judge subagents in a mode chosen deliberately, with model pairing read from .agent-settings.yml — never silently improvised.

The Iron Law

NO JUDGE ON THE SAME MODEL AS THE IMPLEMENTER ON THE SAME CONTEXT.

Same model + same context = same blind spots. The whole point of a judge is a fresh pair of eyes. If .agent-settings.yml resolves to identical implementer and judge models, surface the mismatch before running — do not silently continue.

RDP: parallel async dispatch by default

Within the Reasoning Discipline Protocol, dispatch independent subtasks to parallel subagents by default and keep working while they run (async), rather than blocking on each return — intervene only if one goes off track. Engage per rdp-gate.

Always-on auto-dispatch

"By default" is governed by the delegation-policy rule — the single source of the auto-trigger. It gates on the activation context (auto-orchestration-activation): dispatch only when emergency.orchestration_halt is not set, the host manifest reports subagent_spawn: true, and the task is classified delegable. A matched signal → dispatch, surfacing mode + per-subtask tiers in one line; an ambiguous verdict → ask, always; any gate failing → in-session no-op. There is no more per-layer on/off setting (always-on orchestration). Never lifts a safety floor.

Worker-prompt contract

Every dispatched worker prompt obeys five rules that prevent the two classic handoff failures (lossy re-summarization dropping the user's requirements; over-scripted prompts that break on first contingency): (a) user constraints verbatim, (b) describe the goal — don't script the approach, (c) translate environment paths into the worker's sandbox, (d) pre-declare check-in conditions, (e) attach relevant knowledge read-only (auto-surface, never auto-write — ADR-098 floor). The five rules verbatim: subagent-spawn-contract § Worker-prompt rules.

When to delegate at all is delegation-policy; the spawn boundary is the subagent-spawn-contract.

Hand-off worked examples

Ordered / fan-out hand-offs embed each step's return verbatim in the next prompt and state what to do with it (never "continue from before" — the lossy re-summarization failure). Two worked shapes: subagent-spawn-contract § Hand-off worked examples.

Form gate — deterministic, BEFORE mode selection

With auto-dispatch on by default (ADR-117), mode selection happens without a human in the loop — so the FORM is decided by a static table first, and only then is the specific mode picked inside that form. Static table only: no learned routing, no self-modifying selector (rejected, stays rejected).

Rules:

• The gate consumes the SAME structural signals as auto_dispatch.ts::classifyTask (slice count, dependency declarations, size floor) — it never re-interprets the task text on vibes.
• Ambiguous shape → none (in-session), never a speculative spawn — the delegation-policy default.
• Fork vs. named subagent — an ordering, never a default (road-to-cache-economy Phase 4). On a host that offers a fork primitive, decide fork-vs-named ORTHOGONALLY to the form picked above: tool and scope fit is first-order, cache inheritance is second-order. A fork is preferred only when the child continues the parent's task under identical tools and constraints (it then reads the parent's cache on its first request); a named subagent is preferred the moment isolation, a different tool set, or nested dispatch is needed — a fork cannot nest, and forking forces background mode, which changes the tool set and invalidates the very prefix that motivated the fork. do-in-parallel-shaped fan-out from one parent has this shape by construction (a known, unfixable upstream cost — see prompts/README.md § Prompt-cache discipline). NEVER encode "always fork" — that was proposed and cut (council 2026-07-30): the cache-sharing benefit cannot be predicted before the fork happens.
• Record the outcome in the telemetry line (dispatch_mode field, mode id or none) so the gate's value is measurable inside the ADR-117 prove-or-drop window.

Severity-conditioned team composition — conditions pattern

Incident-style severity tiers (Critical / High / Medium / Low) refine composition and activation within the form the static gate already picked — severity never overrides the form gate, the Iron Law, or any safety floor. Guidance, not a new object class (persona-catalog disposition). Severity→composition table + escalation rule → subagent-modes-detail § Severity-conditioned team composition.

The nine modes

Each mode has a decision row: when to use, when not, and the expected model pairing. Defaults come from subagent-configuration.

Topology hints — per-mode communication shape

Descriptive lookup material (per-mode topology table, anti-drift default, glossary) lives in subagent-topologies — pull it for capacity planning; it is metadata, not runtime-enforced.

Per-mode decision rows (when to use / when not / model pairing) and the mode-2 stage-routing contract live in subagent-modes-detail § Modes 1–6 — pull them at dispatch time.

1. do-and-judge

Implementer produces a diff; judge reviews; loop applies, revises, or hands off. Hard ceiling: two revision cycles, then stop and hand back to the user.

2. do-and-judge-two-stage

Implementer produces a diff; two judges run sequentially — spec compliance first, code quality second. Stage-one BLOCKED shortcuts the loop (no point quality-reviewing a diff that misses the spec). Stage routing + why-two-stages rationale → modes-detail § Mode 2.

3. do-in-steps

Plan is split into N steps; judge runs between steps. A step that fails judgment is revised before the next step starts. Used for multi-file changes where a mid-plan mistake would cascade.

4. do-in-parallel

Independent slices run concurrently. No judge per slice — judge runs once on the aggregated result. Parallelism capped by subagents.max_parallel in .agent-settings.yml.

5. do-competitively

Multiple implementers produce candidate diffs for the same slice. Judge picks the winner and rejects the losers. Expensive — use only when the solution space is genuinely broad.

6. judge-with-debate

Two judges each produce a verdict; a meta-judge reconciles disagreements. Used for high-stakes changes (security, data migration, public API) where a single judge is too easy to fool.

Mode 6 = go/no-go (strict-er verdict wins); for defect-FINDING coverage (the union of what diverse models catch) use Mode 9.

7. do-in-worktrees

Cross-wing or cross-skill chain executed across isolated git worktrees — each handoff runs in its own worktree so one step's workspace state never leaks into the next. Use for a multi-step cross-wing chain (≥2 senior skills, each ≥30 min); not for fast iteration under 30 min (overhead dominates). Full handoff shape, example chain, competitive per-candidate isolation, and the no-auto-merge Hard Floor → subagent-modes-detail § Mode 7.

8. do-with-live-app-judge (gated — UI-heavy tasks)

Implementer ships the change AND starts the dev server; the judge drives the RUNNING app (Playwright / browser) against a written rubric, never reading the diff. Use for UI-heavy change where "looks right in the diff" ≠ "works in the app"; not for backend/logic (a diff judge is cheaper). Experimental until verdict_changed_outcome telemetry proves it. Rubric, adoption gate, and the async-verifier future candidate → subagent-modes-detail § Mode 8.

9. adversarial-verification-council (gated — opt-in, advisory)

A panel of N (default 2) distinct-model skeptics red-teams a real, already-verified change through the judge-* lenses — each prompted to break it. Returns reconcile deterministically (_lib/adversarial_reconcile.ts) into one findings-by-severity envelope with provenance + cross-model confidence (schemas/adversarial-findings.json). Unlike Mode 6 it emits a findings-union, not a go/no-go verdict. Advisory only — never auto-gates (Hard Floor). Default-off (subagents.adversarial_council); opt-in high-risk changes only; registered claim + high-risk tier need cross-vendor skeptics. Invariants, skeptic prompt, reconciliation, prove-or-drop gate → subagent-modes-detail § Mode 9

• prompts/adversarial-verification-council.md

Disposition (2026-07-28, honest null). The adversarial-council finding- coverage benchmark resolved as a published null (see docs/benchmark.md) — this mode is NOT sold as a defect-detection capability. It stays default-off bound to that null; scheduled for removal at the next major unless external evidence (a consumer-filed case where the panel surfaced a real defect the single verifier missed) appears first. Its remaining honest value is perspective diversity + decision documentation, nothing more. (ADR-122).

Status taxonomy — every subagent return uses one envelope

Every implementer or judge return must conform to schemas/subagent-status.json. Exactly four statuses — DONE · DONE_WITH_CONCERNS · NEEDS_CONTEXT · BLOCKED — no free-form alternatives; orchestrators route on status mechanically. Meaning/required-keys table, why-fixed rationale, and the NEEDS_CONTEXT-vs-BLOCKED distinction → subagent-modes-detail § Status taxonomy.

The envelope is the ONLY return channel (token-economy-dispatch Phase 6). A worker writes its full output to disk (runtime artifact dir, gitignored) and returns the bounded envelope — summary + artifact_paths + verdict, size caps validator-enforced (_lib/subagent_response.ts: summary ≤ 2,000 chars, whole envelope ≤ 12,000). The orchestrator reads FROM the artifact paths on demand — never instructs a worker to paste its full result into the return, and never ingests a transcript-shaped return wholesale: dispatching N workers grows the orchestrator context by N envelopes, not N transcripts.

Dispatch prompts — externalized

Each mode's literal dispatch template lives under prompts/{mode}.md. The orchestrator loads the matching prompt at dispatch time and substitutes {{placeholders}}. Edits to a prompt do not bloat this skill against the 400-line sunset trigger. Eight prompt files cover modes 1–7 and 9 (the standalone judge reuses prompts/do-and-judge.md; mode 8's live-app rubric lives in subagent-modes-detail § Mode 8); each prompt cites all four taxonomy statuses — see prompts/README.md.

Procedure

1. Inspect the task shape

Before picking a mode, check:

• Is the task single-change or multi-step?
• Are slices truly independent, or do they share state?
• Is solution space narrow (one right answer) or broad (trade-offs)?
• Is risk high enough to justify debate?

Do not pick a mode until these four questions have concrete answers.

2. Resolve models

Read .agent-settings.yml:

• subagents.implementer_model → empty = session model
• subagents.judge_model → empty = one tier above implementer
• subagents.max_parallel → integer, default 3

If resolution produces an unknown alias or implementer == judge in the same context, stop and report. Do not improvise.

3. Pick the mode

Run the form gate first, then match task shape to one of the nine modes. When two modes could fit, prefer the cheaper one (do-and-judge < do-and-judge-two-stage < do-in-steps < do-in-parallel < do-competitively < judge-with-debate < do-in-worktrees).

Mode 6 (do-in-worktrees) is instruction-only (ADR-229). There is no setting to resolve — worktrees.mode was deleted:

Because mode 6 is unreachable unprompted, it is effectively off the cheapness ladder above unless the user named it; read that ordering as covering modes 1–8 in the default case.

4. Dispatch

Use the matching dispatch prompt and orchestrate inline via this skill. Describe each dispatch step explicitly in chat so the user can follow it.

• do-and-judge → prompts/do-and-judge.md
• do-and-judge-two-stage → prompts/do-and-judge-two-stage.md
• do-in-steps → prompts/do-in-steps.md
• do-in-parallel → prompts/do-in-parallel.md
• do-competitively → prompts/do-competitively.md
• judge-with-debate → prompts/judge-with-debate.md
• do-in-worktrees → prompts/do-in-worktrees.md
• adversarial-verification-council → prompts/adversarial-verification-council.md
• Standalone judge → judge prompt in prompts/do-and-judge.md

5. Report

Follow the output format below. Never merge a diff without reporting the judge verdict.

6. Emit telemetry

After every auto-dispatched run, write one audit-log-v1 line (input_kind: "orchestration") via the orchestration_record recorder — never hand-author the JSON. Line shape, field semantics, recorder invocation, and token_delta sourcing priority → orchestration-telemetry § Emit procedure. Skip emit when emergency.orchestration_halt is set or spawn_count == 0 (in-session run).

Gotcha

• Identical model both sides — same blind spots. The Iron Law blocks this before dispatch.
• Judge drifts off-task — judge reviews the diff, not the task description. Always attach the diff to the judge prompt.
• Infinite revision loop — hard ceiling of two revisions in do-and-judge; then hand back to the user.
• do-in-parallel on overlapping slices — race conditions, conflicting diffs. Verify independence before splitting.
• Cost surprise on do-competitively — N implementers + 1 judge = N+1 subagent calls for one slice. Confirm budget before dispatch.

Output format

1. Mode chosen — one of the nine, with the one-line reason
2. Model pairing — implementer model / judge model (resolved)
3. Verdict — applied / revised / handed back
4. Evidence — diff summary, test output, or judge transcript
5. Next step — what the user does now (review PR, pick winner, etc.)

Do NOT

• NEVER run implementer and judge on the same model and same context
• NEVER exceed the two-revision ceiling in do-and-judge without user consent
• NEVER run do-in-parallel on slices that touch shared files
• NEVER apply a diff that the judge rejected without explicit user override
• NEVER silently resolve an unknown model alias to a fallback

Handover