Autonomous task orchestrator that auto-scales between simple mode (<=3 steps, sequential, no worktrees) and full mode (4+ steps, parallel worktrees with mandatory principal-architect review). Each run operates in its own git worktree with namespaced state (.prove/runs/<slug>/), enabling concurrent runs that consolidate at merge time. Creates feature branches, runs validation gates, commits after each step, and supports rollback via git. Use when a .prove/runs/<slug>/TASK_PLAN.md or .prove/plans/ directory exists and the user wants hands-off execution. Triggers on "orchestrate", "autopilot", "full auto", "run autonomously", "implement without me", "hands-off mode".
From provenpx claudepluginhub mjmorales/claude-prove --plugin proveThis skill uses the workspace's default tool permissions.
references/handoff-protocol.mdreferences/prd-template.mdreferences/reporter-protocol.mdscripts/generate-review-prompt.shscripts/generate-task-prompt.shscripts/manage-worktree.shscripts/update-progress.shGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Analyzes BMad project state from catalog CSV, configs, artifacts, and query to recommend next skills or answer questions. Useful for help requests, 'what next', or starting BMad.
Simple mode (<=3 steps): sequential, no worktrees, lightweight reporting. Full mode (4+ steps): parallel worktrees, architect review, full progress tracking.
Requires .prove/runs/<slug>/TASK_PLAN.md or .prove/plans/plan_X/. If neither exists, suggest /plan-task.
All .prove/... paths are rooted at the main worktree ($MAIN_ROOT), not the orchestrator worktree. Scripts resolve this via git worktree list.
Derive slug from user input (kebab-case, max 40 chars). The slug determines the run directory path -- do not derive from parsing the plan.
Create run directory: mkdir -p .prove/runs/<slug>/reports/
Validate inputs -- read .prove/runs/<slug>/TASK_PLAN.md or .prove/plans/plan_X/ to extract task name and ordered steps.
Auto-scale -- <=3 steps: simple mode. 4+ steps: full mode. Log the decision.
Create feature branch + worktree
git worktree add .claude/worktrees/orchestrator-<slug> -b orchestrator/<slug>
Create run log at .prove/runs/<slug>/reports/run-log.md:
# Orchestrator Run Log: <Task Name>
**Branch**: orchestrator/<slug>
**Worktree**: .claude/worktrees/orchestrator-<slug>
**Mode**: Simple | Full
**Started**: <ISO timestamp>
**Status**: In Progress
**Validators**: <from .claude/.prove.json or auto-detected>
**Steps**: <total count>
## Step Log
| # | Step | Status | Commit | Notes |
|---|------|--------|--------|-------|
Load validators from .claude/.prove.json or auto-detect per references/validation-config.md.
Load reporters from .claude/.prove.json reporters array. Log to run-log: Reporters: <names> or Reporters: none.
Reporter dispatch is automatic via Claude Code hooks -- the orchestrator never invokes reporters manually. See references/reporter-protocol.md.
.prove/runs/<slug>/TASK_PLAN.md > "Implementation Steps" or .prove/plans/plan_X/05_implementation_plan.md06_test_strategy.md and step-level verification itemsFor each step N:
in_progress"[Step N/<total>] Starting: <description>"Group steps into waves by dependency (independent steps = same wave). Max 4 agents per wave -- split larger waves into sub-waves.
For each wave:
For each task in the wave:
WT_PATH=$(bash scripts/manage-worktree.sh create <slug> <task-id>)
PROMPT=$(bash scripts/generate-task-prompt.sh \
.prove/runs/<slug>/TASK_PLAN.md <task-id> .prove/runs/<slug>/PRD.md <project-root> "$WT_PATH")
isolation: "worktree"):
Agent(
subagent_type: "general-purpose",
run_in_background: true,
prompt: $PROMPT
)
Create ALL worktrees first, then launch ALL agents as parallel calls in a single message.
Update progress per task:
bash scripts/update-progress.sh .prove/runs/<slug>/PROGRESS.md task-start <task-id>
Wait for all wave agents. Update progress as each finishes:
bash scripts/update-progress.sh .prove/runs/<slug>/PROGRESS.md task-complete <task-id>
Run before architect review. Implementation agents already run command validators during work, but the orchestrator re-verifies them as a gate. LLM validators run here only -- implementation agents cannot launch validation-agent subagents.
For each completed task:
cd into the task worktreebash scripts/update-progress.sh .prove/runs/<slug>/PROGRESS.md task-validated <task-id>
Every task requires principal-architect approval before merge.
REVIEW LOOP (max 3 iterations per task):
1. Generate review prompt:
WT_PATH=$(bash scripts/manage-worktree.sh path <slug> <task-id>)
REVIEW_PROMPT=$(bash scripts/generate-review-prompt.sh \
"$WT_PATH" <task-id> .prove/runs/<slug>/TASK_PLAN.md .prove/runs/<slug>/PRD.md <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 to step 4
4. Update progress:
bash scripts/update-progress.sh .prove/runs/<slug>/PROGRESS.md task-review <task-id> "CHANGES_REQUIRED"
5. Launch fix agent in the SAME worktree:
Agent(
subagent_type: "general-purpose",
prompt: """
You are fixing review findings for Task <task-id>.
## Review Findings
<paste the CHANGES_REQUIRED items from the review>
## Rules
- Fix ONLY the items flagged by the reviewer
- Do not refactor or improve code beyond what was flagged
- Run tests after fixes
- Commit with message: "fix(<scope>): address review feedback (round N)"
"""
)
6. Go to step 1 (re-review)
If 3 iterations without APPROVED:
- Log failure in PROGRESS.md
- AskUserQuestion header "Resolution", options: "Force Approve" / "Fix Manually" / "Abort"
After all wave tasks are approved:
Merge each task (in order) into the orchestrator worktree:
cd .claude/worktrees/orchestrator-<slug>
BRANCH=$(bash scripts/manage-worktree.sh branch <slug> <task-id>)
git merge "$BRANCH" --no-ff -m "merge: task <id> - <name>"
bash scripts/update-progress.sh .prove/runs/<slug>/PROGRESS.md merge <task-id> "clean"
Clean up task worktree + branch:
bash scripts/manage-worktree.sh remove <slug> <task-id>
Merge conflict: log with merge <task-id> "conflict", attempt auto-resolution for trivial conflicts, ask user for non-trivial.
Run full test suite after merging the wave.
Repeat 2a-2e for each subsequent wave.
Run all validators in phase order: build -> lint -> test -> custom -> llm, then verify expected files exist.
Validators loaded per references/validation-config.md (.claude/.prove.json or auto-detected).
For each prompt validator in .claude/.prove.json:
prompt fieldgit diff HEAD~1 (simple) or git diff <base-branch>...HEAD (full)Agent(
subagent_type: "validation-agent",
model: "haiku",
prompt: """
## Validation Prompt
{contents of the prompt markdown file}
## Changes to Validate
```diff
{git diff output}
```
## Instructions
Evaluate the changes against the validation prompt criteria.
Return your verdict in the required format (PASS/FAIL with findings).
"""
)
"orchestrator: [WIP] step N - <desc> (validation failed)"), log blocker details, halt execution, proceed to Phase 3Record all results in run-log.
git add <files modified in this step>
git commit -m "$(cat <<'EOF'
orchestrator: step N - <step description>
Part of: <task name>
Validated: <comma-separated list of checks passed>
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
Record commit SHA in run-log.
Generate .prove/runs/<slug>/reports/report.md:
# Orchestrator Report: <Task Name>
**Branch**: orchestrator/<slug>
**Mode**: Simple | Full
**Status**: Completed | Halted at Step N
**Started**: <timestamp> **Finished**: <timestamp>
**Total Commits**: N
## Summary
<What was accomplished, what remains>
## Steps
| # | Step | Status | Commit |
|---|------|--------|--------|
(mark HALTED steps with [WIP])
## Validation Summary
- Build/Tests/Lint: PASS or FAIL (include counts)
## Files Changed
<output of: git diff --stat main...HEAD>
## How to Review
- `/prove:review` or `git diff main...orchestrator/<slug>`
- `git log --oneline main..orchestrator/<slug>` -- step-by-step
- `git show <commit-sha>` -- inspect individual step
## Rollback
- Undo all: `git checkout main && git branch -D orchestrator/<slug>`
- Revert one step: `git revert <commit-sha>`
- Reset to step: `git reset --hard <commit-sha>`
## Merge
git checkout main && git merge --no-ff orchestrator/<slug>
Present: status, report location, next action (review / fix blocker / merge).
Runs after user review and approval. Skip if execution halted.
AskUserQuestion header "Merge & Cleanup", options:
/task-cleanup)git merge --no-ff orchestrator/<slug> -m "merge: <task-name>"
If another run merged first, pull/merge main first. On conflict: halt and inform user, do not force-merge.
PROJECT_ROOT="." bash scripts/cleanup.sh --auto <slug>
Archives to .prove/archive/<date>_<slug>/, removes run directory, worktree, and branch. Generates SUMMARY.md in archive.
Present: merge SHA, archived location, skipped items. If "Skip": remind to run /task-cleanup <slug>.
Maintain .prove/runs/<slug>/PROGRESS.md via scripts/update-progress.sh.
Sections: Header (name, status, branch), Overview table (wave/tasks/completed/reviewed), Task Status (per-wave checklist), Review Log, Merge Log, Issues, Test Results.
Update on: task start, task complete, review verdict, merge, wave complete, issue, final tests.
When triggered with "full auto" and no existing plan:
Derive slug, create run directory
Read project context (CLAUDE.md, README.md, docs/, recent git history)
Launch requirements-gathering subagent (user stories, acceptance criteria, non-goals, constraints, verification)
Write PRD to .prove/runs/<slug>/PRD.md using references/prd-template.md
AskUserQuestion header "PRD": "Approve" / "Request Changes"
Generate .prove/runs/<slug>/TASK_PLAN.md with wave-based task graph
Task headers use ### Task {wave}.{seq}: {name} format (e.g., ### Task 1.1: Setup config). Wave = parallel batch, seq = order within wave. The scripts generate-task-prompt.sh and generate-review-prompt.sh parse these with awk -- any other format causes silent extraction failure.
AskUserQuestion header "Plan": "Approve" / "Request Changes"
All artifacts in the run directory. Concurrent runs stay isolated.
| Scenario | Action |
|---|---|
| No plan found | Stop, suggest /plan-task |
| Branch exists | AskUserQuestion: Resume / Start Fresh |
| Build/test fails | One retry, then halt with report |
| Subagent produces no changes | Log warning, skip commit, continue |
| Git conflict | Halt, report to user |
| Unclear requirements | Halt, ask user |
| Review deadlock (3 rounds) | AskUserQuestion: Force Approve / Fix Manually / Abort |
git add <files> over git add -ABranches: orchestrator/<slug> (worktree: .claude/worktrees/orchestrator-<slug>), sub-tasks: task/<slug>/<task-id> (worktree: .claude/worktrees/<slug>-task-<task-id>). Managed by scripts/manage-worktree.sh.
Run directory:
.prove/runs/<slug>/
├── TASK_PLAN.md # Implementation plan
├── PRD.md # Product requirements (if full-auto)
├── PROGRESS.md # Live progress (full mode)
├── dispatch-state.json # Reporter dedup state
└── reports/
├── run-log.md # Audit trail
└── report.md # Final report
| Script | Purpose |
|---|---|
generate-task-prompt.sh | Prompt for worktree implementation agents |
generate-review-prompt.sh | Review prompt for principal-architect |
update-progress.sh | Updates PROGRESS.md with task/wave status |
cleanup.sh | Archives and removes run artifacts |
| File | Purpose |
|---|---|
references/prd-template.md | PRD template |
references/handoff-protocol.md | Phase handoff protocol |
references/reporter-protocol.md | Reporter dispatch protocol |
references/validation-config.md | Validation spec (schema, auto-detection, execution order) |
references/interaction-patterns.md | AskUserQuestion usage |
Follow commit skill conventions: scopes from .claude/.prove.json (fall back to directory-based), <type>(<scope>): <description> format. One atomic commit per step.