krzysztofsurdy 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
Independence is a precondition, not an optimization. If tasks share mutable state, they cannot run in parallel. Period.
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.
Clean context only. Never leak your conversation history, other agents' results, or ambient project context into a subagent's session.
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.
Plan the synthesis before the dispatch. If you cannot describe how outputs will be merged, you are not ready to parallelize.
Failure is expected. Budget for one agent failing. Define what "good enough" looks like with partial results.
Fewer, focused agents beat many scattered ones. Three well-briefed agents outperform seven vaguely-scoped ones.
Investigate before parallelizing. The first dispatch is usually a single investigator. Parallel execution comes after the problem space is mapped.
The orchestrator synthesizes, not concatenates. Pasting outputs together is not integration. Resolve conflicts, deduplicate, and produce a coherent whole.
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 |