@sienklogic/plan-build-run 2.10.0 → 2.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/package.json +1 -1
  3. package/plugins/copilot-pbr/agents/codebase-mapper.agent.md +42 -0
  4. package/plugins/copilot-pbr/agents/debugger.agent.md +4 -1
  5. package/plugins/copilot-pbr/agents/executor.agent.md +31 -1
  6. package/plugins/copilot-pbr/agents/integration-checker.agent.md +33 -2
  7. package/plugins/copilot-pbr/agents/planner.agent.md +58 -1
  8. package/plugins/copilot-pbr/agents/researcher.agent.md +23 -0
  9. package/plugins/copilot-pbr/agents/synthesizer.agent.md +24 -0
  10. package/plugins/copilot-pbr/agents/verifier.agent.md +35 -1
  11. package/plugins/copilot-pbr/plugin.json +1 -1
  12. package/plugins/copilot-pbr/references/agent-contracts.md +297 -0
  13. package/plugins/copilot-pbr/references/ui-formatting.md +38 -56
  14. package/plugins/copilot-pbr/skills/begin/SKILL.md +30 -7
  15. package/plugins/copilot-pbr/skills/build/SKILL.md +28 -31
  16. package/plugins/copilot-pbr/skills/config/SKILL.md +9 -12
  17. package/plugins/copilot-pbr/skills/continue/SKILL.md +6 -6
  18. package/plugins/copilot-pbr/skills/dashboard/SKILL.md +3 -3
  19. package/plugins/copilot-pbr/skills/debug/SKILL.md +23 -26
  20. package/plugins/copilot-pbr/skills/discuss/SKILL.md +20 -10
  21. package/plugins/copilot-pbr/skills/do/SKILL.md +3 -3
  22. package/plugins/copilot-pbr/skills/explore/SKILL.md +11 -14
  23. package/plugins/copilot-pbr/skills/health/SKILL.md +75 -19
  24. package/plugins/copilot-pbr/skills/help/SKILL.md +6 -6
  25. package/plugins/copilot-pbr/skills/import/SKILL.md +22 -18
  26. package/plugins/copilot-pbr/skills/milestone/SKILL.md +90 -48
  27. package/plugins/copilot-pbr/skills/note/SKILL.md +3 -3
  28. package/plugins/copilot-pbr/skills/pause/SKILL.md +11 -10
  29. package/plugins/copilot-pbr/skills/plan/SKILL.md +22 -9
  30. package/plugins/copilot-pbr/skills/plan/templates/planner-prompt.md.tmpl +1 -1
  31. package/plugins/copilot-pbr/skills/quick/SKILL.md +9 -12
  32. package/plugins/copilot-pbr/skills/resume/SKILL.md +9 -9
  33. package/plugins/copilot-pbr/skills/review/SKILL.md +17 -12
  34. package/plugins/copilot-pbr/skills/scan/SKILL.md +9 -11
  35. package/plugins/copilot-pbr/skills/setup/SKILL.md +31 -8
  36. package/plugins/copilot-pbr/skills/shared/error-reporting.md +2 -1
  37. package/plugins/copilot-pbr/skills/shared/progress-display.md +0 -1
  38. package/plugins/copilot-pbr/skills/shared/universal-anti-patterns.md +10 -6
  39. package/plugins/copilot-pbr/skills/status/SKILL.md +3 -3
  40. package/plugins/copilot-pbr/skills/statusline/SKILL.md +12 -8
  41. package/plugins/copilot-pbr/skills/todo/SKILL.md +51 -28
  42. package/plugins/cursor-pbr/.cursor-plugin/plugin.json +1 -1
  43. package/plugins/cursor-pbr/agents/codebase-mapper.md +42 -0
  44. package/plugins/cursor-pbr/agents/debugger.md +4 -1
  45. package/plugins/cursor-pbr/agents/executor.md +31 -1
  46. package/plugins/cursor-pbr/agents/integration-checker.md +33 -2
  47. package/plugins/cursor-pbr/agents/planner.md +58 -1
  48. package/plugins/cursor-pbr/agents/researcher.md +23 -0
  49. package/plugins/cursor-pbr/agents/synthesizer.md +24 -0
  50. package/plugins/cursor-pbr/agents/verifier.md +35 -1
  51. package/plugins/cursor-pbr/references/agent-contracts.md +297 -0
  52. package/plugins/cursor-pbr/references/ui-formatting.md +38 -56
  53. package/plugins/cursor-pbr/skills/begin/SKILL.md +30 -7
  54. package/plugins/cursor-pbr/skills/build/SKILL.md +28 -31
  55. package/plugins/cursor-pbr/skills/config/SKILL.md +9 -10
  56. package/plugins/cursor-pbr/skills/continue/SKILL.md +6 -6
  57. package/plugins/cursor-pbr/skills/dashboard/SKILL.md +3 -3
  58. package/plugins/cursor-pbr/skills/debug/SKILL.md +23 -23
  59. package/plugins/cursor-pbr/skills/discuss/SKILL.md +20 -10
  60. package/plugins/cursor-pbr/skills/do/SKILL.md +3 -3
  61. package/plugins/cursor-pbr/skills/explore/SKILL.md +11 -12
  62. package/plugins/cursor-pbr/skills/health/SKILL.md +75 -19
  63. package/plugins/cursor-pbr/skills/help/SKILL.md +6 -6
  64. package/plugins/cursor-pbr/skills/import/SKILL.md +22 -16
  65. package/plugins/cursor-pbr/skills/milestone/SKILL.md +90 -48
  66. package/plugins/cursor-pbr/skills/note/SKILL.md +3 -3
  67. package/plugins/cursor-pbr/skills/pause/SKILL.md +11 -9
  68. package/plugins/cursor-pbr/skills/plan/SKILL.md +22 -9
  69. package/plugins/cursor-pbr/skills/plan/templates/planner-prompt.md.tmpl +1 -1
  70. package/plugins/cursor-pbr/skills/quick/SKILL.md +9 -12
  71. package/plugins/cursor-pbr/skills/resume/SKILL.md +9 -9
  72. package/plugins/cursor-pbr/skills/review/SKILL.md +17 -12
  73. package/plugins/cursor-pbr/skills/scan/SKILL.md +9 -10
  74. package/plugins/cursor-pbr/skills/setup/SKILL.md +31 -8
  75. package/plugins/cursor-pbr/skills/shared/error-reporting.md +2 -1
  76. package/plugins/cursor-pbr/skills/shared/progress-display.md +0 -1
  77. package/plugins/cursor-pbr/skills/shared/universal-anti-patterns.md +10 -6
  78. package/plugins/cursor-pbr/skills/status/SKILL.md +3 -3
  79. package/plugins/cursor-pbr/skills/statusline/SKILL.md +12 -8
  80. package/plugins/cursor-pbr/skills/todo/SKILL.md +51 -28
  81. package/plugins/pbr/.claude-plugin/plugin.json +1 -1
  82. package/plugins/pbr/agents/codebase-mapper.md +42 -0
  83. package/plugins/pbr/agents/debugger.md +4 -1
  84. package/plugins/pbr/agents/executor.md +31 -1
  85. package/plugins/pbr/agents/integration-checker.md +34 -2
  86. package/plugins/pbr/agents/planner.md +58 -1
  87. package/plugins/pbr/agents/researcher.md +23 -0
  88. package/plugins/pbr/agents/synthesizer.md +24 -0
  89. package/plugins/pbr/agents/verifier.md +36 -1
  90. package/plugins/pbr/references/agent-contracts.md +297 -0
  91. package/plugins/pbr/references/ui-formatting.md +37 -54
  92. package/plugins/pbr/scripts/check-skill-workflow.js +11 -0
  93. package/plugins/pbr/scripts/check-state-sync.js +58 -0
  94. package/plugins/pbr/scripts/check-subagent-output.js +43 -4
  95. package/plugins/pbr/scripts/validate-task.js +69 -17
  96. package/plugins/pbr/skills/begin/SKILL.md +36 -11
  97. package/plugins/pbr/skills/build/SKILL.md +37 -25
  98. package/plugins/pbr/skills/config/SKILL.md +12 -10
  99. package/plugins/pbr/skills/continue/SKILL.md +11 -9
  100. package/plugins/pbr/skills/dashboard/SKILL.md +3 -3
  101. package/plugins/pbr/skills/debug/SKILL.md +29 -23
  102. package/plugins/pbr/skills/discuss/SKILL.md +20 -10
  103. package/plugins/pbr/skills/do/SKILL.md +3 -3
  104. package/plugins/pbr/skills/explore/SKILL.md +14 -12
  105. package/plugins/pbr/skills/health/SKILL.md +76 -20
  106. package/plugins/pbr/skills/help/SKILL.md +8 -6
  107. package/plugins/pbr/skills/import/SKILL.md +25 -16
  108. package/plugins/pbr/skills/milestone/SKILL.md +88 -45
  109. package/plugins/pbr/skills/note/SKILL.md +3 -3
  110. package/plugins/pbr/skills/pause/SKILL.md +13 -9
  111. package/plugins/pbr/skills/plan/SKILL.md +28 -13
  112. package/plugins/pbr/skills/plan/templates/planner-prompt.md.tmpl +1 -1
  113. package/plugins/pbr/skills/quick/SKILL.md +12 -10
  114. package/plugins/pbr/skills/resume/SKILL.md +11 -9
  115. package/plugins/pbr/skills/review/SKILL.md +35 -24
  116. package/plugins/pbr/skills/scan/SKILL.md +12 -10
  117. package/plugins/pbr/skills/setup/SKILL.md +30 -7
  118. package/plugins/pbr/skills/shared/error-reporting.md +2 -0
  119. package/plugins/pbr/skills/shared/universal-anti-patterns.md +10 -6
  120. package/plugins/pbr/skills/status/SKILL.md +8 -6
  121. package/plugins/pbr/skills/statusline/SKILL.md +12 -8
  122. package/plugins/pbr/skills/todo/SKILL.md +51 -28
@@ -19,9 +19,9 @@ This skill runs **inline** and may delegate to other skills via Task().
19
19
  **Before ANY tool calls**, display this banner:
20
20
 
21
21
  ```
22
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
23
- PLAN-BUILD-RUN ► NEXT STEP
24
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
22
+ ╔══════════════════════════════════════════════════════════════╗
23
+ PLAN-BUILD-RUN ► NEXT STEP
24
+ ╚══════════════════════════════════════════════════════════════╝
25
25
  ```
26
26
 
27
27
  Then proceed to Step 1.
@@ -121,21 +121,23 @@ Where `{N}` is the current phase number determined from STATE.md in Step 1.
121
121
 
122
122
  After execution completes, display a branded completion:
123
123
  ```
124
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
125
- PLAN-BUILD-RUN ► STEP COMPLETE ✓
126
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
124
+ ╔══════════════════════════════════════════════════════════════╗
125
+ PLAN-BUILD-RUN ► STEP COMPLETE ✓
126
+ ╚══════════════════════════════════════════════════════════════╝
127
127
 
128
128
  ✓ Completed: {what was done}
129
129
 
130
- ───────────────────────────────────────────────────────────────
131
130
 
132
- ## ▶ Next Up
131
+
132
+ ╔══════════════════════════════════════════════════════════════╗
133
+ ║ ▶ NEXT UP ║
134
+ ╚══════════════════════════════════════════════════════════════╝
133
135
 
134
136
  **{Next action description}**
135
137
 
136
138
  `/pbr:continue` or `{specific command}`
137
139
 
138
- ───────────────────────────────────────────────────────────────
140
+
139
141
  ```
140
142
 
141
143
  **If `features.auto_advance` is `true` AND `mode` is `autonomous`:**
@@ -12,9 +12,9 @@ argument-hint: "[--port N]"
12
12
  **Before ANY tool calls**, display this banner:
13
13
 
14
14
  ```
15
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
16
- PLAN-BUILD-RUN ► DASHBOARD
17
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
15
+ ╔══════════════════════════════════════════════════════════════╗
16
+ PLAN-BUILD-RUN ► DASHBOARD
17
+ ╚══════════════════════════════════════════════════════════════╝
18
18
  ```
19
19
 
20
20
  Then proceed to Step 1.
@@ -12,9 +12,9 @@ argument-hint: "[issue description]"
12
12
  **Before ANY tool calls**, display this banner:
13
13
 
14
14
  ```
15
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
16
- PLAN-BUILD-RUN ► DEBUGGING
17
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
15
+ ╔══════════════════════════════════════════════════════════════╗
16
+ PLAN-BUILD-RUN ► DEBUGGING
17
+ ╚══════════════════════════════════════════════════════════════╝
18
18
  ```
19
19
 
20
20
  Then proceed to Step 1.
@@ -68,9 +68,11 @@ Scan `.planning/debug/` for existing debug files:
68
68
  ```
69
69
 
70
70
  Read each file's frontmatter to check status:
71
- - `status: active` — session is in progress
72
- - `status: resolved` — session is complete
73
- - `status: stale` — session was abandoned
71
+ - `status: gathering` — collecting symptoms from user
72
+ - `status: investigating` — testing hypotheses
73
+ - `status: fixing` — applying fix
74
+ - `status: verifying` — confirming fix works
75
+ - `status: resolved` — session complete
74
76
 
75
77
  **If active sessions found:**
76
78
 
@@ -129,7 +131,7 @@ Create `.planning/debug/{NNN}-{slug}.md`:
129
131
  ---
130
132
  id: "{NNN}"
131
133
  title: "{issue title}"
132
- status: active
134
+ status: gathering
133
135
  created: "{ISO date}"
134
136
  updated: "{ISO date}"
135
137
  severity: "{critical|high|medium|low}"
@@ -233,18 +235,20 @@ Actions:
233
235
  3. Report to user with branded output:
234
236
 
235
237
  ```
236
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
237
- PLAN-BUILD-RUN ► BUG RESOLVED ✓
238
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
238
+ ╔══════════════════════════════════════════════════════════════╗
239
+ PLAN-BUILD-RUN ► BUG RESOLVED ✓
240
+ ╚══════════════════════════════════════════════════════════════╝
239
241
 
240
242
  **Session #{NNN}:** {title}
241
243
  **Root cause:** {cause}
242
244
  **Fix:** {description}
243
245
  **Commit:** {hash}
244
246
 
245
- ───────────────────────────────────────────────────────────────
246
247
 
247
- ## ▶ Next Up
248
+
249
+ ╔══════════════════════════════════════════════════════════════╗
250
+ ║ ▶ NEXT UP ║
251
+ ╚══════════════════════════════════════════════════════════════╝
248
252
 
249
253
  **Continue your workflow** — the bug is fixed
250
254
 
@@ -252,13 +256,13 @@ Actions:
252
256
 
253
257
  <sub>`/clear` first → fresh context window</sub>
254
258
 
255
- ───────────────────────────────────────────────────────────────
259
+
256
260
 
257
261
  **Also available:**
258
262
  - `/pbr:continue` — execute next logical step
259
263
  - `/pbr:review {N}` — verify the current phase
260
264
 
261
- ───────────────────────────────────────────────────────────────
265
+
262
266
  ```
263
267
 
264
268
  #### ROOT CAUSE FOUND (no fix)
@@ -278,9 +282,11 @@ Actions:
278
282
  2. Suggest next steps to user:
279
283
 
280
284
  ```
281
- ───────────────────────────────────────────────────────────────
282
285
 
283
- ## ▶ Next Up
286
+
287
+ ╔══════════════════════════════════════════════════════════════╗
288
+ ║ ▶ NEXT UP ║
289
+ ╚══════════════════════════════════════════════════════════════╝
284
290
 
285
291
  **Apply the fix** — root cause identified, fix needed
286
292
 
@@ -288,13 +294,13 @@ Actions:
288
294
 
289
295
  <sub>`/clear` first → fresh context window</sub>
290
296
 
291
- ───────────────────────────────────────────────────────────────
297
+
292
298
 
293
299
  **Also available:**
294
300
  - `/pbr:plan` — for complex fixes that need planning
295
301
  - `/pbr:status` — see project status
296
302
 
297
- ───────────────────────────────────────────────────────────────
303
+
298
304
  ```
299
305
 
300
306
  #### CHECKPOINT
@@ -404,7 +410,7 @@ Use AskUserQuestion:
404
410
  - label: "Escalate" description: "Save context for manual debugging"
405
411
 
406
412
  - If "Extend": double the limit and continue
407
- - If "Wrap up": update debug file status to `stale`, record all findings, suggest next steps
413
+ - If "Wrap up": update debug file `status: resolved` with `resolution: abandoned`, record all findings, suggest next steps
408
414
  - If "Escalate": write a detailed handoff document to the debug file with all hypotheses, evidence, and suggested manual investigation steps
409
415
 
410
416
  ---
@@ -414,15 +420,15 @@ Use AskUserQuestion:
414
420
  ### Lifecycle
415
421
 
416
422
  ```
417
- activeresolved (root cause found and fixed)
418
- activestale (abandoned no updates for 7+ days)
419
- activeactive (resumed after pause)
423
+ gatheringinvestigating fixing verifying → resolved
424
+ (any non-resolved) resolved (with resolution: abandoned, if 7+ days stale)
425
+ (any non-resolved) → (same) (resumed after pause)
420
426
  ```
421
427
 
422
428
  ### Staleness Detection
423
429
 
424
430
  When scanning for active sessions, check the `updated` date. If more than 7 days old:
425
- - Mark as `stale` in status
431
+ - Set `status: resolved` with `resolution: abandoned` in frontmatter
426
432
  - Still offer to resume, but warn: "This session is {N} days old. Context may have changed."
427
433
 
428
434
  ### Cleanup
@@ -12,9 +12,9 @@ argument-hint: "<phase-number>"
12
12
  **Before ANY tool calls**, display this banner:
13
13
 
14
14
  ```
15
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
16
- PLAN-BUILD-RUN ► DISCUSSION
17
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
15
+ ╔══════════════════════════════════════════════════════════════╗
16
+ PLAN-BUILD-RUN ► DISCUSSION
17
+ ╚══════════════════════════════════════════════════════════════╝
18
18
  ```
19
19
 
20
20
  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
153
153
 
154
154
  For each gray area where the user made a decision (not "Let Claude decide"), ask **4 follow-up questions** to fully capture their intent.
155
155
 
156
+ **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.**
157
+
156
158
  **Follow-up question types:**
157
159
 
160
+ **CRITICAL — STOP: Do NOT skip this follow-up area.**
158
161
  1. **Scope boundary**: "Should {feature} also handle {edge case}?"
159
162
  Use the **yes-no** pattern — this is a binary decision.
160
163
 
164
+ **CRITICAL — STOP: Do NOT skip this follow-up area.**
161
165
  2. **Quality level**: "How polished should this be?"
162
166
  Do NOT use AskUserQuestion — this is freeform. Let the user describe their quality expectations in their own words.
163
167
 
168
+ **CRITICAL — STOP: Do NOT skip this follow-up area.**
164
169
  3. **Integration**: "How should this interact with {existing component}?"
165
170
  Do NOT use AskUserQuestion — this is freeform. The answer depends on the specific component and context.
166
171
 
172
+ **CRITICAL — STOP: Do NOT skip this follow-up area.**
167
173
  4. **Future-proofing**: "Should we design this to support {potential future need}, or keep it simple?"
168
174
  Use the **yes-no** pattern:
169
175
  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
177
183
  - If the user gives a short answer, capture it as-is
178
184
  - If the user says "you decide" on a follow-up, move that specific sub-decision to Claude's Discretion
179
185
 
186
+ **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.
187
+
180
188
  ### Step 6: Capture Deferred Ideas
181
189
 
182
190
  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
221
229
  After writing CONTEXT.md, display branded output:
222
230
 
223
231
  ```
224
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
225
- PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓
226
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
232
+ ╔══════════════════════════════════════════════════════════════╗
233
+ PLAN-BUILD-RUN ► DISCUSSION CAPTURED ✓
234
+ ╚══════════════════════════════════════════════════════════════╝
227
235
 
228
236
  **Phase {N}: {name}**
229
237
 
230
238
  Decisions: {count} locked, {count} deferred, {count} discretion
231
239
 
232
- ───────────────────────────────────────────────────────────────
233
240
 
234
- ## ▶ Next Up
241
+
242
+ ╔══════════════════════════════════════════════════════════════╗
243
+ ║ ▶ NEXT UP ║
244
+ ╚══════════════════════════════════════════════════════════════╝
235
245
 
236
246
  **Plan this phase** — your decisions will be honored
237
247
 
@@ -239,13 +249,13 @@ Decisions: {count} locked, {count} deferred, {count} discretion
239
249
 
240
250
  <sub>`/clear` first → fresh context window</sub>
241
251
 
242
- ───────────────────────────────────────────────────────────────
252
+
243
253
 
244
254
  **Also available:**
245
255
  - `/pbr:status` — see project status
246
256
  - `/pbr:explore` — explore ideas further
247
257
 
248
- ───────────────────────────────────────────────────────────────
258
+
249
259
  ```
250
260
 
251
261
  ---
@@ -16,9 +16,9 @@ You are running the **do** skill. Your job is to analyze freeform text from the
16
16
  **Before ANY tool calls**, display this banner:
17
17
 
18
18
  ```
19
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
20
- PLAN-BUILD-RUN ► ROUTING
21
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
19
+ ╔══════════════════════════════════════════════════════════════╗
20
+ PLAN-BUILD-RUN ► ROUTING
21
+ ╚══════════════════════════════════════════════════════════════╝
22
22
  ```
23
23
 
24
24
  Then proceed to Step 1.
@@ -12,9 +12,9 @@ argument-hint: "[topic]"
12
12
  **Before ANY tool calls**, display this banner:
13
13
 
14
14
  ```
15
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
16
- PLAN-BUILD-RUN ► EXPLORING
17
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
15
+ ╔══════════════════════════════════════════════════════════════╗
16
+ PLAN-BUILD-RUN ► EXPLORING
17
+ ╚══════════════════════════════════════════════════════════════╝
18
18
  ```
19
19
 
20
20
  Then proceed to Step 1.
@@ -178,7 +178,7 @@ Suggest specific outputs with reasoning. Present no more than 4 suggestions —
178
178
  | Phase decision | Clarifies an existing phase | Write/append to phase `CONTEXT.md` |
179
179
  | Research question | Needs deeper investigation | `.planning/research/questions.md` |
180
180
  | New phase | Big enough for its own phase | Append to `ROADMAP.md` |
181
- | Note | Not actionable yet, worth remembering | `.planning/notes/{slug}.md` |
181
+ | Note | Not actionable yet, worth remembering | `.planning/notes/{YYYY-MM-DD}-{slug}.md` |
182
182
  | Quick capture | One-liner idea, no context needed | Suggest `/pbr:note <text>` to the user |
183
183
  | Seed | Idea with trigger conditions | `.planning/seeds/SEED-{NNN}-{slug}.md` |
184
184
 
@@ -218,15 +218,17 @@ Create only the approved artifacts. A single explore session can produce multipl
218
218
  After creating artifacts (or if user chose "Skip"), display:
219
219
 
220
220
  ```
221
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
222
- PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓
223
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
221
+ ╔══════════════════════════════════════════════════════════════╗
222
+ PLAN-BUILD-RUN ► EXPLORATION CAPTURED ✓
223
+ ╚══════════════════════════════════════════════════════════════╝
224
224
 
225
225
  {count} artifacts created: {list of artifact types}
226
226
 
227
- ───────────────────────────────────────────────────────────────
228
227
 
229
- ## ▶ Next Up
228
+
229
+ ╔══════════════════════════════════════════════════════════════╗
230
+ ║ ▶ NEXT UP ║
231
+ ╚══════════════════════════════════════════════════════════════╝
230
232
 
231
233
  **{Primary route based on what was created}**
232
234
 
@@ -242,14 +244,14 @@ After creating artifacts (or if user chose "Skip"), display:
242
244
 
243
245
  <sub>`/clear` first → fresh context window</sub>
244
246
 
245
- ───────────────────────────────────────────────────────────────
247
+
246
248
 
247
249
  **Also available:**
248
250
  - `/pbr:status` — see project status
249
251
  - `/pbr:continue` — execute next logical step
250
252
  - `/pbr:milestone new` — start a new milestone with new phases
251
253
 
252
- ───────────────────────────────────────────────────────────────
254
+
253
255
  ```
254
256
 
255
257
  ---
@@ -292,7 +294,7 @@ Append to `.planning/ROADMAP.md` following the existing phase format. Assign the
292
294
 
293
295
  ### Note
294
296
 
295
- 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.
297
+ 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).
296
298
 
297
299
  ```markdown
298
300
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: health
3
3
  description: "Check planning directory integrity. Find and fix corrupted state."
4
- allowed-tools: Read, Bash, Glob, Grep
4
+ allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
5
5
  ---
6
6
 
7
7
  **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
11
11
  **Before ANY tool calls**, display this banner:
12
12
 
13
13
  ```
14
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
15
- PLAN-BUILD-RUN ► HEALTH CHECK
16
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
14
+ ╔══════════════════════════════════════════════════════════════╗
15
+ PLAN-BUILD-RUN ► HEALTH CHECK
16
+ ╚══════════════════════════════════════════════════════════════╝
17
17
  ```
18
18
 
19
19
  Then proceed to Step 1.
@@ -22,7 +22,7 @@ Then proceed to Step 1.
22
22
 
23
23
  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.
24
24
 
25
- This skill runs **inline** and is **read-only** it never modifies any files.
25
+ 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).
26
26
 
27
27
  ---
28
28
 
@@ -152,6 +152,58 @@ Glob for `.planning/phases/**/.PROGRESS-*` and `.planning/phases/**/.checkpoint-
152
152
 
153
153
  ---
154
154
 
155
+ ## Auto-Fix for Common Corruption Patterns
156
+
157
+ After running all 10 checks and collecting results, if any of the following auto-fixable issues were found, offer to fix them.
158
+
159
+ ### Auto-Fixable Patterns
160
+
161
+ | Pattern | Detection | Fix Action |
162
+ |---------|-----------|------------|
163
+ | Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, total_phases, status) |
164
+ | 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/` |
165
+ | Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `/pbr:setup` defaults) |
166
+ | Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |
167
+ | Empty phases directory | Check 3 finds `.planning/phases/` missing | Create the directory: `mkdir -p .planning/phases` |
168
+ | STATE.md over 150 lines | Check 5 finds STATE.md exceeds 150 lines | Compact the `## Accumulated Context` section, keeping only the last 3 entries |
169
+
170
+ ### Auto-Fix Flow
171
+
172
+ After displaying health check results, if any auto-fixable issues were detected:
173
+
174
+ 1. Count the auto-fixable issues and present:
175
+
176
+ Use AskUserQuestion:
177
+ question: "Found {N} auto-fixable issues. How should we handle them?"
178
+ header: "Fix?"
179
+ options:
180
+ - label: "Fix all" description: "Apply all {N} fixes automatically"
181
+ - label: "Review each" description: "Show each fix and confirm individually"
182
+ - label: "Skip" description: "Do nothing — just report"
183
+
184
+ 2. If "Fix all": Apply all fixes in order, then display a summary:
185
+ ```
186
+ Auto-fix results:
187
+ - Fixed: {description of fix 1}
188
+ - Fixed: {description of fix 2}
189
+ ...
190
+ ```
191
+
192
+ 3. If "Review each": For each fixable issue, display:
193
+ ```
194
+ Issue: {description}
195
+ Fix: {what will be done}
196
+ ```
197
+ Then ask via AskUserQuestion (yes/no): "Apply this fix?"
198
+ - If yes: apply and display `- Fixed: {description}`
199
+ - If no: skip and display `- Skipped: {description}`
200
+
201
+ 4. If "Skip": Do nothing, continue to the rest of the output.
202
+
203
+ **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.
204
+
205
+ ---
206
+
155
207
  ## Bonus: Recent Decisions
156
208
 
157
209
  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:
164
216
 
165
217
  **If all checks passed (0 failures):**
166
218
  ```
167
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
168
- PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓
169
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
219
+ ╔══════════════════════════════════════════════════════════════╗
220
+ PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓
221
+ ╚══════════════════════════════════════════════════════════════╝
170
222
 
171
223
  {N} checks passed, {M} warnings
172
224
 
173
- ───────────────────────────────────────────────────────────────
174
225
 
175
- ## ▶ Next Up
226
+
227
+ ╔══════════════════════════════════════════════════════════════╗
228
+ ║ ▶ NEXT UP ║
229
+ ╚══════════════════════════════════════════════════════════════╝
176
230
 
177
231
  **Continue your workflow** — planning directory is healthy
178
232
 
@@ -180,40 +234,42 @@ After all checks complete, display the branded result:
180
234
 
181
235
  <sub>`/clear` first → fresh context window</sub>
182
236
 
183
- ───────────────────────────────────────────────────────────────
237
+
184
238
 
185
239
  **Also available:**
186
240
  - `/pbr:continue` — execute next logical step
187
241
  - `/pbr:config` — adjust settings
188
242
 
189
- ───────────────────────────────────────────────────────────────
243
+
190
244
  ```
191
245
 
192
246
  **If failures found:**
193
247
  ```
194
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
195
- PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠
196
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
248
+ ╔══════════════════════════════════════════════════════════════╗
249
+ PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠
250
+ ╚══════════════════════════════════════════════════════════════╝
197
251
 
198
252
  {N} checks passed, {F} failures, {M} warnings
199
253
 
200
- ───────────────────────────────────────────────────────────────
201
254
 
202
- ## ▶ Next Up
255
+
256
+ ╔══════════════════════════════════════════════════════════════╗
257
+ ║ ▶ NEXT UP ║
258
+ ╚══════════════════════════════════════════════════════════════╝
203
259
 
204
260
  **Fix the failures** listed above, then re-run
205
261
 
206
262
  `/pbr:health`
207
263
 
208
- ───────────────────────────────────────────────────────────────
264
+
209
265
  ```
210
266
 
211
267
  ---
212
268
 
213
269
  ## Anti-Patterns
214
270
 
215
- 1. **DO NOT** modify any files — this is strictly read-only
216
- 2. **DO NOT** auto-repair anything — present fixes and let the user decide
271
+ 1. **DO NOT** modify files without user consent auto-fix requires explicit user approval via AskUserQuestion
272
+ 2. **DO NOT** auto-repair anything silently always present fixes and let the user decide
217
273
  3. **DO NOT** skip checks that depend on missing files — report the dependency failure and continue
218
274
  4. **DO NOT** treat warnings as failures in the summary count — only count FAIL items
219
275
  5. **DO NOT** read full plan/summary contents — frontmatter and existence checks are sufficient
@@ -11,9 +11,9 @@ allowed-tools: Read
11
11
  **Before ANY tool calls**, display this banner:
12
12
 
13
13
  ```
14
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
15
- PLAN-BUILD-RUN ► COMMAND REFERENCE
16
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
14
+ ╔══════════════════════════════════════════════════════════════╗
15
+ PLAN-BUILD-RUN ► COMMAND REFERENCE
16
+ ╚══════════════════════════════════════════════════════════════╝
17
17
  ```
18
18
 
19
19
  Then proceed to Step 1.
@@ -137,16 +137,18 @@ Skills automatically activate the appropriate context: `/pbr:build` uses dev con
137
137
  ## Getting Started
138
138
 
139
139
  ```
140
- ───────────────────────────────────────────────────────────────
141
140
 
142
- ## ▶ Next Up
141
+
142
+ ╔══════════════════════════════════════════════════════════════╗
143
+ ║ ▶ NEXT UP ║
144
+ ╚══════════════════════════════════════════════════════════════╝
143
145
 
144
146
  → `/pbr:begin` — start a new project
145
147
  → `/pbr:status` — check current project status
146
148
  → `/pbr:config` — configure workflow settings
147
149
  → `/pbr:help <command>` — detailed help for a specific command
148
150
 
149
- ───────────────────────────────────────────────────────────────
151
+
150
152
  ```
151
153
 
152
154
  ## Getting Help