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.
|
package/agents/ms-compounder.md
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
- {
|
|
34
|
-
- {
|
|
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** |
|
|
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,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>
|