@sienklogic/plan-build-run 2.3.0 → 2.4.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 (151) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +54 -20
  3. package/dashboard/src/services/dashboard.service.js +24 -1
  4. package/dashboard/src/services/milestone.service.js +68 -17
  5. package/package.json +1 -1
  6. package/plugins/copilot-pbr/CHANGELOG.md +19 -0
  7. package/plugins/copilot-pbr/README.md +129 -0
  8. package/plugins/copilot-pbr/agents/codebase-mapper.agent.md +109 -0
  9. package/plugins/copilot-pbr/agents/debugger.agent.md +169 -0
  10. package/plugins/copilot-pbr/agents/executor.agent.md +237 -0
  11. package/plugins/copilot-pbr/agents/general.agent.md +88 -0
  12. package/plugins/copilot-pbr/agents/integration-checker.agent.md +88 -0
  13. package/plugins/copilot-pbr/agents/plan-checker.agent.md +199 -0
  14. package/plugins/copilot-pbr/agents/planner.agent.md +181 -0
  15. package/plugins/copilot-pbr/agents/researcher.agent.md +163 -0
  16. package/plugins/copilot-pbr/agents/synthesizer.agent.md +102 -0
  17. package/plugins/copilot-pbr/agents/verifier.agent.md +194 -0
  18. package/plugins/copilot-pbr/hooks/hooks.json +144 -0
  19. package/plugins/copilot-pbr/plugin.json +30 -0
  20. package/plugins/copilot-pbr/references/agent-anti-patterns.md +25 -0
  21. package/plugins/copilot-pbr/references/agent-interactions.md +135 -0
  22. package/plugins/copilot-pbr/references/agent-teams.md +55 -0
  23. package/plugins/copilot-pbr/references/checkpoints.md +158 -0
  24. package/plugins/copilot-pbr/references/common-bug-patterns.md +14 -0
  25. package/plugins/copilot-pbr/references/config-reference.md +442 -0
  26. package/plugins/copilot-pbr/references/continuation-format.md +213 -0
  27. package/plugins/copilot-pbr/references/deviation-rules.md +113 -0
  28. package/plugins/copilot-pbr/references/git-integration.md +227 -0
  29. package/plugins/copilot-pbr/references/integration-patterns.md +118 -0
  30. package/plugins/copilot-pbr/references/model-profiles.md +100 -0
  31. package/plugins/copilot-pbr/references/model-selection.md +32 -0
  32. package/plugins/copilot-pbr/references/pbr-rules.md +194 -0
  33. package/plugins/copilot-pbr/references/plan-authoring.md +182 -0
  34. package/plugins/copilot-pbr/references/plan-format.md +288 -0
  35. package/plugins/copilot-pbr/references/planning-config.md +214 -0
  36. package/plugins/copilot-pbr/references/questioning.md +215 -0
  37. package/plugins/copilot-pbr/references/reading-verification.md +128 -0
  38. package/plugins/copilot-pbr/references/stub-patterns.md +161 -0
  39. package/plugins/copilot-pbr/references/subagent-coordination.md +120 -0
  40. package/plugins/copilot-pbr/references/ui-formatting.md +462 -0
  41. package/plugins/copilot-pbr/references/verification-patterns.md +199 -0
  42. package/plugins/copilot-pbr/references/wave-execution.md +96 -0
  43. package/plugins/copilot-pbr/rules/pbr-workflow.mdc +48 -0
  44. package/plugins/copilot-pbr/setup.ps1 +93 -0
  45. package/plugins/copilot-pbr/setup.sh +92 -0
  46. package/plugins/copilot-pbr/skills/begin/SKILL.md +566 -0
  47. package/plugins/copilot-pbr/skills/begin/templates/PROJECT.md.tmpl +34 -0
  48. package/plugins/copilot-pbr/skills/begin/templates/REQUIREMENTS.md.tmpl +19 -0
  49. package/plugins/copilot-pbr/skills/begin/templates/STATE.md.tmpl +50 -0
  50. package/plugins/copilot-pbr/skills/begin/templates/config.json.tmpl +64 -0
  51. package/plugins/copilot-pbr/skills/begin/templates/researcher-prompt.md.tmpl +20 -0
  52. package/plugins/copilot-pbr/skills/begin/templates/roadmap-prompt.md.tmpl +31 -0
  53. package/plugins/copilot-pbr/skills/begin/templates/synthesis-prompt.md.tmpl +17 -0
  54. package/plugins/copilot-pbr/skills/build/SKILL.md +901 -0
  55. package/plugins/copilot-pbr/skills/config/SKILL.md +253 -0
  56. package/plugins/copilot-pbr/skills/continue/SKILL.md +159 -0
  57. package/plugins/copilot-pbr/skills/dashboard/SKILL.md +31 -0
  58. package/plugins/copilot-pbr/skills/debug/SKILL.md +511 -0
  59. package/plugins/copilot-pbr/skills/debug/templates/continuation-prompt.md.tmpl +17 -0
  60. package/plugins/copilot-pbr/skills/debug/templates/initial-investigation-prompt.md.tmpl +28 -0
  61. package/plugins/copilot-pbr/skills/discuss/SKILL.md +343 -0
  62. package/plugins/copilot-pbr/skills/discuss/templates/CONTEXT.md.tmpl +62 -0
  63. package/plugins/copilot-pbr/skills/discuss/templates/decision-categories.md +10 -0
  64. package/plugins/copilot-pbr/skills/do/SKILL.md +66 -0
  65. package/plugins/copilot-pbr/skills/explore/SKILL.md +374 -0
  66. package/plugins/copilot-pbr/skills/health/SKILL.md +218 -0
  67. package/plugins/copilot-pbr/skills/health/templates/check-pattern.md.tmpl +31 -0
  68. package/plugins/copilot-pbr/skills/health/templates/output-format.md.tmpl +64 -0
  69. package/plugins/copilot-pbr/skills/help/SKILL.md +152 -0
  70. package/plugins/copilot-pbr/skills/import/SKILL.md +498 -0
  71. package/plugins/copilot-pbr/skills/milestone/SKILL.md +703 -0
  72. package/plugins/copilot-pbr/skills/milestone/templates/audit-report.md.tmpl +49 -0
  73. package/plugins/copilot-pbr/skills/milestone/templates/stats-file.md.tmpl +31 -0
  74. package/plugins/copilot-pbr/skills/note/SKILL.md +227 -0
  75. package/plugins/copilot-pbr/skills/pause/SKILL.md +246 -0
  76. package/plugins/copilot-pbr/skills/pause/templates/continue-here.md.tmpl +72 -0
  77. package/plugins/copilot-pbr/skills/plan/SKILL.md +649 -0
  78. package/plugins/copilot-pbr/skills/plan/templates/checker-prompt.md.tmpl +22 -0
  79. package/plugins/copilot-pbr/skills/plan/templates/gap-closure-prompt.md.tmpl +33 -0
  80. package/plugins/copilot-pbr/skills/plan/templates/planner-prompt.md.tmpl +39 -0
  81. package/plugins/copilot-pbr/skills/plan/templates/researcher-prompt.md.tmpl +20 -0
  82. package/plugins/copilot-pbr/skills/plan/templates/revision-prompt.md.tmpl +24 -0
  83. package/plugins/copilot-pbr/skills/quick/SKILL.md +351 -0
  84. package/plugins/copilot-pbr/skills/resume/SKILL.md +399 -0
  85. package/plugins/copilot-pbr/skills/review/SKILL.md +648 -0
  86. package/plugins/copilot-pbr/skills/review/templates/debugger-prompt.md.tmpl +61 -0
  87. package/plugins/copilot-pbr/skills/review/templates/gap-planner-prompt.md.tmpl +41 -0
  88. package/plugins/copilot-pbr/skills/review/templates/verifier-prompt.md.tmpl +116 -0
  89. package/plugins/copilot-pbr/skills/scan/SKILL.md +301 -0
  90. package/plugins/copilot-pbr/skills/scan/templates/mapper-prompt.md.tmpl +202 -0
  91. package/plugins/copilot-pbr/skills/setup/SKILL.md +250 -0
  92. package/plugins/copilot-pbr/skills/shared/commit-planning-docs.md +36 -0
  93. package/plugins/copilot-pbr/skills/shared/config-loading.md +103 -0
  94. package/plugins/copilot-pbr/skills/shared/context-budget.md +41 -0
  95. package/plugins/copilot-pbr/skills/shared/context-loader-task.md +87 -0
  96. package/plugins/copilot-pbr/skills/shared/digest-select.md +80 -0
  97. package/plugins/copilot-pbr/skills/shared/domain-probes.md +126 -0
  98. package/plugins/copilot-pbr/skills/shared/error-reporting.md +80 -0
  99. package/plugins/copilot-pbr/skills/shared/gate-prompts.md +389 -0
  100. package/plugins/copilot-pbr/skills/shared/phase-argument-parsing.md +46 -0
  101. package/plugins/copilot-pbr/skills/shared/progress-display.md +54 -0
  102. package/plugins/copilot-pbr/skills/shared/revision-loop.md +82 -0
  103. package/plugins/copilot-pbr/skills/shared/state-loading.md +63 -0
  104. package/plugins/copilot-pbr/skills/shared/state-update.md +162 -0
  105. package/plugins/copilot-pbr/skills/shared/universal-anti-patterns.md +34 -0
  106. package/plugins/copilot-pbr/skills/status/SKILL.md +362 -0
  107. package/plugins/copilot-pbr/skills/todo/SKILL.md +256 -0
  108. package/plugins/copilot-pbr/templates/CONTEXT.md.tmpl +53 -0
  109. package/plugins/copilot-pbr/templates/INTEGRATION-REPORT.md.tmpl +152 -0
  110. package/plugins/copilot-pbr/templates/RESEARCH-SUMMARY.md.tmpl +98 -0
  111. package/plugins/copilot-pbr/templates/ROADMAP.md.tmpl +41 -0
  112. package/plugins/copilot-pbr/templates/SUMMARY.md.tmpl +82 -0
  113. package/plugins/copilot-pbr/templates/VERIFICATION-DETAIL.md.tmpl +117 -0
  114. package/plugins/copilot-pbr/templates/codebase/ARCHITECTURE.md.tmpl +98 -0
  115. package/plugins/copilot-pbr/templates/codebase/CONCERNS.md.tmpl +93 -0
  116. package/plugins/copilot-pbr/templates/codebase/CONVENTIONS.md.tmpl +104 -0
  117. package/plugins/copilot-pbr/templates/codebase/INTEGRATIONS.md.tmpl +78 -0
  118. package/plugins/copilot-pbr/templates/codebase/STACK.md.tmpl +78 -0
  119. package/plugins/copilot-pbr/templates/codebase/STRUCTURE.md.tmpl +80 -0
  120. package/plugins/copilot-pbr/templates/codebase/TESTING.md.tmpl +107 -0
  121. package/plugins/copilot-pbr/templates/continue-here.md.tmpl +74 -0
  122. package/plugins/copilot-pbr/templates/prompt-partials/phase-project-context.md.tmpl +38 -0
  123. package/plugins/copilot-pbr/templates/research/ARCHITECTURE.md.tmpl +124 -0
  124. package/plugins/copilot-pbr/templates/research/STACK.md.tmpl +71 -0
  125. package/plugins/copilot-pbr/templates/research/SUMMARY.md.tmpl +112 -0
  126. package/plugins/copilot-pbr/templates/research-outputs/phase-research.md.tmpl +81 -0
  127. package/plugins/copilot-pbr/templates/research-outputs/project-research.md.tmpl +99 -0
  128. package/plugins/copilot-pbr/templates/research-outputs/synthesis.md.tmpl +36 -0
  129. package/plugins/cursor-pbr/.cursor-plugin/plugin.json +13 -3
  130. package/plugins/cursor-pbr/skills/dashboard/SKILL.md +14 -4
  131. package/plugins/cursor-pbr/skills/do/SKILL.md +67 -0
  132. package/plugins/cursor-pbr/skills/milestone/SKILL.md +10 -7
  133. package/plugins/cursor-pbr/skills/todo/SKILL.md +28 -5
  134. package/plugins/cursor-pbr/templates/codebase/ARCHITECTURE.md.tmpl +98 -0
  135. package/plugins/cursor-pbr/templates/codebase/CONCERNS.md.tmpl +93 -0
  136. package/plugins/cursor-pbr/templates/codebase/CONVENTIONS.md.tmpl +104 -0
  137. package/plugins/cursor-pbr/templates/codebase/INTEGRATIONS.md.tmpl +78 -0
  138. package/plugins/cursor-pbr/templates/codebase/STACK.md.tmpl +78 -0
  139. package/plugins/cursor-pbr/templates/codebase/STRUCTURE.md.tmpl +80 -0
  140. package/plugins/cursor-pbr/templates/codebase/TESTING.md.tmpl +107 -0
  141. package/plugins/cursor-pbr/templates/research/ARCHITECTURE.md.tmpl +124 -0
  142. package/plugins/cursor-pbr/templates/research/STACK.md.tmpl +71 -0
  143. package/plugins/cursor-pbr/templates/research/SUMMARY.md.tmpl +112 -0
  144. package/plugins/cursor-pbr/templates/research-outputs/phase-research.md.tmpl +81 -0
  145. package/plugins/cursor-pbr/templates/research-outputs/project-research.md.tmpl +99 -0
  146. package/plugins/cursor-pbr/templates/research-outputs/synthesis.md.tmpl +36 -0
  147. package/plugins/pbr/.claude-plugin/plugin.json +7 -2
  148. package/plugins/pbr/scripts/validate-skill-args.js +54 -10
  149. package/plugins/pbr/skills/do/SKILL.md +70 -0
  150. package/plugins/pbr/skills/milestone/SKILL.md +10 -7
  151. package/plugins/pbr/skills/todo/SKILL.md +29 -6
@@ -0,0 +1,566 @@
1
+ ---
2
+ name: begin
3
+ description: "Start a new project. Deep questioning, research, requirements, and roadmap."
4
+ ---
5
+
6
+ # /pbr:begin — Project Initialization
7
+
8
+ You are the orchestrator for `/pbr:begin`. This skill initializes a new Plan-Build-Run project through deep questioning, optional research, requirements scoping, and roadmap generation. Your job is to stay lean — delegate heavy work to agents and keep the user's main context window clean.
9
+
10
+ ## Context Budget
11
+
12
+ Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
13
+
14
+ Additionally for this skill:
15
+ - **Minimize** reading agent output — read only summaries, not full research docs
16
+ - **Delegate** all analysis work to agents — the orchestrator routes, it doesn't analyze
17
+
18
+ ## Step 0 — Immediate Output
19
+
20
+ **Before ANY tool calls**, display this banner:
21
+
22
+ ```
23
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
24
+ PLAN-BUILD-RUN ► STARTING PROJECT
25
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
26
+ ```
27
+
28
+ Then proceed to Step 1.
29
+
30
+ ## Prerequisites
31
+
32
+ - Working directory should be the project root
33
+ - No existing `.planning/` directory (or user confirms overwrite)
34
+
35
+ ---
36
+
37
+ ## Orchestration Flow
38
+
39
+ Execute these steps in order. Each step specifies whether it runs inline (in your context) or is delegated to an agent.
40
+
41
+ ---
42
+
43
+ ### Step 1: Detect Brownfield (inline)
44
+
45
+ > **Cross-platform note**: Use the Glob tool (not Bash `ls` or `find`) for all file and directory discovery. Bash file commands fail on Windows due to path separator issues.
46
+
47
+ Check if the current directory has existing code:
48
+
49
+ ```
50
+ 1. Use Glob to check directory contents (e.g., pattern "*" at project root)
51
+ 2. Look for indicators of existing code:
52
+ - package.json, requirements.txt, CMakeLists.txt, go.mod, Cargo.toml
53
+ - src/, lib/, app/ directories
54
+ - .git/ directory with commits
55
+ 3. Use Glob to check if .planning/ already exists (e.g., pattern ".planning/*")
56
+ ```
57
+
58
+ **If existing code found:**
59
+ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
60
+ question: "This looks like an existing codebase. Run /pbr:scan to analyze what's here first?"
61
+ options:
62
+ - label: "Yes, scan" description: "Run /pbr:scan first to analyze existing code"
63
+ - label: "No, begin" description: "Proceed with /pbr:begin on top of existing code"
64
+ - If user selects "Yes, scan": suggest `/pbr:scan` and stop
65
+ - If user selects "No, begin": proceed to Step 2
66
+
67
+ **If `.planning/` already exists:**
68
+ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
69
+ question: "A .planning/ directory already exists. This will overwrite it. Continue?"
70
+ options:
71
+ - label: "Yes" description: "Overwrite existing planning directory"
72
+ - label: "No" description: "Cancel — keep existing planning"
73
+ - If user selects "No": **STOP IMMEDIATELY. Do not ask again. Do not proceed to Step 2. End the skill with this message:**
74
+ ```
75
+ Keeping existing .planning/ directory. Use `/pbr:status` to see current project state, or `/pbr:plan` to continue planning.
76
+ ```
77
+ **Do NOT re-prompt the same question or any other question. The skill is finished.**
78
+ - If user selects "Yes": proceed (existing directory will be overwritten during state initialization)
79
+
80
+ ---
81
+
82
+ ### Step 2: Deep Questioning (inline)
83
+
84
+ **Reference**: Read `references/questioning.md` for technique details.
85
+
86
+ Have a natural conversation to understand the user's vision. Do NOT present a form or checklist. Instead, have a flowing conversation that covers these areas organically:
87
+
88
+ **Required context to gather:**
89
+
90
+ 1. **What they want to build** — The core product/feature/system
91
+ 2. **Problem being solved** — Why does this need to exist? Who is it for?
92
+ 3. **Success criteria** — How will they know it works? What does "done" look like?
93
+ 4. **Existing constraints** — Technology choices already made, hosting, budget, timeline, team size
94
+ 5. **Key decisions already made** — Framework, language, architecture preferences
95
+ 6. **Edge cases and concerns** — What worries them? What's the hardest part?
96
+
97
+ **Conversation approach:**
98
+ - Start broad: "What are you building?"
99
+ - Go deeper on each answer: "What does that mean exactly?" "Show me an example."
100
+ - Surface assumptions: "Why do you assume that?" "Have you considered X?"
101
+ - Find edges: "What happens when...?" "What about...?"
102
+ - Reveal motivation: "Why does that matter?"
103
+ - Avoid leading questions — let the user define their vision
104
+
105
+ **Keep going until you have:**
106
+ - A clear, concrete understanding of what they want to build
107
+ - At least 3 specific success criteria
108
+ - Known constraints and decisions
109
+ - A sense of complexity and scope
110
+
111
+ **Anti-patterns:**
112
+ - DO NOT present a bulleted checklist and ask them to fill it in
113
+ - DO NOT ask all questions at once — have a conversation
114
+ - DO NOT assume technologies — let them tell you
115
+ - DO NOT rush — this is the foundation for everything that follows
116
+
117
+ ---
118
+
119
+ ### Step 3: Workflow Preferences (inline)
120
+
121
+ After understanding the project, configure the Plan-Build-Run workflow. Present preferences sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
122
+
123
+ **3a. Mode:**
124
+ Use the **toggle-confirm** pattern from `skills/shared/gate-prompts.md`:
125
+ question: "How do you want to work?"
126
+ header: "Mode"
127
+ options:
128
+ - label: "Interactive" description: "Pause at key gates for your approval (default)"
129
+ - label: "Autonomous" description: "Auto-proceed, only stop for critical decisions"
130
+ - `interactive` (default) — confirm at gates (roadmap, plans, transitions)
131
+ - `autonomous` — auto-proceed, only stop for critical decisions
132
+
133
+ **3b. Depth:**
134
+ Use the **depth-select** pattern from `skills/shared/gate-prompts.md`:
135
+ question: "How thorough should planning be?"
136
+ - `quick` — 3-5 phases, skip research, ~50% cheaper
137
+ - `standard` (default) — 5-8 phases, includes research
138
+ - `comprehensive` — 8-12 phases, full deep research, ~2x cost
139
+
140
+ **3c. Parallelization:**
141
+ Use the **toggle-confirm** pattern from `skills/shared/gate-prompts.md`:
142
+ question: "Run multiple agents in parallel when plans are independent?"
143
+ header: "Parallel"
144
+ options:
145
+ - label: "Enable" description: "Parallel execution of independent plans (default)"
146
+ - label: "Disable" description: "Sequential execution only"
147
+ - `enabled` (default) — parallel execution of independent plans
148
+ - `disabled` — sequential execution
149
+
150
+ **3d. Git Branching:**
151
+ Use the **git-strategy-select** pattern from `skills/shared/gate-prompts.md`:
152
+ question: "Git branching strategy?"
153
+ - `none` (default) — commit to current branch
154
+ - `phase` — create branch per phase
155
+ - `milestone` — create branch per milestone
156
+
157
+ **3e. Commit Planning Docs:**
158
+ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
159
+ question: "Should planning documents (.planning/ directory) be committed to git?"
160
+ options:
161
+ - label: "Yes" description: "Commit planning docs (default)"
162
+ - label: "No" description: "Add .planning/ to .gitignore"
163
+ - `yes` (default) — commit planning docs
164
+ - `no` — add .planning/ to .gitignore
165
+
166
+ **After gathering preferences:**
167
+
168
+ 1. Read the config template from `skills/begin/templates/config.json.tmpl`
169
+ 2. Apply the user's choices to the template
170
+ 3. Create `.planning/` directory
171
+ 4. Write `.planning/config.json` with the user's preferences
172
+
173
+ **IMPORTANT**: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
174
+
175
+ ---
176
+
177
+ ### Step 4: Research Decision (inline)
178
+
179
+ Based on the depth setting from Step 3, determine the research approach:
180
+
181
+ **Depth-to-Discovery mapping:**
182
+
183
+ | Depth | Discovery Level | Researchers | Topics |
184
+ |-------|----------------|-------------|--------|
185
+ | quick | Level 0 | 0 | Skip research entirely |
186
+ | standard | Level 1 | 2 | STACK.md, FEATURES.md |
187
+ | standard + brownfield | Level 2 | 2-3 | STACK.md, FEATURES.md, + codebase mapping |
188
+ | comprehensive | Level 3 | 4 | STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md |
189
+
190
+ **If depth is `quick`:**
191
+ - Skip to Step 7 (Requirements Scoping)
192
+ - Tell user: "Skipping research phase (depth: quick). Moving straight to requirements."
193
+
194
+ **If depth is `standard` or `comprehensive`:**
195
+ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
196
+ question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
197
+ options:
198
+ - label: "Yes" description: "Run research agents (recommended for standard/comprehensive)"
199
+ - label: "No" description: "Skip research, move straight to requirements"
200
+ - If user selects "No": skip to Step 7
201
+ - If user selects "Yes": proceed to Step 5
202
+
203
+ ---
204
+
205
+ ### Step 5: Research (delegated to agents)
206
+
207
+ Spawn parallel agents for research. Each researcher writes to `.planning/research/`.
208
+
209
+ **Create `.planning/research/` directory first.**
210
+
211
+ **For each research topic, invoke the @researcher agent:**
212
+
213
+ Invoke `@researcher` with the research prompt constructed from the template.
214
+
215
+ **NOTE**: The `@researcher` agent is defined in `agents/researcher.md`. Do NOT inline the agent definition — it wastes main context.
216
+
217
+ **Path resolution**: Before constructing any agent prompt, resolve plugin root to its absolute path. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
218
+
219
+ #### Researcher Prompt Template
220
+
221
+ For each researcher, construct the prompt by reading the template and filling in placeholders:
222
+
223
+ Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
224
+
225
+ **Placeholders to fill:**
226
+ - `{project name from questioning}` — project name gathered in Step 2
227
+ - `{2-3 sentence description from questioning}` — project description from Step 2
228
+ - `{any locked technology choices}` — technology constraints from Step 2
229
+ - `{budget, timeline, skill level, etc.}` — user constraints from Step 2
230
+ - `{topic}` — the research topic being assigned (e.g., "Technology Stack Analysis")
231
+ - `{TOPIC}` — the output filename (e.g., STACK, FEATURES, ARCHITECTURE, PITFALLS)
232
+ - `{topic-specific questions}` — see topic-specific questions below
233
+
234
+ **Topic-specific questions:**
235
+
236
+ **STACK.md** (Level 1+):
237
+ - What is the standard technology stack for this type of project?
238
+ - What are the current recommended versions?
239
+ - What are the key dependencies and their compatibility?
240
+ - What build tools and development workflow is standard?
241
+
242
+ **FEATURES.md** (Level 1+):
243
+ - How are similar features typically implemented in this stack?
244
+ - What libraries/packages are commonly used for each feature area?
245
+ - What are standard patterns for the key features described?
246
+ - What third-party integrations are typically needed?
247
+
248
+ **ARCHITECTURE.md** (Level 3 only):
249
+ - What is the recommended architecture for this type of project?
250
+ - How should the codebase be organized?
251
+ - What are the standard patterns for data flow, state management, etc.?
252
+ - How should components communicate?
253
+
254
+ **PITFALLS.md** (Level 3 only):
255
+ - What commonly goes wrong with this type of project?
256
+ - What are the most common mistakes developers make?
257
+ - What performance issues are typical?
258
+ - What security concerns exist?
259
+
260
+ **Parallelization:**
261
+ - Spawn ALL researchers in parallel when possible
262
+ - Before spawning, display to the user: `Spawning {N} researchers in parallel...`
263
+ - When each completes: "{topic} researcher complete ({duration})"
264
+ - When all complete: "All {N} researchers finished. Proceeding to synthesis."
265
+ - Wait for all to complete before proceeding
266
+
267
+ ---
268
+
269
+ ### Step 6: Synthesis (delegated to agent)
270
+
271
+ After all researchers complete, display to the user: `Spawning synthesizer...`
272
+
273
+ Invoke the `@synthesizer` agent with the synthesis prompt.
274
+
275
+ **NOTE**: The `@synthesizer` agent is defined in `agents/synthesizer.md`. Do NOT inline it.
276
+
277
+ **Path resolution**: Before constructing the agent prompt, resolve plugin root to its absolute path. Do not pass the variable literally in prompts.
278
+
279
+ #### Synthesis Prompt Template
280
+
281
+ Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
282
+
283
+ **Placeholders to fill:**
284
+ - `{List all .planning/research/*.md files that were created}` — list the research files produced in Step 5
285
+
286
+ **After the synthesizer completes**, display:
287
+ ```
288
+ Research synthesis complete — see .planning/research/SUMMARY.md
289
+ ```
290
+
291
+ ---
292
+
293
+ ### Step 7: Requirements Scoping (inline)
294
+
295
+ Present research findings (if any) and interactively scope requirements with the user.
296
+
297
+ **7a. Present findings:**
298
+ If research was done, read `.planning/research/SUMMARY.md` and present key findings:
299
+ - Recommended stack
300
+ - Key architectural decisions
301
+ - Notable pitfalls to be aware of
302
+
303
+ **7b. Feature identification:**
304
+ From the questioning session, list all features and capabilities discussed. Group them into categories.
305
+
306
+ Example categories: Auth, UI, API, Data, Infrastructure, Testing, etc.
307
+
308
+ **7c. Scope each category:**
309
+ For each category, present the features and ask the user to classify each:
310
+ - **v1 (committed)** — Will be built in this project
311
+ - **v2 (deferred)** — Will be built later, not now
312
+ - **Out of scope** — Will NOT be built
313
+
314
+ **7d. Assign REQ-IDs:**
315
+ For each committed requirement, assign an ID in the format `{CATEGORY}-{NN}`:
316
+ - `AUTH-01`: User can log in with Discord OAuth
317
+ - `AUTH-02`: Protected routes redirect to login
318
+ - `UI-01`: Dashboard shows player statistics
319
+ - `UI-02`: Mobile-responsive layout
320
+
321
+ Each requirement must be:
322
+ - **User-centric** — describes a capability from the user's perspective
323
+ - **Testable** — you can verify whether it's met or not
324
+ - **Specific** — not vague ("fast" is bad, "page loads in <2s" is good)
325
+
326
+ **7e. Write REQUIREMENTS.md:**
327
+ Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
328
+ - All v1 requirements grouped by category
329
+ - All v2 requirements with deferral reasons
330
+ - Out-of-scope items with rationale
331
+ - Traceability table (all REQ-IDs, no phases assigned yet)
332
+
333
+ ---
334
+
335
+ ### Step 8: Roadmap Generation (delegated to agent)
336
+
337
+ Display to the user: `Spawning planner (roadmap)...`
338
+
339
+ Invoke the `@planner` agent in roadmap mode with the roadmap prompt.
340
+
341
+ **NOTE**: The `@planner` agent is defined in `agents/planner.md`. Do NOT inline it. The planner agent will read REQUIREMENTS.md and SUMMARY.md from disk — you only need to tell it what to do and where files are.
342
+
343
+ **Path resolution**: Before constructing the agent prompt, resolve plugin root to its absolute path. Do not pass the variable literally in prompts.
344
+
345
+ #### Roadmap Prompt Template
346
+
347
+ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
348
+
349
+ **Placeholders to fill:**
350
+ - `{project name}` — project name from Step 2
351
+ - `{description}` — project description from Step 2
352
+ - `{quick|standard|comprehensive}` — depth setting from Step 3
353
+
354
+ **After the planner completes:**
355
+ - Read `.planning/ROADMAP.md`
356
+ - Count the phases and milestones from the roadmap content
357
+ - Display:
358
+ ```
359
+ Roadmap created — {N} phases across {M} milestones
360
+ ```
361
+ - If `gates.confirm_roadmap` is true in config, use the **approve-revise-abort** pattern from `skills/shared/gate-prompts.md`:
362
+ question: "Approve this roadmap?"
363
+ options:
364
+ - label: "Approve" description: "Proceed with this roadmap"
365
+ - label: "Request changes" description: "Discuss adjustments before proceeding"
366
+ - label: "Abort" description: "Cancel and start over"
367
+ - If user selects "Request changes": edit the roadmap inline (small changes) or re-invoke planner
368
+ - If user selects "Approve": proceed to Step 9
369
+ - If user selects "Abort": stop execution
370
+
371
+ ---
372
+
373
+ ### Step 9: State Initialization (inline)
374
+
375
+ Write the project state files from templates:
376
+
377
+ **9a. Write PROJECT.md:**
378
+ 1. Read `skills/begin/templates/PROJECT.md.tmpl`
379
+ 2. Fill in:
380
+ - `{project_name}` — from questioning
381
+ - `{2-3 sentences}` — project description from questioning
382
+ - `{ONE sentence}` — core value statement
383
+ - Out-of-scope features
384
+ - Technical context and constraints
385
+ - Initial key decisions from the questioning conversation
386
+ 3. Write to `.planning/PROJECT.md`
387
+ 4. Ensure the `## Milestones` section is filled in with the project name and phase count from the roadmap
388
+
389
+ **9b. Write STATE.md:**
390
+ 1. Read `skills/begin/templates/STATE.md.tmpl`
391
+ 2. Fill in:
392
+ - `{date}` — today's date
393
+ - `{total}` — total phase count from roadmap
394
+ - `{Phase 1 name}` — from roadmap
395
+ - Core value one-liner
396
+ - Decisions from initialization
397
+ 3. Write to `.planning/STATE.md`
398
+ 4. Fill in the `## Milestone` section with the project name and total phase count
399
+ 5. **STATE.md size limit**: Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
400
+
401
+ **9c. Write CONTEXT.md:**
402
+ Create `.planning/CONTEXT.md` from information gathered during questioning:
403
+
404
+ ```markdown
405
+ # Project Context
406
+
407
+ ## Locked Decisions
408
+ {Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE}
409
+
410
+ | Decision | Rationale | Locked By |
411
+ |----------|-----------|-----------|
412
+ | {e.g., "Use TypeScript"} | {User preference, team skill} | User |
413
+
414
+ ## User Constraints
415
+ {Budget, timeline, skill level, hosting, team size}
416
+
417
+ ## Deferred Ideas
418
+ {Features explicitly moved to v2 or out-of-scope}
419
+
420
+ | Idea | Reason Deferred |
421
+ |------|----------------|
422
+ | {feature} | {reason} |
423
+ ```
424
+
425
+ **9d. Write HISTORY.md:**
426
+ Create `.planning/HISTORY.md` with an initial entry:
427
+
428
+ ```markdown
429
+ # Project History
430
+
431
+ ## {date} — Project Created
432
+
433
+ - Initialized Plan-Build-Run project
434
+ - Depth: {depth}, Mode: {mode}
435
+ - Roadmap: {N} phases planned
436
+ ```
437
+
438
+ **9e. Create phase directories:**
439
+ For each phase in the roadmap, create the directory structure:
440
+ ```
441
+ .planning/phases/01-{slug}/
442
+ .planning/phases/02-{slug}/
443
+ ...
444
+ ```
445
+
446
+ Where `{slug}` is the phase name in kebab-case (e.g., `project-setup`, `authentication`).
447
+
448
+ ---
449
+
450
+ ### Step 10: Git Setup (inline)
451
+
452
+ Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
453
+
454
+ **10a. Gitignore:**
455
+ If `planning.commit_docs` is `false` in config:
456
+ - Add `.planning/` to `.gitignore`
457
+
458
+ If `planning.commit_docs` is `true`:
459
+ - Add `.planning/research/` to `.gitignore` (research is always excluded — it's reference material, not project state)
460
+
461
+ **10b. Initial commit (if desired):**
462
+ If `gates.confirm_project` is true in config:
463
+ - Present a summary of everything created:
464
+ - Project: {name}
465
+ - Core value: {one-liner}
466
+ - Phases: {count} phases in roadmap
467
+ - Requirements: {count} v1 requirements
468
+ - Config: depth={depth}, mode={mode}
469
+ - Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
470
+ question: "Everything look good? Commit the planning docs?"
471
+ options:
472
+ - label: "Yes" description: "Stage and commit .planning/ files"
473
+ - label: "No" description: "Let me review and adjust first"
474
+ - If user selects "Yes" and `planning.commit_docs` is true:
475
+ - Stage `.planning/` files (excluding research/ if gitignored)
476
+ - Commit: `chore: initialize plan-build-run project planning`
477
+ - If user selects "No": let user review and adjust
478
+
479
+ ---
480
+
481
+ ## Completion
482
+
483
+ After all steps complete, present the final summary:
484
+
485
+ Use the branded stage banner from `references/ui-formatting.md`:
486
+
487
+ ```
488
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
489
+ PLAN-BUILD-RUN ► PROJECT INITIALIZED
490
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
491
+
492
+ **{name}**
493
+
494
+ {core value one-liner}
495
+
496
+ Roadmap: {N} phases
497
+ 1. {Phase 1 name}
498
+ 2. {Phase 2 name}
499
+ ...
500
+
501
+ Requirements: {N} committed, {M} deferred, {K} out-of-scope
502
+ ```
503
+
504
+ Then use the "Next Up" routing block:
505
+ ```
506
+ ---
507
+
508
+ ## Next Up
509
+
510
+ **Phase 1: {Name}** — {one-line goal}
511
+
512
+ `/pbr:discuss 1`
513
+
514
+ `/clear` first for a fresh context window
515
+
516
+ ---
517
+
518
+ **Also available:**
519
+ - `/pbr:explore` — open-ended exploration before planning
520
+ - `/pbr:plan 1` — jump straight to planning Phase 1
521
+ - `/pbr:config` — adjust workflow settings
522
+
523
+ ---
524
+ ```
525
+
526
+ ---
527
+
528
+ ## Error Handling
529
+
530
+ ### Research agent fails
531
+ If a researcher agent fails or times out:
532
+ - Note which topic wasn't researched
533
+ - Continue with available research
534
+ - Display: "Research on {topic} failed. Proceeding without it. You can re-research during /pbr:plan."
535
+
536
+ ### User wants to restart
537
+ If user says they want to start over mid-flow:
538
+ - Confirm: "Start over from the beginning? Current progress will be lost."
539
+ - If yes: restart from Step 2
540
+
541
+ ### Config write fails
542
+ If `.planning/` directory can't be created, display:
543
+ ```
544
+ ERROR
545
+
546
+ Cannot create .planning/ directory.
547
+
548
+ **To fix:** Check directory permissions or specify an alternative path.
549
+ ```
550
+
551
+ ---
552
+
553
+ ## Files Created by /pbr:begin
554
+
555
+ | File | Purpose | When |
556
+ |------|---------|------|
557
+ | `.planning/config.json` | Workflow configuration | Step 3 |
558
+ | `.planning/research/*.md` | Research documents | Step 5 (if research enabled) |
559
+ | `.planning/research/SUMMARY.md` | Research synthesis | Step 6 (if research enabled) |
560
+ | `.planning/REQUIREMENTS.md` | Scoped requirements | Step 7 |
561
+ | `.planning/ROADMAP.md` | Phase roadmap | Step 8 |
562
+ | `.planning/PROJECT.md` | Project overview | Step 9 |
563
+ | `.planning/STATE.md` | Current state tracker | Step 9 |
564
+ | `.planning/CONTEXT.md` | Decisions and constraints | Step 9 |
565
+ | `.planning/HISTORY.md` | Project history log | Step 9 |
566
+ | `.planning/phases/NN-*/` | Phase directories | Step 9 |
@@ -0,0 +1,34 @@
1
+ <\!-- canonical: ../../../../pbr/skills/begin/templates/PROJECT.md.tmpl -->
2
+ # {project_name}
3
+
4
+ ## What This Is
5
+ {2-3 sentences: current, accurate description}
6
+
7
+ ## Core Value
8
+ {ONE sentence: the thing that matters most}
9
+
10
+ ## Requirements
11
+ ### Active (current scope)
12
+ See: .planning/REQUIREMENTS.md
13
+
14
+ ### Out of Scope
15
+ {Features explicitly excluded and why}
16
+
17
+ ## Context
18
+ {Technical environment, prior work, constraints}
19
+
20
+ ## Constraints
21
+ {Known constraints with rationale}
22
+
23
+ ## Key Decisions
24
+ | Decision | Rationale | Outcome |
25
+ |----------|-----------|---------|
26
+ | {initial decisions from questioning} | {why} | -- Pending |
27
+
28
+ ## Milestones
29
+
30
+ ### Active
31
+ - **{project_name} v1.0** -- Phases 1-{total} -- In progress
32
+
33
+ ### Completed
34
+ (none yet)
@@ -0,0 +1,19 @@
1
+ <\!-- canonical: ../../../../pbr/skills/begin/templates/REQUIREMENTS.md.tmpl -->
2
+ # Requirements: {project_name}
3
+
4
+ ## v1 Requirements (committed scope)
5
+
6
+ ### {Category}
7
+ - [ ] **{CAT}-01**: {User-centric, testable requirement}
8
+
9
+ ## v2 Requirements (deferred)
10
+ - **{CAT}-01**: {Deferred requirement with reason}
11
+
12
+ ## Out of Scope
13
+ | Feature | Reason |
14
+ |---------|--------|
15
+
16
+ ## Traceability
17
+ | Requirement | Phase | Status |
18
+ |-------------|-------|--------|
19
+ | {REQ-ID} | -- | Pending |
@@ -0,0 +1,50 @@
1
+ <\!-- canonical: ../../../../pbr/skills/begin/templates/STATE.md.tmpl -->
2
+ ---
3
+ version: 2
4
+ current_phase: 1
5
+ total_phases: {total}
6
+ phase_slug: "{phase_1_slug}"
7
+ phase_name: "{Phase 1 name}"
8
+ status: "ready_to_plan"
9
+ progress_percent: 0
10
+ plans_total: 0
11
+ plans_complete: 0
12
+ last_activity: "{date}"
13
+ last_command: "/pbr:begin"
14
+ blockers: []
15
+ active_checkpoint: null
16
+ ---
17
+ # Project State
18
+
19
+ ## Project Reference
20
+ See: .planning/PROJECT.md (updated {date})
21
+ **Core value:** {One-liner}
22
+ **Current focus:** Phase 1 - {name}
23
+
24
+ ## Current Position
25
+ Phase: 1 of {total} ({Phase 1 name})
26
+ Plan: 0 of 0 in current phase
27
+ Status: Ready to plan
28
+ Last activity: {date} -- Project initialized
29
+ Progress: [░░░░░░░░░░░░░░░░░░░░] 0%
30
+
31
+ ## Accumulated Context
32
+
33
+ ### Decisions
34
+ {Decisions from initialization}
35
+
36
+ ### Pending Todos
37
+ None yet
38
+
39
+ ### Blockers/Concerns
40
+ None yet
41
+
42
+ ## Milestone
43
+ Current: {project_name} v1.0
44
+ Phases: 1-{total}
45
+ Status: In progress
46
+
47
+ ## Session Continuity
48
+ Last session: {timestamp}
49
+ Stopped at: Project initialization complete
50
+ Resume file: None