@sienklogic/plan-build-run 2.11.0 → 2.12.1

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

@@ -1,22 +1,25 @@
 ---
 name: plan
 description: "Create a detailed plan for a phase. Research, plan, and verify before building."
-allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion
-argument-hint: "<phase-number> [--skip-research] [--assumptions] [--gaps] | add | insert <N> | remove <N>"
+allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion, Skill
+argument-hint: "<phase-number> [--skip-research] [--assumptions] [--gaps] [--model <model>] [--auto] [--through <N>] [--prd <file>] | add | insert <N> | remove <N>"
 ---
 
 **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.**
 
-# /pbr:plan — Phase Planning
+# /pbr:plan-phase — Phase Planning
 
-You are the orchestrator for `/pbr:plan`. This skill creates detailed, executable plans for a specific phase. Plans are the bridge between the roadmap and actual code — they must be specific enough for an executor agent to follow mechanically. Your job is to stay lean, delegate heavy work to Task() subagents, and keep the user's main context window clean.
+**References:** `@references/questioning.md`, `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:plan-phase`. This skill creates detailed, executable plans for a specific phase. Plans are the bridge between the roadmap and actual code — they must be specific enough for an executor agent to follow mechanically. Your job is to stay lean, delegate heavy work to Task() subagents, and keep the user's main context window clean.
 
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 Additionally for this skill:
-- **Minimize** reading subagent output — read only plan frontmatter for summaries
+- **Minimize** reading subagent output — read only plan frontmatter for summaries. Exception: if `context_window_tokens` in `.planning/config.json` is >= 500000, reading full plan bodies is permitted when content is needed for inline decisions.
 - **Delegate** all research and planning work to subagents — the orchestrator routes, it doesn't plan
 
 ## Step 0 — Immediate Output
@@ -31,9 +34,25 @@ Additionally for this skill:
 
 Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
 
+## Multi-Session Sync
+
+Before any phase-modifying operations (writing PLAN files, updating STATE.md/ROADMAP.md), acquire a claim:
+
+```
+acquireClaim(phaseDir, sessionId)
+```
+
+If the claim fails (another session owns this phase), display: "Another session owns this phase. Use `/pbr:progress` to see active claims."
+
+On completion or error (including all exit paths), release the claim:
+
+```
+releaseClaim(phaseDir, sessionId)
+```
+
 ## Prerequisites
 
-- `.planning/config.json` exists (run `/pbr:begin` first)
+- `.planning/config.json` exists (run `/pbr:new-project` first)
 - `.planning/ROADMAP.md` exists with at least one phase
 - `.planning/REQUIREMENTS.md` exists
 
@@ -45,7 +64,7 @@ Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
 
 ### Standard Invocation
 
-`/pbr:plan <N>` — Plan phase N
+`/pbr:plan-phase <N>` — Plan phase N
 
 Parse the phase number and optional flags:
 
@@ -56,7 +75,13 @@ Parse the phase number and optional flags:
 | `3 --assumptions` | Surface assumptions before planning phase 3 |
 | `3 --gaps` | Create gap-closure plans for phase 3 (from VERIFICATION.md) |
 | `3 --teams` | Plan phase 3 using specialist agent teams |
+| `3 --model opus` | Use opus for all researcher, planner, and checker spawns in phase 3 |
 | (no number) | Use current phase from STATE.md |
+| `3 --preview` | Preview what planning would produce for phase 3 without spawning agents |
+| `3 --audit` | Plan phase 3, then force full plan-checker validation |
+| `3 --auto` | Plan phase 3 with auto mode — suppress confirmation gates, auto-advance on success |
+| `1 --through 3` | Plan phases 1 through 3 in a single planner session (requires planning.multi_phase: true) |
+| `3 --prd path/to/prd.md` | Plan phase 3 using a PRD file as input — skip discussion, generate CONTEXT.md from PRD |
 
 ### Subcommands
 
@@ -73,20 +98,21 @@ Parse the phase number and optional flags:
 - Empty (no arguments)
 - A phase number: integer (`3`, `03`) or decimal (`3.1`)
 - A subcommand: `add`, `insert <N>`, `remove <N>`
-- A phase number followed by flags: `3 --skip-research`, `3 --assumptions`, `3 --gaps`, `3 --teams`
+- A phase number followed by flags: `3 --skip-research`, `3 --assumptions`, `3 --gaps`, `3 --teams`, `3 --auto`, `3 --prd <file>`
+- A phase number followed by --through and another number: `1 --through 3`
 - The word `check` (legacy alias)
 
 If `$ARGUMENTS` does NOT match any of these patterns — i.e., it contains freeform words that are not a recognized subcommand or flag — then **stop execution** and respond:
 
 ```
-`/pbr:plan` expects a phase number or subcommand.
+`/pbr:plan-phase` expects a phase number or subcommand.
 
 Usage:
-  /pbr:plan <N>              Plan phase N
-  /pbr:plan <N> --gaps       Create gap-closure plans
-  /pbr:plan add              Add a new phase
-  /pbr:plan insert <N>       Insert a phase at position N
-  /pbr:plan remove <N>       Remove phase N
+  /pbr:plan-phase <N>              Plan phase N
+  /pbr:plan-phase <N> --gaps       Create gap-closure plans
+  /pbr:plan-phase add              Add a new phase
+  /pbr:plan-phase insert <N>       Insert a phase at position N
+  /pbr:plan-phase remove <N>       Remove phase N
 ```
 
 Then suggest the appropriate skill based on the text content:
@@ -95,7 +121,7 @@ Then suggest the appropriate skill based on the text content:
 |---------------------------|---------|
 | A task, idea, or feature request | `/pbr:todo` to capture it, or `/pbr:explore` to investigate |
 | A bug or debugging request | `/pbr:debug` to investigate the issue |
-| A review or quality concern | `/pbr:review` to assess existing work |
+| A review or quality concern | `/pbr:verify-work` to assess existing work |
 | Anything else | `/pbr:explore` for open-ended work |
 
 Do NOT proceed with planning. The user needs to use the correct skill.
@@ -106,7 +132,7 @@ Do NOT proceed with planning. The user needs to use the correct skill.
 
 ## Orchestration Flow: Standard Planning
 
-Execute these steps in order for standard `/pbr:plan <N>` invocations.
+Execute these steps in order for standard `/pbr:plan-phase <N>` invocations.
 
 ---
 
@@ -115,15 +141,102 @@ Execute these steps in order for standard `/pbr:plan <N>` invocations.
 Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state load`, `plan-index`, `phase-info`) and config field reference.
 
 1. Parse `$ARGUMENTS` for phase number and flags
+   - If `--model <value>` is present in `$ARGUMENTS`, extract the value (sonnet, opus, haiku, inherit). Store as `override_model`. When spawning researcher, planner, and plan-checker Task() agents, use `override_model` instead of the config-derived model values. If an invalid value is provided, display an error and list valid values.
+   - If `--auto` is present in `$ARGUMENTS`: set `auto_mode = true`. Log: "Auto mode enabled — suppressing confirmation gates"
+   - If `--through <M>` is present:
+     a. Read `planning.multi_phase` from config
+     b. If `planning.multi_phase` is `false` or unset: display error:
+        "`--through` requires `planning.multi_phase: true` in config. Set it with: `/pbr:config set planning.multi_phase true`"
+        Then STOP.
+     c. Parse start phase (N) and end phase (M). Validate both exist in ROADMAP.md.
+     d. Store `through_phases = [N, N+1, ..., M]`
+     e. Log: "Multi-phase planning: phases {N} through {M}"
+   - If `--prd <file>` is present in `$ARGUMENTS`:
+     a. Extract the file path from the argument
+     b. Set `prd_mode = true`
+     c. Log: "PRD express path — will generate CONTEXT.md from PRD, skip discussion"
 2. Read `.planning/config.json` for settings (see config-loading.md for field reference)
-   **CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+   **Speculative mode guard:** If `$ARGUMENTS` contains `--speculative` or `--no-state-update`, SKIP the `.active-skill` write below — the autonomous orchestrator owns `.active-skill` during speculative planning.
+   **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 3. Resolve depth profile: run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
 4. Validate:
    - Phase exists in ROADMAP.md
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
    - Phase does not already have PLAN.md files (unless user confirms re-planning)
 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.
+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-phase {N}` first to capture your preferences. Continue anyway?" If user says no, stop. If yes, continue. If at least one exists, proceed without warning.
+
+#### --prd express path
+
+If `prd_mode` is `true`:
+
+1. Read the PRD file specified by the `--prd` argument
+2. Parse the PRD content, looking for these sections (case-insensitive):
+   - **Requirements** / **Functional Requirements** / **User Stories**
+   - **Scope** / **In Scope** / **Out of Scope**
+   - **Constraints** / **Technical Constraints**
+   - **Decisions** / **Architecture Decisions** / **Design Decisions**
+   - **Goals** / **Objectives**
+**CRITICAL — DO NOT SKIP: Write CONTEXT.md from the PRD NOW. The planner agent requires this file for locked decisions.**
+3. Generate `.planning/phases/{NN}-{slug}/CONTEXT.md` from the PRD:
+   ```markdown
+   ---
+   source: prd
+   prd_file: "{original file path}"
+   generated: "{ISO timestamp}"
+   ---
+   # Phase {N} Context (from PRD)
+
+   ## Decision Summary
+   {Extracted decisions from PRD, each as a locked decision}
+
+   ## Scope
+   {Extracted scope boundaries}
+
+   ## Constraints
+   {Extracted constraints}
+
+   ## Requirements Mapping
+   {Map PRD requirements to phase REQ-IDs where possible}
+
+   ## Deferred Ideas
+   {Any out-of-scope items from the PRD}
+   ```
+4. Log: "Generated CONTEXT.md from PRD ({line_count} lines)"
+5. **Skip Step 6 (CONTEXT.md existence check)** — we just created one
+6. **Skip Steps 3 and 4** (assumption surfacing and research) — the PRD provides the context
+7. Proceed directly to **Step 5** (planning) with the PRD-derived context
+
+---
+
+#### --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-phase {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`):
@@ -139,10 +252,12 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state lo
 
 ### Step 2: Load Context (inline)
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.cjs init plan-phase {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 Read context file PATHS and metadata. Build lean context bundles for subagent prompts — include paths and one-line descriptions, NOT full file bodies. Agents have the Read tool and will pull file contents on-demand.
 
 ```
-1. Read .planning/ROADMAP.md — extract current phase goal, dependencies, requirements
+1. Read .planning/ROADMAP.md — extract current phase goal, dependencies, **Requirements:** (REQ-IDs), and **Success Criteria:**
 2. Read .planning/REQUIREMENTS.md — extract requirements mapped to this phase
 3. Read .planning/CONTEXT.md (if exists) — extract only the `## Decision Summary` section (everything from `## Decision Summary` to the next `##` heading). If no Decision Summary section exists (legacy CONTEXT.md), fall back to extracting the full `## Decisions (LOCKED...)` and `## Deferred Ideas` sections.
 4. Read .planning/phases/{NN}-{slug}/CONTEXT.md (if exists) — extract only the `## Decision Summary` section. Fall back to full locked decisions + deferred sections if no Decision Summary exists.
@@ -163,34 +278,7 @@ Collect all of this into a context bundle that will be passed to subagents.
 
 **IMPORTANT**: This step is FREE (no subagents). It happens entirely inline.
 
-Before spawning any agents, present your assumptions about how this phase should be approached:
-
-```
-Phase {N}: {Name}
-Goal: {from roadmap}
-
-My assumptions about this phase:
-
-1. **Approach**: I'm assuming we'll {approach}
-   - Correct? [yes/no/adjust]
-
-2. **Key technology**: I'm assuming we'll use {tech}
-   - Correct? [yes/no/adjust]
-
-3. **Architecture**: I'm assuming {architectural assumption}
-   - Correct? [yes/no/adjust]
-
-4. **Scope boundary**: I'm assuming {scope assumption}
-   - Correct? [yes/no/adjust]
-```
-
-For each assumption the user corrects:
-- Record the correction
-- These corrections become additional CONTEXT.md entries
-
-After all assumptions are confirmed/corrected:
-- Update `.planning/CONTEXT.md` with any new locked decisions
-- Continue to Step 4
+Before spawning any agents, present 4 assumptions to the user — one each for: approach (how the phase will be implemented), key technology, architecture, and scope boundary. For each, ask the user to confirm or correct. Record corrections as new CONTEXT.md locked decisions. After all assumptions are confirmed/corrected, continue to Step 4.
 
 ---
 
@@ -207,7 +295,13 @@ To check: run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-de
 
 **If research is needed:**
 
-Display to the user: `◐ Spawning researcher...`
+Display to the user: `◆ Spawning researcher...`
+
+**Parallel research optimization (1M context):** If `context_window_tokens` in `.planning/config.json` is >= 500000, spawn the researcher Task() AND the pre-planner briefing Task() (Step 4.5) in parallel using `run_in_background: true` for both. Both are independent -- the researcher analyzes technologies while the briefing scans seeds and deferred items. Wait for both to complete before proceeding to the planner.
+
+Display: `◆ Spawning researcher + pre-planner briefing in parallel (1M context)...`
+
+If `context_window_tokens` < 500000, maintain the existing sequential flow: researcher first, then pre-planner briefing.
 
 Spawn a researcher Task():
 
@@ -220,11 +314,11 @@ Task({
 NOTE: The pbr:researcher subagent type auto-loads the agent definition. Do NOT inline it.
 ```
 
-**Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
+**Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.cjs or template references included in the prompt.
 
 #### Phase Research Prompt Template
 
-Read `skills/plan/templates/researcher-prompt.md.tmpl` and use it as the prompt template for spawning the researcher agent. Fill in the placeholders with phase-specific context:
+Read `${CLAUDE_SKILL_DIR}/templates/researcher-prompt.md.tmpl` and use it as the prompt template for spawning the researcher agent. Fill in the placeholders with phase-specific context:
 - `{NN}` - phase number (zero-padded)
 - `{phase name}` - phase name from roadmap
 - `{goal from roadmap}` - phase goal statement
@@ -232,65 +326,90 @@ Read `skills/plan/templates/researcher-prompt.md.tmpl` and use it as the prompt
 - `{dependencies from roadmap}` - dependency list
 - Fill `<project_context>` and `<prior_work>` blocks per the shared partial (`templates/prompt-partials/phase-project-context.md.tmpl`): Decision Summary for context, manifest table for prior work
 
+**Prepend this block to the researcher prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/ROADMAP.md — phase goals, dependencies, and structure
+2. .planning/REQUIREMENTS.md — scoped requirements for this phase (if exists)
+</files_to_read>
+```
+
 Wait for the researcher to complete before proceeding.
 
+After the researcher completes, check the Task() output for a completion marker:
+- If `## RESEARCH COMPLETE` is present: proceed to planner
+- If `## RESEARCH BLOCKED` is present: warn the user that research could not complete, ask if they want to proceed with limited context or stop
+- If neither marker is present: warn that researcher may not have completed successfully, but proceed
+
 ---
 
-### Step 4.5: Seed Scanning (inline, before planning)
+### Step 4.5: Pre-Planner Briefing (delegated)
 
-Before spawning the planner, scan `.planning/seeds/` for seeds whose trigger matches the current phase:
+**CRITICAL (no hook): Run pre-planner briefing before spawning the planner. Do NOT skip this step.**
 
-1. Glob for `.planning/seeds/*.md`
-2. For each seed file, read its frontmatter and check the `trigger` field
-3. A seed matches if ANY of these are true:
-   - `trigger` equals the phase slug (e.g., `trigger: authentication`) — **preferred**
-   - `trigger` is a substring of the phase directory name (e.g., `trigger: auth` matches `03-authentication`)
-   - `trigger` equals the current phase number as integer (e.g., `trigger: 3`) — backward compatible but NOT recommended for new seeds (breaks with decimal phases like 3.1)
-   - `trigger` equals `*` (always matches)
-4. If matching seeds are found, present them to the user:
-   ```
-   Found {N} seeds related to Phase {NN}:
-     - {seed_name}: {seed description}
-     - {seed_name}: {seed description}
-   ```
+**Note:** If `context_window_tokens` >= 500000, this step was already spawned in parallel with the researcher in Step 4. Skip spawning it again -- just read the results.
 
-   Use 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"
-5. If "Yes, all": include all matching seed content in the planner's context
-6. If "Let me pick": present individual seeds for selection
-7. If "No" or "Other": proceed without seeds
-8. If no matching seeds found: proceed silently
+Consolidate seed scanning and deferred idea surfacing into a single lightweight Task():
 
----
+```
+Task({
+  subagent_type: "pbr:general",
+  model: "haiku",
+  prompt: "Pre-planner briefing for Phase {NN} ({phase-slug}).
 
-### Step 4.6: Surface Deferred Ideas (inline, before planning)
+1. SEED SCANNING:
+   Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js seeds match {phase-slug} {phase-number}`
+   If `matched` is non-empty, output a ## Seeds section listing each seed name, description, and content.
+   If empty, output: ## Seeds\nNo matching seeds found.
 
-Before spawning the planner, check `.planning/CONTEXT.md` for deferred ideas that may be relevant to this phase:
+2. DEFERRED IDEAS:
+   Collect deferred items from three sources:
 
-1. If `.planning/CONTEXT.md` does NOT exist, skip this step silently
-2. If it exists, scan for sections named "Deferred Ideas", "Deferred", "Ideas", or "Seeds" (case-insensitive heading match)
-3. For each deferred item found, check relevance to the current phase by comparing the item text against the phase goal, requirements, and slug
-4. If relevant deferred items are found, present them to the user:
-   ```
-   Found {N} deferred idea(s) from previous discussions that may be relevant to Phase {NN}:
-     - {deferred item summary}
-     - {deferred item summary}
-   ```
-   Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
-     question: "Include these deferred ideas in the planning context?"
-     header: "Deferred Ideas"
-     options:
-       - label: "Yes"  description: "Pass relevant deferred ideas to the planner"
-       - label: "No"   description: "Proceed without deferred ideas"
-5. If "Yes": append the relevant deferred items to the context bundle for the planner prompt (add them to the `<project_context>` block under a `Deferred ideas to consider:` heading)
-6. If "No" or no relevant items found: proceed without changes
+   a. **Project CONTEXT.md**: Read `.planning/CONTEXT.md`. Check for `<deferred>` XML tags (preferred)
+      OR `## Deferred` / `## Deferred Ideas` markdown headers (backward compat).
+      Extract items that mention Phase {NN} or keywords matching the phase slug.
+
+   b. **Phase CONTEXT.md**: Read `.planning/phases/{NN}-{slug}/CONTEXT.md` (if exists).
+      Check for `<deferred>` XML tags OR markdown deferred headers. Extract relevant items.
+
+   c. **Prior phase SUMMARY.md files**: Read SUMMARY-*.md files from the prior phase directory
+      (`.planning/phases/{prior_phase_dir}/SUMMARY-*.md`, where prior_phase_dir is phase N-1).
+      Extract the `deferred:` field from each SUMMARY frontmatter. List any deferred items
+      from the prior phase that might now be in scope for this phase.
+
+   Output a ## Deferred Ideas section with sub-sections:
+   - 'From project CONTEXT.md:' (items from project-level deferred, or 'None')
+   - 'From phase CONTEXT.md:' (items from current phase deferred, or 'None')
+   - 'From prior phase:' (items from prior phase SUMMARY.md deferred fields, or 'None')
+   If all three sources are empty, output: ## Deferred Ideas\nNo relevant deferred items.
+
+Output format: Return both sections as markdown. End with ## BRIEFING COMPLETE."
+})
+```
 
-This is a lightweight relevance filter — do NOT spawn a subagent for this. Just match keywords from the deferred items against the phase goal and requirement text.
+After the Task() completes:
+- 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)
 
 ---
 
@@ -298,43 +417,67 @@ This is a lightweight relevance filter — do NOT spawn a subagent for this. Jus
 
 #### Team Mode (--teams)
 
-Reference: `references/agent-teams.md` for team role definitions and coordination details.
+If `--teams` flag is set OR `config.parallelization.use_teams` is true, spawn 3 parallel planner agents (architect, security, test) then a synthesizer to merge their outputs. See `references/agent-teams.md` for agent role definitions, output paths (`.planning/phases/{NN}-{slug}/team/`), and prompt content for each role.
 
-If `--teams` flag is set OR `config.parallelization.use_teams` is true:
+If `--teams` is NOT set and `config.parallelization.use_teams` is false or unset, proceed with the single-planner flow below.
 
-1. Create the team output directory: `.planning/phases/{NN}-{slug}/team/`
-2. Display to the user: `◐ Spawning 3 planners in parallel (architect, security, test)...`
+#### Multi-Phase Flow (--through)
 
-   Spawn THREE planner agents in parallel using Task():
+If `through_phases` is set (from Step 1 --through parsing):
 
-   **Agent 1 -- Architect**:
-   - subagent_type: "pbr:planner"
-   - Prompt includes: "You are the ARCHITECT role in a planning team. Focus on: structure, file boundaries, dependency ordering, wave assignment. Write your output to `.planning/phases/{NN}-{slug}/team/architect-PLAN.md`. Do NOT write final PLAN.md files -- your output will be synthesized."
-   - Include phase goal, research doc paths, CONTEXT.md path in the prompt
+1. For each phase P in `through_phases` (in order):
+   a. Load phase P's context: goal, requirements, dependencies from ROADMAP.md
+   b. Load phase P's CONTEXT.md (if exists)
+   c. If P > first phase: include prior phase plans as accumulated context
+      - For each already-planned phase in this session, include:
+        - Plan frontmatter summary (provides, files_modified, must_haves)
+        - This gives the planner visibility into cross-phase dependencies
+   d. Spawn planner Task() with multi-phase instructions:
 
-   **Agent 2 -- Security Reviewer**:
-   - subagent_type: "pbr:planner"
-   - Prompt includes: "You are the SECURITY REVIEWER role in a planning team. Focus on: authentication checks, input validation tasks, secrets handling, permission boundaries. Write your output to `.planning/phases/{NN}-{slug}/team/security-PLAN.md`. Do NOT write final PLAN.md files."
-   - Include same context as Agent 1
+      Add to the planner prompt's `<planning_instructions>` block:
+      ```
+      MULTI-PHASE CONTEXT: This is phase {P} of {N} in a multi-phase planning session ({start} through {end}).
+      Prior phases planned in this session: {list of phase numbers and their provides}
 
-   **Agent 3 -- Test Designer**:
-   - subagent_type: "pbr:planner"
-   - Prompt includes: "You are the TEST DESIGNER role in a planning team. Focus on: test strategy, coverage targets, edge cases, which tasks should use TDD, integration test boundaries. Write your output to `.planning/phases/{NN}-{slug}/team/test-PLAN.md`. Do NOT write final PLAN.md files."
-   - Include same context as Agent 1
+      CROSS-PHASE CONFLICT DETECTION:
+      - Check files_modified in your plans against files_modified from prior phases
+      - If overlap detected: add a warning comment in the plan frontmatter: `cross_phase_conflict: ["{file} also modified in phase {X}"]`
+      - Ensure depends_on includes the conflicting prior phase plan
+      ```
 
-3. Wait for all three to complete
-4. Display to the user: `◐ Spawning synthesizer...`
+   e. Wait for planner to complete
+   f. Read the created plan frontmatters (provides, files_modified) to build accumulated context
+   g. Display: "Phase {P} planned ({N} plans). Proceeding to phase {P+1}..."
 
-   Spawn the synthesizer agent:
-   - subagent_type: "pbr:synthesizer"
-   - Prompt: "Read all files in `.planning/phases/{NN}-{slug}/team/`. Synthesize them into unified PLAN.md files in `.planning/phases/{NN}-{slug}/`. The architect output provides structure, the security output adds security-related tasks or checks, and the test output informs TDD flags and test tasks. Resolve any contradictions by preferring the architect's structure with security and test additions."
-5. Proceed to plan checking as normal
+2. After all phases planned, display summary:
+   ```
+   Multi-phase planning complete: {total_plans} plans across phases {start}-{end}
+   Cross-phase conflicts detected: {count} (see plan frontmatter for details)
+   ```
 
-If `--teams` is NOT set and `config.parallelization.use_teams` is false or unset, proceed with the existing single-planner flow below.
+3. Skip to Step 5b (spot-check) -- run spot-check across ALL phase directories that were planned.
 
 #### Single-Planner Flow (default)
 
-Display to the user: `◐ Spawning planner...`
+**Learnings injection (opt-in):** Check for planning and estimation learnings before spawning the planner:
+
+```bash
+node {resolved_plugin_root}/scripts/pbr-tools.cjs learnings query --tags "estimation,planning,process" 2>/dev/null
+```
+
+If non-empty JSON array returned:
+
+- Write to temp file and note as `{learnings_temp_path}`:
+
+  ```bash
+  node {resolved_plugin_root}/scripts/pbr-tools.cjs learnings query --tags "estimation,planning,process" > /tmp/pbr-learnings-$$.md
+  ```
+
+- Add as an additional `files_to_read` item in the planner prompt below
+
+If no learnings or command fails: omit.
+
+Display to the user: `◆ Spawning planner...`
 
 Spawn the planner Task() with all context inlined:
 
@@ -344,14 +487,19 @@ Task({
   prompt: <planning prompt>
 })
 
-NOTE: The pbr:planner subagent type auto-loads the agent definition. Do NOT inline it.
+NOTE: The pbr:planner subagent type auto-loads the agent definition.
+
+After planner completes, check for completion markers: `## PLANNING COMPLETE`, `## PLANNING FAILED`, or `## PLANNING INCONCLUSIVE`. Route accordingly. Do NOT inline it.
+
+**Memory capture:** Reference `skills/shared/memory-capture.md` — check planner output for `<memory_suggestion>` blocks and save any reusable knowledge discovered during planning.
 ```
 
-**Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
+**Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.cjs or template references included in the prompt.
 
 #### Planning Prompt Template
 
-Read `skills/plan/templates/planner-prompt.md.tmpl` and use it as the prompt template for spawning the planner agent. Fill in all placeholder blocks with phase-specific context:
+Read `${CLAUDE_SKILL_DIR}/templates/planner-prompt.md.tmpl` and use it as the prompt template for spawning the planner agent. Fill in all placeholder blocks with phase-specific context:
+
 - `<phase_context>` - phase number, directory, goal, requirements, dependencies, success criteria
 - `<project_context>` - locked decisions, user constraints, deferred ideas, phase-specific decisions
 - `<prior_work>` - manifest table of preceding phase SUMMARY.md file paths with status and one-line exports (NOT full bodies)
@@ -359,9 +507,25 @@ Read `skills/plan/templates/planner-prompt.md.tmpl` and use it as the prompt tem
 - `<config>` - max tasks, parallelization, TDD mode from config.json
 - `<planning_instructions>` - phase-specific planning rules and output path
 
+**Prepend this block to the planner prompt before sending:**
+
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+2. .planning/ROADMAP.md — phase goals, dependencies, and structure
+3. .planning/phases/{NN}-{slug}/RESEARCH.md — research findings (if exists)
+4. .planning/phases/{NN}-{slug}/CONTEXT.md — phase-level decisions and deferred items (if exists)
+5. .planning/phases/{prior_phase_dir}/SUMMARY-*.md — prior phase summaries with deferred items (if prior phase exists)
+{if learnings_temp_path exists}6. {learnings_temp_path} — cross-project learnings (estimation and planning patterns from past PBR projects){/if}
+</files_to_read>
+```
+
+Items 4-5 provide the planner with deferred items from the current phase CONTEXT.md and from prior phase SUMMARY.md files, enabling the deferred-items forward path. If `{learnings_temp_path}` was produced in the learnings injection step above, replace `{if...}{/if}` with the actual line. If no learnings were found, omit item 6 entirely. If no prior phase exists, omit item 5.
+
 Wait for the planner to complete.
 
-After the planner returns, read the plan files it created to extract counts. Display a completion summary:
+After the planner returns, read the plan files it created to extract counts. Display a completion summary using standardized status symbols (see `@references/ui-brand.md`):
 
 ```
 ✓ Planner created {N} plan(s) across {M} wave(s)
@@ -369,18 +533,42 @@ After the planner returns, read the plan files it created to extract counts. Dis
 
 Where `{N}` is the number of PLAN.md files written and `{M}` is the number of distinct wave values across those plans (from frontmatter).
 
+Present a wave execution table using standardized symbols:
+
+```
+Wave 1: ○ Plan 01, ○ Plan 02
+Wave 2: ○ Plan 03
+```
+
+Use `○` (pending) for all plans at this stage since none have been executed yet.
+
+### Step 5b: Spot-Check Planner Output
+
+CRITICAL (no hook): Verify planner output before proceeding.
+
+1. **PLAN files exist**: Check `.planning/phases/{NN}-{slug}/PLAN-*.md` files exist on disk
+2. **Valid frontmatter**: Read first 20 lines of each PLAN file — verify `depends_on`, `files_modified`, `must_haves` fields present
+3. **Task structure**: Verify at least one `<task>` block exists in each plan file
+4. **Plan count matches**: Number of PLAN files matches what the planner reported
+
+If ANY spot-check fails, present the user with options: **Retry** / **Continue anyway** / **Abort**
+
 ---
 
 ### Step 6: Plan Validation (delegated, conditional)
 
 **Skip this step if:**
-- Depth profile has `features.plan_checking: false`
+- Depth profile has `features.plan_checking: false` AND `--audit` flag is NOT set AND `features.inline_verify` is `true` in config (planner self-validates)
 
 To check: use the resolved depth profile from Step 1. The profile consolidates the depth setting and any user overrides into a single boolean.
 
+**Force validation:** If `--audit` flag is set, ALWAYS spawn the plan-checker agent regardless of depth profile or inline_verify setting. Display: `◆ Audit mode: spawning plan checker (--audit flag)`
+
+**Inline verify mode:** If `features.inline_verify` is `true` and `--audit` is NOT set, skip plan-checker spawn — the planner agent has already self-validated. Display: `✓ Planner self-validated (inline_verify enabled). Use --audit to force full plan-checker.`
+
 **If validation is enabled:**
 
-Display to the user: `◐ Spawning plan checker...`
+Display to the user: `◆ Spawning plan checker...`
 
 Spawn the plan checker Task():
 
@@ -393,15 +581,24 @@ Task({
 NOTE: The pbr:plan-checker subagent type auto-loads the agent definition. Do NOT inline it.
 ```
 
-**Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
+**Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.cjs or template references included in the prompt.
 
 #### Checker Prompt Template
 
-Read `skills/plan/templates/checker-prompt.md.tmpl` and use it as the prompt template for spawning the plan checker agent. Fill in the placeholders:
+Read `${CLAUDE_SKILL_DIR}/templates/checker-prompt.md.tmpl` and use it as the prompt template for spawning the plan checker agent. Fill in the placeholders:
 - `<plans_to_check>` - manifest table of PLAN.md file paths (checker reads each via Read tool)
 - `<phase_context>` - phase goal and requirement IDs
 - `<context>` - file paths to project-level and phase-level CONTEXT.md files (checker reads via Read tool)
 
+**Prepend this block to the checker prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/PLAN-*.md — plan files to validate
+2. .planning/CONTEXT.md — locked decisions to check against (if exists)
+</files_to_read>
+```
+
 **Process checker results:**
 
 After the plan checker returns, display its result:
@@ -415,11 +612,38 @@ After the plan checker returns, display its result:
 
 Reference: `skills/shared/revision-loop.md` for the full Check-Revise-Escalate pattern.
 
+**YAML Issue Parsing:** After the plan-checker returns with issues, parse the YAML `issues:` block from the checker output (located under the `## Issues` heading). Count BLOCKER and WARNING issues separately.
+
+**Issue Count Tracking:** Track `issue_count` per iteration. If the current iteration's `issue_count >= prev_issue_count` (count did not decrease), break early with:
+`⚠ Revision loop stalled (issue count not decreasing). Escalating to user.`
+
+**Iteration Display:** At the start of each iteration, display:
+`◆ Revision iteration {N}/3 — {blocker_count} blockers, {warning_count} warnings`
+
 Follow the revision loop pattern with:
-- **Producer**: planner (re-spawned with `skills/plan/templates/revision-prompt.md.tmpl`)
+- **Producer**: planner (re-spawned with `${CLAUDE_SKILL_DIR}/templates/revision-prompt.md.tmpl` — pass the YAML issues block verbatim in the `<checker_issues>` section)
 - **Checker**: plan-checker (back to Step 6)
+- **Early exit**: if issue count does not decrease between iterations, stop the loop and escalate
 - **Escalation**: present issues to user, offer "Proceed anyway" or "Adjust approach" (re-enter Step 5)
 
+```
+prev_issue_count = Infinity
+
+LOOP (iteration = 1 to 3):
+  1. Parse YAML issues from checker output
+  2. Count: blocker_count = issues where severity == "BLOCKER"
+           warning_count = issues where severity == "WARNING"
+           issue_count = blocker_count + warning_count
+  3. Display: ◆ Revision iteration {iteration}/3 — {blocker_count} blockers, {warning_count} warnings
+  4. If issue_count >= prev_issue_count:
+     → Display stall warning, escalate to user
+  5. prev_issue_count = issue_count
+  6. Read revision-prompt.md.tmpl, fill in YAML issues block
+  7. Re-spawn planner with revision prompt
+  8. Re-run plan-checker (Step 6)
+  9. If checker returns PASSED → exit loop, proceed to Step 8
+```
+
 ---
 
 ### Step 8: User Approval (inline, conditional)
@@ -427,28 +651,11 @@ Follow the revision loop pattern with:
 **Skip if:**
 - `gates.confirm_plan` is `false` in config
 - `mode` is `autonomous` in config
+- `auto_mode` is `true` — proceed as if user selected "Approve"
 
 **If approval is needed:**
 
-Present a summary of all plans to the user:
-
-```
-Phase {N}: {name}
-Plans: {count}
-
-Plan {phase}-01: {plan name} (Wave {W}, {task_count} tasks)
-  Must-haves: {list truths}
-  Files: {list files_modified}
-  Tasks:
-    1. {task name}
-    2. {task name}
-
-Plan {phase}-02: {plan name} (Wave {W}, {task_count} tasks)
-  ...
-
-Wave execution order:
-  Wave 1: Plan 01, Plan 02 (parallel)
-  Wave 2: Plan 03 (depends on 01, 02)
+Present a summary of all plans to the user. For each plan include: plan name, wave, task count, must-haves, files_modified. For each task include the task name. Add a wave execution order summary (Wave 1: Plan 01, 02 (parallel), Wave 2: Plan 03, etc.).
 
 Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prompts.md`):
   question: "Approve these {count} plans for Phase {N}?"
@@ -457,7 +664,6 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
     - label: "Approve"          description: "Proceed to build phase"
     - label: "Request changes"  description: "Discuss adjustments before proceeding"
     - label: "Abort"            description: "Cancel planning for this phase"
-```
 
 **If user selects 'Request changes' or 'Other':**
 - Discuss what needs to change
@@ -465,36 +671,37 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 - Or make small inline edits to plan files directly
 
 **If user selects 'Approve':**
-- **CONTEXT.md compliance reporting**: If `.planning/CONTEXT.md` exists, compare all locked decisions against the generated plans. Print: "CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks" where M = locked decisions that are reflected in at least one task, N = total locked decisions. If any locked decisions are unmapped, list them as warnings.
+- **CONTEXT.md compliance reporting**: Check locked decisions from BOTH sources:
+  a. Project-level: `.planning/CONTEXT.md` (if exists) — cross-cutting decisions for all phases
+  b. Phase-level: `.planning/phases/{NN}-{slug}/CONTEXT.md` (if exists) — phase-specific decisions
+     Phase-level decisions override project-level for the same decision area.
+
+  Collect ALL locked decisions from both files (deduplicate identical decision text).
+  Compare against the generated plan tasks. Print:
+  `CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks`
+  where M = locked decisions reflected in at least one task action, N = total unique locked decisions.
+  If any locked decisions are unmapped, list them as warnings.
+  If neither CONTEXT.md exists: skip this check silently.
 - **Dependency fingerprinting**: For each dependency phase (phases that this phase depends on, per ROADMAP.md):
   1. Find all SUMMARY.md files in the dependency phase directory
-  2. Compute a simple hash of each SUMMARY.md file (e.g., first 8 chars of a SHA-256 of the file content, or a simpler approach: use the file's byte length + last-modified timestamp as a fingerprint string)
-  3. Add a `dependency_fingerprints` field to each plan's YAML frontmatter:
-     ```yaml
-     dependency_fingerprints:
-       "01-01": "len:4856-mod:2025-02-08T09:40"
-       "01-02": "len:4375-mod:2025-02-08T09:43"
-     ```
-  4. This allows the build skill to detect if dependency phases were re-built after this plan was created
+  2. Compute a fingerprint string for each: `"len:{bytes}-mod:{mtime}"` and add as a `dependency_fingerprints` map in each plan's YAML frontmatter — this allows the build skill to detect stale plans if dependencies were rebuilt.
+- **Speculative mode guard:** If `$ARGUMENTS` contains `--speculative` or `--no-state-update`, SKIP all `state update` CLI calls in this section. Do NOT update STATE.md `status`, `current_phase`, or `plans_total` — the autonomous orchestrator manages state exclusively during speculative runs. Also SKIP the ROADMAP.md progress table update below.
 - **Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
-  **Tooling shortcut**: Use the CLI for atomic updates:
+  > Note: Use CLI for atomic writes — direct Write bypasses file locking.
+
   ```bash
   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-plans {phase} 0 {N}
   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status {phase} planned
   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update status planned
   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now
   ```
+- Update STATE.md via CLI **(CRITICAL (no hook) — update BOTH frontmatter AND body)**: set `status: "planned"`, `plans_total`, `last_command` in frontmatter AND update `Status:`, `Plan:` lines in body `## Current Position`
 
-  1. Open `.planning/ROADMAP.md`
-  2. Find the `## Progress` table
-  3. Locate the row matching this phase number
-  4. Update the `Plans Complete` column to `0/{N}` where N = number of plan files just created
-  5. Update the `Status` column to `planned`
-  6. Save the file — do NOT skip this step
-- Update STATE.md: set current phase plan status to "planned"
-- **If `features.auto_advance` is `true` AND `mode` is `autonomous`:** Chain directly to build: `Skill({ skill: "pbr:build", args: "{N}" })`. This continues the build→review→plan→build cycle automatically.
-- **Otherwise:** Suggest next action: `/pbr:build {N}`
+**Tooling shortcut**: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"planned","last_command":"/pbr:plan-phase {N}"}'`
+- **If `auto_mode` is `true`:** Set `features.auto_advance = true` and `mode = autonomous` behavior for the remainder of this invocation. Chain directly to build: `Skill({ skill: "pbr:build", args: "{N} --auto" })`. This continues the plan→build→review cycle automatically.
+- **Else if `features.auto_advance` is `true` AND `mode` is `autonomous`:** Chain directly to build: `Skill({ skill: "pbr:build", args: "{N}" })`. This continues the build→review→plan→build cycle automatically.
+- **Otherwise:** Suggest next action: `/pbr:execute-phase {N}`
 
 ---
 
@@ -502,7 +709,8 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 
 ### Subcommand: `add`
 
-**CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+**Speculative mode guard:** If `$ARGUMENTS` contains `--speculative` or `--no-state-update`, SKIP the `.active-skill` write below — the autonomous orchestrator owns `.active-skill` during speculative planning.
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 
 1. Read `.planning/ROADMAP.md`
 2. Calculate next phase number (last phase + 1)
@@ -512,14 +720,16 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 6. Append phase to ROADMAP.md
 7. Create phase directory: `.planning/phases/{NN}-{slug}/`
 8. Update STATE.md if needed
-9. Suggest: `/pbr:plan {N}` to plan the new phase
-10. Delete `.planning/.active-skill` if it exists.
+9. Suggest: `/pbr:plan-phase {N}` to plan the new phase
+10. **Speculative mode guard:** If `--speculative` is present, skip the delete below (nothing was written).
+    Delete `.planning/.active-skill` if it exists.
 
 ### Subcommand: `insert <N>`
 
-Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
+Reference: `${CLAUDE_SKILL_DIR}/decimal-phase-calc.md` for decimal numbering rules.
 
-**CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+**Speculative mode guard:** If `$ARGUMENTS` contains `--speculative` or `--no-state-update`, SKIP the `.active-skill` write below — the autonomous orchestrator owns `.active-skill` during speculative planning.
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 
 1. Read `.planning/ROADMAP.md`
 2. Calculate decimal phase number:
@@ -530,8 +740,9 @@ Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
 4. Insert phase into ROADMAP.md at the correct position
 5. Create phase directory: `.planning/phases/{NN.M}-{slug}/`
 6. Update dependencies of subsequent phases if affected
-7. Suggest: `/pbr:plan {N.M}` to plan the new phase
-8. Delete `.planning/.active-skill` if it exists.
+7. Suggest: `/pbr:plan-phase {N.M}` to plan the new phase
+8. **Speculative mode guard:** If `--speculative` is present, skip the delete below (nothing was written).
+   Delete `.planning/.active-skill` if it exists.
 
 ### Subcommand: `remove <N>`
 
@@ -540,7 +751,8 @@ Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
    - Phase must exist
    - Phase must be in `pending` or `not started` status (cannot remove completed/in-progress phases)
    - No other phases depend on this phase (or user confirms breaking dependencies)
-3. **CRITICAL: Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
+3. **Speculative mode guard:** If `$ARGUMENTS` contains `--speculative` or `--no-state-update`, SKIP the `.active-skill` write below — the autonomous orchestrator owns `.active-skill` during speculative planning.
+   **CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "plan" to `.planning/.active-skill` using the Write tool.
 4. Confirm with user: "Remove Phase {N}: {name}? This will delete the phase directory and renumber subsequent phases."
 5. If confirmed:
    - Delete `.planning/phases/{NN}-{slug}/` directory
@@ -548,7 +760,8 @@ Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
    - Renumber subsequent phases (N+1 becomes N, etc.)
    - Update all `depends_on` references in ROADMAP.md
    - Update STATE.md if needed
-6. Delete `.planning/.active-skill` if it exists.
+6. **Speculative mode guard:** If `--speculative` is present, skip the delete below (nothing was written).
+   Delete `.planning/.active-skill` if it exists.
 
 ---
 
@@ -557,11 +770,11 @@ Reference: `skills/plan/decimal-phase-calc.md` for decimal numbering rules.
 When invoked with `--gaps`:
 
 1. Read `.planning/phases/{NN}-{slug}/VERIFICATION.md`
-   - If no VERIFICATION.md exists: tell user "No verification report found. Run `/pbr:review {N}` first."
+   - If no VERIFICATION.md exists: tell user "No verification report found. Run `/pbr:verify-work {N}` first."
 2. Extract all gaps from the verification report
 3. Spawn planner Task() in Gap Closure mode:
 
-Read `skills/plan/templates/gap-closure-prompt.md.tmpl` and use it as the prompt template for the gap closure planner. Fill in the placeholders:
+Read `${CLAUDE_SKILL_DIR}/templates/gap-closure-prompt.md.tmpl` and use it as the prompt template for the gap closure planner. Fill in the placeholders:
 - `<verification_report>` - inline the FULL VERIFICATION.md content
 - `<existing_plans>` - inline all existing PLAN.md files for the phase
 - `<gap_closure_instructions>` - specify output path and gap_closure frontmatter flag
@@ -569,35 +782,33 @@ Read `skills/plan/templates/gap-closure-prompt.md.tmpl` and use it as the prompt
 4. After gap-closure plans are created:
    - Run plan checker (if enabled)
    - Present to user for approval
-   - Suggest: `/pbr:build {N} --gaps-only`
+   - Suggest: `/pbr:execute-phase {N} --gaps-only`
 
 ---
 
 ## Error Handling
 
 ### Phase not found
-If the specified phase doesn't exist in ROADMAP.md, display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
+If the specified phase doesn't exist in ROADMAP.md, use conversational recovery:
 
-Phase {N} not found in ROADMAP.md.
-
-**To fix:** Run `/pbr:status` to see available phases.
-```
+1. Run: `node ${CLAUDE_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:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
+If REQUIREMENTS.md or ROADMAP.md don't exist, use conversational recovery:
 
-Project not initialized. Missing REQUIREMENTS.md or ROADMAP.md.
-
-**To fix:** Run `/pbr:begin` first.
-```
+1. Run: `node ${CLAUDE_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:execute-phase {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:
@@ -608,43 +819,20 @@ If the researcher Task() fails, display:
 Continue to the planning step.
 
 ### Planner agent fails
-If the planner Task() fails, display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-Planner agent failed for Phase {N}.
-
-**To fix:**
-- Try again with `/pbr:plan {N} --skip-research`
-- Check `.planning/CONTEXT.md` for conflicting constraints
-```
+If the planner Task() fails, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Planner agent failure.
 
 ### Checker loops forever
-After 3 revision iterations without passing, display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-Plan checker failed to pass after 3 revision iterations for Phase {N}.
-
-**To fix:**
-- Review the remaining issues below and decide whether to proceed or revise manually
-- Run `/pbr:plan {N}` to restart planning from scratch
-```
-
+After 3 revision iterations without passing, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Checker loops.
 Present remaining issues and ask user to decide: proceed or intervene.
 
 ---
 
-## Files Created/Modified by /pbr:plan
+## Files Created/Modified by /pbr:plan-phase
 
 | File | Purpose | When |
 |------|---------|------|
 | `.planning/phases/{NN}-{slug}/RESEARCH.md` | Phase-specific research | Step 4 |
-| `.planning/phases/{NN}-{slug}/PLAN-{NN}.md` | Executable plan files | Step 5 |
+| `.planning/phases/{NN}-{slug}/{NN}-{MM}-PLAN.md` | Executable plan files | Step 5 |
 | `.planning/CONTEXT.md` | Updated with assumptions | Step 3 (--assumptions) |
 | `.planning/ROADMAP.md` | Plans Complete + Status → `planned`; updated for add/insert/remove | Step 8, Subcommands |
 | `.planning/STATE.md` | Updated with plan status | Step 8 |
@@ -653,50 +841,12 @@ Present remaining issues and ask user to decide: proceed or intervene.
 
 ## Cleanup
 
+**Speculative mode guard:** If `--speculative` is present, skip the delete below (nothing was written).
 Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
 
 ## Completion
 
 After planning completes, present:
 
-Use the branded stage banner from `references/ui-formatting.md`:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PLANNING PHASE {N} ✓                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {name}** — {plan_count} plans created
-
-Plans:
-  {phase}-01: {name} (Wave 1, {task_count} tasks)
-  {phase}-02: {name} (Wave 1, {task_count} tasks)
-  {phase}-03: {name} (Wave 2, {task_count} tasks)
-
-Wave execution:
-  Wave 1: Plans 01, 02 (parallel)
-  Wave 2: Plan 03
-```
-
-Then use the "Next Up" routing block:
-```
-
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Build Phase {N}** — execute these plans
-
-/pbr:build {N}
-
-<sub>/clear first → fresh context window</sub>
-
-
-
-**Also available:**
-- /pbr:plan {N} --assumptions — review assumptions first
-- /pbr:discuss {N} — talk through details before building
-
-
-```
+Use the branded stage banner and next-up block from `${CLAUDE_SKILL_DIR}/templates/completion-output.md.tmpl`.
+Fill in: `{N}` (phase number), `{phase-name}`, `{plan_count}`, `{plan_list_lines}` (one line per plan with wave and task count), `{wave_table_lines}` (one line per wave).