mindsystem-cc 3.19.0 → 3.21.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 (83) hide show
  1. package/README.md +5 -6
  2. package/agents/ms-designer.md +5 -2
  3. package/agents/ms-mockup-designer.md +1 -1
  4. package/agents/ms-plan-writer.md +8 -1
  5. package/agents/ms-product-researcher.md +69 -0
  6. package/agents/ms-research-synthesizer.md +1 -1
  7. package/agents/ms-researcher.md +8 -8
  8. package/agents/ms-roadmapper.md +9 -13
  9. package/bin/install.js +68 -5
  10. package/commands/ms/add-phase.md +30 -18
  11. package/commands/ms/adhoc.md +1 -1
  12. package/commands/ms/audit-milestone.md +12 -12
  13. package/commands/ms/complete-milestone.md +25 -22
  14. package/commands/ms/config.md +202 -0
  15. package/commands/ms/design-phase.md +34 -29
  16. package/commands/ms/discuss-phase.md +26 -22
  17. package/commands/ms/doctor.md +22 -202
  18. package/commands/ms/execute-phase.md +18 -7
  19. package/commands/ms/help.md +46 -39
  20. package/commands/ms/insert-phase.md +29 -17
  21. package/commands/ms/new-milestone.md +42 -19
  22. package/commands/ms/new-project.md +88 -103
  23. package/commands/ms/plan-milestone-gaps.md +4 -5
  24. package/commands/ms/plan-phase.md +5 -3
  25. package/commands/ms/progress.md +2 -4
  26. package/commands/ms/research-phase.md +7 -12
  27. package/commands/ms/research-project.md +12 -12
  28. package/mindsystem/references/continuation-format.md +3 -3
  29. package/mindsystem/references/plan-format.md +11 -1
  30. package/mindsystem/references/principles.md +1 -1
  31. package/mindsystem/references/questioning.md +50 -8
  32. package/mindsystem/references/routing/audit-result-routing.md +12 -11
  33. package/mindsystem/references/routing/between-milestones-routing.md +2 -2
  34. package/mindsystem/references/routing/milestone-complete-routing.md +1 -1
  35. package/mindsystem/references/routing/next-phase-routing.md +4 -2
  36. package/mindsystem/templates/context.md +7 -6
  37. package/mindsystem/templates/milestone-archive.md +5 -5
  38. package/mindsystem/templates/milestone-context.md +1 -1
  39. package/mindsystem/templates/milestone.md +9 -9
  40. package/mindsystem/templates/project.md +70 -64
  41. package/mindsystem/templates/research-subagent-prompt.md +3 -3
  42. package/mindsystem/templates/roadmap-milestone.md +14 -14
  43. package/mindsystem/templates/roadmap.md +9 -7
  44. package/mindsystem/workflows/adhoc.md +1 -1
  45. package/mindsystem/workflows/complete-milestone.md +66 -107
  46. package/mindsystem/workflows/discuss-phase.md +137 -65
  47. package/mindsystem/workflows/doctor-fixes.md +273 -0
  48. package/mindsystem/workflows/execute-phase.md +7 -3
  49. package/mindsystem/workflows/execute-plan.md +6 -5
  50. package/mindsystem/workflows/map-codebase.md +2 -2
  51. package/mindsystem/workflows/mockup-generation.md +1 -1
  52. package/mindsystem/workflows/plan-phase.md +28 -3
  53. package/mindsystem/workflows/transition.md +20 -25
  54. package/mindsystem/workflows/verify-work.md +1 -1
  55. package/package.json +1 -1
  56. package/scripts/__pycache__/ms-tools.cpython-314.pyc +0 -0
  57. package/scripts/__pycache__/test_ms_tools.cpython-314-pytest-9.0.2.pyc +0 -0
  58. package/scripts/fixtures/scan-context/.planning/ROADMAP.md +16 -0
  59. package/scripts/fixtures/scan-context/.planning/adhoc/20260220-fix-token-SUMMARY.md +12 -0
  60. package/scripts/fixtures/scan-context/.planning/config.json +3 -0
  61. package/scripts/fixtures/scan-context/.planning/debug/resolved/token-bug.md +11 -0
  62. package/scripts/fixtures/scan-context/.planning/knowledge/auth.md +11 -0
  63. package/scripts/fixtures/scan-context/.planning/phases/02-infra/02-1-SUMMARY.md +20 -0
  64. package/scripts/fixtures/scan-context/.planning/phases/04-setup/04-1-SUMMARY.md +21 -0
  65. package/scripts/fixtures/scan-context/.planning/phases/05-auth/05-1-SUMMARY.md +28 -0
  66. package/scripts/fixtures/scan-context/.planning/todos/done/setup-db.md +10 -0
  67. package/scripts/fixtures/scan-context/.planning/todos/pending/add-logout.md +10 -0
  68. package/scripts/fixtures/scan-context/expected-output.json +257 -0
  69. package/scripts/ms-tools.py +2139 -0
  70. package/scripts/test_ms_tools.py +836 -0
  71. package/commands/ms/list-phase-assumptions.md +0 -56
  72. package/mindsystem/workflows/list-phase-assumptions.md +0 -178
  73. package/scripts/__pycache__/compare_mockups.cpython-314.pyc +0 -0
  74. package/scripts/archive-milestone-files.sh +0 -68
  75. package/scripts/archive-milestone-phases.sh +0 -138
  76. package/scripts/doctor-scan.sh +0 -379
  77. package/scripts/gather-milestone-stats.sh +0 -179
  78. package/scripts/generate-adhoc-patch.sh +0 -79
  79. package/scripts/generate-phase-patch.sh +0 -169
  80. package/scripts/scan-artifact-subsystems.sh +0 -55
  81. package/scripts/scan-planning-context.py +0 -839
  82. package/scripts/update-state.sh +0 -59
  83. package/scripts/validate-execution-order.sh +0 -104
@@ -13,11 +13,15 @@ allowed-tools:
13
13
  ---
14
14
 
15
15
  <objective>
16
- Run comprehensive health checks on project configuration. Detect and fix structural drift across 6 categories: subsystem vocabulary, milestone directory structure, phase archival, knowledge files, phase summaries, and PLAN cleanup.
16
+ Run health checks on project configuration. Detect and fix structural drift across 8 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, and CLI wrappers.
17
17
 
18
- Idempotent — safe to run repeatedly.
18
+ Idempotent.
19
19
  </objective>
20
20
 
21
+ <execution_context>
22
+ @~/.claude/mindsystem/workflows/doctor-fixes.md
23
+ </execution_context>
24
+
21
25
  <context>
22
26
  @.planning/config.json
23
27
  @.planning/MILESTONES.md
@@ -68,7 +72,7 @@ Proceed to next step.
68
72
  Run the diagnostic scan:
69
73
 
70
74
  ```bash
71
- ~/.claude/mindsystem/scripts/doctor-scan.sh
75
+ ms-tools doctor-scan
72
76
  ```
73
77
 
74
78
  Capture the full output. Parse each check's Status (PASS/FAIL/SKIP) and detail lines.
@@ -84,10 +88,12 @@ Display results as a markdown table:
84
88
  |--------------------------|--------|----------------------------------|
85
89
  | Subsystem vocabulary | PASS | 9 subsystems, all artifacts OK |
86
90
  | Milestone directories | FAIL | 2 flat files need restructuring |
91
+ | Milestone naming | FAIL | 2 version-prefixed dirs need migration |
87
92
  | Phase archival | FAIL | 8 orphaned phase directories |
88
93
  | Knowledge files | FAIL | Directory missing |
89
94
  | Phase summaries | FAIL | 2 milestones missing summaries |
90
95
  | PLAN cleanup | FAIL | 9 leftover PLAN.md files |
96
+ | CLI wrappers | FAIL | ms-tools not on PATH |
91
97
  ```
92
98
 
93
99
  Populate Result and Details from scan output. Use concise detail summaries.
@@ -109,210 +115,22 @@ If "Skip" → go to `report`.
109
115
 
110
116
  If "Review each" → use AskUserQuestion for each failed check with its details and options: "Fix" / "Skip". Only run fixes for accepted checks.
111
117
 
112
- Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
113
- </step>
114
-
115
- <step name="fix_subsystems">
116
- **Only if Subsystem Vocabulary failed.**
117
-
118
- If subsystems array is empty (State A):
119
-
120
- 1. Scan all artifacts for existing values:
121
-
122
- ```bash
123
- ~/.claude/mindsystem/scripts/scan-artifact-subsystems.sh --values-only
124
- ```
125
-
126
- 2. Read `.planning/PROJECT.md` and `.planning/ROADMAP.md`.
127
-
128
- 3. Derive 5-12 canonical subsystem identifiers from:
129
- - Unique values found in artifacts
130
- - Project domain from PROJECT.md
131
- - Phase structure from ROADMAP.md
132
-
133
- Rules:
134
- - Lowercase, single-word or hyphenated (e.g., "auth", "real-time", "ui")
135
- - Merge synonyms into one canonical value (pick shortest/most common)
136
- - Cover all existing usage plus obvious gaps
137
- - Include infrastructure-level subsystems if relevant (api, database, infra, testing)
138
-
139
- 4. Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
140
-
141
- 5. Use AskUserQuestion:
142
- - header: "Subsystems"
143
- - question: "These subsystems were derived from your project. Look good?"
144
- - options:
145
- - "Looks good" — accept and apply
146
- - "Add/remove some" — iterate on the list
147
- - "Start over" — re-derive from scratch
148
-
149
- 6. After confirmation: update `config.json` (subsystems as first field), standardize existing artifact `subsystem:` fields using Edit tool.
150
-
151
- If subsystems exist but artifacts have mismatches (State B):
152
-
153
- 1. Classify each artifact as OK/MISMATCH/MISSING.
154
- 2. For MISMATCH: propose closest canonical value.
155
- 3. For MISSING: propose based on artifact content/path.
156
- 4. Apply fixes using Edit tool.
157
-
158
- Commit:
159
-
160
- ```bash
161
- git add .planning/config.json
162
- git add .planning/phases/*/*-SUMMARY.md 2>/dev/null
163
- git add .planning/adhoc/*-SUMMARY.md 2>/dev/null
164
- git add .planning/debug/*.md 2>/dev/null
165
- git add .planning/debug/resolved/*.md 2>/dev/null
166
- git add .planning/todos/pending/*.md 2>/dev/null
167
- git add .planning/todos/done/*.md 2>/dev/null
168
- ```
169
-
170
- ```bash
171
- git commit -m "$(cat <<'EOF'
172
- chore(doctor): fix subsystem vocabulary
173
-
174
- Standardized subsystem configuration and artifact values.
175
- EOF
176
- )"
177
- ```
178
- </step>
179
-
180
- <step name="fix_milestone_dirs">
181
- **Only if Milestone Directory Structure failed.**
182
-
183
- For each flat file like `milestones/v0.1-ROADMAP.md`:
184
-
185
- 1. Extract version prefix (e.g., `v0.1`).
186
- 2. Create versioned directory if it doesn't exist: `mkdir -p .planning/milestones/v0.1`
187
- 3. `git mv` the file, stripping the version prefix from the filename:
188
- `git mv .planning/milestones/v0.1-ROADMAP.md .planning/milestones/v0.1/ROADMAP.md`
189
-
190
- Commit:
191
-
192
- ```bash
193
- git add .planning/milestones/
194
- ```
195
-
196
- ```bash
197
- git commit -m "$(cat <<'EOF'
198
- chore(doctor): restructure milestone directories
199
-
200
- Moved flat milestone files into versioned directories.
201
- EOF
202
- )"
203
- ```
204
- </step>
205
-
206
- <step name="fix_phase_archival">
207
- **Only if Phase Archival failed.**
208
-
209
- Parse MILESTONES.md for completed milestones and their phase ranges (`**Phases completed:** X-Y`).
210
-
211
- For each completed milestone with orphaned phases in `.planning/phases/`:
212
-
213
- 1. Determine the version and phase range from MILESTONES.md.
214
- 2. Ensure the milestone directory exists: `mkdir -p .planning/milestones/{version}`
215
- 3. Run the archive script:
216
-
217
- ```bash
218
- ~/.claude/mindsystem/scripts/archive-milestone-phases.sh <start> <end> <version>
219
- ```
220
-
221
- This simultaneously:
222
- - Consolidates PHASE-SUMMARIES.md (fixes Phase Summaries check)
223
- - Deletes raw artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION)
224
- - Moves phase directories to milestone archive
118
+ Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
225
119
 
226
- **If MILESTONES.md doesn't have parseable phase ranges:** Use AskUserQuestion to ask the user for the phase range for each milestone.
227
-
228
- After archive completes, clean up leftover PLAN files in archived phases (fixes PLAN Cleanup check):
229
-
230
- ```bash
231
- find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
232
- ```
233
-
234
- Commit:
235
-
236
- ```bash
237
- git add .planning/phases/ .planning/milestones/
238
- ```
239
-
240
- ```bash
241
- git commit -m "$(cat <<'EOF'
242
- chore(doctor): archive completed milestone phases
243
-
244
- Consolidated summaries, deleted raw artifacts, moved phase directories.
245
- EOF
246
- )"
247
- ```
120
+ Phase summaries are resolved by fix_phase_archival. CLI wrappers require manual PATH configuration (no automated fix).
248
121
  </step>
249
122
 
250
- <step name="fix_plan_cleanup">
251
- **Only if PLAN Cleanup failed AND fix_phase_archival did not already handle it.**
252
-
253
- Delete leftover PLAN files in completed phase directories:
254
-
255
- ```bash
256
- find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
257
- ```
258
-
259
- For any leftover PLANs in `phases/` belonging to completed milestones (identified by the scan), delete those too.
260
-
261
- Commit:
262
-
263
- ```bash
264
- git add .planning/
265
- ```
266
-
267
- ```bash
268
- git commit -m "$(cat <<'EOF'
269
- chore(doctor): clean up leftover PLAN files
270
-
271
- Removed PLAN files from completed phase directories.
272
- EOF
273
- )"
274
- ```
275
- </step>
276
-
277
- <step name="fix_knowledge">
278
- **Only if Knowledge Files failed.**
279
-
280
- Spawn a `general-purpose` subagent (Task tool) to generate knowledge files retroactively. Provide the subagent with:
281
-
282
- - Subsystem vocabulary from config.json
283
- - Instructions to read all PHASE-SUMMARIES.md from `milestones/*/PHASE-SUMMARIES.md` AND any remaining SUMMARY files in `phases/`
284
- - The knowledge template at `~/.claude/mindsystem/templates/knowledge.md`
285
- - Instructions to read any existing knowledge files and merge (rewrite semantics — current state, not append)
286
- - Instructions to create `.planning/knowledge/` directory if missing
287
- - Instructions to write `.planning/knowledge/{subsystem}.md` for each missing subsystem
288
-
289
- After subagent completes, verify files exist:
290
-
291
- ```bash
292
- ls .planning/knowledge/*.md
293
- ```
294
-
295
- Commit:
296
-
297
- ```bash
298
- git add .planning/knowledge/
299
- ```
300
-
301
- ```bash
302
- git commit -m "$(cat <<'EOF'
303
- chore(doctor): generate knowledge files
304
-
305
- Created per-subsystem knowledge files from phase summaries.
306
- EOF
307
- )"
308
- ```
123
+ <step name="apply_fixes">
124
+ Execute fix steps from doctor-fixes workflow in dependency order. For "Fix all": run all
125
+ applicable steps. For "Review each": run only user-accepted steps. Skip any step whose
126
+ check passed.
309
127
  </step>
310
128
 
311
129
  <step name="verify">
312
130
  Re-run the diagnostic scan:
313
131
 
314
132
  ```bash
315
- ~/.claude/mindsystem/scripts/doctor-scan.sh
133
+ ms-tools doctor-scan
316
134
  ```
317
135
 
318
136
  All checks should now PASS. If any still fail, report which checks remain and why.
@@ -328,10 +146,12 @@ Final summary table:
328
146
  |--------------------------|--------|----------------------------------|
329
147
  | Subsystem vocabulary | PASS | ... |
330
148
  | Milestone directories | PASS | ... |
149
+ | Milestone naming | PASS | ... |
331
150
  | Phase archival | PASS | ... |
332
151
  | Knowledge files | PASS | ... |
333
152
  | Phase summaries | PASS | ... |
334
153
  | PLAN cleanup | PASS | ... |
154
+ | CLI wrappers | PASS | ... |
335
155
 
336
156
  All checks passed.
337
157
  ```
@@ -342,11 +162,11 @@ Include counts: checks total, passed, fixed during this run.
342
162
  </process>
343
163
 
344
164
  <success_criteria>
345
- - [ ] Each fix group committed atomically
346
- - [ ] Re-scan verifies all checks pass after fixes
347
165
  - [ ] User confirms fix strategy before changes (Fix all / Review each / Skip)
348
- - [ ] Fixes applied in dependency order: subsystems → dirs → archival → cleanup → knowledge
349
166
  - [ ] Results displayed as markdown table before any action
350
- - [ ] All 6 categories reported with PASS/FAIL/SKIP
167
+ - [ ] Re-scan verifies all checks pass after fixes
168
+ - [ ] Each fix group committed atomically
169
+ - [ ] Fixes applied in dependency order: subsystems → dirs → milestone naming → archival → cleanup → knowledge
170
+ - [ ] All 8 categories reported with PASS/FAIL/SKIP
351
171
  - [ ] Clean project reports all PASS with no fix prompts
352
172
  </success_criteria>
@@ -30,10 +30,9 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
30
30
  <context>
31
31
  Phase: $ARGUMENTS
32
32
 
33
- **Normalize phase number:**
33
+ **Resolve phase:**
34
34
  ```bash
35
- PHASE_ARG="$ARGUMENTS"
36
- PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
35
+ ms-tools find-phase "$ARGUMENTS"
37
36
  ```
38
37
 
39
38
  @.planning/ROADMAP.md
@@ -53,7 +52,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
53
52
  - Build list of incomplete plans
54
53
 
55
54
  3. **Validate and read execution order**
56
- - Run `validate-execution-order.sh` on phase directory
55
+ - Run `ms-tools validate-execution-order` on phase directory
57
56
  - Parse EXECUTION-ORDER.md wave structure
58
57
  - Report wave structure to user
59
58
 
@@ -62,7 +61,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
62
61
  - Spawn `ms-executor` for each plan in wave (parallel Task calls)
63
62
  - Wait for completion (Task blocks)
64
63
  - Verify SUMMARYs created
65
- - Run `update-state.sh` to update plan progress
64
+ - Run `ms-tools update-state` to update plan progress
66
65
  - Proceed to next wave
67
66
 
68
67
  5. **Aggregate results**
@@ -85,7 +84,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
85
84
  - If changes made: commit as `refactor({phase}): code review improvements`
86
85
 
87
86
  8. **Generate phase patch**
88
- - Run: `~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}`
87
+ - Run: `ms-tools generate-phase-patch ${PHASE_NUMBER}`
89
88
  - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`
90
89
  - Verify: patch file exists OR skip message logged
91
90
  - Note: Patch captures all changes including simplifications
@@ -127,7 +126,19 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
127
126
  <offer_next>
128
127
  **MANDATORY: Present copy/paste-ready next command.**
129
128
 
130
- After verification completes, route based on status:
129
+ After verification completes:
130
+
131
+ **First, surface user actions from all SUMMARYs:**
132
+
133
+ Extract `## User Actions Required` sections from all `*-SUMMARY.md` files in the phase directory. If any contain actions (not "None"), present before route-specific content:
134
+
135
+ ```
136
+ ## ⚠ Action Required
137
+
138
+ {Consolidated list from all SUMMARYs — deduplicate if overlapping}
139
+ ```
140
+
141
+ Then route based on status:
131
142
 
132
143
  | Status | Route |
133
144
  |--------|-------|
@@ -22,24 +22,25 @@ Output ONLY the reference content below. Do NOT add:
22
22
  ## Start Here
23
23
 
24
24
  - If you already have `.planning/` in this repo: run `/ms:progress`.
25
- - If you’re starting in an existing codebase (brownfield): run `/ms:map-codebase`, then `/ms:new-project`.
26
25
  - Otherwise: run `/ms:new-project`.
27
26
 
28
27
  ## Quick Start
29
28
 
30
29
  ### Greenfield (new project)
31
30
 
32
- 1. `/ms:new-project` - Initialize project with brief
33
- 2. `/ms:research-project` - (optional) Research domain ecosystem
34
- 3. `/ms:create-roadmap` - Define requirements and create roadmap
35
- 4. `/ms:plan-phase 1` - Create detailed plan for first phase
36
- 5. `/ms:execute-phase 1` - Execute with parallel agents
31
+ 1. `/ms:new-project` Initialize project with brief
32
+ 2. `/ms:config` (optional) Configure code reviewers and gitignore
33
+ 3. `/ms:research-project` (optional) Research domain ecosystem
34
+ 4. `/ms:create-roadmap` Define requirements and create roadmap
35
+ 5. `/ms:plan-phase 1` Create detailed plan for first phase
36
+ 6. `/ms:execute-phase 1` — Execute with parallel agents
37
37
 
38
38
  ### Brownfield (existing codebase)
39
39
 
40
- 1. `/ms:map-codebase` - Analyze existing code first
41
- 2. `/ms:new-project` - Questions focus on what you’re adding/changing
42
- 3. Continue with steps 2-5 above (codebase docs load automatically)
40
+ 1. `/ms:new-project` Questions focus on business context and vision
41
+ 2. `/ms:map-codebase` Analyze existing code
42
+ 3. `/ms:config` (optional) Configure code reviewers and gitignore
43
+ 4. Continue with research/roadmap/plan/execute
43
44
 
44
45
  ## Staying Updated
45
46
 
@@ -62,8 +63,8 @@ Initialize → (Optional Research) → Roadmap → Plan → Execute → Verify
62
63
  ```
63
64
 
64
65
  Common deviations:
65
- - Existing repo: `/ms:map-codebase` before `/ms:new-project`
66
- - Plan looks wrong: `/ms:list-phase-assumptions <phase>` or `/ms:check-phase <phase>`
66
+ - Existing repo: `/ms:map-codebase` after `/ms:new-project` (or before — either works)
67
+ - Plan looks wrong: `/ms:discuss-phase <phase>` or `/ms:check-phase <phase>`
67
68
  - Unknown domain: `/ms:research-project` or `/ms:research-phase <phase>`
68
69
  - Phase prep: `/ms:discuss-phase` → `/ms:design-phase` → `/ms:research-phase` → `/ms:plan-phase` (all optional before plan)
69
70
  - Execution gaps: `/ms:plan-phase <phase> --gaps` then `/ms:execute-phase <phase>`
@@ -82,6 +83,16 @@ Initialize new project with brief and configuration.
82
83
 
83
84
  Usage: `/ms:new-project`
84
85
 
86
+ **`/ms:config`**
87
+ Configure Mindsystem preferences — code reviewers, gitignore patterns, git remote.
88
+
89
+ - Use when: you want to set up code review agents, manage which .planning/ artifacts are git-ignored, or push your repo to GitHub.
90
+ - Edits `.planning/config.json` and `.gitignore`
91
+ - Suggests code reviewers based on tech stack (needs PROJECT.md)
92
+ - Idempotent — run anytime to reconfigure
93
+
94
+ Usage: `/ms:config`
95
+
85
96
  **`/ms:research-project`**
86
97
  Research domain ecosystem before creating roadmap.
87
98
 
@@ -111,18 +122,20 @@ Map an existing codebase for brownfield projects.
111
122
  - Analyzes codebase with parallel Explore agents
112
123
  - Creates `.planning/codebase/` with 7 focused documents
113
124
  - Covers stack, architecture, structure, conventions, testing, integrations, concerns
114
- - Use before `/ms:new-project` on existing codebases
125
+ - Use on existing codebases (before or after `/ms:new-project`)
115
126
 
116
127
  Usage: `/ms:map-codebase`
117
128
 
118
129
  ### Phase Planning
119
130
 
120
131
  **`/ms:discuss-phase <number>`**
121
- Help articulate your vision for a phase before planning.
132
+ Product-informed collaborative thinking before planning.
122
133
 
123
- - Captures how you imagine this phase working
124
- - Creates CONTEXT.md with your vision, essentials, and boundaries
125
- - Use when you have ideas about how something should look/feel
134
+ - Loads milestone artifacts (PROJECT.md, REQUIREMENTS.md) for product context
135
+ - Surfaces Claude's assumptions and validates before deep questioning
136
+ - Offers competitor/UX research for user-facing phases
137
+ - Grounds every question in target audience, industry patterns, and tradeoffs
138
+ - Creates CONTEXT.md with your vision, essentials, and reasoning-backed decisions
126
139
 
127
140
  Usage: `/ms:discuss-phase 2`
128
141
 
@@ -160,15 +173,6 @@ Comprehensive ecosystem research for niche/complex domains.
160
173
 
161
174
  Usage: `/ms:research-phase 3`
162
175
 
163
- **`/ms:list-phase-assumptions <number>`**
164
- See what Claude is planning to do before it starts.
165
-
166
- - Shows Claude's intended approach for a phase
167
- - Lets you course-correct if Claude misunderstood your vision
168
- - No files created - conversational output only
169
-
170
- Usage: `/ms:list-phase-assumptions 3`
171
-
172
176
  **`/ms:plan-phase [number] [--gaps]`**
173
177
  Create detailed execution plan for a specific phase.
174
178
 
@@ -221,7 +225,7 @@ User acceptance testing of phase or plan.
221
225
 
222
226
  Usage: `/ms:verify-work 5`
223
227
 
224
- **`/ms:audit-milestone [version]`**
228
+ **`/ms:audit-milestone [name]`**
225
229
  Audit milestone completion against original intent.
226
230
 
227
231
  - Use when: you think you’re “done” and want cross-phase integration + requirements coverage checked before archiving.
@@ -230,7 +234,7 @@ Audit milestone completion against original intent.
230
234
  - Maintains TECH-DEBT.md as single source of truth for debt items
231
235
  - Creates MILESTONE-AUDIT.md with gaps and tech debt
232
236
 
233
- Usage: `/ms:audit-milestone 1.0.0`
237
+ Usage: `/ms:audit-milestone`
234
238
 
235
239
  ### Roadmap Management
236
240
 
@@ -280,18 +284,19 @@ Discover what to build next and start a new milestone.
280
284
  - Routes to create-roadmap or research-project
281
285
 
282
286
  Usage: `/ms:new-milestone`
283
- Usage: `/ms:new-milestone "v2.0 Features"`
287
+ Usage: `/ms:new-milestone "Push Notifications"`
284
288
 
285
- **`/ms:complete-milestone <version>`**
286
- Archive completed milestone and prepare for next version.
289
+ **`/ms:complete-milestone [name]`**
290
+ Archive completed milestone and prepare for next.
287
291
 
288
292
  - Creates MILESTONES.md entry with stats
289
293
  - Extracts curated learnings for future milestone planning
290
294
  - Archives full details to milestones/ directory
291
- - Creates git tag for the release
292
- - Prepares workspace for next version
295
+ - Prepares workspace for next milestone
296
+ - Auto-detects current milestone from PROJECT.md if no argument provided
293
297
 
294
- Usage: `/ms:complete-milestone 1.0.0`
298
+ Usage: `/ms:complete-milestone`
299
+ Usage: `/ms:complete-milestone "MVP"`
295
300
 
296
301
  **`/ms:plan-milestone-gaps`**
297
302
  Create phases to close gaps identified by milestone audit.
@@ -443,6 +448,7 @@ Usage: `/ms:release-notes`
443
448
 
444
449
  ```
445
450
  /ms:new-project # Extract your idea through questions
451
+ /ms:config # (optional) Configure code reviewers and gitignore
446
452
  /ms:research-project # (recommended) Research domain ecosystem
447
453
  /ms:create-roadmap # Define requirements and create phases
448
454
  /ms:plan-phase 1 # Create detailed plan
@@ -452,8 +458,9 @@ Usage: `/ms:release-notes`
452
458
  **Starting with existing code (brownfield):**
453
459
 
454
460
  ```
455
- /ms:map-codebase # Step 1: Analyze existing code
456
- /ms:new-project # Step 2: Questions focus on what you're adding/changing
461
+ /ms:new-project # Step 1: Questions focus on business context and vision
462
+ /ms:map-codebase # Step 2: Analyze existing code
463
+ /ms:config # (optional) Configure code reviewers and gitignore
457
464
  /ms:research-project # (optional) Research new domain areas
458
465
  /ms:create-roadmap # Define requirements and create roadmap
459
466
  /ms:plan-phase 1 # Codebase docs load automatically
@@ -517,19 +524,19 @@ Common options:
517
524
  **Completing a milestone:**
518
525
 
519
526
  ```
520
- /ms:audit-milestone 1.0.0 # Verify before completing
521
- /ms:complete-milestone 1.0.0 # Archive and tag
527
+ /ms:audit-milestone # Verify before completing
528
+ /ms:complete-milestone # Archive milestone
522
529
  /ms:new-milestone # Discover and start next milestone
523
530
  ```
524
531
 
525
532
  **Closing gaps from audit:**
526
533
 
527
534
  ```
528
- /ms:audit-milestone 1.0.0 # Finds gaps
535
+ /ms:audit-milestone # Finds gaps
529
536
  /ms:plan-milestone-gaps # Creates phases to fix them
530
537
  /ms:plan-phase 6 # Plan first gap closure phase
531
538
  /ms:execute-phase 6
532
- /ms:audit-milestone 1.0.0 # Re-audit when done
539
+ /ms:audit-milestone # Re-audit when done
533
540
  ```
534
541
 
535
542
  **Capturing ideas during work:**
@@ -133,13 +133,36 @@ Confirm: "Created directory: $phase_dir"
133
133
  Insert the new phase entry into the roadmap:
134
134
 
135
135
  1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
136
- 2. Insert new phase heading with (INSERTED) marker:
136
+
137
+ 2. Before writing the phase entry, analyze the description to determine pre-work flags:
138
+
139
+ **Discuss**: Default Likely — enumerate 2-4 assumptions or open questions specific
140
+ to the phase. Unlikely only for fully mechanical zero-decision work (version bump,
141
+ rename-only refactor, config-only change, pure deletion/cleanup).
142
+
143
+ **Design**: Likely when description involves UI work, visual elements, forms,
144
+ dashboards, or multi-screen flows. Unlikely for backend-only, API, infrastructure,
145
+ or established UI patterns.
146
+
147
+ **Research**: Likely when description mentions external APIs/services, new
148
+ libraries/frameworks, or unclear technical approach. Unlikely for established
149
+ internal patterns or well-documented conventions.
150
+
151
+ Use binary Likely/Unlikely with parenthetical reason. Include topics/focus only when Likely.
152
+
153
+ 3. Insert new phase heading with (INSERTED) marker and pre-work flags:
137
154
 
138
155
  ```
139
156
  ### Phase {decimal_phase}: {Description} (INSERTED)
140
157
 
141
158
  **Goal:** [Urgent work - to be planned]
142
159
  **Depends on:** Phase {after_phase}
160
+ **Discuss**: {Likely (reason) | Unlikely (reason)}
161
+ **Discuss topics**: {topics} ← only if Likely
162
+ **Design**: {Likely (reason) | Unlikely (reason)}
163
+ **Design focus**: {focus} ← only if Likely
164
+ **Research**: {Likely (reason) | Unlikely (reason)}
165
+ **Research topics**: {topics} ← only if Likely
143
166
  **Plans:** 0 plans
144
167
 
145
168
  Plans:
@@ -149,7 +172,7 @@ Insert the new phase entry into the roadmap:
149
172
  [To be added during planning]
150
173
  ```
151
174
 
152
- 3. Write updated roadmap back to file
175
+ 4. Write updated roadmap back to file
153
176
 
154
177
  The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
155
178
 
@@ -183,24 +206,13 @@ Phase {decimal_phase} inserted after Phase {after_phase}:
183
206
  Roadmap updated: {roadmap-path}
184
207
  Project state updated: .planning/STATE.md
185
208
 
186
- ---
187
-
188
- ## ▶ Next Up
189
-
190
- **Phase {decimal_phase}: {description}** — urgent insertion
191
-
192
- `/ms:plan-phase {decimal_phase}`
193
-
194
- <sub>`/clear` first → fresh context window</sub>
209
+ ```
195
210
 
196
- ---
211
+ Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions
212
+ to present "Next Up" with pre-work context for Phase {decimal_phase}.
197
213
 
198
- **Also available:**
214
+ After the "Next Up" section, add:
199
215
  - Review insertion impact: Check if Phase {next_integer} dependencies still make sense
200
- - Review roadmap
201
-
202
- ---
203
- ```
204
216
  </step>
205
217
 
206
218
  <step name="update_last_command">