@sienklogic/plan-build-run 2.22.0 → 2.22.2

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
 
 ```
@@ -130,6 +147,19 @@ Display the following reference to the user:
 /pbr:milestone complete ← Archive when done
 ```
 
+**Shortcut**: After `/pbr:begin`, run `/pbr:continue` repeatedly — it auto-advances through plan → build → review → next phase, stopping at milestones and errors.
+
+## status vs continue vs do
+
+| | `/pbr:status` | `/pbr:continue` | `/pbr:do <text>` |
+|-|---------------|-----------------|-------------------|
+| **Purpose** | Dashboard — show progress, suggest next | Auto-execute the next logical step | Route freeform text to a skill |
+| **Reads state?** | Yes (full scan) | Yes (minimal) | No |
+| **Modifies files?** | Never | Yes (via delegation) | Depends on routed skill |
+| **Asks questions?** | If multiple options | Never — fully automatic | Only if ambiguous |
+| **Use when...** | You want to see where you are before deciding | You trust PBR to pick and run the next step | You'd rather describe a task in plain English |
+| **Hard stops** | N/A | Milestones, checkpoints, errors, verification gaps | N/A |
+
 ## Quick Reference
 
 - **Context strategy**: `aggressive` (delegate everything) | `balanced` | `minimal` (run inline)

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

@@ -235,7 +235,7 @@ Dry-run of milestone completion — shows what would happen without making any c
 6. **Display summary:**
    ```
    ╔══════════════════════════════════════════════════════════════╗
-   ║  MILESTONE PREVIEW — v{version}                              ║
+   ║  PLAN-BUILD-RUN ► MILESTONE PREVIEW — v{version}             ║
    ╚══════════════════════════════════════════════════════════════╝
 
    Phases to archive: {count}

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

@@ -275,7 +275,10 @@ Files: {list of files changed}
 
 **If partial:**
 ```
-⚠ Quick Task {NNN}: {description}
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► QUICK TASK {NNN} PARTIAL ⚠                ║
+╚══════════════════════════════════════════════════════════════╝
+
 Completed: {N} of {M} tasks
 Failed task: {task name} — {failure reason}
 

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/cursor-pbr/skills/setup/SKILL.md

@@ -273,18 +273,29 @@ Run a quick health check:
 Display results:
 
 ```
-Setup Complete!
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SETUP COMPLETE ✓                           ║
+╚══════════════════════════════════════════════════════════════╝
 
 Project: {cwd basename}
 Model profile: {balanced/quality/budget}
 Depth: {quick/standard/comprehensive}
 Features: {list of enabled non-default features}
 
-Next steps:
-  /pbr:begin  — Full project setup with requirements and roadmap
-  /pbr:scan   — Analyze existing codebase (if adding to existing project)
-  /pbr:help   — Command reference
-  /pbr:config — Fine-tune individual settings
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Start your project** — define requirements and create a roadmap
+
+`/pbr:begin`
+
+<sub>`/clear` first → fresh context window</sub>
+
+**Also available:**
+- `/pbr:scan` — analyze existing codebase (if adding to existing project)
+- `/pbr:config` — fine-tune individual settings
+- `/pbr:help` — command reference
 ```
 
 ---

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.22.0",
+  "version": "2.22.2",
   "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",

package/plugins/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,'scripts','run-hook.js'))\" post-write-quality.js",
-            "statusMessage": "Running quality checks..."
-          }
-        ]
-      },
       {
         "matcher": "Task",
         "hooks": [

package/plugins/pbr/scripts/check-cross-plugin-sync.js

@@ -65,7 +65,7 @@ function checkCrossPluginSync(data) {
     return null;
   }
 
-  const msg = `Advisory: Cross-plugin sync may be needed. Changed pbr files without cursor-pbr/copilot-pbr counterparts:\n${missingCounterparts.map(f => `  - ${f}`).join('\n')}`;
+  const msg = `[Advisory] Cross-plugin sync required. These pbr files were changed without matching cursor-pbr/copilot-pbr updates:\n${missingCounterparts.map(f => `  - ${f}`).join('\n')}\nTo fix: copy each changed file to the matching path in plugins/cursor-pbr/ and plugins/copilot-pbr/, applying plugin-specific adjustments. Run: npm test -- tests/cross-plugin-compat.test.js to verify.`;
   logHook('check-cross-plugin-sync', 'PreToolUse', 'warn', { missingCounterparts });
 
   return { additionalContext: msg };

package/plugins/pbr/scripts/check-phase-boundary.js

@@ -102,7 +102,7 @@ function main() {
         process.exit(2);
       } else {
         const output = {
-          additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
+          additionalContext: `[Advisory] Cross-phase edit: modifying phase ${filePhase} file while current phase is ${currentPhase}. If unintentional: check STATE.md to confirm correct phase. If intentional (e.g. backfilling docs): no action needed. To suppress: set safety.enforce_phase_boundaries: false in config.json.`
         };
         process.stdout.write(JSON.stringify(output));
       }
@@ -181,7 +181,7 @@ function checkBoundary(data) {
   return {
     exitCode: 0,
     output: {
-      additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
+      additionalContext: `[Advisory] Cross-phase edit: modifying phase ${filePhase} file while current phase is ${currentPhase}. If unintentional: check STATE.md to confirm correct phase. If intentional (e.g. backfilling docs): no action needed. To suppress: set safety.enforce_phase_boundaries: false in config.json.`
     }
   };
 }

package/plugins/pbr/scripts/check-roadmap-sync.js

@@ -121,7 +121,7 @@ function main() {
       if (!stateInfo || !stateInfo.phase || !stateInfo.status) {
         logHook('check-roadmap-sync', 'PostToolUse', 'skip', { reason: 'could not parse STATE.md' });
         const output = {
-          additionalContext: '[Roadmap Sync] Could not parse phase/status from STATE.md — ensure it contains **Phase**: and **Status**: fields.'
+          additionalContext: '[Roadmap Sync — WARN] Could not parse STATE.md: missing **Phase**: or **Status**: fields. Expected format: "**Phase**: 3 of 8" and "**Status**: Planning". To fix: run /pbr:health for a guided repair, or manually add the missing fields to .planning/STATE.md.'
         };
         process.stdout.write(JSON.stringify(output));
         process.exit(0);

package/plugins/pbr/scripts/check-subagent-output.js

@@ -436,7 +436,7 @@ function main() {
       found: 'none'
     });
     const output = {
-      additionalContext: `Warning: Agent ${agentType} completed but no ${outputSpec.description} was found. The agent may have failed silently. Check agent output for errors.`
+      additionalContext: `[WARN] Agent ${agentType} completed but no ${outputSpec.description} was found. Likely causes: (1) agent hit an error mid-run, (2) wrong working directory. To fix: re-run the parent skill — the executor gate will block until the output is present. Check the Task() output above for error details.`
     };
     process.stdout.write(JSON.stringify(output));
   } else if (skillWarnings.length > 0) {

package/plugins/pbr/scripts/log-tool-failure.js

@@ -55,7 +55,7 @@ async function main() {
   // Provide recovery hints for Bash failures (most common actionable failure)
   if (toolName === 'Bash' && !isInterrupt) {
     const output = {
-      additionalContext: 'Bash command failed. If this is a recurring issue, consider using /pbr:debug for systematic investigation.'
+      additionalContext: '[Tool Failure] Bash command failed. To investigate: check the error output above for permission/path issues. For recurring failures: /pbr:debug for systematic investigation.'
     };
     process.stdout.write(JSON.stringify(output));
   }

package/plugins/pbr/scripts/post-write-dispatch.js

@@ -21,6 +21,7 @@
 const { checkPlanWrite, checkStateWrite } = require('./check-plan-format');
 const { checkSync } = require('./check-roadmap-sync');
 const { checkStateSync } = require('./check-state-sync');
+const { checkQuality } = require('./post-write-quality');
 
 // Conditionally import validateRoadmap (may not exist yet if PLAN-01 hasn't landed)
 let validateRoadmap;
@@ -109,6 +110,13 @@ function main() {
         process.exit(0);
       }
 
+      // Quality checks (Prettier, tsc, console.log detection) — consolidated from post-write-quality.js
+      const qualityResult = checkQuality(data);
+      if (qualityResult) {
+        process.stdout.write(JSON.stringify(qualityResult.output));
+        process.exit(0);
+      }
+
       process.exit(0);
     } catch (_e) {
       // Don't block on parse errors

package/plugins/pbr/scripts/pre-bash-dispatch.js

@@ -88,12 +88,12 @@ function main() {
         // Warn about touching production config files
         if (/\b(production|prod)\b.*\.(json|ya?ml|env|conf|cfg)\b/i.test(command) ||
             /\.(json|ya?ml|env|conf|cfg)\b.*\b(production|prod)\b/i.test(command)) {
-          warnings.push('command references production config files');
+          warnings.push('command references production config files — verify you are not in a live environment');
         }
 
         // Warn about database operations
         if (/\b(DROP|TRUNCATE|DELETE\s+FROM|ALTER\s+TABLE)\b/i.test(command)) {
-          warnings.push('destructive database operation detected — verify target');
+          warnings.push('destructive database operation (DROP/TRUNCATE/DELETE/ALTER) — verify correct database is targeted and a backup exists');
         }
 
         if (warnings.length > 0) {

package/plugins/pbr/scripts/validate-task.js

@@ -49,7 +49,7 @@ function checkTask(data) {
 
   // Check description exists and is non-empty
   if (!description || (typeof description === 'string' && !description.trim())) {
-    warnings.push('Task() called without a description. Descriptions help track agent purpose.');
+    warnings.push('Task() called without a description. Descriptions are required for audit logging and skill enforcement. Add a short description (3-5 words), e.g.: "Build phase 3 executor".');
   } else if (typeof description === 'string') {
     // Check description length
     if (description.length > MAX_DESCRIPTION_LENGTH) {

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

@@ -530,51 +530,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`
-
-<sub>`/clear` first → fresh context window</sub>
-
-
-
-**Also available:**
-- `/pbr:explore` — open-ended exploration before planning
-- `/pbr:plan 1` — jump straight to planning Phase 1
-- `/pbr:milestone new` — add a second milestone with new phases
-- `/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:milestone new`, `/pbr:config`.
 
 ---
 

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

@@ -809,106 +809,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/pbr/skills/config/SKILL.md

@@ -26,7 +26,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/pbr/skills/continue/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Bash, Glob, Grep, Task, Skill
 
 # /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:status` 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().
 

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

@@ -120,6 +120,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
 
 ```
@@ -133,6 +150,19 @@ Display the following reference to the user:
 /pbr:milestone complete ← Archive when done
 ```
 
+**Shortcut**: After `/pbr:begin`, run `/pbr:continue` repeatedly — it auto-advances through plan → build → review → next phase, stopping at milestones and errors.
+
+## status vs continue vs do
+
+| | `/pbr:status` | `/pbr:continue` | `/pbr:do <text>` |
+|-|---------------|-----------------|-------------------|
+| **Purpose** | Dashboard — show progress, suggest next | Auto-execute the next logical step | Route freeform text to a skill |
+| **Reads state?** | Yes (full scan) | Yes (minimal) | No |
+| **Modifies files?** | Never | Yes (via delegation) | Depends on routed skill |
+| **Asks questions?** | If multiple options | Never — fully automatic | Only if ambiguous |
+| **Use when...** | You want to see where you are before deciding | You trust PBR to pick and run the next step | You'd rather describe a task in plain English |
+| **Hard stops** | N/A | Milestones, checkpoints, errors, verification gaps | N/A |
+
 ## Quick Reference
 
 - **Context strategy**: `aggressive` (delegate everything) | `balanced` | `minimal` (run inline)

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

@@ -239,7 +239,7 @@ Dry-run of milestone completion — shows what would happen without making any c
 6. **Display summary:**
    ```
    ╔══════════════════════════════════════════════════════════════╗
-   ║  MILESTONE PREVIEW — v{version}                              ║
+   ║  PLAN-BUILD-RUN ► MILESTONE PREVIEW — v{version}             ║
    ╚══════════════════════════════════════════════════════════════╝
 
    Phases to archive: {count}

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

@@ -281,7 +281,10 @@ Files: {list of files changed}
 
 **If partial:**
 ```
-⚠ Quick Task {NNN}: {description}
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► QUICK TASK {NNN} PARTIAL ⚠                ║
+╚══════════════════════════════════════════════════════════════╝
+
 Completed: {N} of {M} tasks
 Failed task: {task name} — {failure reason}