orchestrating-parallel-workers

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