Dispatching Parallel Agents

Dispatching Parallel Agents Skill

Runs multiple sub-agents concurrently when a plan contains independent subtasks with non-overlapping file boundaries. Each sub-agent receives a self-contained spec. Does NOT parallelize work with dependencies or shared mutable state — that path silently corrupts results.

When to Use

• The plan contains 2+ tasks with no dependency edges between them.
• Multiple research investigations or codebase explorations can run side-by-side.
• Multiple verification runs (lint, test, type-check) can run in parallel.
• User explicitly asks for parallel execution or to "speed this up".
• NOT for debugging (parallel agents mask timing bugs).
• NOT when tasks edit overlapping files or share mutable state.

Prerequisites

• An approved plan in tasks/todo.md with task IDs and explicit dependencies.
• The task Copilot tool available (or equivalent sub-agent mechanism).
• Each candidate task has a precise file-boundary scope ("owns" a directory or file set).
• Integration test or verification step that exercises the combined result.
• The view, edit, grep, and powershell Copilot tools.

How to Run

1. From `tasks/todo.md`, pick tasks with no dependency edges between them.
2. Confirm each has a non-overlapping file scope.
3. Write a self-contained spec per agent (goal, files, DO NOT touch, verification).
4. Dispatch all sub-agents in one tool-call batch.
5. Collect each result; integrate.
6. Run an integration verification on the merged result.
7. Log failures and reasons in `tasks/lessons.md`.

Quick Reference

Procedure

Step 1: Identify Independents

Use view on tasks/todo.md. List tasks with empty or already-satisfied dependency sets. Cross-check file scopes: any overlap → sequential, not parallel.

## Parallelizable
- [ ] Task A: User API endpoints (`src/api/users/`)
- [ ] Task B: Product API endpoints (`src/api/products/`)
- [ ] Task C: Migration scripts (`src/db/migrations/`)

## Sequential (depends on A+B+C)
- [ ] Task D: Integration tests for all endpoints

Step 2: Write Per-Agent Specs

Each spec is self-contained — no agent should need to ask "what do I do?":

### Agent 1 Spec: User API Endpoints
Goal: Implement CRUD endpoints for users.
Files owned: src/api/users/ (create new); src/routes/index.ts (add one route line).
DO NOT touch: src/api/products/, src/db/.
Verification: All new tests in src/api/users/__tests__/ pass; existing tests unaffected.
Return: list of files created + test result summary.

Step 3: Dispatch in One Batch

Issue the sub-agent calls in a single tool-calling batch so they execute in parallel, not sequentially. Use the task tool with mode: background for any agent expected to take more than a few seconds.

Step 4: Collect and Integrate

For each returned agent:

• Confirm it reports verification PASS.
• Inspect the diff with view and git diff --stat.
• Merge changes into the current worktree if the agents wrote to separate worktrees.

Step 5: Integration Verification

After all agents complete, run the full test suite and bash scripts/verify.sh --check on the combined result. Per-agent green does not imply combined green.

Step 6: Handle Partial Failure

If one agent fails:

1. Do not block the others — let successes complete.

2. Diagnose: was the spec ambiguous? Hidden dependency missed?

3. Re-dispatch the failed task with a revised spec, or finish it sequentially.

4. Append to tasks/lessons.md:

   - date: 2026-05-19
     error_type: parallel-dispatch-failure
     trigger: "Agent 2 needed Agent 1's output; was dispatched in parallel"
     root_cause: "Implicit dependency not surfaced in tasks/todo.md"
     fix: "Re-ran Agent 2 after Agent 1 completed"
     rule: "Every parallel-eligible task must declare its dependencies explicitly"
   

Pitfalls

• DO NOT parallelize tasks with dependencies. They will race and one will silently produce wrong output.
• DO NOT dispatch 20 agents at once. 3–5 is manageable; more is chaos and tool-budget exhaustion.
• DO NOT skip integration verification. Per-agent green ≠ combined green.
• DO NOT write vague specs ("handle the user stuff"). They produce vague output.
• DO NOT ignore partial failures. One failure can invalidate downstream work that already merged.

Verification

• Dependency check ran on tasks/todo.md — only zero-dep tasks dispatched in parallel.
• File scopes verified non-overlapping before dispatch.
• Each agent received a self-contained spec including DO NOT list.
• All agents reported back; failures logged.
• Integration test suite + scripts/verify.sh --check passed on the combined result.
• If a failure occurred, tasks/lessons.md was updated with the root cause.