dispatching-parallel-agents

Dispatching Parallel Agents

Use parallel subagents only for truly independent work.

Decision Check

Use parallel dispatch when all are true:

• Problems have separate root causes.
• Tasks do not edit the same files.
• Tasks do not require shared intermediate state.

If any condition fails, run sequentially.

Do not use when:

• Failures are related — fixing one might fix others.
• The task is exploratory — you don't know what's broken yet.
• Agents would edit the same files or shared resources.
• Understanding the problem requires seeing the full system state.

Procedure

1. Split work into independent domains.
2. Write one focused prompt per domain.
3. Dispatch all prompts concurrently.
4. Collect summaries and changed files.
5. Resolve conflicts between summaries and changed files.
6. Run integration verification: execute the full project test suite plus any cross-domain checks. Do not mark the wave complete until integration passes.

Context Isolation

Never forward parent session context or history to subagents. Construct each subagent's prompt from scratch using only the items listed below. Subagents must not receive conversation history, prior reasoning chains, or context from other subagent runs.

Prompt Requirements

Each agent prompt must include:

• Exact scope
• Acceptance criteria
• Constraints (what not to touch)
• Required output format
• Skill leakage prevention: "You are a focused subagent. Do NOT invoke any skills from the superpowers-optimized plugin. Do NOT use the Skill tool. Your only job is the task described below."

Example prompt

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" — expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" — fast tool aborted instead of completed
3. "should properly track pendingToolCount" — expects 3 results but gets 0

Your task:
1. Read the test file and understand what each test verifies.
2. Identify root cause — timing issues or actual bugs?
3. Fix the root cause. Do NOT just increase timeouts.
4. Do NOT change any files outside src/agents/agent-tool-abort.test.ts and its direct implementation file.

You are a focused subagent. Do NOT invoke any skills from the superpowers-optimized plugin.
Do NOT use the Skill tool. Your only job is the task described above.

Return: Summary of root cause and what you changed.

Common mistakes

❌ Too broad: "Fix all the tests" — agent gets lost ✅ Specific: "Fix agent-tool-abort.test.ts" — focused scope

❌ No context: "Fix the race condition" — agent doesn't know where ✅ With context: Paste the error messages and test names

❌ No constraints: Agent might refactor everything ✅ Constrained: "Do NOT change files outside X"

❌ Vague output: "Fix it" — you don't know what changed ✅ Specific output: "Return summary of root cause and what you changed"

Risks

• False independence assumptions
• Merge conflicts across shared files
• Inconsistent behavior across parallel fixes

When risk is high, fall back to sequential execution.