orchestrating-parallel-workers git:20260411.9384f95A

Immutable. This exact content never changes and is served at /api/v1/blob/986487da5e90048a.

---
name: orchestrating-parallel-workers
description: Fan out tasks to parallel background agents with independent context windows. Use when work can be split into independent units that benefit from isolated execution.
compatibility: Designed for Claude Code
metadata:
  allowed-tools: Agent, TaskCreate, TaskUpdate, TaskList, Read, Write
  argument-hint: <task-list-or-description>
  context: inline
  stability: development
---

# Parallel Worker Orchestration

**Target**: $ARGUMENTS

Decomposes work into independent units and dispatches them to parallel
background agents. Each agent gets its own context window, preventing
cross-contamination between unrelated tasks.

## When to Use

- Multiple independent tasks (e.g., create 3 unrelated files, research 4 topics)
- Context-heavy work that would pollute the main session
- Parallel file creation/editing in different areas of the codebase

## When NOT to Use

- Sequential dependent tasks (output of A feeds into B)
- Single-file changes or trivial edits
- Tasks requiring shared mutable state between workers
- Fewer than 2 independent units

## Workflow

### 1. Decompose

Split the user request into independent work units. Each unit must be:
- Self-contained (no dependency on other units)
- Well-scoped (clear input, clear expected output)
- Worth isolating (non-trivial enough to justify agent overhead)

### 2. Plan

For each unit, define:

| Field | Description |
|-------|-------------|
| **Name** | Short identifier (e.g., `worker-auth`, `worker-docs`) |
| **Type** | `worktree` for file changes, `shared` for read-only research |
| **Prompt** | Complete, self-contained instructions (no shared context) |
| **Output** | What the agent should produce and where |

### 3. Dispatch

Launch all agents in a **single message with multiple Agent tool calls**.
This ensures true parallel execution. Each agent prompt must include:
- Full context needed (file paths, requirements, constraints)
- Expected output format and location
- No references to other agents or their work

### 4. Track

Use TaskCreate for each dispatched unit to give the user visibility:

```
TaskCreate: "worker-auth: implement OAuth module" — status: in_progress
TaskCreate: "worker-docs: write API reference" — status: in_progress
```

Update tasks as agents complete via TaskUpdate.

### 5. Collect

After all agents finish:
- Read each agent's output
- Validate completeness and correctness
- Synthesize a summary for the user
- Handle any git operations (worktree agents lack Bash)

## Agent Isolation Modes

| Mode | Use when | File access |
|------|----------|-------------|
| `worktree` | Agent creates/edits files | Isolated copy, lead merges |
| `shared` | Agent only reads/researches | Shared repo, no writes |

## Constraints

- **Worktree agents lack Bash** — the lead agent handles all git operations
  (commits, merges, branch management) after collecting results
- **Max ~5 parallel agents** — diminishing returns beyond this; context
  scheduling overhead increases
- **Self-contained prompts** — each agent gets a complete prompt with all
  necessary context; no shared memory between agents
- **Lead agent owns coordination** — only the lead creates, tracks, and
  collects; agents do not spawn sub-agents

## Anti-Patterns

- Dispatching a single trivial task as a "parallel" worker (just do it inline)
- Sharing mutable state between agents (they cannot see each other's changes)
- Vague prompts that require agents to ask clarifying questions
- Dispatching dependent tasks in parallel (use sequential execution instead)
- Skipping the collect phase (results must be validated and synthesized)

## Quality Check

- Each agent prompt is self-contained and actionable
- No circular or hidden dependencies between units
- All agent results collected and validated before reporting to user
- Git operations performed by lead after collection, not by workers