dispatching-parallel-agents

What this skill does

# Dispatching Parallel Agents

## Overview

This skill coordinates multiple agents working concurrently on independent subtasks to reduce total execution time while maintaining correctness. It provides strict rules for identifying safe parallelization opportunities, writing focused agent prompts, and integrating results without conflicts. The key constraint is that no two agents may modify the same file.

**Announce at start:** "I'm using the dispatching-parallel-agents skill to run [N] independent tasks concurrently."

## Agent Tool Reference

All dispatch uses the `Agent` tool. Parameters:
- `prompt` (required) — task description with full context
- `description` (required) — short label (3-5 words)
- `subagent_type` — `"Explore"` (codebase search), `"Plan"` (architecture), `"general-purpose"` (default)
- `run_in_background` — `true` for async (you'll be notified on completion)
- `model` — optional override: `"sonnet"`, `"opus"`, `"haiku"`

**Parallel:** Multiple `Agent` calls in one message run concurrently.
**Background:** `run_in_background=true` for non-blocking work.
**Named agents:** Use `subagent_type` to reference installed agent templates (e.g., `"superpowers:code-reviewer"`).

## Trigger Conditions

- A task decomposes into 2+ subtasks with no data dependencies between them
- Each subtask operates on different files or different sections of the codebase
- The combined result can be assembled after all agents complete
- Total serial time would be significantly longer than parallel time
- `/decompose` output reveals independent task clusters

---

## Phase 1: Independence Verification

**Goal:** Confirm subtasks are truly independent and safe to parallelize.

Every subtask must satisfy ALL four independence criteria:

| Criterion | Question | If NO |
|-----------|---------|-------|
| No shared files | Do any two agents write to the same file? | Serialize those tasks |
| No shared mutable state | Does any agent depend on a side effect of another? | Serialize dependent tasks |
| Self-contained context | Can each agent work with only its own inputs? | Provide more context or serialize |
| Independent verification | Can each agent's output be validated alone? | Combine into single task |

### Parallelization Decision Table

| Scenario | Parallelize? | Reason |
|----------|-------------|--------|
| Different files, different concerns | Yes | No conflict possible |
| Same module, different files | Yes (careful) | Verify no shared imports change |
| Same file, different sections | No | Merge conflicts inevitable |
| Task B uses Task A's output | No | Sequential dependency |
| Both read same files, write different | Yes | Reads are safe to parallelize |
| Both modify shared config file | No | Config conflicts |
| Independent test files | Yes | Tests are independent |
| One agent adds dep, another uses it | No | Package-level dependency |

### When NOT to Parallelize

- Subtasks share mutable state or modify the same files
- Task B depends on the output of Task A
- The overhead of coordination exceeds the time saved
- A single agent can complete the work in under 30 seconds
- The task requires iterative refinement where each step informs the next

**STOP — Do NOT dispatch agents (via the `Agent` tool) until:**
- [ ] All four independence criteria verified for every subtask pair
- [ ] No two agents write to the same file
- [ ] Each agent's context is self-contained

---

## Phase 2: Prompt Construction

**Goal:** Write focused, unambiguous prompts that prevent scope creep and conflicts.

Each agent prompt MUST contain exactly four sections:

### Section 1: Scope (What to Do)

Be specific about the exact task, files, and expected changes.

```
SCOPE: Add structured JSON logging to all API route handlers in src/api/.
Replace console.log calls with the logger from src/utils/logger.ts.
Files to modify: src/api/users.ts, src/api/orders.ts, src/api/products.ts.
```

### Section 2: Context (Everything Needed)

Provide all information the agent needs without requiring it to explore.

```
CONTEXT:
- Logger API: logger.info(message, metadata), logger.error(message, error)
- Import: import { logger } from '../utils/logger'
- Current pattern in files: console.log('action', data)
- Target pattern: logger.info('action', { data, requestId: req.id })
```

### Section 3: Output Format (What to Return)

Define exactly what the agent should produce.

```
OUTPUT: For each modified file, return:
1. The file path
2. A summary of changes made
3. Number of console.log calls replaced
```

### Section 4: Constraints (What NOT to Do)

Prevent scope creep and conflicts explicitly.

```
CONSTRAINTS:
- Do NOT modify any files outside src/api/
- Do NOT change the logger utility itself
- Do NOT add new dependencies
- Do NOT refactor function signatures
- Do NOT modify test files
- If you encounter an issue outside your scope, report it but do not fix it
```

### Agent Prompt Template

```
You are a focused agent with a single task.

## Scope
[Specific task description with exact files]

## Context
[All information needed to complete the task]
[Relevant code patterns, APIs, conventions]

## Output Format
[Exact structure of what to return]

## Constraints
- Do NOT modify files outside: [list]
- Do NOT change: [list things to leave alone]
- Do NOT add dependencies
- If you encounter an issue outside your scope, report it but do not fix it
```

### Prompt Quality Checklist

| Check | Question |
|-------|---------|
| Scope is specific | Can the agent complete the task without guessing? |
| Context is complete | Does the agent need to explore the codebase? (should be no) |
| Output is defined | Will the agent return what you need to integrate? |
| Constraints are explicit | Are file boundaries and "do NOT" items clear? |

**STOP — Do NOT dispatch (via the `Agent` tool) until:**
- [ ] Every prompt has all 4 sections
- [ ] No prompt requires the agent to explore beyond provided context
- [ ] File boundaries are explicit in every constraint section

---

## Phase 3: Dispatch and Monitor

**Goal:** Launch all agents (via the `Agent` tool) concurrently and track completion.

1. Launch all agents concurrently by invoking multiple `Agent` tool calls in a single message
2. Each agent works in isolation on its designated files
3. Monitor for completion — wait for ALL agents to finish
4. Collect outputs from every agent

### Dispatch Tracking Table

```
| Agent | Task | Status | Files | Result |
|-------|------|--------|-------|--------|
| Agent 1 | Add logging to API | in_progress | src/api/*.ts | — |
| Agent 2 | Update unit tests | in_progress | tests/unit/*.ts | — |
| Agent 3 | Fix CSS layout | in_progress | src/styles/*.css | — |
```

### Failure Handling During Dispatch

| Scenario | Action |
|----------|--------|
| One agent fails, others succeed | Retry failed agent independently (via the `Agent` tool) |
| Multiple agents fail independently | Retry each independently (via the `Agent` tool) |
| Agent reports out-of-scope issue | Note for post-integration review |
| Agent exceeds scope (modifies wrong files) | Reject output, re-dispatch (via the `Agent` tool) with stricter constraints |

---

## Phase 4: Integration and Verification

**Goal:** Combine all agent outputs and verify the integrated result.

1. **Collect outputs** — Gather results from every agent
2. **Check for conflicts** — Verify no file was modified by multiple agents
3. **Apply changes** — Integrate all outputs into the codebase
4. **Run integration checks** — Execute the full test suite
5. **Resolve issues** — If integration fails, identify which agent's changes caused it
6. **Commit atomically** — All changes go in together or not at all

### Integration Verification Checklist

| Check | Command | Must Pass |
|-------|---------|-----------|
| No file conflicts | Diff outputs for shared files | Yes |
| Tests pass | Full test suite | Yes |
| Build passes | Build command | Yes |
| Lint passes | Lint command | Yes |
| No re