autonomous

name	autonomous
description	Run multiple phases hands-free. Chains discuss, plan, build, and verify automatically.
allowed-tools	Read, Write, Bash, Glob, Grep, Skill, Task, AskUserQuestion
argument-hint	[--from <N>] [--through <N>] [--speculative-depth <N>] [--dry-run]

STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 0 immediately.

/pbr:autonomous — Hands-Free Multi-Phase Execution

References: @references/questioning.md, @references/ui-brand.md

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► AUTONOMOUS MODE                           ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

---

Step 1: Config Gate and Parse Arguments

1. Read .planning/config.json. Check workflow.autonomous — if false or missing, display:

Autonomous mode is disabled.

Enable with: /pbr:config set workflow.autonomous true

Stop immediately. Do NOT proceed.

2. Parse $ARGUMENTS:

Argument	Meaning	Default
--from N	Start from phase N	Current phase from STATE.md
--through N	Stop after phase N	Last phase in current milestone
--speculative-depth N	How many phases ahead to plan speculatively	From config workflow.speculative_depth (default 2)
--dry-run	Show which phases would execute without doing anything	Off

3. Determine speculative planning settings:

   • Read workflow.speculative_planning from config — if false, speculative depth = 0
   • Read workflow.speculative_depth from config (default: 2)
   • If --speculative-depth N provided, override config value
   • Store as speculativeDepth for use in Step 3

4. Read gates.checkpoint_auto_resolve from config (default: "none"). Values:

   • "none": STOP on all checkpoints (user must resolve)
   • "verify-only": Auto-resolve checkpoint:human-verify (proceed after confidence-gate passes), STOP on checkpoint:human-action
   • "verify-and-decision": Auto-resolve verify + decision checkpoints, STOP on checkpoint:human-action
   • "all": Auto-resolve all checkpoints (dangerous — only for fully automated pipelines) Store as checkpointResolveLevel for use in Step 3c.

5. Read .planning/STATE.md to determine current phase (used as default for --from).

6. Read .planning/ROADMAP.md to build phase list for current milestone.

7. CRITICAL (hook-enforced): Write .active-skill NOW. Write .planning/.active-skill with the content autonomous using the Write tool. This registers the autonomous session with the workflow enforcement hooks. Child Skill() calls (plan, build, review) will overwrite this with their own skill name during execution and should restore or re-write it — but the orchestrator owns the initial write and final cleanup.

8. Filter to phases from --from through --through that are not yet complete.

9. If no phases to execute, display: "All phases in range are complete." and stop.

If --dry-run: Display the phase list with planned actions per phase, then stop without executing.

DRY RUN — Would execute:
  Phase 3 (data-layer): discuss -> plan -> build -> verify
  Phase 4 (api-endpoints): plan -> build -> verify  (CONTEXT.md exists, skip discuss)
    [speculative: plan Phase 5 during Phase 4 build]
  Phase 5 (frontend): discuss -> plan -> build -> verify
Speculative depth: 2

When speculativeDepth > 0, append the speculative depth value and annotate phases where speculative planning would occur. When speculativeDepth == 0 (speculative_planning is false), omit the speculation lines.

---

Step 2: Dynamic Phase Detection

Before each phase iteration:

1. Re-read .planning/ROADMAP.md (catches inserted/removed phases between iterations)
2. Rebuild the phase list for the current milestone
3. Compare with previous iteration's list — if changed, log:

   Phase list changed: {diff}. Adjusting execution order.
   

4. Skip phases already marked as verified/complete in ROADMAP.md

Verification tracking: Initialize two counters at the start of the autonomous run:

• phases_verified_full = 0 — count of phases that received full /pbr:review verification
• phases_verified_total = 0 — count of phases that completed verification (any type)
• Read verification.min_full_percent from config (default: 30)
• Calculate full_verify_interval: if min_full_percent > 0, compute Math.floor(100 / min_full_percent) (e.g., 30% → every 3rd phase). If 0, set to Infinity (never force full).

---

Step 3: Phase Loop

For each remaining phase N:

3a. Discuss Phase (conditional)

• Check if .planning/phases/{NN}-{slug}/CONTEXT.md exists -- if so, skip (decisions already captured)
• Count requirements for this phase: parse the ### Phase {N}: section in ROADMAP.md, count bullet lines under **Requirements:**
• Auto-skip discuss (no Skill() call) when ANY of these are true:
  • CONTEXT.md already exists
  • Requirement count is 0 or 1 (well-specified, no gray areas worth discussing)
  • --auto mode is active AND all requirements are simple factual statements (no [NEEDS DECISION] markers)
  • Log: Phase {N}: auto-skipping discuss ({count} requirement(s), well-specified)
• Run discuss only when: CONTEXT.md missing AND requirement count >= 2 AND at least one requirement contains ambiguous language or [NEEDS DECISION]
  • Invoke: Skill({ skill: "pbr:discuss", args: "{N} --auto" })
  • The --auto flag triggers smart discuss batching: collect ALL gray areas across the phase requirements and present them in a single batch for resolution, rather than asking one at a time.

3b. Plan Phase

• Check if .planning/phases/{NN}-{slug}/PLAN-*.md files exist
• If NOT exists:
  • Invoke: Skill({ skill: "pbr:plan", args: "{N} --auto" })
• If plans exist (from speculative planning or prior run): skip planning.
  • Log: Phase {N}: plans already exist (speculative or prior) -- skipping plan step.
  • Note: even if planning is skipped, the 3b-validate gate below will verify plans are validated.
• If Skill returns failure: stop autonomous loop, display error, suggest: /pbr:plan {N}

3b-validate. Plan Validation Gate (always runs)

CRITICAL -- DO NOT SKIP. No phase may enter build without passing plan validation.

1. Check if .planning/phases/{NN}-{slug}/.plan-check.json exists.
2. If it exists: read it and verify status === "passed".
   • If passed: log Phase {N}: plan validation passed and proceed to 3c.
   • If not passed: log Phase {N}: plan validation failed -- re-running plan checker
     • Invoke: Skill({ skill: "pbr:plan", args: "{N} --audit --auto" })
     • Re-check .plan-check.json. If still not passed: stop autonomous loop. Display: BLOCKED: Phase {N} plans failed validation. Fix issues with /pbr:plan {N} --audit
3. If .plan-check.json does NOT exist (plans came from speculative planner which bypassed plan-checker):
   • Log: Phase {N}: no .plan-check.json -- running plan checker on existing plans
   • Invoke: Skill({ skill: "pbr:plan", args: "{N} --audit --auto" })
   • After completion, re-check .plan-check.json. If missing or failed: stop autonomous loop with same BLOCKED message.

3c. Build Phase

• Check if all PLAN files have corresponding SUMMARY files
• If incomplete:
  • Invoke: Skill({ skill: "pbr:build", args: "{N} --auto" })
• If all SUMMARYs exist: skip build
• Checkpoint handling (uses checkpointResolveLevel from Step 1):
  • checkpoint:human-action: ALWAYS stop (regardless of config). Display: "Human action required in Phase {N}. Complete the action, then resume with: /pbr:autonomous --from {N}"
  • checkpoint:human-verify: If checkpointResolveLevel is "verify-only", "verify-and-decision", or "all": auto-resolve by running confidence gate. Otherwise STOP.
  • checkpoint:human-decision: If checkpointResolveLevel is "verify-and-decision" or "all": auto-resolve with default option. Otherwise STOP.
  • Any other checkpoint type: If checkpointResolveLevel is "all": auto-resolve. Otherwise STOP.

Error Classification

Before retrying any build failure, classify the error:

Transient errors (auto-fixable -- clean up then retry):

• Stale .active-skill: file exists but session that wrote it is gone (check via ps or absence of matching .session-*.json)
• Stale .active-agent: same pattern
• Git lock file: .git/index.lock or .git/MERGE_HEAD left by a killed process
• EBUSY/EACCES file lock errors on Windows

Permanent errors (do not retry):

• Missing PLAN-*.md files
• Syntax errors in plan YAML frontmatter
• Executor returned checkpoint:human-action
• Missing dependency phase SUMMARY.md (means prior phase incomplete)

CRITICAL — DO NOT DEBUG INLINE: When build or test failures occur, you MUST spawn a pbr:debugger agent via Task(). Do NOT read source files, edit modules, or run tests directly in orchestrator context. Inline debugging consumes main context and violates PBR's delegation principle.

If verification (Step 3d) finds test failures:

• Spawn: Task({ subagent_type: "pbr:debugger", prompt: "Phase {N}: {failure description}. Fix the failing tests." })
• Do NOT use Edit/Write on source files (non-.planning/ files) from the orchestrator

Classification procedure (Step 3c on failure):

1. Read the Skill() return value / error message
2. Check for known transient patterns (lock files, stale signal files)
3. Read autonomous.max_retries from config (default: 2)
4. Read autonomous.error_strategy from config (default: 'retry'): 'stop' | 'retry' | 'skip'

• If Skill returns failure: a. Classify error (see Error Classification above) b. If transient error:
  • Auto-fix: remove stale signal file OR remove .git/index.lock via Bash
  • Increment retry counter for this phase (start at 0)
  • If retry counter < autonomous.max_retries: retry Skill({ skill: "pbr:build", args: "{N} --auto" })
  • If retry counter >= autonomous.max_retries: apply error_strategy (see below) c. If permanent error: apply error_strategy immediately (no retries) d. error_strategy application:
  • stop (safe default): stop autonomous loop, display error, suggest /pbr:build {N}
  • retry: already handled above (retry up to max_retries, then stop)
  • skip: log warning "Skipping Phase {N} due to unrecoverable error", continue to Phase N+1 e. On transient auto-fix: log: Auto-fixed transient error in Phase {N}: {description}. Retry {n}/{max}.

3c-speculative. Speculative Planning (during build)

Gate: Only execute this sub-step if ALL conditions are met:

• speculativeDepth > 0 (from Step 1.3 -- speculative_planning is true AND depth > 0)
• Phase N build was just invoked (not skipped because SUMMARYs exist)

Procedure:

1. Determine candidate phases for speculative planning:

   • Start from N+1, up to N+speculativeDepth
   • For each candidate phase C: a. Skip if C is beyond --through limit b. Skip if C already has PLAN-*.md files c. Skip if C already has CONTEXT.md AND the CONTEXT.md was NOT auto-generated d. Read ROADMAP.md ### Phase C: section, extract **Depends on:** line e. Parse dependency phase numbers (same regex as build-dependency.js: /Phase\s+(\d+)/gi) f. For each dependency D: check if D is completed (has VERIFICATION.md) OR is currently building (D == N) g. If ALL dependencies are satisfied or in-flight: C is a candidate h. If ANY dependency is neither completed nor in-flight: skip C AND all phases after C

2. For each candidate phase C (in order):

   • Check agent budget: if current concurrent agents >= parallelization.max_concurrent_agents, skip remaining candidates
   • Log: Speculative planning: Phase {C} (while Phase {N} builds)
   • Invoke planner as background task:

     Task({
       subagent_type: "pbr:planner",
       model: "sonnet",
       run_in_background: true,
       prompt: "Plan Phase {C} --speculative. Phase goal from ROADMAP.md. Write plans to .planning/phases/{CC}-{slug}/. This is a speculative plan -- Phase {N} is still building. Do NOT write .active-skill. Do NOT update STATE.md."
     })
     

   • After dispatching: add expected plan file paths to .autonomous-state.json speculative_plan_paths["{C}"]. Paths use pattern .planning/phases/{CC}-{slug}/PLAN-*.md. At dispatch time, store the glob pattern as-is; it will be resolved to actual paths after the planner completes.
   • Plans are written directly to the normal phase directory (NOT .speculative/) per locked decision #2

3. After Phase N build completes (the Skill() call returns), proceed to staleness check in 3c-stale below.

Important constraints:

• Plan-only: Do NOT invoke discuss for speculative phases (locked decision #2). The planner only needs ROADMAP + CONTEXT.md.
• Exception: if a phase-level CONTEXT.md already exists from a prior manual /pbr:discuss-phase, that is fine -- the planner will use it.
• Do NOT speculate on phases that already have plans.
• Respect max_concurrent_agents: count the build executor as 1 agent. Speculative planners share the remaining budget.
• After dispatching speculative Task()s, do NOT write .active-skill — the orchestrator already owns it for the active Phase {N} build. The speculative planner receives --speculative and will skip signal file writes.
• Individual Agent Calls: Each speculative planner MUST be dispatched as a separate Task() tool call. Do NOT describe multiple spawns in prose (e.g., "launched 3 planners"). Each separate Task() call gets its own colored badge and independent status tracking in the Claude Code UI. Multiple Task() calls in one message still run concurrently.

3c-stale. Staleness Check (after build completes)

Gate: Only execute if speculative planners were dispatched in 3c-speculative for this phase N.

Note: When speculative plans are replaced (re-planned), the checkpoint manifest from a prior speculative run (if any) becomes stale. Re-initialize it immediately after re-planning so that the build skill does not try to skip plans that no longer exist.

Procedure:

1. Wait for any outstanding speculative planner tasks to complete (they run in background). 1.5. Validate speculative plans: For each speculatively-planned phase C that completed successfully:
   • Check if .planning/phases/{CC}-{slug}/.plan-check.json exists (it will not -- raw planner does not write it)
   • Run plan-checker on the speculative plans:

     Task({
       subagent_type: "pbr:plan-checker",
       model: "sonnet",
       prompt: "Validate plans in .planning/phases/{CC}-{slug}/. Read all PLAN-*.md files. Write .plan-check.json to the phase directory. Phase goal: {goal from ROADMAP}. Check structural completeness, task elements, dependency correctness."
     })
     

   • Log: Speculative plans for Phase {C}: validated ({status})
   • If plan-checker finds blockers: log warning but do NOT stop the loop (plans will be re-validated at 3b-validate before build)
   • Design note: Speculative planning uses raw Task(subagent_type: "pbr:planner") + separate plan-checker rather than Skill("pbr:plan") because: (a) Skill() writes .active-skill which conflicts with the orchestrator's ownership, (b) Skill() updates STATE.md which is incorrect for speculative phases, (c) the raw planner + separate checker is more appropriate for speculative context where state should not be mutated. The 3b-validate gate provides the authoritative check before build.
2. Read Phase N's SUMMARY.md files. For each SUMMARY.md, extract deviations from YAML frontmatter.
3. Compute total deviation count across all SUMMARY files for Phase N.
4. If total deviations == 0: speculative plans are fresh -- no action needed. Log: Phase {N} build: 0 deviations -- speculative plans for Phase(s) {list} are valid.
5. If total deviations > 0: check each speculatively-planned phase C: a. Read ROADMAP.md dependencies for Phase C b. If Phase C depends on Phase N (directly):
   • Delete the speculative PLAN-*.md files for Phase C
   • Log: Phase {N} had {count} deviation(s) -- re-planning Phase {C}
   • Re-invoke planner synchronously:

     Skill({ skill: "pbr:plan", args: "{C} --auto" })
     

   • Verify re-plan validation: After Skill() returns, confirm .plan-check.json exists in the phase directory with status: "passed". The /pbr:plan skill writes this artifact. If missing (edge case -- plan skill failed to write artifact):
     • Run: Task({ subagent_type: "pbr:plan-checker", model: "sonnet", prompt: "Validate plans in .planning/phases/{CC}-{slug}/. Write .plan-check.json." })
     • Log: Phase {C}: re-plan validation completed
   • Re-initialize checkpoint manifest for Phase C with the new plan IDs:

     # Collect new PLAN-*.md filenames from .planning/phases/{CC}-{slug}/
     # Extract plan IDs from frontmatter (plan: field) of each new PLAN file
     pbr-tools checkpoint init {CC}-{slug} --plans "{comma-separated plan IDs}"
     

     This ensures the build skill starts with accurate plan tracking when Phase C is built.
   • Note: The re-plan via /pbr:plan already includes plan-checker validation (Step 6 of the plan skill). The explicit check above is a safety net -- if the plan skill's checker was skipped due to depth profile, the autonomous mode enforces it independently. c. If Phase C does NOT depend on Phase N: plans are still valid, no action needed.

Important: The staleness check uses deviation count from SUMMARY.md frontmatter (locked decision #3). Any deviation > 0 triggers re-plan for dependent phases. This is intentionally simple -- no partial staleness analysis.

STOP — Build and staleness checks are done. NOW EXECUTE Step 3d-pre (validate) and Step 3d (verify). Do NOT skip to Step 3e. Every phase MUST be verified before completion.

3d-pre. Validate Phase (conditional)

Gate: Run only if ALL of these are true:

• workflow.validate_phase is true in config (default: true — read via pbr-tools config get workflow.validate_phase)
• No VALIDATION.md with status: passed already exists in the phase directory

If gate passes:

• Display: ◆ Running validate-phase for Phase {N}...
• Invoke: Skill({ skill: "pbr:validate-phase", args: "{N} --auto" })
• If validate-phase returns gaps (impl_bugs: true in VALIDATION.md frontmatter):
  • Attempt gap closure: Skill({ skill: "pbr:build", args: "{N} --gaps-only --auto" })
  • Re-run validate: Skill({ skill: "pbr:validate-phase", args: "{N} --auto" })
  • If gaps persist: stop loop, display gaps, suggest manual intervention (same hard stop as verification gaps).
• If validate-phase passes or toggle is false: continue to step 3d.

STOP — Validation done. NOW EXECUTE Step 3d below. Do NOT skip to Step 3e.

3d. Verify Phase (Lightweight-First)

CRITICAL — DO NOT SKIP THIS STEP. The LLM historically skips verification under cognitive load after processing the long build section. Every phase MUST be verified before proceeding to 3e. Without VERIFICATION.md, milestone completion, progress tracking, and dependency checks all break. Execute ALL sub-steps below.

• Check if VERIFICATION.md exists with status: passed — if yes, skip to 3e.
• Lightweight verification first (avoid spawning heavyweight verifier agent):

  1. CLI-first SUMMARY validation: For each plan in the phase, run:

     pbr-tools verify summary ".planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md" --check-files 3
     

     Parse JSON result: checks.files_created.missing (claimed files that don't exist), checks.commits_exist (referenced SHAs valid), checks.self_check (executor self-check status). If ANY summary has passed: false, fail the confidence gate.

  2. Compute aggregate completion from SUMMARY frontmatter completion percentage (average across all plans).

  3. CLI commit verification: For all commit SHAs found in SUMMARY files:

     pbr-tools verify commits {space-separated-hashes}
     

     If valid: false for any commit, flag as missing evidence.

  4. Test result caching: Before running the test suite: a. Compute cache key: the current phase directory path (e.g., .planning/phases/23-slug) b. Check .planning/.test-cache.json for a fresh result (TTL: 60 seconds):

     • If a fresh result exists (passed: true, timestamp within 60s): use it directly — do NOT re-run tests
     • Log: Tests: cached result used (age: {age}s) c. If no fresh cache: detect and run test suite (npm test, pytest, make test, etc.)
     • On completion: write result to .planning/.test-cache.json with the phase directory as key
     • Log: Tests: ran fresh, result cached d. Use the result (cached or fresh) for the confidence gate check in sub-step 5 Note: This test run serves as both the confidence gate signal AND the regression gate. If tests fail, this is a regression — delegate to debugger agent per the CRITICAL marker above. 4.5. CLI artifact + wiring check: For each plan in the phase, run the CLI verify commands:

     pbr-tools verify artifacts ".planning/phases/{NN}-{slug}/{plan_id}-PLAN.md"
     pbr-tools verify key-links ".planning/phases/{NN}-{slug}/{plan_id}-PLAN.md"
     

     Parse JSON results: if all_passed: false (artifacts) or all_verified: false (key-links), fail the confidence gate and fall through to full verification. As a supplementary check, for each file in SUMMARY.md key_files (excluding tests and docs), verify at least one require()/import reference exists elsewhere in the project. Use: grep -rl "{basename}" --include="*.js" --include="*.cjs" --include="*.ts" --include="*.md" . | grep -v node_modules | grep -v "{key_file_itself}". If ANY key file is orphaned, fail the confidence gate.

  5. Verification depth selection (round-robin enforcement):

     • Increment phases_verified_total
     • Determine if this phase needs full verification:
       • If phases_verified_total % full_verify_interval === 0: this phase MUST get full verification
       • If this is the LAST phase in the milestone: MUST get full verification
       • If ANY signal failed (completion < 90%, SHAs missing, tests fail, wiring orphan): MUST get full verification
       • Otherwise: confidence-gate is sufficient

  6. If confidence-gate is sufficient (all signals pass AND not a forced-full phase):

     • Display: Phase {N}: confidence gate passed — lightweight verification (full verify on phase {next_full_phase})
     • Increment phases_verified_total but NOT phases_verified_full
     • Write VERIFICATION.md with verification_type: confidence-gate in frontmatter
     • Continue to 3e

CRITICAL — DO NOT SKIP FULL VERIFICATION WHEN REQUIRED. The round-robin enforcement exists because the LLM historically skips full verification under cognitive load. If this phase is marked for full verification, you MUST invoke the review skill.

7. If full verification required (forced-full phase OR any signal failed):
   • Display: Phase {N}: FULL VERIFICATION (enforced — {reason})
   • Invoke: Skill({ skill: "pbr:review", args: "{N} --auto" })
   • Increment both phases_verified_full and phases_verified_total
   • If verification finds gaps:
     • Attempt gap closure: Skill({ skill: "pbr:plan", args: "{N} --gaps --auto" })
     • Then retry build: Skill({ skill: "pbr:build", args: "{N} --gaps-only --auto" })
     • Then retry verify: Skill({ skill: "pbr:review", args: "{N} --auto" })
     • If gaps persist after one retry: stop loop, display gaps, suggest manual intervention.
   • If passes: continue to 3e

CRITICAL — DO NOT FIX FAILURES INLINE: If test failures are detected, delegate to a debugger agent. Do NOT edit source files in orchestrator context.

3e. Phase Complete

• Log: "Phase {N} complete. Moving to Phase {N+1}."

• Git branch (conditional): If git.branching: "phase" in .planning/config.json:

  1. Read git.phase_branch_template from config (default: pbr/phase-{phase}-{slug})
  2. Expand template: {phase} -> zero-padded phase number (e.g., 23), {slug} -> phase slug from ROADMAP
  3. Run git checkout -b {branch_name} to create branch from current HEAD
  4. If that fails with "already exists": run git checkout {branch_name} instead
  5. Log: Branch: {branch_name}
  6. Write branch name to .autonomous-state.json under branch_state["{N}"] CRITICAL — DO NOT SKIP: Update STATE.md current_phase via CLI NOW. Do not skip.

• Update STATE.md current_phase to next phase via CLI:

  pbr-tools state update current_phase {N+1}
  

• Update .autonomous-state.json with phase error metrics:

  # Read current state, merge phase N error/retry data, write back
  node -e "
    const fs=require('fs');
    const f='.planning/.autonomous-state.json';
    const s=fs.existsSync(f)?JSON.parse(fs.readFileSync(f,'utf8')):{};
    s.errors=s.errors||{}; s.retries=s.retries||{};
    // phase_errors and phase_retries are substituted by orchestrator
    if('{phase_errors}') s.errors['{N}']='{phase_errors}';
    if('{phase_retries}'!='0') s.retries['{N}']=parseInt('{phase_retries}');
    s.timestamp=new Date().toISOString();
    fs.writeFileSync(f,JSON.stringify(s,null,2));
  "
  

  Where {phase_errors} and {phase_retries} are the accumulated error description and retry count tracked during Step 3c for phase N. If phase N had no errors, omit the errors entry.

• Update root MILESTONE.md — If MILESTONE.md exists at project root, overwrite it with updated phase statuses from ROADMAP.md progress table for the current milestone. If it doesn't exist, skip silently.

• Proceed to 3e-ci (CI Verification) before starting next phase.

• Check milestone boundary: if this was the last phase in the current milestone:

  1. Log: All phases in milestone complete. Invoking milestone completion...
  2. Invoke: Skill({ skill: "pbr:milestone", args: "complete --auto" })
  3. If the milestone skill succeeds:
     • Check if there are more milestones with unexecuted phases in ROADMAP.md
     • If yes and within --through range: continue to next milestone's first phase
     • If no more milestones or beyond --through: stop loop
     • Display: "Milestone archived. {next action}"
  4. If the milestone skill fails: stop loop. Display: "Milestone completion failed. Run /pbr:milestone complete manually."

3e-ci. CI Verification (after phase complete)

Gate: Run only if git commits were pushed during this phase's build step.

1. Run gh run list --limit 3 to check CI status
2. Parse the output for the most recent run:
   • If status is "in_progress" or "queued": run gh run watch {run_id} --exit-status with a 5-minute timeout
   • If status is "completed" and conclusion is "success": log CI passed for Phase {N} and continue
   • If status is "completed" and conclusion is "failure":
     • Display: CI FAILED for Phase {N}. Run ID: {run_id}
     • Display the failed jobs: gh run view {run_id} --log-failed | head -40
     • Stop autonomous loop. Suggest: /pbr:debug {N} or manual CI investigation
3. If gh CLI is not available or errors: log warning gh CLI unavailable — skipping CI check and continue (do not block)

---

Notification Throttling

During autonomous execution, suppress routine status output to reduce noise:

• Suppress: Hook additionalContext messages that repeat the same content within 60 seconds (e.g., repeated "context budget" warnings)
• Suppress: Per-task progress updates during build — only show per-plan completion
• Keep: Phase-level status changes (discussing → planned → building → verified)
• Keep: Error/warning messages (always display)
• Keep: Speculative planning status (first mention only)
• Batch: When multiple speculative planners complete between phases, report them in a single line: "Speculative plans ready: Phase {list}"

Target: <100 status lines per 7-phase autonomous session (excluding agent output).

---

Step 4: Completion

CRITICAL — DO NOT SKIP: Delete .planning/.active-skill if it exists. This must happen on all paths (success, partial, and failure) before displaying the completion summary.

Display summary:

PLAN-BUILD-RUN > AUTONOMOUS COMPLETE

Phases completed: {list}
Phases remaining: {list}
Speculative plans used: {count} (re-planned: {count})
Total time: {elapsed}
Errors encountered: {count}
Errors auto-fixed: {count} | Phases skipped: {count}
Test cache hits: {count}
Verification: {phases_verified_full}/{phases_verified_total} phases fully verified ({pct}%)
Threshold: {min_full_percent}% required
Status: {PASS if pct >= min_full_percent, else WARN}

If all phases completed successfully:

All {count} phases completed successfully.

Clean up .planning/.autonomous-state.json on successful completion.

---

Hard Stops (autonomous loop MUST stop)

The autonomous loop MUST stop immediately when any of these conditions occur:

1. human-action checkpoint encountered — NEVER auto-resolve these
2. Gap closure fails on retry — gaps persist after one attempt
3. Build fails after exhausting retries — error_strategy is 'stop' or retries exhausted
4. Milestone boundary reached — last phase verified AND milestone archived (or archive failed)
5. --through limit reached — user-specified phase limit hit
6. Context budget > 70% — suggest: /pbr:pause then resume in new session with /pbr:autonomous --from {N}

On ALL hard stops: delete .planning/.active-skill before displaying the stop message.

---

Error Recovery

Save execution state to .planning/.autonomous-state.json after each phase:

{
  "current_phase": 4,
  "completed_phases": [2, 3],
  "speculative_plans": {"5": "pending", "6": "pending"},
  "speculative_plan_paths": {"5": [".planning/phases/05-slug/PLAN-01.md"]},
  "branch_state": {"2": "pbr/phase-02-slug", "3": "pbr/phase-03-slug"},
  "failed_phase": null,
  "error": null,
  "errors": {},
  "retries": {},
  "started_at": "2026-01-15T10:00:00Z",
  "timestamp": "2026-01-15T10:30:00Z"
}

Where:

• "errors": object mapping phase number to error description, e.g. {"4": "stale .active-skill"}

• "retries": object mapping phase number to retry count, e.g. {"4": 1}

• "speculative_plan_paths": maps phase number to list of plan file paths written by speculative planner

• "branch_state": maps phase number to git branch name created for that phase build

• On --from N: check .autonomous-state.json for prior run context

  • Re-write .planning/.active-skill with content autonomous when resuming (the prior session's .active-skill may be stale or missing).

• Display prior run info if available: "Resuming from prior autonomous run. Last completed: Phase {N}."

• Clean up .autonomous-state.json on successful completion of all phases

---

Reference: skills/shared/commit-planning-docs.md -- if planning.commit_docs is true, commit modified .planning/ files.

---

Anti-Patterns

1. DO NOT skip the config gate — workflow.autonomous must be true
2. DO NOT auto-resolve human-action checkpoints — always stop
3. DO NOT retry more than once on gap closure or build failure
4. DO NOT continue past milestone boundaries — user must explicitly archive
5. DO NOT read SKILL.md files into context — use Skill() tool for delegation
6. DO NOT modify STATE.md directly — use CLI commands
7. DO NOT ignore dynamic phase detection — always re-read ROADMAP.md between iterations
8. DO NOT leave .active-skill set after autonomous mode exits — always clean up on every exit path