Orchestrator

Orchestrator Skill

Simple mode (<=3 steps): sequential, no worktrees, lightweight reporting. Full mode (4+ steps): parallel worktrees, architect review, full tracking.

Requires .prove/runs/<branch>/<slug>/plan.json for execution. If missing and the user wants a plan-first flow, use --full (starts with PRD phase) or run /prove:plan --task first.

---

Mode Dispatch

The skill is entered via $ARGUMENTS. Parse the first token as a mode flag:

Flag	Meaning	Entry Point
--autopilot [plan-id]	Plan already exists; skip PRD phase. Derive slug from arg (or active run), locate .prove/runs/<branch>/<slug>/plan.json, begin execution.	Phase 0
--full [task-desc]	No plan yet; gather requirements first. task-desc seeds the PRD.	"Full Mode: Requirements Gathering (PRD)"
(none)	Auto-detect (see below).	Resolved mode

Auto-Detect (no flag)

1. Resolve current branch and look for any .prove/runs/<branch>/<slug>/ with a plan.json. If exactly one exists → act as --autopilot with that slug.
2. If none exists → AskUserQuestion header "Mode":
   • Full (start from requirements) — no plan yet; run PRD + plan before execution.
   • Autopilot (plan exists) — point me at the slug.
3. If multiple runs exist for the branch → AskUserQuestion listing slugs, plus a "Full (new run)" option.

Slug Resolution (autopilot)

• Argument is a slug → use directly.
• Argument is free text → kebab-case it (max 40 chars) and match against existing run dirs; if ambiguous, ask.
• No argument → resolve from .prove-wt-slug.txt in the current worktree, or from the single run dir on the branch.

After mode + slug are resolved, proceed to the appropriate phase. All downstream phases (Initialization, Plan Review, Execution Loop, Completion, Merge & Cleanup) are identical across modes — only the entry point differs.

All run artifacts are JSON and live under .prove/runs/<branch>/<slug>/:

• prd.json, plan.json — write-once inputs
• state.json — hot path, mutated only via scripts/prove-run ... (thin wrapper over claude-prove run-state ...)
• reports/<step_id>.json — write-once per step

Direct edits to state.json are blocked by a PreToolUse hook. Render human views JIT (run_state show).

---

Phase 0: Initialization

All .prove/... paths resolve from the main worktree ($MAIN_ROOT), not the orchestrator worktree. Scripts find this via git worktree list.

1. Derive slug + branch namespace from user input:

   • slug: kebab-case, max 40 chars
   • branch: feature, fix, chore (default feature) — matches the task's intent, not the git branch

2. Verify plan exists: .prove/runs/<branch>/<slug>/plan.json. If missing → stop, suggest /prove:plan --task.

3. Initialize run state (if not already done):

   scripts/prove-run init \
     --branch <branch> --slug <slug> \
     --plan .prove/runs/<branch>/<slug>/plan.json \
     --prd .prove/runs/<branch>/<slug>/prd.json
   

   init is the ONLY subcommand that requires explicit --branch/--slug (no state.json exists yet). After init, the orchestrator worktree's .prove-wt-slug.txt carries the slug and every subsequent invocation resolves it automatically.

4. Auto-scale — total step count <=3: simple mode; 4+: full mode. Record mode in the plan at creation time; orchestrator does not override.

5. Create feature branch + worktree:

   • Existing branch: AskUserQuestion header "Branch" — "Resume" / "Start Fresh"
   • New branch:

     git worktree add .claude/worktrees/orchestrator-<slug> -b orchestrator/<slug>
     printf '%s\n' "<slug>" > .claude/worktrees/orchestrator-<slug>/.prove-wt-slug.txt
     

6. Load validators from .claude/.prove.json or auto-detect per references/validation-config.md.

7. Load reporters from .claude/.prove.json reporters array. Reporter dispatch is automatic via Claude Code hooks (see references/reporter-protocol.md).

---

Phase 1: Plan Review

1. Read plan.json; walk tasks[] in order. Each task carries its own steps[], deps[], wave, optional worktree block.
2. Resolve dependencies (topological sort if needed — the planner typically emits wave-ready ordering).
3. Map validators per step from .claude/.prove.json and any step-level acceptance_criteria.
4. Render for the user: scripts/prove-run show plan

---

Phase 2: Execution Loop

Every state mutation uses scripts/prove-run — the agent-facing wrapper. Never inline python/jq/sed. Slug is auto-resolved from .prove-wt-slug.txt; if missing, prove-run hard-errors (exit 2).

Simple Mode (<=3 steps)

For each step N:

1. Start: scripts/prove-run step-start <step_id>
2. Announce: [Step <id>] Starting: <title>
3. Implement directly (no subagent delegation)
4. Run validation gate
5. Record validator outcomes:

   scripts/prove-run validator <step_id> build pass
   scripts/prove-run validator <step_id> lint pass
   scripts/prove-run validator <step_id> test pass
   

6. Commit (see Git Snapshot). Capture SHA.
7. Complete: scripts/prove-run step-complete <step_id> --commit <SHA>
8. Write report: scripts/prove-run report <step_id> --status completed --commit <SHA>
9. On validation failure → one retry. Still failing:
   • scripts/prove-run step-halt <step_id> --reason "<short>"
   • Commit WIP (orchestrator: [WIP] ...)

Full Mode (4+ steps)

Group steps into waves by dependency. Max 4 agents per wave; split larger waves.

2a. Launch Worktree Agents (parallel)

For each task in the wave:

1. Create worktree (also writes .prove-wt-slug.txt with the run slug):

   WT_PATH=$(claude-prove worktree create <slug> <task-id>)
   

2. Generate the agent prompt from JSON:

   RUN_DIR=".prove/runs/<branch>/<slug>"
   PROMPT=$(claude-prove orchestrator task-prompt \
     --run-dir "$RUN_DIR" --task-id <task-id> --project-root <project-root> --worktree "$WT_PATH")
   

3. Launch agent (worktree already exists — do NOT pass isolation: "worktree"):

   Agent(subagent_type: "general-purpose", run_in_background: true, prompt: $PROMPT)
   

4. Mark first step started:

   scripts/prove-run step-start <task-id>.<first-step-seq>
   

Create ALL worktrees first, then launch ALL agents as parallel calls in a single message.

2b. Wait for Completion

The SubagentStop hook auto-completes the step with the subagent's latest commit SHA (or halts with a diagnostic if no commits landed). You only need to intervene when:

• The hook reports halted → inspect halt_reason, decide retry or abort
• A per-step report is required (validators summary, notes, artifacts):

  scripts/prove-run report <step_id> --status completed --commit <SHA>
  

Sub-agents themselves must NOT call scripts/prove-run step-complete — the orchestrator owns step transitions and the hook is the safety net. Their contract is: record typed findings, commit, exit.

Findings backstop (per completed task). The task prompt instructs each worker to land its substantive findings as typed reasoning-log entries — hack/risk/decision/assumption, the kinds milestone-close curation mechanically sweeps. A finding that exists only in the worker's handoff message is invisible to curation. When a handoff message reports findings, verify they landed: claude-prove acb log list --run-dir "$RUN_DIR" (worker entries carry agent: "task-<task-id>"). Transcribe any missing finding yourself as a typed entry (agent: "driver", the finding prose in body, plus the type's required fields) via claude-prove acb log append --run-dir "$RUN_DIR" --file <entry.json>. Never fold worker findings into synthesis prose alone — synthesis is not swept.

2c. Validation Gate (per task)

Before review, re-run validators. Implementation agents run command validators during work; the orchestrator verifies and runs LLM validators (agents cannot spawn validation-agent).

For each completed task:

1. cd into the task worktree (slug auto-resolves from the worktree marker)
2. Run validators per phase order
3. Record each outcome via scripts/prove-run validator <step_id> <phase> <status>
4. All pass: proceed to 2d. Any fail: retry/halt protocol.

2d. Architect Review (per task)

Every task requires principal-architect approval before merge.

REVIEW LOOP (max 3 iterations per task):

1. Build review prompt:
   WT_PATH=$(claude-prove worktree path <slug> <task-id>)
   RUN_DIR=".prove/runs/<branch>/<slug>"
   REVIEW_PROMPT=$(claude-prove orchestrator review-prompt \
     --worktree "$WT_PATH" --task-id <task-id> --run-dir "$RUN_DIR" --base-branch <base-branch>)

2. Launch review:
   Agent(subagent_type: "principal-architect", prompt: $REVIEW_PROMPT)

3. Parse verdict:
   - APPROVED → exit loop, proceed to merge
   - CHANGES_REQUIRED → continue

4. Record review:
   scripts/prove-run review <task-id> rejected --notes "<summary>" --reviewer principal-architect

5. Launch fix agent in the SAME worktree (slug resolves automatically):
   Agent(
     subagent_type: "general-purpose",
     prompt: """
       Fix review findings for Task <task-id>.

       ## Findings
       <paste CHANGES_REQUIRED items>

       ## Rules
       - Fix ONLY flagged items
       - Do not refactor beyond the flags
       - Run tests after fixes
       - Commit: fix(<scope>): address review feedback (round N)
     """
   )

6. Go to step 1 (re-review)

If 3 iterations without APPROVED:
  - AskUserQuestion header "Resolution" — "Force Approve" / "Fix Manually" / "Abort"

On APPROVED:

scripts/prove-run review <task-id> approved --reviewer principal-architect

2e. Sequential Merge-Back

After all wave tasks are approved:

1. Merge each task (in order) into the orchestrator worktree:

   cd .claude/worktrees/orchestrator-<slug>
   BRANCH=$(claude-prove worktree branch <slug> <task-id>)
   git merge "$BRANCH" --no-ff -m "merge: task <id> - <name>"
   

2. Clean up task worktree + branch:

   claude-prove worktree remove <slug> <task-id>
   

3. Merge conflict: halt, ask user. No force-merge.

4. Run full test suite after the wave merges.

2f. Advance to Next Wave

Repeat 2a-2e for subsequent waves.

Validation Gate (both modes)

Run validators in phase order:

1. build, lint, test, custom — command validators, inline
2. llm — prompt validators dispatched via validation-agent subagent; see references/llm-validator-protocol.md for launch contract, diff scope, and failure handling

Validators load per references/validation-config.md.

Failure Protocol

1. scripts/prove-run validator <step_id> <phase> fail
2. Auto-fix attempt (one): send failure output, re-run validators
3. Still failing:
   • scripts/prove-run step-halt <step_id> --reason "<phase> validation failed"
   • Commit WIP (orchestrator: [WIP] <step> (validation failed))
   • Halt execution; proceed to Phase 3

Git Snapshot (both modes)

git add <files modified in this step>
git commit -m "$(cat <<'EOF'
orchestrator: step <step_id> - <step title>

Part of: <task title>
Validated: <phases that passed>

Co-Authored-By: Claude <[email protected]>
EOF
)"

Capture the SHA and pass it to scripts/prove-run step-complete --commit <SHA> and scripts/prove-run report --status completed --commit <SHA>.

---

Phase 3: Completion

Render the final status:

scripts/prove-run show state

state.json is the single source of truth. Do NOT write a report markdown file — the CLI renders it JIT. For the user-facing summary, combine:

• scripts/prove-run show state output
• git diff --stat main...orchestrator/<slug> for file changes
• Rollback recipes (linked below)

Present: status, JSON artifact paths, next action (review / fix blocker / merge). Never persist a markdown summary — it would drift from state.json.

---

Phase 4: Merge & Cleanup

Runs after user review and approval. Skip if execution halted.

4.1 Merge Gate

AskUserQuestion header "Merge & Cleanup":

• "Merge & Clean" — merge, archive, delete branch
• "Merge Only" — merge, keep artifacts
• "Skip" — manual merge (remind user to run /prove:task cleanup)

4.2 Merge to Main

git merge --no-ff orchestrator/<slug> -m "merge: <task-name>"

If another run merged first, pull/merge main first. On conflict: halt and inform the user — no force-merge.

4.3 Cleanup (if "Merge & Clean")

PROJECT_ROOT="." bash scripts/cleanup.sh --auto <slug>

Archives to .prove/archive/<date>_<slug>/, removes run directory, worktree, branch. Generates SUMMARY.md from JSON in archive.

4.4 Confirm

Present: merge SHA, archived location, skipped items. If "Skip": remind to run /prove:task cleanup <slug>.

---

Full Mode: Requirements Gathering (PRD)

Triggered by --full without an existing plan. Resolve the route first: claude-prove models routing.

• prove — gather PRD + plan via the requirements subagent, gating on two AskUserQuestion approvals (PRD, Plan) before Phase 0 (Initialization). Workflow (steps + gates + subagent dispatch): references/prd-workflow.md; PRD field shape: references/prd-template.md.
• native — follow the shared procedure in references/planning-mode-routing.md (plugin root) with these bindings:
  • Coverage — the PRD's field content plus the plan steps (references/prd-workflow.md names both).
  • Approval mapping — the ExitPlanMode approval replaces BOTH AskUserQuestion gates (PRD, Plan): one combined approval.
  • Contract — the populated prd.json and plan.json examples from skills/plan/SKILL.md "Output Artifacts" (references/prd-template.md is the prose field reference, not the artifact shape); task_id and worktree are driver-owned.
  • Landing order — after approval, in order: create .prove/runs/<branch>/<slug>/; dispatch the backfiller; write the returned prd.json + plan.json and run claude-prove run-state validate; run claude-prove run-state init --branch <b> --slug <s> --plan <plan.json> --prd <prd.json>; surface unmapped/warnings; hand off to Phase 0.

---

Error Handling

Scenario	Action
No plan found	Stop, suggest /prove:plan --task
Branch exists	AskUserQuestion: Resume / Start Fresh
Build/test fails	One retry, then step halt, commit WIP, halt
Subagent produces no changes	Log in report, skip commit, continue
Git conflict	Halt, report to user
Unclear requirements	Halt, ask user
Review deadlock (3 rounds)	AskUserQuestion: Force Approve / Fix Manually / Abort
state.json write rejected by hook	Use scripts/prove-run; never Write/Edit state.json directly
No slug resolved	Ensure you are inside a worktree with .prove-wt-slug.txt (created by claude-prove worktree create)

Interrupting a run — the Layer-1 floor

To stop in-flight work, cancel → discard → re-dispatch fresh:

1. Cancel the task subtree — claude-prove scrum task cancel <id> --cascade --reason <r> [--detail <d>]. Cascades down parent_id, stamping cancelled on the root and parent_cancelled on descendants so the abandonment is auditable.
2. Discard the run — claude-prove run-state init --overwrite --branch <b> --slug <g> .... Resets state.json so a re-dispatch starts clean instead of resuming the abandoned run.
3. Re-dispatch — start a fresh run from the corrected plan.

This is the deterministic guarantee. Native subagents are not externally signalable mid-run, so the only hard stop is the /workflows token budget + the subagent timeout — they bound and terminate the run without cooperation.

Tradeoff: cancel-and-redispatch discards in-flight work unless a synthesis reasoning-log entry was already written. The graceful Layer 2 path below recovers that work cooperatively, but is best-effort and layers ON TOP of this floor — it never replaces it, because a non-polling or stuck agent only stops at the budget/timeout. Layer 1 is always the backstop.

Layer 2 — cooperative checkpoint-interrupt (best-effort)

A best-effort graceful interrupt that lets a re-dispatch RESUME rather than restart. It sits on top of the Layer-1 floor and never replaces it.

1. Raise the cancel-flag (driver writes). Write a CANCEL file under the run dir — .prove/runs/<branch>/<slug>/CANCEL (resolve .prove/... from the main worktree, $MAIN_ROOT, not a task worktree). An optional one-line body records the reason.

   echo "<reason>" > "$MAIN_ROOT/.prove/runs/<branch>/<slug>/CANCEL"
   

2. Worker polls + hands off (subagent reads). The implementation-agent prompt emitted by claude-prove orchestrator task-prompt already instructs workers to poll this flag at natural checkpoints. When the flag is present, the worker performs a graceful handoff: write a synthesis reasoning-log entry capturing progress + next steps (claude-prove acb log append --run-dir <dir> --file <entry.json>), commit work-in-progress, and self-exit — so the re-dispatch resumes from the handoff.
3. Clear the flag before re-dispatch. Remove the CANCEL file so the resumed run is not immediately re-interrupted: rm -f "$MAIN_ROOT/.prove/runs/<branch>/<slug>/CANCEL".

A non-polling or stuck worker will not stop here; the /workflows token budget and the subagent timeout (Layer 1) remain the hard stop.

Rules

• All state mutations through scripts/prove-run — never direct-edit state.json, never inline python3 -c, jq, or sed for run state
• Never write markdown status files (PROGRESS.md, run-log.md, report.md) — views render JIT from JSON via the CLI
• Slug is resolved from .prove-wt-slug.txt; agents must not invent or pass slugs ad-hoc. If no slug, hard-error and surface the fix (create marker or run claude-prove worktree create)
• Do not force-push or rewrite history on the orchestrator branch
• Every step passes validation before proceeding
• All work on the feature branch — main stays clean
• Prefer git add <files> over git add -A

Conventions

Branches: orchestrator/<slug> (worktree: .claude/worktrees/orchestrator-<slug>). Sub-tasks: task/<slug>/<task-id> (worktree: .claude/worktrees/<slug>-task-<task-id>). Managed by claude-prove worktree.

Run directory:

.prove/runs/<branch>/<slug>/
├── prd.json          # Requirements
├── plan.json         # Task graph
├── state.json        # Live run state (mutated only via CLI)
├── state.json.lock
└── reports/
    └── <step_id>.json  # Per-step report (write-once)

Scripts

Script	Purpose
scripts/prove-run	Agent wrapper around the run_state CLI — all JSON mutations and renders go through this
claude-prove orchestrator task-prompt	Prompt for worktree implementation agents (CLI subcommand)
claude-prove orchestrator review-prompt	Review prompt for principal-architect (CLI subcommand)
claude-prove worktree	Create/remove/list/reset sub-task worktrees (writes .prove-wt-slug.txt)
scripts/cleanup.sh	Archive and remove run artifacts

References

File	Purpose
references/prd-workflow.md	Full-mode PRD + plan generation workflow
references/prd-template.md	PRD field reference
references/llm-validator-protocol.md	Prompt validator dispatch contract
references/handoff-protocol.md	Phase handoff
references/reporter-protocol.md	Reporter dispatch
references/validation-config.md	Validators (schema, auto-detect, execution order)
references/interaction-patterns.md	AskUserQuestion usage

Committing

Follow the commit skill: scopes from .claude/.prove.json, <type>(<scope>): <description>. One atomic commit per step.