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.
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.
/interactive-planning produces a plan directory with task_plan.md or manifest.md--resume)task_plan.md or manifest.md + specs), discover project docs (CLAUDE.md, codebase map)--resume)Stage 6 uses .claude/scripts/phase-runner.py — a Python script that runs each protocol step as a separate claude -p subprocess. Artifact gates between steps make every step structurally unskippable.
python3 .claude/scripts/phase-runner.py --phase N --plan-dir docs/plans
Each step gets its own context window. The script controls flow, not prompt instructions. This prevents the known failure mode where a single agent skips review steps.
Protocol steps (each a separate subprocess):
claude -p calls per spec)Fix step detail: Findings are fixed in three sequential passes so later fixers see earlier changes. P0 runs with P1.
| Pass | Severity | Why sequential |
|---|---|---|
| 1 | P0 + P1 | Critical fixes first |
| 2 | P2 | Sees P1 fixes, skips items already resolved |
| 3 | P3 | Sees P1 + P2 fixes, skips items already resolved |
If the subprocess runner is unavailable, Stage 6 falls back to launching a phase-runner subagent per phase. This is the original architecture — each phase-runner gets its own context window but controls its own step execution via prompt instructions. Known limitation: single agents tend to skip review steps.
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) |
| 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 |
--subprocess | Force subprocess phase-runner (default when script exists) |
--no-subprocess | Force agent-based phase-runner |
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 | Protocol spec for one phase (used by both modes) |
references/phase-finisher.md | Test, review, commit chain (runs inside phase-runner) |
Script:
| File | Role |
|---|---|
.claude/scripts/phase-runner.py | Subprocess executor — enforces protocol via artifact gates |
Subprocess mode: Zero main-context cost per phase. The script runs outside the conversation entirely. The orchestrator calls it via Bash and reads the exit code + progress.md updates.
Agent mode (fallback): ~800 tokens per phase in main context. Each phase-runner subagent gets its own context window and returns a ~20-line structured result.
# Standard execution (subprocess mode, auto-detected)
/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 agent-based execution (skip subprocess)
/orchestrate --no-subprocess ./plans/my-feature
# Run phase-runner script directly (outside orchestrator)
python3 .claude/scripts/phase-runner.py --phase 4 --plan-dir docs/plans
python3 .claude/scripts/phase-runner.py --phase 4 --plan-dir docs/plans --dry-run
python3 .claude/scripts/phase-runner.py --phase 4 --plan-dir docs/plans --step review
PLAN_DIR to an absolute path via realpath. Make sure the directory exists and contains task_plan.md or manifest.md.general-purpose agent type with a warning. Add keywords to your plan's task descriptions to improve matching.