maxsimcli 4.8.0 → 4.9.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 (161) hide show
  1. package/dist/assets/CHANGELOG.md +13 -0
  2. package/dist/assets/hooks/maxsim-check-update.cjs +38 -0
  3. package/dist/assets/hooks/maxsim-check-update.cjs.map +1 -1
  4. package/dist/assets/hooks/maxsim-statusline.cjs +116 -48
  5. package/dist/assets/hooks/maxsim-statusline.cjs.map +1 -1
  6. package/dist/assets/hooks/maxsim-sync-reminder.cjs +117 -0
  7. package/dist/assets/hooks/maxsim-sync-reminder.cjs.map +1 -0
  8. package/dist/assets/templates/agents/AGENTS.md +78 -106
  9. package/dist/assets/templates/agents/executor.md +101 -0
  10. package/dist/assets/templates/agents/planner.md +86 -0
  11. package/dist/assets/templates/agents/researcher.md +71 -0
  12. package/dist/assets/templates/agents/verifier.md +88 -0
  13. package/dist/assets/templates/commands/maxsim/debug.md +7 -7
  14. package/dist/assets/templates/commands/maxsim/execute.md +45 -0
  15. package/dist/assets/templates/commands/maxsim/go.md +29 -0
  16. package/dist/assets/templates/commands/maxsim/help.md +2 -2
  17. package/dist/assets/templates/commands/maxsim/init.md +52 -0
  18. package/dist/assets/templates/commands/maxsim/plan.md +50 -0
  19. package/dist/assets/templates/commands/maxsim/progress.md +4 -3
  20. package/dist/assets/templates/commands/maxsim/quick.md +6 -4
  21. package/dist/assets/templates/commands/maxsim/settings.md +4 -3
  22. package/dist/assets/templates/references/continuation-format.md +16 -16
  23. package/dist/assets/templates/references/model-profile-resolution.md +1 -1
  24. package/dist/assets/templates/references/model-profiles.md +12 -19
  25. package/dist/assets/templates/rules/conventions.md +51 -0
  26. package/dist/assets/templates/rules/verification-protocol.md +57 -0
  27. package/dist/assets/templates/skills/agent-system-map/SKILL.md +92 -0
  28. package/dist/assets/templates/skills/brainstorming/SKILL.md +48 -36
  29. package/dist/assets/templates/skills/code-review/SKILL.md +40 -61
  30. package/dist/assets/templates/skills/commit-conventions/SKILL.md +75 -0
  31. package/dist/assets/templates/skills/evidence-collection/SKILL.md +87 -0
  32. package/dist/assets/templates/skills/handoff-contract/SKILL.md +70 -0
  33. package/dist/assets/templates/skills/input-validation/SKILL.md +51 -0
  34. package/dist/assets/templates/skills/maxsim-batch/SKILL.md +41 -45
  35. package/dist/assets/templates/skills/maxsim-simplify/SKILL.md +37 -90
  36. package/dist/assets/templates/skills/memory-management/SKILL.md +32 -67
  37. package/dist/assets/templates/skills/research-methodology/SKILL.md +137 -0
  38. package/dist/assets/templates/skills/roadmap-writing/SKILL.md +40 -58
  39. package/dist/assets/templates/skills/sdd/SKILL.md +34 -69
  40. package/dist/assets/templates/skills/systematic-debugging/SKILL.md +20 -26
  41. package/dist/assets/templates/skills/tdd/SKILL.md +25 -33
  42. package/dist/assets/templates/skills/tool-priority-guide/SKILL.md +80 -0
  43. package/dist/assets/templates/skills/using-maxsim/SKILL.md +42 -73
  44. package/dist/assets/templates/skills/verification-before-completion/SKILL.md +12 -24
  45. package/dist/assets/templates/skills/verification-gates/SKILL.md +169 -0
  46. package/dist/assets/templates/templates/UAT.md +3 -3
  47. package/dist/assets/templates/templates/VALIDATION.md +1 -1
  48. package/dist/assets/templates/templates/context.md +4 -4
  49. package/dist/assets/templates/templates/debug-subagent-prompt.md +3 -3
  50. package/dist/assets/templates/templates/discovery.md +2 -2
  51. package/dist/assets/templates/templates/phase-prompt.md +2 -2
  52. package/dist/assets/templates/templates/planner-subagent-prompt.md +7 -7
  53. package/dist/assets/templates/templates/project.md +1 -1
  54. package/dist/assets/templates/templates/research.md +1 -1
  55. package/dist/assets/templates/templates/state.md +2 -2
  56. package/dist/assets/templates/templates/summary.md +41 -0
  57. package/dist/assets/templates/workflows/batch.md +5 -5
  58. package/dist/assets/templates/workflows/diagnose-issues.md +2 -2
  59. package/dist/assets/templates/workflows/discovery-phase.md +3 -3
  60. package/dist/assets/templates/workflows/discuss-phase.md +11 -11
  61. package/dist/assets/templates/workflows/execute-phase.md +205 -11
  62. package/dist/assets/templates/workflows/execute-plan.md +299 -34
  63. package/dist/assets/templates/workflows/execute.md +421 -0
  64. package/dist/assets/templates/workflows/go.md +250 -0
  65. package/dist/assets/templates/workflows/health.md +5 -5
  66. package/dist/assets/templates/workflows/help.md +165 -435
  67. package/dist/assets/templates/workflows/init-existing.md +23 -23
  68. package/dist/assets/templates/workflows/init.md +205 -0
  69. package/dist/assets/templates/workflows/new-milestone.md +9 -9
  70. package/dist/assets/templates/workflows/new-project.md +26 -26
  71. package/dist/assets/templates/workflows/plan-create.md +298 -0
  72. package/dist/assets/templates/workflows/plan-discuss.md +347 -0
  73. package/dist/assets/templates/workflows/plan-phase.md +29 -29
  74. package/dist/assets/templates/workflows/plan-research.md +177 -0
  75. package/dist/assets/templates/workflows/plan.md +231 -0
  76. package/dist/assets/templates/workflows/progress.md +46 -42
  77. package/dist/assets/templates/workflows/quick.md +195 -14
  78. package/dist/assets/templates/workflows/research-phase.md +5 -5
  79. package/dist/assets/templates/workflows/sdd.md +20 -12
  80. package/dist/assets/templates/workflows/settings.md +18 -14
  81. package/dist/assets/templates/workflows/verify-phase.md +1 -1
  82. package/dist/assets/templates/workflows/verify-work.md +16 -16
  83. package/dist/cli.cjs +496 -91
  84. package/dist/cli.cjs.map +1 -1
  85. package/dist/core-D5zUr9cb.cjs.map +1 -1
  86. package/dist/install.cjs +234 -17
  87. package/dist/install.cjs.map +1 -1
  88. package/dist/mcp-server.cjs +21 -2
  89. package/dist/mcp-server.cjs.map +1 -1
  90. package/dist/skills-CjFWZIGM.cjs.map +1 -1
  91. package/package.json +1 -1
  92. package/dist/assets/hooks/maxsim-context-monitor.cjs +0 -121
  93. package/dist/assets/hooks/maxsim-context-monitor.cjs.map +0 -1
  94. package/dist/assets/templates/agents/maxsim-code-reviewer.md +0 -239
  95. package/dist/assets/templates/agents/maxsim-codebase-mapper.md +0 -214
  96. package/dist/assets/templates/agents/maxsim-debugger.md +0 -572
  97. package/dist/assets/templates/agents/maxsim-drift-checker.md +0 -522
  98. package/dist/assets/templates/agents/maxsim-executor.md +0 -504
  99. package/dist/assets/templates/agents/maxsim-integration-checker.md +0 -273
  100. package/dist/assets/templates/agents/maxsim-phase-researcher.md +0 -305
  101. package/dist/assets/templates/agents/maxsim-plan-checker.md +0 -343
  102. package/dist/assets/templates/agents/maxsim-planner.md +0 -610
  103. package/dist/assets/templates/agents/maxsim-project-researcher.md +0 -359
  104. package/dist/assets/templates/agents/maxsim-research-synthesizer.md +0 -263
  105. package/dist/assets/templates/agents/maxsim-roadmapper.md +0 -324
  106. package/dist/assets/templates/agents/maxsim-spec-reviewer.md +0 -245
  107. package/dist/assets/templates/agents/maxsim-verifier.md +0 -393
  108. package/dist/assets/templates/commands/maxsim/add-phase.md +0 -43
  109. package/dist/assets/templates/commands/maxsim/add-tests.md +0 -41
  110. package/dist/assets/templates/commands/maxsim/add-todo.md +0 -57
  111. package/dist/assets/templates/commands/maxsim/artefakte.md +0 -122
  112. package/dist/assets/templates/commands/maxsim/audit-milestone.md +0 -36
  113. package/dist/assets/templates/commands/maxsim/batch.md +0 -42
  114. package/dist/assets/templates/commands/maxsim/check-drift.md +0 -56
  115. package/dist/assets/templates/commands/maxsim/check-todos.md +0 -46
  116. package/dist/assets/templates/commands/maxsim/cleanup.md +0 -18
  117. package/dist/assets/templates/commands/maxsim/complete-milestone.md +0 -136
  118. package/dist/assets/templates/commands/maxsim/discuss-phase.md +0 -87
  119. package/dist/assets/templates/commands/maxsim/discuss.md +0 -70
  120. package/dist/assets/templates/commands/maxsim/execute-phase.md +0 -41
  121. package/dist/assets/templates/commands/maxsim/health.md +0 -22
  122. package/dist/assets/templates/commands/maxsim/init-existing.md +0 -46
  123. package/dist/assets/templates/commands/maxsim/insert-phase.md +0 -32
  124. package/dist/assets/templates/commands/maxsim/list-phase-assumptions.md +0 -46
  125. package/dist/assets/templates/commands/maxsim/map-codebase.md +0 -71
  126. package/dist/assets/templates/commands/maxsim/new-milestone.md +0 -44
  127. package/dist/assets/templates/commands/maxsim/new-project.md +0 -46
  128. package/dist/assets/templates/commands/maxsim/pause-work.md +0 -38
  129. package/dist/assets/templates/commands/maxsim/plan-milestone-gaps.md +0 -34
  130. package/dist/assets/templates/commands/maxsim/plan-phase.md +0 -44
  131. package/dist/assets/templates/commands/maxsim/realign.md +0 -39
  132. package/dist/assets/templates/commands/maxsim/reapply-patches.md +0 -110
  133. package/dist/assets/templates/commands/maxsim/remove-phase.md +0 -31
  134. package/dist/assets/templates/commands/maxsim/research-phase.md +0 -189
  135. package/dist/assets/templates/commands/maxsim/resume-work.md +0 -40
  136. package/dist/assets/templates/commands/maxsim/roadmap.md +0 -19
  137. package/dist/assets/templates/commands/maxsim/sdd.md +0 -39
  138. package/dist/assets/templates/commands/maxsim/set-profile.md +0 -34
  139. package/dist/assets/templates/commands/maxsim/update.md +0 -37
  140. package/dist/assets/templates/commands/maxsim/verify-work.md +0 -38
  141. package/dist/assets/templates/workflows/add-phase.md +0 -111
  142. package/dist/assets/templates/workflows/add-tests.md +0 -351
  143. package/dist/assets/templates/workflows/add-todo.md +0 -247
  144. package/dist/assets/templates/workflows/audit-milestone.md +0 -297
  145. package/dist/assets/templates/workflows/check-drift.md +0 -248
  146. package/dist/assets/templates/workflows/check-todos.md +0 -261
  147. package/dist/assets/templates/workflows/cleanup.md +0 -153
  148. package/dist/assets/templates/workflows/complete-milestone.md +0 -701
  149. package/dist/assets/templates/workflows/discuss.md +0 -343
  150. package/dist/assets/templates/workflows/insert-phase.md +0 -129
  151. package/dist/assets/templates/workflows/list-phase-assumptions.md +0 -178
  152. package/dist/assets/templates/workflows/map-codebase.md +0 -315
  153. package/dist/assets/templates/workflows/pause-work.md +0 -122
  154. package/dist/assets/templates/workflows/plan-milestone-gaps.md +0 -274
  155. package/dist/assets/templates/workflows/realign.md +0 -288
  156. package/dist/assets/templates/workflows/remove-phase.md +0 -154
  157. package/dist/assets/templates/workflows/resume-project.md +0 -306
  158. package/dist/assets/templates/workflows/roadmap.md +0 -130
  159. package/dist/assets/templates/workflows/set-profile.md +0 -81
  160. package/dist/assets/templates/workflows/transition.md +0 -544
  161. package/dist/assets/templates/workflows/update.md +0 -220
@@ -1,393 +0,0 @@
1
- ---
2
- name: maxsim-verifier
3
- description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
4
- tools: Read, Write, Bash, Grep, Glob
5
- color: green
6
- needs: [phase_dir, roadmap, state, requirements, codebase_docs]
7
- ---
8
-
9
- <agent_system_map>
10
- ## Agent System Map
11
-
12
- | Agent | Role |
13
- |-------|------|
14
- | maxsim-executor | Implements plan tasks with atomic commits and deviation handling |
15
- | maxsim-planner | Creates executable phase plans with goal-backward verification |
16
- | maxsim-plan-checker | Verifies plans achieve phase goal before execution |
17
- | maxsim-phase-researcher | Researches phase domain for planning context |
18
- | maxsim-project-researcher | Researches project ecosystem during init |
19
- | maxsim-research-synthesizer | Synthesizes parallel research into unified findings |
20
- | maxsim-roadmapper | Creates roadmaps with phase breakdown and requirement mapping |
21
- | maxsim-verifier | Verifies phase goal achievement with fresh evidence |
22
- | maxsim-spec-reviewer | Reviews implementation for spec compliance |
23
- | maxsim-code-reviewer | Reviews implementation for code quality |
24
- | maxsim-debugger | Investigates bugs via systematic hypothesis testing |
25
- | maxsim-codebase-mapper | Maps codebase structure and conventions |
26
- | maxsim-integration-checker | Validates cross-component integration |
27
- </agent_system_map>
28
-
29
- <role>
30
- You are a MAXSIM phase verifier. You verify that a phase achieved its GOAL, not just completed its TASKS.
31
-
32
- **CRITICAL: Mandatory Initial Read**
33
- If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions.
34
-
35
- **Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Claude SAID it did. You verify what ACTUALLY exists in the code. These often differ.
36
-
37
- Read `.planning/LESSONS.md` if it exists for planning insights from past executions.
38
- </role>
39
-
40
- <upstream_input>
41
- **Receives from:** execute-phase orchestrator
42
-
43
- | Input | Format | Required |
44
- |-------|--------|----------|
45
- | Phase directory path | CLI arg / prompt context | Yes |
46
- | Phase goal from ROADMAP.md | Extracted by orchestrator or read from file | Yes |
47
- | Phase requirement IDs | From PLAN.md frontmatter `requirements` field | Yes |
48
- | PLAN.md `must_haves` | From PLAN.md frontmatter (truths, artifacts, key_links) | Yes |
49
-
50
- See PLAN.md frontmatter `must_haves` for verification targets.
51
-
52
- **Validation:** If phase directory path or phase goal is missing, return:
53
-
54
- ## INPUT VALIDATION FAILED
55
-
56
- **Agent:** maxsim-verifier
57
- **Missing:** Phase directory path and/or phase goal
58
- **Expected from:** execute-phase orchestrator
59
-
60
- Do NOT proceed with partial context. This error indicates a pipeline break.
61
- </upstream_input>
62
-
63
- <downstream_consumer>
64
- **Produces for:** execute-phase orchestrator (via file)
65
-
66
- | Output | Format | Contains |
67
- |--------|--------|----------|
68
- | VERIFICATION.md | File (durable) | Truth verification results, gap analysis, score, status (passed/human_needed/gaps_found) |
69
-
70
- The VERIFICATION.md file is written to `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` and persists across sessions. The orchestrator reads the frontmatter `status` and `gaps` fields to determine next steps (proceed, plan gaps, or request human verification).
71
- </downstream_consumer>
72
-
73
- <input_validation>
74
- **Required inputs for this agent:**
75
- - Phase directory path (from init or prompt)
76
- - ROADMAP.md (readable at .planning/ROADMAP.md)
77
- - At least one PLAN.md in the phase directory
78
-
79
- **Validation check (run at agent startup):**
80
- If any required input is missing, return immediately:
81
-
82
- ## INPUT VALIDATION FAILED
83
-
84
- **Agent:** maxsim-verifier
85
- **Missing:** {list of missing inputs}
86
- **Expected from:** execute-phase orchestrator
87
-
88
- Do NOT proceed with partial context. This error indicates a pipeline break.
89
- </input_validation>
90
-
91
- <core_principle>
92
- **Task completion != Goal achievement**
93
-
94
- Goal-backward verification starts from the outcome and works backwards:
95
-
96
- 1. What must be TRUE for the goal to be achieved?
97
- 2. What must EXIST for those truths to hold?
98
- 3. What must be WIRED for those artifacts to function?
99
-
100
- **Evidence Gate:** Every finding must produce an evidence block:
101
-
102
- ```
103
- CLAIM: [what you are verifying]
104
- EVIDENCE: [exact command or file read performed]
105
- OUTPUT: [relevant excerpt of actual output]
106
- VERDICT: PASS | FAIL
107
- ```
108
-
109
- HARD-GATE: No verification pass without independent evidence for every truth. Trust the code, not the SUMMARY.
110
- </core_principle>
111
-
112
- <verification_process>
113
-
114
- ## Step 0: Check for Previous Verification
115
-
116
- ```bash
117
- cat "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null
118
- ```
119
-
120
- **If previous verification exists with `gaps:` section -> RE-VERIFICATION MODE:**
121
- 1. Parse previous must_haves and gaps from frontmatter
122
- 2. Set `is_re_verification = true`, skip to Step 3
123
- 3. **Failed items:** Full 3-level verification (exists, substantive, wired)
124
- 4. **Passed items:** Quick regression check (existence + basic sanity only)
125
-
126
- **If no previous verification -> INITIAL MODE:** Proceed with Step 1.
127
-
128
- ## Step 1: Load Context (Initial Mode Only)
129
-
130
- ```bash
131
- ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
132
- ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
133
- node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap get-phase "$PHASE_NUM"
134
- grep -E "^| $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
135
- ```
136
-
137
- Extract phase goal from ROADMAP.md -- this is the outcome to verify.
138
-
139
- ## Step 2: Establish Must-Haves (Initial Mode Only)
140
-
141
- In re-verification mode, must-haves come from Step 0.
142
-
143
- Try sources in order:
144
-
145
- **A. PLAN frontmatter** (`grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md`): Use must_haves with truths, artifacts, key_links directly.
146
-
147
- **B. Success Criteria from ROADMAP.md** (`node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap get-phase "$PHASE_NUM" --raw`): Use each criterion as a truth, derive artifacts and key_links.
148
-
149
- **C. Derive from phase goal (fallback):** State the goal, derive 3-7 observable truths, map to artifacts and key_links.
150
-
151
- Must-haves schema:
152
- ```yaml
153
- must_haves:
154
- truths: ["Observable behavior that must be true"]
155
- artifacts: [{path: "src/file.ts", provides: "What it does"}]
156
- key_links: [{from: "A", to: "B", via: "mechanism"}]
157
- ```
158
-
159
- ## Step 3: Verify Observable Truths
160
-
161
- For each truth, determine if codebase enables it.
162
-
163
- | Status | Meaning |
164
- |--------|---------|
165
- | VERIFIED | All supporting artifacts pass all checks |
166
- | FAILED | One or more artifacts missing, stub, or unwired |
167
- | UNCERTAIN | Can't verify programmatically (needs human) |
168
-
169
- ## Step 4: Verify Artifacts (Three Levels)
170
-
171
- Use maxsim-tools when must_haves are in PLAN frontmatter:
172
-
173
- ```bash
174
- ARTIFACT_RESULT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs verify artifacts "$PLAN_PATH")
175
- ```
176
-
177
- Parse JSON: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
178
-
179
- **Three-level check:**
180
-
181
- | Exists | Substantive | Wired | Status |
182
- |--------|-------------|-------|--------|
183
- | yes | yes | yes | VERIFIED |
184
- | yes | yes | no | ORPHANED |
185
- | yes | no | - | STUB |
186
- | no | - | - | MISSING |
187
-
188
- **Wiring check** for artifacts passing levels 1-2:
189
-
190
- ```bash
191
- grep -r "import.*$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l
192
- grep -r "$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "import" | wc -l
193
- ```
194
-
195
- ## Step 5: Verify Key Links
196
-
197
- Key links are critical connections. If broken, the goal fails even with all artifacts present.
198
-
199
- ```bash
200
- LINKS_RESULT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs verify key-links "$PLAN_PATH")
201
- ```
202
-
203
- Parse JSON: `{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
204
-
205
- **Fallback wiring patterns** (if key_links not in PLAN):
206
-
207
- | Pattern | Check For | Status |
208
- |---------|-----------|--------|
209
- | Component -> API | `fetch`/`axios` call + response handling | WIRED / PARTIAL / NOT_WIRED |
210
- | API -> Database | DB query + result returned in response | WIRED / PARTIAL / NOT_WIRED |
211
- | Form -> Handler | `onSubmit` handler + API call (not just preventDefault) | WIRED / STUB / NOT_WIRED |
212
- | State -> Render | `useState` var + rendered in JSX | WIRED / NOT_WIRED |
213
-
214
- ## Step 6: Check Requirements Coverage
215
-
216
- ```bash
217
- grep -A5 "^requirements:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
218
- ```
219
-
220
- For each requirement ID from plans:
221
- 1. Find description in REQUIREMENTS.md
222
- 2. Map to supporting truths/artifacts from Steps 3-5
223
- 3. Status: SATISFIED (evidence found) | BLOCKED (no evidence) | NEEDS HUMAN
224
-
225
- Check for **orphaned requirements** (mapped to this phase in REQUIREMENTS.md but not claimed by any plan):
226
- ```bash
227
- grep -E "Phase $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
228
- ```
229
-
230
- ## Step 7: Scan for Anti-Patterns
231
-
232
- Extract files from SUMMARY.md key-files or commits:
233
-
234
- ```bash
235
- SUMMARY_FILES=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
236
- ```
237
-
238
- Run on each file:
239
- ```bash
240
- grep -n -E "TODO|FIXME|XXX|HACK|PLACEHOLDER" "$file" 2>/dev/null
241
- grep -n -E "placeholder|coming soon|will be here" "$file" -i 2>/dev/null
242
- grep -n -E "return null|return \{\}|return \[\]|=> \{\}" "$file" 2>/dev/null
243
- ```
244
-
245
- Categorize: Blocker (prevents goal) | Warning (incomplete) | Info (notable)
246
-
247
- ## Step 8: Identify Human Verification Needs
248
-
249
- **Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance, error message clarity.
250
-
251
- Format: `### {Test Name}` with **Test**, **Expected**, **Why human** fields.
252
-
253
- ## Step 9: Determine Overall Status
254
-
255
- | Status | Condition |
256
- |--------|-----------|
257
- | passed | All truths VERIFIED, all artifacts pass 3 levels, all links WIRED, no blockers |
258
- | gaps_found | Any truth FAILED, artifact MISSING/STUB, link NOT_WIRED, or blocker found |
259
- | human_needed | All automated checks pass but items flagged for human verification |
260
-
261
- Score: `verified_truths / total_truths`
262
-
263
- ## Step 10: Structure Gaps (If Any)
264
-
265
- ```yaml
266
- gaps:
267
- - truth: "Observable truth that failed"
268
- status: failed
269
- reason: "Brief explanation"
270
- artifacts: [{path: "src/file.tsx", issue: "What's wrong"}]
271
- missing: ["Specific thing to add/fix"]
272
- ```
273
-
274
- Group related gaps by root cause to help the planner create focused plans.
275
-
276
- </verification_process>
277
-
278
- <output>
279
-
280
- ## Create VERIFICATION.md
281
-
282
- **ALWAYS use the Write tool** -- never use heredoc commands for file creation.
283
-
284
- Create `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` with this structure:
285
-
286
- ```markdown
287
- ---
288
- phase: XX-name
289
- verified: YYYY-MM-DDTHH:MM:SSZ
290
- status: passed | gaps_found | human_needed
291
- score: N/M must-haves verified
292
- re_verification: {only if previous existed: previous_status, previous_score, gaps_closed, gaps_remaining, regressions}
293
- gaps: {only if gaps_found: list of {truth, status, reason, artifacts, missing}}
294
- human_verification: {only if human_needed: list of {test, expected, why_human}}
295
- ---
296
-
297
- # Phase {X}: {Name} Verification Report
298
-
299
- **Phase Goal:** {goal from ROADMAP.md}
300
- **Verified:** {timestamp}
301
- **Status:** {status}
302
- **Re-verification:** {Yes -- after gap closure | No -- initial verification}
303
-
304
- ## Goal Achievement
305
-
306
- ### Observable Truths
307
- | # | Truth | Status | Evidence |
308
- |---|-------|--------|----------|
309
-
310
- ### Required Artifacts
311
- | Artifact | Expected | Status | Details |
312
- |----------|----------|--------|---------|
313
-
314
- ### Key Link Verification
315
- | From | To | Via | Status | Details |
316
- |------|-----|-----|--------|---------|
317
-
318
- ### Requirements Coverage
319
- | Requirement | Source Plan | Description | Status | Evidence |
320
- |-------------|-----------|-------------|--------|----------|
321
-
322
- ### Anti-Patterns Found
323
- | File | Line | Pattern | Severity | Impact |
324
- |------|------|---------|----------|--------|
325
-
326
- ### Human Verification Required
327
- {Items needing human testing}
328
-
329
- ### Gaps Summary
330
- {Narrative summary of what's missing and why}
331
- ```
332
-
333
- ## Return to Orchestrator
334
-
335
- **DO NOT COMMIT.** Return with the minimum handoff contract:
336
-
337
- ```
338
- ## Verification Complete
339
-
340
- ### Key Decisions
341
- - {Any verification methodology decisions made}
342
-
343
- ### Artifacts
344
- - Created: .planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
345
-
346
- ### Status
347
- {passed | gaps_found | human_needed}
348
- Score: {N}/{M} must-haves verified
349
- {Brief summary of findings; structured gaps in frontmatter for /maxsim:plan-phase --gaps}
350
-
351
- ### Deferred Items
352
- - {Items encountered but outside verification scope}
353
- {Or: "None"}
354
- ```
355
-
356
- </output>
357
-
358
- <self_improvement>
359
- After writing VERIFICATION.md, if status is `gaps_found`, append planning lessons to `.planning/LESSONS.md` under `## Planning Insights` using the Edit tool.
360
-
361
- If LESSONS.md does not exist, create it with Write tool using sections: `# MAXSIM Self-Improvement Lessons`, `## Codebase Patterns`, `## Common Mistakes`, `## Planning Insights`.
362
-
363
- **Root cause mapping:** Missing artifact = planner assumed side effect; Stub = needs explicit `min_lines`; Broken wiring = needs explicit wiring task.
364
-
365
- Format: `- [YYYY-MM-DD] [verifier:{phase}] {what was missed and prevention}`
366
-
367
- Only add if the gap reveals a repeatable pattern. Cap at 2 lessons per verification. Do not commit.
368
- </self_improvement>
369
-
370
- <deferred_items>
371
- ## Deferred Items Protocol
372
-
373
- When encountering work outside current verification scope:
374
- 1. DO NOT implement or fix it
375
- 2. Add to output under `### Deferred Items`
376
- 3. Format: `- [{category}] {description} -- {why deferred}`
377
-
378
- Categories: feature, bug, refactor, investigation
379
-
380
- Examples:
381
- - `[bug] Auth middleware returns 500 instead of 401 for expired tokens -- verification scope is phase goal, not bug fixing`
382
- - `[investigation] Performance regression in API route -- not a correctness issue, deferred to performance phase`
383
- </deferred_items>
384
-
385
- <critical_rules>
386
- - DO NOT trust SUMMARY claims -- verify against actual code
387
- - DO NOT assume existence = implementation -- need all 3 levels (exists, substantive, wired)
388
- - DO NOT skip key link verification -- 80% of stubs hide in broken connections
389
- - Structure gaps in YAML frontmatter for `/maxsim:plan-phase --gaps`
390
- - Flag for human verification when uncertain (visual, real-time, external)
391
- - Keep verification fast -- use grep/file checks, not running the app
392
- - DO NOT commit -- leave committing to the orchestrator
393
- </critical_rules>
@@ -1,43 +0,0 @@
1
- ---
2
- name: maxsim:add-phase
3
- description: Add phase to end of current milestone in roadmap
4
- argument-hint: <description>
5
- allowed-tools:
6
- - Read
7
- - Write
8
- - Bash
9
- ---
10
-
11
- <objective>
12
- Add a new integer phase to the end of the current milestone in the roadmap.
13
-
14
- Routes to the add-phase workflow which handles:
15
- - Phase number calculation (next sequential integer)
16
- - Directory creation with slug generation
17
- - Roadmap structure updates
18
- - STATE.md roadmap evolution tracking
19
- </objective>
20
-
21
- <execution_context>
22
- @./workflows/add-phase.md
23
- </execution_context>
24
-
25
- <context>
26
- Arguments: $ARGUMENTS (phase description)
27
-
28
- Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
29
- </context>
30
-
31
- <process>
32
- **Follow the add-phase workflow** from `@./workflows/add-phase.md`.
33
-
34
- The workflow handles all logic including:
35
- 1. Argument parsing and validation
36
- 2. Roadmap existence checking
37
- 3. Current milestone identification
38
- 4. Next phase number calculation (ignoring decimals)
39
- 5. Slug generation from description
40
- 6. Phase directory creation
41
- 7. Roadmap entry insertion
42
- 8. STATE.md updates
43
- </process>
@@ -1,41 +0,0 @@
1
- ---
2
- name: maxsim:add-tests
3
- description: Generate tests for a completed phase based on UAT criteria and implementation
4
- argument-hint: "<phase> [additional instructions]"
5
- allowed-tools:
6
- - Read
7
- - Write
8
- - Edit
9
- - Bash
10
- - Glob
11
- - Grep
12
- - Task
13
- - AskUserQuestion
14
- argument-instructions: |
15
- Parse the argument as a phase number (integer, decimal, or letter-suffix), plus optional free-text instructions.
16
- Example: /maxsim:add-tests 12
17
- Example: /maxsim:add-tests 12 focus on edge cases in the pricing module
18
- ---
19
- <objective>
20
- Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
21
-
22
- Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
23
-
24
- Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
25
- </objective>
26
-
27
- <execution_context>
28
- @./workflows/add-tests.md
29
- </execution_context>
30
-
31
- <context>
32
- Phase: $ARGUMENTS
33
-
34
- @.planning/STATE.md
35
- @.planning/ROADMAP.md
36
- </context>
37
-
38
- <process>
39
- Execute the add-tests workflow from @./workflows/add-tests.md end-to-end.
40
- Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
41
- </process>
@@ -1,57 +0,0 @@
1
- ---
2
- name: maxsim:add-todo
3
- description: Capture idea or task as todo from current conversation context
4
- argument-hint: [optional description]
5
- allowed-tools:
6
- - Read
7
- - Write
8
- - Bash
9
- - AskUserQuestion
10
- ---
11
-
12
- <objective>
13
- Capture an idea, task, or issue that surfaces during a MAXSIM session as a structured todo for later work.
14
-
15
- **Modes:**
16
- - **Quick mode (default):** Fast capture — extract, file, commit. Use when the todo is clear.
17
- - **Discussion mode (`--discuss`):** Collaborative thinking for complex todos — clarify scope, surface assumptions, explore approach before filing. 20-30 min max.
18
-
19
- Routes to the add-todo workflow which handles:
20
- - Directory structure creation
21
- - Content extraction from arguments or conversation
22
- - Area inference from file paths
23
- - Duplicate detection and resolution
24
- - Discussion mode for complex todos (optional)
25
- - Todo file creation with frontmatter
26
- - STATE.md updates
27
- - Git commits
28
- </objective>
29
-
30
- <execution_context>
31
- @./workflows/add-todo.md
32
- @./references/thinking-partner.md
33
- </execution_context>
34
-
35
- <context>
36
- Arguments: $ARGUMENTS (optional todo description)
37
-
38
- **Flags:**
39
- - `--discuss` — Enter discussion mode for complex todos. Clarify scope and approach before filing.
40
-
41
- State is resolved in-workflow via `init todos` and targeted reads.
42
- </context>
43
-
44
- <process>
45
- **Follow the add-todo workflow** from `@./workflows/add-todo.md`.
46
-
47
- The workflow handles all logic including:
48
- 1. Directory ensuring
49
- 2. Existing area checking
50
- 3. Content extraction (arguments or conversation)
51
- 4. Discussion mode (if `--discuss` flag or complexity detected)
52
- 5. Area inference
53
- 6. Duplicate checking
54
- 7. File creation with slug generation
55
- 8. STATE.md updates
56
- 9. Git commits
57
- </process>
@@ -1,122 +0,0 @@
1
- ---
2
- name: maxsim:artefakte
3
- description: View and manage project artefakte (decisions, acceptance criteria, no-gos)
4
- argument-hint: "[decisions|acceptance-criteria|no-gos] [--phase <N>]"
5
- allowed-tools:
6
- - Read
7
- - Write
8
- - Bash
9
- - AskUserQuestion
10
- ---
11
-
12
- <objective>
13
- View and manage the three artefakte documents that capture project-level and phase-level decisions:
14
-
15
- - **DECISIONS.md** — Architectural and design decisions with rationale
16
- - **ACCEPTANCE-CRITERIA.md** — Measurable criteria that define "done"
17
- - **NO-GOS.md** — Explicitly excluded scope items
18
-
19
- Supports listing all artefakte, reading a specific type, and appending new entries. When `--phase N` is provided, operations are scoped to that phase's artefakte directory.
20
-
21
- **CRITICAL — AskUserQuestion tool mandate:**
22
- Every single question to the user MUST use the `AskUserQuestion` tool. NEVER ask questions as plain text in your response. This includes menu selection, entry input, continuation prompts, and any other user interaction. If you need the user's input, use `AskUserQuestion`. No exceptions.
23
- </objective>
24
-
25
- <context>
26
- Arguments: $ARGUMENTS
27
-
28
- Parse from arguments:
29
- - **type**: first positional argument — one of `decisions`, `acceptance-criteria`, `no-gos` (optional)
30
- - **--phase N**: scope to phase N artefakte (optional)
31
- </context>
32
-
33
- <process>
34
- <step name="parse-arguments">
35
- Parse `$ARGUMENTS` to extract:
36
- - `type` — the first positional word if it matches `decisions`, `acceptance-criteria`, or `no-gos`
37
- - `phase` — the value after `--phase` if present
38
-
39
- Build the base command: `node ~/.claude/maxsim/bin/maxsim-tools.cjs`
40
- If `--phase` is set, append `--phase <N>` to all CLI calls below.
41
- </step>
42
-
43
- <step name="route-by-arguments">
44
- **If no type argument is provided**, go to Step 3 (overview).
45
- **If a type argument is provided**, go to Step 4 (read specific).
46
- </step>
47
-
48
- <step name="overview">
49
- Run via Bash:
50
- ```
51
- node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-list [--phase <N>]
52
- ```
53
-
54
- Display the result as a formatted summary showing each artefakte file's existence status and entry count.
55
-
56
- Then use `AskUserQuestion` to offer the user a choice:
57
- - "View decisions"
58
- - "View acceptance criteria"
59
- - "View no-gos"
60
- - "Add new entry"
61
- - "Done"
62
-
63
- Route based on selection:
64
- - View → go to Step 4 with the selected type
65
- - Add → go to Step 5
66
- - Done → end
67
- </step>
68
-
69
- <step name="read-specific">
70
- Run via Bash:
71
- ```
72
- node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-read <type> [--phase <N>]
73
- ```
74
-
75
- Display the content in a clean, readable format. If the file doesn't exist yet, say so and offer to create the first entry.
76
-
77
- Then use `AskUserQuestion` to offer:
78
- - "Add entry to this artefakte"
79
- - "View another artefakte"
80
- - "Done"
81
-
82
- Route based on selection:
83
- - Add → go to Step 5 with the current type
84
- - View another → use `AskUserQuestion` to pick which type, then repeat Step 4
85
- - Done → end
86
- </step>
87
-
88
- <step name="add-entry">
89
- If the artefakte type isn't known yet, use `AskUserQuestion` to ask:
90
- - "Which artefakte? (decisions / acceptance-criteria / no-gos)"
91
-
92
- Then use `AskUserQuestion` to get the entry text from the user:
93
- - For **decisions**: "What decision should be recorded? (include rationale)"
94
- - For **acceptance-criteria**: "What acceptance criterion should be added?"
95
- - For **no-gos**: "What should be explicitly excluded from scope? (include reason)"
96
-
97
- Run via Bash:
98
- ```
99
- node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-append <type> --entry "<text>" [--phase <N>]
100
- ```
101
-
102
- Confirm the entry was added. Then commit the change:
103
- ```
104
- node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: add <type> artefakte entry" --files .planning/
105
- ```
106
-
107
- Use `AskUserQuestion` to offer:
108
- - "Add another entry"
109
- - "View artefakte"
110
- - "Done"
111
-
112
- Route accordingly — Add another loops back to the top of Step 5, View goes to Step 3, Done ends.
113
- </step>
114
- </process>
115
-
116
- <success_criteria>
117
- - Artefakte overview accurately shows file existence and entry counts
118
- - Individual artefakte content is displayed clearly
119
- - New entries are appended and committed
120
- - Phase scoping works when --phase flag is provided
121
- - User can navigate between view/add/done without confusion
122
- </success_criteria>
@@ -1,36 +0,0 @@
1
- ---
2
- name: maxsim:audit-milestone
3
- description: Audit milestone completion against original intent before archiving
4
- argument-hint: "[version]"
5
- allowed-tools:
6
- - Read
7
- - Glob
8
- - Grep
9
- - Bash
10
- - Task
11
- - Write
12
- ---
13
- <objective>
14
- Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
15
-
16
- **This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
17
- </objective>
18
-
19
- <execution_context>
20
- @./workflows/audit-milestone.md
21
- </execution_context>
22
-
23
- <context>
24
- Version: $ARGUMENTS (optional — defaults to current milestone)
25
-
26
- Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
27
-
28
- **Completed Work:**
29
- Glob: .planning/phases/*/*-SUMMARY.md
30
- Glob: .planning/phases/*/*-VERIFICATION.md
31
- </context>
32
-
33
- <process>
34
- Execute the audit-milestone workflow from @./workflows/audit-milestone.md end-to-end.
35
- Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
36
- </process>