dispatching-parallel-agents

Dispatching parallel agents

Overview

When work splits into three or more independent problem domains, dispatch dedicated agents in parallel rather than sequencing them. Each agent operates in full isolation. The coordinator manages fan-out, collects results, and handles merges.

Core principle: Independent problems get independent agents. Shared state is the coordinator's job, not the agents'.

Announce at start: "I'm using the dispatching-parallel-agents skill to parallelize independent work streams."

When to use

• Three or more tasks with no data dependencies between them
• Tasks operate on non-overlapping file sets (or can be structured to do so)
• Wall-clock time matters and the runtime supports concurrent agent execution
• Each task is substantial enough to justify its own agent (not a one-liner)

Do not use when:

• Tasks share mutable state or must execute in sequence
• Fewer than 3 tasks — overhead of coordination exceeds benefit
• File sets overlap significantly — merge conflicts will cost more than sequencing saves

Workflow

1. Decompose into domains

• List all tasks from the plan or user request
• Group by problem domain (e.g., backend API, database schema, frontend UI, infrastructure)
• Verify independence: if task A's output is task B's input, they cannot run in parallel
• Identify shared resources (config files, shared types) and decide ownership — only one agent writes to any given file

2. Prepare context packets

For each parallel agent:

• Relevant spec or plan section only
• File paths the agent owns (explicit list, not "figure it out")
• Interface contracts it must honor (types, API shapes, database schemas)
• Constraints and style guidelines relevant to its domain

Never include: other agents' specs, session history, or coordinator-internal state.

3. Dispatch

• Spawn all agents concurrently
• Each agent is a fresh instance — no shared memory, no cross-agent communication
• If using git worktrees (see using-git-worktrees), each agent gets its own worktree
• If on a single branch, assign non-overlapping file scopes to prevent conflicts

4. Coordinate results

When agents complete:

• Collect deliverables from each agent
• Check for interface mismatches between domains (e.g., frontend expects a field the API does not provide)
• Run integration-level validation across combined output
• Resolve any conflicts in shared files (should be rare if decomposition was correct)

5. Handle failures

• A failed agent does not block other agents
• Retry the failed agent with a fresh instance plus failure context
• If failure reveals a dependency that was missed, restructure: pull the dependent tasks into sequence

Rules

• Minimum three agents. For two tasks, the coordination overhead is not worth it — use sequential execution or subagent-driven-development.
• No cross-agent communication. Agents never send messages to each other. All coordination flows through the coordinator.
• Explicit file ownership. Before dispatch, every writable file path is assigned to exactly one agent. Shared read-only files (types, configs) are fine for multiple agents.
• Coordinator does not implement. The coordinator decomposes, dispatches, collects, and integrates. It does not write application code.
• Fail independently. One agent's failure must not corrupt another's work.

Anti-patterns

• Premature parallelization — Dispatching 2 agents or dispatching when tasks are clearly sequential. Adds overhead without benefit.
• Implicit file sharing — Two agents both editing the same config file leads to merge conflicts or silent overwrites. Assign ownership explicitly.
• Fat coordinator — The coordinator starts "helping" agents by implementing pieces itself. This breaks the separation model and muddies responsibility.
• Cross-pollination — Feeding one agent's intermediate output into another agent's context during execution. Wait until all complete, then integrate.
• Ignoring interface boundaries — Dispatching without defining the contracts between domains. Agents will invent incompatible interfaces.

Integration

Pairs with:

• skills/using-git-worktrees — give each parallel agent its own worktree for true filesystem isolation
• skills/subagent-driven-development — within each parallel track, use subagent-driven-development for sequential subtasks
• skills/validation-aggregator — after merging parallel outputs, run consolidated validation
• skills/git-workflow — branch naming and PR discipline still apply; each worktree branch follows prefix conventions