Multi Agent Orchestration

Multi-Agent Orchestration

Execute work through subagents instead of a single context. Two modes: parallel dispatch (independent tasks to concurrent isolated-context agents) and plan-driven execution (a plan as a sequence of implementer-subagents, each reviewed before the next). Use when the work exceeds one context window, or when isolation prevents cross-task contamination.

When to use

• A plan/ticket set is too large for one session — drive it as sequenced implementer-subagents
• 2+ independent tasks that don't share state — dispatch them concurrently to isolated contexts
• A task needs a fresh context to avoid prior-session bias or context bloat
• Reviewing one task's output before starting the next (plan-driven checkpoint)
• Triggers on "parallel agents", "subagent execution", "dispatch tasks", "fan out", "并行 agent", "子代理执行", "派发任务"

Not for: breaking a plan into tickets (use breakdown — this skill executes the tickets, it doesn't decompose them); doing the implementation yourself in one context (use implement); single-task work that fits one session (just do it — orchestration has overhead).

Steps

1. Decide: parallel dispatch or plan-driven execution?

• Parallel dispatch — the tasks are independent (no data dependency between them). Run them concurrently. Use when: lint-fixing N files, researching N competitors, generating N independent components.
• Plan-driven execution — the tasks have an order (each informs or gates the next). Run them sequentially with review between. Use when: a feature spans schema → API → UI → tests, or when task N's output must be verified before task N+1 starts.

If tasks are independent but few (2-3) and each is small, don't orchestrate — do them inline. Orchestration earns its overhead only when isolation or scale matters.

2. Construct the context for each subagent

A subagent has no access to your conversation — its context is only what you put in its prompt. Construct it deliberately:

• Goal — what the subagent must produce (a verifiable outcome, not "work on X").
• Inputs — the files, specs, decisions, and constraints it needs. Quote the relevant spec section; don't say "see the PRD" (it can't).
• Boundaries — what's in scope, what's out, what to ask about vs. decide autonomously.
• Verify target — the exact check that defines done (tests pass, file exists with N sections, output matches schema).
• Isolation note — tell it not to assume state from any prior session; its prompt is its entire world.

3. Dispatch (parallel) or sequence (plan-driven)

• Parallel — launch all subagents in one message (multiple Agent tool calls). Wait for all; collect results. Don't start the next phase until all return, unless a slow one unblocks others.
• Plan-driven — launch one implementer-subagent for task 1. When it returns, review its output (read the result, run its verify check, confirm it's correct) before launching task 2's implementer. The review is the checkpoint — never auto-advance to the next task without verifying the prior.

4. Review each subagent's output

For every subagent result, before consuming it:

• Did it meet the verify target from its prompt? (Run the check; don't trust the claim.)
• Did it stay in scope, or invent work outside the boundaries?
• Is the output consistent with what downstream tasks expect?
• If it failed or drifted — either re-dispatch with a corrected prompt, or fix inline if the gap is small. Don't build on a broken foundation.

5. Synthesize and verify the whole

After all subagents complete (parallel) or the plan finishes (plan-driven):

• Does the integrated result meet the original goal? Run the end-to-end verify, not just each piece.
• Are there seams between subagent outputs — inconsistencies in naming, style, assumptions? Reconcile them; isolated contexts produce isolated assumptions.
• State what was done by subagents vs. inline, so the trace is auditable.

Verify

• Each subagent had a constructed context (goal + inputs + boundaries + verify target) — not a vague "do X"
• Parallel tasks were genuinely independent (no hidden data dependency that serialized them)
• Plan-driven tasks were reviewed before advancing — no auto-advance past an unverified step
• Each subagent's output met its verify target (checked, not claimed)
• The integrated whole meets the original goal (end-to-end verify, not just per-piece)
• Seams between subagent outputs reconciled (naming, style, assumptions)

Red flags: dispatching tasks that share state as if independent (race condition); auto-advancing a plan-driven sequence without reviewing the prior step; a subagent prompt that says "see the conversation" or "you know what to do" (it doesn't — its context is only its prompt); skipping the end-to-end verify because each piece "passed"; treating subagent output as trusted without checking.

References

• ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — shared discipline (surface assumptions, verify don't assume, goal-driven execution, surgical scope).
• references/dispatch-patterns.md — when to fan out vs sequence, context-construction templates, review-checkpoint patterns, common failure modes (race conditions, context-starved subagents, unverified seams).