@sienklogic/plan-build-run 2.9.1 → 2.11.0

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

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

@@ -19,9 +19,9 @@ This skill runs **inline** and may delegate to other skills via Task().
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► NEXT STEP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► NEXT STEP                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -121,21 +121,23 @@ Where `{N}` is the current phase number determined from STATE.md in Step 1.
 
 After execution completes, display a branded completion:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STEP COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STEP COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
 
 ✓ Completed: {what was done}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Next action description}**
 
 `/pbr:continue` or `{specific command}`
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 **If `features.auto_advance` is `true` AND `mode` is `autonomous`:**

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

@@ -7,6 +7,18 @@ argument-hint: "[--port N]"
 
 **STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing immediately.**
 
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DASHBOARD                                  ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
 ## Behavior
 
 1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.

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

@@ -12,9 +12,9 @@ argument-hint: "[issue description]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DEBUGGING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DEBUGGING                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -68,9 +68,11 @@ Scan `.planning/debug/` for existing debug files:
 ```
 
 Read each file's frontmatter to check status:
-- `status: active` — session is in progress
-- `status: resolved` — session is complete
-- `status: stale` — session was abandoned
+- `status: gathering` — collecting symptoms from user
+- `status: investigating` — testing hypotheses
+- `status: fixing` — applying fix
+- `status: verifying` — confirming fix works
+- `status: resolved` — session complete
 
 **If active sessions found:**
 
@@ -129,7 +131,7 @@ Create `.planning/debug/{NNN}-{slug}.md`:
 ---
 id: "{NNN}"
 title: "{issue title}"
-status: active
+status: gathering
 created: "{ISO date}"
 updated: "{ISO date}"
 severity: "{critical|high|medium|low}"
@@ -233,18 +235,20 @@ Actions:
 3. Report to user with branded output:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► BUG RESOLVED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► BUG RESOLVED ✓                             ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Session #{NNN}:** {title}
 **Root cause:** {cause}
 **Fix:** {description}
 **Commit:** {hash}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — the bug is fixed
 
@@ -252,13 +256,13 @@ Actions:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:review {N}` — verify the current phase
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 #### ROOT CAUSE FOUND (no fix)
@@ -278,9 +282,11 @@ Actions:
 2. Suggest next steps to user:
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Apply the fix** — root cause identified, fix needed
 
@@ -288,13 +294,13 @@ Actions:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:plan` — for complex fixes that need planning
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 #### CHECKPOINT
@@ -404,7 +410,7 @@ Use AskUserQuestion:
     - label: "Escalate"  description: "Save context for manual debugging"
 
 - If "Extend": double the limit and continue
-- If "Wrap up": update debug file status to `stale`, record all findings, suggest next steps
+- If "Wrap up": update debug file `status: resolved` with `resolution: abandoned`, record all findings, suggest next steps
 - If "Escalate": write a detailed handoff document to the debug file with all hypotheses, evidence, and suggested manual investigation steps
 
 ---
@@ -414,15 +420,15 @@ Use AskUserQuestion:
 ### Lifecycle
 
 ```
-active → resolved     (root cause found and fixed)
-active → stale        (abandoned — no updates for 7+ days)
-active → active       (resumed after pause)
+gathering → investigating → fixing → verifying → resolved
+(any non-resolved) → resolved  (with resolution: abandoned, if 7+ days stale)
+(any non-resolved) → (same)    (resumed after pause)
 ```
 
 ### Staleness Detection
 
 When scanning for active sessions, check the `updated` date. If more than 7 days old:
-- Mark as `stale` in status
+- Set `status: resolved` with `resolution: abandoned` in frontmatter
 - Still offer to resume, but warn: "This session is {N} days old. Context may have changed."
 
 ### Cleanup