mindsystem-cc 3.14.0 → 3.16.1

package/commands/ms/design-phase.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Task
   - AskUserQuestion
+  - Skill
 ---
 
 <objective>
@@ -107,15 +108,24 @@ If exists, extract:
 - What Must Be Nailed (essentials)
 - Specific Ideas (references to products)
 
-**3c. Optional context — project UI skill:**
+**3b2. Optional context — prior knowledge:**
 
-Scan the skills list in the most recent system-reminder for a skill whose description mentions UI patterns, components, design system, or implementation styling (e.g., "Flutter/Dart patterns", "React component library", "UI implementation patterns").
+Match subsystem(s) to this phase by comparing ROADMAP phase description against subsystem names in config.json. Load matching knowledge files:
 
-If a matching skill is found, invoke it: `Skill(skill: "skill-name")`. Extract aesthetic patterns (colors, components, spacing, typography) from the loaded content for the `<existing_aesthetic>` block passed to ms-designer.
+```bash
+jq -r '.subsystems[]' .planning/config.json 2>/dev/null
+cat .planning/knowledge/{matched_subsystem}.md 2>/dev/null
+```
 
-If no matching skill is found, skip this step and note "No project UI skill found" in the `<existing_aesthetic>` block.
+If knowledge files exist, extract:
+- Architecture patterns (tech constraints the design must respect)
+- Prior design patterns (visual consistency)
+- Key decisions (constraints)
+- Pitfalls (design must avoid known traps)
 
-**3d. Optional context - codebase analysis:**
+Pass the extracted knowledge to ms-designer in the design prompt (see step 6 `<prior_knowledge>` block).
+
+**3c. Optional context - codebase analysis:**
 
 ```bash
 # Platform detection
@@ -135,14 +145,24 @@ grep -r "colors\|theme\|spacing" src/ --include="*.ts" --include="*.dart" 2>/dev
 
 Document discovered patterns for the designer.
 
-## 4. Adaptive Q&A (If Gaps Exist)
+## 4. Load Project Skills
+
+Scan the skill list in your system message for skills matching this phase's technology or domain. Invoke each match via the Skill tool before proceeding — skills contain conventions and patterns that change what you design for.
+
+- One clear match → invoke it directly
+- Multiple candidates → use AskUserQuestion to let the user choose
+- No match → proceed without
+
+Extract aesthetic patterns (colors, components, spacing, typography) from loaded skill content for the `<existing_aesthetic>` block passed to ms-designer.
+
+## 5. Adaptive Q&A (If Gaps Exist)
 
 Assess context coverage:
 - Can platform be inferred? (from codebase or PROJECT.md)
 - Can visual style be inferred? (from project UI skill or codebase)
 - Can design priorities be inferred? (from CONTEXT.md or phase requirements)
 
-**If everything can be inferred:** Skip to step 5.
+**If everything can be inferred:** Skip to step 6.
 
 **If gaps exist:** Use AskUserQuestion with targeted questions.
 
@@ -160,7 +180,7 @@ Use AskUserQuestion to confirm:
 2. **Ask more questions** — Continue gathering context
 3. **Add context** — Let user provide additional information
 
-## 4b. Mockup Generation (Optional)
+## 5b. Mockup Generation (Optional)
 
 After gathering context and closing gaps, assess whether this phase has significant new UI (new screens, novel flows, complex layouts — not minor tweaks to existing patterns).
 
@@ -186,11 +206,11 @@ Follow mockup-generation workflow:
 8. Handle selection (single pick, combine, tweak, more variants, or skip)
 9. Extract CSS specs from chosen variant into `<mockup_direction>` block
 
-Pass gathered context (PROJECT.md, ROADMAP.md phase entry, existing aesthetic) to the workflow. The workflow returns either a `<mockup_direction>` block for step 5, or nothing if user skips.
+Pass gathered context (PROJECT.md, ROADMAP.md phase entry, existing aesthetic) to the workflow. The workflow returns either a `<mockup_direction>` block for step 6, or nothing if user skips.
 
-**If user selects "No":** Proceed directly to step 5.
+**If user selects "No":** Proceed directly to step 6.
 
-## 5. Spawn ms-designer Agent
+## 6. Spawn ms-designer Agent
 
 Assemble the design prompt from gathered context:
 
@@ -238,6 +258,23 @@ Vision inferred from phase requirements and PROJECT.md context.
 Reference products: [From Q&A if asked, or "None specified"]
 </user_vision>
 
+<prior_knowledge>
+[If knowledge files exist:]
+
+Architecture constraints:
+[From knowledge Architecture sections]
+
+Prior design patterns:
+[From knowledge Design sections]
+
+Pitfalls to avoid:
+[From knowledge Pitfalls sections]
+
+[If no knowledge files exist:]
+
+No prior knowledge files. First phase or no prior execution.
+</prior_knowledge>
+
 <existing_aesthetic>
 [If project UI skill exists:]
 
@@ -260,7 +297,7 @@ No existing aesthetic. Design fresh with platform conventions.
 </existing_aesthetic>
 
 <mockup_direction>
-[If mockups were generated in step 4b, include the extracted specs:]
+[If mockups were generated in step 5b, include the extracted specs:]
 
 Direction: [chosen direction name]
 Philosophy: [direction one-sentence philosophy]
@@ -317,7 +354,7 @@ Task(
 )
 ```
 
-## 6. Handle Agent Return
+## 7. Handle Agent Return
 
 **`## DESIGN COMPLETE`:**
 
@@ -344,7 +381,7 @@ Also offer:
 
 Present the question to user. Get response. Spawn continuation with the clarification.
 
-## 7. Conversational Refinement
+## 8. Conversational Refinement
 
 After initial generation, if user wants to refine:
 
@@ -379,7 +416,7 @@ Use the iteration template from `~/.claude/mindsystem/templates/design-iteration
    - Verify "what needs improvement" was addressed
    - Update design version in DESIGN.md frontmatter
 
-## 8. Update Last Command
+## 9. Update Last Command
 
 Update `.planning/STATE.md` Last Command field:
 - Find line starting with `Last Command:` in Current Position section

package/commands/ms/discuss-phase.md

@@ -2,6 +2,12 @@
 name: ms:discuss-phase
 description: Gather phase context through adaptive questioning before planning
 argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
 ---
 
 <objective>
@@ -13,9 +19,7 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase
 </objective>
 
 <execution_context>
-@~/.claude/mindsystem/references/principles.md
 @~/.claude/mindsystem/workflows/discuss-phase.md
-@~/.claude/mindsystem/templates/context.md
 </execution_context>
 
 <context>
@@ -38,6 +42,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
 1. Validate phase number argument (error if missing or invalid)
 2. Check if phase exists in roadmap
 3. Check if CONTEXT.md already exists (offer to update if yes)
+3.5. **Load prior knowledge** — determine relevant subsystem(s) by matching ROADMAP.md phase description against subsystem names in config.json. Load matching `.planning/knowledge/{subsystem}.md` files. If knowledge exists, present brief "What we know so far" summary before questioning.
 4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**:
    - Present phase from roadmap
    - Use AskUserQuestion: "How do you imagine this working?" with interpretation options
@@ -50,13 +55,6 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - Format: `Last Command: ms:discuss-phase $ARGUMENTS | YYYY-MM-DD HH:MM`
 
 **CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
-
-User is the visionary, you are the builder:
-- Ask about vision, feel, essential outcomes
-- DON'T ask about technical risks (you figure those out)
-- DON'T ask about codebase patterns (you read the code)
-- DON'T ask about success metrics (too corporate)
-- DON'T interrogate about constraints they didn't mention
 </process>
 
 <success_criteria>

package/commands/ms/doctor.md

@@ -0,0 +1,224 @@
+---
+name: ms:doctor
+description: Health check and fix project configuration
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Run health checks on project configuration. Detect and fix configuration issues.
+
+V1 check: subsystem vocabulary setup and validation. Ensures `.planning/config.json` has a canonical `subsystems` array and all artifacts use values from it.
+
+Idempotent — safe to run repeatedly.
+</objective>
+
+<context>
+@.planning/config.json
+</context>
+
+<process>
+
+<step name="check_planning_dir">
+```bash
+[ -d .planning ] && echo "EXISTS" || echo "MISSING"
+```
+
+If MISSING:
+
+```
+No .planning/ directory found.
+
+Run `/ms:new-project` to initialize this project.
+```
+
+Exit.
+</step>
+
+<step name="ensure_config">
+```bash
+[ -f .planning/config.json ] && echo "EXISTS" || echo "MISSING"
+```
+
+If MISSING, create from template structure:
+
+```json
+{
+  "subsystems": [],
+  "code_review": {
+    "adhoc": null,
+    "phase": null,
+    "milestone": null
+  }
+}
+```
+
+Write to `.planning/config.json`. Log: "Created config.json with empty subsystems."
+
+Proceed to next step.
+</step>
+
+<step name="read_current_subsystems">
+```bash
+jq -r '.subsystems // [] | length' .planning/config.json
+```
+
+- If 0 → **State A**: no subsystems configured. Go to `audit_existing_usage`.
+- If >0 → **State B**: subsystems exist. Go to `validate_vocabulary`.
+</step>
+
+<step name="audit_existing_usage">
+**State A only.** Scan all artifact types for existing free-form `subsystem:` values.
+
+```bash
+~/.claude/mindsystem/scripts/scan-artifact-subsystems.sh --values-only
+```
+
+Collect all unique values found. Note count of artifacts scanned and values found.
+</step>
+
+<step name="derive_and_confirm">
+**State A only.** Read `.planning/PROJECT.md` and `.planning/ROADMAP.md`.
+
+Derive 5-12 canonical subsystem identifiers from:
+
+1. Unique values found in `audit_existing_usage`
+2. Project domain from PROJECT.md
+3. Phase structure from ROADMAP.md
+
+Rules:
+- Lowercase, single-word or hyphenated (e.g., "auth", "real-time", "ui")
+- Merge synonyms into one canonical value (pick shortest/most common)
+- Cover all existing usage plus obvious gaps
+- Include infrastructure-level subsystems if relevant (api, database, infra, testing)
+
+Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
+
+Use AskUserQuestion:
+- header: "Subsystems"
+- question: "These subsystems were derived from your project. Look good?"
+- options:
+  - "Looks good" — accept and apply
+  - "Add/remove some" — iterate on the list
+  - "Start over" — re-derive from scratch
+
+After confirmation:
+
+1. Update `config.json` — set `subsystems` array as first field
+2. If existing artifacts had free-form values, standardize each `subsystem:` field to the canonical value using the Edit tool (only modify the `subsystem:` line, never body content)
+3. Commit all changes:
+
+```bash
+git add .planning/config.json
+git add .planning/phases/*/*-SUMMARY.md 2>/dev/null
+git add .planning/adhoc/*-SUMMARY.md 2>/dev/null
+git add .planning/debug/*.md 2>/dev/null
+git add .planning/debug/resolved/*.md 2>/dev/null
+git add .planning/todos/pending/*.md 2>/dev/null
+git add .planning/todos/done/*.md 2>/dev/null
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore: initialize subsystem vocabulary
+
+Added subsystems array to config.json and standardized existing artifact values.
+EOF
+)"
+```
+</step>
+
+<step name="validate_vocabulary">
+**State B only.** Read canonical list from config.json:
+
+```bash
+jq -r '.subsystems[]' .planning/config.json
+```
+
+Scan all artifacts for `subsystem:` values. Extract from YAML frontmatter:
+
+```bash
+~/.claude/mindsystem/scripts/scan-artifact-subsystems.sh
+```
+
+Classify each artifact's `subsystem:` value:
+- **OK** — value is in canonical list
+- **MISMATCH** — value exists but not in canonical list
+- **MISSING** — no `subsystem:` field found
+
+Display results grouped by status. If all OK:
+
+```
+## Subsystem Vocabulary
+
+PASS — all N artifacts use canonical subsystem values.
+```
+
+Go to `report`.
+
+If MISMATCH or MISSING found, use AskUserQuestion:
+- header: "Fix issues"
+- question: "Found N issues (X mismatches, Y missing). How to proceed?"
+- options:
+  - "Fix all" — apply best-match canonical values to all issues
+  - "Review each" — present each issue individually for decision
+  - "Skip" — leave as-is
+
+For fixes:
+- MISMATCH: propose closest canonical value (fuzzy match on prefix/synonym)
+- MISSING: propose based on artifact content/path context
+
+Apply fixes using Edit tool. Commit:
+
+```bash
+git add .planning/phases/*/*-SUMMARY.md 2>/dev/null
+git add .planning/adhoc/*-SUMMARY.md 2>/dev/null
+git add .planning/debug/*.md 2>/dev/null
+git add .planning/debug/resolved/*.md 2>/dev/null
+git add .planning/todos/pending/*.md 2>/dev/null
+git add .planning/todos/done/*.md 2>/dev/null
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore: fix subsystem vocabulary mismatches
+
+Standardized artifact subsystem values to canonical vocabulary.
+EOF
+)"
+```
+</step>
+
+<step name="report">
+Final summary:
+
+```
+## Doctor Report
+
+| Check                  | Result      | Details                    |
+|------------------------|-------------|----------------------------|
+| Subsystem vocabulary   | PASS / INIT | N artifacts, M subsystems  |
+
+All checks passed.
+```
+
+- **PASS**: subsystems were already configured and all artifacts validated
+- **INIT**: subsystems were initialized during this run
+- Include artifact count (how many scanned) and subsystem count
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] State A: config.json updated, existing artifacts standardized to canonical values, changes committed
+- [ ] State B issues: offers fix/review/skip, applies fixes, commits
+- [ ] Final report displayed with check name, result, and artifact/subsystem counts
+- [ ] State A: derives canonical list from audit + project context, confirms with user before applying
+- [ ] State B: all artifacts scanned and classified; reports PASS if all OK
+</success_criteria>

package/commands/ms/execute-phase.md

@@ -90,10 +90,17 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - Verify: patch file exists OR skip message logged
    - Note: Patch captures all changes including simplifications
 
-9. **Update roadmap and state**
-   - Update ROADMAP.md, STATE.md
+9. **Consolidate knowledge**
+   - Spawn `ms-consolidator` with phase directory and number
+   - Consolidator reads phase artifacts and existing knowledge files
+   - Produces updated `.planning/knowledge/{subsystem}.md` files
+   - Deletes PLAN.md files (execution instructions consumed)
+   - Verify: knowledge files written to `.planning/knowledge/`
 
-10. **Update requirements**
+10. **Update roadmap and state**
+    - Update ROADMAP.md, STATE.md
+
+11. **Update requirements**
     Mark phase requirements as Complete:
     - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
     - Read REQUIREMENTS.md traceability table
@@ -101,16 +108,18 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
     - Write updated REQUIREMENTS.md
     - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
-11. **Commit phase completion**
+12. **Commit phase completion**
     Bundle all phase metadata updates in one commit:
     - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
+    - Stage knowledge files: `git add .planning/knowledge/*.md`
+    - Stage PLAN.md deletions: `git add -u .planning/phases/{phase_dir}/*-PLAN.md`
     - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
     - Commit: `docs({phase}): complete {phase-name} phase`
 
-12. **Offer next steps**
+13. **Offer next steps**
     - Route to next action (see `<offer_next>`)
 
-13. **Update last command**
+14. **Update last command**
     - Update `.planning/STATE.md` Last Command field
     - Format: `Last Command: ms:execute-phase $ARGUMENTS | YYYY-MM-DD HH:MM`
 </process>
@@ -213,8 +222,10 @@ After code simplification step:
 
 After all plans in phase complete:
 1. Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
-2. Commit with format: `docs({phase}): complete {phase-name} phase`
-3. Bundles all phase-level state updates in one commit
+2. Stage knowledge files: `git add .planning/knowledge/*.md`
+3. Stage PLAN.md deletions: `git add -u .planning/phases/{phase_dir}/*-PLAN.md`
+4. Commit with format: `docs({phase}): complete {phase-name} phase`
+5. Bundles all phase-level state updates in one commit
 
 **NEVER use:**
 - `git add .`
@@ -226,13 +237,12 @@ After all plans in phase complete:
 
 <success_criteria>
 - [ ] All incomplete plans in phase executed
-- [ ] Each plan has SUMMARY.md
 - [ ] Code review completed (or skipped if config says "skip")
 - [ ] Phase goal verified (Must-Haves checked against codebase)
 - [ ] VERIFICATION.md created in phase directory
 - [ ] Patch file generated OR explicitly skipped with message
-- [ ] STATE.md reflects phase completion
-- [ ] ROADMAP.md updated
+- [ ] Knowledge files written to .planning/knowledge/ (consolidation complete)
+- [ ] PLAN.md files deleted from phase directory
+- [ ] STATE.md and ROADMAP.md reflect phase completion
 - [ ] REQUIREMENTS.md updated (phase requirements marked Complete)
-- [ ] User informed of next steps
 </success_criteria>

package/commands/ms/help.md

@@ -376,6 +376,17 @@ Usage: `/ms:adhoc Fix auth token not refreshing on 401`
 
 ### Utility Commands
 
+**`/ms:doctor`**
+Health check and fix project configuration.
+
+- Use when: subsystems are missing, artifacts have inconsistent vocabulary, or periodic health check
+- V1: subsystem vocabulary setup and validation
+- If subsystems missing: derives from project context and guides through setup
+- If subsystems present: validates all artifacts use canonical values
+- Idempotent — safe to run repeatedly
+
+Usage: `/ms:doctor`
+
 **`/ms:help`**
 Show this command reference.
 

package/commands/ms/new-milestone.md

@@ -63,10 +63,9 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 3. **Strategic assessment (silent — do not output this step):**
    - Check for previous milestone artifacts using calculated version:
-     - `.planning/milestones/v{VERSION}-DECISIONS.md` (if exists)
+     - `.planning/knowledge/*.md` (subsystem knowledge files — persist across milestones)
      - `.planning/milestones/v{VERSION}-MILESTONE-AUDIT.md` (if exists)
      - `.planning/TECH-DEBT.md` (if exists)
-     - `.planning/LEARNINGS.md` (if exists)
    - Identify: outstanding tech debt, untested assumptions, high-impact gaps, unaddressed requirements
    - This is background analysis — synthesize silently, surface through suggestions in step 4
 
@@ -85,7 +84,8 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
    ```
 
    Sources for suggestions:
-   - High-impact tech debt from TECH-DEBT.md or MILESTONE-AUDIT.md
+   - Tech debt from TECH-DEBT.md, MILESTONE-AUDIT.md, or knowledge file Pitfalls sections
+   - Settled decisions and patterns from knowledge files
    - Untested assumptions from previous audit
    - Unaddressed requirements from previous milestones
    - Strategic features inferred from PROJECT.md's problem/audience/USP

package/commands/ms/plan-phase.md

@@ -84,7 +84,7 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
 5. Follow plan-phase.md workflow:
    - Load project state and accumulated decisions
    - Perform mandatory discovery (Level 0-3 as appropriate)
-   - Read project history (prior decisions, issues, debug resolutions, adhoc learnings, cross-milestone patterns)
+   - Scan project history via context scanner script (prior decisions, issues, debug resolutions, adhoc learnings, cross-milestone patterns)
    - Break phase into tasks
    - Estimate scope and split into multiple plans if needed
    - Create PLAN.md file(s) with executable structure