Dispatching Parallel Agents

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:

Parallelization Decision Table

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

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

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

Integration Failure Decision Table

STOP — Do NOT commit until:

• All agent outputs collected
• No file conflicts detected
• Full test suite passes
• Build and lint pass

Common Parallel Patterns

Pattern Decision Table

Example: Full Dispatch

TASK: "Update the API to v2, add tests, and update OpenAPI spec"

AGENT 1 - API Routes:
  Scope: Update route handlers in src/routes/v2/
  Context: [v2 API spec, breaking changes list]
  Output: Modified files list, breaking changes implemented
  Constraints: Do NOT touch tests or docs

AGENT 2 - Tests:
  Scope: Write tests in tests/v2/
  Context: [v2 API spec, test conventions, existing v1 tests as reference]
  Output: New test files, coverage summary
  Constraints: Do NOT modify source code

AGENT 3 - OpenAPI Spec:
  Scope: Update openapi/v2.yaml
  Context: [v2 API spec, OpenAPI 3.1 format]
  Output: Updated spec file
  Constraints: Do NOT modify code or tests

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

If you catch yourself thinking:

• "These agents probably won't conflict..." — Verify. Do not assume.
• "The integration will be fine..." — Run the full test suite. Always.
• "I can merge their changes to the same file manually..." — No. One file, one owner.

Integration Points

Parallelism Safety Rules Summary

Skill Type

RIGID — Follow this process exactly. Independence verification is mandatory. All four prompt sections are mandatory. Integration verification is mandatory. No shortcuts on parallelism safety.