Orchestrate

Coordinate a team of parallel agents to execute a phase from a task plan. Manages task assignment, monitoring, scope enforcement, and wave-transition quality gates.

Modes:

Interactive (default): In-session agents via TeamCreate/Task/SendMessage — use for complex tasks needing inter-agent coordination
Headless (--headless): Independent claude -p processes — use for parallelizable tasks with clear scope boundaries (~54% less coordination overhead)

Do NOT load when

task is small enough for one agent to finish directly
no written plan or no separable workstreams exist
parallel execution would create more overlap than speedup

NEVER

Never let parallel agents git add && git commit without flock — git's index is process-global. Concurrent writes silently mix staged files between commits. Every agent system prompt must include flock /tmp/orchestrate/{session-id}/git.lock. Symptom: commit A contains files from task B.
Never skip file overlap check — two agents editing the same file produces merge conflicts neither can resolve (they have no knowledge of each other). Detect overlap at plan time, serialize conflicting tasks.
Never trust is_error field alone for failure detection — budget exhaustion sets is_error: false with subtype: "error_max_budget_usd". Always check subtype.startsWith("error_"). Confirmed via live testing of claude -p --output-format json.
Never reuse PID files across waves — OS recycles process IDs. Always clear /tmp/orchestrate/{session-id}/task-*.pid between waves or a stale PID matches an unrelated process, causing the monitor loop to wait indefinitely.
Never spawn headless agents without --no-session-persistence — each claude -p writes a session file to ~/.claude/. 22 parallel tasks = 22 orphaned session files polluting session history.
Never use --dangerously-skip-permissions without --allowedTools — the flag alone gives unrestricted tool access including TeamCreate/SendMessage/Task (recursive agents). Always pair with --allowedTools "Bash Edit Write Read Glob Grep".
Never retry a failed agent by re-spawning the same one with appended errors — accumulated failed reasoning makes the second attempt worse. Always spawn a fresh fix-subagent with targeted instructions.
Never run code quality review before spec compliance passes — quality review on spec-incorrect code wastes tokens and produces misleading results. Spec compliance first, always.
Never consider a headless task done without running the full verification chain — even subtype: "success" doesn't guarantee: correct branch, in-scope files, passing build. Always: commit exists → scope check → verify command.

Mode selection decision tree

Is task count > 10 AND tasks have clear file boundaries?
  YES → Headless: ~54% less overhead, simpler monitoring
  NO → Interactive: better for coordination, cross-task decisions

Do tasks share many files (>50% overlap)?
  YES → Add git worktrees OR serialize into sequential waves
  NO → Standard parallel execution with flock

Resource loading (mandatory)

Before spawning any agent: Read agent-roles.md for role assignments and model selection
Headless mode, before each task prompt: Read prompt-templates/{role}.md for that task's role
At every wave transition: Read wave-template.md for the pre/during/post checklist
For claude -p flag details or error classification: headless-runner.md

Do NOT load prompt templates in interactive mode — interactive agents invoke /quality-commit and /tdd directly.

Scripts

bash scripts/setup-session-dir.sh
node scripts/check-file-overlap.js "apps/api/src/a.ts,apps/api/src/b.ts" "apps/api/src/b.ts,apps/web/src/c.ts"

Failure escalation (headless)

Retry with context (up to 2): Append error output, re-spawn same model
Model escalation (after 2 fails): haiku→sonnet, sonnet→opus. Budget ×1.5
User intervention: Print full failure history. Offer: Skip / Manual fix / Abort

Progressive stall escalation (interactive)

Timer	Action
60s	Ping: "Status check — what are you working on?"
120s	Warning: "No response in 2min. Will reassign in 60s."
180s	Reassign: spawn replacement with task context

Integration map

File	Load when
`agent-roles.md`	Assigning roles to tasks (Step 2)
`prompt-templates/{role}.md`	Building headless agent prompts
`wave-template.md`	Running wave transition gate
`headless-runner.md`	Debugging `claude -p` flags or output format
`execution-steps.md`	Full step-by-step execution reference (3H/3I)

Arguments

$ARGUMENTS accepts: Phase ID, plan file path, or inline task list.

Key flags: --headless, --interactive, --dry-run, --wave N, --max-agents N, --budget-per-task N, --timeout-multiplier N, --no-qa, --verbose

Examples

/orchestrate A                          # Phase A, interactive
/orchestrate A --headless               # Phase A, headless
/orchestrate A --headless --dry-run     # Preview prompts without spawning
/orchestrate A --wave 2                 # Resume from wave 2
/orchestrate docs/plans/custom.md       # Custom plan file
/orchestrate "add auth; write tests"    # Inline task list