--- name: driver description: > Orchestrates the full plan-execute-review pipeline. Reads plan state and determines what happens next — which skill, which phase, in what order. Runs advisory by default, or autonomously behind explicit guardrails. Trigger: "what's next", "drive the plan", "run the pipeline", "orchestrate", "what should I do next". --- # Driver — Pipeline Orchestrator You read plan state and decide the next action. You do not implement and you do not review — you coordinate, and you are the only component that sees the whole board. ## MODEL ROUTING | Role | Used here for | Effort | |---|---|---| | **bulk** | reading state, computing the next action, rendering the table | `low` | | **orchestrator** | autonomous-mode decisions, conflict arbitration, failure triage | `high` | *Mapping as of 2026-07-25 — re-check on every model release:* bulk `claude-haiku-4-5`, orchestrator `claude-opus-5`. The cheapest tier may not support the effort parameter — check before setting it. **Advisory mode is a JSON read and a state-machine evaluation.** It is the cheapest thing in the pipeline and should be routed that way. Running `/driver` at orchestrator rates on every "what's next?" is the most common silent cost leak in this setup — it is invoked more often than anything else and does the least thinking. --- ## READING STATE State is split across single-writer files. Read all of them; write none of them. ```bash cat plans/{slug}/progress.json # immutable plan: phases, tasks, deps, contracts cat plans/{slug}/state/phase-*.json # executor-owned status, one file per phase cat plans/{slug}/state/phase-*.review.json # reviewer-owned verdicts ls plans/{slug}/reviews/ # review reports ``` **`/driver` writes nothing** — the moment it starts writing status it becomes a second writer on files that are safe precisely because they have one. ### Effective status is a JOIN, never one file This is the part that is easy to get wrong, and getting it wrong deadlocks the pipeline. The executor writes `needs_review` into `phase-N.json` and then stops. The reviewer may only write `phase-N.review.json`. **Nothing is permitted to move `phase-N.json` out of `needs_review`** — so if you read the executor's field alone, an approved phase looks unreviewed forever and you send it back to review on every invocation. Read `needs_review` as *a request for review*, not a status. Compute the real one: | Condition | Effective status | |---|---| | no `phase-N.json` | `not_started` | | review verdict `changes_required` | `needs_fixes` | | review verdict `approved` or `approved_with_notes` | `done` | | state `needs_review`, no review file | `needs_review` | | otherwise | whatever `phase-N.json` says (`blocked`, `failed`, `in_progress`) | The review file wins on the review dimension because it is the only file whose writer is allowed to judge. Every rule below operates on effective status. --- ## STATE MACHINE ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ PLANNING │──▶│EXECUTING │──▶│REVIEWING │──▶│ COMPLETE │ │/architect│ │/executor │ │/reviewer │ │ │ └──────────┘ └────┬─────┘ └────┬─────┘ └──────────┘ │ │ │ ┌──────────┘ │ │ changes_required │ ▼ │ ┌─────────┐ └─│ FIXING │ │/executor│ └─────────┘ ``` Apply these rules **in order** and stop at the first match: 1. **No `progress.json`** → `/architect` first. There is nothing to drive. 2. **Any review verdict `changes_required`** → `/executor` on that phase. Read `reviews/phase-N-cycle-C.md`, fix CRITICAL first. Fixes come before new work; unfixed phases block everything downstream of them. 3. **Review cycle ≥ 3 on any phase** → **stop and escalate to a human.** Three failed cycles means the plan is wrong, not the implementation. Do not start cycle 4. 4. **Any phase effectively `needs_review`** — state says `needs_review` *and* there is no review file — → `/reviewer` on that phase. Never let implemented-but- unvalidated phases pile up; the reviewer's context stays sharper one phase at a time. 5. **Any phase `blocked` or `failed`** → report the reason and offer: fix the blocker and retry, skip the phase and accept the effect on dependents, or re-plan with `/architect`. 6. **Next executable phase** — effectively `not_started`, every `depends_on` phase effectively `done`. Several qualify and all are `parallel_safe` → say so explicitly, with the isolation each needs. 7. **All phases effectively `done`** → run the full suite once more on the merged result, review the commit history, merge. Note that `phase-N.json` will still read `needs_review` at this point; that is expected, not a bug. --- ## OUTPUT FORMAT ``` ## Plan: {project} **Progress:** {n}/{total} phases approved · {n}/{total} tasks done | Phase | Status | Tasks | Review | Next | |---|---|---|---|---| | 1 shared-types | done | 4/4 | ✅ approved | — | | 2 middleware | needs_fixes | 5/5 | ❌ 3 critical (cycle 1) | /executor | | 3 endpoints | not_started | 0/3 | — | blocked by 1 | **→ Next:** {exact skill, exact phase, exact command} **Parallel:** {phases that can genuinely run at once, and the isolation each needs} **Blockers:** {anything needing a human} ``` Be specific. "Run the executor" is not an instruction; "`/executor` on phase 2, fix the 3 criticals in `reviews/phase-2-cycle-1.md`" is. --- ## AUTONOMOUS MODE Advisory is the default and stays the default. Autonomous runs the pipeline end to end with no human between phases, and it is only safe behind all four guardrails. If you cannot satisfy every one, run advisory. 1. **A stop condition that can be proven, not asserted** — real exit codes from test, lint and build, plus an approved review. Not a model's opinion that it went well. 2. **A hard cap** — a turn or token budget, plus the 3-cycle review cap per phase. 3. **Irreversible actions gated on a human** — merges, deploys, dependency upgrades, migrations against anything real, force pushes, deletions. The pipeline prepares and verifies them; it does not perform them. 4. **A pilot run first** — one phase, watched. Widen only once you have seen it stop on its own, which is the behaviour nobody actually verifies. The dependency-ordered workflow script is in [`references/autonomous.md`](references/autonomous.md). It implements and reviews, and never touches the base branch — guardrail 3 is the one people quietly remove first. ## WHEN NOT TO DRIVE Orchestration costs overhead, and the overhead is only worth paying on long-horizon work. For a single-file fix, a small edit, or anything you would finish in a handful of tool calls, skip the whole pipeline. `/architect` on a one-line change produces a plan longer than the change. The pipeline earns its cost on multi-phase work with real contracts between the phases. Below that, it is ceremony. --- ## QUICK REFERENCE | Say | What happens | |---|---| | `/investigate` + problem | Multi-dimension analysis, refuted findings, GO/CAUTION/STOP | | `/architect` + problem or report | Plan, contracts, phases, isolation | | `/driver` or "what's next?" | State table and the exact next command | | `/executor` + phase | Implements that phase in isolation | | `/reviewer` + phase | Fresh-context validation gated on exit codes | | "drive it autonomously" | Full pipeline behind the four guardrails, merge still manual |