pan-wizard 3.33.0 → 3.35.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 (214) hide show
  1. package/README.md +29 -26
  2. package/agents/pan-conductor.md +18 -17
  3. package/agents/pan-counterfactual.md +2 -2
  4. package/agents/pan-debugger.md +30 -9
  5. package/agents/pan-design-checker.md +2 -1
  6. package/agents/pan-designer.md +2 -2
  7. package/agents/pan-distiller.md +3 -3
  8. package/agents/pan-document_code.md +14 -14
  9. package/agents/pan-executor.md +30 -9
  10. package/agents/pan-experiment-runner.md +9 -8
  11. package/agents/pan-hardener.md +1 -1
  12. package/agents/pan-integration-checker.md +2 -2
  13. package/agents/pan-knowledge.md +1 -1
  14. package/agents/pan-meta-reviewer.md +4 -4
  15. package/agents/pan-optimizer.md +39 -43
  16. package/agents/pan-phase-researcher.md +10 -10
  17. package/agents/pan-plan-checker.md +37 -34
  18. package/agents/pan-planner.md +57 -44
  19. package/agents/pan-previewer.md +1 -1
  20. package/agents/pan-project-researcher.md +12 -12
  21. package/agents/pan-release.md +1 -1
  22. package/agents/pan-research-synthesizer.md +3 -3
  23. package/agents/pan-reviewer.md +26 -3
  24. package/agents/pan-roadmapper.md +15 -14
  25. package/agents/pan-verifier.md +33 -25
  26. package/bin/install-lib.cjs +176 -38
  27. package/bin/install.js +81 -63
  28. package/commands/pan/army.md +15 -11
  29. package/commands/pan/assumptions.md +2 -2
  30. package/commands/pan/audit-deployment.md +11 -12
  31. package/commands/pan/cost.md +8 -8
  32. package/commands/pan/dashboard.md +0 -3
  33. package/commands/pan/debug.md +10 -7
  34. package/commands/pan/design-phase.md +5 -5
  35. package/commands/pan/discuss-phase.md +2 -0
  36. package/commands/pan/exec-phase.md +21 -37
  37. package/commands/pan/experiment.md +9 -8
  38. package/commands/pan/focus-auto.md +22 -20
  39. package/commands/pan/focus-design.md +7 -6
  40. package/commands/pan/focus-doc-audit.md +4 -3
  41. package/commands/pan/focus-drift-walking.md +4 -3
  42. package/commands/pan/focus-exec.md +6 -6
  43. package/commands/pan/focus-plan.md +12 -11
  44. package/commands/pan/focus-scan.md +5 -3
  45. package/commands/pan/focus-sync.md +3 -2
  46. package/commands/pan/git.md +8 -8
  47. package/commands/pan/health.md +2 -2
  48. package/commands/pan/hud.md +4 -7
  49. package/commands/pan/hygiene.md +14 -7
  50. package/commands/pan/knowledge.md +9 -10
  51. package/commands/pan/learn.md +10 -7
  52. package/commands/pan/links.md +4 -1
  53. package/commands/pan/map-codebase.md +1 -1
  54. package/commands/pan/mcp-bridge.md +19 -21
  55. package/commands/pan/milestone-done.md +6 -3
  56. package/commands/pan/milestone-new.md +1 -1
  57. package/commands/pan/new-project.md +10 -10
  58. package/commands/pan/optimize.md +18 -14
  59. package/commands/pan/patches.md +2 -6
  60. package/commands/pan/pause.md +1 -1
  61. package/commands/pan/phase-tests.md +3 -2
  62. package/commands/pan/plan-phase.md +9 -19
  63. package/commands/pan/preview.md +2 -3
  64. package/commands/pan/profile.md +2 -2
  65. package/commands/pan/quick.md +1 -1
  66. package/commands/pan/remove-phase.md +1 -1
  67. package/commands/pan/report.md +3 -7
  68. package/commands/pan/research-phase.md +16 -15
  69. package/commands/pan/resume.md +9 -11
  70. package/commands/pan/retro.md +5 -3
  71. package/commands/pan/review-deep.md +7 -9
  72. package/commands/pan/settings.md +1 -1
  73. package/commands/pan/verify-phase.md +0 -11
  74. package/commands/pan/what-if.md +3 -4
  75. package/hooks/dist/pan-context-monitor.js +352 -44
  76. package/hooks/dist/pan-cost-logger.js +30 -0
  77. package/hooks/dist/pan-guard.js +244 -0
  78. package/hooks/dist/pan-statusline.js +73 -24
  79. package/hooks/dist/pan-stop-guard.js +7 -2
  80. package/package.json +1 -1
  81. package/pan-wizard-core/bin/lib/agents-md.cjs +44 -6
  82. package/pan-wizard-core/bin/lib/bridge.cjs +6 -5
  83. package/pan-wizard-core/bin/lib/campaign.cjs +4 -2
  84. package/pan-wizard-core/bin/lib/commands-learnings.cjs +19 -2
  85. package/pan-wizard-core/bin/lib/commands.cjs +57 -6
  86. package/pan-wizard-core/bin/lib/config.cjs +7 -1
  87. package/pan-wizard-core/bin/lib/constants.cjs +18 -6
  88. package/pan-wizard-core/bin/lib/context-budget.cjs +12 -9
  89. package/pan-wizard-core/bin/lib/core.cjs +53 -19
  90. package/pan-wizard-core/bin/lib/cost-rebuild.cjs +13 -1
  91. package/pan-wizard-core/bin/lib/cost.cjs +142 -13
  92. package/pan-wizard-core/bin/lib/distill.cjs +6 -3
  93. package/pan-wizard-core/bin/lib/doc-lint.cjs +30 -11
  94. package/pan-wizard-core/bin/lib/findings.cjs +135 -21
  95. package/pan-wizard-core/bin/lib/focus.cjs +13 -4
  96. package/pan-wizard-core/bin/lib/frontmatter.cjs +105 -26
  97. package/pan-wizard-core/bin/lib/hygiene.cjs +184 -17
  98. package/pan-wizard-core/bin/lib/init.cjs +13 -4
  99. package/pan-wizard-core/bin/lib/knowledge.cjs +17 -1
  100. package/pan-wizard-core/bin/lib/learn-index.cjs +111 -10
  101. package/pan-wizard-core/bin/lib/learn-lint.cjs +30 -3
  102. package/pan-wizard-core/bin/lib/memory-optimize.cjs +8 -4
  103. package/pan-wizard-core/bin/lib/memory.cjs +508 -54
  104. package/pan-wizard-core/bin/lib/milestone.cjs +8 -3
  105. package/pan-wizard-core/bin/lib/optimize.cjs +97 -17
  106. package/pan-wizard-core/bin/lib/phase-gate.cjs +174 -0
  107. package/pan-wizard-core/bin/lib/phase-remove.cjs +85 -21
  108. package/pan-wizard-core/bin/lib/phase-report.cjs +8 -2
  109. package/pan-wizard-core/bin/lib/phase.cjs +39 -13
  110. package/pan-wizard-core/bin/lib/preview.cjs +34 -31
  111. package/pan-wizard-core/bin/lib/roadmap-compact.cjs +267 -0
  112. package/pan-wizard-core/bin/lib/roadmap.cjs +243 -9
  113. package/pan-wizard-core/bin/lib/runner.cjs +2 -1
  114. package/pan-wizard-core/bin/lib/state-compact.cjs +11 -6
  115. package/pan-wizard-core/bin/lib/state.cjs +43 -28
  116. package/pan-wizard-core/bin/lib/template.cjs +11 -4
  117. package/pan-wizard-core/bin/lib/verdict.cjs +140 -10
  118. package/pan-wizard-core/bin/lib/verify-integrity.cjs +181 -0
  119. package/pan-wizard-core/bin/lib/verify-plan-set.cjs +230 -0
  120. package/pan-wizard-core/bin/lib/verify-preflight.cjs +4 -13
  121. package/pan-wizard-core/bin/lib/verify-retro.cjs +5 -3
  122. package/pan-wizard-core/bin/lib/verify-scope.cjs +11 -7
  123. package/pan-wizard-core/bin/lib/verify.cjs +30 -28
  124. package/pan-wizard-core/bin/lib/whatif.cjs +53 -9
  125. package/pan-wizard-core/bin/pan-tools.cjs +114 -19
  126. package/pan-wizard-core/learnings/index.json +5 -5
  127. package/pan-wizard-core/mcp/merge-gate.cjs +14 -3
  128. package/pan-wizard-core/mcp/native-tools.cjs +3 -3
  129. package/pan-wizard-core/opencode/pan-wizard.js +139 -0
  130. package/pan-wizard-core/references/checkpoints.md +3 -3
  131. package/pan-wizard-core/references/continuation-format.md +3 -3
  132. package/pan-wizard-core/references/decimal-phase-calculation.md +2 -3
  133. package/pan-wizard-core/references/design-methodology.md +1 -1
  134. package/pan-wizard-core/references/git-integration.md +4 -6
  135. package/pan-wizard-core/references/git-planning-commit.md +2 -2
  136. package/pan-wizard-core/references/guardrails.md +2 -2
  137. package/pan-wizard-core/references/handoff-decisions.md +3 -3
  138. package/pan-wizard-core/references/model-profile-resolution.md +5 -5
  139. package/pan-wizard-core/references/model-profiles.md +15 -10
  140. package/pan-wizard-core/references/phase-argument-parsing.md +7 -7
  141. package/pan-wizard-core/references/planning-config.md +7 -7
  142. package/pan-wizard-core/references/tdd.md +10 -1
  143. package/pan-wizard-core/references/verdict-contract.md +6 -1
  144. package/pan-wizard-core/references/verification-patterns.md +5 -5
  145. package/pan-wizard-core/templates/codebase/architecture.md +2 -2
  146. package/pan-wizard-core/templates/codebase/best-practices.md +2 -2
  147. package/pan-wizard-core/templates/codebase/concerns.md +3 -3
  148. package/pan-wizard-core/templates/codebase/integrations.md +6 -6
  149. package/pan-wizard-core/templates/codebase/relationships.md +2 -2
  150. package/pan-wizard-core/templates/codebase/stack.md +2 -2
  151. package/pan-wizard-core/templates/codebase/structure.md +4 -4
  152. package/pan-wizard-core/templates/codebase/testing.md +4 -4
  153. package/pan-wizard-core/templates/config.json +2 -6
  154. package/pan-wizard-core/templates/continue-here.md +1 -1
  155. package/pan-wizard-core/templates/debug-subagent-prompt.md +5 -3
  156. package/pan-wizard-core/templates/debug.md +15 -1
  157. package/pan-wizard-core/templates/milestone-archive.md +6 -6
  158. package/pan-wizard-core/templates/milestone.md +1 -1
  159. package/pan-wizard-core/templates/phase-prompt.md +31 -17
  160. package/pan-wizard-core/templates/planner-subagent-prompt.md +5 -5
  161. package/pan-wizard-core/templates/preview-report.md +1 -1
  162. package/pan-wizard-core/templates/research-project/architecture.md +3 -3
  163. package/pan-wizard-core/templates/research-project/features.md +1 -1
  164. package/pan-wizard-core/templates/research-project/pitfalls.md +1 -1
  165. package/pan-wizard-core/templates/research-project/stack.md +3 -3
  166. package/pan-wizard-core/templates/research.md +5 -5
  167. package/pan-wizard-core/templates/retrospective.md +1 -1
  168. package/pan-wizard-core/templates/roadmap.md +15 -15
  169. package/pan-wizard-core/templates/state.md +4 -4
  170. package/pan-wizard-core/templates/summary-complex.md +1 -0
  171. package/pan-wizard-core/templates/summary-minimal.md +1 -0
  172. package/pan-wizard-core/templates/summary-standard.md +2 -1
  173. package/pan-wizard-core/templates/summary.md +18 -2
  174. package/pan-wizard-core/templates/uat.md +3 -3
  175. package/pan-wizard-core/templates/user-setup.md +8 -8
  176. package/pan-wizard-core/templates/verification-report.md +53 -8
  177. package/pan-wizard-core/workflows/add-phase.md +1 -1
  178. package/pan-wizard-core/workflows/assumptions.md +1 -1
  179. package/pan-wizard-core/workflows/diagnose-issues.md +4 -4
  180. package/pan-wizard-core/workflows/discuss-phase.md +10 -8
  181. package/pan-wizard-core/workflows/exec-phase.md +75 -95
  182. package/pan-wizard-core/workflows/execute-plan.md +8 -7
  183. package/pan-wizard-core/workflows/health.md +13 -12
  184. package/pan-wizard-core/workflows/help.md +8 -9
  185. package/pan-wizard-core/workflows/learn.md +13 -11
  186. package/pan-wizard-core/workflows/map-codebase.md +10 -10
  187. package/pan-wizard-core/workflows/milestone-audit.md +10 -10
  188. package/pan-wizard-core/workflows/milestone-gaps.md +18 -25
  189. package/pan-wizard-core/workflows/milestone-new.md +7 -6
  190. package/pan-wizard-core/workflows/new-project.md +17 -25
  191. package/pan-wizard-core/workflows/optimize.md +11 -9
  192. package/pan-wizard-core/workflows/pause.md +6 -1
  193. package/pan-wizard-core/workflows/phase-tests.md +4 -4
  194. package/pan-wizard-core/workflows/plan-phase.md +53 -42
  195. package/pan-wizard-core/workflows/profile.md +2 -2
  196. package/pan-wizard-core/workflows/progress.md +6 -8
  197. package/pan-wizard-core/workflows/quick.md +7 -5
  198. package/pan-wizard-core/workflows/remove-phase.md +1 -1
  199. package/pan-wizard-core/workflows/research-phase.md +9 -5
  200. package/pan-wizard-core/workflows/resume-project.md +4 -6
  201. package/pan-wizard-core/workflows/retro.md +3 -1
  202. package/pan-wizard-core/workflows/settings.md +16 -24
  203. package/pan-wizard-core/workflows/todo-check.md +4 -3
  204. package/pan-wizard-core/workflows/transition.md +16 -12
  205. package/pan-wizard-core/workflows/update.md +25 -17
  206. package/pan-wizard-core/workflows/verify-phase.md +22 -20
  207. package/pan-zcode/KNOWN-BETA-RISKS.md +2 -2
  208. package/pan-zcode/README.md +7 -7
  209. package/pan-zcode/bin/install-zcode.js +1 -1
  210. package/scripts/build-hooks.js +1 -0
  211. package/scripts/build-plugin.js +3 -1
  212. package/scripts/generate-skills-docs.py +15 -6
  213. package/scripts/prompt-lint.cjs +167 -0
  214. package/scripts/test-surface.cjs +1 -0
@@ -8,7 +8,7 @@ Template for `.planning/codebase/concerns.md` - captures known issues and areas
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # Codebase Concerns
13
13
 
14
14
  **Analysis Date:** [YYYY-MM-DD]
@@ -132,7 +132,7 @@ quadrantChart
132
132
 
133
133
  *Concerns audit: [date]*
134
134
  *Update as issues are fixed or new ones discovered*
135
- ```
135
+ ~~~
136
136
 
137
137
  <good_examples>
138
138
  ```markdown
@@ -321,5 +321,5 @@ quadrantChart
321
321
  - Planning refactoring work
322
322
 
323
323
  **How this gets populated:**
324
- Explore agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list.
324
+ The `pan-document_code` mapper agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list.
325
325
  </guidelines>
@@ -8,7 +8,7 @@ Template for `.planning/codebase/integrations.md` - captures external service de
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # External Integrations
13
13
 
14
14
  **Analysis Date:** [YYYY-MM-DD]
@@ -149,7 +149,7 @@ erDiagram
149
149
 
150
150
  *Integration audit: [date]*
151
151
  *Update when adding/removing external services*
152
- ```
152
+ ~~~
153
153
 
154
154
  <good_examples>
155
155
  ```markdown
@@ -279,10 +279,10 @@ erDiagram
279
279
 
280
280
  **What does NOT belong here:**
281
281
  - Actual API keys or secrets (NEVER write these)
282
- - Internal architecture (that's ARCHITECTURE.md)
283
- - Code patterns (that's PATTERNS.md)
284
- - Technology choices (that's STACK.md)
285
- - Performance issues (that's CONCERNS.md)
282
+ - Internal architecture (that's architecture.md)
283
+ - Code patterns (that's conventions.md)
284
+ - Technology choices (that's stack.md)
285
+ - Performance issues (that's concerns.md)
286
286
 
287
287
  **When filling this template:**
288
288
  - Check .env.example or .env.template for required env vars
@@ -8,7 +8,7 @@ Template for `.planning/codebase/relationships.md` - maps module dependencies an
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # Module Relationships
13
13
 
14
14
  **Analysis Date:** [YYYY-MM-DD]
@@ -90,7 +90,7 @@ Imports that cross architectural boundaries:
90
90
 
91
91
  *Relationship analysis: [date]*
92
92
  *Update when module structure changes*
93
- ```
93
+ ~~~
94
94
 
95
95
  <guidelines>
96
96
  **What belongs in relationships.md:**
@@ -8,7 +8,7 @@ Template for `.planning/codebase/stack.md` - captures the technology foundation.
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # Technology Stack
13
13
 
14
14
  **Analysis Date:** [YYYY-MM-DD]
@@ -92,7 +92,7 @@ graph TD
92
92
 
93
93
  *Stack analysis: [date]*
94
94
  *Update after major dependency changes*
95
- ```
95
+ ~~~
96
96
 
97
97
  <good_examples>
98
98
  ```markdown
@@ -8,7 +8,7 @@ Template for `.planning/codebase/structure.md` - captures physical file organiza
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # Codebase Structure
13
13
 
14
14
  **Analysis Date:** [YYYY-MM-DD]
@@ -125,10 +125,10 @@ graph TD
125
125
 
126
126
  *Structure analysis: [date]*
127
127
  *Update when directory structure changes*
128
- ```
128
+ ~~~
129
129
 
130
130
  <good_examples>
131
- ```markdown
131
+ ~~~markdown
132
132
  # Codebase Structure
133
133
 
134
134
  **Analysis Date:** 2025-01-20
@@ -255,7 +255,7 @@ pan-wizard-core/
255
255
 
256
256
  *Structure analysis: 2025-01-20*
257
257
  *Update when directory structure changes*
258
- ```
258
+ ~~~
259
259
  </good_examples>
260
260
 
261
261
  <guidelines>
@@ -8,7 +8,7 @@ Template for `.planning/codebase/testing.md` - captures test framework and patte
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # Testing Patterns
13
13
 
14
14
  **Analysis Date:** [YYYY-MM-DD]
@@ -207,10 +207,10 @@ it('should reject on failure', async () => {
207
207
 
208
208
  *Testing analysis: [date]*
209
209
  *Update when test patterns change*
210
- ```
210
+ ~~~
211
211
 
212
212
  <good_examples>
213
- ```markdown
213
+ ~~~markdown
214
214
  # Testing Patterns
215
215
 
216
216
  **Analysis Date:** 2025-01-20
@@ -435,7 +435,7 @@ it('mocks file system', () => {
435
435
 
436
436
  *Testing analysis: 2025-01-20*
437
437
  *Update when test patterns change*
438
- ```
438
+ ~~~
439
439
  </good_examples>
440
440
 
441
441
  <guidelines>
@@ -8,6 +8,7 @@
8
8
  "auto_advance": false,
9
9
  "nyquist_validation": false,
10
10
  "phase_record_compact": false,
11
+ "phase_gate": "warn",
11
12
  "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
12
13
  },
13
14
  "planning": {
@@ -15,12 +16,7 @@
15
16
  "search_gitignored": false
16
17
  },
17
18
  "parallelization": {
18
- "enabled": true,
19
- "plan_level": true,
20
- "task_level": false,
21
- "skip_checkpoints": true,
22
- "max_concurrent_agents": 3,
23
- "min_plans_for_parallel": 2
19
+ "enabled": true
24
20
  },
25
21
  "gates": {
26
22
  "confirm_project": true,
@@ -74,5 +74,5 @@ Required YAML frontmatter:
74
74
  - Be specific enough that a fresh Claude instance understands immediately
75
75
  - Include WHY decisions were made, not just what
76
76
  - The `<next_action>` should be actionable without reading anything else
77
- - This file gets DELETED after resume - it's not permanent storage
77
+ - It's not permanent storage, but resuming does not delete it: the transition workflow deletes a phase's handoffs once that phase is complete
78
78
  </guidelines>
@@ -23,7 +23,7 @@ timeline: {timeline}
23
23
 
24
24
  <mode>
25
25
  symptoms_prefilled: {true_or_false}
26
- goal: {find_root_cause_only | find_and_fix}
26
+ goal: {goal}
27
27
  </mode>
28
28
 
29
29
  <debug_file>
@@ -44,7 +44,8 @@ Create: .planning/debug/{slug}.md
44
44
  | `{errors}` | From symptoms | `None in console` |
45
45
  | `{reproduction}` | From symptoms | `Open /auth page` |
46
46
  | `{timeline}` | From symptoms | `After recent deploy` |
47
- | `{goal}` | Orchestrator sets | `find_and_fix` |
47
+ | `{true_or_false}` | Orchestrator sets (symptoms prefilled?) | `true` |
48
+ | `{goal}` | Orchestrator sets: `find_root_cause_only` or `find_and_fix` | `find_and_fix` |
48
49
  | `{slug}` | Generated | `auth-screen-dark` |
49
50
 
50
51
  ---
@@ -56,13 +57,14 @@ Create: .planning/debug/{slug}.md
56
57
  Task(
57
58
  prompt=filled_template,
58
59
  subagent_type="pan-debugger",
60
+ model="{debugger_model}",
59
61
  description="Debug {slug}"
60
62
  )
61
63
  ```
62
64
 
63
65
  **From diagnose-issues (UAT):**
64
66
  ```python
65
- Task(prompt=template, subagent_type="pan-debugger", description="Debug UAT-001")
67
+ Task(prompt=template, subagent_type="pan-debugger", model="{debugger_model}", description="Debug UAT-001")
66
68
  ```
67
69
 
68
70
  ---
@@ -8,7 +8,7 @@ Template for `.planning/debug/[slug].md` — active debug session tracking.
8
8
 
9
9
  ```markdown
10
10
  ---
11
- status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
11
+ status: gathering | investigating | diagnosed | fixing | verifying | awaiting_human_verify | resolved
12
12
  trigger: "[verbatim user input]"
13
13
  created: [ISO timestamp]
14
14
  updated: [ISO timestamp]
@@ -31,6 +31,14 @@ errors: [error messages if any]
31
31
  reproduction: [how to trigger]
32
32
  started: [when it broke / always broken]
33
33
 
34
+ ## Reproduction
35
+ <!-- Written before the first hypothesis; OVERWRITE only to shrink it -->
36
+
37
+ command: [one command you have RUN that fails on the reported symptom, or "none"]
38
+ fails_with: [the output that shows the symptom, secrets redacted]
39
+ deterministic: [yes / rate N of M runs for a flaky bug]
40
+ tried: [only when command is "none": what you tried and why it cannot be built]
41
+
34
42
  ## Eliminated
35
43
  <!-- APPEND only - prevents re-investigating after /clear -->
36
44
 
@@ -77,6 +85,12 @@ files_changed: []
77
85
  - Reference point for what we're trying to fix
78
86
  - Fields: expected, actual, errors, reproduction, started
79
87
 
88
+ **Reproduction:**
89
+ - Written before the first hypothesis: one command, already run, that fails on the reported symptom
90
+ - OVERWRITE only to shrink it; the fix is verified when this command passes
91
+ - `command: none` needs `tried:` (what was attempted and why it could not be built)
92
+ - Fields: command, fails_with, deterministic, tried
93
+
80
94
  **Eliminated:**
81
95
  - APPEND only - never remove entries
82
96
  - Prevents re-investigating dead ends after context reset
@@ -30,8 +30,8 @@ This template is used by the milestone-done workflow to create archive files in
30
30
 
31
31
  Plans:
32
32
 
33
- - [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
34
- - [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
33
+ - [x] {{PHASE}}-01-plan.md — {{PLAN_DESCRIPTION}}
34
+ - [x] {{PHASE}}-02-plan.md — {{PLAN_DESCRIPTION}}
35
35
  [... all plans ...]
36
36
 
37
37
  **Details:**
@@ -47,7 +47,7 @@ Plans:
47
47
 
48
48
  Plans:
49
49
 
50
- - [x] 02.1-01: Patch auth vulnerability
50
+ - [x] 02.1-01-plan.md — Patch auth vulnerability
51
51
 
52
52
  **Details:**
53
53
  {{PHASE_DETAILS_FROM_ROADMAP}}
@@ -106,14 +106,14 @@ _For current project status, see .planning/roadmap.md_
106
106
  - Replace {{PLACEHOLDERS}} with actual values
107
107
  - Extract phase details from roadmap.md
108
108
  - Document decimal phases with (INSERTED) marker
109
- - Include key decisions from PROJECT-state.md or SUMMARY files
109
+ - Include key decisions from project.md's Key Decisions table, state.md or the summary files
110
110
  - List issues resolved vs deferred
111
111
  - Capture technical debt for future reference
112
112
 
113
113
  **Archive location:**
114
114
 
115
- - Save to `.planning/milestones/v{VERSION}-{NAME}.md`
116
- - Example: `.planning/milestones/v1.0-mvp.md`
115
+ - Save to `.planning/milestones/v{VERSION}-roadmap.md` (the file `/pan:milestone-done` creates)
116
+ - Example: `.planning/milestones/v1.0-roadmap.md`
117
117
 
118
118
  **After archiving:**
119
119
 
@@ -51,7 +51,7 @@ If milestones.md doesn't exist, create it with header:
51
51
  - Minor bug fixes that don't constitute a release
52
52
 
53
53
  **Stats to include:**
54
- - Count modified files: `git diff --stat feat(XX-XX)..feat(YY-YY) | tail -1`
54
+ - Count modified files: `FIRST=$(git log --reverse --format=%h --grep="feat(XX-XX)" | head -1); LAST=$(git log --format=%h --grep="feat(YY-YY)" | head -1); git diff --stat "${FIRST}^..${LAST}" | tail -1`
55
55
  - Count LOC: `find . -name "*.swift" -o -name "*.ts" | xargs wc -l` (or relevant extension)
56
56
  - Phase/plan/task counts from ROADMAP
57
57
  - Timeline from first phase commit to last phase commit
@@ -16,18 +16,19 @@ Template for `.planning/phases/XX-name/{phase}-{plan}-plan.md` - executable phas
16
16
  phase: XX-name
17
17
  plan: NN
18
18
  type: execute
19
- wave: N # Execution wave (1, 2, 3...). Pre-computed at plan time.
20
- depends_on: [] # Plan IDs this plan requires (e.g., ["01-01"]).
21
- files_modified: [] # Files this plan modifies.
22
- autonomous: true # false if plan has checkpoints requiring user interaction
23
- requirements: [] # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
24
- user_setup: [] # Human-required setup Claude cannot automate (see below)
25
-
26
- # Goal-backward verification (derived during planning, verified after execution)
19
+ wave: N
20
+ depends_on: []
21
+ files_modified: []
22
+ autonomous: true
23
+ requirements: []
24
+ user_setup: []
25
+ planned_commit: <sha>
26
+
27
+ # Goal-backward verification (derived during planning, verified after execution); the Frontmatter Fields table below explains each field
27
28
  must_haves:
28
- truths: [] # Observable behaviors that must be true for goal achievement
29
- artifacts: [] # Files that must exist with real implementation
30
- key_links: [] # Critical connections between artifacts
29
+ truths: []
30
+ artifacts: []
31
+ key_links: []
31
32
  ---
32
33
 
33
34
  <objective>
@@ -46,7 +47,7 @@ Output: [What artifacts will be created]
46
47
 
47
48
  <context>
48
49
  @.planning/project.md
49
- @.planning/roadmap.md
50
+ @.planning/phases/XX-name/{phase}-roadmap-slice.md
50
51
  @.planning/state.md
51
52
 
52
53
  # Only reference prior plan SUMMARYs if genuinely needed:
@@ -58,6 +59,18 @@ Output: [What artifacts will be created]
58
59
  @src/path/to/relevant.ts
59
60
  </context>
60
61
 
62
+ ## Plan Decisions
63
+ <!-- Schema: @~/.claude/pan-wizard-core/references/handoff-decisions.md -->
64
+
65
+ ### Locked (executor MUST follow)
66
+ - D-1: [statement]. Why: [rationale]. Source: [context.md REQ-X | research.md | architecture constraint].
67
+
68
+ ### Open (executor's discretion within constraints)
69
+ - O-1: [decision space]. Constraints: [list]. Reason left open: [why planner did not lock].
70
+
71
+ ### Considered and rejected
72
+ - R-1: [alternative]. Rejected because: [reason].
73
+
61
74
  <tasks>
62
75
 
63
76
  <task type="auto">
@@ -132,6 +145,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-summary.md`
132
145
  | `files_modified` | Yes | Files this plan touches. |
133
146
  | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
134
147
  | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement MUST appear in at least one plan. |
148
+ | `planned_commit` | Yes | `git rev-parse HEAD` when the plan is written. exec-phase lists the `files_modified` that changed on the branch since then, so an executor knows its plan's picture of the code may be out of date. |
135
149
  | `user_setup` | No | Array of human-required setup items (external services) |
136
150
  | `must_haves` | Yes | Goal-backward verification criteria (see below) |
137
151
 
@@ -194,7 +208,7 @@ Plan 02 in Wave 2 waits for Plan 01 in Wave 1 - genuine dependency on auth types
194
208
  wave: 3
195
209
  depends_on: ["01", "02"]
196
210
  files_modified: [src/components/Dashboard.tsx]
197
- autonomous: false # Has checkpoint:human-verify
211
+ autonomous: false
198
212
  ```
199
213
 
200
214
  Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to user, resumes on approval.
@@ -210,7 +224,7 @@ Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to
210
224
  ```markdown
211
225
  <context>
212
226
  @.planning/project.md
213
- @.planning/roadmap.md
227
+ @.planning/phases/XX-name/{phase}-roadmap-slice.md
214
228
  @.planning/state.md
215
229
 
216
230
  # Only include SUMMARY refs if genuinely needed:
@@ -289,7 +303,7 @@ See `~/.claude/pan-wizard-core/references/tdd.md` for TDD plan structure.
289
303
  - Agent returns with checkpoint details + agent_id
290
304
  - Orchestrator presents to user
291
305
  - User responds
292
- - Orchestrator resumes agent with `resume: agent_id`
306
+ - Orchestrator spawns a fresh continuation agent with the user's response (exec-phase: a fresh agent, not a resume)
293
307
 
294
308
  ---
295
309
 
@@ -317,7 +331,7 @@ Output: User model, API endpoints, and UI components.
317
331
 
318
332
  <context>
319
333
  @.planning/project.md
320
- @.planning/roadmap.md
334
+ @.planning/phases/03-features/03-roadmap-slice.md
321
335
  @.planning/state.md
322
336
  </context>
323
337
 
@@ -382,7 +396,7 @@ Output: Working dashboard component.
382
396
 
383
397
  <context>
384
398
  @.planning/project.md
385
- @.planning/roadmap.md
399
+ @.planning/phases/03-features/03-roadmap-slice.md
386
400
  @.planning/phases/03-features/03-01-summary.md
387
401
  @.planning/phases/03-features/03-02-summary.md
388
402
  </context>
@@ -15,11 +15,8 @@ Template for spawning pan-planner agent. The agent contains all planning experti
15
15
  **Project State:**
16
16
  @.planning/state.md
17
17
 
18
- **Roadmap:**
19
- @.planning/roadmap.md
20
-
21
- **Requirements (if exists):**
22
- @.planning/requirements.md
18
+ **This phase's roadmap and requirements** (`pan-tools roadmap slice {phase_number} --write`; the whole roadmap.md and requirements.md only for something it leaves out):
19
+ @.planning/phases/{phase_dir}/{phase_num}-roadmap-slice.md
23
20
 
24
21
  **Phase Context (if exists):**
25
22
  @.planning/phases/{phase_dir}/{phase_num}-context.md
@@ -62,6 +59,7 @@ Before returning PLANNING COMPLETE:
62
59
  | `{phase_number}` | From roadmap/arguments | `5` or `2.1` |
63
60
  | `{phase_dir}` | Phase directory name | `05-user-profiles` |
64
61
  | `{phase}` | Phase prefix | `05` |
62
+ | `{phase_num}` | Padded phase number in file names | `05` |
65
63
  | `{standard \| gap_closure}` | Mode flag | `standard` |
66
64
 
67
65
  ---
@@ -73,6 +71,7 @@ Before returning PLANNING COMPLETE:
73
71
  Task(
74
72
  prompt=filled_template,
75
73
  subagent_type="pan-planner",
74
+ model="{planner_model}",
76
75
  description="Plan Phase {phase}"
77
76
  )
78
77
  ```
@@ -82,6 +81,7 @@ Task(
82
81
  Task(
83
82
  prompt=filled_template, # with mode: gap_closure
84
83
  subagent_type="pan-planner",
84
+ model="{planner_model}",
85
85
  description="Plan gaps for Phase {phase}"
86
86
  )
87
87
  ```
@@ -59,7 +59,7 @@ source: pan-previewer
59
59
  ## Hidden coupling
60
60
 
61
61
  <!-- phases mode only; may be "none found" -->
62
- - Phase {{from}} → Phase {{to}} — inferred from prose mention; consider promoting to `depends_on:` frontmatter.
62
+ - Phase {{from}} → Phase {{to}} — inferred from prose mention; consider adding it to Phase {{to}}'s `**Depends on:**` line in the roadmap.
63
63
 
64
64
  ## Current state
65
65
 
@@ -1,10 +1,10 @@
1
1
  # Architecture Research Template
2
2
 
3
- Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
3
+ Template for `.planning/research/architecture.md` — system structure patterns for the project domain.
4
4
 
5
5
  <template>
6
6
 
7
- ```markdown
7
+ ~~~markdown
8
8
  # Architecture Research
9
9
 
10
10
  **Domain:** [domain type]
@@ -170,7 +170,7 @@ src/
170
170
  ---
171
171
  *Architecture research for: [domain]*
172
172
  *Researched: [date]*
173
- ```
173
+ ~~~
174
174
 
175
175
  </template>
176
176
 
@@ -1,6 +1,6 @@
1
1
  # Features Research Template
2
2
 
3
- Template for `.planning/research/FEATURES.md` — feature landscape for the project domain.
3
+ Template for `.planning/research/features.md` — feature landscape for the project domain.
4
4
 
5
5
  <template>
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Pitfalls Research Template
2
2
 
3
- Template for `.planning/research/PITFALLS.md` — common mistakes to avoid in the project domain.
3
+ Template for `.planning/research/pitfalls.md` — common mistakes to avoid in the project domain.
4
4
 
5
5
  <template>
6
6
 
@@ -1,10 +1,10 @@
1
1
  # Stack Research Template
2
2
 
3
- Template for `.planning/research/STACK.md` — recommended technologies for the project domain.
3
+ Template for `.planning/research/stack.md` — recommended technologies for the project domain.
4
4
 
5
5
  <template>
6
6
 
7
- ```markdown
7
+ ~~~markdown
8
8
  # Stack Research
9
9
 
10
10
  **Domain:** [domain type]
@@ -88,7 +88,7 @@ npm install -D [packages]
88
88
  ---
89
89
  *Stack research for: [domain]*
90
90
  *Researched: [date]*
91
- ```
91
+ ~~~
92
92
 
93
93
  </template>
94
94
 
@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase_num}-research.md` - comprehensive
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # Phase [X]: [Name] - Research
13
13
 
14
14
  **Researched:** [date]
@@ -21,7 +21,7 @@ Template for `.planning/phases/XX-name/{phase_num}-research.md` - comprehensive
21
21
  **CRITICAL:** If context.md exists from /pan:discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
22
22
 
23
23
  ### Locked Decisions
24
- [Copy from context.md `## Decisions` section - these are NON-NEGOTIABLE]
24
+ [Copy from context.md `## Implementation Decisions` section (inside `<decisions>`) - these are NON-NEGOTIABLE]
25
25
  - [Decision 1]
26
26
  - [Decision 2]
27
27
 
@@ -242,13 +242,13 @@ Things that couldn't be fully resolved:
242
242
  *Phase: XX-name*
243
243
  *Research completed: [date]*
244
244
  *Ready for planning: [yes/no]*
245
- ```
245
+ ~~~
246
246
 
247
247
  ---
248
248
 
249
249
  ## Good Example
250
250
 
251
- ```markdown
251
+ ~~~markdown
252
252
  # Phase 3: 3D City Driving - Research
253
253
 
254
254
  **Researched:** 2025-01-20
@@ -516,7 +516,7 @@ function useVehicleControls(rigidBodyRef) {
516
516
  *Phase: 03-city-driving*
517
517
  *Research completed: 2025-01-20*
518
518
  *Ready for planning: yes*
519
- ```
519
+ ~~~
520
520
 
521
521
  ---
522
522
 
@@ -28,7 +28,7 @@
28
28
  2. {Another lesson}
29
29
 
30
30
  ### Cost Observations
31
- - Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
31
+ - Model mix: {X}% reasoning tier, {Y}% mid, {Z}% fast
32
32
  - Sessions: {count}
33
33
  - Notable: {efficiency observation}
34
34
 
@@ -29,7 +29,7 @@ Decimal phases appear between their surrounding integers in numeric order.
29
29
  ### Phase 1: [Name]
30
30
  **Goal:** [What this phase delivers]
31
31
  **Depends on:** Nothing (first phase)
32
- **Requirements:** [REQ-01, REQ-02, REQ-03] <!-- brackets optional, parser handles both formats -->
32
+ **Requirements:** [REQ-01, REQ-02, REQ-03]
33
33
  **Success Criteria** (what must be TRUE):
34
34
  1. [Observable behavior from user perspective]
35
35
  2. [Observable behavior from user perspective]
@@ -37,9 +37,9 @@ Decimal phases appear between their surrounding integers in numeric order.
37
37
  **Plans:** [Number of plans, e.g., "3 plans" or "TBD"]
38
38
 
39
39
  Plans:
40
- - [ ] 01-01: [Brief description of first plan]
41
- - [ ] 01-02: [Brief description of second plan]
42
- - [ ] 01-03: [Brief description of third plan]
40
+ - [ ] 01-01-plan.md — [Brief description of first plan]
41
+ - [ ] 01-02-plan.md — [Brief description of second plan]
42
+ - [ ] 01-03-plan.md — [Brief description of third plan]
43
43
 
44
44
  ### Phase 2: [Name]
45
45
  **Goal:** [What this phase delivers]
@@ -51,8 +51,8 @@ Plans:
51
51
  **Plans:** [Number of plans]
52
52
 
53
53
  Plans:
54
- - [ ] 02-01: [Brief description]
55
- - [ ] 02-02: [Brief description]
54
+ - [ ] 02-01-plan.md — [Brief description]
55
+ - [ ] 02-02-plan.md — [Brief description]
56
56
 
57
57
  ### Phase 2.1: Critical Fix (INSERTED)
58
58
  **Goal:** [Urgent work inserted between phases]
@@ -62,7 +62,7 @@ Plans:
62
62
  **Plans:** 1 plan
63
63
 
64
64
  Plans:
65
- - [ ] 02.1-01: [Description]
65
+ - [ ] 02.1-01-plan.md — [Description]
66
66
 
67
67
  ### Phase 3: [Name]
68
68
  **Goal:** [What this phase delivers]
@@ -75,8 +75,8 @@ Plans:
75
75
  **Plans:** [Number of plans]
76
76
 
77
77
  Plans:
78
- - [ ] 03-01: [Brief description]
79
- - [ ] 03-02: [Brief description]
78
+ - [ ] 03-01-plan.md — [Brief description]
79
+ - [ ] 03-02-plan.md — [Brief description]
80
80
 
81
81
  ### Phase 4: [Name]
82
82
  **Goal:** [What this phase delivers]
@@ -88,7 +88,7 @@ Plans:
88
88
  **Plans:** [Number of plans]
89
89
 
90
90
  Plans:
91
- - [ ] 04-01: [Brief description]
91
+ - [ ] 04-01-plan.md — [Brief description]
92
92
 
93
93
  ## Progress
94
94
 
@@ -156,9 +156,9 @@ After completing first milestone, reorganize with milestone groupings:
156
156
  **Plans:** 3 plans
157
157
 
158
158
  Plans:
159
- - [x] 01-01: [Brief description]
160
- - [x] 01-02: [Brief description]
161
- - [x] 01-03: [Brief description]
159
+ - [x] 01-01-plan.md — [Brief description]
160
+ - [x] 01-02-plan.md — [Brief description]
161
+ - [x] 01-03-plan.md — [Brief description]
162
162
 
163
163
  [... remaining v1.0 phases ...]
164
164
 
@@ -174,8 +174,8 @@ Plans:
174
174
  **Plans:** 2 plans
175
175
 
176
176
  Plans:
177
- - [ ] 05-01: [Brief description]
178
- - [ ] 05-02: [Brief description]
177
+ - [ ] 05-01-plan.md — [Brief description]
178
+ - [ ] 05-02-plan.md — [Brief description]
179
179
 
180
180
  [... remaining v1.1 phases ...]
181
181