pan-wizard 3.33.0 → 3.34.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 (197) hide show
  1. package/README.md +23 -20
  2. package/agents/pan-conductor.md +17 -16
  3. package/agents/pan-counterfactual.md +2 -2
  4. package/agents/pan-debugger.md +27 -8
  5. package/agents/pan-design-checker.md +1 -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 +12 -8
  10. package/agents/pan-experiment-runner.md +8 -7
  11. package/agents/pan-integration-checker.md +2 -2
  12. package/agents/pan-knowledge.md +1 -1
  13. package/agents/pan-meta-reviewer.md +3 -3
  14. package/agents/pan-optimizer.md +39 -43
  15. package/agents/pan-phase-researcher.md +8 -8
  16. package/agents/pan-plan-checker.md +30 -28
  17. package/agents/pan-planner.md +54 -43
  18. package/agents/pan-previewer.md +1 -1
  19. package/agents/pan-project-researcher.md +11 -11
  20. package/agents/pan-release.md +1 -1
  21. package/agents/pan-research-synthesizer.md +2 -2
  22. package/agents/pan-reviewer.md +24 -2
  23. package/agents/pan-roadmapper.md +15 -14
  24. package/agents/pan-verifier.md +32 -24
  25. package/bin/install-lib.cjs +58 -23
  26. package/bin/install.js +47 -1
  27. package/commands/pan/army.md +15 -11
  28. package/commands/pan/assumptions.md +2 -2
  29. package/commands/pan/audit-deployment.md +11 -12
  30. package/commands/pan/cost.md +8 -4
  31. package/commands/pan/debug.md +10 -7
  32. package/commands/pan/design-phase.md +3 -3
  33. package/commands/pan/discuss-phase.md +2 -0
  34. package/commands/pan/exec-phase.md +21 -37
  35. package/commands/pan/experiment.md +9 -8
  36. package/commands/pan/focus-auto.md +22 -20
  37. package/commands/pan/focus-design.md +7 -6
  38. package/commands/pan/focus-doc-audit.md +4 -3
  39. package/commands/pan/focus-drift-walking.md +4 -3
  40. package/commands/pan/focus-exec.md +6 -6
  41. package/commands/pan/focus-plan.md +12 -11
  42. package/commands/pan/focus-scan.md +5 -3
  43. package/commands/pan/focus-sync.md +3 -2
  44. package/commands/pan/git.md +8 -8
  45. package/commands/pan/health.md +2 -2
  46. package/commands/pan/hud.md +3 -2
  47. package/commands/pan/hygiene.md +14 -7
  48. package/commands/pan/knowledge.md +9 -9
  49. package/commands/pan/learn.md +10 -7
  50. package/commands/pan/links.md +4 -1
  51. package/commands/pan/map-codebase.md +1 -1
  52. package/commands/pan/mcp-bridge.md +18 -18
  53. package/commands/pan/milestone-done.md +6 -3
  54. package/commands/pan/milestone-new.md +1 -1
  55. package/commands/pan/new-project.md +10 -10
  56. package/commands/pan/optimize.md +16 -14
  57. package/commands/pan/patches.md +2 -6
  58. package/commands/pan/pause.md +1 -1
  59. package/commands/pan/phase-tests.md +2 -1
  60. package/commands/pan/plan-phase.md +9 -19
  61. package/commands/pan/preview.md +1 -1
  62. package/commands/pan/profile.md +2 -2
  63. package/commands/pan/quick.md +1 -1
  64. package/commands/pan/remove-phase.md +1 -1
  65. package/commands/pan/report.md +2 -2
  66. package/commands/pan/research-phase.md +12 -11
  67. package/commands/pan/resume.md +9 -11
  68. package/commands/pan/retro.md +5 -3
  69. package/commands/pan/review-deep.md +7 -7
  70. package/commands/pan/settings.md +1 -1
  71. package/commands/pan/verify-phase.md +0 -11
  72. package/commands/pan/what-if.md +2 -2
  73. package/hooks/dist/pan-context-monitor.js +343 -44
  74. package/hooks/dist/pan-cost-logger.js +30 -0
  75. package/hooks/dist/pan-statusline.js +68 -22
  76. package/hooks/dist/pan-stop-guard.js +7 -2
  77. package/package.json +1 -1
  78. package/pan-wizard-core/bin/lib/agents-md.cjs +44 -6
  79. package/pan-wizard-core/bin/lib/bridge.cjs +6 -5
  80. package/pan-wizard-core/bin/lib/campaign.cjs +4 -2
  81. package/pan-wizard-core/bin/lib/commands-learnings.cjs +19 -2
  82. package/pan-wizard-core/bin/lib/commands.cjs +33 -4
  83. package/pan-wizard-core/bin/lib/config.cjs +2 -1
  84. package/pan-wizard-core/bin/lib/constants.cjs +18 -6
  85. package/pan-wizard-core/bin/lib/context-budget.cjs +12 -9
  86. package/pan-wizard-core/bin/lib/core.cjs +53 -19
  87. package/pan-wizard-core/bin/lib/cost-rebuild.cjs +13 -1
  88. package/pan-wizard-core/bin/lib/cost.cjs +142 -13
  89. package/pan-wizard-core/bin/lib/distill.cjs +6 -3
  90. package/pan-wizard-core/bin/lib/doc-lint.cjs +30 -11
  91. package/pan-wizard-core/bin/lib/findings.cjs +9 -2
  92. package/pan-wizard-core/bin/lib/focus.cjs +13 -4
  93. package/pan-wizard-core/bin/lib/frontmatter.cjs +105 -26
  94. package/pan-wizard-core/bin/lib/hygiene.cjs +178 -17
  95. package/pan-wizard-core/bin/lib/init.cjs +7 -4
  96. package/pan-wizard-core/bin/lib/knowledge.cjs +17 -1
  97. package/pan-wizard-core/bin/lib/learn-index.cjs +111 -10
  98. package/pan-wizard-core/bin/lib/learn-lint.cjs +30 -3
  99. package/pan-wizard-core/bin/lib/memory-optimize.cjs +8 -4
  100. package/pan-wizard-core/bin/lib/memory.cjs +508 -54
  101. package/pan-wizard-core/bin/lib/milestone.cjs +8 -3
  102. package/pan-wizard-core/bin/lib/optimize.cjs +84 -16
  103. package/pan-wizard-core/bin/lib/phase-remove.cjs +85 -21
  104. package/pan-wizard-core/bin/lib/phase-report.cjs +8 -2
  105. package/pan-wizard-core/bin/lib/phase.cjs +15 -13
  106. package/pan-wizard-core/bin/lib/preview.cjs +3 -1
  107. package/pan-wizard-core/bin/lib/roadmap-compact.cjs +267 -0
  108. package/pan-wizard-core/bin/lib/roadmap.cjs +243 -9
  109. package/pan-wizard-core/bin/lib/runner.cjs +2 -1
  110. package/pan-wizard-core/bin/lib/state-compact.cjs +11 -6
  111. package/pan-wizard-core/bin/lib/state.cjs +43 -28
  112. package/pan-wizard-core/bin/lib/template.cjs +11 -4
  113. package/pan-wizard-core/bin/lib/verify-preflight.cjs +4 -13
  114. package/pan-wizard-core/bin/lib/verify-retro.cjs +5 -3
  115. package/pan-wizard-core/bin/lib/verify-scope.cjs +5 -2
  116. package/pan-wizard-core/bin/lib/verify.cjs +30 -28
  117. package/pan-wizard-core/bin/lib/whatif.cjs +5 -3
  118. package/pan-wizard-core/bin/pan-tools.cjs +101 -15
  119. package/pan-wizard-core/learnings/index.json +5 -5
  120. package/pan-wizard-core/opencode/pan-wizard.js +111 -0
  121. package/pan-wizard-core/references/checkpoints.md +3 -3
  122. package/pan-wizard-core/references/continuation-format.md +3 -3
  123. package/pan-wizard-core/references/decimal-phase-calculation.md +2 -3
  124. package/pan-wizard-core/references/design-methodology.md +1 -1
  125. package/pan-wizard-core/references/git-integration.md +4 -6
  126. package/pan-wizard-core/references/git-planning-commit.md +2 -2
  127. package/pan-wizard-core/references/guardrails.md +2 -2
  128. package/pan-wizard-core/references/handoff-decisions.md +3 -3
  129. package/pan-wizard-core/references/model-profile-resolution.md +5 -5
  130. package/pan-wizard-core/references/model-profiles.md +14 -9
  131. package/pan-wizard-core/references/phase-argument-parsing.md +7 -7
  132. package/pan-wizard-core/references/planning-config.md +4 -4
  133. package/pan-wizard-core/references/tdd.md +10 -1
  134. package/pan-wizard-core/references/verification-patterns.md +5 -5
  135. package/pan-wizard-core/templates/codebase/architecture.md +2 -2
  136. package/pan-wizard-core/templates/codebase/best-practices.md +2 -2
  137. package/pan-wizard-core/templates/codebase/concerns.md +3 -3
  138. package/pan-wizard-core/templates/codebase/integrations.md +6 -6
  139. package/pan-wizard-core/templates/codebase/relationships.md +2 -2
  140. package/pan-wizard-core/templates/codebase/stack.md +2 -2
  141. package/pan-wizard-core/templates/codebase/structure.md +4 -4
  142. package/pan-wizard-core/templates/codebase/testing.md +4 -4
  143. package/pan-wizard-core/templates/continue-here.md +1 -1
  144. package/pan-wizard-core/templates/debug-subagent-prompt.md +3 -2
  145. package/pan-wizard-core/templates/debug.md +15 -1
  146. package/pan-wizard-core/templates/milestone-archive.md +6 -6
  147. package/pan-wizard-core/templates/milestone.md +1 -1
  148. package/pan-wizard-core/templates/phase-prompt.md +29 -17
  149. package/pan-wizard-core/templates/planner-subagent-prompt.md +3 -5
  150. package/pan-wizard-core/templates/research-project/architecture.md +3 -3
  151. package/pan-wizard-core/templates/research-project/features.md +1 -1
  152. package/pan-wizard-core/templates/research-project/pitfalls.md +1 -1
  153. package/pan-wizard-core/templates/research-project/stack.md +3 -3
  154. package/pan-wizard-core/templates/research.md +5 -5
  155. package/pan-wizard-core/templates/retrospective.md +1 -1
  156. package/pan-wizard-core/templates/roadmap.md +15 -15
  157. package/pan-wizard-core/templates/summary-complex.md +1 -0
  158. package/pan-wizard-core/templates/summary-minimal.md +1 -0
  159. package/pan-wizard-core/templates/summary-standard.md +2 -1
  160. package/pan-wizard-core/templates/summary.md +18 -2
  161. package/pan-wizard-core/templates/uat.md +3 -3
  162. package/pan-wizard-core/templates/user-setup.md +8 -8
  163. package/pan-wizard-core/templates/verification-report.md +53 -8
  164. package/pan-wizard-core/workflows/add-phase.md +1 -1
  165. package/pan-wizard-core/workflows/assumptions.md +1 -1
  166. package/pan-wizard-core/workflows/discuss-phase.md +9 -8
  167. package/pan-wizard-core/workflows/exec-phase.md +26 -57
  168. package/pan-wizard-core/workflows/execute-plan.md +8 -7
  169. package/pan-wizard-core/workflows/health.md +13 -12
  170. package/pan-wizard-core/workflows/help.md +8 -9
  171. package/pan-wizard-core/workflows/learn.md +13 -11
  172. package/pan-wizard-core/workflows/map-codebase.md +10 -10
  173. package/pan-wizard-core/workflows/milestone-audit.md +10 -10
  174. package/pan-wizard-core/workflows/milestone-gaps.md +17 -24
  175. package/pan-wizard-core/workflows/milestone-new.md +7 -6
  176. package/pan-wizard-core/workflows/new-project.md +9 -9
  177. package/pan-wizard-core/workflows/optimize.md +11 -9
  178. package/pan-wizard-core/workflows/pause.md +6 -1
  179. package/pan-wizard-core/workflows/phase-tests.md +4 -4
  180. package/pan-wizard-core/workflows/plan-phase.md +31 -34
  181. package/pan-wizard-core/workflows/profile.md +2 -2
  182. package/pan-wizard-core/workflows/progress.md +5 -7
  183. package/pan-wizard-core/workflows/quick.md +5 -3
  184. package/pan-wizard-core/workflows/remove-phase.md +1 -1
  185. package/pan-wizard-core/workflows/research-phase.md +9 -5
  186. package/pan-wizard-core/workflows/resume-project.md +4 -6
  187. package/pan-wizard-core/workflows/retro.md +3 -1
  188. package/pan-wizard-core/workflows/settings.md +16 -24
  189. package/pan-wizard-core/workflows/todo-check.md +1 -1
  190. package/pan-wizard-core/workflows/transition.md +12 -12
  191. package/pan-wizard-core/workflows/update.md +25 -17
  192. package/pan-wizard-core/workflows/verify-phase.md +17 -15
  193. package/pan-zcode/KNOWN-BETA-RISKS.md +2 -2
  194. package/pan-zcode/README.md +7 -7
  195. package/pan-zcode/bin/install-zcode.js +1 -1
  196. package/scripts/build-plugin.js +3 -1
  197. package/scripts/generate-skills-docs.py +13 -4
@@ -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>
@@ -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
  ---
@@ -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,18 @@ 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
+
26
+ # Goal-backward verification (derived during planning, verified after execution); the Frontmatter Fields table below explains each field
27
27
  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
28
+ truths: []
29
+ artifacts: []
30
+ key_links: []
31
31
  ---
32
32
 
33
33
  <objective>
@@ -46,7 +46,7 @@ Output: [What artifacts will be created]
46
46
 
47
47
  <context>
48
48
  @.planning/project.md
49
- @.planning/roadmap.md
49
+ @.planning/phases/XX-name/{phase}-roadmap-slice.md
50
50
  @.planning/state.md
51
51
 
52
52
  # Only reference prior plan SUMMARYs if genuinely needed:
@@ -58,6 +58,18 @@ Output: [What artifacts will be created]
58
58
  @src/path/to/relevant.ts
59
59
  </context>
60
60
 
61
+ ## Plan Decisions
62
+ <!-- Schema: @~/.claude/pan-wizard-core/references/handoff-decisions.md -->
63
+
64
+ ### Locked (executor MUST follow)
65
+ - D-1: [statement]. Why: [rationale]. Source: [context.md REQ-X | research.md | architecture constraint].
66
+
67
+ ### Open (executor's discretion within constraints)
68
+ - O-1: [decision space]. Constraints: [list]. Reason left open: [why planner did not lock].
69
+
70
+ ### Considered and rejected
71
+ - R-1: [alternative]. Rejected because: [reason].
72
+
61
73
  <tasks>
62
74
 
63
75
  <task type="auto">
@@ -194,7 +206,7 @@ Plan 02 in Wave 2 waits for Plan 01 in Wave 1 - genuine dependency on auth types
194
206
  wave: 3
195
207
  depends_on: ["01", "02"]
196
208
  files_modified: [src/components/Dashboard.tsx]
197
- autonomous: false # Has checkpoint:human-verify
209
+ autonomous: false
198
210
  ```
199
211
 
200
212
  Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to user, resumes on approval.
@@ -210,7 +222,7 @@ Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to
210
222
  ```markdown
211
223
  <context>
212
224
  @.planning/project.md
213
- @.planning/roadmap.md
225
+ @.planning/phases/XX-name/{phase}-roadmap-slice.md
214
226
  @.planning/state.md
215
227
 
216
228
  # Only include SUMMARY refs if genuinely needed:
@@ -289,7 +301,7 @@ See `~/.claude/pan-wizard-core/references/tdd.md` for TDD plan structure.
289
301
  - Agent returns with checkpoint details + agent_id
290
302
  - Orchestrator presents to user
291
303
  - User responds
292
- - Orchestrator resumes agent with `resume: agent_id`
304
+ - Orchestrator spawns a fresh continuation agent with the user's response (exec-phase: a fresh agent, not a resume)
293
305
 
294
306
  ---
295
307
 
@@ -317,7 +329,7 @@ Output: User model, API endpoints, and UI components.
317
329
 
318
330
  <context>
319
331
  @.planning/project.md
320
- @.planning/roadmap.md
332
+ @.planning/phases/03-features/03-roadmap-slice.md
321
333
  @.planning/state.md
322
334
  </context>
323
335
 
@@ -382,7 +394,7 @@ Output: Working dashboard component.
382
394
 
383
395
  <context>
384
396
  @.planning/project.md
385
- @.planning/roadmap.md
397
+ @.planning/phases/03-features/03-roadmap-slice.md
386
398
  @.planning/phases/03-features/03-01-summary.md
387
399
  @.planning/phases/03-features/03-02-summary.md
388
400
  </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
  ---
@@ -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
 
@@ -19,6 +19,7 @@ key-decisions:
19
19
  - "Decision 1"
20
20
  patterns-established:
21
21
  - "Pattern 1: description"
22
+ requirements-completed: []
22
23
  duration: Xmin
23
24
  completed: YYYY-MM-DD
24
25
  ---
@@ -13,6 +13,7 @@ key-files:
13
13
  created: [important files created]
14
14
  modified: [important files modified]
15
15
  key-decisions: []
16
+ requirements-completed: []
16
17
  duration: Xmin
17
18
  completed: YYYY-MM-DD
18
19
  ---
@@ -6,7 +6,8 @@ tags: [searchable tech]
6
6
  provides:
7
7
  - [bullet list of what was built/delivered]
8
8
  affects: [list of phase names or keywords]
9
- test-tiers: [] # Optional — Test tiers exercised: [unit, integration, e2e, visual]
9
+ requirements-completed: []
10
+ test-tiers: []
10
11
  tech-stack:
11
12
  added: [libraries/tools]
12
13
  patterns: [architectural/code patterns]
@@ -38,8 +38,10 @@ patterns-established:
38
38
  - "Pattern 1: description"
39
39
  - "Pattern 2: description"
40
40
 
41
- requirements-completed: [] # REQUIRED — Copy ALL requirement IDs from this plan's `requirements` frontmatter field.
42
- test-tiers: [] # Optional — Test tiers exercised in this plan: [unit, integration, e2e, visual]
41
+ # requirements-completed: REQUIRED — copy ALL requirement IDs from this plan's `requirements` frontmatter field
42
+ requirements-completed: []
43
+ # test-tiers: optional — the test tiers this plan exercised (unit, integration, e2e, visual)
44
+ test-tiers: []
43
45
 
44
46
  # Metrics
45
47
  duration: Xmin
@@ -79,6 +81,20 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
79
81
  - `path/to/file.ts` - What it does
80
82
  - `path/to/another.ts` - What it does
81
83
 
84
+ ## Implementation Decisions
85
+ <!-- Schema: @~/.claude/pan-wizard-core/references/handoff-decisions.md -->
86
+
87
+ ### Taken (within plan's discretion)
88
+ - DT-1: Chose [option] for O-N. Reason: [rationale].
89
+
90
+ ### Deviations (from plan; must explain)
91
+ - DV-1: Plan said [X]; I did [Y]. Reason: [rationale]. Verification: [how I confirmed Y is acceptable].
92
+
93
+ ### Open questions for verifier
94
+ - Q-1: [question]. Why it matters: [stake].
95
+
96
+ <!-- If none: replace ALL three buckets with "No deviations or open questions — implementation followed plan exactly." -->
97
+
82
98
  ## Decisions Made
83
99
  [Key decisions with brief rationale, or "None - followed plan as specified"]
84
100
 
@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase_num}-uat.md` — persistent UAT se
8
8
 
9
9
  ```markdown
10
10
  ---
11
- status: testing | complete | diagnosed
11
+ status: testing | complete | diagnosed | resolved
12
12
  phase: XX-name
13
13
  source: [list of summary.md files tested]
14
14
  started: [ISO timestamp]
@@ -74,7 +74,7 @@ skipped: [N]
74
74
  <section_rules>
75
75
 
76
76
  **Frontmatter:**
77
- - `status`: OVERWRITE - "testing" or "complete"
77
+ - `status`: OVERWRITE - "testing", "complete", "diagnosed" (after diagnosis) or "resolved" (exec-phase closes the gaps)
78
78
  - `phase`: IMMUTABLE - set on creation
79
79
  - `source`: IMMUTABLE - SUMMARY files being tested
80
80
  - `started`: IMMUTABLE - set on creation
@@ -106,7 +106,7 @@ skipped: [N]
106
106
 
107
107
  **After testing complete (status: complete), if gaps exist:**
108
108
 
109
- 1. User runs diagnosis (from verify-phase offer or manually)
109
+ 1. User runs diagnosis (on Claude Code, the native `/pan-diagnose-issues <phase>`; no `/pan:` command or verify-phase step runs it)
110
110
  2. diagnose-issues workflow spawns parallel debug agents
111
111
  3. Each agent investigates one gap, returns root cause
112
112
  4. uat.md Gaps section updated with diagnosis:
@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required c
8
8
 
9
9
  ## File Template
10
10
 
11
- ```markdown
11
+ ~~~markdown
12
12
  # Phase {X}: User Setup Required
13
13
 
14
14
  **Generated:** [YYYY-MM-DD]
@@ -55,7 +55,7 @@ Expected results:
55
55
  ---
56
56
 
57
57
  **Once all items complete:** Mark status as "Complete" at top of file.
58
- ```
58
+ ~~~
59
59
 
60
60
  ---
61
61
 
@@ -117,7 +117,7 @@ user_setup:
117
117
  ## Service-Specific Examples
118
118
 
119
119
  <stripe_example>
120
- ```markdown
120
+ ~~~markdown
121
121
  # Phase 10: User Setup Required
122
122
 
123
123
  **Generated:** 2025-01-14
@@ -188,11 +188,11 @@ Expected: Build passes, webhook returns 400 (signature validation working).
188
188
  ---
189
189
 
190
190
  **Once all items complete:** Mark status as "Complete" at top of file.
191
- ```
191
+ ~~~
192
192
  </stripe_example>
193
193
 
194
194
  <supabase_example>
195
- ```markdown
195
+ ~~~markdown
196
196
  # Phase 2: User Setup Required
197
197
 
198
198
  **Generated:** 2025-01-14
@@ -242,11 +242,11 @@ npx supabase status
242
242
  ---
243
243
 
244
244
  **Once all items complete:** Mark status as "Complete" at top of file.
245
- ```
245
+ ~~~
246
246
  </supabase_example>
247
247
 
248
248
  <sendgrid_example>
249
- ```markdown
249
+ ~~~markdown
250
250
  # Phase 5: User Setup Required
251
251
 
252
252
  **Generated:** 2025-01-14
@@ -297,7 +297,7 @@ curl -X POST http://localhost:3000/api/test-email \
297
297
  ---
298
298
 
299
299
  **Once all items complete:** Mark status as "Complete" at top of file.
300
- ```
300
+ ~~~
301
301
  </sendgrid_example>
302
302
 
303
303
  ---