@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plugins/pbr/skills/build/templates/continuation-prompt.md.tmpl

@@ -0,0 +1,26 @@
+You are the executor agent. Continue executing a plan from a checkpoint.
+
+<plan_summary>
+{plan_summary}
+</plan_summary>
+
+<plan_file>
+.planning/phases/{NN}-{slug}/{plan_id}-PLAN.md
+</plan_file>
+
+<completed_tasks>
+| Task | Commit | Status |
+|------|--------|--------|
+{task table rows}
+</completed_tasks>
+
+<checkpoint_resolution>
+User response to checkpoint: {user's response}
+Resume at: Task {N+1} (or re-execute checkpoint task with user's answer)
+</checkpoint_resolution>
+
+<project_context>
+{project context key-values}
+</project_context>
+
+Continue execution from the checkpoint. Skip completed tasks. Process the checkpoint resolution, then continue with remaining tasks. Write SUMMARY.md when done.

package/plugins/pbr/skills/build/templates/executor-prompt.md.tmpl

@@ -0,0 +1,77 @@
+You are the executor agent. Execute the following plan.
+
+<downstream_consumer>
+Your output will be consumed by:
+- **Verifier agent:** Reads executor output SUMMARY.md to verify work. Needs: key_files list, accomplishments, deviations from plan.
+- **Status skill:** Reads plan completion state. Needs: frontmatter with status field (complete/partial/blocked).
+- **Next plan executor:** Reads your SUMMARY.md for context on prior work. Needs: provides/requires fields and key decisions made.
+</downstream_consumer>
+
+<quality_gates>
+Before completing your SUMMARY.md, verify:
+- [ ] SUMMARY.md frontmatter is complete (phase, plan, status, provides, requires, key_files)
+- [ ] All key_files paths listed actually exist on disk
+- [ ] Every task has an associated commit
+- [ ] Deviations from plan are documented (or "None" stated explicitly)
+</quality_gates>
+
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/{plan_id}-PLAN.md — the full plan with task details
+2. .planning/PROJECT.md — project context and locked decisions (if exists)
+3. .planning/STATE.md — current project state and progress
+4. .planning/ROADMAP.md — phase goals and dependencies (read Phase {phase_num} section only)
+5. .planning/KNOWLEDGE.md — project knowledge base with rules, patterns, lessons (if exists)
+</files_to_read>
+
+<plan_summary>
+[Inline only the ## Summary section from PLAN.md]
+</plan_summary>
+
+<plan_file>
+.planning/phases/{NN}-{slug}/{plan_id}-PLAN.md
+</plan_file>
+
+<project_context>
+Project root: {absolute path to project root}
+Platform: {win32|linux|darwin}
+
+Config:
+  commit_format: {commit_format}
+  tdd_mode: {tdd_mode}
+  atomic_commits: {atomic_commits}
+
+Available context files (read via Read tool as needed):
+  - Config: {absolute path to config.json}
+  - State: {absolute path to STATE.md}
+{If PROJECT.md exists:}
+  - Project context (locked decisions): {absolute path to PROJECT.md}
+</project_context>
+
+<phase_goal>
+Phase {phase_num}: {phase_name}
+Goal: {phase_goal}
+</phase_goal>
+
+<prior_work>
+Completed plans in this phase:
+| Plan | Status | Commits | Summary File |
+|------|--------|---------|-------------|
+| {prior_work table rows} |
+
+Read any SUMMARY file via Read tool if you need details on what prior plans produced.
+</prior_work>
+
+Execute all tasks in the plan sequentially. For each task:
+0. Read the full plan file from the path in <plan_file> to get task details
+1. Execute the <action> steps
+2. Run the <verify> commands
+3. Create an atomic commit with format: {commit_format}
+4. Record the commit hash
+
+After all tasks complete:
+1. Write SUMMARY.md to .planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md
+2. Run self-check (verify files exist, commits exist, verify commands still pass)
+3. Return your SUMMARY.md content as your final response
+
+If you hit a checkpoint task, STOP and return the checkpoint response format immediately.

package/plugins/pbr/skills/build/templates/inline-verifier-prompt.md.tmpl

@@ -0,0 +1,33 @@
+<downstream_consumer>
+Your verification report will be consumed by:
+- **Executor agent:** Reads inline verification to decide whether to proceed or fix. Needs: pass/fail status and specific failure details with file paths.
+- **Review skill:** Reads verification report for must_haves results. Needs: each must_have checked and reported individually.
+- **Dashboard:** Displays verification status. Needs: binary pass/fail status per check.
+</downstream_consumer>
+
+<quality_gates>
+Your verification must satisfy:
+- [ ] Every must_have from the plan is checked and reported
+- [ ] Failure details include file path and expected vs actual
+- [ ] Automated checks are run (not just visual inspection)
+- [ ] Verification status is binary (PASS/FAIL, not "mostly works")
+</quality_gates>
+
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/{plan_id}-PLAN.md — must-haves to verify against
+2. .planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md — what the executor claims was built
+3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
+</files_to_read>
+
+Targeted inline verification for plan {plan_id}.
+
+Verify ONLY these files: {comma-separated key_files list}
+
+For each file, check three layers:
+1. Existence — does the file exist?
+2. Substantiveness — is it more than a stub? (>10 lines, no TODO/FIXME placeholders)
+3. Wiring — is it imported/used by at least one other file?
+
+Report PASS or FAIL with a one-line reason per file.
+Write nothing to disk — just return your results as text.

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

@@ -18,7 +18,7 @@ allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 
 Then proceed to Step 1.
 
-# /pbr:config — Configure Plan-Build-Run
+# /pbr:settings — Configure Plan-Build-Run
 
 ## Overview
 
@@ -26,8 +26,10 @@ Reads and writes `.planning/config.json`. Interactive configuration with AskUser
 
 ## References
 
-- `references/planning-config.md` — Full config.json schema (54 fields, 16 feature toggles, validation rules)
+- `references/config-reference.md` — Full config.json schema (54 fields, 16 feature toggles, validation rules)
 - `references/model-profiles.md` — Model selection guide for agent spawning
+- `references/questioning.md` — Questioning philosophy for config decision guidance
+- `references/ui-brand.md` — Status symbols, banners, formatting for config display output
 
 ## Flow
 
@@ -41,9 +43,75 @@ Read `.planning/config.json`. If it doesn't exist, display:
 
 No Plan-Build-Run project found.
 
-**To fix:** Run `/pbr:begin` first.
+**To fix:** Run `/pbr:new-project` first.
 ```
 
+### 1b. Quick Start Path (no arguments, first-time configuration)
+
+If no `$ARGUMENTS` provided and this is the first time running `/pbr:settings` interactively (no prior config changes detected), present:
+
+Use AskUserQuestion:
+  question: "How would you like to configure?"
+  header: "Setup"
+  options:
+    - label: "Quick Start (recommended)"
+      description: "Answer 4 essential questions, sensible defaults for everything else"
+    - label: "Advanced (all fields)"
+      description: "Full config with 54 fields for granular customization"
+
+**If user selects "Quick Start":**
+
+First, check for global defaults: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config load-defaults`
+If defaults exist, use them as pre-populated values. Otherwise, use hardcoded defaults shown below.
+
+Present 4 essential questions sequentially:
+
+**Q1. Mode:**
+Use AskUserQuestion:
+  question: "How do you want to work?"
+  header: "Mode"
+  options:
+    - label: "Interactive (default)"  description: "Pause at key gates for your approval"
+    - label: "Autonomous"             description: "Auto-proceed, only stop for critical decisions"
+
+**Q2. Depth:**
+Use AskUserQuestion:
+  question: "How thorough should planning be?"
+  header: "Depth"
+  options:
+    - label: "Standard (default)"     description: "5-8 phases, includes research"
+    - label: "Quick"                  description: "3-5 phases, skip research, ~50% cheaper"
+    - label: "Comprehensive"          description: "8-12 phases, full deep research, ~2x cost"
+
+**Q3. Parallel agents:**
+Use AskUserQuestion:
+  question: "Run agents in parallel when possible?"
+  header: "Parallel"
+  options:
+    - label: "Yes (default)"          description: "Parallel execution of independent plans"
+    - label: "No"                     description: "Sequential execution only"
+
+**Q4. Git branching:**
+Use AskUserQuestion:
+  question: "Git branching strategy?"
+  header: "Branching"
+  options:
+    - label: "Phase (default, recommended)"  description: "Branch per phase for safe undo"
+    - label: "None"                          description: "All work on current branch"
+
+After 4 answers, write config.json with all other fields set to sensible defaults.
+
+**Quick Start defaults:** mode=interactive, depth=standard, parallel=true, git.branching=phase
+
+After writing config, offer: "Save these as your global defaults for future projects? (y/n)"
+If yes, run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config save-defaults`
+
+Display: "Config written. For full field reference, see `references/config-reference.md`."
+
+Skip to Step 4 (Apply Changes confirmation).
+
+**If user selects "Advanced":** proceed to Step 3 (Interactive Mode) below.
+
 ### 2. Parse Arguments
 
 If `$ARGUMENTS` is provided, handle direct setting:
@@ -52,6 +120,7 @@ If `$ARGUMENTS` is provided, handle direct setting:
 - `model-profile quality|balanced|budget|adaptive` — set all models at once using a preset
 - `gate <gate-name> on|off` — toggle a gate
 - `feature <feature-name> on|off` — toggle a feature (e.g., `feature auto_continue on`). When the user specifies a feature name without the `features.` prefix, automatically prepend `features.` before writing to config.
+- `session_phase_limit <N>` — set the session phase limit directly (e.g., `/pbr:settings session_phase_limit 5`). Validate N is an integer between 0 and 20. Write to config.json at top level: `"session_phase_limit": N`. Display: "Session phase limit set to {N}. PBR will suggest pausing after {N} phases per session. (0 = disabled)"
 - `git branching none|phase|milestone|disabled` — set branching strategy
 - `git mode disabled` — disable git integration entirely
 - `show` — display current config (default when no args)
@@ -70,6 +139,8 @@ Workflow:
     Scan mappers: 4   Debug rounds: 5   Inline verify: off
   Mode: interactive
   Context Strategy: aggressive
+  Session Phase Limit: 3 (pause after 3 phases)
+  # When session_phase_limit is 0, display: "Session Phase Limit: disabled"
 
 Features:
   ✓ Structured planning    ✓ Goal verification
@@ -115,10 +186,11 @@ Use AskUserQuestion:
     - label: "Depth"          description: "quick/standard/comprehensive"
     - label: "Model profile"  description: "quality/balanced/budget/adaptive"
     - label: "Features"       description: "Toggle workflow features, gates, status line"
-    - label: "Git settings"   description: "branching strategy, commit mode"
+    - label: "Git settings"      description: "branching strategy, commit mode"
+    - label: "Save as defaults"  description: "Save current config as user-level defaults for new projects"
   multiSelect: false
 
-Note: The original 7 categories are condensed to 4. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features".
+Note: The original 7 categories are condensed to 5. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features". "Save as defaults" exports to ~/.claude/pbr-defaults.json.
 
 **Follow-up based on selection:**
 
@@ -140,7 +212,7 @@ To resolve the profile, run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js co
 
 If the user wants to override a specific profile setting, they can set `depth_profiles.{depth}.{key}` directly.
 For example: to use quick mode but keep plan-checking, the user would set depth to quick and then override:
-  `/pbr:config` -> Features -> Plan checking -> Enable
+  `/pbr:settings` -> Features -> Plan checking -> Enable
 This writes `depth_profiles.quick.features.plan_checking: true` to config.json.
 
 If user selects "Model profile":
@@ -170,6 +242,8 @@ Use AskUserQuestion:
 
 Repeat for each feature the user wants to change. Show updated status after each toggle.
 
+For numeric settings like `session_phase_limit`, use the direct command: `/pbr:settings session_phase_limit <N>`
+
 If user selects "Git settings":
 Use AskUserQuestion:
   question: "Select branching strategy"
@@ -181,11 +255,35 @@ Use AskUserQuestion:
     - label: "Disabled"    description: "No git integration"
   multiSelect: false
 
+If user selects "Save as defaults":
+Save current project config as user-level defaults for future projects:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" config save-defaults
+```
+
+Display: "Saved your preferences to ~/.claude/pbr-defaults.json. New projects created with /pbr:setup will use these as starting values."
+
 If user types something else (freeform): interpret as a direct setting command and handle via Step 2 argument parsing logic.
 
 ### 4. Apply Changes
 
-Update config.json with new values. Show what changed with a branded completion:
+**CRITICAL (no hook) -- DO NOT SKIP: Write updated config.json to disk.**
+
+Update config.json with new values.
+
+#### 4b. Commit Config Changes
+
+Reference: `skills/shared/commit-planning-docs.md` for the commit pattern.
+
+Read `.planning/config.json` and check `planning.commit_docs` (or `git.commit_docs`).
+If true, commit the modified config.json:
+
+```text
+docs(config): update config — {changed_fields}
+```
+
+Show what changed with a branded completion:
 ```
 ╔══════════════════════════════════════════════════════════════╗
 ║  PLAN-BUILD-RUN ► CONFIG UPDATED ✓                           ║
@@ -203,7 +301,7 @@ Updated:
 
 **Continue your workflow** — settings saved
 
-`/pbr:status`
+`/pbr:progress`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -211,7 +309,7 @@ Updated:
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
-- `/pbr:config` — change more settings
+- `/pbr:settings` — change more settings
 
 
 ```
@@ -244,6 +342,7 @@ The `model-profile` command sets all agent models at once:
 |---------|-----|---------|-------------|
 | Auto-continue | `features.auto_continue` | `false` | Automatically spawn continuation agents without user prompt |
 | Auto-advance | `features.auto_advance` | `false` | Chain build→review→plan automatically in autonomous mode |
+| Session phase limit | `session_phase_limit` | `3` | Maximum phases per session before auto-pause. 0 disables. Requires `auto_continue: true`. |
 | Team discussions | `features.team_discussions` | `false` | Enable team-based discussion workflows |
 
 **Team boundaries**: Teams are NEVER used for execution, planning, or verification. Teams are only for discussion and brainstorming workflows. All execution, planning, and verification use single-agent Task() spawns with proper subagent types.

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

@@ -1,14 +1,15 @@
 ---
 name: continue
 description: "Execute the next logical step automatically. No prompts, no decisions — just do it."
-allowed-tools: Read, Write, Bash, Glob, Grep, Task
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, Skill
+argument-hint: "[--auto]"
 ---
 
 **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:continue — Action-Oriented Resumption
 
-You are running the **continue** skill. Unlike `/pbr:resume` which shows status and suggests actions, `/pbr:continue` determines and EXECUTES the next logical step automatically.
+You are running the **continue** skill. Unlike `/pbr:progress` which shows the dashboard and suggests the next action, `/pbr:continue` determines and EXECUTES the next logical step automatically. Stops safely at milestones, checkpoints, errors, and verification gaps.
 
 This skill runs **inline** and may delegate to other skills via Task().
 
@@ -33,6 +34,8 @@ Reference: `skills/shared/context-budget.md` for the universal orchestrator rule
 Additionally for this skill:
 - **Minimize** state reads — read only STATE.md lines 1-20 to determine next action
 - **Delegate** execution to the appropriate skill via Skill() or Task()
+- **At context >= 500k (context_window_tokens >= 500000)**: Read full ROADMAP.md (already required), glob phase frontmatters, read PROJECT.md out-of-scope section. Total additional reads: ~10-30 small frontmatter reads.
+- **At context < 500k (context_window_tokens < 500000)**: No change — reads only STATE.md lines 1-20 as before.
 
 ---
 
@@ -46,11 +49,83 @@ Additionally for this skill:
 
 ### Step 1: Read State
 
+Parse `$ARGUMENTS`:
+- If `--auto` is present in `$ARGUMENTS`: set `auto_mode = true`. Log: "Auto mode enabled — passing --auto to delegated skills"
+
+| Argument | Meaning |
+|----------|---------|
+| `--auto` | Pass --auto flag to all delegated skills, increase consecutive chain limit from 6 to 20 |
+
 Read `.planning/STATE.md` and determine current position:
 - Current phase number and name
 - Current plan progress
 - Phase status (planning, building, reviewing, complete)
 
+Then read `.planning/ROADMAP.md` to identify the current milestone boundary:
+- Find which `## Milestone:` section contains the current phase
+- Determine if the current phase is the **last phase** in that milestone section
+- If this is the last phase and it is verified/complete, warn: "This is the final phase of milestone {name}. After verification, run `/pbr:milestone` to complete it."
+- If the current phase's `Depends on` references a phase from the **previous** milestone that is not yet complete, warn: "Cross-milestone dependency: Phase {N} depends on Phase {M} from milestone {prev}, which is not yet complete."
+
+#### Lookahead Mode (context >= 500k)
+
+Before proceeding to Step 2, check the configured context window:
+
+```bash
+node scripts/pbr-tools.cjs config get context_window_tokens
+```
+
+If the returned value is **>= 500000**, perform the following lookahead reads before moving to Step 2. If the value is **< 500000** (or the command fails), skip this section entirely and proceed to Step 2 with no changes to behavior.
+
+**Lookahead reads:**
+
+1. You have already read full ROADMAP.md (required above). Extract every phase entry:
+   - Phase number (NN from slug)
+   - Phase slug
+   - `Depends on:` list
+
+2. Glob all phase summary and state frontmatters:
+   - `Glob({ pattern: ".planning/phases/*/SUMMARY-*.md" })` — read frontmatter only (lines 1-20) for each result
+   - `Glob({ pattern: ".planning/phases/*/STATE.md" })` — read frontmatter only (lines 1-10) for each result
+   - Build a map: `{ phase_slug -> { status, provides, requires } }`
+
+3. Read `PROJECT.md` section `## Out of Scope` (or `### Out of Scope`) — extract deferred items as a list.
+
+**Lookahead analysis (perform after reads above):**
+
+**A. Parallel phase candidates**
+
+For each pair of phases that are both Pending/Planning status:
+- Extract their `Depends on:` sets
+- If their dependency sets are **disjoint** (no shared dependency, and neither depends on the other), they are parallel candidates
+- Display:
+  ```
+  ► Parallel opportunity: Phase {A} and Phase {B} have no shared dependencies — they can be planned and built concurrently.
+  ```
+  Show at most 3 parallel pairs to avoid noise.
+
+**B. Dependency inversion warnings**
+
+For each phase entry in ROADMAP.md, for each item in its `Depends on:` list:
+- Extract the phase number of the dependency (parse `NN` from the slug prefix)
+- If dependency phase number > current phase number → dependency inversion detected
+- Display:
+  ```
+  ⚠ Dependency inversion: Phase {N} ({slug}) lists Phase {M} ({dep-slug}) as a dependency, but Phase M > Phase N. Check roadmap ordering.
+  ```
+
+**C. Deferred item surfacing**
+
+For each item in the PROJECT.md out-of-scope list:
+- Check if the item mentions a phase or capability that is now shown as Complete in the phase map
+- If so, display:
+  ```
+  ► Deferred item may be unblocked: "{item}" — the phase it depends on is now complete. Consider adding it to the next milestone.
+  ```
+  Surface at most 2 items to avoid noise.
+
+Display all findings BEFORE proceeding to Step 2. If no findings exist (no parallel pairs, no inversions, no unblocked deferred items), display nothing — do not add noise when there is nothing to report.
+
 If STATE.md doesn't exist, display:
 ```
 ╔══════════════════════════════════════════════════════════════╗
@@ -59,7 +134,7 @@ If STATE.md doesn't exist, display:
 
 No project state found.
 
-**To fix:** Run `/pbr:begin` first.
+**To fix:** Run `/pbr:new-project` first.
 ```
 
 #### Context Budget Guard
@@ -72,31 +147,51 @@ Before proceeding to priority evaluation, check for runaway continue chains:
    - Check `.planning/.active-skill` file — if it contains `continue`, treat as a chained continue
    - Check STATE.md `last_action` field — if it contains `continue`, treat as a chained continue
    - If neither source is available, assume this is the first invocation (do not warn)
-4. **If this is the 3rd consecutive `/pbr:continue` in a row**, display:
+4. **If this is the 6th consecutive `/pbr:continue` in a row** (or 20th if `auto_mode` is true), display:
 
 ```
-WARNING: Context budget warning: 3 consecutive auto-continues detected.
-Recommend running /pbr:pause then resuming in a fresh session.
+WARNING: Context budget warning: 6 consecutive auto-continues detected.
+Recommend running /pbr:pause-work then resuming in a fresh session.
 ```
 
 Then present the user with a choice:
 - **"Continue"** — proceed with the next action
-- **"Pause"** — run `/pbr:pause` logic to save state and stop
+- **"Pause"** — run `/pbr:pause-work` logic to save state and stop
 
 This prevents runaway chains that fill the context window without a human checkpoint.
 
 ### Step 2: Scan for Priority Items
 
-Check the resumption priority hierarchy (same as /pbr:resume):
+Check the resumption priority hierarchy (same as /pbr:resume-work):
 
-1. **UAT Blockers**: VERIFICATION.md with `status: gaps_found` → Execute `/pbr:plan {N} --gaps`
+1. **UAT Blockers**: VERIFICATION.md with `status: gaps_found` → Execute `/pbr:plan-phase {N} --gaps`
 2. **Checkpoint pending**: `.checkpoint-manifest.json` with pending items → Resume the build
 3. **Continue-here file**: `.continue-here.md` exists → Follow its next step
-4. **Incomplete build**: PLAN.md files without SUMMARY.md → Execute `/pbr:build {N}`
-5. **Unverified phase**: All plans complete, no VERIFICATION.md → Execute `/pbr:review {N}`
-6. **Phase complete, more phases exist**: Verification passed → Execute `/pbr:plan {N+1}`
-7. **Last phase in current milestone complete**: Verification passed on the last phase of the current milestone's phase range → Stop. Display: "Milestone complete! Run `/pbr:milestone audit` to verify cross-phase integration, then `/pbr:milestone complete` to archive."
-8. **Between milestones**: Current milestone is marked complete in STATE.md, but more milestones exist or user needs to create the next one → Stop. Display: "Current milestone is complete. Run `/pbr:milestone new` to start the next milestone, or `/pbr:milestone audit` if not yet audited."
+4. **Incomplete build**: PLAN.md files without SUMMARY.md → Execute `/pbr:execute-phase {N}`
+5. **Unverified phase**: All plans complete, no VERIFICATION.md → Execute `/pbr:verify-work {N}`
+6. **Phase complete, more phases exist**: Verification passed → Execute `/pbr:plan-phase {N+1}`
+7. **Last phase in current milestone complete**: Verification passed on the last phase of the current milestone's phase range → Stop. Display: "Milestone complete! Run `/pbr:audit-milestone` to verify cross-phase integration, then `/pbr:complete-milestone` to archive."
+8. **Between milestones**: Current milestone is marked complete in STATE.md, but more milestones exist or user needs to create the next one → Stop. Display: "Current milestone is complete. Run `/pbr:new-milestone` to start the next milestone, or `/pbr:audit-milestone` if not yet audited."
+
+#### Status-Based Routing (13 valid statuses)
+
+When the priority hierarchy above doesn't match, route based on the current phase status from STATE.md:
+
+| Status | Next Action |
+|--------|-------------|
+| `not_started` | Suggest `/pbr:discuss-phase {N}` or `/pbr:plan-phase {N}` |
+| `discussed` | Suggest `/pbr:plan-phase {N}` |
+| `ready_to_plan` | Suggest `/pbr:plan-phase {N}` |
+| `planning` | Wait for planner to complete, or re-run `/pbr:plan-phase {N}` |
+| `planned` | Suggest `/pbr:build {N}` |
+| `ready_to_execute` | Suggest `/pbr:build {N}` |
+| `building` | Resume build with `/pbr:build {N}` |
+| `built` | Read `workflow.validate_phase` from config.json (default: `true`). If true: suggest `/pbr:validate-phase {N}`. If false: suggest `/pbr:review {N}`. **Secondary:** If `workflow.suggest_test_generation` is `true` (default: `true`) AND the phase has no `TESTING.md` or test coverage is unknown, also display advisory: "Test coverage not tracked for this phase. Consider `/pbr:test {N}` to generate tests before review." |
+| `partial` | Resume build with `/pbr:build {N}` |
+| `verified` | Suggest `/pbr:plan-phase {N+1}` or milestone completion |
+| `needs_fixes` | Suggest `/pbr:plan-phase {N} --gaps` |
+| `complete` | Advance to next phase or milestone completion |
+| `skipped` | Advance to next phase |
 
 ### Step 3: Execute
 
@@ -109,11 +204,13 @@ Then invoke the appropriate skill via the Skill tool. **NEVER read SKILL.md file
 
 | Situation | Action | How |
 |-----------|--------|-----|
-| Gaps need closure | Plan gap closure | `Skill({ skill: "pbr:plan", args: "{N} --gaps" })` |
-| Build incomplete | Continue build | `Skill({ skill: "pbr:build", args: "{N}" })` |
-| Review needed | Run review | `Skill({ skill: "pbr:review", args: "{N}" })` |
-| Next phase needed | Plan next phase | `Skill({ skill: "pbr:plan", args: "{N+1}" })` |
-| Project not started | Plan phase 1 | `Skill({ skill: "pbr:plan", args: "1" })` |
+| Gaps need closure | Plan gap closure | `Skill({ skill: "pbr:plan", args: "{N} --gaps" })` (append `--auto` if `auto_mode`) |
+| Build incomplete | Continue build | `Skill({ skill: "pbr:build", args: "{N}" })` (append `--auto` if `auto_mode`) |
+| Validate needed (`built` + `workflow.validate_phase: true`) | Run validate-phase | `Skill({ skill: "pbr:validate-phase", args: "{N}" })` (append `--auto` if `auto_mode`) |
+| Test generation needed (built + `workflow.suggest_test_generation: true` + no TESTING.md) | Suggest test generation | Display: "Advisory: `/pbr:test {N}` — generate tests before review" (do NOT auto-delegate; leave as user-visible suggestion only) |
+| Review needed (validate_phase disabled or already validated) | Run review | `Skill({ skill: "pbr:review", args: "{N}" })` (append `--auto` if `auto_mode`) |
+| Next phase needed | Plan next phase | `Skill({ skill: "pbr:plan", args: "{N+1}" })` (append `--auto` if `auto_mode`) |
+| Project not started | Plan phase 1 | `Skill({ skill: "pbr:plan", args: "1" })` (append `--auto` if `auto_mode`) |
 
 Where `{N}` is the current phase number determined from STATE.md in Step 1.
 
@@ -158,6 +255,8 @@ In these cases, explain why auto-continue stopped and what the user needs to do.
 
 ---
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ## Anti-Patterns
 
 1. **DO NOT** ask the user what to do — determine it from state

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

@@ -21,21 +21,33 @@ Then proceed to Step 1.
 
 ## Behavior
 
-1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.
+1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3141`.
 
-2. **Check dependencies**: Check if `${CLAUDE_PLUGIN_ROOT}/dashboard/node_modules/` exists. If not, run:
-   ```
-   npm install --prefix ${CLAUDE_PLUGIN_ROOT}/dashboard
-   ```
+2. **Locate dashboard**: The dashboard lives at the **repository root** `dashboard/` directory (NOT under `${CLAUDE_PLUGIN_ROOT}`). Resolve the repo root from `<cwd>` — for PBR's own repo this is the project root; for installed plugins, use `git rev-parse --show-toplevel` or walk up from `${CLAUDE_PLUGIN_ROOT}` to find `dashboard/`.
+
+3. **Check dependencies**: Check if `<repo-root>/dashboard/server/node_modules/` exists. If not, run:
 
-3. **Launch dashboard**: Run in background via Bash:
+   ```bash
+   npm run dashboard:install --prefix <repo-root>
    ```
-   node ${CLAUDE_PLUGIN_ROOT}/dashboard/bin/cli.js --dir <cwd> --port <port> &
+
+4. **Launch dashboard**: Run in background via Bash:
+
+   ```bash
+   node <repo-root>/dashboard/bin/cli.cjs --dir <cwd> --port <port> &
    ```
+
    Use `&` to background the process so it doesn't block the session.
 
-4. **Output to user**:
+5. **Verify startup**: After launching, check the process is responding:
+
+   ```bash
+   curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/
    ```
+
+6. **Output to user**:
+
+   ```text
    Dashboard running at http://localhost:<port>
    Open this URL in your browser to view your project's planning state.
    ```
@@ -43,4 +55,4 @@ Then proceed to Step 1.
 ## Notes
 
 - If the port is already in use, the dashboard will fail to start — suggest the user try a different port with `--port`.
-- The dashboard watches `.planning/` for live updates via SSE.
+- The dashboard watches `.planning/` for live updates via WebSockets.