@sienklogic/plan-build-run 2.10.0 → 2.11.0

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

@@ -21,6 +21,19 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 
+/**
+ * Check if a file was modified recently (within thresholdMs).
+ * Returns false if file doesn't exist or on error.
+ */
+function isRecent(filePath, thresholdMs = 300000) {
+  try {
+    const stat = fs.statSync(filePath);
+    return (Date.now() - stat.mtimeMs) < thresholdMs;
+  } catch (_e) {
+    return false;
+  }
+}
+
 // Agent type → expected output patterns
 const AGENT_OUTPUTS = {
   'pbr:executor': {
@@ -46,9 +59,16 @@ const AGENT_OUTPUTS = {
       const researchDir = path.join(planningDir, 'research');
       if (!fs.existsSync(researchDir)) return [];
       try {
-        return fs.readdirSync(researchDir)
+        const allFiles = fs.readdirSync(researchDir)
           .filter(f => f.endsWith('.md'))
           .map(f => path.join('research', f));
+        if (allFiles.length === 0) return [];
+        const recentFiles = allFiles.filter(f => isRecent(path.join(planningDir, f)));
+        if (recentFiles.length === 0) {
+          // Files exist but none are recent — return them but flag staleness
+          allFiles._stale = true;
+        }
+        return allFiles;
       } catch (_e) {
         return [];
       }
@@ -61,14 +81,27 @@ const AGENT_OUTPUTS = {
       if (fs.existsSync(researchDir)) {
         try {
           const files = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
-          if (files.length > 0) return files.map(f => path.join('research', f));
+          if (files.length > 0) {
+            const allFiles = files.map(f => path.join('research', f));
+            const recentFiles = allFiles.filter(f => isRecent(path.join(planningDir, f)));
+            if (recentFiles.length === 0) {
+              allFiles._stale = true;
+            }
+            return allFiles;
+          }
         } catch (_e) { /* best-effort */ }
       }
       const contextFile = path.join(planningDir, 'CONTEXT.md');
       if (fs.existsSync(contextFile)) {
         try {
           const stat = fs.statSync(contextFile);
-          if (stat.size > 0) return ['CONTEXT.md'];
+          if (stat.size > 0) {
+            const result = ['CONTEXT.md'];
+            if (!isRecent(contextFile)) {
+              result._stale = true;
+            }
+            return result;
+          }
         } catch (_e) { /* best-effort */ }
       }
       return [];
@@ -255,6 +288,12 @@ function main() {
   // Skill-specific post-completion validation
   const skillWarnings = [];
 
+  // Mtime-based recency check for researcher and synthesizer
+  if (found._stale && (agentType === 'pbr:researcher' || agentType === 'pbr:synthesizer')) {
+    const label = agentType === 'pbr:researcher' ? 'Researcher' : 'Synthesizer';
+    skillWarnings.push(`${label} output may be stale — no recent output files detected.`);
+  }
+
   // GAP-04: Begin planner must produce core files
   if (activeSkill === 'begin' && agentType === 'pbr:planner') {
     const coreFiles = ['REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
@@ -317,5 +356,5 @@ function main() {
   process.exit(0);
 }
 
-module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits };
+module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -114,7 +114,8 @@ function checkQuickExecutorGate(data) {
     return {
       block: true,
       reason: 'Cannot spawn executor: .planning/quick/ directory does not exist. ' +
-        'You must create the quick task directory and PLAN.md first (Steps 4-6).'
+        'You must create the quick task directory and PLAN.md first (Steps 4-6). ' +
+        'To fix: Re-run /pbr:quick to create the quick task directory and PLAN.md.'
     };
   }
 
@@ -138,13 +139,15 @@ function checkQuickExecutorGate(data) {
       return {
         block: true,
         reason: 'Cannot spawn executor: no PLAN.md found in any .planning/quick/*/ directory. ' +
-          'You must create .planning/quick/{NNN}-{slug}/PLAN.md first (Steps 4-6).'
+          'You must create .planning/quick/{NNN}-{slug}/PLAN.md first (Steps 4-6). ' +
+          'To fix: Re-run /pbr:quick to create the quick task directory and PLAN.md.'
       };
     }
   } catch (_e) {
     return {
       block: true,
-      reason: 'Cannot spawn executor: failed to read .planning/quick/ directory.'
+      reason: 'Cannot spawn executor: failed to read .planning/quick/ directory. ' +
+        'To fix: Re-run /pbr:quick to create the quick task directory and PLAN.md.'
     };
   }
 
@@ -187,7 +190,7 @@ function checkBuildExecutorGate(data) {
     if (!fs.existsSync(phasesDir)) {
       return {
         block: true,
-        reason: 'Cannot spawn executor: .planning/phases/ directory does not exist. Run /pbr:plan first.'
+        reason: 'Cannot spawn executor: .planning/phases/ directory does not exist. To fix: Run /pbr:plan {N} to create plans first.'
       };
     }
 
@@ -195,7 +198,7 @@ function checkBuildExecutorGate(data) {
     if (dirs.length === 0) {
       return {
         block: true,
-        reason: `Cannot spawn executor: no phase directory found for phase ${currentPhase}. Run /pbr:plan first.`
+        reason: `Cannot spawn executor: no phase directory found for phase ${currentPhase}. To fix: Run /pbr:plan ${currentPhase} to create plans first.`
       };
     }
 
@@ -213,7 +216,7 @@ function checkBuildExecutorGate(data) {
     if (!hasPlan) {
       return {
         block: true,
-        reason: `Cannot spawn executor: no PLAN.md found in .planning/phases/${dirs[0]}/. Run /pbr:plan first.`
+        reason: `Cannot spawn executor: no PLAN.md found in .planning/phases/${dirs[0]}/. To fix: Run /pbr:plan ${currentPhase} to create plans first.`
       };
     }
   } catch (_e) {
@@ -248,7 +251,7 @@ function checkPlanExecutorGate(data) {
 
   return {
     block: true,
-    reason: 'Plan skill should not spawn executors. Use /pbr:build to execute plans.'
+    reason: 'Plan skill should not spawn executors. To fix: Run /pbr:build to execute plans. The plan skill creates plans; the build skill executes them.'
   };
 }
 
@@ -296,7 +299,7 @@ function checkReviewPlannerGate(data) {
     if (!hasVerification) {
       return {
         block: true,
-        reason: 'Review planner gate: Cannot spawn planner for gap closure without a VERIFICATION.md. Run /pbr:review first to generate verification results.'
+        reason: 'Review planner gate: Cannot spawn planner for gap closure without a VERIFICATION.md. To fix: Run /pbr:review {N} to create VERIFICATION.md first.'
       };
     }
   } catch (_e) {
@@ -358,7 +361,7 @@ function checkReviewVerifierGate(data) {
     if (!hasSummary) {
       return {
         block: true,
-        reason: 'Review verifier gate: Cannot spawn verifier without SUMMARY.md in phase directory. Run /pbr:build first.'
+        reason: 'Review verifier gate: Cannot spawn verifier without SUMMARY.md in phase directory. To fix: Run /pbr:build {N} to create SUMMARY.md first.'
       };
     }
   } catch (_e) {
@@ -443,14 +446,22 @@ function checkMilestoneCompleteGate(data) {
         if (pDirs.length === 0) {
           return {
             block: true,
-            reason: `Milestone complete gate: Phase ${paddedPhase} directory not found. All milestone phases must be verified before completing milestone.`
+            reason: `Milestone complete gate: Phase ${paddedPhase} directory not found. All milestone phases must be verified before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have status: passed.`
           };
         }
-        const hasVerification = fs.existsSync(path.join(phasesDir, pDirs[0], 'VERIFICATION.md'));
+        const verificationFile = path.join(phasesDir, pDirs[0], 'VERIFICATION.md');
+        const hasVerification = fs.existsSync(verificationFile);
         if (!hasVerification) {
           return {
             block: true,
-            reason: `Milestone complete gate: Phase ${paddedPhase} (${pDirs[0]}) lacks VERIFICATION.md. All milestone phases must be verified before completing milestone.`
+            reason: `Milestone complete gate: Phase ${paddedPhase} (${pDirs[0]}) lacks VERIFICATION.md. All milestone phases must be verified before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have status: passed.`
+          };
+        }
+        const verStatus = getVerificationStatus(verificationFile);
+        if (verStatus === 'gaps_found') {
+          return {
+            block: true,
+            reason: `Milestone complete gate: Phase ${paddedPhase} VERIFICATION.md has status: gaps_found. Close all gaps before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have status: passed.`
           };
         }
       }
@@ -538,14 +549,14 @@ function checkBuildDependencyGate(data) {
       if (pDirs.length === 0) {
         return {
           block: true,
-          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. Run /pbr:review on dependent phases first.`
+          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. To fix: Run /pbr:review on the dependency phase first.`
         };
       }
       const hasVerification = fs.existsSync(path.join(phasesDir, pDirs[0], 'VERIFICATION.md'));
       if (!hasVerification) {
         return {
           block: true,
-          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. Run /pbr:review on dependent phases first.`
+          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. To fix: Run /pbr:review on the dependency phase first.`
         };
       }
     }
@@ -561,6 +572,45 @@ function checkBuildDependencyGate(data) {
  * spawned, warn if .checkpoint-manifest.json is missing in the phase dir.
  * Returns a warning string or null.
  */
+/**
+ * Parse VERIFICATION.md frontmatter to extract status field.
+ * Returns the status string or 'unknown' if not parseable.
+ */
+function getVerificationStatus(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch) return 'unknown';
+    const statusMatch = fmMatch[1].match(/^status:\s*(\S+)/m);
+    return statusMatch ? statusMatch[1] : 'unknown';
+  } catch (_e) {
+    return 'unknown';
+  }
+}
+
+/**
+ * Advisory check: when pbr:debugger is spawned and .active-skill is 'debug',
+ * warn if .planning/debug/ directory does not exist.
+ * Returns a warning string or null.
+ */
+function checkDebuggerAdvisory(data) {
+  const subagentType = data.tool_input?.subagent_type || '';
+  if (subagentType !== 'pbr:debugger') return null;
+  // Only advise when spawned from the debug skill
+  const activeSkillPath = path.join(process.cwd(), '.planning', '.active-skill');
+  try {
+    const activeSkill = fs.readFileSync(activeSkillPath, 'utf8').trim();
+    if (activeSkill !== 'debug') return null;
+  } catch (_e) {
+    return null; // No .active-skill file — skip advisory
+  }
+  const debugDir = path.join(process.cwd(), '.planning', 'debug');
+  if (!fs.existsSync(debugDir)) {
+    return 'Debugger advisory: .planning/debug/ does not exist. Create it before spawning the debugger so output has a target location.';
+  }
+  return null;
+}
+
 function checkCheckpointManifest(data) {
   const toolInput = data.tool_input || {};
   const subagentType = toolInput.subagent_type || '';
@@ -595,7 +645,7 @@ function checkCheckpointManifest(data) {
     const phaseDir = path.join(phasesDir, dirs[0]);
     const manifestFile = path.join(phaseDir, '.checkpoint-manifest.json');
     if (!fs.existsSync(manifestFile)) {
-      return 'Build advisory: .checkpoint-manifest.json not found in phase directory. The build skill should write this before spawning executors.';
+      return 'Build advisory: .checkpoint-manifest.json not found in phase directory. The build skill should write this before spawning executors. To fix: Run /pbr:health to regenerate checkpoint manifest.';
     }
   } catch (_e) {
     return null;
@@ -624,7 +674,7 @@ function checkActiveSkillIntegrity(data) {
 
   const activeSkillFile = path.join(planningDir, '.active-skill');
   if (!fs.existsSync(activeSkillFile)) {
-    return 'Active-skill integrity: .planning/.active-skill not found. Skill-specific enforcement is disabled. The invoking skill should write this file.';
+    return 'Active-skill integrity: .planning/.active-skill not found. Skill-specific enforcement is disabled. The invoking skill should write this file. To fix: Wait for the current skill to finish, or delete .planning/.active-skill if stale.';
   }
 
   return null;
@@ -727,6 +777,8 @@ function main() {
       const warnings = checkTask(data);
       const manifestWarning = checkCheckpointManifest(data);
       if (manifestWarning) warnings.push(manifestWarning);
+      const debuggerWarning = checkDebuggerAdvisory(data);
+      if (debuggerWarning) warnings.push(debuggerWarning);
       const activeSkillWarning = checkActiveSkillIntegrity(data);
       if (activeSkillWarning) warnings.push(activeSkillWarning);
 
@@ -747,5 +799,5 @@ function main() {
   });
 }
 
-module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkBuildDependencyGate, checkCheckpointManifest, checkActiveSkillIntegrity, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
+module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkBuildDependencyGate, checkCheckpointManifest, checkDebuggerAdvisory, getVerificationStatus, checkActiveSkillIntegrity, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -23,9 +23,9 @@ Additionally for this skill:
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STARTING PROJECT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STARTING PROJECT                           ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -168,6 +168,8 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **After gathering preferences:**
 
+**CRITICAL: You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
+
 1. Read the config template from `skills/begin/templates/config.json.tmpl`
 2. Apply the user's choices to the template
 3. Create `.planning/` directory
@@ -175,6 +177,8 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **IMPORTANT**: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
 
+**CRITICAL: Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
+
 ---
 
 ### Step 4: Research Decision (inline)
@@ -209,7 +213,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 Spawn parallel Task() subagents for research. Each researcher writes to `.planning/research/`.
 
-**Create `.planning/research/` directory first.**
+**CRITICAL: Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
 
 **For each research topic, spawn a Task():**
 
@@ -343,6 +347,9 @@ Each requirement must be:
 - **Specific** — not vague ("fast" is bad, "page loads in <2s" is good)
 
 **7e. Write REQUIREMENTS.md:**
+
+**CRITICAL: Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
+
 Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
 - All v1 requirements grouped by category
 - All v2 requirements with deferral reasons
@@ -401,6 +408,10 @@ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 
 Write the project state files from templates:
 
+**CRITICAL: You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
+
+**CRITICAL: Write PROJECT.md NOW. Do NOT skip this step.**
+
 **9a. Write PROJECT.md:**
 1. Read `skills/begin/templates/PROJECT.md.tmpl`
 2. Fill in:
@@ -413,6 +424,8 @@ Write the project state files from templates:
 3. Write to `.planning/PROJECT.md`
 4. Ensure the `## Milestones` section is filled in with the project name and phase count from the roadmap
 
+**CRITICAL: Write STATE.md NOW. Do NOT skip this step.**
+
 **9b. Write STATE.md:**
 1. Read `skills/begin/templates/STATE.md.tmpl`
 2. Fill in:
@@ -425,6 +438,8 @@ Write the project state files from templates:
 4. Fill in the `## Milestone` section with the project name and total phase count
 5. **STATE.md size limit**: Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 
+**CRITICAL: Write CONTEXT.md NOW. Do NOT skip this step.**
+
 **9c. Write CONTEXT.md:**
 Create `.planning/CONTEXT.md` from information gathered during questioning:
 
@@ -449,6 +464,8 @@ Create `.planning/CONTEXT.md` from information gathered during questioning:
 | {feature} | {reason} |
 ```
 
+**CRITICAL: Write HISTORY.md NOW. Do NOT skip this step.**
+
 **9d. Write HISTORY.md:**
 Create `.planning/HISTORY.md` with an initial entry:
 
@@ -462,6 +479,8 @@ Create `.planning/HISTORY.md` with an initial entry:
 - Roadmap: {N} phases planned
 ```
 
+**CRITICAL: Create phase directories NOW. Do NOT skip this step.**
+
 **9e. Create phase directories:**
 For each phase in the roadmap, create the directory structure:
 ```
@@ -505,6 +524,10 @@ If `gates.confirm_project` is true in config:
 
 ---
 
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
 ## Completion
 
 After all steps complete, present the final summary:
@@ -512,9 +535,9 @@ After all steps complete, present the final summary:
 Use the branded stage banner from `references/ui-formatting.md`:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PROJECT INITIALIZED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PROJECT INITIALIZED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{name}**
 
@@ -530,9 +553,11 @@ Requirements: {N} committed, {M} deferred, {K} out-of-scope
 
 Then use the "Next Up" routing block:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase 1: {Name}** — {one-line goal}
 
@@ -540,7 +565,7 @@ Then use the "Next Up" routing block:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:explore` — open-ended exploration before planning
@@ -548,7 +573,7 @@ Then use the "Next Up" routing block:
 - `/pbr:milestone new` — add a second milestone with new phases
 - `/pbr:config` — adjust workflow settings
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---

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

@@ -24,9 +24,9 @@ Additionally for this skill:
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► BUILDING PHASE {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► BUILDING PHASE {N}                         ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
@@ -65,7 +65,7 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number and flags
 2. Read `.planning/config.json` for parallelization, model, and gate settings (see config-loading.md for field reference)
 3. Resolve depth profile: run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get the effective feature/gate settings for the current depth. Store the result for use in later gating decisions.
-4. Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
+4. **CRITICAL: Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
 5. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
    - PLAN.md files exist in the directory
@@ -198,6 +198,8 @@ Validate wave consistency:
 
 ### Step 5b: Write Checkpoint Manifest (inline)
 
+**CRITICAL: Write .checkpoint-manifest.json NOW before entering the wave loop.**
+
 Before entering the wave loop, write `.planning/phases/{NN}-{slug}/.checkpoint-manifest.json`:
 
 ```json
@@ -693,6 +695,8 @@ If triggered:
    ```
 4. Do NOT block on this — use `run_in_background: true` and continue to Step 8a. Report completion in Step 8f if it finishes in time.
 
+**CRITICAL: Update ROADMAP.md progress table NOW. Do NOT skip this step.**
+
 **8a. Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 
 **Tooling shortcut**: Use the CLI for atomic ROADMAP.md table updates instead of manual editing:
@@ -709,6 +713,8 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
 5. Update the `Status` column to the final_status determined in Step 8-pre
 6. Save the file — do NOT skip this step
 
+**CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
+
 **8b. Update STATE.md:**
 - Phase status: {final_status from Step 8-pre}
 - Plan completion count
@@ -803,18 +809,20 @@ Then present the appropriate branded banner:
 
 **If `passed` + more phases:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- 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}
 
@@ -822,28 +830,30 @@ Goal verified ✓
 
 <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 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} phases completed
 All phase goals verified ✓
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Audit milestone** — verify requirements, cross-phase integration, E2E flows
 
@@ -851,20 +861,20 @@ All phase goals verified ✓
 
 <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 ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                     ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -875,9 +885,11 @@ 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
 
@@ -885,13 +897,13 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 <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
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 **8g. Display USER-SETUP.md (conditional):**

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

@@ -11,9 +11,9 @@ allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► CONFIGURATION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► CONFIGURATION                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -187,17 +187,19 @@ If user types something else (freeform): interpret as a direct setting command a
 
 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
 
@@ -205,13 +207,13 @@ Updated:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:config` — change more settings
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ## Config Schema