@sienklogic/plan-build-run 2.9.1 → 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 (128) hide show
  1. package/CHANGELOG.md +44 -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/pbr-rules.md +1 -0
  14. package/plugins/copilot-pbr/references/pbr-tools-cli.md +285 -0
  15. package/plugins/copilot-pbr/references/ui-formatting.md +38 -56
  16. package/plugins/copilot-pbr/skills/begin/SKILL.md +30 -7
  17. package/plugins/copilot-pbr/skills/build/SKILL.md +28 -31
  18. package/plugins/copilot-pbr/skills/config/SKILL.md +9 -12
  19. package/plugins/copilot-pbr/skills/continue/SKILL.md +6 -6
  20. package/plugins/copilot-pbr/skills/dashboard/SKILL.md +12 -0
  21. package/plugins/copilot-pbr/skills/debug/SKILL.md +23 -26
  22. package/plugins/copilot-pbr/skills/discuss/SKILL.md +20 -10
  23. package/plugins/copilot-pbr/skills/do/SKILL.md +3 -3
  24. package/plugins/copilot-pbr/skills/explore/SKILL.md +11 -14
  25. package/plugins/copilot-pbr/skills/health/SKILL.md +75 -19
  26. package/plugins/copilot-pbr/skills/help/SKILL.md +6 -6
  27. package/plugins/copilot-pbr/skills/import/SKILL.md +22 -18
  28. package/plugins/copilot-pbr/skills/milestone/SKILL.md +90 -48
  29. package/plugins/copilot-pbr/skills/note/SKILL.md +3 -3
  30. package/plugins/copilot-pbr/skills/pause/SKILL.md +11 -10
  31. package/plugins/copilot-pbr/skills/plan/SKILL.md +22 -9
  32. package/plugins/copilot-pbr/skills/plan/templates/planner-prompt.md.tmpl +1 -1
  33. package/plugins/copilot-pbr/skills/quick/SKILL.md +9 -12
  34. package/plugins/copilot-pbr/skills/resume/SKILL.md +9 -9
  35. package/plugins/copilot-pbr/skills/review/SKILL.md +17 -12
  36. package/plugins/copilot-pbr/skills/scan/SKILL.md +9 -11
  37. package/plugins/copilot-pbr/skills/setup/SKILL.md +54 -8
  38. package/plugins/copilot-pbr/skills/shared/error-reporting.md +2 -1
  39. package/plugins/copilot-pbr/skills/shared/progress-display.md +0 -1
  40. package/plugins/copilot-pbr/skills/shared/universal-anti-patterns.md +10 -6
  41. package/plugins/copilot-pbr/skills/status/SKILL.md +3 -3
  42. package/plugins/copilot-pbr/skills/statusline/SKILL.md +12 -8
  43. package/plugins/copilot-pbr/skills/todo/SKILL.md +51 -28
  44. package/plugins/cursor-pbr/.cursor-plugin/plugin.json +1 -1
  45. package/plugins/cursor-pbr/agents/codebase-mapper.md +42 -0
  46. package/plugins/cursor-pbr/agents/debugger.md +4 -1
  47. package/plugins/cursor-pbr/agents/executor.md +31 -1
  48. package/plugins/cursor-pbr/agents/integration-checker.md +33 -2
  49. package/plugins/cursor-pbr/agents/planner.md +58 -1
  50. package/plugins/cursor-pbr/agents/researcher.md +23 -0
  51. package/plugins/cursor-pbr/agents/synthesizer.md +24 -0
  52. package/plugins/cursor-pbr/agents/verifier.md +35 -1
  53. package/plugins/cursor-pbr/references/agent-contracts.md +297 -0
  54. package/plugins/cursor-pbr/references/pbr-rules.md +1 -0
  55. package/plugins/cursor-pbr/references/pbr-tools-cli.md +285 -0
  56. package/plugins/cursor-pbr/references/ui-formatting.md +38 -56
  57. package/plugins/cursor-pbr/skills/begin/SKILL.md +30 -7
  58. package/plugins/cursor-pbr/skills/build/SKILL.md +28 -31
  59. package/plugins/cursor-pbr/skills/config/SKILL.md +9 -10
  60. package/plugins/cursor-pbr/skills/continue/SKILL.md +6 -6
  61. package/plugins/cursor-pbr/skills/dashboard/SKILL.md +12 -0
  62. package/plugins/cursor-pbr/skills/debug/SKILL.md +23 -23
  63. package/plugins/cursor-pbr/skills/discuss/SKILL.md +20 -10
  64. package/plugins/cursor-pbr/skills/do/SKILL.md +3 -3
  65. package/plugins/cursor-pbr/skills/explore/SKILL.md +11 -12
  66. package/plugins/cursor-pbr/skills/health/SKILL.md +75 -19
  67. package/plugins/cursor-pbr/skills/help/SKILL.md +6 -6
  68. package/plugins/cursor-pbr/skills/import/SKILL.md +22 -16
  69. package/plugins/cursor-pbr/skills/milestone/SKILL.md +90 -48
  70. package/plugins/cursor-pbr/skills/note/SKILL.md +3 -3
  71. package/plugins/cursor-pbr/skills/pause/SKILL.md +11 -9
  72. package/plugins/cursor-pbr/skills/plan/SKILL.md +22 -9
  73. package/plugins/cursor-pbr/skills/plan/templates/planner-prompt.md.tmpl +1 -1
  74. package/plugins/cursor-pbr/skills/quick/SKILL.md +9 -12
  75. package/plugins/cursor-pbr/skills/resume/SKILL.md +9 -9
  76. package/plugins/cursor-pbr/skills/review/SKILL.md +17 -12
  77. package/plugins/cursor-pbr/skills/scan/SKILL.md +9 -10
  78. package/plugins/cursor-pbr/skills/setup/SKILL.md +54 -8
  79. package/plugins/cursor-pbr/skills/shared/error-reporting.md +2 -1
  80. package/plugins/cursor-pbr/skills/shared/progress-display.md +0 -1
  81. package/plugins/cursor-pbr/skills/shared/universal-anti-patterns.md +10 -6
  82. package/plugins/cursor-pbr/skills/status/SKILL.md +3 -3
  83. package/plugins/cursor-pbr/skills/statusline/SKILL.md +12 -8
  84. package/plugins/cursor-pbr/skills/todo/SKILL.md +51 -28
  85. package/plugins/pbr/.claude-plugin/plugin.json +1 -1
  86. package/plugins/pbr/agents/codebase-mapper.md +42 -0
  87. package/plugins/pbr/agents/debugger.md +4 -1
  88. package/plugins/pbr/agents/executor.md +31 -1
  89. package/plugins/pbr/agents/integration-checker.md +34 -2
  90. package/plugins/pbr/agents/planner.md +58 -1
  91. package/plugins/pbr/agents/researcher.md +23 -0
  92. package/plugins/pbr/agents/synthesizer.md +24 -0
  93. package/plugins/pbr/agents/verifier.md +36 -1
  94. package/plugins/pbr/references/agent-contracts.md +297 -0
  95. package/plugins/pbr/references/pbr-rules.md +1 -0
  96. package/plugins/pbr/references/pbr-tools-cli.md +285 -0
  97. package/plugins/pbr/references/ui-formatting.md +37 -54
  98. package/plugins/pbr/scripts/check-skill-workflow.js +11 -0
  99. package/plugins/pbr/scripts/check-state-sync.js +58 -0
  100. package/plugins/pbr/scripts/check-subagent-output.js +43 -4
  101. package/plugins/pbr/scripts/validate-task.js +69 -17
  102. package/plugins/pbr/skills/begin/SKILL.md +36 -11
  103. package/plugins/pbr/skills/build/SKILL.md +37 -25
  104. package/plugins/pbr/skills/config/SKILL.md +12 -10
  105. package/plugins/pbr/skills/continue/SKILL.md +11 -9
  106. package/plugins/pbr/skills/dashboard/SKILL.md +12 -0
  107. package/plugins/pbr/skills/debug/SKILL.md +29 -23
  108. package/plugins/pbr/skills/discuss/SKILL.md +20 -10
  109. package/plugins/pbr/skills/do/SKILL.md +3 -3
  110. package/plugins/pbr/skills/explore/SKILL.md +14 -12
  111. package/plugins/pbr/skills/health/SKILL.md +76 -20
  112. package/plugins/pbr/skills/help/SKILL.md +8 -6
  113. package/plugins/pbr/skills/import/SKILL.md +25 -16
  114. package/plugins/pbr/skills/milestone/SKILL.md +88 -45
  115. package/plugins/pbr/skills/note/SKILL.md +3 -3
  116. package/plugins/pbr/skills/pause/SKILL.md +13 -9
  117. package/plugins/pbr/skills/plan/SKILL.md +28 -13
  118. package/plugins/pbr/skills/plan/templates/planner-prompt.md.tmpl +1 -1
  119. package/plugins/pbr/skills/quick/SKILL.md +12 -10
  120. package/plugins/pbr/skills/resume/SKILL.md +11 -9
  121. package/plugins/pbr/skills/review/SKILL.md +35 -24
  122. package/plugins/pbr/skills/scan/SKILL.md +12 -10
  123. package/plugins/pbr/skills/setup/SKILL.md +53 -7
  124. package/plugins/pbr/skills/shared/error-reporting.md +2 -0
  125. package/plugins/pbr/skills/shared/universal-anti-patterns.md +10 -6
  126. package/plugins/pbr/skills/status/SKILL.md +8 -6
  127. package/plugins/pbr/skills/statusline/SKILL.md +12 -8
  128. package/plugins/pbr/skills/todo/SKILL.md +51 -28
@@ -1,4 +1,3 @@
1
- <!-- canonical: ../../pbr/references/ui-formatting.md -->
2
1
  # Plan-Build-Run UI Brand & Formatting Reference
3
2
 
4
3
  Consistent output formatting for all Plan-Build-Run skills. Every skill that produces user-facing output should follow these patterns.
@@ -8,9 +7,9 @@ Consistent output formatting for all Plan-Build-Run skills. Every skill that pro
8
7
  Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
9
8
 
10
9
  ```
11
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
12
- PLAN-BUILD-RUN ► {STAGE NAME}
13
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
10
+ ╔══════════════════════════════════════════════════════════════╗
11
+ PLAN-BUILD-RUN ► {STAGE NAME}
12
+ ╚══════════════════════════════════════════════════════════════╝
14
13
  ```
15
14
 
16
15
  **Stage names (uppercase):**
@@ -22,7 +21,7 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
22
21
  - `EXECUTING WAVE {N}`
23
22
  - `VERIFYING`
24
23
  - `PHASE {N} COMPLETE ✓`
25
- - `MILESTONE COMPLETE 🎉`
24
+ - `MILESTONE COMPLETE`
26
25
  - `SCANNING CODEBASE`
27
26
  - `DEBUGGING`
28
27
 
@@ -34,9 +33,9 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
34
33
 
35
34
  Format:
36
35
  ```
37
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
38
- PLAN-BUILD-RUN ► {SKILL NAME}
39
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
36
+ ╔══════════════════════════════════════════════════════════════╗
37
+ PLAN-BUILD-RUN ► {SKILL NAME}
38
+ ╚══════════════════════════════════════════════════════════════╝
40
39
  ```
41
40
 
42
41
  **Skill names (uppercase):**
@@ -156,7 +155,7 @@ For research agents:
156
155
 
157
156
  ## Checkpoint Boxes
158
157
 
159
- User action required. Use double-line box drawing, 62-character width.
158
+ User action required. Use double-line box drawing, 62-character inner width.
160
159
 
161
160
  ```
162
161
  ╔══════════════════════════════════════════════════════════════╗
@@ -165,9 +164,7 @@ User action required. Use double-line box drawing, 62-character width.
165
164
 
166
165
  {Content}
167
166
 
168
- ──────────────────────────────────────────────────────────────
169
167
  → {ACTION PROMPT}
170
- ──────────────────────────────────────────────────────────────
171
168
  ```
172
169
 
173
170
  **Types:**
@@ -261,25 +258,21 @@ Use plain conversational prompts for these cases instead.
261
258
  Always present at end of major completions (phase complete, milestone complete, project init).
262
259
 
263
260
  ```
264
- ───────────────────────────────────────────────────────────────
265
-
266
- ## ▶ Next Up
261
+ ╔══════════════════════════════════════════════════════════════╗
262
+ ║ ▶ NEXT UP ║
263
+ ╚══════════════════════════════════════════════════════════════╝
267
264
 
268
265
  **{Identifier}: {Name}** — {one-line description}
269
266
 
270
267
  `{copy-paste command}`
271
268
 
272
269
  <sub>`/clear` first → fresh context window</sub>
273
-
274
- ───────────────────────────────────────────────────────────────
270
+ ```
275
271
 
276
272
  **Also available:**
277
273
  - `/pbr:alternative-1` — description
278
274
  - `/pbr:alternative-2` — description
279
275
 
280
- ───────────────────────────────────────────────────────────────
281
- ```
282
-
283
276
  **Shorter routing (for minor completions):**
284
277
  ```
285
278
  What's next?
@@ -334,18 +327,18 @@ Use tables for structured data:
334
327
  ### Phase Complete
335
328
 
336
329
  ```
337
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
338
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
339
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
330
+ ╔══════════════════════════════════════════════════════════════╗
331
+ PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
332
+ ╚══════════════════════════════════════════════════════════════╝
340
333
 
341
334
  **Phase {N}: {Name}**
342
335
 
343
336
  {X} plans executed
344
337
  Goal verified ✓
345
338
 
346
- ───────────────────────────────────────────────────────────────
347
-
348
- ## ▶ Next Up
339
+ ╔══════════════════════════════════════════════════════════════╗
340
+ ║ ▶ NEXT UP ║
341
+ ╚══════════════════════════════════════════════════════════════╝
349
342
 
350
343
  **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
351
344
 
@@ -353,30 +346,26 @@ Goal verified ✓
353
346
 
354
347
  <sub>/clear first → fresh context window</sub>
355
348
 
356
- ───────────────────────────────────────────────────────────────
357
-
358
349
  **Also available:**
359
350
  - /pbr:plan {N+1} — skip discussion, plan directly
360
351
  - /pbr:review {N} — manual acceptance testing before continuing
361
-
362
- ───────────────────────────────────────────────────────────────
363
352
  ```
364
353
 
365
354
  ### Milestone Complete
366
355
 
367
356
  ```
368
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
369
- PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
370
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
357
+ ╔══════════════════════════════════════════════════════════════╗
358
+ PLAN-BUILD-RUN ► MILESTONE COMPLETE
359
+ ╚══════════════════════════════════════════════════════════════╝
371
360
 
372
361
  **{version}**
373
362
 
374
363
  {N} phases completed
375
364
  All phase goals verified ✓
376
365
 
377
- ───────────────────────────────────────────────────────────────
378
-
379
- ## ▶ Next Up
366
+ ╔══════════════════════════════════════════════════════════════╗
367
+ ║ ▶ NEXT UP ║
368
+ ╚══════════════════════════════════════════════════════════════╝
380
369
 
381
370
  **Audit milestone** — verify requirements, cross-phase integration, E2E flows
382
371
 
@@ -384,21 +373,17 @@ All phase goals verified ✓
384
373
 
385
374
  <sub>/clear first → fresh context window</sub>
386
375
 
387
- ───────────────────────────────────────────────────────────────
388
-
389
376
  **Also available:**
390
377
  - /pbr:review — manual acceptance testing
391
- - /pbr:milestone complete — skip audit, archive directly
392
-
393
- ───────────────────────────────────────────────────────────────
378
+ - /pbr:milestone complete — archive milestone after audit passes
394
379
  ```
395
380
 
396
381
  ### Gaps Found
397
382
 
398
383
  ```
399
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
400
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
401
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
384
+ ╔══════════════════════════════════════════════════════════════╗
385
+ PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
386
+ ╚══════════════════════════════════════════════════════════════╝
402
387
 
403
388
  **Phase {N}: {Name}**
404
389
 
@@ -409,9 +394,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
409
394
 
410
395
  {Extract gap summaries from VERIFICATION.md}
411
396
 
412
- ───────────────────────────────────────────────────────────────
413
-
414
- ## ▶ Next Up
397
+ ╔══════════════════════════════════════════════════════════════╗
398
+ ║ ▶ NEXT UP ║
399
+ ╚══════════════════════════════════════════════════════════════╝
415
400
 
416
401
  **Plan gap closure** — create additional plans to complete the phase
417
402
 
@@ -419,13 +404,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
419
404
 
420
405
  <sub>/clear first → fresh context window</sub>
421
406
 
422
- ───────────────────────────────────────────────────────────────
423
-
424
407
  **Also available:**
425
408
  - cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
426
409
  - /pbr:review {N} — manual testing before planning
427
-
428
- ───────────────────────────────────────────────────────────────
429
410
  ```
430
411
 
431
412
  ---
@@ -435,9 +416,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
435
416
  Use for session lifecycle transitions (pause/resume):
436
417
 
437
418
  ```
438
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
439
- PLAN-BUILD-RUN ► SESSION RESTORED ✓
440
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
419
+ ╔══════════════════════════════════════════════════════════════╗
420
+ PLAN-BUILD-RUN ► SESSION RESTORED ✓
421
+ ╚══════════════════════════════════════════════════════════════╝
441
422
 
442
423
  Position: Phase {N} — {phase name}, Plan {M}
443
424
  Paused: {ISO datetime}
@@ -453,10 +434,11 @@ Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume s
453
434
  ## Anti-Patterns
454
435
 
455
436
  Do NOT:
456
- - Use varying box/banner widths
457
- - Mix banner styles (`===`, `---`, `***`) with `━━━` banners
437
+ - Use varying box/banner widths — always 62-character inner width
438
+ - Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
439
+ - Mix banner styles (`===`, `---`, `***`) with double-line boxes
458
440
  - Skip `PLAN-BUILD-RUN ►` prefix in stage banners
459
- - Use random emoji (only `🎉` for milestone complete, `✓` for phase complete)
441
+ - Use random emoji (only for milestone complete, `✓` for phase complete)
460
442
  - Skip the "Next Up" block after major completions
461
443
  - Reference non-Plan-Build-Run commands (always use `/pbr:*` commands)
462
444
  - Use non-Plan-Build-Run branding in banners
@@ -20,9 +20,9 @@ Additionally for this skill:
20
20
  **Before ANY tool calls**, display this banner:
21
21
 
22
22
  ```
23
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
24
- PLAN-BUILD-RUN ► STARTING PROJECT
25
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
23
+ ╔══════════════════════════════════════════════════════════════╗
24
+ PLAN-BUILD-RUN ► STARTING PROJECT
25
+ ╚══════════════════════════════════════════════════════════════╝
26
26
  ```
27
27
 
28
28
  Then proceed to Step 1.
@@ -165,6 +165,8 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
165
165
 
166
166
  **After gathering preferences:**
167
167
 
168
+ **CRITICAL: You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
169
+
168
170
  1. Read the config template from `skills/begin/templates/config.json.tmpl`
169
171
  2. Apply the user's choices to the template
170
172
  3. Create `.planning/` directory
@@ -172,6 +174,8 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
172
174
 
173
175
  **IMPORTANT**: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
174
176
 
177
+ **CRITICAL: Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
178
+
175
179
  ---
176
180
 
177
181
  ### Step 4: Research Decision (inline)
@@ -206,7 +210,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
206
210
 
207
211
  Spawn parallel agents for research. Each researcher writes to `.planning/research/`.
208
212
 
209
- **Create `.planning/research/` directory first.**
213
+ **CRITICAL: Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
210
214
 
211
215
  **For each research topic, invoke the @researcher agent:**
212
216
 
@@ -324,6 +328,9 @@ Each requirement must be:
324
328
  - **Specific** — not vague ("fast" is bad, "page loads in <2s" is good)
325
329
 
326
330
  **7e. Write REQUIREMENTS.md:**
331
+
332
+ **CRITICAL: Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
333
+
327
334
  Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
328
335
  - All v1 requirements grouped by category
329
336
  - All v2 requirements with deferral reasons
@@ -374,6 +381,10 @@ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
374
381
 
375
382
  Write the project state files from templates:
376
383
 
384
+ **CRITICAL: You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
385
+
386
+ **CRITICAL: Write PROJECT.md NOW. Do NOT skip this step.**
387
+
377
388
  **9a. Write PROJECT.md:**
378
389
  1. Read `skills/begin/templates/PROJECT.md.tmpl`
379
390
  2. Fill in:
@@ -386,6 +397,8 @@ Write the project state files from templates:
386
397
  3. Write to `.planning/PROJECT.md`
387
398
  4. Ensure the `## Milestones` section is filled in with the project name and phase count from the roadmap
388
399
 
400
+ **CRITICAL: Write STATE.md NOW. Do NOT skip this step.**
401
+
389
402
  **9b. Write STATE.md:**
390
403
  1. Read `skills/begin/templates/STATE.md.tmpl`
391
404
  2. Fill in:
@@ -398,6 +411,8 @@ Write the project state files from templates:
398
411
  4. Fill in the `## Milestone` section with the project name and total phase count
399
412
  5. **STATE.md size limit**: Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
400
413
 
414
+ **CRITICAL: Write CONTEXT.md NOW. Do NOT skip this step.**
415
+
401
416
  **9c. Write CONTEXT.md:**
402
417
  Create `.planning/CONTEXT.md` from information gathered during questioning:
403
418
 
@@ -422,6 +437,8 @@ Create `.planning/CONTEXT.md` from information gathered during questioning:
422
437
  | {feature} | {reason} |
423
438
  ```
424
439
 
440
+ **CRITICAL: Write HISTORY.md NOW. Do NOT skip this step.**
441
+
425
442
  **9d. Write HISTORY.md:**
426
443
  Create `.planning/HISTORY.md` with an initial entry:
427
444
 
@@ -435,6 +452,8 @@ Create `.planning/HISTORY.md` with an initial entry:
435
452
  - Roadmap: {N} phases planned
436
453
  ```
437
454
 
455
+ **CRITICAL: Create phase directories NOW. Do NOT skip this step.**
456
+
438
457
  **9e. Create phase directories:**
439
458
  For each phase in the roadmap, create the directory structure:
440
459
  ```
@@ -478,6 +497,10 @@ If `gates.confirm_project` is true in config:
478
497
 
479
498
  ---
480
499
 
500
+ ## Cleanup
501
+
502
+ Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
503
+
481
504
  ## Completion
482
505
 
483
506
  After all steps complete, present the final summary:
@@ -485,9 +508,9 @@ After all steps complete, present the final summary:
485
508
  Use the branded stage banner from `references/ui-formatting.md`:
486
509
 
487
510
  ```
488
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
489
- PLAN-BUILD-RUN ► PROJECT INITIALIZED
490
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
511
+ ╔══════════════════════════════════════════════════════════════╗
512
+ PLAN-BUILD-RUN ► PROJECT INITIALIZED
513
+ ╚══════════════════════════════════════════════════════════════╝
491
514
 
492
515
  **{name}**
493
516
 
@@ -22,9 +22,9 @@ Additionally for this skill:
22
22
  **Before ANY tool calls**, display this banner:
23
23
 
24
24
  ```
25
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
26
- PLAN-BUILD-RUN ► BUILDING PHASE {N}
27
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
25
+ ╔══════════════════════════════════════════════════════════════╗
26
+ PLAN-BUILD-RUN ► BUILDING PHASE {N}
27
+ ╚══════════════════════════════════════════════════════════════╝
28
28
  ```
29
29
 
30
30
  Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
@@ -63,7 +63,7 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
63
63
  1. Parse `$ARGUMENTS` for phase number and flags
64
64
  2. Read `.planning/config.json` for parallelization, model, and gate settings (see config-loading.md for field reference)
65
65
  3. Resolve depth profile: run `node ${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.
66
- 4. Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
66
+ 4. **CRITICAL: Write .active-skill NOW.** Write `.planning/.active-skill` with the content `build` (registers with workflow enforcement hook)
67
67
  5. Validate:
68
68
  - Phase directory exists at `.planning/phases/{NN}-{slug}/`
69
69
  - PLAN.md files exist in the directory
@@ -196,6 +196,8 @@ Validate wave consistency:
196
196
 
197
197
  ### Step 5b: Write Checkpoint Manifest (inline)
198
198
 
199
+ **CRITICAL: Write .checkpoint-manifest.json NOW before entering the wave loop.**
200
+
199
201
  Before entering the wave loop, write `.planning/phases/{NN}-{slug}/.checkpoint-manifest.json`:
200
202
 
201
203
  ```json
@@ -691,6 +693,8 @@ If triggered:
691
693
  ```
692
694
  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.
693
695
 
696
+ **CRITICAL: Update ROADMAP.md progress table NOW. Do NOT skip this step.**
697
+
694
698
  **8a. Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
695
699
 
696
700
  **Tooling shortcut**: Use the CLI for atomic ROADMAP.md table updates instead of manual editing:
@@ -707,6 +711,8 @@ These return `{ success, old_status, new_status }` or `{ success, old_plans, new
707
711
  5. Update the `Status` column to the final_status determined in Step 8-pre
708
712
  6. Save the file — do NOT skip this step
709
713
 
714
+ **CRITICAL: Update STATE.md NOW with phase completion status. Do NOT skip this step.**
715
+
710
716
  **8b. Update STATE.md:**
711
717
  - Phase status: {final_status from Step 8-pre}
712
718
  - Plan completion count
@@ -801,18 +807,18 @@ Then present the appropriate branded banner:
801
807
 
802
808
  **If `passed` + more phases:**
803
809
  ```
804
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
805
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
806
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
810
+ ╔══════════════════════════════════════════════════════════════╗
811
+ PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
812
+ ╚══════════════════════════════════════════════════════════════╝
807
813
 
808
814
  **Phase {N}: {Name}**
809
815
 
810
816
  {X} plans executed
811
817
  Goal verified ✓
812
818
 
813
- ───────────────────────────────────────────────────────────────
814
-
815
- ## ▶ Next Up
819
+ ╔══════════════════════════════════════════════════════════════╗
820
+ ║ ▶ NEXT UP ║
821
+ ╚══════════════════════════════════════════════════════════════╝
816
822
 
817
823
  **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
818
824
 
@@ -820,28 +826,25 @@ Goal verified ✓
820
826
 
821
827
  <sub>`/clear` first → fresh context window</sub>
822
828
 
823
- ───────────────────────────────────────────────────────────────
824
-
825
829
  **Also available:**
826
830
  - `/pbr:review {N}` — manual acceptance testing before continuing
827
831
  - `/pbr:discuss {N+1}` — talk through the next phase before planning
828
832
  - `/pbr:status` — see full project status
829
833
 
830
- ───────────────────────────────────────────────────────────────
831
834
  ```
832
835
 
833
836
  **If `passed` + last phase:**
834
837
  ```
835
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
836
- PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
837
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
838
+ ╔══════════════════════════════════════════════════════════════╗
839
+ PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
840
+ ╚══════════════════════════════════════════════════════════════╝
838
841
 
839
842
  {N} phases completed
840
843
  All phase goals verified ✓
841
844
 
842
- ───────────────────────────────────────────────────────────────
843
-
844
- ## ▶ Next Up
845
+ ╔══════════════════════════════════════════════════════════════╗
846
+ ║ ▶ NEXT UP ║
847
+ ╚══════════════════════════════════════════════════════════════╝
845
848
 
846
849
  **Audit milestone** — verify requirements, cross-phase integration, E2E flows
847
850
 
@@ -849,20 +852,17 @@ All phase goals verified ✓
849
852
 
850
853
  <sub>`/clear` first → fresh context window</sub>
851
854
 
852
- ───────────────────────────────────────────────────────────────
853
-
854
855
  **Also available:**
855
856
  - `/pbr:review` — manual acceptance testing
856
857
  - `/pbr:milestone complete` — archive milestone after audit passes
857
858
 
858
- ───────────────────────────────────────────────────────────────
859
859
  ```
860
860
 
861
861
  **If `gaps_found`:**
862
862
  ```
863
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
864
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
865
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
863
+ ╔══════════════════════════════════════════════════════════════╗
864
+ PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
865
+ ╚══════════════════════════════════════════════════════════════╝
866
866
 
867
867
  **Phase {N}: {Name}**
868
868
 
@@ -873,9 +873,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
873
873
 
874
874
  {Extract gap summaries from VERIFICATION.md}
875
875
 
876
- ───────────────────────────────────────────────────────────────
877
-
878
- ## ▶ Next Up
876
+ ╔══════════════════════════════════════════════════════════════╗
877
+ ║ ▶ NEXT UP ║
878
+ ╚══════════════════════════════════════════════════════════════╝
879
879
 
880
880
  **Plan gap closure** — create additional plans to complete the phase
881
881
 
@@ -883,13 +883,10 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
883
883
 
884
884
  <sub>`/clear` first → fresh context window</sub>
885
885
 
886
- ───────────────────────────────────────────────────────────────
887
-
888
886
  **Also available:**
889
887
  - `cat .planning/phases/{phase_dir}/VERIFICATION.md` — see full report
890
888
  - `/pbr:review {N}` — manual testing before planning
891
889
 
892
- ───────────────────────────────────────────────────────────────
893
890
  ```
894
891
 
895
892
  **8g. Display USER-SETUP.md (conditional):**
@@ -8,9 +8,9 @@ description: "Configure settings: depth, model profiles, features, git, and gate
8
8
  **Before ANY tool calls**, display this banner:
9
9
 
10
10
  ```
11
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
12
- PLAN-BUILD-RUN ► CONFIGURATION
13
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
11
+ ╔══════════════════════════════════════════════════════════════╗
12
+ PLAN-BUILD-RUN ► CONFIGURATION
13
+ ╚══════════════════════════════════════════════════════════════╝
14
14
  ```
15
15
 
16
16
  Then proceed to Step 1.
@@ -184,17 +184,17 @@ If user types something else (freeform): interpret as a direct setting command a
184
184
 
185
185
  Update config.json with new values. Show what changed with a branded completion:
186
186
  ```
187
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
188
- PLAN-BUILD-RUN ► CONFIG UPDATED ✓
189
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
187
+ ╔══════════════════════════════════════════════════════════════╗
188
+ PLAN-BUILD-RUN ► CONFIG UPDATED ✓
189
+ ╚══════════════════════════════════════════════════════════════╝
190
190
 
191
191
  Updated:
192
192
  depth: standard → quick
193
193
  models.executor: inherit → sonnet
194
194
 
195
- ───────────────────────────────────────────────────────────────
196
-
197
- ## ▶ Next Up
195
+ ╔══════════════════════════════════════════════════════════════╗
196
+ ║ ▶ NEXT UP ║
197
+ ╚══════════════════════════════════════════════════════════════╝
198
198
 
199
199
  **Continue your workflow** — settings saved
200
200
 
@@ -202,13 +202,10 @@ Updated:
202
202
 
203
203
  <sub>`/clear` first → fresh context window</sub>
204
204
 
205
- ───────────────────────────────────────────────────────────────
206
-
207
205
  **Also available:**
208
206
  - `/pbr:continue` — execute next logical step
209
207
  - `/pbr:config` — change more settings
210
208
 
211
- ───────────────────────────────────────────────────────────────
212
209
  ```
213
210
 
214
211
  ## Config Schema
@@ -16,9 +16,9 @@ This skill runs **inline** and may delegate to other skills via agent invocation
16
16
  **Before ANY tool calls**, display this banner:
17
17
 
18
18
  ```
19
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
20
- PLAN-BUILD-RUN ► NEXT STEP
21
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
19
+ ╔══════════════════════════════════════════════════════════════╗
20
+ PLAN-BUILD-RUN ► NEXT STEP
21
+ ╚══════════════════════════════════════════════════════════════╝
22
22
  ```
23
23
 
24
24
  Then proceed to Step 1.
@@ -115,9 +115,9 @@ Where `{N}` is the current phase number determined from STATE.md in Step 1.
115
115
 
116
116
  After execution completes, display a branded completion:
117
117
  ```
118
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
119
- PLAN-BUILD-RUN ► STEP COMPLETE
120
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
118
+ ╔══════════════════════════════════════════════════════════════╗
119
+ PLAN-BUILD-RUN ► STEP COMPLETE
120
+ ╚══════════════════════════════════════════════════════════════╝
121
121
 
122
122
  Completed: {what was done}
123
123
 
@@ -3,6 +3,18 @@ name: dashboard
3
3
  description: "Launch the PBR web dashboard for the current project."
4
4
  ---
5
5
 
6
+ ## Step 0 — Immediate Output
7
+
8
+ **Before ANY tool calls**, display this banner:
9
+
10
+ ```
11
+ ╔══════════════════════════════════════════════════════════════╗
12
+ ║ PLAN-BUILD-RUN ► DASHBOARD ║
13
+ ╚══════════════════════════════════════════════════════════════╝
14
+ ```
15
+
16
+ Then proceed to Step 1.
17
+
6
18
  ## Behavior
7
19
 
8
20
  1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.