mindsystem-cc 3.13.1 → 3.16.0

package/mindsystem/workflows/discuss-phase.md

@@ -30,11 +30,7 @@ Phase number: $ARGUMENTS (required)
 Validate phase exists in roadmap:
 
 ```bash
-if [ -f .planning/ROADMAP.md ]; then
-  cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
-else
-  cat .planning/ROADMAP.md | grep "Phase ${PHASE}:"
-fi
+grep "Phase ${PHASE}:" .planning/ROADMAP.md
 ```
 
 **If phase not found:**
@@ -55,6 +51,29 @@ Parse phase details from roadmap:
 - Phase description
 - Status (should be "Not started" or "In progress")
 
+Continue to load_prior_knowledge.
+</step>
+
+<step name="load_prior_knowledge">
+Determine which subsystem(s) this phase touches from ROADMAP.md phase description + config.json:
+
+```bash
+jq -r '.subsystems[]' .planning/config.json 2>/dev/null
+grep -A20 "Phase ${PHASE}:" .planning/ROADMAP.md
+```
+
+Load matching `knowledge/{subsystem}.md` files:
+
+```bash
+cat .planning/knowledge/{subsystem}.md 2>/dev/null
+```
+
+Handle gracefully when `.planning/knowledge/` doesn't exist (first milestone, no phases executed yet).
+
+**If knowledge exists:** Present a brief "What we know so far" summary to the user before questioning — prior decisions, architectural patterns, and pitfalls relevant to this phase. This grounds the discussion without interrogating.
+
+**If no knowledge files exist:** Skip silently (normal for first phase).
+
 Continue to check_existing.
 </step>
 
@@ -239,10 +258,8 @@ Confirm: "Committed: docs(${PHASE}): capture phase context"
 
 <success_criteria>
 
-- Phase validated against roadmap
 - Vision gathered through collaborative thinking (not interrogation)
 - User's imagination captured: how it works, what's essential
-- CONTEXT.md created in phase directory
-- CONTEXT.md committed to git
 - User knows next steps (typically: research or plan the phase)
+- CONTEXT.md committed to git
 </success_criteria>

package/mindsystem/workflows/execute-phase.md

@@ -441,6 +441,38 @@ fi
 - Discard: `rm {patch_file}`
 </step>
 
+<step name="consolidate_knowledge">
+Consolidate phase knowledge into per-subsystem knowledge files.
+
+**Spawn ms-consolidator:**
+
+```
+Task(
+  prompt="Consolidate knowledge from phase {phase_number}.
+  Phase directory: {phase_dir}
+  Phase number: {phase_number}
+  Read SUMMARY.md files for affected subsystems, then read phase artifacts
+  and existing knowledge files. Produce updated knowledge files and delete
+  PLAN.md files.",
+  subagent_type="ms-consolidator"
+)
+```
+
+**Verify consolidation:**
+
+```bash
+ls .planning/knowledge/*.md 2>/dev/null
+```
+
+Report the consolidation summary returned by ms-consolidator.
+
+**Handle failure:** If consolidation fails, ask user:
+- "Continue without consolidation" → proceed to update_roadmap
+- "Stop execution" → exit with partial completion report
+
+Knowledge consolidation is not a blocking gate — phase execution succeeded regardless.
+</step>
+
 <step name="update_roadmap">
 Update ROADMAP.md to reflect phase completion:
 
@@ -453,6 +485,8 @@ Update ROADMAP.md to reflect phase completion:
 Commit phase completion (roadmap, state, verification):
 ```bash
 git add .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md .planning/phases/{phase_dir}/*-SUMMARY.md
+git add .planning/knowledge/*.md
+git add -u .planning/phases/{phase_dir}/*-PLAN.md
 git add .planning/REQUIREMENTS.md  # if updated
 git commit -m "docs(phase-{X}): complete phase execution"
 ```

package/mindsystem/workflows/execute-plan.md

@@ -43,6 +43,14 @@ Parse plan sections:
 **If `**Type:** tdd`:** Read `~/.claude/mindsystem/references/tdd-execution.md` for RED-GREEN-REFACTOR execution flow.
 </step>
 
+<step name="load_skills">
+Scan the skill list in your system message for skills matching the plan's technology or domain. Invoke each match via the Skill tool before proceeding — skills contain project-specific conventions and patterns that change what you produce during implementation.
+
+- One clear match → invoke it directly
+- Multiple candidates → use AskUserQuestion to let the user choose
+- No match → proceed without
+</step>
+
 <step name="execute">
 Record start time: `PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ"); PLAN_START_EPOCH=$(date +%s)`
 

package/mindsystem/workflows/mockup-generation.md

@@ -87,7 +87,7 @@ Task(prompt=assembled_context, subagent_type="ms-mockup-designer", description="
 </step>
 
 <step name="present_mockups">
-After all 3 agents return, generate comparison page and open it:
+After all 3 agents return, run the comparison script to create the comparison page. Do NOT generate comparison HTML manually — use the script:
 
 ```bash
 uv run ~/.claude/mindsystem/scripts/compare_mockups.py "${PHASE_DIR}/mockups"

package/mindsystem/workflows/plan-phase.md

@@ -263,135 +263,74 @@ For niche domains (3D, games, audio, shaders, ML), suggest `/ms:research-phase`
 </step>
 
 <step name="read_project_history">
-**Intelligent context assembly from frontmatter dependency graph:**
+**Intelligent context assembly via scanner script + selective reading:**
 
-**1. Scan all summary frontmatter (cheap - first ~25 lines):**
+**1. Determine scanner arguments** from prior steps:
+
+- Phase number from identify_phase step
+- Subsystem from `.planning/config.json` if available
+- Phase name from ROADMAP.md phase description
 
 ```bash
-for f in .planning/phases/*/*-SUMMARY.md; do
-  # Extract frontmatter only (between first two --- markers)
-  sed -n '1,/^---$/p; /^---$/q' "$f" | head -30
-done
+SUBSYSTEM=$(jq -r '.subsystems[0] // empty' .planning/config.json 2>/dev/null)
+PHASE_NAME=$(grep -A2 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null | head -1 | sed 's/.*Phase [0-9]*: *//')
 ```
 
-Parse YAML to extract: phase, subsystem, requires, provides, affects, tags, key-decisions, key-files
-
-**2. Build dependency graph for current phase:**
-
-- **Check affects field:** Which prior phases have current phase in their `affects` list? → Direct dependencies
-- **Check subsystem:** Which prior phases share same subsystem? → Related work
-- **Check requires chains:** If phase X requires phase Y, and we need X, we also need Y → Transitive dependencies
-- **Check roadmap:** Any phases marked as dependencies in ROADMAP.md phase description?
-
-**3. Select relevant summaries:**
-
-Auto-select phases that match ANY of:
-- Current phase name/number appears in prior phase's `affects` field
-- Same `subsystem` value
-- In `requires` chain (transitive closure)
-- Explicitly mentioned in STATE.md decisions as affecting current phase
+**2. Run context scanner:**
 
-Typical selection: 2-4 prior phases (immediately prior + related subsystem work)
-
-**4. Extract context from frontmatter (WITHOUT opening full summaries yet):**
+```bash
+uv run ~/.claude/mindsystem/scripts/scan-planning-context.py \
+  --phase "${PHASE}" \
+  --phase-name "${PHASE_NAME}" \
+  ${SUBSYSTEM:+--subsystem "${SUBSYSTEM}"}
+```
 
-From selected phases' frontmatter, extract:
-- **Tech available:** Union of all tech-stack.added lists
-- **Patterns established:** Union of all tech-stack.patterns and patterns-established
-- **Key files:** Union of all key-files (for @context references)
-- **Decisions:** Extract key-decisions from frontmatter
+**3. Parse JSON output.** Check `success` field. If the script fails or returns non-JSON, fall back to manual scanning (read SUMMARY frontmatter with sed as before). The scanner handles missing directories gracefully — check `sources.*.skipped` for skip reasons.
 
-**4b. Present established patterns to user:**
+**4. Present established patterns to user:**
 
-If patterns-established entries were collected, display:
+From `aggregated.patterns_established`, display:
 
 ```
 ### Established Patterns to Maintain
 - [Pattern: description] (from phase XX)
 ```
 
-If no patterns collected, skip.
+If empty, skip.
 
-**5. Now read FULL summaries for selected phases:**
+**5. Conditionally read full summaries.**
 
-Only now open and read complete SUMMARY.md files for the selected relevant phases. Extract:
-- Detailed "Accomplishments" section
-- "Next Phase Readiness" warnings/blockers
-- "Issues Encountered" that might affect current phase
-- "Deviations from Plan" for patterns
+Read full SUMMARY.md body ONLY for summaries where:
+- `relevance` is HIGH AND `has_readiness_warnings` is true
+- OR frontmatter alone doesn't provide enough context for task breakdown (use judgment)
 
-**6. Search additional knowledge sources (cross-cutting retrieval):**
+Extract from full reads: "Next Phase Readiness" warnings, "Issues Encountered", detailed accomplishments.
 
-Use keywords already extracted: phase name, subsystem (from config.json), tags/tech terms from selected summaries.
+Summaries scored MEDIUM or HIGH without readiness warnings → frontmatter data in JSON is sufficient (tech stack, patterns, key files, decisions already aggregated).
 
-**6a. Resolved debug docs:**
+**6. Present matched learnings:**
 
-```bash
-for f in .planning/debug/resolved/*.md; do
-  sed -n '1,/^---$/p; /^---$/q' "$f" | head -20
-done 2>/dev/null
-```
-
-Select docs matching: same `subsystem`, overlapping `tags`, or `phase` in dependency chain.
-Extract: `root_cause` + `resolution` one-liners from frontmatter.
-
-**If matched debug docs found, present warning to user:**
+**From `debug_learnings`** — present as warnings:
 
 ```
 ### Previous Debug Sessions in This Area
 - **{slug}** ({subsystem}): {root_cause} — Fix: {resolution}
 ```
 
-Awareness only — learnings still flow to `<learnings>` handoff.
-If no matches, skip.
-
-**6b. Adhoc summaries:**
+**From `adhoc_learnings`** — extract entries with non-empty `learnings` arrays for handoff context.
 
-```bash
-for f in .planning/adhoc/*-SUMMARY.md; do
-  sed -n '1,/^---$/p; /^---$/q' "$f" | head -20
-done 2>/dev/null
-```
+If neither source has matches, skip.
 
-Select matching: same `subsystem`, overlapping `tags`, or `related_phase` in dependency chain.
-Extract: `learnings` array entries (skip if empty).
+**7. Read knowledge files:**
 
-**6c. Completed todos:**
+For each entry in `knowledge_files` where `matched` is true, read the full file. Knowledge files are prose (no frontmatter) so the LLM must read them to extract decisions, architecture, pitfalls.
 
-```bash
-ls .planning/todos/done/*.md 2>/dev/null
-```
+**8. Assess pending todos:**
 
-If exists, grep body content for phase keywords or subsystem. Extract brief description of resolved items.
-
-**6d. Milestone decisions:**
-
-```bash
-ls .planning/milestones/v*-DECISIONS.md 2>/dev/null
-```
-
-If exists, grep for entries matching current subsystem or phase keywords. Extract matched decision rows.
-
-**6e. LEARNINGS.md (cross-milestone index):**
-
-```bash
-cat .planning/LEARNINGS.md 2>/dev/null
-```
-
-If exists, grep for entries matching phase keywords, subsystem, or tech terms. Extract matched one-liner entries with source references.
-
-**Collect matched learnings for handoff** — assemble into flat list for `<learnings>` section.
+From `pending_todos` frontmatter in JSON, assess each todo's relevance. Read full body only for todos matching current phase subsystem/tags.
 
 **From STATE.md:** Decisions → constrain approach. Pending todos → candidates. Blockers → may need to address.
 
-**From pending todos:**
-
-```bash
-ls .planning/todos/pending/*.md 2>/dev/null
-```
-
-Assess each pending todo - relevant to this phase? Natural to address now?
-
 **Answer before proceeding:**
 - Q1: What decisions from previous phases constrain this phase?
 - Q2: Are there pending todos that should become tasks?
@@ -400,13 +339,13 @@ Assess each pending todo - relevant to this phase? Natural to address now?
 
 **Track for handoff to ms-plan-writer:**
 - Which summaries were selected (for @context references)
-- Tech stack available (from frontmatter)
-- Established patterns (from frontmatter)
-- Key files to reference (from frontmatter)
-- Applicable decisions (from frontmatter + full summary)
+- Tech stack available (from `aggregated.tech_stack_added`)
+- Established patterns (from `aggregated.patterns_established`)
+- Key files to reference (from `aggregated.key_files_created` + `key_files_modified`)
+- Applicable decisions (from `aggregated.key_decisions` + full summary reads)
 - Todos being addressed (from pending todos)
-- Concerns being verified (from "Next Phase Readiness")
-- Matched learnings (from debug docs, adhoc summaries, patterns, decisions, LEARNINGS.md)
+- Concerns being verified (from "Next Phase Readiness" in full reads)
+- Matched learnings (from `debug_learnings`, `adhoc_learnings`, patterns, knowledge files)
 </step>
 
 <step name="gather_phase_context">
@@ -563,8 +502,7 @@ Assemble handoff payload:
   <learning type="debug" source=".planning/debug/resolved/{slug}.md">{root_cause} — fix: {resolution}</learning>
   <learning type="adhoc" source=".planning/adhoc/{file}.md">{learnings entry}</learning>
   <learning type="pattern" source=".planning/phases/{path}">{patterns-established entry}</learning>
-  <learning type="decision" source=".planning/milestones/{file}">{decision}: {rationale}</learning>
-  <learning type="curated" source="{source_ref from LEARNINGS.md}">{one-liner pattern}</learning>
+  <learning type="knowledge" source=".planning/knowledge/{subsystem}.md">{decisions, architecture, pitfalls from knowledge files}</learning>
 </learnings>
 ```