Dispatching Parallel Agents
Dispatch subagents only when independence is real. Parallelism helps when each agent can reason and edit without needing the others' context or touching the same state.
If work units must be recorded as issues and are not defined yet, use creating-issues before dispatching agents.
Use When
- multiple failing test files have different likely causes
- separate subsystems are broken independently
- research questions can be answered independently
- each task has a clear owner and expected output
- agents can avoid editing the same files
- each task can be verified independently before integration
Do Not Use When
- one root cause may explain all failures
- the system state must be understood as a whole
- tasks share files, migrations, generated output, or external state
- you do not yet know how the work decomposes
- results must be sequenced for correctness
- one agent's answer can change another agent's task definition
Process
- Group work into independent domains with expected verification.
- Assign each agent one domain, explicit file ownership, and protected paths not to touch.
- Tell each agent they are not alone in the codebase and must not revert others' edits.
- Give each agent fresh, self-contained context: goal, constraints, relevant errors, commands, expected output, verification, owned files, and files not to touch. Do not rely on inherited session history.
- Run agents in one parallel batch only after checking for likely conflicts.
- Read every result, inspect diffs, and resolve overlaps.
- Run the full relevant verification after integration.
Independence Check
Before dispatch, each task must have:
- distinct files or read-only research scope
- no shared generated artifacts, migrations, or global state
- a clear result that can be reviewed independently
- no dependency on another agent's pending answer
- a verification method whose result proves that domain's completion
If any item fails, sequence the work instead.
Prompt Shape
Task: <one problem domain>
Context:
- relevant failure or requirement
- files or modules owned by this agent
- constraints and files not to touch
Goal:
- what should be true when done
Return:
- root cause or finding
- changes made
- verification run
- requirement or task coverage proven
- remaining risk
If ownership cannot be stated clearly, do not parallelize yet.
Integration Report
After agents return, summarize:
## Results
- Agent/task: outcome and files changed
## Conflicts
- Overlap or contradiction, and resolution
## Verification
- Commands run after integration
## Remaining Risk
- What was not checked
1---2name: dispatching-parallel-agents3description: Use when splitting two or more independent tasks, failures, investigations, or research questions across parallel subagents is safe because files, state, dependencies, and verification can be isolated.4license: MIT5---67# Dispatching Parallel Agents89Dispatch subagents only when independence is real. Parallelism helps when each agent can reason and edit without needing the others' context or touching the same state.1011If work units must be recorded as issues and are not defined yet, use `creating-issues` before dispatching agents.1213## Use When1415- multiple failing test files have different likely causes16- separate subsystems are broken independently17- research questions can be answered independently18- each task has a clear owner and expected output19- agents can avoid editing the same files20- each task can be verified independently before integration2122## Do Not Use When2324- one root cause may explain all failures25- the system state must be understood as a whole26- tasks share files, migrations, generated output, or external state27- you do not yet know how the work decomposes28- results must be sequenced for correctness29- one agent's answer can change another agent's task definition3031## Process32331. Group work into independent domains with expected verification.342. Assign each agent one domain, explicit file ownership, and protected paths not to touch.353. Tell each agent they are not alone in the codebase and must not revert others' edits.364. Give each agent fresh, self-contained context: goal, constraints, relevant errors, commands, expected output, verification, owned files, and files not to touch. Do not rely on inherited session history.375. Run agents in one parallel batch only after checking for likely conflicts.386. Read every result, inspect diffs, and resolve overlaps.397. Run the full relevant verification after integration.4041## Independence Check4243Before dispatch, each task must have:4445- distinct files or read-only research scope46- no shared generated artifacts, migrations, or global state47- a clear result that can be reviewed independently48- no dependency on another agent's pending answer49- a verification method whose result proves that domain's completion5051If any item fails, sequence the work instead.5253## Prompt Shape5455```text56Task: <one problem domain>5758Context:59- relevant failure or requirement60- files or modules owned by this agent61- constraints and files not to touch6263Goal:64- what should be true when done6566Return:67- root cause or finding68- changes made69- verification run70- requirement or task coverage proven71- remaining risk72```7374If ownership cannot be stated clearly, do not parallelize yet.7576## Integration Report7778After agents return, summarize:7980```markdown81## Results82- Agent/task: outcome and files changed8384## Conflicts85- Overlap or contradiction, and resolution8687## Verification88- Commands run after integration8990## Remaining Risk91- What was not checked92```
h3y6e