@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -3,19 +3,21 @@ name: config
 description: "Configure settings: depth, model profiles, features, git, and gates."
 ---
 
+**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.**
+
 ## Step 0 — Immediate Output
 
 **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
 
@@ -23,8 +25,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
 
@@ -38,9 +42,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 ${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 ${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:
@@ -49,6 +119,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)
@@ -67,6 +138,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
@@ -112,10 +185,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:**
 
@@ -133,11 +207,11 @@ After setting depth, the profile is automatically resolved. Show the user the ef
   "Depth set to {value}. Effective profile:"
   Then display the profile summary (research, plan-check, verify, scan mappers, debug rounds, inline verify).
 
-To resolve the profile, run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth`
+To resolve the profile, run: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth`
 
 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":
@@ -167,6 +241,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"
@@ -178,37 +254,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 "${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
@@ -239,6 +326,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/cursor-pbr/skills/continue/SKILL.md

@@ -3,11 +3,13 @@ name: continue
 description: "Execute the next logical step automatically. No prompts, no decisions — just do it."
 ---
 
+**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 agent invocation.
+This skill runs **inline** and may delegate to other skills via Task().
 
 ---
 
@@ -16,9 +18,9 @@ This skill runs **inline** and may delegate to other skills via agent invocation
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► NEXT STEP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► NEXT STEP                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -29,7 +31,7 @@ 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
+- **Delegate** execution to the appropriate skill via Skill() or Task()
 
 ---
 
@@ -48,13 +50,21 @@ 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."
+
 If STATE.md doesn't exist, display:
 ```
-ERROR
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 No project state found.
 
-**To fix:** Run `/pbr:begin` first.
+**To fix:** Run `/pbr:new-project` first.
 ```
 
 #### Context Budget Guard
@@ -67,47 +77,48 @@ 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`
-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."
+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: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
 
 Based on the determined action, display the delegation indicator to the user:
 ```
-Delegating to /pbr:{skill} {args}...
+◐ Delegating to /pbr:{skill} {args}...
 ```
 
-Then invoke the appropriate skill. **NEVER read SKILL.md files into your context** — this wastes the main context budget with 500+ lines of instructions. Instead, invoke the skill directly:
+Then invoke the appropriate skill via the Skill tool. **NEVER read SKILL.md files into your context** — this wastes the main context budget with 500+ lines of instructions. Instead, use the Skill tool which runs the skill in a clean invocation:
 
-| Situation | Action | Skill to invoke |
+| Situation | Action | How |
 |-----------|--------|-----|
-| Gaps need closure | Plan gap closure | `/pbr:plan {N} --gaps` |
-| Build incomplete | Continue build | `/pbr:build {N}` |
-| Review needed | Run review | `/pbr:review {N}` |
-| Next phase needed | Plan next phase | `/pbr:plan {N+1}` |
-| Project not started | Plan phase 1 | `/pbr:plan 1` |
+| 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" })` |
 
 Where `{N}` is the current phase number determined from STATE.md in Step 1.
 
@@ -115,25 +126,27 @@ 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}
+✓ 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`:**
-After the delegated skill completes, immediately re-run Step 1-3 to determine and execute the NEXT action. Continue chaining until a hard stop is reached. This enables hands-free phase cycling: build->review->plan->build->...
+After the delegated skill completes, immediately re-run Step 1-3 to determine and execute the NEXT action. Continue chaining until a hard stop is reached. This enables hands-free phase cycling: build→review→plan→build→...
 
 ---
 

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

@@ -0,0 +1,57 @@
+---
+name: dashboard
+description: "Launch the PBR web dashboard for the current project."
+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 `${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 `${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.