orchestrator

name	orchestrator
description	Automated plan execution pipeline. Use when running /orchestrate on an /interactive-planning output. Handles plan ingestion, review, skill matching, tech research, user gating, and phased execution with worktree isolation, testing, code review, and incremental commits.
metadata	{"author":"shihwesley","version":"1.0.0"}
user-invocable	true
allowed-tools	["Bash","Glob","Grep","Read","Write","Edit","Task","AskUserQuestion","TaskCreate","TaskUpdate","TaskList","Skill","ToolSearch","WebSearch"]

Orchestrator

Takes /interactive-planning output and executes it through a 6-stage pipeline: ingest, review, skill-match, research, user gate, and phased execution with worktree isolation.

When to Use

• After /interactive-planning produces a plan directory with task_plan.md or manifest.md
• When you need automated, isolated execution of a multi-phase plan
• When resuming an interrupted orchestration (--resume)

Pipeline Stages

1. INGEST -- read plan files (task_plan.md or manifest.md + specs), discover project docs (CLAUDE.md, codebase map)
2. REVIEW -- agent checks phase sizing, gaps, clarity, dependencies, confidence (skipped on --resume)
3. MATCH -- resolve skills per phase via registry lookup, AgentReverse fallback, web search fallback, or general-purpose default
4. RESEARCH -- fetch official docs for unfamiliar tech (Context7, knowledge store, web), produce cheat sheets
5. GATE -- present full execution plan to user for approval
6. EXECUTE -- for each phase sequentially, launch a phase-runner subagent that handles worktree creation, agent dispatch, testing, code review, commit, and merge

Dispatch Modes

The orchestrator picks classic or team mode per-phase based on task count, shared files, and dependencies:

Condition	Mode
1-2 tasks	classic
3+ tasks, all independent	classic
4+ tasks with shared files or deps	team
Low/medium confidence, 3+ tasks	team
--team flag	team (forced)
--no-team flag	classic (forced)

Flags

Flag	Effect
--dry-run	Run stages 1-4, show plan at stage 5, stop
--resume	Skip completed phases, skip stage 2 review
--max-parallel N	Max agents per batch (default: 3)
--model sonnet|opus|haiku	Model for dispatched agents
--phase N	Execute only phase N
--team	Force Agent Teams mode
--no-team	Force classic Task dispatch

Component Files

All component specifications live in references/:

File	Role
references/plan-ingester.md	Parse plan files, handle spec-driven and task-based modes
references/plan-reviewer.md	Review and restructure plans (sizing, gaps, clarity)
references/skill-matcher.md	3-step skill resolution cascade
references/tech-researcher.md	Fetch docs, produce cheat sheets, manage knowledge store
references/skill-registry.json	Keyword-to-skill/agent mappings
references/worktree-manager.md	Worktree lifecycle per phase
references/agent-dispatcher.md	Dual-mode dispatch (team or classic)
references/team-lead.md	Agent Teams lead coordination protocol
references/phase-runner.md	Self-contained protocol for one phase
references/phase-finisher.md	Test, review, commit chain (runs inside phase-runner)

Context Window Design

The main orchestrator stays lean (~800 tokens per phase) by delegating all heavy work to phase-runner subagents. Each phase-runner gets its own context window and returns a ~20-line structured result. A 5-phase plan uses roughly 4k tokens for execution.

Examples

# Standard execution
/orchestrate ./plans/my-feature

# Preview without executing
/orchestrate --dry-run ./plans/my-feature

# Resume after interruption
/orchestrate --resume ./plans/my-feature

# Execute specific phase with limited parallelism
/orchestrate --phase 2 --max-parallel 2 ./plans/my-feature

# Force team mode
/orchestrate --team ./plans/my-feature

Common Issues

• Plan file not found: The orchestrator resolves PLAN_DIR to an absolute path via realpath. Make sure the directory exists and contains task_plan.md or manifest.md.
• No skills matched: Falls back to general-purpose agent type with a warning. Add keywords to your plan's task descriptions to improve matching.
• Phase-runner fails after retries: You get four options: fix manually, skip the phase, abort, or retry from scratch. The phase-runner's error message usually points to the root cause.
• Context window fills up: The phase-runner architecture prevents this by design. If the main orchestrator still fills up, it's likely from stages 1-4 reading too many files. Use --resume to skip stages on retry.
• Merge conflicts: The orchestrator pauses and asks you to resolve manually. It won't force-merge.