mindsystem-cc 4.4.1 → 4.4.2

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.
package/README.md CHANGED
@@ -31,6 +31,7 @@ Then `/ms:new-project` to initialize. See the [full walkthrough](#end-to-end-wal
31
31
 
32
32
  ## What's new in v4.4
33
33
 
34
+ - **Knowledge quality gate** — consolidator and compounder filter extracted knowledge through signal density enforcement, eliminating noise entries that wouldn't change how an LLM implements code.
34
35
  - **User journey browser verification** — end-to-end click/fill/submit testing instead of screenshot-only observation. Catches unreachable pages with no navigation path from the UI.
35
36
  - **Single-plan mode (default)** — one plan per phase, eliminating multi-agent orchestration overhead with 1M context windows.
36
37
  - **Full phase specification** for add-phase and insert-phase — both commands now derive goal, success criteria, and requirements mapping.
@@ -25,6 +25,10 @@ You are a Mindsystem knowledge compounder spawned by the compound workflow to up
25
25
 
26
26
  </inputs>
27
27
 
28
+ <references>
29
+ @~/.claude/mindsystem/references/knowledge-quality.md
30
+ </references>
31
+
28
32
  <extraction_guide>
29
33
 
30
34
  ## What to Extract From Raw Changes
@@ -59,15 +63,19 @@ ls .planning/knowledge/*.md 2>/dev/null
59
63
 
60
64
  Read only the files matching confirmed affected subsystems. On first run, `.planning/knowledge/` may not exist — start fresh.
61
65
 
62
- ## Step 3: Extract Knowledge From Changes
66
+ ## Step 3: Classify and Extract Knowledge From Changes
67
+
68
+ Classify each change signal before extraction:
63
69
 
64
- Apply the extraction guide to the change content.
70
+ | Signal Type | Action |
71
+ |------------|--------|
72
+ | Decision with rationale (chose X over Y because Z) | Extract |
73
+ | Structural pattern (how components connect, data flows) | Extract |
74
+ | Non-obvious pitfall or gotcha | Extract |
75
+ | Code-derivable detail (schema fields, component props, config values) | Skip |
76
+ | Implementation description without alternative considered | Skip |
65
77
 
66
- Focus on:
67
- - **Decisions with rationale** — not just "used X" but "used X because Y"
68
- - **Structural patterns** — how components connect, data flows, API contracts
69
- - **Gotchas discovered** — failure modes, workarounds, non-obvious behavior
70
- - **Significant file changes** — new entry points, renamed modules, deleted code
78
+ Apply the extraction guide to change content that passes classification. Then apply the knowledge-quality.md filtering test — drop entries that fail. For entries that pass, check existing knowledge files for cross-subsystem duplication — use `(see {subsystem})` cross-references instead of duplicating.
71
79
 
72
80
  ## Step 4: Merge Into Existing Knowledge
73
81
 
@@ -81,6 +89,8 @@ For each affected subsystem, edit the knowledge file to reflect current state:
81
89
 
82
90
  Use `Edit` for existing files — targeted changes preserve content you haven't inspected. Use `Write` only for new files (subsystem has no knowledge file yet).
83
91
 
92
+ While merging, review the touched file's existing entries through the same quality gate. Remove entries that are now code-derivable, superseded by new decisions, or duplicated in another subsystem's knowledge file. This is opportunistic maintenance during normal writes, not a full audit.
93
+
84
94
  ## Step 5: Update Knowledge Files and Return Report
85
95
 
86
96
  ```bash
@@ -142,4 +152,6 @@ If changes suggest a subsystem not in the confirmed list, note it as a proposal
142
152
  - [ ] Report returned with update counts
143
153
  - [ ] Empty sections omitted from knowledge files
144
154
  - [ ] Existing knowledge files read for affected subsystems only
155
+ - [ ] Extracted entries pass the knowledge-quality.md filtering test
156
+ - [ ] No cross-subsystem duplication (cross-references used instead)
145
157
  </success_criteria>
@@ -41,6 +41,10 @@ You are a Mindsystem knowledge consolidator spawned by execute-phase after plan
41
41
 
42
42
  </inputs>
43
43
 
44
+ <references>
45
+ @~/.claude/mindsystem/references/knowledge-quality.md
46
+ </references>
47
+
44
48
  <extraction_guide>
45
49
 
46
50
  ## What to Extract Per Artifact
@@ -68,7 +72,7 @@ You are a Mindsystem knowledge consolidator spawned by execute-phase after plan
68
72
  | DESIGN Content | Target Knowledge Section |
69
73
  |----------------|------------------------|
70
74
  | Wireframe layouts, inline annotations | Design |
71
- | Design tokens (colors, spacing, typography) | Design |
75
+ | Design reasoning (why this approach, not pixel values) | Design |
72
76
  | Behavior notes, interaction patterns | Design |
73
77
  | States tables, platform hints | Design |
74
78
 
@@ -135,6 +139,8 @@ Apply the extraction guide to each artifact:
135
139
 
136
140
  Extract knowledge, not descriptions. "Using React" is not knowledge. "Using React over Vue because of ecosystem maturity and team familiarity" is knowledge.
137
141
 
142
+ Apply the knowledge-quality.md filtering test to each extracted entry before assigning it to a subsystem. Drop entries that fail. For entries that pass, check existing knowledge files for cross-subsystem duplication — use `(see {subsystem})` cross-references instead of duplicating.
143
+
138
144
  ## Step 6: Merge Into Knowledge Files
139
145
 
140
146
  For each affected subsystem, edit the knowledge file to reflect current state:
@@ -147,6 +153,8 @@ For each affected subsystem, edit the knowledge file to reflect current state:
147
153
 
148
154
  Use `Edit` for existing files — targeted changes preserve content you haven't inspected. Use `Write` only for new files (subsystem has no knowledge file yet).
149
155
 
156
+ While merging, review the touched file's existing entries through the same quality gate. Remove entries that are now code-derivable, superseded by new decisions, or duplicated in another subsystem's knowledge file. This is opportunistic maintenance during normal writes, not a full audit.
157
+
150
158
  ## Step 7: Update Knowledge Files
151
159
 
152
160
  ```bash
@@ -225,5 +233,7 @@ Use `+N` for new entries added, `updated` for sections rewritten with changes, `
225
233
  - [ ] Empty sections omitted from knowledge files
226
234
  - [ ] PLAN.md files deleted from phase directory
227
235
  - [ ] CONTEXT.md, DESIGN.md, RESEARCH.md, SUMMARY.md preserved
236
+ - [ ] Extracted entries pass the knowledge-quality.md filtering test
237
+ - [ ] No cross-subsystem duplication (cross-references used instead)
228
238
  - [ ] No commits made
229
239
  </success_criteria>
@@ -0,0 +1,89 @@
1
+ <knowledge_quality>
2
+
3
+ Shared quality gate for knowledge extraction. Referenced by ms-consolidator and ms-compounder agents.
4
+
5
+ <filtering_principle>
6
+
7
+ **The single test:** "Would an LLM implement this incorrectly without this entry?"
8
+
9
+ If yes — the entry earns its place. If an LLM with access to the codebase would get it right anyway, the entry is noise.
10
+
11
+ What passes the test:
12
+ - Conventions that differ from LLM defaults or framework norms
13
+ - Failed experiments and why they failed (prevents re-discovery)
14
+ - Non-obvious bugs, gotchas, or workarounds
15
+ - Decisions where the alternative was reasonable (the "because" matters)
16
+ - Cross-cutting patterns not visible from a single file
17
+
18
+ </filtering_principle>
19
+
20
+ <fails_the_test>
21
+
22
+ These categories consistently fail the filtering test. Drop them during extraction.
23
+
24
+ | Category | Why It Fails | Example |
25
+ |----------|-------------|---------|
26
+ | Design tokens (colors, spacing, typography) | Readable from code/config files | "Primary: #6366F1, spacing-md: 16px" |
27
+ | Component API descriptions | Readable from component source | "SubscriptionCard accepts `plan`, `onSelect` props" |
28
+ | Schema/model field listings | Readable from schema files | "User has fields: id, email, name, createdAt" |
29
+ | Version pins without rationale | Readable from package.json/lockfile | "Using React 18.2.0" |
30
+ | Decisions without alternatives | No "because" = no reusable knowledge | "Using Tailwind for styling" (vs. what?) |
31
+ | Implementation descriptions | Restates what the code does | "Login endpoint hashes password and returns JWT" |
32
+
33
+ </fails_the_test>
34
+
35
+ <passes_the_test>
36
+
37
+ Concrete examples that earn their place — each would cause incorrect implementation without the entry.
38
+
39
+ 1. **FieldMask casing (gRPC):** FieldMask paths must use camelCase in JSON, not snake_case — proto3 JSON mapping silently drops snake_case paths. LLMs default to snake_case matching proto definitions.
40
+
41
+ 2. **keepAlive auto-dispose (Flutter):** Riverpod providers with `keepAlive()` in `autoDispose` family providers — calling `keepAlive()` inside `ref.onDispose` creates a retain cycle. Dispose callback never fires, provider leaks. Place `keepAlive()` in the provider body before any async gap.
42
+
43
+ 3. **HiveField index stability:** HiveField indices are permanent storage keys — changing an index silently corrupts existing user data. New fields must use the next unused index, never reuse or reorder.
44
+
45
+ 4. **do/while pagination (API):** Firestore `startAfter` cursor pagination requires do/while, not while — a while loop with an empty-page exit condition misses the last partial page when `limit` equals page size exactly.
46
+
47
+ 5. **Payment timeout (Stripe):** Stripe webhook delivery retries for up to 72 hours. Payment confirmation UI must show "processing" state, not assume success/failure within a session.
48
+
49
+ 6. **Interceptor ordering (Dio):** Dio interceptors run in addition order for requests but reverse order for responses/errors. Auth token injection must be added first to run last on error (so retry logic sees the refreshed token).
50
+
51
+ </passes_the_test>
52
+
53
+ <decision_quality_test>
54
+
55
+ Not every decision is knowledge. Apply this secondary filter:
56
+
57
+ **"Could a reasonable agent have chosen differently?"**
58
+
59
+ - **Pass:** "jose over jsonwebtoken — better TypeScript types and actively maintained" → Yes, jsonwebtoken is the more common choice. The rationale prevents revisiting.
60
+ - **Pass:** "httpOnly cookies over localStorage for JWT — XSS prevention" → Yes, localStorage is the LLM default. Without this entry, an LLM would likely use localStorage.
61
+ - **Fail:** "Using TypeScript for type safety" → No reasonable agent would choose plain JS for a new project. This is a default, not a decision.
62
+ - **Fail:** "Using ESLint for linting" → No alternative was seriously considered. Not knowledge.
63
+
64
+ </decision_quality_test>
65
+
66
+ <cross_subsystem_dedup>
67
+
68
+ Before writing an entry, check whether it already exists in another subsystem's knowledge file.
69
+
70
+ - If the entry belongs primarily to another subsystem, add a cross-reference: `(see {subsystem})` instead of duplicating.
71
+ - If the entry spans multiple subsystems equally, place it in the most upstream subsystem and cross-reference from others.
72
+ - If an existing duplicate is found during extraction, remove it from the less-relevant file and cross-reference.
73
+
74
+ </cross_subsystem_dedup>
75
+
76
+ <existing_content_review>
77
+
78
+ On every write to a knowledge file, review the touched file's existing entries:
79
+
80
+ - **Still relevant?** Remove entries for features/patterns that no longer exist.
81
+ - **Code-derivable now?** Remove entries that were non-obvious when written but are now self-evident from the codebase (e.g., a pattern that was novel is now standard in the project).
82
+ - **Superseded?** Update or remove entries contradicted by new decisions.
83
+ - **Duplicated?** Check against other knowledge files — deduplicate using cross-references.
84
+
85
+ This is opportunistic maintenance during normal writes, not a full audit.
86
+
87
+ </existing_content_review>
88
+
89
+ </knowledge_quality>
@@ -30,8 +30,8 @@ Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge fi
30
30
 
31
31
  ## Design
32
32
 
33
- - {Visual/UX spec, interaction pattern, or design token}
34
- - {Component state, layout choice, or color value}
33
+ - {Design reasoning why this approach, not alternatives}
34
+ - {Interaction pattern that differs from LLM defaults}
35
35
 
36
36
  ## Pitfalls
37
37
 
@@ -54,7 +54,7 @@ Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge fi
54
54
  |---------|----------|-----------------|
55
55
  | **Decisions** | Choices with rationale (the "because" part) | CONTEXT.md locked decisions, RESEARCH.md recommendations, PLAN.md approach rationale, SUMMARY.md key-decisions |
56
56
  | **Architecture** | How the subsystem works, structural patterns | RESEARCH.md architecture patterns, PLAN.md implementation details, SUMMARY.md accomplishments |
57
- | **Design** | Visual/UX specs, interaction patterns, design tokens | DESIGN.md wireframe layouts, states tables, behavior notes, design tokens |
57
+ | **Design** | Design reasoning, non-obvious interaction patterns (reasoning only — not tokens or values readable from code) | DESIGN.md wireframe layouts, states tables, behavior notes |
58
58
  | **Pitfalls** | What to watch out for, operational patterns | RESEARCH.md common pitfalls, SUMMARY.md issues/deviations, debug resolutions, adhoc learnings |
59
59
  | **Key Files** | Important file paths for this subsystem | SUMMARY.md key-files, PLAN.md file targets |
60
60
 
@@ -96,4 +96,19 @@ The cross-reference is navigational, not essential. Each file is self-contained
96
96
  - Fixed a bug in auth (description, not a reusable pattern)
97
97
  - Missing import in login.ts (trivial, not worth persisting)
98
98
 
99
+ ## What Doesn't Belong
100
+
101
+ Apply this test to every entry: **"Would an LLM implement this incorrectly without this entry?"** If the answer is no, the entry is noise.
102
+
103
+ Categories that consistently fail the test:
104
+
105
+ - **Design tokens** (colors, spacing, typography) — readable from code/config files
106
+ - **Component API descriptions** — readable from component source
107
+ - **Schema/model field listings** — readable from schema files
108
+ - **Version pins without rationale** — readable from package.json/lockfile
109
+ - **Decisions without alternatives** — no "because" = no reusable knowledge ("Using Tailwind" vs. what?)
110
+ - **Implementation descriptions** — restates what the code does
111
+
112
+ **Decision quality test:** "Could a reasonable agent have chosen differently?" If no, it's a default, not a decision. "Using TypeScript for type safety" fails. "jose over jsonwebtoken for better TypeScript types" passes — jsonwebtoken is the more common choice.
113
+
99
114
  </guidelines>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mindsystem-cc",
3
- "version": "4.4.1",
3
+ "version": "4.4.2",
4
4
  "description": "The engineer's meta-prompting system for Claude Code.",
5
5
  "bin": {
6
6
  "mindsystem-cc": "bin/install.js"
@@ -1,460 +0,0 @@
1
- <required_reading>
2
-
3
- **Read these files NOW:**
4
-
5
- 1. `.planning/STATE.md`
6
- 2. `.planning/PROJECT.md`
7
- 3. `.planning/ROADMAP.md`
8
- 4. Current phase's plan files (`*-PLAN.md`)
9
- 5. Current phase's summary files (`*-SUMMARY.md`)
10
-
11
- </required_reading>
12
-
13
- <purpose>
14
-
15
- Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen.
16
-
17
- "Planning next phase" = "current phase is done"
18
-
19
- </purpose>
20
-
21
- <process>
22
-
23
- <step name="load_project_state" priority="first">
24
-
25
- Before transition, read project state:
26
-
27
- ```bash
28
- cat .planning/STATE.md 2>/dev/null
29
- cat .planning/PROJECT.md 2>/dev/null
30
- ```
31
-
32
- Parse current position to verify we're transitioning the right phase.
33
- Note accumulated context that may need updating after transition.
34
-
35
- </step>
36
-
37
- <step name="verify_completion">
38
-
39
- Check current phase has all plan summaries:
40
-
41
- ```bash
42
- ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort
43
- ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
44
- ```
45
-
46
- **Verification logic:**
47
-
48
- - Count PLAN files
49
- - Count SUMMARY files
50
- - If counts match: all plans complete
51
- - If counts don't match: incomplete
52
-
53
- **If all plans complete:**
54
-
55
- ```
56
- ⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
57
- Phase [X] complete — all [Y] plans finished.
58
-
59
- Proceeding to mark done and advance...
60
- ```
61
-
62
- Proceed directly to cleanup_handoff step.
63
-
64
- **If plans incomplete:**
65
-
66
- **SAFETY RAIL: Skipping incomplete plans is destructive — always confirm.**
67
-
68
- Present:
69
-
70
- ```
71
- Phase [X] has incomplete plans:
72
- - {phase}-01-SUMMARY.md ✓ Complete
73
- - {phase}-02-SUMMARY.md ✗ Missing
74
- - {phase}-03-SUMMARY.md ✗ Missing
75
-
76
- ⚠️ Safety rail: Skipping plans requires confirmation (destructive action)
77
-
78
- Options:
79
- 1. Continue current phase (execute remaining plans)
80
- 2. Mark complete anyway (skip remaining plans)
81
- 3. Review what's left
82
- ```
83
-
84
- Wait for user decision.
85
-
86
- </step>
87
-
88
- <step name="update_roadmap">
89
-
90
- Update the roadmap file:
91
-
92
- ```bash
93
- ROADMAP_FILE=".planning/ROADMAP.md"
94
- ```
95
-
96
- Update the file:
97
-
98
- - Mark current phase: `[x] Complete`
99
- - Add completion date
100
- - Update Progress table
101
- - Keep next phase as `[ ] Not started`
102
-
103
- **Example:**
104
-
105
- ```markdown
106
- ## Phases
107
-
108
- - [x] Phase 1: Foundation (completed 2025-01-15)
109
- - [ ] Phase 2: Authentication ← Next
110
- - [ ] Phase 3: Core Features
111
-
112
- ## Progress
113
-
114
- | Phase | Status | Completed |
115
- | ----------------- | ----------- | ---------- |
116
- | 1. Foundation | Complete | 2025-01-15 |
117
- | 2. Authentication | Not started | - |
118
- | 3. Core Features | Not started | - |
119
- ```
120
-
121
- </step>
122
-
123
- <step name="archive_prompts">
124
-
125
- If prompts were generated for the phase, they stay in place.
126
- The `completed/` subfolder pattern from create-meta-prompts handles archival.
127
-
128
- </step>
129
-
130
- <step name="evolve_project">
131
-
132
- Evolve PROJECT.md to reflect learnings from completed phase.
133
-
134
- **Read phase summaries:**
135
-
136
- ```bash
137
- cat .planning/phases/XX-current/*-SUMMARY.md
138
- ```
139
-
140
- **Assess requirement changes:**
141
-
142
- 1. **Requirements validated?**
143
- - Any requirements shipped in this phase?
144
- - Add to Validated with phase reference: `- ✓ [Requirement] — Phase X`
145
-
146
- 2. **Requirements invalidated?**
147
- - Any requirements discovered to be unnecessary or wrong?
148
- - Add to Out of Scope with reason: `- [Requirement] — [why invalidated]`
149
-
150
- 3. **Business context evolved?**
151
- - Has understanding of audience, problem, or differentiation changed?
152
- - Update Who It's For, Core Problem, or How It's Different if so
153
- - New key flows emerged? → Update Key User Flows
154
-
155
- 4. **Decisions to log?**
156
- - Extract decisions from SUMMARY.md files
157
- - Add to Key Decisions table with outcome if known
158
-
159
- 5. **"What This Is" still accurate?**
160
- - If the product has meaningfully changed, update the description
161
- - Keep it current and accurate
162
-
163
- **Update PROJECT.md:**
164
-
165
- Make the edits inline. Update "Last updated" footer:
166
-
167
- ```markdown
168
- ---
169
- *Last updated: [date] after Phase [X]*
170
- ```
171
-
172
- **Example evolution:**
173
-
174
- Before:
175
-
176
- ```markdown
177
- ## Validated
178
-
179
- - ✓ Canvas drawing tools — Phase 1
180
-
181
- ## Out of Scope
182
-
183
- - OAuth2 — complexity not needed for v1
184
- ```
185
-
186
- After (Phase 2 shipped JWT auth, discovered rate limiting needed):
187
-
188
- ```markdown
189
- ## Validated
190
-
191
- - ✓ Canvas drawing tools — Phase 1
192
- - ✓ JWT authentication — Phase 2
193
-
194
- ## Out of Scope
195
-
196
- - OAuth2 — complexity not needed for v1
197
- - Offline mode — real-time is core value, discovered Phase 2
198
- ```
199
-
200
- **Step complete when:**
201
-
202
- - [ ] Phase summaries reviewed for learnings
203
- - [ ] Shipped requirements added to Validated
204
- - [ ] Invalidated requirements added to Out of Scope with reason
205
- - [ ] Business context sections reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
206
- - [ ] New decisions logged with rationale
207
- - [ ] "What This Is" updated if product changed
208
- - [ ] "Last updated" footer reflects this transition
209
-
210
- </step>
211
-
212
- <step name="update_current_position_after_transition">
213
-
214
- Update Current Position section in STATE.md to reflect phase completion and transition.
215
-
216
- **Format:**
217
-
218
- ```markdown
219
- Phase: [next] of [total] ([Next phase name])
220
- Plan: Not started
221
- Status: Ready to plan
222
- Last activity: [today] — Phase [X] complete, transitioned to Phase [X+1]
223
-
224
- Progress: [updated progress bar]
225
- ```
226
-
227
- **Instructions:**
228
-
229
- - Increment phase number to next phase
230
- - Reset plan to "Not started"
231
- - Set status to "Ready to plan"
232
- - Update last activity to describe transition
233
- - Recalculate progress bar based on completed plans
234
-
235
- **Example — transitioning from Phase 2 to Phase 3:**
236
-
237
- Before:
238
-
239
- ```markdown
240
- ## Current Position
241
-
242
- Phase: 2 of 4 (Authentication)
243
- Plan: 2 of 2 in current phase
244
- Status: Phase complete
245
- Last activity: 2025-01-20 — Completed 02-02-PLAN.md
246
-
247
- Progress: ███████░░░ 60%
248
- ```
249
-
250
- After:
251
-
252
- ```markdown
253
- ## Current Position
254
-
255
- Phase: 3 of 4 (Core Features)
256
- Plan: Not started
257
- Status: Ready to plan
258
- Last activity: 2025-01-20 — Phase 2 complete, transitioned to Phase 3
259
-
260
- Progress: ███████░░░ 60%
261
- ```
262
-
263
- **Step complete when:**
264
-
265
- - [ ] Phase number incremented to next phase
266
- - [ ] Plan status reset to "Not started"
267
- - [ ] Status shows "Ready to plan"
268
- - [ ] Last activity describes the transition
269
- - [ ] Progress bar reflects total completed plans
270
-
271
- </step>
272
-
273
- <step name="update_project_reference">
274
-
275
- Update Project Reference section in STATE.md.
276
-
277
- ```markdown
278
- ## Project Reference
279
-
280
- See: .planning/PROJECT.md (updated [today])
281
-
282
- **Core value:** [Current core value from PROJECT.md]
283
- **Current focus:** [Next phase name]
284
- ```
285
-
286
- Update the date and current focus to reflect the transition.
287
-
288
- </step>
289
-
290
- <step name="review_accumulated_context">
291
-
292
- Review and update Accumulated Context section in STATE.md.
293
-
294
- **Decisions:**
295
-
296
- - Note recent decisions from this phase (3-5 max)
297
- - Full log lives in PROJECT.md Key Decisions table
298
-
299
- **Blockers/Concerns:**
300
-
301
- - Review blockers from completed phase
302
- - If addressed in this phase: Remove from list
303
- - If still relevant for future: Keep with "Phase X" prefix
304
- - Add any new concerns from completed phase's summaries
305
-
306
- **Example:**
307
-
308
- Before:
309
-
310
- ```markdown
311
- ### Blockers/Concerns
312
-
313
- - ⚠️ [Phase 1] Database schema not indexed for common queries
314
- - ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
315
- ```
316
-
317
- After (if database indexing was addressed in Phase 2):
318
-
319
- ```markdown
320
- ### Blockers/Concerns
321
-
322
- - ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
323
- ```
324
-
325
- **Step complete when:**
326
-
327
- - [ ] Recent decisions noted (full log in PROJECT.md)
328
- - [ ] Resolved blockers removed from list
329
- - [ ] Unresolved blockers kept with phase prefix
330
- - [ ] New concerns from completed phase added
331
-
332
- </step>
333
-
334
- <step name="update_session_continuity_after_transition">
335
-
336
- Update Session Continuity section in STATE.md to reflect transition completion.
337
-
338
- **Format:**
339
-
340
- ```markdown
341
- Last session: [today]
342
- Stopped at: Phase [X] complete, ready to plan Phase [X+1]
343
- ```
344
-
345
- **Step complete when:**
346
-
347
- - [ ] Last session timestamp updated to current date and time
348
- - [ ] Stopped at describes phase completion and next phase
349
-
350
- </step>
351
-
352
- <step name="offer_next_phase">
353
-
354
- **MANDATORY: Verify milestone status before presenting next steps.**
355
-
356
- **Step 1: Read ROADMAP.md and identify phases in current milestone**
357
-
358
- Read the ROADMAP.md file and extract:
359
- 1. Current phase number (the phase just transitioned from)
360
- 2. All phase numbers in the current milestone section
361
-
362
- To find phases, look for:
363
- - Phase headers: lines starting with `### Phase` or `#### Phase`
364
- - Phase list items: lines like `- [ ] **Phase X:` or `- [x] **Phase X:`
365
-
366
- Count total phases and identify the highest phase number in the milestone.
367
-
368
- State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
369
-
370
- **Step 2: Route based on milestone status**
371
-
372
- | Condition | Meaning | Action |
373
- |-----------|---------|--------|
374
- | current phase < highest phase | More phases remain | Go to **Route A** |
375
- | current phase = highest phase | Milestone complete | Go to **Route B** |
376
-
377
- ---
378
-
379
- **Route A: More phases remain in milestone**
380
-
381
- Read ROADMAP.md to get the next phase's name and goal.
382
-
383
- **If next phase exists:**
384
-
385
- ```
386
- Phase [X] marked complete.
387
-
388
- Next: Phase [X+1] — [Name]
389
-
390
- ⚡ Auto-continuing: Plan Phase [X+1] in detail
391
- ```
392
-
393
- Exit skill and invoke SlashCommand("/ms:plan-phase [X+1]")
394
-
395
- ---
396
-
397
- **Route B: Milestone complete (all phases done)**
398
-
399
- ```
400
- Phase {X} marked complete.
401
-
402
- 🎉 Milestone is 100% complete — all {N} phases finished!
403
-
404
- ⚡ Auto-continuing: Complete milestone and archive
405
- ```
406
-
407
- Exit skill and invoke SlashCommand("/ms:complete-milestone")
408
-
409
- </step>
410
-
411
- </process>
412
-
413
- <implicit_tracking>
414
-
415
- Progress tracking is IMPLICIT:
416
-
417
- - "Plan phase 2" → Phase 1 must be done (or ask)
418
- - "Plan phase 3" → Phases 1-2 must be done (or ask)
419
- - Transition workflow makes it explicit in ROADMAP.md
420
-
421
- No separate "update progress" step. Forward motion IS progress.
422
-
423
- </implicit_tracking>
424
-
425
- <partial_completion>
426
-
427
- If user wants to move on but phase isn't fully complete:
428
-
429
- ```
430
- Phase [X] has incomplete plans:
431
- - {phase}-02-PLAN.md (not executed)
432
- - {phase}-03-PLAN.md (not executed)
433
-
434
- Options:
435
- 1. Mark complete anyway (plans weren't needed)
436
- 2. Defer work to later phase
437
- 3. Stay and finish current phase
438
- ```
439
-
440
- Respect user judgment — they know if work matters.
441
-
442
- **If marking complete with incomplete plans:**
443
-
444
- - Note in transition message which plans were skipped
445
-
446
- </partial_completion>
447
-
448
- <success_criteria>
449
-
450
- Transition is complete when:
451
-
452
- - [ ] Current phase plan summaries verified (all exist or user chose to skip)
453
- - [ ] Any stale handoffs deleted
454
- - [ ] ROADMAP.md updated with completion status
455
- - [ ] PROJECT.md evolved (requirements, decisions, description if needed)
456
- - [ ] STATE.md updated (position, project reference, context, session)
457
- - [ ] Progress table updated
458
- - [ ] User knows next steps
459
-
460
- </success_criteria>