@sienklogic/plan-build-run 2.22.0 → 2.22.1

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/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
 
 ```

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

@@ -581,109 +581,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}`
-
-<sub>`/clear` first → fresh context window</sub>
-
-
-
-**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`
-
-<sub>`/clear` first → fresh context window</sub>
-
-
-
-**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`
-
-<sub>`/clear` first → fresh context window</sub>
-
-
-
-**Also available:**
-- `/pbr:milestone complete` — archive milestone after audit passes
-- `/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/copilot-pbr/references/agent-interactions.md

@@ -1,135 +0,0 @@
-<!-- canonical: ../../pbr/references/agent-interactions.md -->
-# Agent Interaction Map
-
-This document shows how Plan-Build-Run agents communicate through files on disk. Agents never message each other directly -- they read and write shared files in `.planning/`.
-
-## Interaction Graph
-
-```
-                    User / Orchestrator
-                     |           ^
-                     v           |
-              +--------------+   |
-              |  researcher  |---+---> planner
-              +--------------+         |    ^
-                     |                 v    |
-              +--------------+   +--------------+
-              | synthesizer  |   | plan-checker |
-              +--------------+   +--------------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  executor  |
-                                 +-----------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  verifier  |----> planner (gap closure)
-                                 +-----------+
-                                       |
-                                       v
-                              +--------------------+
-                              | integration-checker|
-                              +--------------------+
-```
-
-## Per-Agent Interaction Details
-
-### researcher
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | User/Orchestrator | Research topics, CONTEXT.md constraints, phase goals |
-| Produces for | planner | Research documents with technology details and recommendations |
-| Produces for | synthesizer | Research documents to be combined |
-| Produces for | User | Direct reading for decision-making |
-
-### synthesizer
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents to synthesize |
-| Receives from | Orchestrator | Paths to research documents, synthesis request |
-| Produces for | planner | SUMMARY.md as consolidated research input for planning |
-| Produces for | User | High-level project/phase research overview |
-
-### planner
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents with technology details and recommendations |
-| Receives from | plan-checker | Issue reports requiring plan revision |
-| Receives from | verifier | VERIFICATION.md reports requiring gap closure plans |
-| Receives from | User/Orchestrator | Phase goals, CONTEXT.md, planning requests |
-| Produces for | plan-checker | Plan files for quality verification |
-| Produces for | executor | Plan files for execution |
-| Produces for | verifier | Must-have definitions for verification (embedded in plan frontmatter) |
-
-### plan-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Plan files to check, phase context |
-| Receives from | planner | Newly created or revised plan files |
-| Produces for | planner | Issue reports for revision |
-| Produces for | Orchestrator/User | Pass/fail decision on plan quality |
-
-### executor
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Plan files to execute, continuation instructions |
-| Receives from | planner | The plans themselves (indirectly, via files) |
-| Produces for | verifier | SUMMARY.md for verification, committed code for inspection |
-| Produces for | Orchestrator | Checkpoint responses, completion status |
-| Produces for | planner | Deferred ideas (in SUMMARY.md) for future planning |
-
-### verifier
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phase to verify, timing trigger |
-| Receives from | executor | Completed work (via codebase and SUMMARY.md) |
-| Receives from | Previous VERIFICATION.md | Gaps to re-check (in re-verification mode) |
-| Produces for | planner | Gap list for gap-closure planning (via VERIFICATION.md) |
-| Produces for | Orchestrator | Phase status (passed/gaps_found/human_needed) |
-| Produces for | User | Human verification items with specific test instructions |
-
-### integration-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phases to check, trigger event (milestone/review) |
-| Receives from | verifier | Phase-level verification reports (for context on per-phase status) |
-| Produces for | planner | Integration gap list for cross-phase fix plans |
-| Produces for | Orchestrator | Integration status for milestone decisions |
-| Produces for | User | Integration health overview and security issues |
-
-### debugger
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Bug reports, symptoms, reproduction steps |
-| Receives from | executor | Errors encountered during execution (via checkpoint responses) |
-| Receives from | verifier | Issues discovered during verification |
-| Produces for | Orchestrator/User | Root cause analysis, fix commits, checkpoint requests |
-| Produces for | planner | Findings requiring architectural changes |
-| Produces for | executor | Simple fix instructions for executor to apply |
-
-### codebase-mapper
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Focus area to analyze, project path |
-| Receives from | researcher | May be invoked alongside researcher for new projects |
-| Produces for | planner | STACK.md, ARCHITECTURE.md, STRUCTURE.md for informed planning |
-| Produces for | executor | CONVENTIONS.md for code style, TESTING.md for test patterns |
-| Produces for | verifier | All documents as reference for what "correct" looks like |
-| Produces for | User | Direct reading for project understanding |
-
-### general
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Ad-hoc task instructions |
-| Produces for | Orchestrator/User | Task output (files, formatting, config changes) |