@sienklogic/plan-build-run 2.0.0 → 2.0.2

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 (233) hide show
  1. package/CHANGELOG.md +56 -56
  2. package/CLAUDE.md +149 -149
  3. package/LICENSE +21 -21
  4. package/README.md +247 -247
  5. package/dashboard/bin/cli.js +25 -25
  6. package/dashboard/package.json +34 -34
  7. package/dashboard/public/css/layout.css +406 -406
  8. package/dashboard/public/css/status-colors.css +98 -98
  9. package/dashboard/public/js/htmx-title.js +5 -5
  10. package/dashboard/public/js/sidebar-toggle.js +20 -20
  11. package/dashboard/src/app.js +78 -78
  12. package/dashboard/src/middleware/errorHandler.js +52 -52
  13. package/dashboard/src/middleware/notFoundHandler.js +9 -9
  14. package/dashboard/src/repositories/planning.repository.js +128 -128
  15. package/dashboard/src/routes/events.routes.js +40 -40
  16. package/dashboard/src/routes/index.routes.js +31 -31
  17. package/dashboard/src/routes/pages.routes.js +245 -195
  18. package/dashboard/src/server.js +42 -42
  19. package/dashboard/src/services/dashboard.service.js +222 -222
  20. package/dashboard/src/services/phase.service.js +220 -167
  21. package/dashboard/src/services/project.service.js +57 -57
  22. package/dashboard/src/services/roadmap.service.js +171 -171
  23. package/dashboard/src/services/sse.service.js +58 -58
  24. package/dashboard/src/services/todo.service.js +254 -254
  25. package/dashboard/src/services/watcher.service.js +48 -48
  26. package/dashboard/src/views/coming-soon.ejs +11 -11
  27. package/dashboard/src/views/error.ejs +13 -13
  28. package/dashboard/src/views/index.ejs +5 -5
  29. package/dashboard/src/views/layout.ejs +1 -1
  30. package/dashboard/src/views/partials/dashboard-content.ejs +77 -77
  31. package/dashboard/src/views/partials/footer.ejs +3 -3
  32. package/dashboard/src/views/partials/head.ejs +21 -21
  33. package/dashboard/src/views/partials/header.ejs +12 -12
  34. package/dashboard/src/views/partials/layout-bottom.ejs +15 -15
  35. package/dashboard/src/views/partials/layout-top.ejs +8 -8
  36. package/dashboard/src/views/partials/phase-content.ejs +188 -181
  37. package/dashboard/src/views/partials/phase-doc-content.ejs +38 -0
  38. package/dashboard/src/views/partials/phases-content.ejs +117 -117
  39. package/dashboard/src/views/partials/roadmap-content.ejs +142 -142
  40. package/dashboard/src/views/partials/sidebar.ejs +38 -38
  41. package/dashboard/src/views/partials/todo-create-content.ejs +53 -53
  42. package/dashboard/src/views/partials/todo-detail-content.ejs +38 -38
  43. package/dashboard/src/views/partials/todos-content.ejs +53 -53
  44. package/dashboard/src/views/phase-detail.ejs +5 -5
  45. package/dashboard/src/views/phase-doc.ejs +5 -0
  46. package/dashboard/src/views/phases.ejs +5 -5
  47. package/dashboard/src/views/roadmap.ejs +5 -5
  48. package/dashboard/src/views/todo-create.ejs +5 -5
  49. package/dashboard/src/views/todo-detail.ejs +5 -5
  50. package/dashboard/src/views/todos.ejs +5 -5
  51. package/package.json +57 -57
  52. package/plugins/cursor-pbr/.cursor-plugin/plugin.json +22 -0
  53. package/plugins/cursor-pbr/agents/.gitkeep +0 -0
  54. package/plugins/cursor-pbr/assets/.gitkeep +0 -0
  55. package/plugins/cursor-pbr/hooks/hooks.json +11 -0
  56. package/plugins/cursor-pbr/references/.gitkeep +0 -0
  57. package/plugins/cursor-pbr/rules/.gitkeep +0 -0
  58. package/plugins/cursor-pbr/skills/.gitkeep +0 -0
  59. package/plugins/cursor-pbr/templates/.gitkeep +0 -0
  60. package/plugins/pbr/.claude-plugin/plugin.json +13 -13
  61. package/plugins/pbr/UI-CONSISTENCY-GAPS.md +61 -61
  62. package/plugins/pbr/agents/codebase-mapper.md +279 -271
  63. package/plugins/pbr/agents/debugger.md +281 -281
  64. package/plugins/pbr/agents/executor.md +428 -407
  65. package/plugins/pbr/agents/general.md +164 -164
  66. package/plugins/pbr/agents/integration-checker.md +169 -141
  67. package/plugins/pbr/agents/plan-checker.md +296 -280
  68. package/plugins/pbr/agents/planner.md +358 -358
  69. package/plugins/pbr/agents/researcher.md +363 -363
  70. package/plugins/pbr/agents/synthesizer.md +230 -230
  71. package/plugins/pbr/agents/verifier.md +489 -454
  72. package/plugins/pbr/commands/begin.md +5 -5
  73. package/plugins/pbr/commands/build.md +5 -5
  74. package/plugins/pbr/commands/config.md +5 -5
  75. package/plugins/pbr/commands/continue.md +5 -5
  76. package/plugins/pbr/commands/debug.md +5 -5
  77. package/plugins/pbr/commands/discuss.md +5 -5
  78. package/plugins/pbr/commands/explore.md +5 -5
  79. package/plugins/pbr/commands/health.md +5 -5
  80. package/plugins/pbr/commands/help.md +5 -5
  81. package/plugins/pbr/commands/import.md +5 -5
  82. package/plugins/pbr/commands/milestone.md +5 -5
  83. package/plugins/pbr/commands/note.md +5 -5
  84. package/plugins/pbr/commands/pause.md +5 -5
  85. package/plugins/pbr/commands/plan.md +5 -5
  86. package/plugins/pbr/commands/quick.md +5 -5
  87. package/plugins/pbr/commands/resume.md +5 -5
  88. package/plugins/pbr/commands/review.md +5 -5
  89. package/plugins/pbr/commands/scan.md +5 -5
  90. package/plugins/pbr/commands/setup.md +5 -5
  91. package/plugins/pbr/commands/status.md +5 -5
  92. package/plugins/pbr/commands/todo.md +5 -5
  93. package/plugins/pbr/contexts/dev.md +27 -27
  94. package/plugins/pbr/contexts/research.md +28 -28
  95. package/plugins/pbr/contexts/review.md +36 -36
  96. package/plugins/pbr/hooks/hooks.json +183 -183
  97. package/plugins/pbr/references/agent-anti-patterns.md +24 -24
  98. package/plugins/pbr/references/agent-interactions.md +134 -134
  99. package/plugins/pbr/references/agent-teams.md +54 -54
  100. package/plugins/pbr/references/checkpoints.md +157 -157
  101. package/plugins/pbr/references/common-bug-patterns.md +13 -13
  102. package/plugins/pbr/references/config-reference.md +441 -0
  103. package/plugins/pbr/references/continuation-format.md +212 -212
  104. package/plugins/pbr/references/deviation-rules.md +112 -112
  105. package/plugins/pbr/references/git-integration.md +226 -226
  106. package/plugins/pbr/references/integration-patterns.md +117 -117
  107. package/plugins/pbr/references/model-profiles.md +99 -99
  108. package/plugins/pbr/references/model-selection.md +31 -31
  109. package/plugins/pbr/references/pbr-rules.md +193 -193
  110. package/plugins/pbr/references/plan-authoring.md +181 -181
  111. package/plugins/pbr/references/plan-format.md +287 -283
  112. package/plugins/pbr/references/planning-config.md +213 -213
  113. package/plugins/pbr/references/questioning.md +214 -214
  114. package/plugins/pbr/references/reading-verification.md +127 -127
  115. package/plugins/pbr/references/stub-patterns.md +160 -160
  116. package/plugins/pbr/references/subagent-coordination.md +119 -119
  117. package/plugins/pbr/references/ui-formatting.md +461 -399
  118. package/plugins/pbr/references/verification-patterns.md +198 -198
  119. package/plugins/pbr/references/wave-execution.md +95 -95
  120. package/plugins/pbr/scripts/auto-continue.js +80 -80
  121. package/plugins/pbr/scripts/check-dangerous-commands.js +136 -136
  122. package/plugins/pbr/scripts/check-doc-sprawl.js +102 -102
  123. package/plugins/pbr/scripts/check-phase-boundary.js +196 -196
  124. package/plugins/pbr/scripts/check-plan-format.js +270 -270
  125. package/plugins/pbr/scripts/check-roadmap-sync.js +322 -252
  126. package/plugins/pbr/scripts/check-skill-workflow.js +262 -262
  127. package/plugins/pbr/scripts/check-state-sync.js +476 -476
  128. package/plugins/pbr/scripts/check-subagent-output.js +144 -144
  129. package/plugins/pbr/scripts/config-schema.json +251 -251
  130. package/plugins/pbr/scripts/context-budget-check.js +287 -287
  131. package/plugins/pbr/scripts/event-handler.js +151 -151
  132. package/plugins/pbr/scripts/event-logger.js +92 -92
  133. package/plugins/pbr/scripts/hook-logger.js +80 -76
  134. package/plugins/pbr/scripts/hooks-schema.json +79 -79
  135. package/plugins/pbr/scripts/log-subagent.js +164 -152
  136. package/plugins/pbr/scripts/log-tool-failure.js +88 -88
  137. package/plugins/pbr/scripts/pbr-tools.js +1378 -1301
  138. package/plugins/pbr/scripts/post-write-dispatch.js +66 -66
  139. package/plugins/pbr/scripts/post-write-quality.js +207 -207
  140. package/plugins/pbr/scripts/pre-bash-dispatch.js +86 -56
  141. package/plugins/pbr/scripts/pre-write-dispatch.js +97 -62
  142. package/plugins/pbr/scripts/progress-tracker.js +281 -228
  143. package/plugins/pbr/scripts/run-hook.js +92 -0
  144. package/plugins/pbr/scripts/session-cleanup.js +254 -254
  145. package/plugins/pbr/scripts/status-line.js +288 -285
  146. package/plugins/pbr/scripts/suggest-compact.js +119 -119
  147. package/plugins/pbr/scripts/task-completed.js +45 -45
  148. package/plugins/pbr/scripts/track-context-budget.js +149 -119
  149. package/plugins/pbr/scripts/validate-commit.js +200 -200
  150. package/plugins/pbr/scripts/validate-plugin-structure.js +183 -172
  151. package/plugins/pbr/scripts/validate-task.js +106 -0
  152. package/plugins/pbr/skills/begin/SKILL.md +594 -545
  153. package/plugins/pbr/skills/begin/templates/PROJECT.md.tmpl +33 -33
  154. package/plugins/pbr/skills/begin/templates/REQUIREMENTS.md.tmpl +18 -18
  155. package/plugins/pbr/skills/begin/templates/STATE.md.tmpl +49 -49
  156. package/plugins/pbr/skills/begin/templates/config.json.tmpl +64 -63
  157. package/plugins/pbr/skills/begin/templates/researcher-prompt.md.tmpl +19 -19
  158. package/plugins/pbr/skills/begin/templates/roadmap-prompt.md.tmpl +30 -30
  159. package/plugins/pbr/skills/begin/templates/synthesis-prompt.md.tmpl +16 -16
  160. package/plugins/pbr/skills/build/SKILL.md +943 -962
  161. package/plugins/pbr/skills/config/SKILL.md +256 -241
  162. package/plugins/pbr/skills/continue/SKILL.md +164 -127
  163. package/plugins/pbr/skills/debug/SKILL.md +515 -489
  164. package/plugins/pbr/skills/debug/templates/continuation-prompt.md.tmpl +16 -16
  165. package/plugins/pbr/skills/debug/templates/initial-investigation-prompt.md.tmpl +27 -27
  166. package/plugins/pbr/skills/discuss/SKILL.md +347 -338
  167. package/plugins/pbr/skills/discuss/templates/CONTEXT.md.tmpl +61 -61
  168. package/plugins/pbr/skills/discuss/templates/decision-categories.md +9 -9
  169. package/plugins/pbr/skills/explore/SKILL.md +378 -362
  170. package/plugins/pbr/skills/health/SKILL.md +221 -186
  171. package/plugins/pbr/skills/health/templates/check-pattern.md.tmpl +30 -30
  172. package/plugins/pbr/skills/health/templates/output-format.md.tmpl +63 -63
  173. package/plugins/pbr/skills/help/SKILL.md +155 -140
  174. package/plugins/pbr/skills/import/SKILL.md +504 -490
  175. package/plugins/pbr/skills/milestone/SKILL.md +704 -673
  176. package/plugins/pbr/skills/milestone/templates/audit-report.md.tmpl +48 -48
  177. package/plugins/pbr/skills/milestone/templates/stats-file.md.tmpl +30 -30
  178. package/plugins/pbr/skills/note/SKILL.md +231 -212
  179. package/plugins/pbr/skills/pause/SKILL.md +249 -235
  180. package/plugins/pbr/skills/pause/templates/continue-here.md.tmpl +71 -71
  181. package/plugins/pbr/skills/plan/SKILL.md +685 -628
  182. package/plugins/pbr/skills/plan/decimal-phase-calc.md +98 -98
  183. package/plugins/pbr/skills/plan/templates/checker-prompt.md.tmpl +21 -21
  184. package/plugins/pbr/skills/plan/templates/gap-closure-prompt.md.tmpl +32 -32
  185. package/plugins/pbr/skills/plan/templates/planner-prompt.md.tmpl +38 -38
  186. package/plugins/pbr/skills/plan/templates/researcher-prompt.md.tmpl +19 -19
  187. package/plugins/pbr/skills/plan/templates/revision-prompt.md.tmpl +23 -23
  188. package/plugins/pbr/skills/quick/SKILL.md +354 -335
  189. package/plugins/pbr/skills/resume/SKILL.md +402 -388
  190. package/plugins/pbr/skills/review/SKILL.md +686 -652
  191. package/plugins/pbr/skills/review/templates/debugger-prompt.md.tmpl +60 -60
  192. package/plugins/pbr/skills/review/templates/gap-planner-prompt.md.tmpl +40 -40
  193. package/plugins/pbr/skills/review/templates/verifier-prompt.md.tmpl +115 -115
  194. package/plugins/pbr/skills/scan/SKILL.md +304 -269
  195. package/plugins/pbr/skills/scan/templates/mapper-prompt.md.tmpl +201 -201
  196. package/plugins/pbr/skills/setup/SKILL.md +253 -227
  197. package/plugins/pbr/skills/shared/commit-planning-docs.md +35 -35
  198. package/plugins/pbr/skills/shared/config-loading.md +102 -102
  199. package/plugins/pbr/skills/shared/context-budget.md +40 -40
  200. package/plugins/pbr/skills/shared/context-loader-task.md +86 -86
  201. package/plugins/pbr/skills/shared/digest-select.md +79 -79
  202. package/plugins/pbr/skills/shared/domain-probes.md +125 -125
  203. package/plugins/pbr/skills/shared/error-reporting.md +79 -79
  204. package/plugins/pbr/skills/shared/gate-prompts.md +388 -388
  205. package/plugins/pbr/skills/shared/phase-argument-parsing.md +45 -45
  206. package/plugins/pbr/skills/shared/progress-display.md +53 -53
  207. package/plugins/pbr/skills/shared/revision-loop.md +81 -81
  208. package/plugins/pbr/skills/shared/state-loading.md +62 -62
  209. package/plugins/pbr/skills/shared/state-update.md +161 -161
  210. package/plugins/pbr/skills/shared/universal-anti-patterns.md +33 -33
  211. package/plugins/pbr/skills/status/SKILL.md +367 -353
  212. package/plugins/pbr/skills/todo/SKILL.md +198 -181
  213. package/plugins/pbr/templates/CONTEXT.md.tmpl +52 -52
  214. package/plugins/pbr/templates/INTEGRATION-REPORT.md.tmpl +151 -151
  215. package/plugins/pbr/templates/RESEARCH-SUMMARY.md.tmpl +97 -97
  216. package/plugins/pbr/templates/ROADMAP.md.tmpl +40 -40
  217. package/plugins/pbr/templates/SUMMARY.md.tmpl +81 -81
  218. package/plugins/pbr/templates/VERIFICATION-DETAIL.md.tmpl +116 -116
  219. package/plugins/pbr/templates/codebase/ARCHITECTURE.md.tmpl +98 -98
  220. package/plugins/pbr/templates/codebase/CONCERNS.md.tmpl +93 -93
  221. package/plugins/pbr/templates/codebase/CONVENTIONS.md.tmpl +104 -104
  222. package/plugins/pbr/templates/codebase/INTEGRATIONS.md.tmpl +78 -78
  223. package/plugins/pbr/templates/codebase/STACK.md.tmpl +78 -78
  224. package/plugins/pbr/templates/codebase/STRUCTURE.md.tmpl +80 -80
  225. package/plugins/pbr/templates/codebase/TESTING.md.tmpl +107 -107
  226. package/plugins/pbr/templates/continue-here.md.tmpl +73 -73
  227. package/plugins/pbr/templates/prompt-partials/phase-project-context.md.tmpl +37 -37
  228. package/plugins/pbr/templates/research/ARCHITECTURE.md.tmpl +124 -124
  229. package/plugins/pbr/templates/research/STACK.md.tmpl +71 -71
  230. package/plugins/pbr/templates/research/SUMMARY.md.tmpl +112 -112
  231. package/plugins/pbr/templates/research-outputs/phase-research.md.tmpl +81 -81
  232. package/plugins/pbr/templates/research-outputs/project-research.md.tmpl +99 -99
  233. package/plugins/pbr/templates/research-outputs/synthesis.md.tmpl +36 -36
package/CHANGELOG.md CHANGED
@@ -1,56 +1,56 @@
1
- # Changelog
2
-
3
- All notable changes to Plan-Build-Run will be documented in this file.
4
-
5
- The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
- and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
-
8
- ## [Unreleased]
9
-
10
- ## [2.0.0] - 2026-02-17
11
-
12
- ### Added
13
- - Token-saving CLI: 6 new commands in `towline-tools.js` — `frontmatter`, `must-haves`, `phase-info`, `state update`, `roadmap update-status`, `roadmap update-plans`
14
- - Companion web dashboard (Express 5.x, EJS, Pico.css v2, HTMX 2.0) with overview, phase detail, roadmap, todos, and SSE live updates
15
- - `/dev:import` skill — Import external plan documents into Towline format
16
- - `/dev:note` skill — Zero-friction idea capture with promote-to-todo support
17
- - `/dev:setup` skill — Interactive onboarding wizard for new installations
18
- - `/dev:explore` skill — Socratic conversation for idea exploration
19
- - `/dev:continue` skill — Execute the next logical step automatically
20
- - `/dev:health` skill — Validate `.planning/` directory integrity
21
- - General agent — Lightweight Towline-aware agent for ad-hoc tasks
22
- - `/dev:build <N> --team` variant — Agent Teams for complex inter-agent coordination
23
- - `/dev:review <N> --auto-fix` variant — Auto-diagnose and fix verification failures
24
- - Hook spawn tests for all lifecycle hooks
25
- - Iterative retrieval protocol for researcher agent
26
- - Behavioral contexts for agent prompt refinement
27
- - Published to npm with OIDC trusted publishing
28
-
29
- ### Changed
30
- - Skill count increased from 15 to 21
31
- - Agent count increased from 9 to 10 (added General agent)
32
- - Hook scripts consolidated: Write/Edit dispatch reduced from 4 spawns to 2
33
- - All hook scripts now use `logHook()` from `hook-logger.js` for unified logging
34
- - Agents reference new CLI tooling shortcuts instead of manual YAML parsing
35
- - README rewritten with badges, comparison table, and acknowledgments
36
- - Package tarball trimmed from 1.9MB to 305KB via explicit `files` field
37
-
38
- ### Fixed
39
- - Windows CI: `parseMustHaves` now trims CRLF line endings
40
- - Context budget: main orchestrator no longer reads agent definitions (saves ~15% context)
41
- - Hook logger rotation: `.hook-log` now caps at 200 entries with JSONL format
42
- - Status line ANSI rendering on Windows terminals
43
-
44
- ## [1.0.0] - 2025-02-07
45
-
46
- ### Added
47
- - Initial release of Plan-Build-Run plugin for Claude Code
48
- - 15 skills: begin, plan, build, review, discuss, quick, debug, status, pause, resume, milestone, scan, todo, config, help
49
- - 9 specialized agents: researcher, planner, plan-checker, executor, verifier, integration-checker, debugger, codebase-mapper, synthesizer
50
- - Hook-enforced quality gates: commit validation, plan format checking, session state injection, pre-compact preservation
51
- - Wave-based parallel execution via Task() subagents
52
- - Goal-backward verification at phase and milestone levels
53
- - Persistent file-based state management (.planning/ directory)
54
- - Configurable workflow: depth, models, gates, parallelization, git branching
55
- - Cross-platform Node.js hook scripts (Windows + macOS + Linux)
56
- - Plugin distribution via npm
1
+ # Changelog
2
+
3
+ All notable changes to Plan-Build-Run will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [2.0.0] - 2026-02-17
11
+
12
+ ### Added
13
+ - Token-saving CLI: 6 new commands in `towline-tools.js` — `frontmatter`, `must-haves`, `phase-info`, `state update`, `roadmap update-status`, `roadmap update-plans`
14
+ - Companion web dashboard (Express 5.x, EJS, Pico.css v2, HTMX 2.0) with overview, phase detail, roadmap, todos, and SSE live updates
15
+ - `/dev:import` skill — Import external plan documents into Towline format
16
+ - `/dev:note` skill — Zero-friction idea capture with promote-to-todo support
17
+ - `/dev:setup` skill — Interactive onboarding wizard for new installations
18
+ - `/dev:explore` skill — Socratic conversation for idea exploration
19
+ - `/dev:continue` skill — Execute the next logical step automatically
20
+ - `/dev:health` skill — Validate `.planning/` directory integrity
21
+ - General agent — Lightweight Towline-aware agent for ad-hoc tasks
22
+ - `/dev:build <N> --team` variant — Agent Teams for complex inter-agent coordination
23
+ - `/dev:review <N> --auto-fix` variant — Auto-diagnose and fix verification failures
24
+ - Hook spawn tests for all lifecycle hooks
25
+ - Iterative retrieval protocol for researcher agent
26
+ - Behavioral contexts for agent prompt refinement
27
+ - Published to npm with OIDC trusted publishing
28
+
29
+ ### Changed
30
+ - Skill count increased from 15 to 21
31
+ - Agent count increased from 9 to 10 (added General agent)
32
+ - Hook scripts consolidated: Write/Edit dispatch reduced from 4 spawns to 2
33
+ - All hook scripts now use `logHook()` from `hook-logger.js` for unified logging
34
+ - Agents reference new CLI tooling shortcuts instead of manual YAML parsing
35
+ - README rewritten with badges, comparison table, and acknowledgments
36
+ - Package tarball trimmed from 1.9MB to 305KB via explicit `files` field
37
+
38
+ ### Fixed
39
+ - Windows CI: `parseMustHaves` now trims CRLF line endings
40
+ - Context budget: main orchestrator no longer reads agent definitions (saves ~15% context)
41
+ - Hook logger rotation: `.hook-log` now caps at 200 entries with JSONL format
42
+ - Status line ANSI rendering on Windows terminals
43
+
44
+ ## [1.0.0] - 2025-02-07
45
+
46
+ ### Added
47
+ - Initial release of Plan-Build-Run plugin for Claude Code
48
+ - 15 skills: begin, plan, build, review, discuss, quick, debug, status, pause, resume, milestone, scan, todo, config, help
49
+ - 9 specialized agents: researcher, planner, plan-checker, executor, verifier, integration-checker, debugger, codebase-mapper, synthesizer
50
+ - Hook-enforced quality gates: commit validation, plan format checking, session state injection, pre-compact preservation
51
+ - Wave-based parallel execution via Task() subagents
52
+ - Goal-backward verification at phase and milestone levels
53
+ - Persistent file-based state management (.planning/ directory)
54
+ - Configurable workflow: depth, models, gates, parallelization, git branching
55
+ - Cross-platform Node.js hook scripts (Windows + macOS + Linux)
56
+ - Plugin distribution via npm
package/CLAUDE.md CHANGED
@@ -1,149 +1,149 @@
1
- # CLAUDE.md
2
-
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
-
5
- ## What This Is
6
-
7
- Plan-Build-Run is a **Claude Code plugin** that provides a structured development workflow. It solves context rot — quality degradation as Claude's context window fills up — through disciplined subagent delegation, file-based state, and goal-backward verification. Users invoke `/pbr:*` slash commands (skills) that orchestrate specialized agents via `Task()`.
8
-
9
- ## Critical Rules
10
-
11
- - **NEVER add AI co-author lines** to git commits or PRs. No `Co-Authored-By: Claude` or similar. Only add co-author lines referencing actual human contributors.
12
- - **NEVER inline agent definitions** into skill prompts. Use `subagent_type: "pbr:{name}"` — Claude Code auto-loads agent definitions from `agents/`. Reading agent `.md` files wastes main context.
13
-
14
- ## Commands
15
-
16
- ```bash
17
- npm test # Run all Jest tests (~780 tests, 36 suites)
18
- npm run lint # ESLint on plugins/pbr/scripts/ and tests/
19
- npm run validate # Validate plugin directory structure
20
- npx jest tests/validate-commit.test.js # Run a single test file
21
- npx jest --coverage # Run with coverage report
22
- ```
23
-
24
- Coverage thresholds (enforced in `package.json`): 65% statements, 58% branches, 70% functions, 65% lines.
25
-
26
- Dashboard (separate dependency tree):
27
- ```bash
28
- npm run dashboard:install # One-time install of dashboard deps
29
- npm run dashboard -- --dir /path/to/project # Launch dashboard for a project
30
- ```
31
-
32
- Load the plugin locally for manual testing:
33
- ```bash
34
- claude --plugin-dir .
35
- ```
36
-
37
- CI runs on Node 18/20/22 across Windows, macOS, and Linux. All three platforms must pass.
38
-
39
- ## Architecture
40
-
41
- All plugin code lives under `plugins/pbr/`. Three layers:
42
-
43
- ### Skills (`skills/{name}/SKILL.md`)
44
- Markdown files with YAML frontmatter defining slash commands (`/pbr:begin`, `/pbr:plan`, etc.). Each SKILL.md is a complete prompt that tells the orchestrator what to do. Skills read state, interact with the user, and spawn agents.
45
-
46
- 21 skills: begin, build, config, continue, debug, discuss, explore, health, help, import, milestone, note, pause, plan, quick, resume, review, scan, setup, status, todo.
47
-
48
- ### Agents (`agents/{name}.md`)
49
- Markdown files with YAML frontmatter defining specialized subagent prompts. Agents run in fresh `Task()` contexts with clean 200k token windows. Spawned via `subagent_type: "pbr:{name}"` — auto-loaded by Claude Code.
50
-
51
- 10 agents: researcher, planner, plan-checker, executor, verifier, integration-checker, debugger, codebase-mapper, synthesizer, general.
52
-
53
- ### Scripts (`scripts/*.js`)
54
- 28 Node.js hook scripts that fire on Claude Code lifecycle events. Configured in `hooks/hooks.json`. All use CommonJS, must be cross-platform (`path.join()`, not hardcoded separators), and log via `logHook()` from `hook-logger.js`.
55
-
56
- **Dispatch pattern**: Several hooks use dispatch scripts that fan out to sub-scripts based on the file being written/read:
57
-
58
- | Hook Event | Entry Script | Delegates To |
59
- |------------|-------------|-------------|
60
- | SessionStart | progress-tracker.js | — (injects project state) |
61
- | PostToolUse (Write\|Edit) | post-write-dispatch.js | check-plan-format.js, check-roadmap-sync.js, check-state-sync.js |
62
- | PostToolUse (Write\|Edit) | post-write-quality.js | check-doc-sprawl.js, check-skill-workflow.js |
63
- | PostToolUse (Task) | check-subagent-output.js | — (validates agent output) |
64
- | PostToolUse (Write\|Edit) | suggest-compact.js | — (context budget warnings) |
65
- | PostToolUse (Read) | track-context-budget.js | — (tracks reads for budget) |
66
- | PostToolUseFailure | log-tool-failure.js | — (logs failures) |
67
- | PreToolUse (Bash) | pre-bash-dispatch.js | validate-commit.js, check-dangerous-commands.js, check-phase-boundary.js |
68
- | PreToolUse (Write\|Edit) | pre-write-dispatch.js | — (write guards) |
69
- | PreCompact | context-budget-check.js | — (preserves STATE.md) |
70
- | Stop | auto-continue.js | — (chains next command) |
71
- | SubagentStart/Stop | log-subagent.js | — (tracks lifecycle) |
72
- | SubagentStop | event-handler.js | — (auto-verification trigger) |
73
- | TaskCompleted | task-completed.js | — (processes task completion) |
74
- | SessionEnd | session-cleanup.js | — (cleanup) |
75
-
76
- **Hook exit codes**: 0 = success, 2 = block (PreToolUse hooks that reject a tool call).
77
-
78
- **`${CLAUDE_PLUGIN_ROOT}`**: Used in hooks.json to reference script paths. Claude Code expands this internally — works on all platforms without shell expansion.
79
-
80
- ### Supporting directories
81
-
82
- - **`references/`** — Shared reference docs loaded by skills (plan format, commit conventions, UI formatting, deviation rules)
83
- - **`templates/`** — EJS-style `.tmpl` files for generated markdown (VERIFICATION.md, SUMMARY.md, etc.)
84
- - **`commands/`** — Command registration files (one `.md` per command mapping to its skill)
85
- - **`skills/shared/`** — 14 shared skill fragments extracted from repeated patterns across skills (config-loading, digest-select, revision-loop, context-loader-task, universal-anti-patterns, phase-argument-parsing, gate-prompts, state-loading, state-update, commit-planning-docs, context-budget, domain-probes, progress-display, error-reporting)
86
-
87
- ## Key Conventions
88
-
89
- **Commit format**: `{type}({scope}): {description}` — enforced by PreToolUse hook. Types: feat, fix, refactor, test, docs, chore, wip. Scopes: `{NN}-{MM}` (phase-plan), `quick-{NNN}`, `planning`, `tools`, or descriptive word.
90
-
91
- **Skill frontmatter** (SKILL.md):
92
- ```yaml
93
- ---
94
- name: skill-name
95
- description: "What this skill does"
96
- allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task
97
- argument-hint: "<N> [--flag]"
98
- ---
99
- ```
100
-
101
- **Agent frontmatter** ({name}.md):
102
- ```yaml
103
- ---
104
- name: agent-name
105
- description: "What this agent does"
106
- model: sonnet|inherit|haiku
107
- memory: none|user|project
108
- tools:
109
- - Read
110
- - Write
111
- - Bash
112
- ---
113
- ```
114
-
115
- ## Data Flow
116
-
117
- Skills and agents communicate through files on disk, not messages:
118
-
119
- ```
120
- .planning/STATE.md ← source of truth for current position
121
- .planning/ROADMAP.md ← phase structure, goals, dependencies
122
- .planning/config.json ← workflow settings (~62 properties across 12 top-level keys)
123
- .planning/phases/NN-slug/
124
- PLAN.md ← written by planner, read by executor
125
- SUMMARY.md ← written by executor, read by orchestrator
126
- VERIFICATION.md ← written by verifier, read by review skill
127
- ```
128
-
129
- The orchestrator stays lean (~15% context) by delegating heavy work to agents. Each agent gets a fresh context window.
130
-
131
- **Utility library**: `pbr-tools.js` is a shared Node.js library (stateLoad, configLoad, frontmatterParse, mustHavesCollect, etc.) used by multiple hook scripts. It provides CLI subcommands that agents call to avoid wasting tokens on file parsing.
132
-
133
- ## Testing
134
-
135
- Tests live in `tests/` using Jest. Test files mirror script names: `validate-commit.test.js` tests `validate-commit.js`.
136
-
137
- **Fixture project**: `tests/fixtures/fake-project/.planning/` provides read-only fixture data for tests.
138
-
139
- **Mutation tests**: Use `fs.mkdtempSync()` to create temporary directories — never mutate the fixture project.
140
-
141
- **`pbr-tools.js` tests** span both `pbr-tools.test.js` and `integration.test.js`.
142
-
143
- When adding a new hook script, create a corresponding test file. Tests must pass on Windows, macOS, and Linux.
144
-
145
- ## Dashboard
146
-
147
- The dashboard (`dashboard/`) is a separate Express.js application with its own dependency tree (`dashboard/package.json`). It provides a web UI for browsing `.planning/` state. Tech: Express 5.x, EJS, Pico.css, HTMX 2.0, chokidar for file watching, SSE for live updates.
148
-
149
- Dashboard tests use Vitest (not Jest) and live in `dashboard/tests/`. Run with `npm --prefix dashboard test`.
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## What This Is
6
+
7
+ Plan-Build-Run is a **Claude Code plugin** that provides a structured development workflow. It solves context rot — quality degradation as Claude's context window fills up — through disciplined subagent delegation, file-based state, and goal-backward verification. Users invoke `/pbr:*` slash commands (skills) that orchestrate specialized agents via `Task()`.
8
+
9
+ ## Critical Rules
10
+
11
+ - **NEVER add AI co-author lines** to git commits or PRs. No `Co-Authored-By: Claude` or similar. Only add co-author lines referencing actual human contributors.
12
+ - **NEVER inline agent definitions** into skill prompts. Use `subagent_type: "pbr:{name}"` — Claude Code auto-loads agent definitions from `agents/`. Reading agent `.md` files wastes main context.
13
+
14
+ ## Commands
15
+
16
+ ```bash
17
+ npm test # Run all Jest tests (~780 tests, 36 suites)
18
+ npm run lint # ESLint on plugins/pbr/scripts/ and tests/
19
+ npm run validate # Validate plugin directory structure
20
+ npx jest tests/validate-commit.test.js # Run a single test file
21
+ npx jest --coverage # Run with coverage report
22
+ ```
23
+
24
+ Coverage thresholds (enforced in `package.json`): 65% statements, 58% branches, 70% functions, 65% lines.
25
+
26
+ Dashboard (separate dependency tree):
27
+ ```bash
28
+ npm run dashboard:install # One-time install of dashboard deps
29
+ npm run dashboard -- --dir /path/to/project # Launch dashboard for a project
30
+ ```
31
+
32
+ Load the plugin locally for manual testing:
33
+ ```bash
34
+ claude --plugin-dir .
35
+ ```
36
+
37
+ CI runs on Node 18/20/22 across Windows, macOS, and Linux. All three platforms must pass.
38
+
39
+ ## Architecture
40
+
41
+ All plugin code lives under `plugins/pbr/`. Three layers:
42
+
43
+ ### Skills (`skills/{name}/SKILL.md`)
44
+ Markdown files with YAML frontmatter defining slash commands (`/pbr:begin`, `/pbr:plan`, etc.). Each SKILL.md is a complete prompt that tells the orchestrator what to do. Skills read state, interact with the user, and spawn agents.
45
+
46
+ 21 skills: begin, build, config, continue, debug, discuss, explore, health, help, import, milestone, note, pause, plan, quick, resume, review, scan, setup, status, todo.
47
+
48
+ ### Agents (`agents/{name}.md`)
49
+ Markdown files with YAML frontmatter defining specialized subagent prompts. Agents run in fresh `Task()` contexts with clean 200k token windows. Spawned via `subagent_type: "pbr:{name}"` — auto-loaded by Claude Code.
50
+
51
+ 10 agents: researcher, planner, plan-checker, executor, verifier, integration-checker, debugger, codebase-mapper, synthesizer, general.
52
+
53
+ ### Scripts (`scripts/*.js`)
54
+ 28 Node.js hook scripts that fire on Claude Code lifecycle events. Configured in `hooks/hooks.json`. All use CommonJS, must be cross-platform (`path.join()`, not hardcoded separators), and log via `logHook()` from `hook-logger.js`.
55
+
56
+ **Dispatch pattern**: Several hooks use dispatch scripts that fan out to sub-scripts based on the file being written/read:
57
+
58
+ | Hook Event | Entry Script | Delegates To |
59
+ |------------|-------------|-------------|
60
+ | SessionStart | progress-tracker.js | — (injects project state) |
61
+ | PostToolUse (Write\|Edit) | post-write-dispatch.js | check-plan-format.js, check-roadmap-sync.js, check-state-sync.js |
62
+ | PostToolUse (Write\|Edit) | post-write-quality.js | check-doc-sprawl.js, check-skill-workflow.js |
63
+ | PostToolUse (Task) | check-subagent-output.js | — (validates agent output) |
64
+ | PostToolUse (Write\|Edit) | suggest-compact.js | — (context budget warnings) |
65
+ | PostToolUse (Read) | track-context-budget.js | — (tracks reads for budget) |
66
+ | PostToolUseFailure | log-tool-failure.js | — (logs failures) |
67
+ | PreToolUse (Bash) | pre-bash-dispatch.js | validate-commit.js, check-dangerous-commands.js, check-phase-boundary.js |
68
+ | PreToolUse (Write\|Edit) | pre-write-dispatch.js | — (write guards) |
69
+ | PreCompact | context-budget-check.js | — (preserves STATE.md) |
70
+ | Stop | auto-continue.js | — (chains next command) |
71
+ | SubagentStart/Stop | log-subagent.js | — (tracks lifecycle) |
72
+ | SubagentStop | event-handler.js | — (auto-verification trigger) |
73
+ | TaskCompleted | task-completed.js | — (processes task completion) |
74
+ | SessionEnd | session-cleanup.js | — (cleanup) |
75
+
76
+ **Hook exit codes**: 0 = success, 2 = block (PreToolUse hooks that reject a tool call).
77
+
78
+ **`${CLAUDE_PLUGIN_ROOT}`**: Used in hooks.json to reference script paths. Claude Code expands this internally — works on all platforms without shell expansion.
79
+
80
+ ### Supporting directories
81
+
82
+ - **`references/`** — Shared reference docs loaded by skills (plan format, commit conventions, UI formatting, deviation rules)
83
+ - **`templates/`** — EJS-style `.tmpl` files for generated markdown (VERIFICATION.md, SUMMARY.md, etc.)
84
+ - **`commands/`** — Command registration files (one `.md` per command mapping to its skill)
85
+ - **`skills/shared/`** — 14 shared skill fragments extracted from repeated patterns across skills (config-loading, digest-select, revision-loop, context-loader-task, universal-anti-patterns, phase-argument-parsing, gate-prompts, state-loading, state-update, commit-planning-docs, context-budget, domain-probes, progress-display, error-reporting)
86
+
87
+ ## Key Conventions
88
+
89
+ **Commit format**: `{type}({scope}): {description}` — enforced by PreToolUse hook. Types: feat, fix, refactor, test, docs, chore, wip. Scopes: `{NN}-{MM}` (phase-plan), `quick-{NNN}`, `planning`, `tools`, or descriptive word.
90
+
91
+ **Skill frontmatter** (SKILL.md):
92
+ ```yaml
93
+ ---
94
+ name: skill-name
95
+ description: "What this skill does"
96
+ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task
97
+ argument-hint: "<N> [--flag]"
98
+ ---
99
+ ```
100
+
101
+ **Agent frontmatter** ({name}.md):
102
+ ```yaml
103
+ ---
104
+ name: agent-name
105
+ description: "What this agent does"
106
+ model: sonnet|inherit|haiku
107
+ memory: none|user|project
108
+ tools:
109
+ - Read
110
+ - Write
111
+ - Bash
112
+ ---
113
+ ```
114
+
115
+ ## Data Flow
116
+
117
+ Skills and agents communicate through files on disk, not messages:
118
+
119
+ ```
120
+ .planning/STATE.md ← source of truth for current position
121
+ .planning/ROADMAP.md ← phase structure, goals, dependencies
122
+ .planning/config.json ← workflow settings (~62 properties across 12 top-level keys)
123
+ .planning/phases/NN-slug/
124
+ PLAN.md ← written by planner, read by executor
125
+ SUMMARY.md ← written by executor, read by orchestrator
126
+ VERIFICATION.md ← written by verifier, read by review skill
127
+ ```
128
+
129
+ The orchestrator stays lean (~15% context) by delegating heavy work to agents. Each agent gets a fresh context window.
130
+
131
+ **Utility library**: `pbr-tools.js` is a shared Node.js library (stateLoad, configLoad, frontmatterParse, mustHavesCollect, etc.) used by multiple hook scripts. It provides CLI subcommands that agents call to avoid wasting tokens on file parsing.
132
+
133
+ ## Testing
134
+
135
+ Tests live in `tests/` using Jest. Test files mirror script names: `validate-commit.test.js` tests `validate-commit.js`.
136
+
137
+ **Fixture project**: `tests/fixtures/fake-project/.planning/` provides read-only fixture data for tests.
138
+
139
+ **Mutation tests**: Use `fs.mkdtempSync()` to create temporary directories — never mutate the fixture project.
140
+
141
+ **`pbr-tools.js` tests** span both `pbr-tools.test.js` and `integration.test.js`.
142
+
143
+ When adding a new hook script, create a corresponding test file. Tests must pass on Windows, macOS, and Linux.
144
+
145
+ ## Dashboard
146
+
147
+ The dashboard (`dashboard/`) is a separate Express.js application with its own dependency tree (`dashboard/package.json`). It provides a web UI for browsing `.planning/` state. Tech: Express 5.x, EJS, Pico.css, HTMX 2.0, chokidar for file watching, SSE for live updates.
148
+
149
+ Dashboard tests use Vitest (not Jest) and live in `dashboard/tests/`. Run with `npm --prefix dashboard test`.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2025 Towline Contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Towline Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.