dispatching-parallel-agents
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.
What it does
Section titled “What it does”This is the shared fan-out mechanism other parts of the system dispatch through whenever work splits across independent units, each handled by its own agent — used inside the implementation engine, an autonomous sprint, and a parallel code review. It owns the mechanics of dispatching safely, not the judgment about what the units are: bound the concurrency, isolate each unit’s scope, collect every result even when one errors, remove duplicate findings, and only then let the results reach whoever asked for the work.
Phases
Section titled “Phases”- Partition the work into units with disjoint file paths, routing any unavoidable overlap through worktree isolation or serialization.
- Dispatch one agent per unit in bounded waves, each agent seeing only its own unit’s scope.
- Collect every unit’s terminal state — completed, errored, or halted — without letting one failure discard the rest of the batch.
- Merge duplicate findings, surface contradictions instead of silently picking one, and verify any completion claim with a fresh proving run rather than trusting a self-report.
- Route the deduped results through severity triage and then aggregation, and hand the caller only the resulting verdict.
The caller receives one aggregated verdict — a pass, or a list of blocking findings — never the raw agent output. Every dispatched unit terminates with a recorded state, so nothing dispatched ever silently disappears from the batch.
| Gate | When | Effect |
|---|---|---|
| partition | before any agent is dispatched | two units that would mutate the same file cannot share a batch — the collision is isolated or serialized first |
| funnel | after results are deduped | the caller only ever sees the aggregated verdict from triage plus aggregation; raw or merely-deduped agent output never reaches it directly |
Related
Section titled “Related”Source
Section titled “Source”Source — plugins/ca/skills/dispatching-parallel-agents/SKILL.md (v2.9.1)
---name: dispatching-parallel-agentsdescription: 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.
1. 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.2. 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.