mindsystem-cc 4.4.2 → 4.5.0

package/commands/ms/design-phase.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 Create design specifications for a phase. Spawns ms-designer agent with phase context.
 
-**Orchestrator role:** Parse phase, validate against roadmap, check existing design, gather context chain (CONTEXT.md → project UI skill → codebase), adaptive Q&A if gaps, spawn designer agent, enable conversational refinement.
+**Orchestrator role:** Parse phase, validate against roadmap, check existing design, gather context chain (CONTEXT.md → design skill → codebase extraction), adaptive Q&A if gaps, spawn designer agent, enable conversational refinement.
 
 **When to use:**
 - UI-heavy phases with significant new interface work
@@ -70,27 +70,23 @@ Wait for response and act accordingly.
 
 **If doesn't exist:** Continue to gather context.
 
-## 3. Discover Relevant Skills
+## 3. Load Design Skills
 
-Before gathering context, check for skills that provide design-relevant conventions.
-
-**3a. Scan available skills:**
+```bash
+DESIGN_SKILLS=$(ms-tools config-get skills.design --default "[]")
+```
 
-Scan skills in your system-reminder for matches. Look for skills related to:
-- The platform or framework (Flutter, React, web, etc.)
-- UI conventions, design systems, or component patterns
-- The specific domain of this phase (from the ROADMAP.md phase description extracted in step 1)
+**If skills configured:** Invoke each via the Skill tool.
 
-**3b. Confirm with user:**
+After loading, check if the skill content contains project-specific design tokens (hex colors in palette context, spacing scales with values, font family names). If it does, these are the authoritative aesthetic — skip step 4c. If it contains only design methodology or you're uncertain, proceed to codebase extraction in step 4c.
 
-Present via AskUserQuestion with `multiSelect: true`:
-- Each matching skill is one option (label: skill name, description: what it provides)
-- Always include a "None — skip skill loading" option
-- User selects which to load, skips, or types a skill name in the free-text field
+**If no skills configured:**
 
-**3c. Load selected skills:**
+```
+Tip: Configuring design skills in /ms:config can improve design and mockup quality. Run /ms:config to set them up.
+```
 
-Invoke each confirmed skill via the Skill tool. Extract aesthetic patterns (colors, components, spacing, typography) from loaded content for the `<existing_aesthetic>` block in step 6.
+Non-blocking. Proceed to codebase extraction in step 4c.
 
 ## 4. Gather Context Chain
 
@@ -148,31 +144,57 @@ If knowledge files exist, extract:
 
 Pass the extracted knowledge to ms-designer in the design prompt (see step 6 `<prior_knowledge>` block).
 
-**4c. Optional context - codebase analysis:**
+**4c. Optional context - codebase aesthetic extraction:**
 
-```bash
-# Platform detection
-if [ -f "pubspec.yaml" ]; then
-  echo "Platform: Flutter (pubspec.yaml found)"
-  # Search Flutter project structure
-  find lib -name "*.dart" 2>/dev/null | head -20
-  grep -r "colors\|theme\|spacing" lib/ --include="*.dart" 2>/dev/null | head -10
-elif [ -f "package.json" ]; then
-  echo "Platform: Web (package.json found)"
-  grep -E "react|vue|angular|svelte" package.json 2>/dev/null | head -5
-  # Search web project structure
-  find src -name "*.tsx" -o -name "*.ts" -o -name "*.jsx" 2>/dev/null | head -20
-  grep -r "colors\|theme\|spacing" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -10
-fi
+If authoritative aesthetic already gathered from skill in step 3 → skip this step.
+
+Otherwise, spawn an Explore agent to extract the project's visual identity:
+
+```
+Task(
+  prompt="Read `.planning/PROJECT.md` (Technical Context section) for tech stack. If PROJECT.md doesn't exist, read root dependency files (`pubspec.yaml`, `package.json`, etc.) to identify the framework.
+
+Extract exact values for:
+- **Color palette:** background, text, accent, error — hex values with semantic roles
+- **Typography scale:** font families, size/weight combos
+- **Spacing system:** recurring padding/margin/gap values
+- **Reusable UI components:** names + visual characteristics (border-radius, shadows)
+- **Layout conventions:** navigation pattern, content layout
+
+Format findings as:
+
+Color palette:
+| Role | Value | Context |
+|------|-------|---------|
+| [role] | #hex | [where used] |
+
+Typography:
+| Element | Family | Size/Weight | Usage |
+|---------|--------|-------------|-------|
+| [element] | [family] | [size/weight] | [where used] |
+
+Spacing scale:
+[base unit and scale values]
+
+Component inventory:
+- [ComponentName] — [visual characteristics]
+
+Layout conventions:
+- [pattern description]
+
+Extract EXACT values (hex codes, pixel values, font names). Don't summarize or approximate. Return 'not found' for sections with no data. Look in theme files, style constants, design token files, and framework-specific configuration — you know where these live for the detected framework.",
+  subagent_type="Explore",
+  description="Extract codebase aesthetic"
+)
 ```
 
-Document discovered patterns for the designer.
+If the agent returns mostly empty results → greenfield. If substantive findings → use them for the `<existing_aesthetic>` block in step 6.
 
 ## 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 visual style be inferred? (from existing aesthetic)
 - Can design priorities be inferred? (from CONTEXT.md or phase requirements)
 
 **If everything can be inferred:** Skip to step 6.
@@ -206,17 +228,7 @@ Use AskUserQuestion:
 
 **If user selects "Yes":**
 
-Read `~/.claude/mindsystem/workflows/mockup-generation.md` and follow the mockup-generation workflow.
-
-1. Determine platform from context chain (or ask user)
-2. Identify primary screen for the phase
-3. Derive 3 design directions from feature context
-4. Present directions to user for approval/tweaking
-5. Read platform template (mobile or web)
-6. Spawn 3 x ms-mockup-designer agents in parallel
-7. Run comparison script (`compare_mockups.py`), open in browser, and present to user
-8. Handle selection (single pick, combine, tweak, more variants, or skip)
-9. Extract CSS specs from chosen variant into `<mockup_direction>` block
+Read `~/.claude/mindsystem/workflows/mockup-generation.md` and follow the mockup-generation workflow. Generate 3 HTML mockup variants, present comparison to user, and handle selection.
 
 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.
 
@@ -275,7 +287,7 @@ Reference products:
 
 [If CONTEXT.md doesn't exist:]
 
-Vision inferred from phase requirements and PROJECT.md context.
+No explicit vision provided. Derive design direction from phase requirements and product context above.
 Reference products: [From Q&A if asked, or "None specified"]
 </user_vision>
 
@@ -297,24 +309,35 @@ No prior knowledge files. First phase or no prior execution.
 </prior_knowledge>
 
 <existing_aesthetic>
-[If project UI skill exists:]
+[Always present. Populated from skill content OR Explore agent findings OR greenfield.]
+
+Color palette:
+| Role | Value | Context |
+|------|-------|---------|
+| bg-primary | #hex | Main background |
+| text-primary | #hex | Body text |
+| accent | #hex | Interactive elements |
+| ... | | |
+
+Typography:
+| Element | Family | Size/Weight | Usage |
+|---------|--------|-------------|-------|
+| heading | [family] | [size/weight] | Page titles |
+| body | [family] | [size/weight] | General content |
+| ... | | | |
 
-Authoritative patterns from project UI skill:
-- Color palette: [exact values]
-- Typography: [font families, sizes]
-- Spacing system: [scale values]
-- Component library: [named components]
+Spacing scale:
+[base unit and scale values, e.g. 4/8/12/16/24/32px]
 
-[If no UI skill, from codebase analysis:]
+Component inventory:
+- [ComponentName] — [visual characteristics]
 
-Discovered patterns from codebase:
-- Colors found: [hex values from theme/styles]
-- Components found: [existing component names]
-- Layout patterns: [grid systems, spacing used]
+Layout conventions:
+- [Navigation pattern, content layout, responsive breakpoints]
 
-[If greenfield:]
+Platform: [Flutter / React / etc.]
 
-No existing aesthetic. Design fresh with platform conventions.
+[If greenfield: "No existing aesthetic. Design fresh with platform conventions."]
 </existing_aesthetic>
 
 <mockup_direction>
@@ -413,7 +436,6 @@ After initial generation, if user wants to refine:
 **Refinement principles:**
 - Direct edits — Edit DESIGN.md directly, don't regenerate
 - Preserve decisions — Changes are incremental, not wholesale replacement
-- User controls pace — User decides when design is "done"
 
 **For major redesigns (multiple aspects changing):**
 
@@ -439,11 +461,9 @@ Read `~/.claude/mindsystem/templates/design-iteration.md` and use the iteration
 </process>
 
 <success_criteria>
-- [ ] Available skills scanned, surfaced via AskUserQuestion, and loaded via Skill tool
-- [ ] Codebase analyzed for existing patterns (step 4c)
+- [ ] Aesthetic context gathered: skills checked for design tokens, codebase extraction run if needed
 - [ ] Adaptive Q&A completed if context gaps existed
-- [ ] Mockup generation offered if phase has significant new UI
-- [ ] Mockup direction extracted and passed to ms-designer (if generated)
+- [ ] Mockup generation offered for significant UI; direction passed to ms-designer if generated
 - [ ] ms-designer spawned with quality-forcing patterns
 - [ ] DESIGN.md created with Design Direction, Design Tokens, and Screens sections and committed
 - [ ] User informed of refinement options and next steps

package/commands/ms/discuss-phase.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Write
   - Bash
   - Glob
+  - Skill
   - AskUserQuestion
   - Task
 ---

package/commands/ms/doctor.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <objective>
-Run health checks on project configuration. Detect and fix structural drift across 12 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers and environment diagnostics, research API keys, phase directory naming, browser verification prerequisites, and Mindsystem version.
+Run health checks on project configuration. Detect and fix structural drift across 14 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers and environment diagnostics, research API keys, phase directory naming, browser verification prerequisites, roadmap format, phase skills, and Mindsystem version.
 
 Idempotent.
 </objective>
@@ -121,6 +121,8 @@ Display results as a markdown table:
 | Research API Keys        | WARN   | PERPLEXITY_API_KEY not set        |
 | Phase directory naming   | FAIL   | 1 non-canonical directory         |
 | Browser Verification     | WARN   | Web project, missing agent-browser CLI |
+| Roadmap Format           | FAIL   | 4 pre-work flag issues               |
+| Phase Skills             | WARN   | skills.plan, skills.design not configured |
 | Mindsystem version       | WARN   | v3.21.0 → v3.22.1 available       |
 ```
 
@@ -143,7 +145,7 @@ If "Skip" → go to `report`.
 
 If "Review each" → use AskUserQuestion for each failed check with its details and options: "Fix" / "Skip". Only run fixes for accepted checks.
 
-Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_phase_dirs → fix_knowledge. Skip any fix whose check passed or was skipped by user.
+Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_phase_dirs → fix_knowledge → fix_roadmap_format. Skip any fix whose check passed or was skipped by user.
 
 Phase summaries are resolved by fix_phase_archival. CLI wrapper failures have specific fixes: bin dir not in PATH → restart Claude Code session; missing wrappers or bin dir → re-run `npx mindsystem-cc`; uv not found → `curl -LsSf https://astral.sh/uv/install.sh | sh`. WARN checks (Research API Keys, missing uv) are informational — no automated fix, only displayed in the report. Research API Keys check provides platform-aware setup guidance (shell export on macOS/Linux, settings.json on Windows) and checks both environment variables and `~/.claude/settings.json` env section as fallback.
 </step>
@@ -183,6 +185,8 @@ Final summary table:
 | Research API Keys        | PASS   | ...                              |
 | Phase directory naming   | PASS   | ...                              |
 | Browser Verification     | PASS   | ...                              |
+| Roadmap Format           | PASS   | ...                              |
+| Phase Skills             | PASS   | ...                              |
 | Mindsystem version       | PASS   | ...                              |
 
 All checks passed.
@@ -199,6 +203,6 @@ Include counts: checks total, passed, warned, fixed during this run.
 - [ ] Re-scan verifies all checks pass after fixes
 - [ ] Each fix group committed atomically
 - [ ] Fixes applied in dependency order: subsystems → dirs → milestone naming → archival → cleanup → knowledge
-- [ ] All 12 categories reported with PASS/FAIL/WARN/SKIP
+- [ ] All 14 categories reported with PASS/FAIL/WARN/SKIP
 - [ ] Clean project reports all PASS with no fix prompts
 </success_criteria>

package/commands/ms/execute-phase.md

@@ -178,11 +178,7 @@ All {Y} plans finished. Phase goal verified.
 
 **Route A: More phases remain**
 
-4. **If skip context applies:** Determine next phase's primary suggestion:
-   - From ROADMAP.md (already in context), get Phase {Z+1} pre-work flags
-   - Check: CONTEXT.md exists? DESIGN.md? RESEARCH.md? in next phase dir
-   - Priority: discuss (if Likely + no CONTEXT.md) > design (if Likely + no DESIGN.md) > research (if Likely + no RESEARCH.md) > plan-phase
-   - Present ONE "Also available" entry:
+4. **If skip context applies:** Run `ms-tools prework-status {Z+1}` and use the Suggested line for the "Also available" entry:
    ```
    ---
    **Also available:**

package/commands/ms/help.md

@@ -38,7 +38,7 @@ Output ONLY the reference content below. Do NOT add:
 2. `/ms:map-codebase` — Analyze existing code for patterns and conventions
 3. `/ms:doctor` — Validate config and generate knowledge files from source code
 
-Optional: `/ms:config` — Configure code reviewers, gitignore, and other preferences
+Optional: `/ms:config` — Configure skills, code reviewers, gitignore, and other preferences
 
 ### Building features (repeat per milestone)
 
@@ -108,9 +108,9 @@ Initialize new project with brief and configuration.
 Usage: `/ms:new-project`
 
 **`/ms:config`**
-Configure Mindsystem preferences — code reviewers, mockup preferences, browser verification, plan mode, gitignore patterns, git remote, task tracker.
+Configure Mindsystem preferences — per-phase skills, code reviewers, mockup preferences, browser verification, plan mode, gitignore patterns, git remote, task tracker.
 
-- Use when: you want to set up code review agents, mockup open behavior, manage which .planning/ artifacts are git-ignored, or push your repo to GitHub.
+- Use when: you want to configure per-phase skills, set up code review agents, mockup open behavior, manage which .planning/ artifacts are git-ignored, or push your repo to GitHub.
 - Edits `.planning/config.json` and `.gitignore`
 - Suggests code reviewers based on tech stack (needs PROJECT.md)
 - Idempotent — run anytime to reconfigure
@@ -366,6 +366,7 @@ Execute discovered work with knowledge-aware planning and execution.
 - Use when: you discover work mid-session that can be completed in a single context window without multi-phase orchestration.
 - Bridges the gap between `/ms:add-todo` (capture for later) and `/ms:insert-phase` (multi-plan coordination)
 - Knowledge-aware: loads relevant knowledge files before planning, consolidates learnings after execution
+- Browser verification for web projects (same flow as execute-phase)
 - Accepts Linear ticket IDs when task tracker is configured via `/ms:config` — auto-fetches context, tags commits, and finalizes the ticket on completion
 - Spawns Explore agents for codebase understanding, ms-adhoc-planner for plan creation, ms-executor for execution
 - Creates per-execution artifacts in `.planning/adhoc/{timestamp}-{slug}/`
@@ -381,7 +382,7 @@ Usage: `/ms:adhoc Refactor API error handling to use consistent format`
 Health check and fix project configuration — subsystems, milestone structure, knowledge files.
 
 - Use when: project has structural drift, missing config, or periodic health check
-- Runs 6 checks: subsystem vocabulary, milestone directories, phase archival, knowledge files, phase summaries, PLAN cleanup
+- Runs 14 checks: subsystem vocabulary, milestone directories, milestone naming, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers, API keys, phase directory naming, browser verification prerequisites, roadmap format, phase skills, version freshness
 - Presents results table, then offers to fix all issues in dependency order
 - Each fix group gets its own atomic commit
 - Idempotent — safe to run repeatedly
@@ -480,7 +481,7 @@ Usage: `/ms:release-notes`
 /ms:doctor                      # Validate config, generate knowledge files
 ```
 
-Optional: `/ms:config` — configure code reviewers, gitignore, and other preferences
+Optional: `/ms:config` — configure skills, code reviewers, gitignore, and other preferences
 
 **Building features (repeat per milestone):**
 

package/commands/ms/remove-phase.md

@@ -168,37 +168,19 @@ fi
 If directory doesn't exist, note: "No directory to delete (phase not yet created)"
 </step>
 
-<step name="renumber_directories">
-Rename all subsequent phase directories:
-
-For each phase directory that needs renumbering (in reverse order to avoid conflicts):
+<step name="renumber_phases">
+Renumber all subsequent phase directories and their files:
 
 ```bash
-# Example: renaming 18-dashboard to 17-dashboard
-mv ".planning/phases/18-dashboard" ".planning/phases/17-dashboard"
+ms-tools phase-renumber "$PHASE"
 ```
 
-Process in descending order (20→19, then 19→18, then 18→17) to avoid overwriting.
-
-Also rename decimal phase directories:
-- `17.1-fix-bug` → `16.1-fix-bug` (if removing integer 17)
-- `17.2-hotfix` → `17.1-hotfix` (if removing decimal 17.1)
-</step>
-
-<step name="rename_files_in_directories">
-Rename plan files inside renumbered directories:
+Renames all phase directories with numbers greater than the removed phase (decrementing by 1), and renames phase-prefixed files inside those directories.
 
-For each renumbered directory, rename files that contain the phase number:
-
-```bash
-# Inside 17-dashboard (was 18-dashboard):
-mv "18-01-PLAN.md" "17-01-PLAN.md"
-mv "18-02-PLAN.md" "17-02-PLAN.md"
-mv "18-01-SUMMARY.md" "17-01-SUMMARY.md"  # if exists
-# etc.
-```
+For integer removal: subsequent integers and their decimals are decremented. Decimals under the removed integer fold into the prior integer (17.1 → 16.1).
+For decimal removal: only subsequent decimals in the same series are decremented. Integer phases unchanged.
 
-Also handle CONTEXT.md and DISCOVERY.md (these don't have phase prefixes, so no rename needed).
+Review the JSON output to confirm expected renames before proceeding.
 </step>
 
 <step name="update_roadmap">

package/commands/ms/research-phase.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Task
   - Write
+  - Skill
   - AskUserQuestion
 ---
 
@@ -106,6 +107,18 @@ Spawning 3 parallel agents:
 Proceed? (yes / adjust scope / change mode)
 ```
 
+## 4b. Load Research Skills
+
+```bash
+RESEARCH_SKILLS=$(ms-tools config-get skills.research --default "[]")
+```
+
+**If skills configured:** Invoke each via the Skill tool. Use skill content to:
+- Add brief domain context to each research agent's prompt (alongside `<prior_knowledge>`)
+- Inform synthesis decisions when mapping agent findings to RESEARCH.md sections (step 6)
+
+**If no skills configured:** Continue silently. Research agents perform well with just project context.
+
 ## 5. Spawn 3 Agents in Parallel
 
 Announce: "Spawning 3 research agents in parallel..."

package/commands/ms/review-design.md

@@ -76,7 +76,7 @@ Before analyzing, establish what this screen is trying to accomplish.
 - Read `.planning/PROJECT.md` for product type, core value, target audience
 - If phase-based, grep `.planning/ROADMAP.md` for phase requirements
 - Glob for existing DESIGN.md in `.planning/phases/` for design intent
-- Scan available skills in system-reminder for matches related to UI, design, or the screen's platform/framework. If matches found, present via AskUserQuestion with `multiSelect: true`: each matching skill is one option (label: skill name, description: what it provides), always include a "None — skip skill loading" option. User selects which to load, skips, or types a skill name in the free-text field. Load selected skills via Skill tool for existing patterns.
+- Load design skills from config: `ms-tools config-get skills.design --default "[]"`. If configured, invoke each via the Skill tool for existing patterns. If not configured, proceed without (no nudge — review-design is a utility command, not a core phase).
 
 **State the screen's job in one sentence:**
 > "This screen helps the user [accomplish X]."

package/commands/ms/verify-work.md

@@ -56,8 +56,7 @@ ms-tools find-phase "$ARGUMENTS"
    - **For each issue found:**
      - On first issue: load knowledge files (match phase subsystem against `.planning/knowledge/*.md`)
      - Lightweight investigation (2-3 tool calls, informed by knowledge)
-     - If simple: Fix inline, commit (amend previous fix commit on retry when HEAD matches fix_commit), ask for re-test
-     - If complex: Spawn ms-verify-fixer subagent (with knowledge context in prompt)
+     - Fix inline, commit (amend previous fix commit on retry when HEAD matches fix_commit), ask for re-test
      - 2 retries on failed re-test, then offer options
 8. **On batch transition:**
    - If new mock_type: Revert old mocks (`git checkout -- <mocked_files>`), apply new ones
@@ -79,7 +78,6 @@ ms-tools find-phase "$ARGUMENTS"
 - Don't present more than 4 tests at a time
 - Don't run automated tests — this is manual user validation
 - Don't skip investigation — always try 2-3 tool calls before escalating
-- Don't fix complex issues inline — spawn fixer subagent for multi-file or architectural changes
 - Don't commit mock code — stash mocked files before fixing, restore after
 - Don't re-present skipped tests — assumptions stand
 - Don't Read/Edit UAT.md for field updates — use `ms-tools uat-update`

package/mindsystem/references/design-directions.md

@@ -93,7 +93,7 @@ Rule: If you can only tell variants apart by squinting at colors, they are not d
 
 <existing_aesthetic_constraint>
 
-When the project has an existing visual aesthetic (project UI skill, established codebase patterns):
+When `<existing_aesthetic>` contains concrete values:
 
 **ALL variants use the same colors, fonts, and component shapes.** Directions differ ONLY in:
 - Layout and spatial organization
@@ -104,7 +104,7 @@ When the project has an existing visual aesthetic (project UI skill, established
 
 This constraint is non-negotiable. Mockup directions explore layout alternatives, not brand alternatives. An existing product stays visually cohesive across all variants.
 
-When the project is greenfield (no existing aesthetic):
+When `<existing_aesthetic>` states no existing aesthetic:
 - Each variant MAY propose a different color palette
 - Each variant MAY propose different typography
 - Structural differences remain the primary differentiator

package/mindsystem/references/plan-format.md

@@ -43,7 +43,7 @@ Details referencing existing utilities: "Use `comparePassword` in `src/lib/crypt
 | Section | Purpose | Required |
 |---------|---------|----------|
 | `# Plan NN: Title` | H1 with plan number and descriptive title | Yes |
-| `**Subsystem:** X \| **Type:** Y \| **Skills:** Z` | Inline metadata (replaces YAML frontmatter) | Yes (type defaults to `execute`, skills optional) |
+| `**Subsystem:** X \| **Type:** Y` | Inline metadata (replaces YAML frontmatter) | Yes (type defaults to `execute`) |
 | `## Context` | Why this work exists, why this approach | Yes |
 | `## Changes` | Numbered subsections with files and implementation details | Yes |
 | `## Verification` | Bash commands and observable checks | Yes |
@@ -130,17 +130,6 @@ Matches vocabulary from the project's `config.json`. Used by the executor when g
 
 When `**Type:**` is omitted, the plan defaults to `execute`.
 
-### Skills
-
-| Value | Behavior |
-|-------|----------|
-| *(omitted)* | No skills loaded. Skill discovery happens during `/ms:plan-phase` — absence means none were relevant. |
-| `skill-a, skill-b` | Executor invokes listed skills via Skill tool before implementing. |
-
-Skills are confirmed by the user during `/ms:plan-phase` and encoded into plans. Comma-separated list of skill names matching entries in the system-reminder.
-
----
-
 ## Must-Haves Specification
 
 The `## Must-Haves` section is a markdown checklist consumed by ms-verifier. Each item is a user-observable truth — not an implementation detail.
@@ -199,7 +188,7 @@ Execution order lives in a single `EXECUTION-ORDER.md` file alongside the plans.
 | What triggers TDD lazy-loading? | `**Type:** tdd` in inline metadata |
 | How does the executor know why an approach was chosen? | Reads `## Context` section |
 | How does the executor find existing utilities? | Reads `**Files:**` lines and inline references in `## Changes` |
-| What triggers skill loading in executor? | `**Skills:**` in inline metadata. No skills loaded if omitted. |
+| How do skills influence plans? | Skill conventions are woven into plan content during `/ms:plan-phase`. No runtime skill loading by executor. |
 
 ---
 

package/mindsystem/references/prework-status.md

@@ -6,46 +6,20 @@ Reference for showing what pre-work is done vs still needed for the CURRENT phas
 
 After completing one pre-work command, show what else is recommended before planning.
 
-## Information to Extract
+## Data
 
-From ROADMAP.md, get the current phase details:
+Run `ms-tools prework-status` to get pre-work flags, completion status, and routing suggestion:
 
 ```bash
-grep -A 25 "### Phase ${PHASE}:" .planning/ROADMAP.md
+ms-tools prework-status "${PHASE}"
 ```
 
-Extract:
-- `**Research**: Likely/Unlikely (reason)`
-- `**Discuss**: Likely/Unlikely (reason)`
-- `**Design**: Likely/Unlikely (reason)`
-
-Check what context files already exist:
-
-```bash
-ms-tools find-phase "${PHASE}"
-# Extract PHASE_DIR from the `dir` field of the JSON output
-[ -f "$PHASE_DIR"/*-CONTEXT.md ] && echo "CONTEXT_EXISTS"
-[ -f "$PHASE_DIR"/*-DESIGN.md ] && echo "DESIGN_EXISTS"
-[ -f "$PHASE_DIR"/*-RESEARCH.md ] && echo "RESEARCH_EXISTS"
-```
-
-## Routing Logic
-
-Suggest the next incomplete Likely pre-work:
-
-```
-IF Discuss: Likely AND no CONTEXT.md:
-  SUGGEST = discuss-phase
-ELSE IF Design: Likely AND no DESIGN.md:
-  SUGGEST = design-phase
-ELSE IF Research: Likely AND no RESEARCH.md:
-  SUGGEST = research-phase
-ELSE:
-  SUGGEST = plan-phase (ready to plan)
-```
+Output includes phase name, goal, pre-work flags with status (done/not started), existing artifacts, and the suggested next command with reason.
 
 ## Output Format
 
+Use the `prework-status` output to populate this template:
+
 ```markdown
 ---
 

package/mindsystem/references/routing/next-phase-routing.md

@@ -6,54 +6,20 @@ Reference for presenting "Next Up" guidance for a phase. Used by progress (curre
 
 Help user decide between Discuss/Research/Design/Plan for a target phase using ROADMAP.md pre-work flags.
 
-## Information to Extract
+## Data
 
-From ROADMAP.md, get the target phase details:
+Run `ms-tools prework-status` to get phase info, pre-work status, and routing suggestion:
 
 ```bash
-grep -A 25 "### Phase ${TARGET_PHASE}:" .planning/ROADMAP.md
+ms-tools prework-status "${TARGET_PHASE}"
 ```
 
-Extract:
-- Phase name and goal
-- `**Research**: Likely/Unlikely (reason)`
-- `**Research topics**: ...` (if Likely)
-- `**Discuss**: Likely/Unlikely (reason)`
-- `**Discuss topics**: ...` (if Likely)
-- `**Design**: Likely/Unlikely (reason)`
-- `**Design focus**: ...` (if Likely)
-
-Check for existing context files:
-
-```bash
-ms-tools find-phase "${TARGET_PHASE}"
-# Extract PHASE_DIR from the `dir` field of the JSON output
-[ -f "$PHASE_DIR"/*-CONTEXT.md ] && echo "CONTEXT_EXISTS"
-[ -f "$PHASE_DIR"/*-DESIGN.md ] && echo "DESIGN_EXISTS"
-[ -f "$PHASE_DIR"/*-RESEARCH.md ] && echo "RESEARCH_EXISTS"
-```
-
-## Routing Logic
-
-Determine primary suggestion (priority order):
-
-```
-IF Discuss: Likely AND no CONTEXT.md:
-  PRIMARY = discuss-phase
-  REASON = from Discuss parenthetical
-ELSE IF Design: Likely AND no DESIGN.md:
-  PRIMARY = design-phase
-  REASON = from Design parenthetical
-ELSE IF Research: Likely AND no RESEARCH.md:
-  PRIMARY = research-phase
-  REASON = from Research parenthetical
-ELSE:
-  PRIMARY = plan-phase
-  REASON = "ready to plan"
-```
+Output includes phase name, goal, pre-work flags with status (done/not started), existing artifacts, and the suggested next command with reason.
 
 ## Output Format
 
+Use the `prework-status` output to populate this template:
+
 ```markdown
 ---
 
@@ -77,7 +43,7 @@ ELSE:
 
 ### Suggested
 
-`/ms:{primary} {N}` — {reason}
+`/ms:{suggested command} {N}` — {reason}
 
 <sub>`/clear` first → fresh context window</sub>
 

package/mindsystem/references/scope-estimation.md

@@ -41,9 +41,13 @@ Why 50% not 80%?
 </task_rule>
 
 <tdd_plans>
-**TDD features get their own plans. Target ~40% context.**
+**In multi-plan mode, TDD features get their own plans. Target ~40% context.**
 
-TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than linear task execution. TDD features are inherently heavy-weight (~25-40% marginal) and are always isolated into dedicated plans.
+TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than linear task execution.
+
+In **multi-plan mode** (`multi_plan: true`), TDD features are isolated into dedicated plans — the orchestrator proposes them as standalone plans during grouping.
+
+In **single-plan mode** (default), TDD tasks are included inline alongside other tasks. The orchestrator already determined that all tasks fit within one plan's context budget. Do not split TDD tasks into separate plans in single-plan mode.
 
 | TDD Feature Complexity | Context Usage |
 |------------------------|---------------|
@@ -51,9 +55,9 @@ TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file r
 | Business logic with edge cases | ~35-40% |
 | Complex algorithm | ~40-50% |
 
-**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD.
+**One feature per TDD plan (multi-plan mode only).** If features are trivial enough to batch, they're trivial enough to skip TDD.
 
-**Why TDD plans are separate:**
+**Why TDD plans are separate in multi-plan mode:**
 - TDD consumes 40-50% context for a single feature
 - Dedicated plans ensure full quality throughout RED-GREEN-REFACTOR
 - Each TDD feature gets fresh context, peak quality