@sienklogic/plan-build-run 2.0.0 → 2.0.1

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 (225) 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/pbr/.claude-plugin/plugin.json +13 -13
  53. package/plugins/pbr/UI-CONSISTENCY-GAPS.md +61 -61
  54. package/plugins/pbr/agents/codebase-mapper.md +279 -271
  55. package/plugins/pbr/agents/debugger.md +281 -281
  56. package/plugins/pbr/agents/executor.md +428 -407
  57. package/plugins/pbr/agents/general.md +164 -164
  58. package/plugins/pbr/agents/integration-checker.md +169 -141
  59. package/plugins/pbr/agents/plan-checker.md +296 -280
  60. package/plugins/pbr/agents/planner.md +358 -358
  61. package/plugins/pbr/agents/researcher.md +363 -363
  62. package/plugins/pbr/agents/synthesizer.md +230 -230
  63. package/plugins/pbr/agents/verifier.md +489 -454
  64. package/plugins/pbr/commands/begin.md +5 -5
  65. package/plugins/pbr/commands/build.md +5 -5
  66. package/plugins/pbr/commands/config.md +5 -5
  67. package/plugins/pbr/commands/continue.md +5 -5
  68. package/plugins/pbr/commands/debug.md +5 -5
  69. package/plugins/pbr/commands/discuss.md +5 -5
  70. package/plugins/pbr/commands/explore.md +5 -5
  71. package/plugins/pbr/commands/health.md +5 -5
  72. package/plugins/pbr/commands/help.md +5 -5
  73. package/plugins/pbr/commands/import.md +5 -5
  74. package/plugins/pbr/commands/milestone.md +5 -5
  75. package/plugins/pbr/commands/note.md +5 -5
  76. package/plugins/pbr/commands/pause.md +5 -5
  77. package/plugins/pbr/commands/plan.md +5 -5
  78. package/plugins/pbr/commands/quick.md +5 -5
  79. package/plugins/pbr/commands/resume.md +5 -5
  80. package/plugins/pbr/commands/review.md +5 -5
  81. package/plugins/pbr/commands/scan.md +5 -5
  82. package/plugins/pbr/commands/setup.md +5 -5
  83. package/plugins/pbr/commands/status.md +5 -5
  84. package/plugins/pbr/commands/todo.md +5 -5
  85. package/plugins/pbr/contexts/dev.md +27 -27
  86. package/plugins/pbr/contexts/research.md +28 -28
  87. package/plugins/pbr/contexts/review.md +36 -36
  88. package/plugins/pbr/hooks/hooks.json +183 -183
  89. package/plugins/pbr/references/agent-anti-patterns.md +24 -24
  90. package/plugins/pbr/references/agent-interactions.md +134 -134
  91. package/plugins/pbr/references/agent-teams.md +54 -54
  92. package/plugins/pbr/references/checkpoints.md +157 -157
  93. package/plugins/pbr/references/common-bug-patterns.md +13 -13
  94. package/plugins/pbr/references/config-reference.md +441 -0
  95. package/plugins/pbr/references/continuation-format.md +212 -212
  96. package/plugins/pbr/references/deviation-rules.md +112 -112
  97. package/plugins/pbr/references/git-integration.md +226 -226
  98. package/plugins/pbr/references/integration-patterns.md +117 -117
  99. package/plugins/pbr/references/model-profiles.md +99 -99
  100. package/plugins/pbr/references/model-selection.md +31 -31
  101. package/plugins/pbr/references/pbr-rules.md +193 -193
  102. package/plugins/pbr/references/plan-authoring.md +181 -181
  103. package/plugins/pbr/references/plan-format.md +287 -283
  104. package/plugins/pbr/references/planning-config.md +213 -213
  105. package/plugins/pbr/references/questioning.md +214 -214
  106. package/plugins/pbr/references/reading-verification.md +127 -127
  107. package/plugins/pbr/references/stub-patterns.md +160 -160
  108. package/plugins/pbr/references/subagent-coordination.md +119 -119
  109. package/plugins/pbr/references/ui-formatting.md +461 -399
  110. package/plugins/pbr/references/verification-patterns.md +198 -198
  111. package/plugins/pbr/references/wave-execution.md +95 -95
  112. package/plugins/pbr/scripts/auto-continue.js +80 -80
  113. package/plugins/pbr/scripts/check-dangerous-commands.js +136 -136
  114. package/plugins/pbr/scripts/check-doc-sprawl.js +102 -102
  115. package/plugins/pbr/scripts/check-phase-boundary.js +196 -196
  116. package/plugins/pbr/scripts/check-plan-format.js +270 -270
  117. package/plugins/pbr/scripts/check-roadmap-sync.js +322 -252
  118. package/plugins/pbr/scripts/check-skill-workflow.js +262 -262
  119. package/plugins/pbr/scripts/check-state-sync.js +476 -476
  120. package/plugins/pbr/scripts/check-subagent-output.js +144 -144
  121. package/plugins/pbr/scripts/config-schema.json +251 -251
  122. package/plugins/pbr/scripts/context-budget-check.js +287 -287
  123. package/plugins/pbr/scripts/event-handler.js +151 -151
  124. package/plugins/pbr/scripts/event-logger.js +92 -92
  125. package/plugins/pbr/scripts/hook-logger.js +80 -76
  126. package/plugins/pbr/scripts/hooks-schema.json +79 -79
  127. package/plugins/pbr/scripts/log-subagent.js +164 -152
  128. package/plugins/pbr/scripts/log-tool-failure.js +88 -88
  129. package/plugins/pbr/scripts/pbr-tools.js +1378 -1301
  130. package/plugins/pbr/scripts/post-write-dispatch.js +66 -66
  131. package/plugins/pbr/scripts/post-write-quality.js +207 -207
  132. package/plugins/pbr/scripts/pre-bash-dispatch.js +86 -56
  133. package/plugins/pbr/scripts/pre-write-dispatch.js +97 -62
  134. package/plugins/pbr/scripts/progress-tracker.js +281 -228
  135. package/plugins/pbr/scripts/run-hook.js +92 -0
  136. package/plugins/pbr/scripts/session-cleanup.js +254 -254
  137. package/plugins/pbr/scripts/status-line.js +288 -285
  138. package/plugins/pbr/scripts/suggest-compact.js +119 -119
  139. package/plugins/pbr/scripts/task-completed.js +45 -45
  140. package/plugins/pbr/scripts/track-context-budget.js +149 -119
  141. package/plugins/pbr/scripts/validate-commit.js +200 -200
  142. package/plugins/pbr/scripts/validate-plugin-structure.js +183 -172
  143. package/plugins/pbr/scripts/validate-task.js +106 -0
  144. package/plugins/pbr/skills/begin/SKILL.md +594 -545
  145. package/plugins/pbr/skills/begin/templates/PROJECT.md.tmpl +33 -33
  146. package/plugins/pbr/skills/begin/templates/REQUIREMENTS.md.tmpl +18 -18
  147. package/plugins/pbr/skills/begin/templates/STATE.md.tmpl +49 -49
  148. package/plugins/pbr/skills/begin/templates/config.json.tmpl +64 -63
  149. package/plugins/pbr/skills/begin/templates/researcher-prompt.md.tmpl +19 -19
  150. package/plugins/pbr/skills/begin/templates/roadmap-prompt.md.tmpl +30 -30
  151. package/plugins/pbr/skills/begin/templates/synthesis-prompt.md.tmpl +16 -16
  152. package/plugins/pbr/skills/build/SKILL.md +943 -962
  153. package/plugins/pbr/skills/config/SKILL.md +256 -241
  154. package/plugins/pbr/skills/continue/SKILL.md +164 -127
  155. package/plugins/pbr/skills/debug/SKILL.md +515 -489
  156. package/plugins/pbr/skills/debug/templates/continuation-prompt.md.tmpl +16 -16
  157. package/plugins/pbr/skills/debug/templates/initial-investigation-prompt.md.tmpl +27 -27
  158. package/plugins/pbr/skills/discuss/SKILL.md +347 -338
  159. package/plugins/pbr/skills/discuss/templates/CONTEXT.md.tmpl +61 -61
  160. package/plugins/pbr/skills/discuss/templates/decision-categories.md +9 -9
  161. package/plugins/pbr/skills/explore/SKILL.md +378 -362
  162. package/plugins/pbr/skills/health/SKILL.md +221 -186
  163. package/plugins/pbr/skills/health/templates/check-pattern.md.tmpl +30 -30
  164. package/plugins/pbr/skills/health/templates/output-format.md.tmpl +63 -63
  165. package/plugins/pbr/skills/help/SKILL.md +155 -140
  166. package/plugins/pbr/skills/import/SKILL.md +504 -490
  167. package/plugins/pbr/skills/milestone/SKILL.md +704 -673
  168. package/plugins/pbr/skills/milestone/templates/audit-report.md.tmpl +48 -48
  169. package/plugins/pbr/skills/milestone/templates/stats-file.md.tmpl +30 -30
  170. package/plugins/pbr/skills/note/SKILL.md +231 -212
  171. package/plugins/pbr/skills/pause/SKILL.md +249 -235
  172. package/plugins/pbr/skills/pause/templates/continue-here.md.tmpl +71 -71
  173. package/plugins/pbr/skills/plan/SKILL.md +685 -628
  174. package/plugins/pbr/skills/plan/decimal-phase-calc.md +98 -98
  175. package/plugins/pbr/skills/plan/templates/checker-prompt.md.tmpl +21 -21
  176. package/plugins/pbr/skills/plan/templates/gap-closure-prompt.md.tmpl +32 -32
  177. package/plugins/pbr/skills/plan/templates/planner-prompt.md.tmpl +38 -38
  178. package/plugins/pbr/skills/plan/templates/researcher-prompt.md.tmpl +19 -19
  179. package/plugins/pbr/skills/plan/templates/revision-prompt.md.tmpl +23 -23
  180. package/plugins/pbr/skills/quick/SKILL.md +354 -335
  181. package/plugins/pbr/skills/resume/SKILL.md +402 -388
  182. package/plugins/pbr/skills/review/SKILL.md +686 -652
  183. package/plugins/pbr/skills/review/templates/debugger-prompt.md.tmpl +60 -60
  184. package/plugins/pbr/skills/review/templates/gap-planner-prompt.md.tmpl +40 -40
  185. package/plugins/pbr/skills/review/templates/verifier-prompt.md.tmpl +115 -115
  186. package/plugins/pbr/skills/scan/SKILL.md +304 -269
  187. package/plugins/pbr/skills/scan/templates/mapper-prompt.md.tmpl +201 -201
  188. package/plugins/pbr/skills/setup/SKILL.md +253 -227
  189. package/plugins/pbr/skills/shared/commit-planning-docs.md +35 -35
  190. package/plugins/pbr/skills/shared/config-loading.md +102 -102
  191. package/plugins/pbr/skills/shared/context-budget.md +40 -40
  192. package/plugins/pbr/skills/shared/context-loader-task.md +86 -86
  193. package/plugins/pbr/skills/shared/digest-select.md +79 -79
  194. package/plugins/pbr/skills/shared/domain-probes.md +125 -125
  195. package/plugins/pbr/skills/shared/error-reporting.md +79 -79
  196. package/plugins/pbr/skills/shared/gate-prompts.md +388 -388
  197. package/plugins/pbr/skills/shared/phase-argument-parsing.md +45 -45
  198. package/plugins/pbr/skills/shared/progress-display.md +53 -53
  199. package/plugins/pbr/skills/shared/revision-loop.md +81 -81
  200. package/plugins/pbr/skills/shared/state-loading.md +62 -62
  201. package/plugins/pbr/skills/shared/state-update.md +161 -161
  202. package/plugins/pbr/skills/shared/universal-anti-patterns.md +33 -33
  203. package/plugins/pbr/skills/status/SKILL.md +367 -353
  204. package/plugins/pbr/skills/todo/SKILL.md +198 -181
  205. package/plugins/pbr/templates/CONTEXT.md.tmpl +52 -52
  206. package/plugins/pbr/templates/INTEGRATION-REPORT.md.tmpl +151 -151
  207. package/plugins/pbr/templates/RESEARCH-SUMMARY.md.tmpl +97 -97
  208. package/plugins/pbr/templates/ROADMAP.md.tmpl +40 -40
  209. package/plugins/pbr/templates/SUMMARY.md.tmpl +81 -81
  210. package/plugins/pbr/templates/VERIFICATION-DETAIL.md.tmpl +116 -116
  211. package/plugins/pbr/templates/codebase/ARCHITECTURE.md.tmpl +98 -98
  212. package/plugins/pbr/templates/codebase/CONCERNS.md.tmpl +93 -93
  213. package/plugins/pbr/templates/codebase/CONVENTIONS.md.tmpl +104 -104
  214. package/plugins/pbr/templates/codebase/INTEGRATIONS.md.tmpl +78 -78
  215. package/plugins/pbr/templates/codebase/STACK.md.tmpl +78 -78
  216. package/plugins/pbr/templates/codebase/STRUCTURE.md.tmpl +80 -80
  217. package/plugins/pbr/templates/codebase/TESTING.md.tmpl +107 -107
  218. package/plugins/pbr/templates/continue-here.md.tmpl +73 -73
  219. package/plugins/pbr/templates/prompt-partials/phase-project-context.md.tmpl +37 -37
  220. package/plugins/pbr/templates/research/ARCHITECTURE.md.tmpl +124 -124
  221. package/plugins/pbr/templates/research/STACK.md.tmpl +71 -71
  222. package/plugins/pbr/templates/research/SUMMARY.md.tmpl +112 -112
  223. package/plugins/pbr/templates/research-outputs/phase-research.md.tmpl +81 -81
  224. package/plugins/pbr/templates/research-outputs/project-research.md.tmpl +99 -99
  225. package/plugins/pbr/templates/research-outputs/synthesis.md.tmpl +36 -36
package/README.md CHANGED
@@ -1,247 +1,247 @@
1
- <p align="center">
2
- <img src="./assets/pbr_banner_logo.png" alt="Plan-Build-Run Logo" width="550" />
3
- </p>
4
-
5
- <p align="center">
6
- <strong>Context-engineered development workflow for Claude Code.</strong>
7
- <br />
8
- Build ambitious multi-phase software without quality degradation.
9
- <br />
10
- Works with any Claude Code plan. Shines on Max.
11
- <br />
12
- <br />
13
- <a href="#why-plan-build-run">Why Plan-Build-Run?</a> &bull;
14
- <a href="#getting-started">Getting Started</a> &bull;
15
- <a href="#commands">Commands</a> &bull;
16
- <a href="#how-it-works">How It Works</a> &bull;
17
- <a href="https://github.com/SienkLogic/plan-build-run/wiki">Wiki</a> &bull;
18
- <a href=".github/CONTRIBUTING.md">Contributing</a>
19
- </p>
20
-
21
- <p align="center">
22
- <a href="https://github.com/SienkLogic/plan-build-run/actions"><img src="https://img.shields.io/github/actions/workflow/status/SienkLogic/plan-build-run/ci.yml?style=for-the-badge&label=CI&logo=github" alt="CI Status" /></a>
23
- <img src="https://img.shields.io/badge/Claude_Code-Plugin-7C3AED?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code Plugin" />
24
- <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
25
- <a href="LICENSE"><img src="https://img.shields.io/github/license/SienkLogic/plan-build-run?style=for-the-badge" alt="License" /></a>
26
- <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a>
27
- <img src="https://img.shields.io/badge/Tests-780_passing-brightgreen?style=for-the-badge" alt="780 Tests" />
28
- </p>
29
-
30
- ---
31
-
32
- ## The Problem
33
-
34
- Claude Code is remarkably capable...until your context window fills up. As tokens accumulate during a long session, reasoning quality degrades, hallucinations increase, and the model starts losing track of earlier decisions. This is **context rot**, and it's the primary failure mode when building anything beyond a single-session project.
35
-
36
- **Plan-Build-Run solves this.** It keeps your main orchestrator under ~15% context usage by delegating heavy work to fresh subagent contexts, each getting a clean 200k token window. All state lives on disk. Sessions are killable at any second without data loss. Whether you're on a free tier or Max 5x, wasted context means wasted budget, and context rot is the biggest source of waste.
37
-
38
- ## Why Plan-Build-Run?
39
-
40
- Most AI coding tools treat context as infinite. They index your codebase, track your edits, and hope the model keeps up. That works for single-file changes. It falls apart when you're building something that takes days, spans dozens of files, and requires decisions made on Monday to still hold on Friday.
41
-
42
- Plan-Build-Run takes a different approach: **structured context isolation**. Instead of stuffing everything into one session, it delegates each operation to a fresh subagent with a clean 200k token window and coordinates through files on disk.
43
-
44
- <p align="center">
45
- <img src="./assets/pbr-demo.gif" alt="Plan-Build-Run workflow: begin → plan → build → review" width="800" />
46
- </p>
47
-
48
- Goal-backward verification, lifecycle hooks, wave-based parallelism, kill-safe state, and more. See **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart)** for the full comparison and differentiators.
49
-
50
- > **When to use Plan-Build-Run:** Multi-phase projects where quality matters. New features spanning 5+ files, large refactors, greenfield builds, anything that would take more than one Claude Code session to complete. Use `depth: quick` or `depth: standard` to control agent spawn count per phase.
51
- >
52
- > **When to skip it:** Single-file fixes, quick questions, one-off scripts. Use `/pbr:quick` for atomic commits without full workflow overhead: single executor spawn, no research or verification agents.
53
-
54
- Works on every Claude Code plan. Use `depth: quick` on Free/Pro, `depth: standard` on Max, `depth: comprehensive` on Max 5x. See **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart#plan-build-run-on-different-claude-code-plans)** for tier-specific guidance.
55
-
56
- ---
57
-
58
- ## Getting Started
59
-
60
- ### Prerequisites
61
-
62
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 2.1.45+ &nbsp;(`claude --version`)
63
- - Node.js 18+
64
-
65
- ### Install
66
-
67
- ```bash
68
- # From your terminal
69
- claude plugin marketplace add SienkLogic/plan-build-run
70
- claude plugin install pbr@plan-build-run
71
-
72
- # Or from inside a Claude Code session
73
- /plugin marketplace add SienkLogic/plan-build-run
74
- /plugin install pbr@plan-build-run
75
- ```
76
-
77
- All `/pbr:*` commands are now available globally.
78
-
79
- <details>
80
- <summary><strong>Install scopes</strong></summary>
81
-
82
- | Scope | Command | Effect |
83
- |-------|---------|--------|
84
- | **Global** (default) | `claude plugin install pbr@plan-build-run` | Available in all projects |
85
- | **Project only** | `claude plugin install pbr@plan-build-run --scope local` | This project only, gitignored |
86
- | **Team project** | `claude plugin install pbr@plan-build-run --scope project` | Shared via git, teammates get prompted |
87
-
88
- </details>
89
-
90
- ### Dashboard (Optional)
91
-
92
- Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser. To set it up:
93
-
94
- ```bash
95
- # One-time install of dashboard dependencies
96
- npm run dashboard:install
97
-
98
- # Launch the dashboard for any project with a .planning/ directory
99
- npm run dashboard -- --dir /path/to/your/project
100
- # Opens at http://127.0.0.1:3000
101
- ```
102
-
103
- Or run directly:
104
-
105
- ```bash
106
- node dashboard/bin/cli.js --dir /path/to/your/project --port 3000
107
- ```
108
-
109
- ### Quick Start (Max / Max 5x)
110
-
111
- Full pipeline with parallel research and multi-agent builds. Best experience.
112
-
113
- ```bash
114
- cd your-project && claude
115
- ```
116
- ```
117
- /pbr:begin # Plan-Build-Run asks about your project, researches the domain,
118
- # scopes requirements, and generates a phased roadmap
119
-
120
- /pbr:plan 1 # Research + plan the first phase
121
- /pbr:build 1 # Build it with parallel agents, atomic commits
122
- /pbr:review 1 # Verify the codebase matches requirements
123
- /pbr:plan 2 # Repeat for next phase
124
- ```
125
-
126
- That's the whole cycle. Everything lands in a `.planning/` directory. Kill your terminal anytime, `/pbr:resume` picks up where you left off.
127
-
128
- ### Quick Start (Pro / Free)
129
-
130
- Lighter workflow that still gives you structured state tracking and clean commits.
131
-
132
- ```bash
133
- cd your-project && claude
134
- ```
135
- ```
136
- /pbr:setup # Create .planning/ structure without the heavy research step
137
- /pbr:plan 1 --skip-research # Plan without spawning a research agent
138
- /pbr:build 1 # Build it
139
- /pbr:quick # For one-off tasks: single agent, atomic commit, lowest cost
140
- ```
141
-
142
- Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.
143
-
144
- ### Quick Reference
145
-
146
- | What you want | Command |
147
- |---------------|---------|
148
- | Start a new project | `/pbr:begin` (or `/pbr:setup` for lightweight init) |
149
- | Plan a phase | `/pbr:plan 1` |
150
- | Build a phase | `/pbr:build 1` |
151
- | Verify a phase | `/pbr:review 1` |
152
- | Do something quick | `/pbr:quick` |
153
- | See where you are | `/pbr:status` |
154
- | Resume after restart | `/pbr:resume` |
155
- | Auto-advance | `/pbr:continue` |
156
- | Change settings | `/pbr:config` |
157
-
158
- ---
159
-
160
- ## Commands
161
-
162
- ### Core Workflow
163
-
164
- | Command | Description | Agents |
165
- |---------|-------------|--------|
166
- | `/pbr:begin` | Start a new project: questioning, research, requirements, roadmap | 4-6 (quick: 2-3) |
167
- | `/pbr:plan <N>` | Plan a phase: research, plan creation, verification loop | 2-3 (quick: 1-2) |
168
- | `/pbr:build <N>` | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) |
169
- | `/pbr:review <N>` | Verify a phase: automated 3-layer checks + conversational UAT | 1 |
170
-
171
- See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 21 commands with flags, cost-by-depth tables, and detailed descriptions.
172
-
173
- ---
174
-
175
- ## How It Works
176
-
177
- Plan-Build-Run is a **thin orchestrator** that delegates heavy work to fresh subagent contexts via `Task()`. Data flows through files on disk, not through messages.
178
-
179
- ```
180
- Main Session (~15% context)
181
-
182
- ├── Task(researcher) ──▶ writes .planning/research/
183
- ├── Task(planner) ──▶ writes PLAN.md files
184
- ├── Task(executor) ──▶ builds code, creates commits
185
- ├── Task(executor) ──▶ (parallel, same wave)
186
- └── Task(verifier) ──▶ checks codebase against must-haves
187
- ```
188
-
189
- See **[Architecture](https://github.com/SienkLogic/plan-build-run/wiki/Architecture)** for key concepts, the token-saving CLI, data flow details, and supporting directories.
190
-
191
- ---
192
-
193
- ## Deep Dive
194
-
195
- | Topic | Description |
196
- |-------|-------------|
197
- | **[Agents](https://github.com/SienkLogic/plan-build-run/wiki/Agents)** | 10 specialized agents with configurable model profiles and file-based communication |
198
- | **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 12 config keys, depth/model profiles, 16+ feature toggles |
199
- | **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 15 lifecycle hooks that enforce discipline at zero token cost |
200
- | **[Project Structure](https://github.com/SienkLogic/plan-build-run/wiki/Project-Structure)** | The `.planning/` directory layout, key files, and file ownership |
201
- | **[Dashboard](https://github.com/SienkLogic/plan-build-run/wiki/Dashboard)** | Web UI with live updates for browsing project state |
202
- | **[Philosophy](https://github.com/SienkLogic/plan-build-run/wiki/Philosophy)** | Design principles and platform alignment strategy |
203
- | **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart)** | Feature comparison and key differentiators |
204
-
205
- ---
206
-
207
- ## Local Development
208
-
209
- ```bash
210
- # Clone and install
211
- git clone https://github.com/SienkLogic/plan-build-run.git
212
- cd plan-build-run
213
- npm install
214
-
215
- # Run tests (758 tests, 36 suites)
216
- npm test
217
-
218
- # Lint
219
- npm run lint
220
-
221
- # Validate plugin structure
222
- npm run validate
223
-
224
- # Load locally for manual testing
225
- claude --plugin-dir .
226
- ```
227
-
228
- CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
229
-
230
- ---
231
-
232
- ## Stats
233
-
234
- | Metric | Count |
235
- |--------|-------|
236
- | Skills (slash commands) | 21 |
237
- | Specialized agents | 10 |
238
- | Hook scripts | 28 |
239
- | Tests | 758 |
240
- | Test suites | 36 |
241
- | Config toggles | 12 top-level keys |
242
-
243
- ---
244
-
245
- ## License
246
-
247
- [MIT](LICENSE)
1
+ <p align="center">
2
+ <img src="./assets/pbr_banner_logo.png" alt="Plan-Build-Run Logo" width="550" />
3
+ </p>
4
+
5
+ <p align="center">
6
+ <strong>Context-engineered development workflow for Claude Code.</strong>
7
+ <br />
8
+ Build ambitious multi-phase software without quality degradation.
9
+ <br />
10
+ Works with any Claude Code plan. Shines on Max.
11
+ <br />
12
+ <br />
13
+ <a href="#why-plan-build-run">Why Plan-Build-Run?</a> &bull;
14
+ <a href="#getting-started">Getting Started</a> &bull;
15
+ <a href="#commands">Commands</a> &bull;
16
+ <a href="#how-it-works">How It Works</a> &bull;
17
+ <a href="https://github.com/SienkLogic/plan-build-run/wiki">Wiki</a> &bull;
18
+ <a href=".github/CONTRIBUTING.md">Contributing</a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <a href="https://github.com/SienkLogic/plan-build-run/actions"><img src="https://img.shields.io/github/actions/workflow/status/SienkLogic/plan-build-run/ci.yml?style=for-the-badge&label=CI&logo=github" alt="CI Status" /></a>
23
+ <img src="https://img.shields.io/badge/Claude_Code-Plugin-7C3AED?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code Plugin" />
24
+ <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
25
+ <a href="LICENSE"><img src="https://img.shields.io/github/license/SienkLogic/plan-build-run?style=for-the-badge" alt="License" /></a>
26
+ <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a>
27
+ <img src="https://img.shields.io/badge/Tests-780_passing-brightgreen?style=for-the-badge" alt="780 Tests" />
28
+ </p>
29
+
30
+ ---
31
+
32
+ ## The Problem
33
+
34
+ Claude Code is remarkably capable...until your context window fills up. As tokens accumulate during a long session, reasoning quality degrades, hallucinations increase, and the model starts losing track of earlier decisions. This is **context rot**, and it's the primary failure mode when building anything beyond a single-session project.
35
+
36
+ **Plan-Build-Run solves this.** It keeps your main orchestrator under ~15% context usage by delegating heavy work to fresh subagent contexts, each getting a clean 200k token window. All state lives on disk. Sessions are killable at any second without data loss. Whether you're on a free tier or Max 5x, wasted context means wasted budget, and context rot is the biggest source of waste.
37
+
38
+ ## Why Plan-Build-Run?
39
+
40
+ Most AI coding tools treat context as infinite. They index your codebase, track your edits, and hope the model keeps up. That works for single-file changes. It falls apart when you're building something that takes days, spans dozens of files, and requires decisions made on Monday to still hold on Friday.
41
+
42
+ Plan-Build-Run takes a different approach: **structured context isolation**. Instead of stuffing everything into one session, it delegates each operation to a fresh subagent with a clean 200k token window and coordinates through files on disk.
43
+
44
+ <p align="center">
45
+ <img src="./assets/pbr-demo.gif" alt="Plan-Build-Run workflow: begin → plan → build → review" width="800" />
46
+ </p>
47
+
48
+ Goal-backward verification, lifecycle hooks, wave-based parallelism, kill-safe state, and more. See **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart)** for the full comparison and differentiators.
49
+
50
+ > **When to use Plan-Build-Run:** Multi-phase projects where quality matters. New features spanning 5+ files, large refactors, greenfield builds, anything that would take more than one Claude Code session to complete. Use `depth: quick` or `depth: standard` to control agent spawn count per phase.
51
+ >
52
+ > **When to skip it:** Single-file fixes, quick questions, one-off scripts. Use `/pbr:quick` for atomic commits without full workflow overhead: single executor spawn, no research or verification agents.
53
+
54
+ Works on every Claude Code plan. Use `depth: quick` on Free/Pro, `depth: standard` on Max, `depth: comprehensive` on Max 5x. See **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart#plan-build-run-on-different-claude-code-plans)** for tier-specific guidance.
55
+
56
+ ---
57
+
58
+ ## Getting Started
59
+
60
+ ### Prerequisites
61
+
62
+ - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 2.1.45+ &nbsp;(`claude --version`)
63
+ - Node.js 18+
64
+
65
+ ### Install
66
+
67
+ ```bash
68
+ # From your terminal
69
+ claude plugin marketplace add SienkLogic/plan-build-run
70
+ claude plugin install pbr@plan-build-run
71
+
72
+ # Or from inside a Claude Code session
73
+ /plugin marketplace add SienkLogic/plan-build-run
74
+ /plugin install pbr@plan-build-run
75
+ ```
76
+
77
+ All `/pbr:*` commands are now available globally.
78
+
79
+ <details>
80
+ <summary><strong>Install scopes</strong></summary>
81
+
82
+ | Scope | Command | Effect |
83
+ |-------|---------|--------|
84
+ | **Global** (default) | `claude plugin install pbr@plan-build-run` | Available in all projects |
85
+ | **Project only** | `claude plugin install pbr@plan-build-run --scope local` | This project only, gitignored |
86
+ | **Team project** | `claude plugin install pbr@plan-build-run --scope project` | Shared via git, teammates get prompted |
87
+
88
+ </details>
89
+
90
+ ### Dashboard (Optional)
91
+
92
+ Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser. To set it up:
93
+
94
+ ```bash
95
+ # One-time install of dashboard dependencies
96
+ npm run dashboard:install
97
+
98
+ # Launch the dashboard for any project with a .planning/ directory
99
+ npm run dashboard -- --dir /path/to/your/project
100
+ # Opens at http://127.0.0.1:3000
101
+ ```
102
+
103
+ Or run directly:
104
+
105
+ ```bash
106
+ node dashboard/bin/cli.js --dir /path/to/your/project --port 3000
107
+ ```
108
+
109
+ ### Quick Start (Max / Max 5x)
110
+
111
+ Full pipeline with parallel research and multi-agent builds. Best experience.
112
+
113
+ ```bash
114
+ cd your-project && claude
115
+ ```
116
+ ```
117
+ /pbr:begin # Plan-Build-Run asks about your project, researches the domain,
118
+ # scopes requirements, and generates a phased roadmap
119
+
120
+ /pbr:plan 1 # Research + plan the first phase
121
+ /pbr:build 1 # Build it with parallel agents, atomic commits
122
+ /pbr:review 1 # Verify the codebase matches requirements
123
+ /pbr:plan 2 # Repeat for next phase
124
+ ```
125
+
126
+ That's the whole cycle. Everything lands in a `.planning/` directory. Kill your terminal anytime, `/pbr:resume` picks up where you left off.
127
+
128
+ ### Quick Start (Pro / Free)
129
+
130
+ Lighter workflow that still gives you structured state tracking and clean commits.
131
+
132
+ ```bash
133
+ cd your-project && claude
134
+ ```
135
+ ```
136
+ /pbr:setup # Create .planning/ structure without the heavy research step
137
+ /pbr:plan 1 --skip-research # Plan without spawning a research agent
138
+ /pbr:build 1 # Build it
139
+ /pbr:quick # For one-off tasks: single agent, atomic commit, lowest cost
140
+ ```
141
+
142
+ Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.
143
+
144
+ ### Quick Reference
145
+
146
+ | What you want | Command |
147
+ |---------------|---------|
148
+ | Start a new project | `/pbr:begin` (or `/pbr:setup` for lightweight init) |
149
+ | Plan a phase | `/pbr:plan 1` |
150
+ | Build a phase | `/pbr:build 1` |
151
+ | Verify a phase | `/pbr:review 1` |
152
+ | Do something quick | `/pbr:quick` |
153
+ | See where you are | `/pbr:status` |
154
+ | Resume after restart | `/pbr:resume` |
155
+ | Auto-advance | `/pbr:continue` |
156
+ | Change settings | `/pbr:config` |
157
+
158
+ ---
159
+
160
+ ## Commands
161
+
162
+ ### Core Workflow
163
+
164
+ | Command | Description | Agents |
165
+ |---------|-------------|--------|
166
+ | `/pbr:begin` | Start a new project: questioning, research, requirements, roadmap | 4-6 (quick: 2-3) |
167
+ | `/pbr:plan <N>` | Plan a phase: research, plan creation, verification loop | 2-3 (quick: 1-2) |
168
+ | `/pbr:build <N>` | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) |
169
+ | `/pbr:review <N>` | Verify a phase: automated 3-layer checks + conversational UAT | 1 |
170
+
171
+ See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 21 commands with flags, cost-by-depth tables, and detailed descriptions.
172
+
173
+ ---
174
+
175
+ ## How It Works
176
+
177
+ Plan-Build-Run is a **thin orchestrator** that delegates heavy work to fresh subagent contexts via `Task()`. Data flows through files on disk, not through messages.
178
+
179
+ ```
180
+ Main Session (~15% context)
181
+
182
+ ├── Task(researcher) ──▶ writes .planning/research/
183
+ ├── Task(planner) ──▶ writes PLAN.md files
184
+ ├── Task(executor) ──▶ builds code, creates commits
185
+ ├── Task(executor) ──▶ (parallel, same wave)
186
+ └── Task(verifier) ──▶ checks codebase against must-haves
187
+ ```
188
+
189
+ See **[Architecture](https://github.com/SienkLogic/plan-build-run/wiki/Architecture)** for key concepts, the token-saving CLI, data flow details, and supporting directories.
190
+
191
+ ---
192
+
193
+ ## Deep Dive
194
+
195
+ | Topic | Description |
196
+ |-------|-------------|
197
+ | **[Agents](https://github.com/SienkLogic/plan-build-run/wiki/Agents)** | 10 specialized agents with configurable model profiles and file-based communication |
198
+ | **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 12 config keys, depth/model profiles, 16+ feature toggles |
199
+ | **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 15 lifecycle hooks that enforce discipline at zero token cost |
200
+ | **[Project Structure](https://github.com/SienkLogic/plan-build-run/wiki/Project-Structure)** | The `.planning/` directory layout, key files, and file ownership |
201
+ | **[Dashboard](https://github.com/SienkLogic/plan-build-run/wiki/Dashboard)** | Web UI with live updates for browsing project state |
202
+ | **[Philosophy](https://github.com/SienkLogic/plan-build-run/wiki/Philosophy)** | Design principles and platform alignment strategy |
203
+ | **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart)** | Feature comparison and key differentiators |
204
+
205
+ ---
206
+
207
+ ## Local Development
208
+
209
+ ```bash
210
+ # Clone and install
211
+ git clone https://github.com/SienkLogic/plan-build-run.git
212
+ cd plan-build-run
213
+ npm install
214
+
215
+ # Run tests (758 tests, 36 suites)
216
+ npm test
217
+
218
+ # Lint
219
+ npm run lint
220
+
221
+ # Validate plugin structure
222
+ npm run validate
223
+
224
+ # Load locally for manual testing
225
+ claude --plugin-dir .
226
+ ```
227
+
228
+ CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
229
+
230
+ ---
231
+
232
+ ## Stats
233
+
234
+ | Metric | Count |
235
+ |--------|-------|
236
+ | Skills (slash commands) | 21 |
237
+ | Specialized agents | 10 |
238
+ | Hook scripts | 28 |
239
+ | Tests | 758 |
240
+ | Test suites | 36 |
241
+ | Config toggles | 12 top-level keys |
242
+
243
+ ---
244
+
245
+ ## License
246
+
247
+ [MIT](LICENSE)
@@ -1,25 +1,25 @@
1
- #!/usr/bin/env node
2
-
3
- import { Command } from 'commander';
4
- import { resolve } from 'path';
5
- import { startServer } from '../src/server.js';
6
-
7
- const program = new Command();
8
-
9
- program
10
- .name('pbr-dashboard')
11
- .description('Start the Plan-Build-Run planning dashboard')
12
- .option('-d, --dir <path>', 'Path to Plan-Build-Run project directory', process.cwd())
13
- .option('-p, --port <number>', 'Server port', '3000')
14
- .parse();
15
-
16
- const options = program.opts();
17
- const projectDir = resolve(options.dir);
18
- const port = parseInt(options.port, 10);
19
-
20
- if (isNaN(port) || port < 1 || port > 65535) {
21
- console.error(`Invalid port: ${options.port}`);
22
- process.exit(1);
23
- }
24
-
25
- startServer({ projectDir, port });
1
+ #!/usr/bin/env node
2
+
3
+ import { Command } from 'commander';
4
+ import { resolve } from 'path';
5
+ import { startServer } from '../src/server.js';
6
+
7
+ const program = new Command();
8
+
9
+ program
10
+ .name('pbr-dashboard')
11
+ .description('Start the Plan-Build-Run planning dashboard')
12
+ .option('-d, --dir <path>', 'Path to Plan-Build-Run project directory', process.cwd())
13
+ .option('-p, --port <number>', 'Server port', '3000')
14
+ .parse();
15
+
16
+ const options = program.opts();
17
+ const projectDir = resolve(options.dir);
18
+ const port = parseInt(options.port, 10);
19
+
20
+ if (isNaN(port) || port < 1 || port > 65535) {
21
+ console.error(`Invalid port: ${options.port}`);
22
+ process.exit(1);
23
+ }
24
+
25
+ startServer({ projectDir, port });
@@ -1,34 +1,34 @@
1
- {
2
- "name": "plan-build-run-dashboard",
3
- "version": "0.1.0",
4
- "description": "Web dashboard for viewing Plan-Build-Run project planning state",
5
- "type": "module",
6
- "bin": {
7
- "pbr-dashboard": "./bin/cli.js"
8
- },
9
- "scripts": {
10
- "start": "node bin/cli.js",
11
- "dev": "node --watch bin/cli.js",
12
- "test": "vitest run"
13
- },
14
- "keywords": [
15
- "plan-build-run",
16
- "dashboard",
17
- "planning"
18
- ],
19
- "license": "MIT",
20
- "dependencies": {
21
- "@rollup/rollup-win32-x64-msvc": "^4.57.1",
22
- "chokidar": "^5.0.0",
23
- "commander": "^12.1.0",
24
- "ejs": "^3.1.10",
25
- "express": "^5.1.0",
26
- "gray-matter": "^4.0.3",
27
- "helmet": "^8.1.0",
28
- "marked": "^17.0.1"
29
- },
30
- "devDependencies": {
31
- "memfs": "^4.56.10",
32
- "vitest": "^3.1.0"
33
- }
34
- }
1
+ {
2
+ "name": "plan-build-run-dashboard",
3
+ "version": "0.1.0",
4
+ "description": "Web dashboard for viewing Plan-Build-Run project planning state",
5
+ "type": "module",
6
+ "bin": {
7
+ "pbr-dashboard": "./bin/cli.js"
8
+ },
9
+ "scripts": {
10
+ "start": "node bin/cli.js",
11
+ "dev": "node --watch bin/cli.js",
12
+ "test": "vitest run"
13
+ },
14
+ "keywords": [
15
+ "plan-build-run",
16
+ "dashboard",
17
+ "planning"
18
+ ],
19
+ "license": "MIT",
20
+ "dependencies": {
21
+ "@rollup/rollup-win32-x64-msvc": "^4.57.1",
22
+ "chokidar": "^5.0.0",
23
+ "commander": "^12.1.0",
24
+ "ejs": "^3.1.10",
25
+ "express": "^5.1.0",
26
+ "gray-matter": "^4.0.3",
27
+ "helmet": "^8.1.0",
28
+ "marked": "^17.0.1"
29
+ },
30
+ "devDependencies": {
31
+ "memfs": "^4.56.10",
32
+ "vitest": "^3.1.0"
33
+ }
34
+ }