orchestrating-parallel-workers

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)