Dispatching Parallel Agents

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.