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)

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