@sienklogic/plan-build-run 2.10.0 → 2.11.0

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

@@ -19,9 +19,9 @@ This skill **spawns a single Task(subagent_type: "pbr:executor")** for execution
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► QUICK TASK
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► QUICK TASK                                 ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -250,17 +250,19 @@ Display results to the user with branded output:
 
 **If completed:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► QUICK TASK COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► QUICK TASK COMPLETE ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Quick Task {NNN}:** {description}
 Commit: {hash} — {commit message}
 Files: {list of files changed}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — task complete
 
@@ -268,13 +270,13 @@ Files: {list of files changed}
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:todo list` — see pending todos
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 **If partial:**

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

@@ -11,9 +11,9 @@ allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► RESUMING SESSION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RESUMING SESSION                           ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -147,9 +147,9 @@ Use the selected pause point for the rest of the resume flow.
 3. Display the resume context using the branded banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SESSION RESTORED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 Resuming session from {pause date}
 
@@ -182,9 +182,11 @@ Blockers:
 
 **If only one clear next action exists**, present it with branded routing:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{explanation from continue-here}**
 
@@ -192,7 +194,7 @@ Blockers:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 **If multiple reasonable actions exist** (e.g., the continue-here suggests one thing but the filesystem state suggests another), use the **action-routing** pattern (see `skills/shared/gate-prompts.md`):

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

@@ -23,9 +23,9 @@ Additionally for this skill:
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► REVIEWING PHASE {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► REVIEWING PHASE {N}                        ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
@@ -66,6 +66,7 @@ Execute these steps in order.
 
 1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
 2. Read `.planning/config.json`
+   **CRITICAL: Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
 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. Validate:
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
@@ -574,6 +575,10 @@ Ask user: "Would you like to proceed with gap-closure plans without root cause a
 
 ---
 
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
 ## Completion
 
 After review completes, always present a clear next action:
@@ -582,9 +587,9 @@ After review completes, always present a clear next action:
 
 Display the "Phase Complete" banner inline:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                       ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -594,9 +599,11 @@ Goal verified ✓
 
 Then the branded "Next Up" block:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
 
@@ -604,26 +611,28 @@ Then the branded "Next Up" block:
 
 <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 ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                     ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {name}** — {count} gaps remaining
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Fix gaps** — diagnose and create fix plans
 
@@ -631,22 +640,22 @@ Then the branded "Next Up" block:
 
 <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 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} phases completed
 All phase goals verified ✓
@@ -654,9 +663,11 @@ All phase goals verified ✓
 
 Then:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Audit milestone** — verify cross-phase integration
 
@@ -664,14 +675,14 @@ Then:
 
 <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
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---

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

@@ -11,9 +11,9 @@ allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCANNING CODEBASE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCANNING CODEBASE                          ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -180,9 +180,9 @@ Agent that failed: {focus_area} mapper
 Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-formatting.md`:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SCAN COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCAN COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
 
 Project: {type} ({scale})
 Stack: {primary language} + {framework}
@@ -209,9 +209,11 @@ Top concerns:
 
 Then use the "Next Up" routing block:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Start a project** — use the scan results to plan your work
 
@@ -219,13 +221,13 @@ Then use the "Next Up" routing block:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:milestone new` — create a milestone to address concerns
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### Step 7: Git Integration

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

@@ -11,9 +11,9 @@ allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SETUP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SETUP                                      ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -24,14 +24,29 @@ You are running the **setup** skill. This is an interactive onboarding wizard th
 
 ---
 
-## Step 1: Detect Project State
+## Step 1: Detect Project State — Idempotency Guard
 
 Check if `.planning/` directory exists in the current working directory.
 
 **If `.planning/` exists**:
-- Read `.planning/config.json` to check current settings
-- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
-- Skip to Step 3 (model selection)
+- Check for existing core files: `STATE.md`, `ROADMAP.md`, `config.json`
+- If ANY of these exist, present a checkpoint:
+
+  Use AskUserQuestion:
+    question: "Existing project detected with {list of found files}. How should we proceed?"
+    header: "Setup"
+    options:
+      - label: "Resume"       description: "Keep existing .planning/ and review configuration (recommended)"
+      - label: "Reset"        description: "Archive current .planning/ to .planning.bak/ and start fresh"
+      - label: "Abort"        description: "Cancel setup — keep everything as-is"
+
+  - If "Resume": Tell the user: "Keeping existing project. Reviewing configuration." Skip to Step 3 (model selection)
+  - If "Reset": Run `mv .planning .planning.bak` (creating a backup), then proceed with fresh setup below
+  - If "Abort": Display "Setup cancelled. Run `/pbr:status` to see current project state." and stop
+
+- If `.planning/` exists but has NONE of the core files (empty or only has subdirs):
+  - Tell the user: "Found empty .planning/ directory. Proceeding with initialization."
+  - Continue to fresh setup below
 
 **If `.planning/` does NOT exist**:
 - Ask the user:
@@ -51,10 +66,14 @@ If "No", display: "Run `/pbr:begin` when you're ready to start a project. It inc
 
 If "Yes", create the minimal `.planning/` structure:
 
+**CRITICAL: Create .planning/ directory structure NOW. Do NOT skip this step.**
+
 ```bash
 mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
 ```
 
+**CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
+
 Create `.planning/config.json` with defaults:
 ```json
 {
@@ -123,6 +142,8 @@ Create `.planning/config.json` with defaults:
 }
 ```
 
+**CRITICAL: Write .planning/STATE.md NOW. Do NOT skip this step.**
+
 Create `.planning/STATE.md`:
 ```markdown
 ---
@@ -243,6 +264,8 @@ This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run)
 
 ## Step 5: Verification
 
+**CRITICAL: Run validation checks NOW to confirm setup succeeded. Do NOT skip this step.**
+
 Run a quick health check:
 
 1. Verify `.planning/config.json` is valid JSON

package/plugins/pbr/skills/shared/error-reporting.md

@@ -77,3 +77,5 @@ Blocked: {short reason}
 ```
 
 This format is used by validate-commit.js and check-dangerous-commands.js. The `decision: "block"` and `reason` fields in the JSON output follow this pattern.
+
+Block reasons should always include a "To fix:" line with actionable guidance so the user or agent knows how to resolve the block.

package/plugins/pbr/skills/shared/universal-anti-patterns.md

@@ -23,11 +23,15 @@ These rules prevent context rot -- quality degradation as the context window fil
 8. **Never** read `.planning/logs/` files -- only the health skill reads these.
 9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields.
 
+## Task/Subagent Rules (apply to every skill)
+
+10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Subagents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
+
 ## Behavioral Rules (apply to every skill)
 
-10. **Do not** re-litigate decisions that are already locked in CONTEXT.md -- respect locked decisions unconditionally.
-11. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
-12. **Do not** modify files outside the skill's stated scope -- check the "Files Created/Modified" table in each skill.
-13. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
-14. **Do not** use `git add .` or `git add -A` -- stage specific files only.
-15. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+11. **Do not** re-litigate decisions that are already locked in CONTEXT.md -- respect locked decisions unconditionally.
+12. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
+13. **Do not** modify files outside the skill's stated scope -- check the "Files Created/Modified" table in each skill.
+14. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
+15. **Do not** use `git add .` or `git add -A` -- stage specific files only.
+16. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.

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

@@ -11,9 +11,9 @@ allowed-tools: Read, Glob, Grep, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PROJECT STATUS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PROJECT STATUS                             ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -268,9 +268,11 @@ Based on the project state, suggest the single most logical next action:
 **If only one reasonable next action exists**, present it with branded routing:
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{brief explanation}**
 
@@ -278,7 +280,7 @@ Based on the project state, suggest the single most logical next action:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 **If multiple reasonable next actions exist** (2-3 alternatives), use the **action-routing** pattern (see `skills/shared/gate-prompts.md`):

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

@@ -12,9 +12,9 @@ argument-hint: "[install | uninstall | preview]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STATUS LINE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STATUS LINE                                ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -78,9 +78,12 @@ If "Install":
 
 **CRITICAL: Use Read tool to read the file, then Write to update it. Do NOT use sed or other text manipulation on JSON files.**
 
+**CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+
 1. Read `~/.claude/settings.json`
-2. Parse the JSON
-3. Set `statusLine` to:
+2. Write the original content to `~/.claude/settings.json.bak`
+3. Parse the JSON
+4. Set `statusLine` to:
    ```json
    {
      "type": "command",
@@ -88,7 +91,7 @@ If "Install":
    }
    ```
    Where `SCRIPT_PATH` is the resolved absolute path from Step 1. Use forward slashes even on Windows.
-4. Write the updated JSON back (preserve all other settings, use 2-space indentation)
+5. Write the updated JSON back (preserve all other settings, use 2-space indentation)
 
 ### Step 4: Verify and confirm
 
@@ -115,8 +118,9 @@ Customize per-project via .planning/config.json:
 
 1. Read `~/.claude/settings.json`
 2. If no `statusLine` key: inform user "No status line configured." and stop
-3. Remove the `statusLine` key from the JSON
-4. Write the updated file
+3. **CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+4. Remove the `statusLine` key from the JSON
+5. Write the updated file
 5. Display: `✓ PBR status line removed. Restart Claude Code to take effect.`
 
 ---