name: dispatching-parallel-agents
description: The parallel fan-out primitive. Routed to by any skill or command that splits work across independent units and dispatches an agent per unit — subagent-driven-development, /sprint, parallel /review. It owns the dispatch/collect/funnel discipline: bound concurrency, isolate units, collect every result, dedupe overlap, and funnel through finding-triage then checkpoint-aggregator. Raw agent output is never consumed before the funnel runs; an agent that errors drops its unit without corrupting the batch.
dispatching-parallel-agents
Fan out, collect everything, funnel before consuming. Plumbing other skills dispatch through — it owns the parallel discipline, not domain logic.
Pre-flight
The caller supplies the work. Confirm it, or STOP and surface the gap — never invent units or pick an agent on a hunch:
- The unit list — N discrete, independently-completable units of work, each with its scope and target paths.
- The agent kind — which agent kind to dispatch per unit (e.g.
backend-author, frontend-author, scout, security-reviewer at ${CLAUDE_PLUGIN_ROOT}/agents/<name>.md). One kind per batch.
- The completion contract — what each agent must return: a structured result, its unit ID, and a pass/fail/error status. Self-reports are claims, not evidence (see Phase 4).
Phase 1 — Partition · gate: BLOCK
Split the work into units that do not collide. A unit owns a distinct file or path set; two units in one batch MUST NOT mutate the same path.
- Independent paths — units touch disjoint files. Dispatch directly. This is the common, fast case.
- Shared paths unavoidable — units must mutate the same file or tree. Do NOT dispatch into the conflict. Route to
using-git-worktrees to give each unit an isolated working tree, or serialize the colliding units into one sequential unit. A shared-path collision in a parallel batch is a corruption, not a merge.
Tag each unit with its ID, scope, target paths, and the agent kind. Read-only batches (review, scout) skip the collision check — they mutate nothing.
Gate: every unit has a disjoint path set, or its overlap is resolved by worktree isolation or serialization. An unresolved collision does not pass.
Phase 2 — Dispatch · gate: BLOCK
Dispatch one agent per unit, bounded.
- Concurrency bound — dispatch in waves of at most a fixed width (default 4 concurrent agents; the caller MAY override). Do not fan out unbounded; a hundred agents at once starves the batch and corrupts nothing useful.
- Fresh and isolated — each agent gets only its own unit's scope and the completion contract. No agent sees another's working state. No shared mutable context between units in flight.
- Hard-stop propagation — a
tdd BLOCK, a commit-gate failure, a security CRITICAL, or a [CONFIRM-NN] inside any unit halts that unit and surfaces immediately; it does not get silently swallowed by the batch.
Gate: every unit is dispatched or explicitly deferred. No unit is dropped silently at dispatch.
Phase 3 — Collect · gate: BLOCK
Wait for the full wave, then the next, until every unit has terminated. Record each unit's terminal state: DONE (returned a result), ERRORED (the agent failed), or DEFERRED (a hard-stop surfaced).
An ERRORED unit drops its own work — its partial output is discarded, never half-applied — and is logged against its unit ID. One errored unit MUST NOT corrupt or discard the batch. The remaining units' results stand. Record the error for the funnel; do not retry blindly inside this phase.
Gate: every unit has a terminal state and DONE results are captured intact. A still-running or unaccounted unit blocks Phase 4 — partial collection does not pass.
Phase 4 — Dedupe · gate: BLOCK
Parallel agents over adjacent units produce overlapping findings — the same issue reported by two units, the same fix proposed twice. Collapse them before anything downstream sees the batch.
- Merge findings that name the same defect at the same location into one, keeping the highest severity reported.
- Reconcile contradictory results across units (two units that disagree on the same fact) into a single surfaced conflict, not a silent pick.
- Verify any "done" claim that gates real work: re-run the proving command fresh and read its output and exit code. A subagent's self-report is a claim — never trust it as evidence of completion.
Gate: the result set is deduped, contradictions surfaced, and completion claims verified by fresh evidence. Raw, un-deduped agent output MUST NOT reach Phase 5.
Phase 5 — Funnel · gate: STOP
The batch is consumed only here, through the fixed funnel — never directly by the caller.
- Dispatch
finding-triage (${CLAUDE_PLUGIN_ROOT}/agents/finding-triage.md) over the deduped result set: it classifies severity, marks out-of-scope items with an inline [NEEDS-TRIAGE] marker, and discards noise.
- Hand the triaged set to
checkpoint-aggregator (${CLAUDE_PLUGIN_ROOT}/agents/checkpoint-aggregator.md): it aggregates into the single batch verdict the caller consumes — pass, or a blocking finding list.
The errored and deferred units from Phase 3 ride through the funnel as findings — an ERRORED unit is a finding the caller must see, not a silent gap.
Gate: the caller receives only the aggregated verdict. Bypassing the funnel — consuming raw or merely-deduped agent output — is a gate violation. STOP and return the verdict.
Hard rules
- MUST NOT dispatch two units that mutate the same path in one batch; isolate via
using-git-worktrees or serialize.
- MUST NOT fan out unbounded; dispatch within the concurrency bound.
- MUST NOT let one
ERRORED unit discard or corrupt the rest of the batch.
- MUST NOT consume agent output before the
finding-triage → checkpoint-aggregator funnel runs.
- MUST NOT trust a subagent's self-reported completion; verify with a fresh proving command.
- MUST NOT silently drop a unit — every unit terminates with a recorded state that rides through the funnel.
