Dispatching parallel agents

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

Principle	Meaning
Independence over coordination	If two tasks share state, they are one task. Only dispatch work that can complete without cross-agent communication.
Precision over hope	A subagent brief must be specific enough that the agent cannot misinterpret its scope. Vague briefs produce vague results.
Isolation over sharing	Each subagent starts with a clean context. It receives exactly what it needs - nothing inherited, nothing ambient.
Synthesis over concatenation	The orchestrator's job is not to paste outputs together. It is to resolve conflicts, deduplicate, and produce a coherent whole.
Fail fast over fail silent	Every dispatch includes a failure mode. Subagents report blockers immediately rather than guessing past them.

---

When to Parallelize

Signal	Example
Multiple independent areas of investigation	"How does auth work?" + "How does billing work?" - no shared code path
Research spanning distinct topics	Investigating a framework upgrade requires checking breaking changes, dependency compatibility, and test coverage separately
Implementation across non-overlapping files	Backend API + frontend component + database migration touching different file sets
Review of independent subsystems	Running a reviewer on module A while running a refactor scout on module B
Repetitive tasks with different inputs	Auditing 5 services for security vulnerabilities - same process, different targets

When NOT to Parallelize

Signal	Why Sequential Is Better
Output of task A is input to task B	Pipeline dependency - parallelize within stages, not across them
Tasks modify overlapping files	Merge conflicts are inevitable and expensive to resolve
Understanding requires full context	Splitting a single complex investigation loses the thread
The problem is not yet understood	Parallelize execution, not exploration of unknowns
Fewer than 3 independent units	Dispatch overhead exceeds time saved
Results must be strictly ordered	Sequential execution preserves natural ordering without post-processing

---

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

Pattern	Shape	Best For
Fan-out / Fan-in	One orchestrator dispatches N workers, collects all results	Independent tasks with a single synthesis step
Pipeline	A feeds B feeds C - sequential stages, parallel within each stage	Work with clear phase dependencies
Scatter-gather	Same question to multiple specialists, best/merged answer wins	Getting diverse perspectives on the same problem
Specialist-per-concern	Each agent owns one domain (security, performance, correctness)	Multi-dimensional review or analysis
Map-reduce	Split input into chunks, process in parallel, merge results	Large-scale repetitive operations

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

Strategy	When to Use	Trade-off
Context isolation	Always. Every subagent starts clean.	Requires explicit context transfer in the brief
Filesystem isolation (worktree)	When agents modify files	Branch management overhead, merge step required
Read-only shared tree	When agents only read (investigation, review, analysis)	No merge needed, but agents must not write
Context + filesystem	When agents modify files AND need independence from each other	Maximum isolation, maximum merge complexity

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

Anti-Pattern	Symptom	Fix
Dependency masquerading as independence	Agent B blocks waiting for Agent A's output	Reorder as pipeline or merge into one unit
Overlapping writes	Merge conflicts after agents return	Enforce file-level ownership per agent
Context bleed	Agent inherits irrelevant history, gets confused	Start every agent with a clean brief, no inherited context
Ambiguous brief	Agent interprets scope differently than intended	Add explicit boundaries and out-of-scope list
Agent sprawl	8+ agents dispatched for a task that needs 3	Combine related work into fewer, focused units
Duplicate research	Two agents investigate the same files	Define non-overlapping investigation scopes
No failure budget	One agent failure stalls the entire workflow	Define fallback per agent; accept partial results
Premature parallelization	Splitting before understanding the problem	Investigate first, parallelize the known work

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

Reference	Contents
Decomposition Patterns	Fan-out/fan-in, pipeline, scatter-gather, specialist-per-concern, map-reduce - decision criteria, examples with project agents
Briefing Template	Complete subagent brief template, good vs bad brief examples, output format specification
Isolation and Merging	Context isolation, worktree isolation, result synthesis, conflict resolution, merge strategies
Anti-Patterns	Detailed anti-pattern descriptions, detection signals, recovery strategies, prevention techniques
When Not to Parallelize	Sequential workflow advantages, decision tree, cost-benefit analysis of dispatch overhead

---

Integration with Other Skills

Situation	Recommended Skill
Planning the work before dispatching agents	Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for the writing-plans skill
Understanding codebase before decomposition	Delegate to the investigator agent from krzysztofsurdy/code-virtuoso
Implementing features in isolated worktrees	Delegate to the implementer agent from krzysztofsurdy/code-virtuoso
Multi-dimensional code review	Delegate to reviewer and refactor-scout agents from krzysztofsurdy/code-virtuoso
Identifying test gaps across modules	Delegate to the test-gap-analyzer agent from krzysztofsurdy/code-virtuoso
Full feature delivery with agent team	See agent chaining patterns in krzysztofsurdy/code-virtuoso AGENTS.md
Structuring agent-driven development workflows	Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for the subagent-driven-development skill
Designing system architecture before dispatch	Delegate to the architect agent from krzysztofsurdy/code-virtuoso