Dispatching Parallel Agents

Overview

When you have multiple unrelated failures or features, investigating them sequentially wastes time. Core principle: Dispatch one agent per independent problem domain into strictly isolated physical environments.

When to Use

digraph when_to_use {
    "Multiple tasks/failures?" [shape=diamond];
    "Strictly independent? (No shared state)" [shape=diamond];
    "Sequential execution" [shape=box];
    "Deep Context Gathering" [shape=box];
    "Create Git Worktree per task" [shape=box];
    "Dispatch in Parallel" [shape=box];

    "Multiple tasks/failures?" -> "Strictly independent? (No shared state)" [label="yes"];
    "Strictly independent? (No shared state)" -> "Sequential execution" [label="no"];
    "Strictly independent? (No shared state)" -> "Deep Context Gathering" [label="yes"];
    "Deep Context Gathering" -> "Create Git Worktree per task";
    "Create Git Worktree per task" -> "Dispatch in Parallel";
}

The Strict Dispatch Protocol

1. Prove Independence (Do not guess)

Before considering parallel dispatch, verify independence mechanically:

• Do these tasks touch the same files?
• Do these tests rely on the same global state (e.g., shared mock database, same local network ports)?
• IF YES to any: Abort parallel dispatch. Use sequential subagent-driven-development.

2. Deep Context Gathering (The 20-Question Rule)

The human architect is perfectly willing to answer as many questions as necessary to ensure context is crystal clear before dispatch.

• Ask clarifying questions about each independent domain.
• Define strict boundaries: "Agent A will ONLY touch X, Agent B will ONLY touch Y."
• Do not dispatch until the boundaries are verified by the user.

3. Physical Isolation (MANDATORY)

You MUST NOT run parallel agents in the same directory. For each independent task, use superpowers:using-git-worktrees to create a fresh, isolated branch and physical directory.

• Task 1 -> Worktree A (Branch: fix/domain-1)
• Task 2 -> Worktree B (Branch: fix/domain-2)

4. Dispatch the Subagents

Provide each subagent with a highly focused prompt.

Prompt Structure per Agent:

You are working in an isolated worktree. 
Your specific scope is: [Target File/Subsystem]
Context gathered from architect: [Inject deep context here]

Constraints:
1. Do NOT modify any files outside your scope.
2. Rely on condition-based waiting for tests, not arbitrary timeouts.
3. If tests fail 3 times, trigger your circuit breaker.

Return: A structured summary of the root cause, exact files changed, and test results.

5. Review and Integrate

When all agents complete their work:

1. Review the summaries from all worktrees.
2. Merge fix/domain-1 and fix/domain-2 back into the main development branch.
3. Handle merge conflicts if the independence proof was flawed.
4. Run the full integrated test suite.
5. Cleanup worktrees using superpowers:finishing-a-development-branch.

Common Mistakes & Hard Constraints

| Mistake | Prevention | |---------|------------| | File Locking / Collisions | MANDATORY: Always use separate git-worktrees for concurrent agents. | | Vague Scope | Provide exact file paths and error logs in the prompt. | | Assuming Independence | Check imports and shared mocks before dispatching. | | Rushing the Dispatch | Ask the human architect exhaustive questions to build a bulletproof context for each agent. |

Required Workflow Integrations

• superpowers:using-git-worktrees (For physical isolation)
• superpowers:systematic-debugging (If an agent hits a blocker)
• superpowers:finishing-a-development-branch (For merging and cleanup)