dispatching-parallel-agents（调度并行 Agent）

Dispatching Parallel Agents

Effective orchestration means knowing when to do work yourself and when to delegate it to focused subagents working in parallel. The core insight is simple: independent work should happen concurrently, not sequentially. But "independent" is the load-bearing word -- getting decomposition wrong turns parallel execution into a coordination nightmare.

Core Principles

When to Parallelize

When NOT to Parallelize

The Dispatch Cycle

Phase 1: Identify Independent Work

Examine the task and list every subtask. For each pair, ask: "Can subtask A complete without knowing the result of subtask B?" If yes for all pairs in a group, that group is parallelizable.

Actions: Break the task into candidate subtasks. Draw dependency arrows between them. Groups with no inbound arrows from other groups are independent.

Output: A dependency map showing which subtasks are independent and which form pipelines.

Phase 2: Decompose into Dispatch Units

Each dispatch unit is one subagent's complete assignment. A dispatch unit has a single objective, a bounded scope, and a defined output format. If a unit requires the agent to make judgment calls about scope, it is too vague.

Actions: For each independent group, define the dispatch unit. Choose the right decomposition pattern (see Decomposition Patterns).

Output: A list of dispatch units, each with objective, scope boundary, and expected output.

Phase 3: Brief Each Agent

Write a precise brief for each subagent. The brief is the contract between orchestrator and worker. See Briefing Template for the full format.

Minimum brief contents:

• Task objective (one sentence)
• Input data or file paths
• Expected output format
• Explicit out-of-scope boundaries
• Failure handling instructions

Phase 4: Execute with Isolation

Launch subagents with clean context. Agents that modify files operate in isolated worktrees. Read-only agents can share the working tree safely.

Actions: Dispatch all units. Do not provide agents with your conversation history or context beyond their brief. See Isolation and Merging.

Output: Running subagents, each working independently.

Phase 5: Synthesize Results

When all agents return, the orchestrator integrates their outputs into a coherent result. This is active work, not passive collection.

Actions: Review each output against its brief. Deduplicate overlapping findings. Resolve contradictions. Identify gaps where agents hit blockers. Produce the unified deliverable.

Output: Integrated result that is more than the sum of its parts.

Phase 6: Handle Failures

Some agents will fail, hit blockers, or return incomplete results. Plan for this.

Actions: For each failed unit, decide: retry with a revised brief, reassign to a different agent type, absorb the work yourself, or accept the gap and document it.

Output: Complete result with any gaps documented and justified.

Decomposition Patterns

See Decomposition Patterns Reference for detailed descriptions, decision criteria, and examples using this project's agent roster.

Briefing a Subagent

A brief is not a wish list. It is a contract that constrains the agent's behavior. Good briefs produce predictable results; bad briefs produce creative surprises.

What a good brief contains:

• Task: One-sentence objective. What must be true when the agent finishes?
• Context: Relevant background -- just enough to understand the task, no more
• Inputs: File paths, data, references the agent needs to start working
• Expected output: The exact structure and format of the result
• Boundaries: What is explicitly out of scope. What the agent must NOT do.
• Failure mode: What to do when stuck -- report back, skip, or attempt a fallback

What a good brief does NOT contain:

• The orchestrator's full conversation history
• Unrelated context from other subagents
• Ambiguous scope ("look into this area and see what you find")
• Multiple unrelated objectives

See Briefing Template Reference for a complete template with examples.

Isolation Strategies

Rule: If two agents might touch the same file, they must be in separate worktrees or run sequentially. There is no safe middle ground.

See Isolation and Merging Reference for worktree setup, result synthesis, and conflict resolution strategies.

Anti-Patterns

See Anti-Patterns Reference for detailed descriptions and recovery strategies.

Practical Dispatch Patterns

These patterns map directly to the agent chaining flows defined in this project's agent roster:

Investigation Fan-Out

Orchestrator -> [Investigator(auth), Investigator(billing), Investigator(notifications)]
            <- Merged findings
            -> Architect (design based on merged findings)

Dispatch multiple investigators in parallel when the task requires understanding several independent subsystems. Each gets a focused scope. The orchestrator merges findings before handing them to the architect.

Feature Build with Parallel Implementation

Product Manager -> Architect -> [Backend Dev(API), Frontend Dev(UI), Implementer(migration)]
                             <- Integrated feature
                             -> QA Engineer

After requirements and design are sequential, implementation fans out to specialists working in isolated worktrees on non-overlapping file sets.

Multi-Dimensional Review

Orchestrator -> [Reviewer(correctness), Refactor Scout(smells), Test Gap Analyzer(coverage)]
            <- Consolidated review report

Three specialists examine the same code from different angles simultaneously. Read-only agents sharing the working tree. The orchestrator consolidates findings by severity.

Coverage Improvement Scatter

Orchestrator -> [Test Gap Analyzer(module-a), Test Gap Analyzer(module-b), Test Gap Analyzer(module-c)]
            <- Prioritized gap list
            -> [Implementer(module-a-tests), Implementer(module-b-tests)]

Fan-out analysis, then fan-out implementation -- two rounds of parallel dispatch.

Quality Checklist

Before dispatching subagents:

• Each dispatch unit has a single, clear objective
• No two agents modify overlapping files
• Every brief includes explicit out-of-scope boundaries
• Expected output format is defined for each agent
• Failure mode is specified (report, skip, or fallback)
• File-modifying agents are assigned isolated worktrees
• Read-only agents have no write tools in their brief
• The synthesis plan is defined before dispatch (how will you merge results?)
• Dependencies between units are zero (or they are sequenced, not parallelized)
• The number of agents is justified (3-5 is typical; more needs strong rationale)

Critical Rules

1. Independence is a precondition, not an optimization. If tasks share mutable state, they cannot run in parallel. Period.
2. The brief is the contract. Everything a subagent needs must be in the brief. If it is not in the brief, the agent does not know about it.
3. Clean context only. Never leak your conversation history, other agents' results, or ambient project context into a subagent's session.
4. File ownership is exclusive. Two agents must never modify the same file in the same dispatch round. Worktree isolation prevents accidents but does not prevent merge conflicts.
5. Plan the synthesis before the dispatch. If you cannot describe how outputs will be merged, you are not ready to parallelize.
6. Failure is expected. Budget for one agent failing. Define what "good enough" looks like with partial results.
7. Fewer, focused agents beat many scattered ones. Three well-briefed agents outperform seven vaguely-scoped ones.
8. Investigate before parallelizing. The first dispatch is usually a single investigator. Parallel execution comes after the problem space is mapped.
9. The orchestrator synthesizes, not concatenates. Pasting outputs together is not integration. Resolve conflicts, deduplicate, and produce a coherent whole.
10. Match agent type to task type. Use investigators for exploration, implementers for coding, reviewers for quality checks. Do not ask an investigator to write code or a reviewer to investigate.

Reference Files

Integration with Other Skills