@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/cursor-pbr/references/ui-formatting.md

@@ -1,6 +1,7 @@
-<!-- canonical: ../../pbr/references/ui-formatting.md -->
 # Plan-Build-Run UI Brand & Formatting Reference
 
+> **Migration note:** Skills are being migrated to these patterns. See Phase 5 for skill-level updates.
+
 Consistent output formatting for all Plan-Build-Run skills. Every skill that produces user-facing output should follow these patterns.
 
 ## Stage Banners
@@ -8,9 +9,9 @@ Consistent output formatting for all Plan-Build-Run skills. Every skill that pro
 Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {STAGE NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {STAGE NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Stage names (uppercase):**
@@ -22,7 +23,7 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 - `EXECUTING WAVE {N}`
 - `VERIFYING`
 - `PHASE {N} COMPLETE ✓`
-- `MILESTONE COMPLETE 🎉`
+- `MILESTONE COMPLETE`
 - `SCANNING CODEBASE`
 - `DEBUGGING`
 
@@ -34,9 +35,9 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 Format:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {SKILL NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {SKILL NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Skill names (uppercase):**
@@ -86,14 +87,13 @@ Use these patterns for consistent visual hierarchy within sections:
 
 | Status | Indicator | Usage |
 |--------|-----------|-------|
-| Complete | `✓` | Completed items, passed checks |
-| Failed | `✗` | Failed verification, missing items |
+| Complete | `✓` | Completed items, passed checks, verified |
+| Failed | `✗` | Failed verification, missing items, blocked |
+| In Progress | `◆` | Currently executing |
 | Pending | `○` | Not yet started |
-| In Progress | `◐` | Currently executing |
-| Needs Human | `?` | Requires human verification |
-| Warning | `⚠` | Warnings, non-blocking issues |
-| Blocked | `⊘` | Blocked by dependency |
 | Auto-approved | `⚡` | Automatically approved (gates) |
+| Warning | `⚠` | Warnings, non-blocking issues |
+| Milestone | `🎉` | Milestone complete (banner only) |
 
 ---
 
@@ -114,7 +114,7 @@ Plans: 2/5 complete
 **Build progress (wave tracking):**
 ```
 Wave 1: ✓ Plan 01, ✓ Plan 02
-Wave 2: ◐ Plan 03 (executing)
+Wave 2: ◆ Plan 03 (executing)
 Wave 3: ○ Plan 04
 ```
 
@@ -130,9 +130,9 @@ Tasks: 2/4 complete
 Show when agents are being launched:
 
 ```
-◐ Spawning executor...
+◆ Spawning executor...
 
-◐ Spawning 4 executors in parallel...
+◆ Spawning 4 executors in parallel...
   → Plan 01: Database Schema
   → Plan 02: Auth Service
   → Plan 03: API Routes
@@ -143,7 +143,7 @@ Show when agents are being launched:
 
 For research agents:
 ```
-◐ Spawning 4 researchers in parallel...
+◆ Spawning 4 researchers in parallel...
   → Stack research
   → Features research
   → Architecture research
@@ -156,7 +156,7 @@ For research agents:
 
 ## Checkpoint Boxes
 
-User action required. Use double-line box drawing, 62-character width.
+User action required. Use double-line box drawing, 62-character inner width.
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
@@ -165,9 +165,7 @@ User action required. Use double-line box drawing, 62-character width.
 
 {Content}
 
-──────────────────────────────────────────────────────────────
 → {ACTION PROMPT}
-──────────────────────────────────────────────────────────────
 ```
 
 **Types:**
@@ -240,8 +238,8 @@ options:
 question: "What would you like to do next?"
 header: "Next Step"
 options:
-  - label: "/pbr:build 3"    description: "Execute phase 3 plans"
-  - label: "/pbr:review 2"   description: "Verify phase 2 results"
+  - label: "/pbr:execute-phase 3"    description: "Execute phase 3 plans"
+  - label: "/pbr:verify-work 2"   description: "Verify phase 2 results"
   - label: "Something else"  description: "Enter a different command"
 ```
 
@@ -254,6 +252,10 @@ Do not use AskUserQuestion for:
 
 Use plain conversational prompts for these cases instead.
 
+### Cross-Reference
+
+For questioning philosophy, when to use/not use AskUserQuestion, freeform rule, and decision gate patterns, see `references/questioning.md`.
+
 ---
 
 ## Next Up Block
@@ -261,31 +263,27 @@ Use plain conversational prompts for these cases instead.
 Always present at end of major completions (phase complete, milestone complete, project init).
 
 ```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Identifier}: {Name}** — {one-line description}
 
 `{copy-paste command}`
 
 <sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
+```
 
 **Also available:**
 - `/pbr:alternative-1` — description
 - `/pbr:alternative-2` — description
 
-───────────────────────────────────────────────────────────────
-```
-
 **Shorter routing (for minor completions):**
 ```
 What's next?
-→ /pbr:plan 4 — plan the next phase
-→ /pbr:review 3 — review what was just built
-→ /pbr:status — see full project status
+→ /pbr:plan-phase 4 — plan the next phase
+→ /pbr:verify-work 3 — review what was just built
+→ /pbr:progress — see full project status
 ```
 
 ---
@@ -313,7 +311,7 @@ Use tables for structured data:
 |-------|--------|-------|----------|
 | 1. Foundation | ✓ Complete | 3/3 | 100% |
 | 2. Database | ✓ Complete | 2/2 | 100% |
-| 3. Auth | ◐ Building | 1/3 | 33% |
+| 3. Auth | ◆ Building | 1/3 | 33% |
 | 4. Frontend | ○ Pending | 0/4 | 0% |
 ```
 
@@ -324,7 +322,7 @@ Use tables for structured data:
 ```
 ⚠ Budget check: This operation will spawn 4 agents (~400k tokens)
   Estimated: ~20% of 5-hour window
-  Continue? [/pbr:config to adjust depth first]
+  Continue? [/pbr:settings to adjust depth first]
 ```
 
 ---
@@ -334,71 +332,63 @@ Use tables for structured data:
 ### Phase Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
 {X} plans executed
 Goal verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
 
-/pbr:discuss {N+1} — gather context and clarify approach
+/pbr:discuss-phase {N+1} — gather context and clarify approach
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
-- /pbr:plan {N+1} — skip discussion, plan directly
-- /pbr:review {N} — manual acceptance testing before continuing
-
-───────────────────────────────────────────────────────────────
+- /pbr:plan-phase {N+1} — skip discussion, plan directly
+- /pbr:verify-work {N} — manual acceptance testing before continuing
 ```
 
 ### Milestone Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{version}**
 
 {N} phases completed
 All phase goals verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Audit milestone** — verify requirements, cross-phase integration, E2E flows
 
-/pbr:milestone audit
+/pbr:audit-milestone
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
-- /pbr:review — manual acceptance testing
-- /pbr:milestone complete — skip audit, archive directly
-
-───────────────────────────────────────────────────────────────
+- /pbr:verify-work — manual acceptance testing
+- /pbr:complete-milestone — archive milestone after audit passes
 ```
 
 ### Gaps Found
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                    ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -409,23 +399,19 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 {Extract gap summaries from VERIFICATION.md}
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan gap closure** — create additional plans to complete the phase
 
-/pbr:plan {N} --gaps
+/pbr:plan-phase {N} --gaps
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
-- /pbr:review {N} — manual testing before planning
-
-───────────────────────────────────────────────────────────────
+- /pbr:verify-work {N} — manual testing before planning
 ```
 
 ---
@@ -435,9 +421,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 Use for session lifecycle transitions (pause/resume):
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SESSION RESTORED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 Position: Phase {N} — {phase name}, Plan {M}
 Paused: {ISO datetime}
@@ -453,10 +439,11 @@ Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume s
 ## Anti-Patterns
 
 Do NOT:
-- Use varying box/banner widths
-- Mix banner styles (`===`, `---`, `***`) with `━━━` banners
+- Use varying box/banner widths — always 62-character inner width
+- Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
+- Mix banner styles (`===`, `---`, `***`) with double-line boxes
 - Skip `PLAN-BUILD-RUN ►` prefix in stage banners
-- Use random emoji (only `🎉` for milestone complete, `✓` for phase complete)
+- Use random emoji (only for milestone complete, `✓` for phase complete)
 - Skip the "Next Up" block after major completions
 - Reference non-Plan-Build-Run commands (always use `/pbr:*` commands)
 - Use non-Plan-Build-Run branding in banners

package/plugins/cursor-pbr/references/wave-execution.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/wave-execution.md -->
 # Wave-Based Execution
 
 How Plan-Build-Run parallelizes plan execution within a phase while respecting dependencies.

package/plugins/cursor-pbr/rules/pbr-workflow.mdc

@@ -22,7 +22,7 @@ Context is your scarcest resource. Protect it:
 - **Never read agent definitions** (agents/*.md) — agent invocation auto-loads them
 - **Read summaries, not full files** — when checking agent results, read only frontmatter or first 20 lines
 - **Proactive session boundaries**: When you sense context is getting heavy (long conversation, many tool calls, large file reads), proactively tell the user:
-  - "Context is getting full. I recommend running `/pbr:pause` now so we can resume fresh."
+  - "Context is getting full. I recommend running `/pbr:pause-work` now so we can resume fresh."
   - Do this BEFORE hitting the limit — once context is compacted, details are lost
 - **After compaction**: If the conversation was auto-compacted, immediately read STATE.md to reorient
 - **One phase per session** is a good rule of thumb for complex work
@@ -35,14 +35,14 @@ Context is your scarcest resource. Protect it:
 
 ## Workflow Discipline
 
-- When asked to implement multi-step changes, suggest `/pbr:plan` before diving in
+- When asked to implement multi-step changes, suggest `/pbr:plan-phase` before diving in
 - When asked to fix bugs, suggest `/pbr:debug` for systematic investigation
-- When asked about project status, suggest `/pbr:status`
-- When starting a new session, suggest `/pbr:resume` if paused work exists
+- When asked about project status, suggest `/pbr:progress`
+- When starting a new session, suggest `/pbr:resume-work` if paused work exists
 
 ## Planning Integrity
 
-- Do not modify files in `.planning/phases/` directly — use `/pbr:plan` and `/pbr:build`
-- Do not skip verification — use `/pbr:review` after building
+- Do not modify files in `.planning/phases/` directly — use `/pbr:plan-phase` and `/pbr:execute-phase`
+- Do not skip verification — use `/pbr:verify-work` after building
 - Respect locked decisions in CONTEXT.md files
 - Do not implement deferred ideas from CONTEXT.md

package/plugins/cursor-pbr/setup.ps1

@@ -70,7 +70,7 @@ Write-Host "  .cursor\agents\*.md             - 10 specialized agents"
 Write-Host ""
 Write-Host "Next steps:"
 Write-Host "  1. Open this project in Cursor"
-Write-Host "  2. Start a conversation and use /pbr:begin to start a new project"
+Write-Host "  2. Start a conversation and use /pbr:new-project to start a new project"
 Write-Host ""
 Write-Host "Skills are located at:"
 Write-Host "  $PluginDir\skills\"

package/plugins/cursor-pbr/setup.sh

@@ -70,7 +70,7 @@ echo "  .cursor/agents/*.md             — 10 specialized agents"
 echo ""
 echo "Next steps:"
 echo "  1. Open this project in Cursor"
-echo "  2. Start a conversation and use /pbr:begin to start a new project"
+echo "  2. Start a conversation and use /pbr:new-project to start a new project"
 echo "     (or paste the contents of a skill's SKILL.md as a prompt)"
 echo ""
 echo "Skills are located at:"