@sienklogic/plan-build-run 2.52.0 → 2.54.0

package/plugins/cursor-pbr/commands/undo.md

@@ -0,0 +1,5 @@
+---
+description: "Revert recent PBR-generated commits by phase/plan, safely using git revert."
+---
+
+This command is provided by the `pbr:undo` skill.

package/plugins/cursor-pbr/references/signal-files.md

@@ -0,0 +1,41 @@
+# Signal Files Reference
+
+Signal files are ephemeral files in `.planning/` that coordinate state between hook scripts
+and skills. They are scoped to either the current session or the current phase/plan.
+
+## Session-Scoped Files
+
+All 5 session signals are consolidated in `.planning/.session.json`. Scripts must read and write
+`.session.json` via `pbr-tools session get|set|clear` — never read the raw `.session.json` file directly.
+The `.session.json` schema is an object with the keys documented below.
+
+| JSON Key | Former File | Written By | Read By | Semantics |
+|----------|-------------|------------|---------|-----------|
+| `activeSkill` | `.active-skill` | Skills (Write tool) | check-skill-workflow, enforce-pbr-workflow, check-subagent-output, log-subagent, block-skill-self-read | Which skill is active. Written at skill start, cleared at skill end (session-cleanup). |
+| `compactCounter` | `.compact-counter` | suggest-compact.js | suggest-compact.js | Write count since last /compact. Resets on SessionStart. |
+| `sessionStart` | `.session-start` | progress-tracker.js | local-llm metrics | ISO timestamp of session start. Used for LLM metrics correlation. |
+| `activeOperation` | `.active-operation` | context-budget-check.js | context-budget-check.js | Current named operation for budget display. |
+| `activePlan` | `.active-plan` | context-budget-check.js | context-budget-check.js | Current plan ID for budget display. |
+
+**Atomic access**: Use `pbr-tools session get|set|clear` for safe reads/writes from hook scripts.
+
+**Lifecycle**: Written during SessionStart (progress-tracker), cleared during SessionEnd (session-cleanup).
+Stale sessions (> 60 min) are auto-cleaned by progress-tracker.js on next SessionStart.
+
+## One-Shot Files
+
+These files are NOT consolidated — they use write-once, delete-on-read semantics.
+
+| File | Written By | Read By | Semantics |
+|------|------------|---------|-----------|
+| `.planning/.auto-next` | auto-continue.js | auto-continue.js (Stop hook) | Next command to run after session stops. Deleted after read. |
+| `.planning/.auto-verify` | event-handler.js | event-handler.js (SubagentStop hook) | Trigger auto-verification after agent completes. Deleted after read. |
+
+## Phase-Scoped Files
+
+These files persist across sessions, scoped to a specific phase or plan.
+
+| File Pattern | Written By | Read By | Semantics |
+|-------------|------------|---------|-----------|
+| `.planning/phases/{id}/.checkpoint-manifest.json` | build skill | validate-task.js, session-cleanup.js | Checkpoint state for a plan in progress. Cleaned up after 24h. |
+| `.planning/phases/{id}/.PROGRESS-{taskId}` | executor agent | validate-task.js | Task progress marker for crash recovery. Orphaned files warn on SessionStart. |

package/plugins/cursor-pbr/skills/begin/SKILL.md

@@ -118,10 +118,138 @@ Have a natural conversation to understand the user's vision. Do NOT present a fo
 
 ---
 
+### Step 2.5: Fast-Path Offer (inline)
+
+Before asking any workflow preference questions, offer the user a quick-start option:
+
+Use AskUserQuestion:
+  question: "How do you want to configure this project?"
+  header: "Setup mode"
+  options:
+    - label: "Quick start"
+      description: "Use all defaults — model balanced, depth standard, interactive mode, parallel on. Writes config in seconds."
+    - label: "Custom setup"
+      description: "Walk through model selection, features, and preferences step by step."
+
+**If user selects "Quick start":**
+- Write `.planning/config.json` immediately using the default config below (no further questions):
+  ```json
+  {
+    "version": 2,
+    "context_strategy": "aggressive",
+    "mode": "interactive",
+    "depth": "standard",
+    "features": {
+      "structured_planning": true,
+      "goal_verification": true,
+      "integration_verification": true,
+      "context_isolation": true,
+      "atomic_commits": true,
+      "session_persistence": true,
+      "research_phase": true,
+      "plan_checking": true,
+      "tdd_mode": false,
+      "status_line": true,
+      "auto_continue": false,
+      "auto_advance": false,
+      "team_discussions": false,
+      "inline_verify": false
+    },
+    "models": {
+      "researcher": "sonnet",
+      "planner": "inherit",
+      "executor": "inherit",
+      "verifier": "sonnet",
+      "integration_checker": "sonnet",
+      "debugger": "inherit",
+      "mapper": "sonnet",
+      "synthesizer": "haiku"
+    },
+    "parallelization": {
+      "enabled": true,
+      "plan_level": true,
+      "task_level": false,
+      "max_concurrent_agents": 3,
+      "min_plans_for_parallel": 2,
+      "use_teams": false
+    },
+    "planning": {
+      "commit_docs": true,
+      "max_tasks_per_plan": 3,
+      "search_gitignored": false
+    },
+    "git": {
+      "branching": "none",
+      "commit_format": "{type}({phase}-{plan}): {description}",
+      "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
+      "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
+      "mode": "enabled"
+    },
+    "gates": {
+      "confirm_project": true,
+      "confirm_roadmap": true,
+      "confirm_plan": true,
+      "confirm_execute": false,
+      "confirm_transition": true,
+      "issues_review": true
+    },
+    "safety": {
+      "always_confirm_destructive": true,
+      "always_confirm_external_services": true
+    }
+  }
+  ```
+- Write `.planning/.active-skill` with text "begin"
+- Write CLAUDE.md integration block (see Step 3d-claude below) using the project name gathered in Step 2
+- Skip to Step 4 (Research Decision)
+- Tell the user: "Quick start selected. Using all defaults — you can adjust later with `/pbr:config`."
+
+**If user selects "Custom setup":** proceed to Step 3 normally.
+
+---
+
 ### Step 3: Workflow Preferences (inline)
 
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
+**3-model. Model Profile:**
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
+  header: "Models"
+  options:
+    - label: "Balanced (Recommended)"
+      description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff."
+    - label: "Quality"
+      description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
+    - label: "Budget"
+      description: "Haiku for most agents. Fastest and cheapest, but lower quality."
+
+Apply the selected profile to the models block in config.json:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+
+**3-features. Workflow Features:**
+Use AskUserQuestion:
+  question: "Any extra workflow features?"
+  header: "Features"
+  multiSelect: true
+  options:
+    - label: "Auto-continue"
+      description: "Automatically chain commands (build → review → next phase) without prompting"
+    - label: "TDD mode"
+      description: "Write tests before implementation in executor agents"
+    - label: "Strict gates"
+      description: "Require verification AND review to pass before advancing phases"
+    - label: "Git branching"
+      description: "Create a branch per phase for cleaner PR history"
+
+Apply selections:
+- **Auto-continue**: Set `features.auto_continue: true`
+- **TDD mode**: Set `features.tdd_mode: true`
+- **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
+- **Git branching**: Set `git.branching: "phase"`
+
 **3a. Mode:**
 Use the **toggle-confirm** pattern from `skills/shared/gate-prompts.md`:
   question: "How do you want to work?"
@@ -165,12 +293,33 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 - `yes` (default) — commit planning docs
 - `no` — add .planning/ to .gitignore
 
+**3d-claude. CLAUDE.md Integration:**
+
+Check if a `CLAUDE.md` file exists in the project root.
+
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
+**If it does NOT exist**: Create `CLAUDE.md` with the block below.
+
+Append/create:
+
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
+- Configuration: `.planning/config.json`
+- Run `/pbr:status` to see current project state and suggested next action.
+
+**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+```
+
 **After gathering preferences:**
 
 **CRITICAL (no hook): You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
 
 1. Read the config template from `skills/begin/templates/config.json.tmpl`
-2. Apply the user's choices to the template
+2. Apply the user's choices to the template (including 3d-claude CLAUDE.md integration)
 3. Create `.planning/` directory
 4. Write `.planning/config.json` with the user's preferences
 
@@ -198,13 +347,15 @@ Based on the depth setting from Step 3, determine the research approach:
 - Tell user: "Skipping research phase (depth: quick). Moving straight to requirements."
 
 **If depth is `standard` or `comprehensive`:**
-Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
-  question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
-  options:
-    - label: "Yes"  description: "Run research agents (recommended for standard/comprehensive)"
-    - label: "No"   description: "Skip research, move straight to requirements"
-- If user selects "No": skip to Step 7
-- If user selects "Yes": proceed to Step 5
+- If `gates.confirm_research` is `true` in config:
+  Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
+    question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
+    options:
+      - label: "Yes"  description: "Run research agents (recommended for standard/comprehensive)"
+      - label: "No"   description: "Skip research, move straight to requirements"
+  - If user selects "No": skip to Step 7
+  - If user selects "Yes": proceed to Step 5
+- If `gates.confirm_research` is `false` (default): proceed directly to Step 5 (research runs automatically)
 
 ---
 
@@ -580,15 +731,17 @@ If `gates.confirm_project` is true in config:
   - Phases: {count} phases in roadmap
   - Requirements: {count} v1 requirements
   - Config: depth={depth}, mode={mode}
-- Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
-  question: "Everything look good? Commit the planning docs?"
-  options:
-    - label: "Yes"  description: "Stage and commit .planning/ files"
-    - label: "No"   description: "Let me review and adjust first"
-- If user selects "Yes" and `planning.commit_docs` is true:
-  - Stage `.planning/` files (excluding research/ if gitignored)
-  - Commit: `chore: initialize plan-build-run project planning`
-- If user selects "No": let user review and adjust
+- If `gates.confirm_commit_docs` is `true` OR this is a **brownfield** project (existing code detected in Step 1):
+  Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
+    question: "Everything look good? Commit the planning docs?"
+    options:
+      - label: "Yes"  description: "Stage and commit .planning/ files"
+      - label: "No"   description: "Let me review and adjust first"
+  - If user selects "Yes" and `planning.commit_docs` is true:
+    - Stage `.planning/` files (excluding research/ if gitignored)
+    - Commit: `chore: initialize plan-build-run project planning`
+  - If user selects "No": let user review and adjust
+- If `gates.confirm_commit_docs` is `false` AND greenfield: skip the question and commit automatically if `planning.commit_docs` is true
 
 ---
 

package/plugins/cursor-pbr/skills/build/SKILL.md

@@ -17,6 +17,8 @@ Reference: `skills/shared/context-budget.md` for the universal orchestrator rule
 Additionally for this skill:
 - **Minimize** reading executor output — read only SUMMARY.md frontmatter, not full content
 - **Delegate** all building work to executor agents — the orchestrator routes, it doesn't build
+- **Lazy-load steps**: Instead of reading ahead, fetch the next step's instructions on demand:
+  `node ${PLUGIN_ROOT}/scripts/pbr-tools.js skill-section build "step-6"` → returns that step's content as JSON. Use this when context budget is DEGRADING.
 
 ## Step 0 — Immediate Output
 
@@ -48,6 +50,53 @@ Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
 | `3 --gaps-only` | Build only gap-closure plans in phase 3 |
 | `3 --team` | Use Agent Teams for complex inter-agent coordination |
 | (no number) | Use current phase from STATE.md |
+| `3 --preview` | Preview what build would do for phase 3 without executing |
+
+---
+
+### --preview mode
+
+If `--preview` is present in `$ARGUMENTS`:
+
+1. Extract the phase slug from `$ARGUMENTS` (use the phase number to look up the slug, or pass the number directly — the CLI accepts partial slug matches).
+2. Run:
+
+   ```bash
+   node ${PLUGIN_ROOT}/scripts/pbr-tools.js build-preview {phase-slug}
+   ```
+
+   Capture the JSON output.
+3. Render the following preview document (do NOT proceed to Step 2):
+
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  DRY RUN — /pbr:build {N} --preview                          ║
+   ║  No executor agents will be spawned                          ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   PHASE: {phase}
+
+   ## Plans
+   {for each plan: - {id} (wave {wave}, {task_count} tasks)}
+
+   ## Wave Structure
+   {for each wave: Wave {wave}: {plan IDs} [parallel | sequential]}
+
+   ## Files That Would Be Modified
+   {for each file in files_affected: - {file}}
+   (Total: {count} files)
+
+   ## Estimated Agent Spawns
+   {agent_count} executor task(s)
+
+   ## Critical Path
+   {critical_path joined with " → "}
+
+   ## Dependency Chain
+   {for each entry in dependency_chain: - {id} (wave {wave}) depends on: {depends_on or "none"}}
+   ```
+
+4. **STOP** — do not proceed to Step 2.
 
 ---
 
@@ -108,16 +157,23 @@ Phase {N} has no plans.
 **To fix:** Run `/pbr:plan {N}` first.
 ```
 
-If dependencies incomplete:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
+If dependencies incomplete, use conversational recovery:
 
-Phase {N} depends on Phase {M}, which is not complete.
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives missing-prereq {dependency-phase-slug}`
+2. Parse the JSON response to get `existing_summaries`, `missing_summaries`, and `suggested_action`.
+3. Display what summaries exist and what is still missing.
+4. Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`) to offer:
+   - "Build {dependency-phase} first" — stop and show: `/pbr:build {dependency-phase}`
+   - "Continue anyway (skip dependency check)" — proceed with build, note unmet deps in output
 
-**To fix:** Build Phase {M} first with `/pbr:build {M}`.
-```
+If config validation fails for a specific field, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives config-invalid {field} {value}`
+2. Parse the JSON response to get `valid_values` and `suggested_fix`.
+3. Display the invalid field, its current value, and the valid options.
+4. Use AskUserQuestion to offer: "Fix config.json now, or continue with current value?"
+   - If "Fix now": stop and display the `suggested_fix` instruction.
+   - If "Continue": proceed with default value for that field.
 
 ---
 
@@ -565,6 +621,9 @@ node ${PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now
 - [ ] STATE.md body progress bar updated
 - [ ] `last_activity` timestamp refreshed
 
+To verify programmatically: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-6f '["STATE.md updated","SUMMARY.md exists","commit made"]'`
+If any item fails, investigate before proceeding to Step 7.
+
 ---
 
 ### Step 7: Phase Verification (delegated, conditional)
@@ -697,6 +756,9 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 - [ ] STATE.md body ## Current Position updated: Phase, Status, Last activity, Progress bar
 - [ ] Frontmatter and body are consistent (same status value in both)
 
+To verify programmatically: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-8b '["STATE.md updated","ROADMAP.md updated","commit made"]'`
+If any item fails, investigate before marking phase complete.
+
 **8c. Commit planning docs (if configured):**
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
 If `planning.commit_docs` is `true`:
@@ -766,6 +828,9 @@ Write `.planning/.auto-next` containing the next logical command (e.g., `/pbr:pl
 - [ ] Pending todos evaluated (Step 8e-ii)
 - [ ] Clearly-satisfied todos auto-closed via `pbr-tools.js todo done`
 
+To verify programmatically: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-8e '["STATE.md updated","commit made"]'`
+If any item fails, investigate before closing the session.
+
 **8e-ii. Check Pending Todos:**
 
 **CRITICAL (no hook): Check pending todos after build. Do NOT skip this step.**

package/plugins/cursor-pbr/skills/plan/SKILL.md

@@ -56,6 +56,7 @@ Parse the phase number and optional flags:
 | `3 --gaps` | Create gap-closure plans for phase 3 (from VERIFICATION.md) |
 | `3 --teams` | Plan phase 3 using specialist agent teams |
 | (no number) | Use current phase from STATE.md |
+| `3 --preview` | Preview what planning would produce for phase 3 without spawning agents |
 
 ### Subcommands
 
@@ -124,6 +125,35 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state lo
 5. If no phase number given, read current phase from `.planning/STATE.md`
 6. **CONTEXT.md existence check**: If the phase is non-trivial (has 2+ requirements or success criteria), check whether a CONTEXT.md exists at EITHER `.planning/CONTEXT.md` (project-level) OR `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level). If NEITHER exists, warn: "Phase {N} has no CONTEXT.md. Consider running `/pbr:discuss {N}` first to capture your preferences. Continue anyway?" If user says no, stop. If yes, continue. If at least one exists, proceed without warning.
 
+#### --preview mode
+
+If `--preview` is present in `$ARGUMENTS`:
+
+1. Detect the `--preview` flag and extract the phase number.
+2. Render the following dry-run banner:
+
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  DRY RUN — /pbr:plan {N} --preview                           ║
+   ║  No researchers or planners will be spawned                  ║
+   ╚══════════════════════════════════════════════════════════════╝
+   ```
+
+3. Show the 5 steps that would occur:
+
+   1. Parse ROADMAP.md for phase {N} goal, dependencies, and requirements
+   2. Spawn researcher agents to investigate codebase and gather context
+   3. Spawn planner agent to write PLAN files based on research
+   4. Run plan-checker to validate structure and completeness
+   5. Present plans for your approval before building
+
+4. Show estimated agent spawns: ~2-4 agents (1-2 researchers + 1 planner + 1 plan-checker)
+5. Show output location: `.planning/phases/{NN}-{slug}/PLAN-NN.md`
+
+6. **STOP** — do not proceed to Step 2.
+
+---
+
 **If phase already has plans:**
 - Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
   question: "Phase {N} already has plans. Re-plan from scratch?"
@@ -252,21 +282,25 @@ Output format: Return both sections as markdown. End with ## BRIEFING COMPLETE."
 ```
 
 After the Task() completes:
-- If `## Seeds` section contains matches: present them to the user via AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
-  question: "Include these {N} seeds in planning?"
-  header: "Seeds?"
-  options:
-    - label: "Yes, all"     description: "Include all {N} matching seeds"
-    - label: "Let me pick"  description: "Choose which seeds to include"
-    - label: "No"           description: "Proceed without seeds"
-- If "Yes, all": include seed content in planner context
-- If "Let me pick": present individual seeds for selection
-- If "No": proceed without seeds
-
-- If `## Deferred Ideas` section has items: present via AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
-  question: "Include these deferred ideas in planning context?"
-- If "Yes": append to planner context under `Deferred ideas to consider:`
-- If "No": proceed without changes
+- If `## Seeds` section contains matches:
+  - If `gates.confirm_seeds` is `true` in config: present them to the user via AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
+      question: "Include these {N} seeds in planning?"
+      header: "Seeds?"
+      options:
+        - label: "Yes, all"     description: "Include all {N} matching seeds"
+        - label: "Let me pick"  description: "Choose which seeds to include"
+        - label: "No"           description: "Proceed without seeds"
+    - If "Yes, all": include seed content in planner context
+    - If "Let me pick": present individual seeds for selection
+    - If "No": proceed without seeds
+  - If `gates.confirm_seeds` is `false` (default): automatically include all matching seeds in planner context without prompting. Log: "Including {N} seeds automatically (gates.confirm_seeds=false)."
+
+- If `## Deferred Ideas` section has items:
+  - If `gates.confirm_deferred` is `true` in config: present via AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+      question: "Include these deferred ideas in planning context?"
+    - If "Yes": append to planner context under `Deferred ideas to consider:`
+    - If "No": proceed without changes
+  - If `gates.confirm_deferred` is `false` (default): automatically append deferred ideas to planner context without prompting. Log: "Including deferred ideas automatically (gates.confirm_deferred=false)."
 
 - If both sections are empty: proceed silently to Step 5 (no AskUserQuestion needed)
 
@@ -555,10 +589,26 @@ Read `skills/plan/templates/gap-closure-prompt.md.tmpl` and use it as the prompt
 ## Error Handling
 
 ### Phase not found
-If the specified phase doesn't exist in ROADMAP.md, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Phase not found.
+If the specified phase doesn't exist in ROADMAP.md, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives phase-not-found {slug}`
+2. Parse the JSON response to get `available` phases and `suggestions` (closest matches).
+3. Display: "Phase '{slug}' not found. Did you mean one of these?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`) to let the user pick a phase or abort.
+   - If user picks a valid phase slug: re-run with that slug.
+   - If user chooses to abort: stop cleanly with a friendly message.
 
 ### Missing prerequisites
-If REQUIREMENTS.md or ROADMAP.md don't exist, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Missing prerequisites.
+If REQUIREMENTS.md or ROADMAP.md don't exist, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives missing-prereq {phase}`
+2. Parse the JSON response to get `existing_summaries`, `missing_summaries`, and `suggested_action`.
+3. Display what is already complete and what is missing.
+4. Use AskUserQuestion to offer: "Run /pbr:build {prerequisite-phase} first, or continue anyway?"
+   - If user chooses to continue: proceed with planning (note missing prereqs in plan frontmatter).
+   - If user chooses to build first: stop and display the suggested build command.
 
 ### Research agent fails
 If the researcher Task() fails, display:

package/plugins/cursor-pbr/skills/review/SKILL.md

@@ -76,7 +76,18 @@ Execute these steps in order.
 5. If no phase number given, read current phase from `.planning/STATE.md`
 6. If `.planning/.auto-verify` signal file exists, read it and note the auto-verification was already queued. Delete the signal file after reading (one-shot, same pattern as auto-continue.js).
 
-**Validation errors — use branded error boxes:**
+**Validation errors:**
+
+If phase directory not found, use conversational recovery:
+
+1. Run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives phase-not-found {slug}`
+2. Parse the JSON response to get `available` phases and `suggestions` (closest matches).
+3. Display: "Phase '{slug}' not found. Did you mean one of these?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`) to let the user pick a phase or abort.
+   - If user picks a valid phase slug: re-run with that slug.
+   - If user chooses to abort: stop cleanly with a friendly message.
 
 If no SUMMARY.md files:
 ```