@sienklogic/plan-build-run 2.1.0 → 2.1.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,70 @@
+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/CONTEXT.md — locked decisions and constraints (if exists)
+3. .planning/STATE.md — current project state and progress
+</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 CONTEXT.md exists:}
+  - Project context (locked decisions): {absolute path to CONTEXT.md}
+</project_context>
+
+<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

@@ -11,14 +11,14 @@ allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► CONFIGURATION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► CONFIGURATION                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 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,37 +255,48 @@ 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:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► CONFIG UPDATED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► CONFIG UPDATED ✓                           ║
+╚══════════════════════════════════════════════════════════════╝
 
 Updated:
   depth: standard → quick
   models.executor: inherit → sonnet
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — settings saved
 
-`/pbr:status`
+`/pbr:progress`
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
-- `/pbr:config` — change more settings
+- `/pbr:settings` — change more settings
+
 
-───────────────────────────────────────────────────────────────
 ```
 
 ## Config Schema
@@ -242,6 +327,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,14 @@
 ---
 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
 ---
 
 **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().
 
@@ -19,9 +19,9 @@ This skill runs **inline** and may delegate to other skills via Task().
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► NEXT STEP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► NEXT STEP                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -33,6 +33,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.
 
 ---
 
@@ -51,6 +53,71 @@ Read `.planning/STATE.md` and determine current position:
 - 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 +126,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,30 +139,31 @@ 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**, 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. **All phases complete**: Verification passed on final phase, no more phases in ROADMAP.md → Stop. Display: "All phases are complete. Run `/pbr:milestone audit` to verify cross-phase integration, or `/pbr:milestone complete` to archive this milestone."
+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."
 
 ### Step 3: Execute
 
@@ -120,21 +188,23 @@ Where `{N}` is the current phase number determined from STATE.md in Step 1.
 
 After execution completes, display a branded completion:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STEP COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STEP COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
 
 ✓ Completed: {what was done}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Next action description}**
 
 `/pbr:continue` or `{specific command}`
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 **If `features.auto_advance` is `true` AND `mode` is `autonomous`:**

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

@@ -0,0 +1,58 @@
+---
+name: dashboard
+description: "Launch the PBR web dashboard for the current project."
+allowed-tools: Bash, Read
+argument-hint: "[--port 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. Begin executing immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DASHBOARD                                  ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+## Behavior
+
+1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3141`.
+
+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:
+
+   ```bash
+   npm run dashboard:install --prefix <repo-root>
+   ```
+
+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.
+
+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.
+   ```
+
+## 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 WebSockets.