@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/skills/forensics/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: forensics
+description: "Post-mortem investigation for failed or stuck workflows. Analyzes git history and planning artifacts."
+allowed-tools: Read, Bash, Glob, Grep, Write, AskUserQuestion
+argument-hint: "[description of what went wrong]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it.**
+
+# /pbr:forensics — Post-Mortem Investigation
+
+Read-only investigation for failed or stuck workflows. Analyzes git history, `.planning/` artifacts, and file system state to detect anomalies. Writes a diagnostic report. Does NOT modify project files.
+
+## Step 0 — Banner
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► FORENSICS                                  ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Step 1 — Get Problem Description
+
+If `$ARGUMENTS` is empty, ask: "What went wrong? Describe the issue — e.g., 'autonomous mode got stuck on phase 3', 'execute-phase failed silently', 'commits seem wrong'."
+
+## Step 2 — Gather Evidence
+
+Collect data from all available sources. Missing sources are fine — adapt.
+
+### 2a. Git History
+
+```bash
+git log --oneline -30
+git log --format="%H %ai %s" -30
+git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
+git status --short
+git diff --stat
+```
+
+Record: commit timeline, most-edited files, uncommitted changes.
+
+### 2b. Planning State
+
+Read if they exist: STATE.md, ROADMAP.md, config.json. Extract current phase, last session, blockers.
+
+### 2c. Phase Artifacts
+
+For each phase in `.planning/phases/*/`, check which artifacts exist vs expected (PLAN, SUMMARY, VERIFICATION, CONTEXT, RESEARCH).
+
+### 2d. Worktree State
+
+```bash
+git worktree list
+```
+
+Check for orphaned worktrees from crashed agents.
+
+## Step 3 — Detect Anomalies
+
+### Stuck Loop Detection
+Same file in 3+ consecutive commits within a short time window. HIGH confidence if commit messages are similar.
+
+### Missing Artifact Detection
+Phase appears complete (has commits, past in roadmap) but lacks PLAN, SUMMARY, or VERIFICATION.
+
+### Abandoned Work Detection
+Large gap between last commit and now, with STATE.md showing mid-execution.
+
+### Crash/Interruption Detection
+Uncommitted changes + STATE.md active + orphaned worktrees.
+
+### Scope Drift Detection
+Recent commits touch files outside current phase's expected scope (from PLAN.md).
+
+### Test Regression Detection
+Commit messages containing "fix test", "revert", or re-commits of test files.
+
+## Step 4 — Generate Report
+
+```bash
+mkdir -p .planning/forensics
+```
+
+Write to `.planning/forensics/report-{YYYYMMDD-HHMMSS}.md`:
+
+```markdown
+# Forensic Report
+
+**Generated:** {ISO timestamp}
+**Problem:** {user's description}
+
+## Evidence Summary
+
+### Git Activity
+- **Last commit:** {date} — "{message}"
+- **Commits (last 30):** {count}
+- **Uncommitted changes:** {yes/no}
+- **Active worktrees:** {count}
+
+### Planning State
+- **Current phase:** {N} — {name} ({status})
+- **Last session:** {date}
+- **Blockers:** {list or "none"}
+
+### Artifact Completeness
+| Phase | PLAN | SUMMARY | VERIFICATION | Status |
+|-------|------|---------|-------------|--------|
+| {N} | {Y/N} | {Y/N} | {Y/N} | {complete/incomplete} |
+
+## Anomalies Detected
+
+### {Anomaly Name}
+**Confidence:** {HIGH/MEDIUM/LOW}
+**Evidence:** {specific data points}
+**Impact:** {what this caused}
+**Recommendation:** {what to do}
+
+## Recommendations
+
+1. {Prioritized action items}
+```
+
+## Step 5 — Present Findings
+
+Display a summary of findings inline, point to the full report on disk:
+
+```
+Report: .planning/forensics/report-{timestamp}.md
+
+Anomalies found: {count}
+  - {anomaly 1}: {brief}
+  - {anomaly 2}: {brief}
+
+Recommended: {top action item}
+```
+
+Optionally offer to create a GitHub issue with the findings.
+
+## Anti-Patterns
+
+1. DO NOT modify project files — forensics is read-only
+2. DO NOT spawn subagents — run everything inline
+3. DO NOT guess — base all findings on evidence
+4. DO NOT report anomalies without evidence and confidence levels

package/plugins/pbr/skills/health/SKILL.md

@@ -2,6 +2,7 @@
 name: health
 description: "Check planning directory integrity. Find and fix corrupted state."
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--repair]"
 ---
 
 **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 ~7,600 tokens. Begin executing Step 1 immediately.**
@@ -20,135 +21,46 @@ Then proceed to Step 1.
 
 # /pbr:health — Planning Directory Diagnostics
 
-You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes. You never auto-repair anything.
+You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes.
 
 This skill runs **inline**. It is read-only by default, but offers an optional **auto-fix** flow for common corruption patterns (see the Auto-Fix section below).
 
----
+## References
 
-## How Checks Work
+- `references/questioning.md` — Questioning philosophy for diagnostic probing
+- `references/ui-brand.md` — Status symbols, banners, checkpoint boxes
 
-Each check follows the common pattern. Read `skills/health/templates/check-pattern.md.tmpl` for the shared execution flow: target files, validate against rules, classify as PASS/FAIL/WARN/INFO, and record the result with a fix suggestion for any failures.
+## Argument Parsing
 
-Read `skills/health/templates/output-format.md.tmpl` for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
+Check if the user passed `--repair`:
+- `--repair`: Skip the AskUserQuestion prompt in the Auto-Fix section and automatically apply ALL fixes (equivalent to selecting "Fix all"). Still create backups before any destructive operations.
+- No flag: Use the interactive AskUserQuestion flow as described below (default behavior).
 
 ---
 
-## Checks
+## How Checks Work
 
-Run all 10 checks in order. Collect results and present them together at the end.
+Health checks are now CLI-driven via `verify health`. The check-pattern template (`${CLAUDE_SKILL_DIR}/templates/check-pattern.md.tmpl`) describes the classification model (PASS/FAIL/WARN/INFO) used by the CLI internally.
 
-### Check 1: Structure
+Read `${CLAUDE_SKILL_DIR}/templates/output-format.md.tmpl` for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
 
-Validate `.planning/` exists with required scaffolding: `STATE.md`, `config.json`, `ROADMAP.md`.
+---
 
-- If `.planning/` is missing: FAIL the entire health check immediately. Display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
+## Checks
 
-No .planning/ directory found.
+Run all health checks via the CLI:
 
-**To fix:** Run `/pbr:begin` to initialize.
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js verify health
 ```
-Stop all further checks.
-- PASS: All three required files exist
-- FAIL: List each missing file — "Run `/pbr:begin` to re-initialize, or create the file manually."
-
-### Check 2: Config Validity
-
-Parse `.planning/config.json` as JSON. Check required fields: `version`, `depth`. Check recommended fields: `features`, `models`.
-
-- PASS: Valid JSON with all required fields
-- FAIL (parse error): Report the parse error message — "Open the file and correct the syntax."
-- FAIL (missing required field): Report which field — "Add the field to config.json."
-- WARN (missing recommended field): Report which field — "This may cause issues with some skills."
-
-### Check 3: Phase Consistency
-
-Compare directories in `.planning/phases/` against phases defined in `ROADMAP.md`.
-
-- PASS: Every directory matches a ROADMAP.md phase; no started phases are missing directories
-- FAIL (orphan directory): Directory exists but not in ROADMAP.md — "Add to ROADMAP.md or remove the directory."
-- FAIL (missing directory): ROADMAP.md lists phase as in-progress but directory missing — "Create the directory or update ROADMAP.md."
-- Note: Future phases without directories are normal (not a failure).
-
-### Check 4: Plan/Summary Pairing
-
-Glob all `PLAN*.md` and `SUMMARY*.md` in `.planning/phases/`. Match by plan number. A PLAN without SUMMARY is normal unless the phase is marked complete.
-
-- PASS: All pairings valid, no orphaned summaries
-- FAIL (orphaned summary): SUMMARY has no matching PLAN — "Verify and remove or re-pair."
-- WARN (missing summary in complete phase): Phase marked complete but plan has no SUMMARY — "Execute with `/pbr:build` or mark phase incomplete."
-
-### Check 5: STATE.md Accuracy
-
-Extract current phase, plan identifier, and progress percentage from `STATE.md`. Verify each against the file system.
-
-- PASS: All STATE.md references match the file system
-- FAIL (stale phase): Referenced phase directory does not exist — "Update STATE.md to reflect the actual current phase."
-- FAIL (stale plan): Referenced plan file does not exist — "Update STATE.md to the correct current plan."
-- FAIL (wrong progress): Stated progress does not match actual plan/summary counts — "Update the progress in STATE.md."
-- WARN (no position): No current phase or plan specified — "Fine for new projects but may indicate lost state."
-
-### Check 6: Frontmatter Validity
 
-Glob all `PLAN*.md` and `SUMMARY*.md` in `.planning/phases/`. Each file must start with `---`, have a closing `---`, contain valid YAML, and include required fields: `title`, `status`.
+Parse the JSON output. The CLI returns an object with:
+- `checks`: array of `{ name, status, message, fix_suggestion }` for each check
+- `summary`: `{ passed, failed, warned, total }`
 
-- PASS: All files have valid frontmatter with required fields
-- FAIL (no frontmatter): "Add frontmatter block starting with `---` at the top of the file."
-- FAIL (malformed): Report the YAML error — "Correct the YAML syntax between the `---` delimiters."
-- FAIL (missing field): Report which field — "Add `{field}: {suggested value}` to the frontmatter."
+For each check result, record the status (PASS/FAIL/WARN/INFO) for display in the output table.
 
-### Check 7: ROADMAP/STATE Sync
-
-Compare ROADMAP.md phase statuses against STATE.md current position. Flag if ROADMAP says a phase is "verified" but STATE says it is "building", or if phases after current are marked complete.
-
-- PASS: ROADMAP and STATE are consistent
-- FAIL (mismatch): Report both statuses — "Update STATE.md to match ROADMAP.md, or vice versa."
-- WARN (drift): Current phase in STATE.md is behind phases marked complete in ROADMAP.md.
-
-### Check 8: Hook Execution Log
-
-Check if `.planning/logs/hooks.jsonl` exists. Also check the legacy path `.planning/.hook-log` (the logger migrates this automatically, but it may still exist if hooks haven't fired since the migration was added). Use whichever file exists (prefer `hooks.jsonl`). If found, scan last 20 entries for `decision: "error"` or `decision: "unlink-failed"`.
-
-- PASS: Log exists with no recent errors
-- WARN (errors found): Report error count and most recent error description — "Hooks may not be firing correctly."
-- INFO (no log): "No hook log found. Normal if no hooks have fired yet."
-
-### Check 9: Config Completeness
-
-Read `.planning/config.json` and check for fields referenced by skills:
-- `features.auto_continue` (build skill, auto-continue.js hook)
-- `features.team_discussions` (config skill)
-- `features.goal_verification` (build, review skills)
-- `features.integration_verification` (review skill)
-- `git.mode` (config skill)
-- `planning.commit_docs` (import, discuss, quick skills) — must be a boolean; validate that the value is strictly `true` or `false`, not a string or number
-
-- PASS: All expected fields present with correct types
-- WARN (missing fields): Report each missing field and which skill uses it — "Run `/pbr:config` to set all options."
-
-### Check 10: Orphaned Crash Recovery Files
-
-The executor creates `.PROGRESS-{plan_id}` files as crash recovery breadcrumbs during builds and deletes them after `SUMMARY.md` is written. Similarly, `.checkpoint-manifest.json` files track checkpoint state during execution. If the executor crashes mid-build, these files remain and could confuse future runs.
-
-Glob for `.planning/phases/**/.PROGRESS-*` and `.planning/phases/**/.checkpoint-manifest.json`.
-
-- PASS: No orphaned files found
-- WARN (orphaned progress files): List each file with its parent phase directory:
-  ```
-  Orphaned progress files detected:
-  - .planning/phases/02-auth/.PROGRESS-02-01 (executor may have crashed)
-  ```
-  Fix suggestion: "These are crash recovery breadcrumbs from interrupted builds. Safe to delete if no `/pbr:build` is currently running. Remove with `rm <path>`."
-- WARN (orphaned checkpoint manifests): List each file:
-  ```
-  Orphaned checkpoint manifests detected:
-  - .planning/phases/02-auth/.checkpoint-manifest.json (stale build checkpoint)
-  ```
-  Fix suggestion: "Checkpoint manifests are leftover from interrupted builds. Safe to delete if no `/pbr:build` is currently running. Remove with `rm <path>`."
+If the CLI fails, display a branded ERROR box: "Failed to run health checks. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js verify health` manually to diagnose." and stop.
 
 ---
 
@@ -158,9 +70,11 @@ After running all 10 checks and collecting results, if any of the following auto
 
 ### Auto-Fixable Patterns
 
+**CRITICAL: Execute each fix immediately when found. Do not defer fixes to a later step.**
+
 | Pattern | Detection | Fix Action |
 |---------|-----------|------------|
-| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, total_phases, status) |
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
 | STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
 | Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `/pbr:setup` defaults) |
 | Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |
@@ -171,7 +85,20 @@ After running all 10 checks and collecting results, if any of the following auto
 
 After displaying health check results, if any auto-fixable issues were detected:
 
-1. Count the auto-fixable issues and present:
+**CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.**
+
+```
+mkdir -p .planning/backups
+cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
+```
+
+This ensures the user can recover the original STATE.md if the fix produces incorrect results.
+
+1. Count the auto-fixable issues.
+
+   **If `--repair` flag was passed**: Skip the question and go directly to "Fix all" (step 2). Display: "Auto-repair mode: applying {N} fixes..."
+
+   **Otherwise**: Present the choice:
 
    Use AskUserQuestion:
      question: "Found {N} auto-fixable issues. How should we handle them?"
@@ -181,7 +108,7 @@ After displaying health check results, if any auto-fixable issues were detected:
        - label: "Review each"   description: "Show each fix and confirm individually"
        - label: "Skip"          description: "Do nothing — just report"
 
-2. If "Fix all": Apply all fixes in order, then display a summary:
+2. If "Fix all" (or `--repair`): Apply all fixes in order, then display a summary:
    ```
    Auto-fix results:
    - Fixed: {description of fix 1}
@@ -200,8 +127,6 @@ After displaying health check results, if any auto-fixable issues were detected:
 
 4. If "Skip": Do nothing, continue to the rest of the output.
 
-**Note:** When auto-fix is active, the health skill is no longer strictly read-only. The `allowed-tools` frontmatter must include `Write` and `AskUserQuestion` for auto-fix to work. Update the frontmatter accordingly.
-
 ---
 
 ## Bonus: Recent Decisions
@@ -210,6 +135,8 @@ After all checks, look for `.planning/logs/decisions.jsonl`. If it exists, displ
 
 ---
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ## Completion
 
 After all checks complete, display the branded result:
@@ -230,7 +157,7 @@ After all checks complete, display the branded result:
 
 **Continue your workflow** — planning directory is healthy
 
-`/pbr:status`
+`/pbr:progress`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -238,7 +165,7 @@ After all checks complete, display the branded result:
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
-- `/pbr:config` — adjust settings
+- `/pbr:settings` — adjust settings
 
 
 ```

package/plugins/pbr/skills/help/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: help
 description: "Command reference and workflow guide for Plan-Build-Run."
-allowed-tools: Read
+allowed-tools: Read, Bash
 ---
 
-**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 ~7,600 tokens. Begin executing Step 1 immediately.**
+**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 1 immediately.**
 
 ## Step 0 — Immediate Output
 
@@ -20,138 +20,120 @@ Then proceed to Step 1.
 
 # /pbr:help — Plan-Build-Run Command Reference
 
-## Contextual Help
+## Step 1 — Contextual Help (Single Command)
 
-If `$ARGUMENTS` contains a command name (e.g., `plan`, `build`, `review`, `config`, `quick`), show detailed help for just that command instead of the full reference. Match the argument against the command tables below and display only the matching section with its subcommands and flags. If the argument doesn't match any command, show the full reference.
+If `$ARGUMENTS` contains a command name (e.g., `plan`, `build`, `review`, `config`, `quick`), show detailed help for just that command:
 
-Examples:
-- `/pbr:help plan` → Show only the plan command and its flags (--assumptions, --skip-research, --gaps, add, insert, remove)
-- `/pbr:help build` → Show only the build command and its flags (--gaps-only, --team)
-- `/pbr:help` → Show the full reference below
+1. Run this command to get metadata for the requested skill:
 
-## Full Reference
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js skill-metadata $ARGUMENTS
+```
 
-Display the following reference to the user:
+2. Parse the JSON response.
 
----
+3. **If the response contains a `name` field** (success): Display a formatted detail block:
 
-## Plan-Build-Run Commands
+| Field | Value |
+|-------|-------|
+| **Command** | `/pbr:{name}` |
+| **Description** | `{description}` |
+| **Arguments** | `{argument_hint}` (or "None" if empty) |
+| **Allowed Tools** | `{allowed_tools}` joined with ", " |
 
-### Core Workflow (the main loop)
+4. **If the response contains an `error` field** (not found): Tell the user the command was not found. List available commands from the `available` array, formatted as `/pbr:{name}`.
 
-| Command | Description | Cost |
-|---------|-------------|------|
-| `/pbr:begin` | Start a new project. Deep questioning, research, requirements, roadmap. | High (4-6 agents) |
-| `/pbr:plan <N>` | Plan a phase. Research, create plans, verify before building. | Medium (2-3 agents) |
-| `/pbr:build <N>` | Build a phase. Execute plans in parallel waves, verify results. | High (2-4 agents) |
-| `/pbr:review <N>` | Review what was built. Automated verification + walkthrough with you. | Low (1 agent) |
+5. **STOP after displaying single-skill help.** Do not continue to Step 2.
 
-### Planning & Discovery
+## Step 2 — Full Help (All Commands)
 
-| Command | Description |
-|---------|-------------|
-| `/pbr:explore [topic]` | Explore ideas, think through approaches. No phase number needed. |
-| `/pbr:discuss <N>` | Talk through a phase before planning. Captures decisions. |
-| `/pbr:plan <N> --assumptions` | Surface Claude's assumptions before planning. Zero cost. |
-| `/pbr:plan <N> --skip-research` | Plan without research phase. Faster. |
-| `/pbr:plan <N> --gaps` | Create gap-closure plans from verification failures. |
-| `/pbr:plan add` | Append a new phase to the roadmap. |
-| `/pbr:plan insert <N>` | Insert a phase using decimal numbering. |
-| `/pbr:plan remove <N>` | Remove a future phase and renumber. |
+If no argument was provided, display the full command reference:
 
-### Execution
+1. Run this command to get all skills:
 
-| Command | Description |
-|---------|-------------|
-| `/pbr:build <N>` | Execute all plans in a phase. |
-| `/pbr:build <N> --gaps-only` | Execute only gap-closure plans. |
-| `/pbr:build <N> --team` | Use Agent Teams for complex inter-agent coordination. |
-| `/pbr:quick` | Quick ad-hoc task with atomic commit. Low cost. |
-| `/pbr:continue` | Execute the next logical step automatically. No prompts. |
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js help
+```
 
-### Verification & Debugging
+2. Parse the JSON response. The result has a `.skills` array of objects with `name`, `description`, and `argument_hint` fields.
 
-| Command | Description |
-|---------|-------------|
-| `/pbr:review <N>` | Verify phase + conversational UAT. |
-| `/pbr:review <N> --auto-fix` | Auto-diagnose and fix verification failures. |
-| `/pbr:debug` | Systematic debugging with hypothesis testing. |
-| `/pbr:scan` | Analyze existing codebase (brownfield). |
+3. Group the skills into these categories based on skill name:
 
-### Session Management
+- **Core Workflow**: begin, plan, build, review, test
+- **Planning & Discovery**: explore, discuss, import, scan, list-phase-assumptions
+- **Execution**: quick, continue, autonomous, do
+- **Verification & Debugging**: debug, health, validate-phase, ui-review, ui-phase
+- **Session Management**: status, pause, resume, undo, continue
+- **Project Management**: milestone, todo, note, config, setup, release, ship
+- **Analysis & Utilities**: audit, audit-fix, dashboard, intel, profile, profile-user, session-report, statusline
 
-| Command | Description |
-|---------|-------------|
-| `/pbr:status` | Where am I? Shows progress and suggests next action. |
-| `/pbr:health` | Check planning directory integrity. Find and fix corrupted state. |
-| `/pbr:pause` | Save session state for later. |
-| `/pbr:pause --checkpoint` | Save with a named checkpoint for easier resumption. |
-| `/pbr:resume` | Pick up where you left off. |
+Skills not matching any category go under **Other**.
 
-### Project Management
+4. For each category, display a markdown table:
 
 | Command | Description |
 |---------|-------------|
-| `/pbr:milestone new` | Start a new milestone cycle. |
-| `/pbr:milestone complete` | Archive completed milestone. |
-| `/pbr:milestone audit` | Verify milestone completion. |
-| `/pbr:milestone gaps` | Create phases to close audit gaps. |
-| `/pbr:todo add\|list\|done` | Persistent file-based todos. |
-| `/pbr:todo work <NNN>` | Work on a specific todo by ID. |
-| `/pbr:note <text>\|list\|promote` | Zero-friction idea capture. Quick notes that persist across sessions. |
-| `/pbr:note --global` | Save note to global notes directory (shared across projects). |
-| `/pbr:config` | Configure workflow settings. |
-| `/pbr:import <N>` | Import external plans (design docs, RFCs) into PBR format. |
-| `/pbr:import --from <path>` | Import from a specific file path. |
-| `/pbr:import --skip-checker` | Skip plan-checker validation on import. |
-| `/pbr:setup` | Interactive onboarding wizard for new projects. |
-
-### Analysis & Utilities
+| `/pbr:{name} {argument_hint}` | `{description}` |
 
-| Command | Description |
-|---------|-------------|
-| `/pbr:audit` | Review past sessions for PBR workflow compliance and UX quality. |
-| `/pbr:audit --today` | Audit today's sessions (default). |
-| `/pbr:audit --from DATE --to DATE` | Audit a specific date range. |
-| `/pbr:audit --mode compliance\|ux` | Run compliance-only or UX-only audit. |
-| `/pbr:do <description>` | Route freeform text to the right PBR skill automatically. |
-| `/pbr:dashboard` | Launch the web dashboard for the current project. |
-| `/pbr:dashboard --port <N>` | Launch dashboard on a specific port. |
-| `/pbr:statusline` | Install or configure the PBR status line in Claude Code. |
+Format command names as `/pbr:{name}` with the `argument_hint` appended (space-separated) when present.
+
+5. After the CLI-driven command tables, display the static sections below.
+
+## Choose Your Command
+
+Not sure which command to use? Follow this guide:
+
+| I want to... | Command |
+|--------------|---------|
+| Start a new project | `/pbr:new-project` |
+| Fix a bug or investigate an error | `/pbr:debug` |
+| Think through an idea or approach | `/pbr:explore` |
+| Do a small task (≤3 files) | `/pbr:quick` |
+| Plan a complex change (4+ files) | `/pbr:plan-phase <N>` |
+| See where I am and what's next | `/pbr:progress` |
+| Auto-execute the next step | `/pbr:continue` |
+| Describe something and let PBR route it | `/pbr:do <description>` |
+| Lock decisions for a specific phase | `/pbr:discuss-phase <N>` |
+| Check project health | `/pbr:health` |
 
 ## Typical Workflow
 
 ```
-/pbr:begin              ← Start project, define requirements, create roadmap
-/pbr:discuss 1          ← (optional) Talk through phase details
-/pbr:plan 1             ← Plan the first phase
-/pbr:build 1            ← Build it
-/pbr:review 1           ← Verify it works
-/pbr:plan 2             ← Plan the next phase
+/pbr:new-project              ← Start project, define requirements, create roadmap
+/pbr:discuss-phase 1          ← (optional) Talk through phase details
+/pbr:plan-phase 1             ← Plan the first phase
+/pbr:execute-phase 1            ← Build it
+/pbr:verify-work 1           ← Verify it works
+/pbr:plan-phase 2             ← Plan the next phase
 ...                     ← Repeat plan → build → review
-/pbr:milestone complete ← Archive when done
+/pbr:complete-milestone ← Archive when done
 ```
 
+**Shortcut**: After `/pbr:new-project`, run `/pbr:continue` repeatedly — it auto-advances through plan → build → review → next phase, stopping at milestones and errors.
+
+## status vs continue vs do
+
+| | `/pbr:progress` | `/pbr:continue` | `/pbr:do <text>` |
+|-|---------------|-----------------|-------------------|
+| **Purpose** | Dashboard — show progress, suggest next | Auto-execute the next logical step | Route freeform text to a skill |
+| **Reads state?** | Yes (full scan) | Yes (minimal) | No |
+| **Modifies files?** | Never | Yes (via delegation) | Depends on routed skill |
+| **Asks questions?** | If multiple options | Never — fully automatic | Only if ambiguous |
+| **Use when...** | You want to see where you are before deciding | You trust PBR to pick and run the next step | You'd rather describe a task in plain English |
+| **Hard stops** | N/A | Milestones, checkpoints, errors, verification gaps, session phase limit | N/A |
+
 ## Quick Reference
 
 - **Context strategy**: `aggressive` (delegate everything) | `balanced` | `minimal` (run inline)
 - **Depth**: `quick` (skip research, ~50% cheaper) | `standard` | `comprehensive` (~2x cost)
 - **State files**: `.planning/STATE.md` (position), `.planning/ROADMAP.md` (phases), `.planning/config.json` (settings)
-- **Configure**: `/pbr:config` to change depth, models, gates, parallelization
+- **Configure**: `/pbr:settings` to change depth, models, gates, parallelization
+- **List agents**: Run `claude agents` in your terminal to see all registered PBR agents and verify loading
 - **Tip**: Use `/pbr:quick` for creative/visual work where structured planning adds overhead without benefit.
 - **PR hygiene**: When creating PRs from a Plan-Build-Run project, `.planning/` commits can be filtered using phase branching (`git.branching: phase`) which squash-merges code-only changes to main.
+- **Session cycling**: After `session_phase_limit` phases (default 3), PBR auto-pauses and resumes with a fresh context. In TMUX, this is seamless. Configure via `/pbr:settings session_phase_limit <N>`.
 - **Seeds**: `/pbr:explore` can create seed files (`.planning/seeds/`) with trigger conditions. Seeds auto-inject into planning when their trigger phase is reached.
 
-## Behavioral Contexts
-
-Plan-Build-Run includes three behavioral contexts in `contexts/` that adjust how Claude operates:
-
-- **dev** — Active development: write code first, low verbosity, medium risk tolerance
-- **research** — Exploration mode: read widely, no code writing, high verbosity, evidence-based
-- **review** — Code review: read thoroughly, prioritize by severity, report don't fix
-
-Skills automatically activate the appropriate context: `/pbr:build` uses dev context, `/pbr:discuss` uses research context, `/pbr:review` uses review context.
-
 ## Getting Started
 
 ```
@@ -161,10 +143,10 @@ Skills automatically activate the appropriate context: `/pbr:build` uses dev con
 ║  ▶ NEXT UP                                                   ║
 ╚══════════════════════════════════════════════════════════════╝
 
-→ `/pbr:begin` — start a new project
-→ `/pbr:status` — check current project status
-→ `/pbr:config` — configure workflow settings
-→ `/pbr:help <command>` — detailed help for a specific command
+- `/pbr:new-project` — start a new project
+- `/pbr:progress` — check current project status
+- `/pbr:settings` — configure workflow settings
+- `/pbr:help <command>` — detailed help for a specific command
 
 
 ```