mindsystem-cc 3.19.0 → 3.21.0

package/mindsystem/workflows/discuss-phase.md

@@ -1,29 +1,25 @@
 <purpose>
-Gather phase context through collaborative thinking before planning. Help the user articulate their vision for how this phase should work, look, and feel.
+Gather phase context through product-informed collaborative thinking before planning. Act as a collaborative product owner — loading milestone-level artifacts, surfacing assumptions, optionally researching competitors, and grounding every question in product analysis.
 
-You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to understand their vision, not interrogate them about technical details you can figure out yourself.
+You are a thinking partner, not an interviewer. The user is the visionary — you are the builder with product sense. Your job is to understand their vision, ground it in industry context, and help them make informed decisions.
 </purpose>
 
 <philosophy>
-**User = founder/visionary. Claude = builder.**
+The user knows vision, priorities, and preferences. They don't know codebase patterns, technical risks, or implementation constraints — you figure those out.
 
-The user doesn't know (and shouldn't need to know):
-- Codebase patterns (you read the code)
-- Technical risks (you identify during research)
-- Implementation constraints (you figure those out)
-- Success metrics (you infer from the work)
-
-The user DOES know:
-- How they imagine it working
-- What it should look/feel like
-- What's essential vs nice-to-have
-- Any specific things they have in mind
+**Product-thinking lens (analytical tool, not checklist):**
+- Ground analysis in target audience (Who It's For from PROJECT.md)
+- Focus on what moves the needle (Core Value)
+- Think in systems, not features — how does this phase connect to the whole?
+- Validate against industry patterns, don't blindly follow them
 
-Ask about vision. Figure out implementation yourself.
+Ask about vision. Apply product thinking. Figure out implementation yourself.
 </philosophy>
 
 <process>
 
+<!-- STAGE 1: LOAD + ASSESS -->
+
 <step name="validate_phase" priority="first">
 Phase number: $ARGUMENTS (required)
 
@@ -51,30 +47,33 @@ Parse phase details from roadmap:
 - Phase description
 - Status (should be "Not started" or "In progress")
 
-Continue to load_prior_knowledge.
+Continue to load_context.
 </step>
 
-<step name="load_prior_knowledge">
-Determine which subsystem(s) this phase touches from ROADMAP.md phase description + config.json:
+<step name="load_context">
+Load milestone artifacts and prior knowledge. Handle gracefully when any file is missing.
 
 ```bash
+cat .planning/PROJECT.md 2>/dev/null
+cat .planning/MILESTONE-CONTEXT.md 2>/dev/null
+cat .planning/REQUIREMENTS.md 2>/dev/null
 jq -r '.subsystems[]' .planning/config.json 2>/dev/null
 grep -A20 "Phase ${PHASE}:" .planning/ROADMAP.md
 ```
 
-Load matching `knowledge/{subsystem}.md` files:
+Extract from PROJECT.md: **Who It's For**, **Core Value**, **How It's Different**
+
+Extract from REQUIREMENTS.md: Requirements mapped to this phase (match phase number/name against requirement tags)
+
+Load matching `knowledge/{subsystem}.md` files for subsystems this phase touches:
 
 ```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 knowledge exists:** Present a brief "What we know so far" summary — prior decisions, patterns, and pitfalls relevant to this phase.
 
 **If no knowledge files exist:** Skip silently (normal for first phase).
-
-Continue to check_existing.
 </step>
 
 <step name="check_existing">
@@ -98,75 +97,142 @@ What's next?
 
 Wait for user response.
 
-If "Update context": Load existing CONTEXT.md, continue to questioning
+If "Update context": Load existing CONTEXT.md, continue to assess_and_research
 If "View existing": Read and display CONTEXT.md, then offer update/skip
 If "Skip": Exit workflow
 
 **If doesn't exist:**
-Continue to questioning.
+Continue to assess_and_research.
 </step>
 
-<step name="questioning">
-**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+<!-- STAGE 2: BRIEFING + CONDITIONAL RESEARCH -->
+
+<step name="assess_and_research">
+Parse the requirements mapped to this phase from REQUIREMENTS.md and the phase description from ROADMAP.md.
+
+**Assess whether product research would add value:**
 
-Present initial context from roadmap, then immediately use AskUserQuestion:
+Research is valuable when the phase involves user-facing product decisions where competitor context, UX patterns, or audience expectations would inform better choices. Examples: UI layouts, user flows, feature scope, interaction patterns.
+
+Research is NOT valuable for: backend infrastructure, data migrations, build tooling, refactoring, developer-facing work with no UX decisions.
+
+**If research would add value:**
+
+Use AskUserQuestion:
+- header: "Research"
+- question: "This phase involves product decisions where competitor and UX research could help. Want me to research how others handle this before we discuss?"
+- options:
+  - "Research first" — Investigate competitors and UX patterns (~30s)
+  - "Skip research" — Discuss based on what we know
+
+**If user selects "Research first":**
+
+Spawn ms-product-researcher subagent via Task tool:
 
 ```
-Phase ${PHASE}: ${PHASE_NAME}
+<product_context>
+[Who It's For, Core Value, How It's Different from PROJECT.md]
+</product_context>
+
+<phase_requirements>
+[Phase goal, description, mapped requirements from ROADMAP.md/REQUIREMENTS.md]
+</phase_requirements>
 
-From the roadmap: ${PHASE_DESCRIPTION}
+<research_focus>
+[Specific product questions relevant to this phase — what would help the user decide?]
+</research_focus>
 ```
 
-**1. Open:**
+Store research findings for use in present_briefing and questioning steps.
 
-Use AskUserQuestion:
-- header: "Vision"
-- question: "How do you imagine this working?"
-- options: 2-3 interpretations based on the phase description + "Let me describe it"
+**If user selects "Skip research" or research not valuable:**
+Continue without research findings.
+</step>
+
+<step name="present_briefing">
+Present a consolidated briefing that weaves together all loaded context.
+
+```
+## Phase ${PHASE}: ${PHASE_NAME}
 
-**2. Follow the thread:**
+### What This Phase Delivers
+[Requirements mapped to this phase from REQUIREMENTS.md, or phase goal from ROADMAP.md if no requirements mapping]
 
-Based on their response, use AskUserQuestion:
-- header: "[Topic they mentioned]"
-- question: "You mentioned [X] — what would that look like?"
-- options: 2-3 interpretations + "Something else"
+### My Assumptions
+- **Approach:** How Claude would tackle this
+- **Scope:** What's included vs excluded
+- **Risks/Dependencies:** Where Claude expects complexity or unknowns
 
-**3. Sharpen the core:**
+[If research findings available:]
+### Industry Context
+[Key findings from product research — competitor patterns, UX conventions, audience expectations. Dense, prescriptive summary.]
+```
 
-Use AskUserQuestion with multiSelect: true:
-- header: "Essential"
-- question: "What's most important to nail in this phase? Select all that apply."
-- options: Key aspects they've mentioned
+Then use AskUserQuestion:
+- header: "Assumptions"
+- question: "Are these assumptions on track? Anything I'm getting wrong or missing?"
+- options:
+  - "Looks right" — Assumptions are accurate, let's continue
+  - "Some corrections" — I have specific corrections
+  - "Way off" — Let me reframe this
 
-**4. Capture specifics (optional):**
+**If "Some corrections" or "Way off":** Receive corrections, acknowledge, update understanding. Then continue to questioning.
+**If "Looks right":** Continue to questioning.
+</step>
 
-If they seem to have specific ideas, use AskUserQuestion:
-- header: "Specifics"
-- question: "Any particular look/feel/behavior in mind?"
-- options: Contextual options based on what they've said + "No specifics" + "Let me describe"
+<!-- STAGE 3: INFORMED DISCUSSION -->
 
-CRITICAL — What NOT to ask:
+<step name="questioning">
+**ALL questions use AskUserQuestion. Never ask inline text questions.**
+
+What NOT to ask — the user doesn't know and shouldn't be asked about:
 - Technical risks (you figure those out)
 - Codebase patterns (you read the code)
 - Success metrics (too corporate)
 - Constraints they didn't mention (don't interrogate)
 - What's out of scope (implicit from roadmap)
 
-**5. Decision gate:**
+**Scope guardrail:** Phase boundary from ROADMAP.md is FIXED. Discussion clarifies HOW to implement, not WHETHER to add more. If user suggests new capabilities: "That sounds like its own phase. I'll note it in Deferred Ideas."
+
+**Product lens:** Before each question, show brief analysis — audience needs, competitor patterns (from research if available), tradeoffs and recommendation. This grounds the user's decision.
+
+**1. Open:**
+
+Present brief product analysis, then use AskUserQuestion:
+- header: "Vision"
+- question: "How do you imagine this working?"
+- options: 2-3 interpretations based on phase description, requirements, and industry context + "Let me describe it"
+
+**2. Follow the thread (2-4 rounds typical):**
+
+Follow the user's thread. Each round: apply product lens to the topic they raised, then AskUserQuestion with 2-3 interpretations + escape hatch. Use multiSelect for priority/essential questions. Stop when vision is clear — don't over-question.
+
+**3. Decision gate:**
+
+Present a coverage summary before offering to finalize:
+
+```
+### Coverage Summary
+**Discussed:** [Topics covered during this conversation]
+**From artifacts:** [Context loaded from PROJECT.md, REQUIREMENTS.md, research]
+**Open areas:** [Anything from the requirements/roadmap not yet discussed — or "None" if comprehensive]
+```
 
 Use AskUserQuestion:
 - header: "Ready?"
 - question: "Ready to capture this context, or explore more?"
 - options (ALL THREE REQUIRED):
-  - "Create CONTEXT.md" - I've shared my vision
-  - "Ask more questions" - Help me think through this more
-  - "Let me add context" - I have more to share
+  - "Create CONTEXT.md" — I've shared my vision
+  - "Ask more questions" — Help me think through this more
+  - "Let me add context" — I have more to share
 
 If "Ask more questions" → return to step 2 with new probes.
 If "Let me add context" → receive input → return to step 2.
 Loop until "Create CONTEXT.md" selected.
 </step>
 
+<!-- STAGE 4: OUTPUT -->
+
 <step name="write_context">
 Create CONTEXT.md capturing the user's vision and decisions.
 
@@ -188,15 +254,10 @@ Populate template sections:
 - `<notes>`: Any other context gathered
 
 **Decision context (for downstream agents):**
-- `<decisions>`: Concrete choices made during discussion (locked)
+- `<decisions>`: Concrete choices made during discussion (locked). Include inline reasoning grounded in vision, audience, competitor patterns, or tradeoff analysis: `- [Decision] — [Why: reasoning]`
 - `### Claude's Discretion`: Areas where user said "you decide" or didn't express preference
 - `<deferred>`: Ideas mentioned but explicitly out of scope
 
-**Scope guardrail:**
-- Phase boundary from ROADMAP.md is FIXED
-- Discussion clarifies HOW to implement, not WHETHER to add more
-- If user suggests new capabilities: "That sounds like its own phase. I'll note it in Deferred Ideas."
-
 Do NOT populate with your own technical analysis. That comes during research/planning.
 
 Write file.
@@ -254,12 +315,23 @@ EOF
 Confirm: "Committed: docs(${PHASE}): capture phase context"
 </step>
 
+<step name="show_prework_status">
+Read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
+</step>
+
+<step name="update_state">
+Update `.planning/STATE.md` Last Command field:
+
+Format: `Last Command: ms:discuss-phase ${PHASE} | YYYY-MM-DD HH:MM`
+</step>
+
 </process>
 
 <success_criteria>
 
-- Vision gathered through collaborative thinking (not interrogation)
-- User's imagination captured: how it works, what's essential
+- Assumptions surfaced and validated with user before deep questioning
+- Product research offered for user-facing phases (skipped silently for infra/backend)
+- Vision gathered through product-informed collaborative thinking (not interrogation)
+- CONTEXT.md captures: vision, essentials, and decisions with inline reasoning
 - User knows next steps (typically: research or plan the phase)
-- CONTEXT.md committed to git
 </success_criteria>

package/mindsystem/workflows/doctor-fixes.md

@@ -0,0 +1,273 @@
+<purpose>
+Apply fixes for doctor health check failures. Each step targets one check category,
+runs only if that check failed, and commits atomically.
+</purpose>
+
+<process>
+
+<step name="fix_subsystems">
+**Only if Subsystem Vocabulary failed.**
+
+If subsystems array is empty (State A):
+
+1. Scan all artifacts for existing values:
+
+```bash
+ms-tools scan-artifact-subsystems --values-only
+```
+
+2. Read `.planning/PROJECT.md` and `.planning/ROADMAP.md`.
+
+3. Derive 5-12 canonical subsystem identifiers from:
+   - Unique values found in artifacts
+   - Project domain from PROJECT.md
+   - 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)
+
+4. Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
+
+5. 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
+
+6. After confirmation: update `config.json` (subsystems as first field), standardize existing artifact `subsystem:` fields using Edit tool.
+
+If subsystems exist but artifacts have mismatches (State B):
+
+1. Classify each artifact as OK/MISMATCH/MISSING.
+2. For MISMATCH: propose closest canonical value.
+3. For MISSING: propose based on artifact content/path.
+4. Apply fixes using Edit tool.
+
+Commit:
+
+```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(doctor): fix subsystem vocabulary
+
+Standardized subsystem configuration and artifact values.
+EOF
+)"
+```
+</step>
+
+<step name="fix_milestone_dirs">
+**Only if Milestone Directory Structure failed.**
+
+For each flat file like `milestones/v0.1-ROADMAP.md`:
+
+1. Extract version prefix (e.g., `v0.1`).
+2. Create directory if it doesn't exist: `mkdir -p .planning/milestones/v0.1`
+3. `git mv` the file, stripping the version prefix from the filename:
+   `git mv .planning/milestones/v0.1-ROADMAP.md .planning/milestones/v0.1/ROADMAP.md`
+
+**Note:** New milestones use slug-based directories (e.g., `milestones/mvp/`, `milestones/push-notifications/`). Old v-prefixed directories from previous format are valid and handled.
+
+Commit:
+
+```bash
+git add .planning/milestones/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): restructure milestone directories
+
+Moved flat milestone files into versioned directories.
+EOF
+)"
+```
+</step>
+
+<step name="fix_milestone_naming">
+**Only if Milestone Naming Convention failed.**
+
+1. **Build mapping** — run `ms-tools scan-milestone-naming`, parse JSON output.
+
+2. **Resolve slugs** — For each versioned dir, match to MILESTONES.md name mapping:
+   - Standard dirs: version matches directly (v0.1 → "MVP" → slug "mvp")
+   - Nested dirs: match sub-directory name to the milestone name in MILESTONES.md (v2.0.0/quests → "Quests Feature" → slug "quests-feature")
+   - Derive short slugs from names (Claude proposes, user confirms)
+
+3. **Present mapping** to user with AskUserQuestion:
+
+   ```
+   | Current Directory       | Milestone Name       | Proposed Slug    |
+   |-------------------------|----------------------|------------------|
+   | v0.1/                   | MVP                  | mvp              |
+   | v0.2/                   | Infrastructure       | infrastructure   |
+   | (active)                | Demo Release         | demo-release     |
+   ```
+
+   Options: "Looks good" / "Edit slugs" / "Skip"
+
+4. **Rename directories:**
+   - Standard: `git mv .planning/milestones/v0.1 .planning/milestones/mvp`
+   - Nested: `git mv .planning/milestones/v2.0.0/quests .planning/milestones/quests-feature` for each sub-dir, then `rmdir .planning/milestones/v2.0.0` to remove empty parent
+
+5. **Update archived milestone files** (inside each renamed dir):
+   - `PHASE-SUMMARIES.md`: `# Phase Summaries: v0.1` → `# Phase Summaries: MVP`
+   - `ROADMAP.md`: `# Milestone v0.1: Name` → `# Milestone: Name`
+   - `REQUIREMENTS.md`: `# Requirements Archive: v0.1 Name` → `# Requirements Archive: Name`
+   - `MILESTONE-AUDIT.md`: YAML `milestone: v0.1` → `milestone: mvp` (use slug)
+   - `CONTEXT.md`: `# Milestone Context: v0.1 Name` → `# Milestone Context: Name`
+
+6. **Update MILESTONES.md:**
+   - Strip version prefix from headers: `## v0.1 MVP (Shipped:...)` → `## MVP (Shipped:...)`
+   - Preserve all other content (git ranges, stats, accomplishments)
+
+7. **Update active .planning files:**
+   - `PROJECT.md`: Replace `— v0.1` with `— MVP` in validated requirements, strip version from `## Current Milestone:` header, update `Shipped v0.2 with...` → `Shipped Infrastructure with...`
+   - `STATE.md`: Replace version refs with names (`v0.3 Demo Release` → `Demo Release`)
+   - `ROADMAP.md`: Strip version from `**Milestone:** v0.3 Demo Release` → `**Milestone:** Demo Release`
+   - `MILESTONE-CONTEXT.md`: Strip version from header
+   - `REQUIREMENTS.md`: Strip version from `**Milestone:**` line. For deferred sections (`### v0.4 — On-Device Hardening`), use AskUserQuestion to confirm replacement names or keep description-only format (`### On-Device Hardening (deferred)`)
+
+8. **Rules:**
+   - Do NOT modify git range references (`**Git range:** feat(01-01) → ...`)
+   - Do NOT modify git commit messages quoted in MILESTONES.md
+   - Preserve shipped dates, stats, phase ranges
+   - Use Edit tool for targeted replacements (not bulk find-replace)
+
+9. **Commit:**
+
+```bash
+git add .planning/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): migrate milestone naming from versions to slugs
+
+Renamed milestone directories from version-based (v0.1/, v2.0.0/) to
+name-based slugs (mvp/, quests-feature/). Updated all planning file references.
+EOF
+)"
+```
+</step>
+
+<step name="fix_phase_archival">
+**Only if Phase Archival failed.**
+
+Parse MILESTONES.md for completed milestones and their phase ranges (`**Phases completed:** X-Y`).
+
+For each completed milestone with orphaned phases in `.planning/phases/`:
+
+1. Determine the version and phase range from MILESTONES.md.
+2. Ensure the milestone directory exists: `mkdir -p .planning/milestones/{slug}`
+3. Run the archive script:
+
+```bash
+ms-tools archive-milestone-phases <start> <end> <slug>
+```
+
+This simultaneously:
+- Consolidates PHASE-SUMMARIES.md (fixes Phase Summaries check)
+- Deletes raw artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION)
+- Moves phase directories to milestone archive
+
+**If MILESTONES.md doesn't have parseable phase ranges:** Use AskUserQuestion to ask the user for the phase range for each milestone.
+
+After archive completes, clean up leftover PLAN files in archived phases (fixes PLAN Cleanup check):
+
+```bash
+find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
+```
+
+Commit:
+
+```bash
+git add .planning/phases/ .planning/milestones/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): archive completed milestone phases
+
+Consolidated summaries, deleted raw artifacts, moved phase directories.
+EOF
+)"
+```
+</step>
+
+<step name="fix_plan_cleanup">
+**Only if PLAN Cleanup failed AND fix_phase_archival did not already handle it.**
+
+Delete leftover PLAN files in completed phase directories:
+
+```bash
+find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
+```
+
+For any leftover PLANs in `phases/` belonging to completed milestones (identified by the scan), delete those too.
+
+Commit:
+
+```bash
+git add .planning/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): clean up leftover PLAN files
+
+Removed PLAN files from completed phase directories.
+EOF
+)"
+```
+</step>
+
+<step name="fix_knowledge">
+**Only if Knowledge Files failed.**
+
+Spawn a `general-purpose` subagent (Task tool) to generate knowledge files retroactively. Provide the subagent with:
+
+- Subsystem vocabulary from config.json
+- Instructions to read all PHASE-SUMMARIES.md from `milestones/*/PHASE-SUMMARIES.md` AND any remaining SUMMARY files in `phases/`
+- The knowledge template at `~/.claude/mindsystem/templates/knowledge.md`
+- Instructions to read any existing knowledge files and merge (rewrite semantics — current state, not append)
+- Instructions to create `.planning/knowledge/` directory if missing
+- Instructions to write `.planning/knowledge/{subsystem}.md` for each missing subsystem
+
+After subagent completes, verify files exist:
+
+```bash
+ls .planning/knowledge/*.md
+```
+
+Commit:
+
+```bash
+git add .planning/knowledge/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): generate knowledge files
+
+Created per-subsystem knowledge files from phase summaries.
+EOF
+)"
+```
+</step>
+
+</process>

package/mindsystem/workflows/execute-phase.md

@@ -81,7 +81,7 @@ Skip completed plans. If all complete, report "Phase already executed" and exit.
 Run validation before launching executors:
 
 ```bash
-~/.claude/mindsystem/scripts/validate-execution-order.sh "$PHASE_DIR"
+ms-tools validate-execution-order "$PHASE_DIR"
 ```
 
 If validation fails (exit 1), stop execution and report the mismatch to user.
@@ -201,7 +201,7 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel.
 
    After reporting wave completion, update STATE.md with progress:
    ```bash
-   ~/.claude/mindsystem/scripts/update-state.sh {completed_count} {total_count}
+   ms-tools update-state {completed_count} {total_count}
    ```
 
 5. **Handle failures:**
@@ -412,7 +412,7 @@ Generate a patch file with all implementation changes from this phase.
 
 **Run the patch generation script:**
 ```bash
-~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}
+ms-tools generate-phase-patch ${PHASE_NUMBER}
 ```
 
 The script will:
@@ -527,6 +527,10 @@ git commit -m "docs: update codebase map after phase {X}"
 <step name="offer_next">
 Present next steps based on milestone status.
 
+**First, surface user actions:**
+
+Read `## User Actions Required` from all `*-SUMMARY.md` files in the phase directory. If any non-empty actions exist, present as `## ⚠ Action Required` block before route-specific content. Skip if all "None".
+
 **If more phases remain:**
 
 Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions to present "Next Up" with pre-work context for the next phase.

package/mindsystem/workflows/execute-plan.md

@@ -28,7 +28,7 @@ cat .planning/STATE.md 2>/dev/null
 <step name="load_plan">
 Read the plan file provided in your prompt context.
 
-Parse inline metadata from header: `**Subsystem:**` and `**Type:**` values.
+Parse inline metadata from header: `**Subsystem:**`, `**Type:**`, and `**Skills:**` values.
 
 Parse plan sections:
 - Context (files to read, @-references)
@@ -44,11 +44,9 @@ Parse plan sections:
 </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.
+**If `**Skills:**` is present in plan metadata:** Invoke each listed skill via the Skill tool before proceeding. These were confirmed by the user during planning — load them without further confirmation.
 
-- One clear match → invoke it directly
-- Multiple candidates → use AskUserQuestion to let the user choose
-- No match → proceed without
+**If `**Skills:**` is absent:** Proceed without loading skills. Skill discovery happens during `/ms:plan-phase` — absence means no skills were relevant.
 </step>
 
 <step name="execute">
@@ -300,6 +298,9 @@ completed: YYYY-MM-DD
 ## Issues Encountered
 [Problems during planned work, or "None"]
 
+## User Actions Required
+[Commands the user must run: migrations, package installs, env vars, server restarts. Or "None — no manual steps needed."]
+
 ## Next Step
 [Ready for next plan, or "Phase complete, ready for transition"]
 ```

package/mindsystem/workflows/map-codebase.md

@@ -100,8 +100,8 @@ After writing STACK.md, update config.json code_review fields with the appropria
 1. Read STACK.md to detect primary framework
 2. Map framework to code review agent names:
    - Flutter/Dart:
-     - adhoc: "ms-flutter-simplifier"
-     - phase: "ms-flutter-simplifier"
+     - adhoc: "ms-flutter-code-quality"
+     - phase: "ms-flutter-code-quality"
      - milestone: "ms-flutter-reviewer"
    - All others (React, Next.js, Node, Swift, Kotlin, etc.):
      - adhoc: "ms-code-simplifier"

package/mindsystem/workflows/mockup-generation.md

@@ -106,7 +106,7 @@ Task(prompt=assembled_context, subagent_type="ms-mockup-designer", description="
 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"
+ms-compare-mockups "${PHASE_DIR}/mockups"
 open "${PHASE_DIR}/mockups/comparison.html"
 ```