@sienklogic/plan-build-run 2.9.1 → 2.11.0

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

@@ -12,9 +12,9 @@ argument-hint: "<phase-number>"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DISCUSSION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION                                 ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -153,17 +153,23 @@ If more than 3 concrete options exist for a gray area, present only the top 3 pl
 
 For each gray area where the user made a decision (not "Let Claude decide"), ask **4 follow-up questions** to fully capture their intent.
 
+**CRITICAL — STOP: Do NOT skip ANY of the 4 follow-up areas below. All 4 MUST be asked for each gray area where the user made a decision.**
+
 **Follow-up question types:**
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 1. **Scope boundary**: "Should {feature} also handle {edge case}?"
    Use the **yes-no** pattern — this is a binary decision.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 2. **Quality level**: "How polished should this be?"
    Do NOT use AskUserQuestion — this is freeform. Let the user describe their quality expectations in their own words.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 3. **Integration**: "How should this interact with {existing component}?"
    Do NOT use AskUserQuestion — this is freeform. The answer depends on the specific component and context.
 
+**CRITICAL — STOP: Do NOT skip this follow-up area.**
 4. **Future-proofing**: "Should we design this to support {potential future need}, or keep it simple?"
    Use the **yes-no** pattern:
      question: "Design {feature} to support {future need}, or keep it simple for now?"
@@ -177,6 +183,8 @@ For each gray area where the user made a decision (not "Let Claude decide"), ask
 - If the user gives a short answer, capture it as-is
 - If the user says "you decide" on a follow-up, move that specific sub-decision to Claude's Discretion
 
+**Completion check:** After all follow-up questions for all gray areas, verify that all 4 follow-up areas produced output for each decided gray area. If any area was missed, go back and ask it before proceeding to Step 6.
+
 ### Step 6: Capture Deferred Ideas
 
 During the conversation, the user may mention ideas they want but not in this phase. Track these separately:
@@ -221,17 +229,19 @@ This creates a pointer so `/pbr:resume` and `progress-tracker.js` know that phas
 After writing CONTEXT.md, display branded output:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {name}**
 
 Decisions: {count} locked, {count} deferred, {count} discretion
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan this phase** — your decisions will be honored
 
@@ -239,13 +249,13 @@ Decisions: {count} locked, {count} deferred, {count} discretion
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:status` — see project status
 - `/pbr:explore` — explore ideas further
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---

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

@@ -16,9 +16,9 @@ You are running the **do** skill. Your job is to analyze freeform text from the
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► ROUTING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► ROUTING                                    ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.

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

@@ -12,9 +12,9 @@ argument-hint: "[topic]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► EXPLORING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► EXPLORING                                  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -178,7 +178,7 @@ Suggest specific outputs with reasoning. Present no more than 4 suggestions —
 | Phase decision | Clarifies an existing phase | Write/append to phase `CONTEXT.md` |
 | Research question | Needs deeper investigation | `.planning/research/questions.md` |
 | New phase | Big enough for its own phase | Append to `ROADMAP.md` |
-| Note | Not actionable yet, worth remembering | `.planning/notes/{slug}.md` |
+| Note | Not actionable yet, worth remembering | `.planning/notes/{YYYY-MM-DD}-{slug}.md` |
 | Quick capture | One-liner idea, no context needed | Suggest `/pbr:note <text>` to the user |
 | Seed | Idea with trigger conditions | `.planning/seeds/SEED-{NNN}-{slug}.md` |
 
@@ -218,15 +218,17 @@ Create only the approved artifacts. A single explore session can produce multipl
 After creating artifacts (or if user chose "Skip"), display:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
 
 {count} artifacts created: {list of artifact types}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Primary route based on what was created}**
 
@@ -242,14 +244,14 @@ After creating artifacts (or if user chose "Skip"), display:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:status` — see project status
 - `/pbr:continue` — execute next logical step
 - `/pbr:milestone new` — start a new milestone with new phases
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---
@@ -292,7 +294,7 @@ Append to `.planning/ROADMAP.md` following the existing phase format. Assign the
 
 ### Note
 
-Write to `.planning/notes/{NNN}-{slug}.md` where NNN is a zero-padded 3-digit sequential number (001, 002, 003...). Scan `.planning/notes/` for the highest existing number prefix, increment by 1, and zero-pad.
+Write to `.planning/notes/{YYYY-MM-DD}-{slug}.md` where the date prefix is today's date in ISO format. Scan `.planning/notes/` to avoid filename collisions — if a file with the same date and slug exists, append `-2` (or increment).
 
 ```markdown
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: health
 description: "Check planning directory integrity. Find and fix corrupted state."
-allowed-tools: Read, Bash, Glob, Grep
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 
 **STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
@@ -11,9 +11,9 @@ allowed-tools: Read, Bash, Glob, Grep
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► HEALTH CHECK
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK                               ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -22,7 +22,7 @@ Then proceed to Step 1.
 
 You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes. You never auto-repair anything.
 
-This skill runs **inline** and is **read-only** — it never modifies any files.
+This skill runs **inline**. It is read-only by default, but offers an optional **auto-fix** flow for common corruption patterns (see the Auto-Fix section below).
 
 ---
 
@@ -152,6 +152,58 @@ Glob for `.planning/phases/**/.PROGRESS-*` and `.planning/phases/**/.checkpoint-
 
 ---
 
+## Auto-Fix for Common Corruption Patterns
+
+After running all 10 checks and collecting results, if any of the following auto-fixable issues were found, offer to fix them.
+
+### Auto-Fixable Patterns
+
+| Pattern | Detection | Fix Action |
+|---------|-----------|------------|
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, total_phases, status) |
+| STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
+| Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `/pbr:setup` defaults) |
+| Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |
+| Empty phases directory | Check 3 finds `.planning/phases/` missing | Create the directory: `mkdir -p .planning/phases` |
+| STATE.md over 150 lines | Check 5 finds STATE.md exceeds 150 lines | Compact the `## Accumulated Context` section, keeping only the last 3 entries |
+
+### Auto-Fix Flow
+
+After displaying health check results, if any auto-fixable issues were detected:
+
+1. Count the auto-fixable issues and present:
+
+   Use AskUserQuestion:
+     question: "Found {N} auto-fixable issues. How should we handle them?"
+     header: "Fix?"
+     options:
+       - label: "Fix all"       description: "Apply all {N} fixes automatically"
+       - label: "Review each"   description: "Show each fix and confirm individually"
+       - label: "Skip"          description: "Do nothing — just report"
+
+2. If "Fix all": Apply all fixes in order, then display a summary:
+   ```
+   Auto-fix results:
+   - Fixed: {description of fix 1}
+   - Fixed: {description of fix 2}
+   ...
+   ```
+
+3. If "Review each": For each fixable issue, display:
+   ```
+   Issue: {description}
+   Fix: {what will be done}
+   ```
+   Then ask via AskUserQuestion (yes/no): "Apply this fix?"
+   - If yes: apply and display `- Fixed: {description}`
+   - If no: skip and display `- Skipped: {description}`
+
+4. If "Skip": Do nothing, continue to the rest of the output.
+
+**Note:** When auto-fix is active, the health skill is no longer strictly read-only. The `allowed-tools` frontmatter must include `Write` and `AskUserQuestion` for auto-fix to work. Update the frontmatter accordingly.
+
+---
+
 ## Bonus: Recent Decisions
 
 After all checks, look for `.planning/logs/decisions.jsonl`. If it exists, display the last 5 entries as `- {date}: {summary} (phase {N})`. If it does not exist, skip silently.
@@ -164,15 +216,17 @@ After all checks complete, display the branded result:
 
 **If all checks passed (0 failures):**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} checks passed, {M} warnings
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Continue your workflow** — planning directory is healthy
 
@@ -180,40 +234,42 @@ After all checks complete, display the branded result:
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:config` — adjust settings
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 **If failures found:**
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 {N} checks passed, {F} failures, {M} warnings
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Fix the failures** listed above, then re-run
 
 `/pbr:health`
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---
 
 ## Anti-Patterns
 
-1. **DO NOT** modify any files — this is strictly read-only
-2. **DO NOT** auto-repair anything — present fixes and let the user decide
+1. **DO NOT** modify files without user consent — auto-fix requires explicit user approval via AskUserQuestion
+2. **DO NOT** auto-repair anything silently — always present fixes and let the user decide
 3. **DO NOT** skip checks that depend on missing files — report the dependency failure and continue
 4. **DO NOT** treat warnings as failures in the summary count — only count FAIL items
 5. **DO NOT** read full plan/summary contents — frontmatter and existence checks are sufficient

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

@@ -11,9 +11,9 @@ allowed-tools: Read
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► COMMAND REFERENCE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► COMMAND REFERENCE                          ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -137,16 +137,18 @@ Skills automatically activate the appropriate context: `/pbr:build` uses dev con
 ## Getting Started
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 → `/pbr:begin` — start a new project
 → `/pbr:status` — check current project status
 → `/pbr:config` — configure workflow settings
 → `/pbr:help <command>` — detailed help for a specific command
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ## Getting Help

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

@@ -12,9 +12,9 @@ argument-hint: "<phase-number> [--from <filepath>] [--skip-checker]"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► IMPORTING PLAN
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► IMPORTING PLAN                             ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -51,11 +51,12 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number
 2. Parse optional `--from <filepath>` flag (path to the external document to import)
 3. Parse optional `--skip-checker` flag (skip plan validation step)
-4. Validate:
+4. **CRITICAL: Write .active-skill NOW.** Write the text "import" to `.planning/.active-skill` using the Write tool.
+5. Validate:
    - Phase exists in ROADMAP.md
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
-5. If no phase number given, read current phase from `.planning/STATE.md`
-6. Check for existing plans in the phase directory (glob for `*-PLAN.md`)
+6. If no phase number given, read current phase from `.planning/STATE.md`
+7. Check for existing plans in the phase directory (glob for `*-PLAN.md`)
    - If plans exist: ask user via AskUserQuestion: "Phase {N} already has plans. Replace them with imported plans?"
    - If yes: note that existing plans will be overwritten in Step 7
    - If no: stop
@@ -323,7 +324,7 @@ Follow the revision loop with:
 
 ### Step 7: Write PLAN.md Files (inline)
 
-Write each plan to `.planning/phases/{NN}-{slug}/{phase}-{plan_num}-PLAN.md`.
+Write each plan to `.planning/phases/{NN}-{slug}/PLAN-{plan_num}.md`.
 
 If existing plans are being replaced (user confirmed in Step 1):
 - Delete existing `*-PLAN.md` files in the phase directory before writing new ones
@@ -381,14 +382,18 @@ docs({phase}): import plans for phase {N} ({count} plans, {wave_count} waves)
 
 ---
 
-### Step 10: Confirm (inline)
+### Step 10: Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
+### Step 11: Confirm (inline)
 
 Present a summary of the import using the branded banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► IMPORT COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► IMPORT COMPLETE ✓                          ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {name}** — {plan_count} plans imported
 
@@ -407,9 +412,11 @@ Wave execution order:
 Must-haves coverage: {count} truths across {plan_count} plans
 Requirements traced: {count}/{total} REQ-IDs covered
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Build Phase {N}** — execute these imported plans
 
@@ -417,19 +424,21 @@ Requirements traced: {count}/{total} REQ-IDs covered
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:plan {N}` — re-plan from scratch if import needs rework
 - `/pbr:discuss {N}` — talk through details before building
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ---
 
 ## Error Handling
 
+**IMPORTANT:** On ALL error exits below, delete `.planning/.active-skill` if it exists before displaying the error message.
+
 ### Phase not found
 If the specified phase does not exist in ROADMAP.md, display:
 ```
@@ -498,7 +507,7 @@ Present remaining issues and ask user to decide: proceed or intervene.
 
 | File | Purpose | When |
 |------|---------|------|
-| `.planning/phases/{NN}-{slug}/{phase}-{NN}-PLAN.md` | Imported plan files | Step 7 |
+| `.planning/phases/{NN}-{slug}/PLAN-{NN}.md` | Imported plan files | Step 7 |
 | `.planning/ROADMAP.md` | Plans Complete + Status updated to `planned` | Step 8a |
 | `.planning/STATE.md` | Updated with plan status and import source | Step 8b |
 | `.planning/CONTEXT.md` | Updated if blockers surfaced new locked decisions | Step 8d |