Dispatching Parallel Agents

1---
2name: dispatching-parallel-agents
3description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
4---
5 
6# Dispatching Parallel Agents
7 
8## Overview
9 
10When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
11 
12**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
13 
14## When to Use
15 
16```dot
17digraph when_to_use {
18    "Multiple failures?" [shape=diamond];
19    "Are they independent?" [shape=diamond];
20    "Single agent investigates all" [shape=box];
21    "One agent per problem domain" [shape=box];
22    "Can they work in parallel?" [shape=diamond];
23    "Sequential agents" [shape=box];
24    "Parallel dispatch" [shape=box];
25 
26    "Multiple failures?" -> "Are they independent?" [label="yes"];
27    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
28    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
29    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
30    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
31}
32```
33 
34**Use when:**
35- 3+ test files failing with different root causes
36- Multiple subsystems broken independently
37- Each problem can be understood without context from others
38- No shared state between investigations
39 
40**Don't use when:**
41- Failures are related (fix one might fix others)
42- Need to understand full system state
43- Agents would interfere with each other
44 
45## The Pattern
46 
47### 1. Identify Independent Domains
48 
49Group failures by what's broken:
50- File A tests: Tool approval flow
51- File B tests: Batch completion behavior
52- File C tests: Abort functionality
53 
54Each domain is independent - fixing tool approval doesn't affect abort tests.
55 
56### 2. Create Focused Agent Tasks
57 
58Each agent gets:
59- **Specific scope:** One test file or subsystem
60- **Clear goal:** Make these tests pass
61- **Constraints:** Don't change other code
62- **Expected output:** Summary of what you found and fixed
63 
64### 3. Dispatch in Parallel
65 
66```typescript
67// In Claude Code / AI environment
68Task("Fix agent-tool-abort.test.ts failures")
69Task("Fix batch-completion-behavior.test.ts failures")
70Task("Fix tool-approval-race-conditions.test.ts failures")
71// All three run concurrently
72```
73 
74### 4. Review and Integrate
75 
76When agents return:
77- Read each summary
78- Verify fixes don't conflict
79- Run full test suite
80- Integrate all changes
81 
82## Agent Prompt Structure
83 
84Good agent prompts are:
851. **Focused** - One clear problem domain
862. **Self-contained** - All context needed to understand the problem
873. **Specific about output** - What should the agent return?
88 
89```markdown
90Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
91 
921. "should abort tool with partial output capture" - expects 'interrupted at' in message
932. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
943. "should properly track pendingToolCount" - expects 3 results but gets 0
95 
96These are timing/race condition issues. Your task:
97 
981. Read the test file and understand what each test verifies
992. Identify root cause - timing issues or actual bugs?
1003. Fix by:
101   - Replacing arbitrary timeouts with event-based waiting
102   - Fixing bugs in abort implementation if found
103   - Adjusting test expectations if testing changed behavior
104 
105Do NOT just increase timeouts - find the real issue.
106 
107Return: Summary of what you found and what you fixed.
108```
109 
110## Common Mistakes
111 
112**❌ Too broad:** "Fix all the tests" - agent gets lost
113**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
114 
115**❌ No context:** "Fix the race condition" - agent doesn't know where
116**✅ Context:** Paste the error messages and test names
117 
118**❌ No constraints:** Agent might refactor everything
119**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
120 
121**❌ Vague output:** "Fix it" - you don't know what changed
122**✅ Specific:** "Return summary of root cause and changes"
123 
124## When NOT to Use
125 
126**Related failures:** Fixing one might fix others - investigate together first
127**Need full context:** Understanding requires seeing entire system
128**Exploratory debugging:** You don't know what's broken yet
129**Shared state:** Agents would interfere (editing same files, using same resources)
130 
131## Real Example from Session
132 
133**Scenario:** 6 test failures across 3 files after major refactoring
134 
135**Failures:**
136- agent-tool-abort.test.ts: 3 failures (timing issues)
137- batch-completion-behavior.test.ts: 2 failures (tools not executing)
138- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
139 
140**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
141 
142**Dispatch:**
143```
144Agent 1 → Fix agent-tool-abort.test.ts
145Agent 2 → Fix batch-completion-behavior.test.ts
146Agent 3 → Fix tool-approval-race-conditions.test.ts
147```
148 
149**Results:**
150- Agent 1: Replaced timeouts with event-based waiting
151- Agent 2: Fixed event structure bug (threadId in wrong place)
152- Agent 3: Added wait for async tool execution to complete
153 
154**Integration:** All fixes independent, no conflicts, full suite green
155 
156**Time saved:** 3 problems solved in parallel vs sequentially
157 
158## Key Benefits
159 
1601. **Parallelization** - Multiple investigations happen simultaneously
1612. **Focus** - Each agent has narrow scope, less context to track
1623. **Independence** - Agents don't interfere with each other
1634. **Speed** - 3 problems solved in time of 1
164 
165## Verification
166 
167After agents return:
1681. **Review each summary** - Understand what changed
1692. **Check for conflicts** - Did agents edit same code?
1703. **Run full suite** - Verify all fixes work together
1714. **Spot check** - Agents can make systematic errors
172 
173## Real-World Impact
174 
175From debugging session (2025-10-03):
176- 6 failures across 3 files
177- 3 agents dispatched in parallel
178- All investigations completed concurrently
179- All fixes integrated successfully
180- Zero conflicts between agent changes
181