@sienklogic/plan-build-run 2.22.0 → 2.22.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.22.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.22.0...plan-build-run-v2.22.1) (2026-02-24)
+
+
+### Bug Fixes
+
+* **tools:** standardize error messages with severity prefix and actionable next-steps ([3b3b6dd](https://github.com/SienkLogic/plan-build-run/commit/3b3b6dd2cd1d868896edccfec19acefcb70b087f))
+
 ## [2.22.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.21.1...plan-build-run-v2.22.0) (2026-02-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.22.0",
+  "version": "2.22.1",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/hooks/hooks.json

@@ -28,18 +28,6 @@
           }
         ]
       },
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" post-write-quality.js",
-            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') post-write-quality.js",
-            "cwd": ".",
-            "timeoutSec": 15
-          }
-        ]
-      },
       {
         "matcher": "Task",
         "hooks": [

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.22.0",
+  "version": "2.22.1",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-pbr/skills/begin/SKILL.md

@@ -503,48 +503,9 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 ## Completion
 
-After all steps complete, present the final summary:
+After all steps complete, present the final summary using the stage banner format from Read `references/ui-formatting.md`:
 
-Use the branded stage banner from `references/ui-formatting.md`:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PROJECT INITIALIZED                        ║
-╚══════════════════════════════════════════════════════════════╝
-
-**{name}**
-
-{core value one-liner}
-
-Roadmap: {N} phases
-  1. {Phase 1 name}
-  2. {Phase 2 name}
-  ...
-
-Requirements: {N} committed, {M} deferred, {K} out-of-scope
-```
-
-Then use the "Next Up" routing block:
-```
----
-
-## Next Up
-
-**Phase 1: {Name}** — {one-line goal}
-
-`/pbr:discuss 1`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:explore` — open-ended exploration before planning
-- `/pbr:plan 1` — jump straight to planning Phase 1
-- `/pbr:config` — adjust workflow settings
-
----
-```
+Display the `PROJECT INITIALIZED` banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-formatting.md) pointing to `/pbr:discuss 1` with alternatives: `/pbr:explore`, `/pbr:plan 1`, `/pbr:config`.
 
 ---
 

package/plugins/copilot-pbr/skills/build/SKILL.md

@@ -807,91 +807,11 @@ Total files modified: {count}
 Deviations: {count}
 ```
 
-Then present the appropriate branded banner:
+Then present the appropriate branded banner from Read `references/ui-formatting.md` § "Completion Summary Templates":
 
-**If `passed` + more phases:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-{X} plans executed
-Goal verified ✓
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/pbr:plan {N+1}`
-
-<sub>`/clear` first → fresh context window</sub>
-
-**Also available:**
-- `/pbr:review {N}` — manual acceptance testing before continuing
-- `/pbr:discuss {N+1}` — talk through the next phase before planning
-- `/pbr:status` — see full project status
-
-```
-
-**If `passed` + last phase:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
-╚══════════════════════════════════════════════════════════════╝
-
-{N} phases completed
-All phase goals verified ✓
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Audit milestone** — verify requirements, cross-phase integration, E2E flows
-
-`/pbr:milestone audit`
-
-<sub>`/clear` first → fresh context window</sub>
-
-**Also available:**
-- `/pbr:review` — manual acceptance testing
-- `/pbr:milestone complete` — archive milestone after audit passes
-
-```
-
-**If `gaps_found`:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                     ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-Score: {X}/{Y} must-haves verified
-Report: .planning/phases/{phase_dir}/VERIFICATION.md
-
-### What's Missing
-
-{Extract gap summaries from VERIFICATION.md}
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Plan gap closure** — create additional plans to complete the phase
-
-`/pbr:plan {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
-
-```
+- **If `passed` + more phases:** Use the "Phase Complete" template. Fill in phase number, name, plan count, and next phase details.
+- **If `passed` + last phase:** Use the "Milestone Complete" template. Fill in phase count.
+- **If `gaps_found`:** Use the "Gaps Found" template. Fill in phase number, name, score, and gap summaries from VERIFICATION.md.
 
 **8g. Display USER-SETUP.md (conditional):**
 

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

@@ -23,7 +23,7 @@ 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
 
 ## Flow

package/plugins/copilot-pbr/skills/help/SKILL.md

@@ -117,6 +117,23 @@ Display the following reference to the user:
 | `/pbr:dashboard --port <N>` | Launch dashboard on a specific port. |
 | `/pbr:statusline` | Install or configure the PBR status line in Claude Code. |
 
+## Choose Your Command
+
+Not sure which command to use? Follow this guide:
+
+| I want to... | Command |
+|--------------|---------|
+| Start a new project | `/pbr:begin` |
+| Fix a bug or investigate an error | `/pbr:debug` |
+| Think through an idea or approach | `/pbr:explore` |
+| Do a small task (≤3 files) | `/pbr:quick` |
+| Plan a complex change (4+ files) | `/pbr:plan <N>` |
+| See where I am and what's next | `/pbr:status` |
+| Auto-execute the next step | `/pbr:continue` |
+| Describe something and let PBR route it | `/pbr:do <description>` |
+| Lock decisions for a specific phase | `/pbr:discuss <N>` |
+| Check project health | `/pbr:health` |
+
 ## Typical Workflow
 
 ```

package/plugins/copilot-pbr/skills/review/SKILL.md

@@ -542,103 +542,11 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 ## Completion
 
-After review completes, always present a clear next action:
+After review completes, always present a clear next action using the completion banners from Read `references/ui-formatting.md` § "Completion Summary Templates":
 
-**If verified (not final phase):**
-
-Display the "Phase Complete" banner inline:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE                         ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-{X} plans executed
-Goal verified
-```
-
-Then the branded "Next Up" block:
-```
----
-
-## Next Up
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/pbr:plan {N+1}`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:discuss {N+1}` — talk through details before planning
-- `/pbr:status` — see full project status
-
----
-```
-
-**If gaps remain:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {name}** — {count} gaps remaining
-
----
-
-## Next Up
-
-**Fix gaps** — diagnose and create fix plans
-
-`/pbr:review {N} --auto-fix`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:plan {N} --gaps` — create fix plans manually
-- Fix manually, then `/pbr:review {N}`
-
----
-```
-
-**If final phase:**
-
-Display the "Milestone Complete" banner inline:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
-╚══════════════════════════════════════════════════════════════╝
-
-{N} phases completed
-All phase goals verified
-```
-
-Then:
-```
----
-
-## Next Up
-
-**Audit milestone** — verify cross-phase integration
-
-`/pbr:milestone audit`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:milestone complete` — archive this milestone and tag it
-- `/pbr:milestone new` — start planning next features
-- `/pbr:status` — see final project status
-
----
-```
+- **If verified (not final phase):** Use the "Phase Complete" template. Fill in phase number, name, plan count, and next phase details.
+- **If gaps remain:** Use the "Gaps Found" template. Fill in phase number, name, gap count, and gap summaries.
+- **If final phase:** Use the "Milestone Complete" template. Fill in phase count.
 
 ---
 

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.22.0",
+  "version": "2.22.1",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/hooks/hooks.json

@@ -24,16 +24,6 @@
           }
         ]
       },
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" post-write-quality.js",
-            "statusMessage": "Running quality checks..."
-          }
-        ]
-      },
       {
         "matcher": "Task",
         "hooks": [

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

@@ -503,48 +503,9 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 ## Completion
 
-After all steps complete, present the final summary:
+After all steps complete, present the final summary using the stage banner format from Read `references/ui-formatting.md`:
 
-Use the branded stage banner from `references/ui-formatting.md`:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PROJECT INITIALIZED                        ║
-╚══════════════════════════════════════════════════════════════╝
-
-**{name}**
-
-{core value one-liner}
-
-Roadmap: {N} phases
-  1. {Phase 1 name}
-  2. {Phase 2 name}
-  ...
-
-Requirements: {N} committed, {M} deferred, {K} out-of-scope
-```
-
-Then use the "Next Up" routing block:
-```
----
-
-## Next Up
-
-**Phase 1: {Name}** — {one-line goal}
-
-`/pbr:discuss 1`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:explore` — open-ended exploration before planning
-- `/pbr:plan 1` — jump straight to planning Phase 1
-- `/pbr:config` — adjust workflow settings
-
----
-```
+Display the `PROJECT INITIALIZED` banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-formatting.md) pointing to `/pbr:discuss 1` with alternatives: `/pbr:explore`, `/pbr:plan 1`, `/pbr:config`.
 
 ---
 

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

@@ -808,91 +808,11 @@ Total files modified: {count}
 Deviations: {count}
 ```
 
-Then present the appropriate branded banner:
+Then present the appropriate branded banner from Read `references/ui-formatting.md` § "Completion Summary Templates":
 
-**If `passed` + more phases:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-{X} plans executed
-Goal verified ✓
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/pbr:plan {N+1}`
-
-<sub>`/clear` first → fresh context window</sub>
-
-**Also available:**
-- `/pbr:review {N}` — manual acceptance testing before continuing
-- `/pbr:discuss {N+1}` — talk through the next phase before planning
-- `/pbr:status` — see full project status
-
-```
-
-**If `passed` + last phase:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
-╚══════════════════════════════════════════════════════════════╝
-
-{N} phases completed
-All phase goals verified ✓
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Audit milestone** — verify requirements, cross-phase integration, E2E flows
-
-`/pbr:milestone audit`
-
-<sub>`/clear` first → fresh context window</sub>
-
-**Also available:**
-- `/pbr:review` — manual acceptance testing
-- `/pbr:milestone complete` — archive milestone after audit passes
-
-```
-
-**If `gaps_found`:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                     ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-Score: {X}/{Y} must-haves verified
-Report: .planning/phases/{phase_dir}/VERIFICATION.md
-
-### What's Missing
-
-{Extract gap summaries from VERIFICATION.md}
-
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Plan gap closure** — create additional plans to complete the phase
-
-`/pbr:plan {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
-
-```
+- **If `passed` + more phases:** Use the "Phase Complete" template. Fill in phase number, name, plan count, and next phase details.
+- **If `passed` + last phase:** Use the "Milestone Complete" template. Fill in phase count.
+- **If `gaps_found`:** Use the "Gaps Found" template. Fill in phase number, name, score, and gap summaries from VERIFICATION.md.
 
 **8g. Display USER-SETUP.md (conditional):**
 

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

@@ -23,7 +23,7 @@ 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
 
 ## Flow

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

@@ -117,6 +117,23 @@ Display the following reference to the user:
 | `/pbr:dashboard --port <N>` | Launch dashboard on a specific port. |
 | `/pbr:statusline` | Install or configure the PBR status line in Claude Code. |
 
+## Choose Your Command
+
+Not sure which command to use? Follow this guide:
+
+| I want to... | Command |
+|--------------|---------|
+| Start a new project | `/pbr:begin` |
+| Fix a bug or investigate an error | `/pbr:debug` |
+| Think through an idea or approach | `/pbr:explore` |
+| Do a small task (≤3 files) | `/pbr:quick` |
+| Plan a complex change (4+ files) | `/pbr:plan <N>` |
+| See where I am and what's next | `/pbr:status` |
+| Auto-execute the next step | `/pbr:continue` |
+| Describe something and let PBR route it | `/pbr:do <description>` |
+| Lock decisions for a specific phase | `/pbr:discuss <N>` |
+| Check project health | `/pbr:health` |
+
 ## Typical Workflow
 
 ```

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

@@ -543,103 +543,11 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 ## Completion
 
-After review completes, always present a clear next action:
+After review completes, always present a clear next action using the completion banners from Read `references/ui-formatting.md` § "Completion Summary Templates":
 
-**If verified (not final phase):**
-
-Display the "Phase Complete" banner inline:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE                         ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {Name}**
-
-{X} plans executed
-Goal verified
-```
-
-Then the branded "Next Up" block:
-```
----
-
-## Next Up
-
-**Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/pbr:plan {N+1}`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:discuss {N+1}` — talk through details before planning
-- `/pbr:status` — see full project status
-
----
-```
-
-**If gaps remain:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Phase {N}: {name}** — {count} gaps remaining
-
----
-
-## Next Up
-
-**Fix gaps** — diagnose and create fix plans
-
-`/pbr:review {N} --auto-fix`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:plan {N} --gaps` — create fix plans manually
-- Fix manually, then `/pbr:review {N}`
-
----
-```
-
-**If final phase:**
-
-Display the "Milestone Complete" banner inline:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
-╚══════════════════════════════════════════════════════════════╝
-
-{N} phases completed
-All phase goals verified
-```
-
-Then:
-```
----
-
-## Next Up
-
-**Audit milestone** — verify cross-phase integration
-
-`/pbr:milestone audit`
-
-`/clear` first for a fresh context window
-
----
-
-**Also available:**
-- `/pbr:milestone complete` — archive this milestone and tag it
-- `/pbr:milestone new` — start planning next features
-- `/pbr:status` — see final project status
-
----
-```
+- **If verified (not final phase):** Use the "Phase Complete" template. Fill in phase number, name, plan count, and next phase details.
+- **If gaps remain:** Use the "Gaps Found" template. Fill in phase number, name, gap count, and gap summaries.
+- **If final phase:** Use the "Milestone Complete" template. Fill in phase count.
 
 ---
 

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.22.0",
+  "version": "2.22.1",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",