mindsystem-cc 3.19.0 → 3.20.0

package/agents/ms-designer.md

@@ -29,9 +29,12 @@ Your job: Transform user vision into concrete, implementable design specificatio
 
 | Section | How You Use It |
 |---------|----------------|
-| `## What This Is` | Product type informs design conventions |
+| `## What This Is` | Product identity — informs design conventions |
 | `## Core Value` | The ONE thing design must serve |
-| `## Context` | Target audience shapes UX priorities |
+| `## Who It's For` | Target audience — shapes UX complexity, language, navigation priorities |
+| `## Core Problem` | Problem being solved — clarifies what UI must address first |
+| `## How It's Different` | Competitive context — prevents generic design |
+| `## Key User Flows` | Primary interactions — drives screen hierarchy and navigation |
 | `## Constraints` | Technical limits, platform requirements |
 
 **ROADMAP.md** — Phase-specific requirements

package/agents/ms-plan-writer.md

@@ -16,6 +16,7 @@ Your job: Transform task lists into PLAN.md files following the orchestrator's p
 **What you receive:**
 - Task list with needs/creates/tdd_candidate flags
 - Proposed grouping from orchestrator (plan boundaries, wave assignments, budget estimates)
+- Confirmed skills from user (skill names to embed in plan metadata)
 - Phase context (number, name, goal, directory, requirements)
 - Project references (paths to STATE, ROADMAP, CONTEXT, prior summaries)
 - Relevant learnings from past work (debug resolutions, adhoc insights, established patterns, prior decisions, curated cross-milestone learnings)
@@ -89,6 +90,10 @@ The orchestrator provides structured XML:
   </plan>
 </proposed_grouping>
 
+<confirmed_skills>
+  flutter-code-quality, flutter-code-simplification
+</confirmed_skills>
+
 <learnings>
   <learning type="debug" source=".planning/debug/resolved/n-plus-one-queries.md">Missing eager loading on association chains — fix: Added includes() for all relationship traversals</learning>
   <learning type="pattern" source=".planning/phases/02-foundation/02-01-SUMMARY.md">All API endpoints use Zod validation on input</learning>
@@ -227,7 +232,7 @@ For each plan, create `.planning/phases/{phase_dir}/{phase}-{plan}-PLAN.md`:
 ```markdown
 # Plan {NN}: {Descriptive Title}
 
-**Subsystem:** {subsystem_hint} | **Type:** tdd
+**Subsystem:** {subsystem_hint} | **Type:** tdd | **Skills:** {skill_names}
 
 ## Context
 {Why this work exists. Approach chosen and WHY.}
@@ -255,6 +260,8 @@ For each plan, create `.planning/phases/{phase_dir}/{phase}-{plan}-PLAN.md`:
 
 **Format rules:**
 - Omit `| **Type:** tdd` when type is execute (type defaults to execute)
+- Omit `| **Skills:** ...` when no skills were confirmed (confirmed_skills is "none" or empty)
+- Include `| **Skills:** skill-a, skill-b` when skills were confirmed — apply to ALL plans in the phase
 - Plans carry no `<execution_context>`, `<context>`, or @-references — the executor loads its own workflow and project files via its agent definition
 - No `<tasks>`, `<verification>`, `<success_criteria>`, `<output>` XML containers
 

package/commands/ms/add-phase.md

@@ -118,13 +118,36 @@ Confirm: "Created directory: $phase_dir"
 Add the new phase entry to the roadmap:
 
 1. Find the insertion point (after last phase in current milestone, before "---" separator)
-2. Insert new phase heading:
+
+2. Before writing the phase entry, analyze the description to determine pre-work flags:
+
+   **Discuss**: Likely when description mentions user-facing features, UX decisions,
+   experiential qualities, or novel features. Unlikely for backend/infra, bug fixes,
+   technical debt, or clear-cut work.
+
+   **Design**: Likely when description involves UI work, visual elements, forms,
+   dashboards, or multi-screen flows. Unlikely for backend-only, API, infrastructure,
+   or established UI patterns.
+
+   **Research**: Likely when description mentions external APIs/services, new
+   libraries/frameworks, or unclear technical approach. Unlikely for established
+   internal patterns or well-documented conventions.
+
+   Use binary Likely/Unlikely with parenthetical reason. Include topics/focus only when Likely.
+
+3. Insert new phase heading with pre-work flags:
 
    ```
    ### Phase {N}: {Description}
 
    **Goal:** [To be planned]
    **Depends on:** Phase {N-1}
+   **Discuss**: {Likely (reason) | Unlikely (reason)}
+   **Discuss topics**: {topics} ← only if Likely
+   **Design**: {Likely (reason) | Unlikely (reason)}
+   **Design focus**: {focus} ← only if Likely
+   **Research**: {Likely (reason) | Unlikely (reason)}
+   **Research topics**: {topics} ← only if Likely
    **Plans:** 0 plans
 
    Plans:
@@ -134,7 +157,7 @@ Add the new phase entry to the roadmap:
    [To be added during planning]
    ```
 
-3. Write updated roadmap back to file
+4. Write updated roadmap back to file
 
 Preserve all other content exactly (formatting, spacing, other phases).
 </step>
@@ -164,24 +187,13 @@ Phase {N} added to current milestone:
 Roadmap updated: {roadmap-path}
 Project state updated: .planning/STATE.md
 
----
-
-## ▶ Next Up
-
-**Phase {N}: {description}**
-
-`/ms:plan-phase {N}`
-
-<sub>`/clear` first → fresh context window</sub>
+```
 
----
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions
+to present "Next Up" with pre-work context for Phase {N}.
 
-**Also available:**
+After the "Next Up" section, add:
 - `/ms:add-phase <description>` — add another phase
-- Review roadmap
-
----
-```
 </step>
 
 <step name="update_last_command">

package/commands/ms/design-phase.md

@@ -15,8 +15,6 @@ Create design specifications for a phase. Spawns ms-designer agent with phase co
 
 **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.
 
-**Why subagent:** Design requires focused attention with quality-forcing patterns. Fresh 200k context for design generation. Main context reserved for user refinement conversation.
-
 **When to use:**
 - UI-heavy phases with significant new interface work
 - Novel flows/components not deducible from existing patterns
@@ -108,7 +106,10 @@ grep -A30 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
 Extract from PROJECT.md:
 - What This Is (product type)
 - Core Value (design must serve this)
-- Context (target audience)
+- Who It's For (target audience and their context)
+- Core Problem (what the design must address)
+- How It's Different (competitive context, differentiators)
+- Key User Flows (primary interactions that drive hierarchy)
 - Constraints (platform, technical limits)
 
 Extract from ROADMAP.md:
@@ -148,18 +149,18 @@ Pass the extracted knowledge to ms-designer in the design prompt (see step 6 `<p
 
 ```bash
 # Platform detection
-if [ -f "package.json" ]; then
-  echo "Platform: Web (package.json found)"
-  grep -E "react|vue|angular|svelte" package.json 2>/dev/null | head -5
-fi
-
 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
-
-# Find existing component/theme files
-find src -name "*.tsx" -o -name "*.dart" 2>/dev/null | head -20
-grep -r "colors\|theme\|spacing" src/ --include="*.ts" --include="*.dart" 2>/dev/null | head -10
 ```
 
 Document discovered patterns for the designer.
@@ -202,8 +203,7 @@ Use AskUserQuestion:
 
 **If user selects "Yes":**
 
-Follow mockup-generation workflow:
-@~/.claude/mindsystem/workflows/mockup-generation.md
+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
@@ -230,11 +230,20 @@ Platform: [Inferred from codebase or PROJECT.md constraints]
 Phase: [N]: [Phase name from ROADMAP.md]
 
 Target audience:
-[From PROJECT.md - Context section]
+[From PROJECT.md - Who It's For section]
+
+Core problem:
+[From PROJECT.md - Core Problem section]
+
+Competitive differentiators:
+[From PROJECT.md - How It's Different section]
 
 Core value this design must serve:
 [From PROJECT.md - Core Value section]
 
+Primary user flows:
+[From PROJECT.md - Key User Flows section]
+
 Technical constraints:
 [From PROJECT.md - Constraints section]
 </design_context>
@@ -329,13 +338,13 @@ User preferences:
 [If mockups were NOT generated, omit this entire block.]
 </mockup_direction>
 
-<quality_expectation>
-Commercial benchmark: This design must look like a [benchmark] with intentional decisions, not defaults.
+<quality_constraints>
+Specify exact values for every design token — colors as hex, spacing in px/dp, typography with weight+size+line-height. No "appropriate", "suitable", or "as needed". Every decision must be explicit and implementable without interpretation.
 
-Pre-emptive criticism: Assume the user will say "This looks like generic AI output." Generate something that proves them wrong.
+Differentiate from platform defaults: if a color, radius, or spacing matches the default system value, choose a deliberate alternative that serves the product's identity.
 
-Accountability check: Could you show this design to a professional UI designer and claim it as skilled work? If not, it's not done.
-</quality_expectation>
+Assume the user will say "This looks like generic AI output." Generate something that proves them wrong. Could you show this design to a professional UI designer and claim it as skilled work? If not, it's not done.
+</quality_constraints>
 
 <output_specification>
 Generate: DESIGN.md following template structure
@@ -404,7 +413,7 @@ After initial generation, if user wants to refine:
 
 **For major redesigns (multiple aspects changing):**
 
-Use the iteration template from `~/.claude/mindsystem/templates/design-iteration.md`:
+Read `~/.claude/mindsystem/templates/design-iteration.md` and use the iteration template:
 
 1. Capture feedback using the structured format:
    - What worked well (KEEP)
@@ -441,4 +450,5 @@ Update `.planning/STATE.md` Last Command field:
 - [ ] 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
+- [ ] STATE.md Last Command updated with timestamp
 </success_criteria>

package/commands/ms/insert-phase.md

@@ -133,13 +133,36 @@ Confirm: "Created directory: $phase_dir"
 Insert the new phase entry into the roadmap:
 
 1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
-2. Insert new phase heading with (INSERTED) marker:
+
+2. Before writing the phase entry, analyze the description to determine pre-work flags:
+
+   **Discuss**: Likely when description mentions user-facing features, UX decisions,
+   experiential qualities, or novel features. Unlikely for backend/infra, bug fixes,
+   technical debt, or clear-cut work.
+
+   **Design**: Likely when description involves UI work, visual elements, forms,
+   dashboards, or multi-screen flows. Unlikely for backend-only, API, infrastructure,
+   or established UI patterns.
+
+   **Research**: Likely when description mentions external APIs/services, new
+   libraries/frameworks, or unclear technical approach. Unlikely for established
+   internal patterns or well-documented conventions.
+
+   Use binary Likely/Unlikely with parenthetical reason. Include topics/focus only when Likely.
+
+3. Insert new phase heading with (INSERTED) marker and pre-work flags:
 
    ```
    ### Phase {decimal_phase}: {Description} (INSERTED)
 
    **Goal:** [Urgent work - to be planned]
    **Depends on:** Phase {after_phase}
+   **Discuss**: {Likely (reason) | Unlikely (reason)}
+   **Discuss topics**: {topics} ← only if Likely
+   **Design**: {Likely (reason) | Unlikely (reason)}
+   **Design focus**: {focus} ← only if Likely
+   **Research**: {Likely (reason) | Unlikely (reason)}
+   **Research topics**: {topics} ← only if Likely
    **Plans:** 0 plans
 
    Plans:
@@ -149,7 +172,7 @@ Insert the new phase entry into the roadmap:
    [To be added during planning]
    ```
 
-3. Write updated roadmap back to file
+4. Write updated roadmap back to file
 
 The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
 
@@ -183,24 +206,13 @@ Phase {decimal_phase} inserted after Phase {after_phase}:
 Roadmap updated: {roadmap-path}
 Project state updated: .planning/STATE.md
 
----
-
-## ▶ Next Up
-
-**Phase {decimal_phase}: {description}** — urgent insertion
-
-`/ms:plan-phase {decimal_phase}`
-
-<sub>`/clear` first → fresh context window</sub>
+```
 
----
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions
+to present "Next Up" with pre-work context for Phase {decimal_phase}.
 
-**Also available:**
+After the "Next Up" section, add:
 - Review insertion impact: Check if Phase {next_integer} dependencies still make sense
-- Review roadmap
-
----
-```
 </step>
 
 <step name="update_last_command">

package/commands/ms/new-milestone.md

@@ -88,7 +88,7 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
    - 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
+   - Strategic features inferred from PROJECT.md: Who It's For, Core Problem, How It's Different
    - Pending todos from STATE.md
 
    If no meaningful artifacts exist (first milestone after v1.0), base suggestions purely on PROJECT.md.
@@ -199,8 +199,8 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
     - [Feature 3]
     ```
 
-    Update Active requirements section with new goals.
     Update "Last updated" footer.
+    Note: Milestone-specific goals live in MILESTONE-CONTEXT.md (step 15), not in PROJECT.md.
 
 15. **Write MILESTONE-CONTEXT.md:**
 
@@ -285,7 +285,6 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 <success_criteria>
 - PROJECT.md updated with Current Milestone section
-- Active requirements reflect new milestone goals
 - MILESTONE-CONTEXT.md created with vision, features, scope, priorities
 - STATE.md reset for new milestone
 - Git commit made

package/commands/ms/new-project.md

@@ -94,31 +94,32 @@ Exit command.
 
 Ask inline (freeform, NOT AskUserQuestion):
 
-"What do you want to build?"
+- **Greenfield** (no existing code): "What do you want to build?"
+- **Brownfield** (code detected in Step 1): "Tell me about this project — if you were explaining it to someone who's never seen it, what does it do and who uses it?"
+
+For brownfield, explicitly note: "Not the next feature — the product as a whole."
 
 Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
 
+**Derive business context:**
+
+After the initial response, infer business context before asking more questions. Present inferred audience/problem/differentiation for the user to react to:
+
+"It sounds like this is for [audience] dealing with [problem], and your approach is different because [differentiation]. Sound right?"
+
+This leverages what they've already said and gives them something concrete to react to.
+
 **Follow the thread:**
 
 Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
 
-Keep following threads. Each answer opens new threads to explore. Ask about:
-- What excited them
-- What problem sparked this
-- What they mean by vague terms
-- What it would actually look like
-- What's already decided
+Track coverage against the 6-item context checklist from `questioning.md`. Probe fuzziest areas first — spend questioning budget where clarity is lowest.
 
-Consult `questioning.md` for techniques:
-- Challenge vagueness
-- Make abstract concrete
-- Surface assumptions
-- Find edges
-- Reveal motivation
+Use grounding questions from `questioning.md` instead of template-shaped questions. Don't ask "Who is your target audience?" — ask "Who would be your first 10 users?"
 
-**Check context (background, not out loud):**
+When the conversation pauses and sections are still fuzzy, use success-backward: "Imagine this is wildly successful in a year. What does that look like?"
 
-As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
+Consult `questioning.md` for techniques — challenge vagueness, derive before asking, use grounding questions over template-shaped questions.
 
 **Decision gate:**
 
@@ -142,54 +143,31 @@ Synthesize all context into `.planning/PROJECT.md` using the template from `temp
 
 **For greenfield projects:**
 
-Initialize requirements as hypotheses:
-
-```markdown
-## Requirements
-
-### Validated
-
-(None yet — ship to validate)
-
-### Active
-
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
-
-### Out of Scope
-
-- [Exclusion 1] — [why]
-- [Exclusion 2] — [why]
-```
-
-All Active requirements are hypotheses until shipped and validated.
+Initialize all sections from questioning:
+- **What This Is** — product identity from questioning
+- **Core Value** — the ONE thing from questioning
+- **Who It's For** — target audience from questioning
+- **Core Problem** — pain or desire from questioning
+- **How It's Different** — differentiators from questioning
+- **Key User Flows** — core interactions from questioning
+- **Out of Scope** — boundaries from questioning
+- **Constraints** — hard limits from questioning
+- **Technical Context** — minimal for greenfield (stack choices if discussed)
+- **Validated** — `(None yet — ship to validate)`
+- **Key Decisions** — any decisions made during questioning
 
 **For brownfield projects (codebase map exists):**
 
-Infer Validated requirements from existing code:
+Same as greenfield, plus:
 
 1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
-2. Identify what the codebase already does
-3. These become the initial Validated set
+2. Infer Validated requirements from existing code — what the codebase already does
+3. Populate Technical Context from codebase map (stack, integrations, known debt)
 
 ```markdown
-## Requirements
-
-### Validated
-
+## Validated
 - ✓ [Existing capability 1] — existing
 - ✓ [Existing capability 2] — existing
-- ✓ [Existing capability 3] — existing
-
-### Active
-
-- [ ] [New requirement 1]
-- [ ] [New requirement 2]
-
-### Out of Scope
-
-- [Exclusion 1] — [why]
 ```
 
 **Key Decisions:**
@@ -239,7 +217,7 @@ docs: initialize [project-name]
 
 [One-liner from PROJECT.md]
 
-Creates PROJECT.md with requirements and constraints.
+Creates PROJECT.md with business context and constraints.
 EOF
 )"
 ```
@@ -261,19 +239,14 @@ Project initialized:
 
 ## ▶ Next Up
 
-Choose your path:
-
-**Option A: Research first** (recommended)
-Research ecosystem → define requirements → create roadmap. Discovers standard stacks, expected features, architecture patterns.
-
-`/ms:research-project`
+`/ms:new-milestone` — Discover what to build first, create requirements and roadmap
 
-**Option B: Define requirements and roadmap directly** (familiar domains)
-Skip research, define requirements and create roadmap from what you know.
+<sub>`/clear` first → fresh context window</sub>
 
-`/ms:create-roadmap`
+---
 
-<sub>`/clear` first → fresh context window</sub>
+**Also available:**
+- `/ms:create-roadmap` — Skip milestone discovery, define requirements and roadmap directly
 
 ---
 ```
@@ -299,9 +272,10 @@ Update `.planning/STATE.md` Last Command field (if STATE.md exists):
 
 <success_criteria>
 
-- [ ] Deep questioning completed (not rushed, threads followed)
-- [ ] PROJECT.md captures full context with evolutionary structure
-- [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
+- [ ] Deep questioning completed with business context extracted
+- [ ] PROJECT.md captures product identity (What/Value/Audience/Problem/Differentiation/Flows)
+- [ ] PROJECT.md captures boundaries (Out of Scope, Constraints, Technical Context)
+- [ ] Validated requirements initialized (empty for greenfield, inferred for brownfield)
 - [ ] Key Decisions table initialized
 - [ ] config.json has subsystems and code_review settings
 - [ ] All committed to git

package/commands/ms/plan-phase.md

@@ -12,6 +12,7 @@ allowed-tools:
   - WebFetch
   - mcp__context7__*
   - Task
+  - Skill
 ---
 
 <objective>
@@ -91,7 +92,8 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
    - Scan project history via context scanner script (prior decisions, issues, debug resolutions, adhoc learnings, cross-milestone patterns)
    - Break phase into tasks
    - Propose plan grouping (plan boundaries, wave structure, budget estimates) for user review
-   - Hand off tasks + proposed grouping to plan-writer subagent
+   - Discover relevant project skills, confirm with user
+   - Hand off tasks + proposed grouping + confirmed skills to plan-writer subagent
    - Create PLAN.md file(s) with executable structure
 
 **Gap closure mode (--gaps flag):**

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` | Inline metadata (replaces YAML frontmatter) | Yes (type defaults to `execute`) |
+| `**Subsystem:** X \| **Type:** Y \| **Skills:** Z` | Inline metadata (replaces YAML frontmatter) | Yes (type defaults to `execute`, skills optional) |
 | `## 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,6 +130,15 @@ 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
@@ -190,6 +199,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. |
 
 ---
 

package/mindsystem/references/questioning.md

@@ -16,9 +16,10 @@ Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
 
 By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
 
-- **research-project** needs: what domain to research, what the user already knows, what unknowns exist
-- **create-roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
-- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **research-project** needs: product domain, target audience, core problem, what unknowns exist
+- **create-roadmap** needs: clear vision with business context grounding — who it's for, what problem it solves, how it's different — to decompose into phases
+- **plan-phase** needs: audience context for task weighting, specific requirements for implementation choices
+- **discuss-phase** needs: business context for PO-style analysis — audience, problem, differentiation inform scope recommendations
 - **execute-phase** needs: success criteria to verify against, the "why" behind requirements
 
 A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
@@ -37,13 +38,17 @@ A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
 
 **Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
 
+**Brownfield reframing.** For brownfield projects, reframe to product-level before feature-level. "Tell me about this project" not "What do you want to build?" Users with existing codebases default to describing the next feature — redirect to the product as a whole first.
+
+**Derive before asking.** Infer business context from feature descriptions before asking directly. "You described X, Y, Z — it sounds like this is for [audience] dealing with [problem]. Sound right?" This leverages what they've already said and gives them something concrete to react to.
+
 **Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
 
 </how_to_question>
 
 <highest_leverage>
 
-These three questions unlock the most downstream value. Everything else is nice-to-have context.
+These four questions unlock the most downstream value. Everything else is nice-to-have context.
 
 1. **"What does done look like?"** — Without observable outcomes, every downstream phase guesses scope. Roadmap can't decompose, plans can't verify, execution can't stop.
 
@@ -51,7 +56,9 @@ These three questions unlock the most downstream value. Everything else is nice-
 
 3. **"What already exists / what can't change?"** — Constraints and existing code prevent planning in a vacuum. Surfaces brownfield reality, API limitations, time pressure.
 
-If you only get three answers, get these three.
+4. **"How will you know this is a success?"** — Reveals what actually matters: commercial viability, reliability, user experience, personal satisfaction. Informs Core Value and the weighting of all sections.
+
+If you only get four answers, get these four.
 
 </highest_leverage>
 
@@ -109,16 +116,49 @@ User mentions "frustrated with current tools"
 
 </using_askuserquestion>
 
+<clarity_adaptive>
+
+Clarity is non-uniform across dimensions. Track per-section, not globally. Spend questioning budget where clarity is lowest.
+
+**High clarity signals:** Specific demographics, named competitors, concrete scenarios, quantifiable outcomes, clear success metrics.
+→ Confirm and move on. Probe one level deeper to test robustness at most.
+
+**Low clarity signals:** Broad categories ("developers", "small businesses"), vague benefits ("makes things easier"), no competitor awareness ("nothing else does this"), feature-focused language, hedging ("I think", "maybe").
+→ Offer frameworks. Provide concrete options via AskUserQuestion with derived options. Use scenarios to ground.
+
+If audience is crystal-clear but differentiation is fuzzy, probe differentiation — don't revisit audience.
+
+</clarity_adaptive>
+
+<grounding_questions>
+
+Grounding questions produce better answers than template-shaped questions. Use these instead of asking directly for template sections.
+
+| Section | Don't Ask | Ask Instead |
+|---------|-----------|-------------|
+| Who It's For | "Who is your target audience?" | "Who would be your first 10 users — real people you'd tell tomorrow?" |
+| Core Problem | "What problem does this solve?" | "What triggered you to want to build this? What's broken today?" |
+| How It's Different | "What's your USP?" | "What are people using today instead? What's wrong with it?" |
+| Core Value | "What's most important?" | "If only ONE thing worked perfectly and everything else was mediocre, what would that one thing be?" |
+| Key User Flows | "What are the key flows?" | "Walk me through a session. You open the app — then what?" |
+| Success | "How do you define success?" | "Imagine this is wildly successful in a year. What does that look like?" |
+
+People articulate by reacting, not generating.
+
+</grounding_questions>
+
 <context_checklist>
 
 Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
 
 - [ ] What they're building (concrete enough to explain to a stranger)
 - [ ] Why it needs to exist (the problem or desire driving it)
-- [ ] Who it's for (even if just themselves)
-- [ ] What "done" looks like (observable outcomes)
+- [ ] Who it's for (specific enough to find 10 of these people)
+- [ ] What makes it different (from alternatives, even manual ones)
+- [ ] What users actually do (2-3 core interactions)
+- [ ] What success looks like (how they'll know it worked)
 
-Four things. If they volunteer more, capture it.
+Six things. If they volunteer more, capture it.
 
 </context_checklist>
 
@@ -148,6 +188,8 @@ Loop until "Create PROJECT.md" selected.
 - **Shallow acceptance** — Taking vague answers without probing
 - **Premature constraints** — Asking about tech stack before understanding the idea
 - **User skills** — NEVER ask about user's technical experience. Claude builds.
+- **Accepting "everyone" as audience** — Always narrow: "Who needs this MOST?" Broad audiences are a sign of fuzzy thinking, not universal appeal.
+- **Skipping differentiation** — "Nothing else does this" is almost always wrong. Probe alternatives including manual workarounds, spreadsheets, competitor products.
 
 </anti_patterns>
 

package/mindsystem/templates/project.md

@@ -8,60 +8,50 @@ Template for `.planning/PROJECT.md` — the living project context document.
 # [Project Name]
 
 ## What This Is
-
-[Current accurate description — 2-3 sentences. What does this product do and who is it for?
-Use the user's language and framing. Update whenever reality drifts from this description.]
+[2-3 sentences. Product identity in plain language.]
 
 ## Core Value
+[Single sentence: the ONE thing that cannot fail.]
 
-[The ONE thing that matters most. If everything else fails, this must work.
-One sentence that drives prioritization when tradeoffs arise.]
-
-## Requirements
-
-### Validated
-
-<!-- Shipped and confirmed valuable. -->
-
-(None yet — ship to validate)
-
-### Active
-
-<!-- Current scope. Building toward these. -->
+## Who It's For
+[Target audience — who they are, their context, how they work today. 2-4 sentences.]
 
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
+## Core Problem
+[Why this exists — what pain or desire drives it. 1-2 sentences.]
 
-### Out of Scope
+## How It's Different
+[What makes this not another [category]. Include competitive context if relevant.]
+- [Differentiator 1]
+- [Differentiator 2]
+- [Differentiator 3]
 
-<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
+## Key User Flows
+[The 2-3 core interactions users perform.]
+- [Flow 1]
+- [Flow 2]
+- [Flow 3]
 
+## Out of Scope
 - [Exclusion 1] — [why]
 - [Exclusion 2] — [why]
 
-## Context
-
-[Background information that informs implementation:
-- Technical environment or ecosystem
-- Relevant prior work or experience
-- User research or feedback themes
-- Known issues to address]
-
 ## Constraints
-
 - **[Type]**: [What] — [Why]
 - **[Type]**: [What] — [Why]
 
 Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
 
-## Key Decisions
+## Technical Context
+[Tech stack, integrations, prior work, known issues/debt.]
 
-<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+## Validated
+(None yet — ship to validate)
+
+## Key Decisions
 
 | Decision | Rationale | Outcome |
 |----------|-----------|---------|
-| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
+| [Choice] | [Why] | — Pending |
 
 ---
 *Last updated: [date] after [trigger]*
@@ -83,32 +73,51 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 - Drives prioritization when tradeoffs arise
 - Rarely changes; if it does, it's a significant pivot
 
-**Requirements — Validated:**
-- Requirements that shipped and proved valuable
-- Format: `- ✓ [Requirement] — [version/phase]`
-- These are locked — changing them requires explicit discussion
-
-**Requirements — Active:**
-- Current scope being built toward
-- These are hypotheses until shipped and validated
-- Move to Validated when shipped, Out of Scope if invalidated
-
-**Requirements — Out of Scope:**
+**Who It's For:**
+- Specific enough to find 10 of these people
+- Include their context: what they do today, what tools they use, what frustrates them
+- Avoid broad categories ("developers", "small businesses") — narrow to who needs this MOST
+- Update as real user data replaces assumptions
+
+**Core Problem:**
+- The pain or desire that makes this product necessary
+- Should explain why existing alternatives don't suffice
+- One sentence is better than two — forces precision
+- If you can't articulate the problem, the product isn't ready to build
+
+**How It's Different:**
+- 2-3 concrete differentiators, not marketing language
+- Include what people use today instead (even manual workarounds)
+- "Nothing else does this" is almost always wrong — probe alternatives
+- Competitive context folds in here — no standalone section needed
+
+**Key User Flows:**
+- The 2-3 core interactions that make the product valuable
+- One line each — verb-driven ("Log workout → view history → track progress")
+- Bridges abstract identity and concrete architecture
+- Update as flows are validated or new ones emerge
+
+**Out of Scope:**
 - Explicit boundaries on what we're not building
 - Always include reasoning (prevents re-adding later)
 - Includes: considered and rejected, deferred to future, explicitly excluded
 
-**Context:**
-- Background that informs implementation decisions
-- Technical environment, prior work, user feedback
-- Known issues or technical debt to address
-- Update as new context emerges
-
 **Constraints:**
 - Hard limits on implementation choices
 - Tech stack, timeline, budget, compatibility, dependencies
 - Include the "why" — constraints without rationale get questioned
 
+**Technical Context:**
+- Background that informs implementation decisions
+- Tech stack, integrations, prior work, known issues/debt
+- Update as new technical context emerges
+- Purely technical — business context lives in Layer 1 sections
+
+**Validated:**
+- Requirements that shipped and proved valuable
+- Format: `- ✓ [Requirement] — [version/phase]`
+- These are locked — changing them requires explicit discussion
+
 **Key Decisions:**
 - Significant choices that affect future work
 - Add decisions as they're made throughout the project
@@ -131,15 +140,17 @@ PROJECT.md evolves throughout the project lifecycle.
 **After each phase transition:**
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
-3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
-5. "What This Is" still accurate? → Update if drifted
+3. Decisions to log? → Add to Key Decisions
+4. "What This Is" still accurate? → Update if drifted
+5. Has understanding of audience, problem, or differentiation evolved? → Update Who It's For, Core Problem, or How It's Different
+6. New key flows emerged? → Update Key User Flows
 
 **After each milestone:**
-1. Full review of all sections
+1. Full review of all sections including business context (Who It's For, Core Problem, How It's Different)
 2. Core Value check — still the right priority?
 3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state (users, feedback, metrics)
+4. Update Technical Context with current state (users, feedback, metrics)
+5. Key User Flows — validated against what users actually do?
 
 </evolution>
 
@@ -154,15 +165,10 @@ For existing codebases:
    - What patterns are established?
    - What's clearly working and relied upon?
 
-3. **Gather Active requirements** from user:
-   - Present inferred current state
-   - Ask what they want to build next
-
-4. **Initialize:**
+3. **Initialize:**
    - Validated = inferred from existing code
-   - Active = user's goals for this work
    - Out of Scope = boundaries user specifies
-   - Context = includes current codebase state
+   - Technical Context = populated from codebase map
 
 </brownfield>
 

package/mindsystem/workflows/complete-milestone.md

@@ -184,30 +184,31 @@ cat .planning/phases/*-*/*-SUMMARY.md
 3. **Requirements audit:**
 
    **Validated section:**
-   - All Active requirements shipped in this milestone → Move to Validated
+   - All requirements shipped in this milestone → Add to Validated
    - Format: `- ✓ [Requirement] — v[X.Y]`
 
-   **Active section:**
-   - Remove requirements that moved to Validated
-   - Add any new requirements for next milestone
-   - Keep requirements that weren't addressed yet
-
    **Out of Scope audit:**
    - Review each item — is the reasoning still valid?
    - Remove items that are no longer relevant
    - Add any requirements invalidated during this milestone
 
-4. **Context update:**
+4. **Business context review:**
+   - Who It's For — has understanding of audience evolved?
+   - Core Problem — still the right framing?
+   - How It's Different — new competitors or differentiators?
+   - Key User Flows — validated against what users actually do?
+
+5. **Technical Context update:**
    - Current codebase state (LOC, tech stack)
    - User feedback themes (if any)
    - Known issues or technical debt to address
 
-5. **Key Decisions audit:**
+6. **Key Decisions audit:**
    - Extract all decisions from milestone phase summaries
    - Add to Key Decisions table with outcomes where known
    - Mark ✓ Good, ⚠️ Revisit, or — Pending for each
 
-6. **Constraints check:**
+7. **Constraints check:**
    - Any constraints that changed during development?
    - Update as needed
 
@@ -233,20 +234,16 @@ A real-time collaborative whiteboard for remote teams.
 
 Real-time sync that feels instant.
 
-## Requirements
+## Who It's For
 
-### Validated
-
-(None yet — ship to validate)
+Remote teams who need to brainstorm visually during meetings.
+Currently using Miro or physical whiteboards.
 
-### Active
+## Validated
 
-- [ ] Canvas drawing tools
-- [ ] Real-time sync < 500ms
-- [ ] User authentication
-- [ ] Export to PNG
+(None yet — ship to validate)
 
-### Out of Scope
+## Out of Scope
 
 - Mobile app — web-first approach
 - Video chat — use external tools
@@ -263,27 +260,24 @@ A real-time collaborative whiteboard for remote teams with instant sync and draw
 
 Real-time sync that feels instant.
 
-## Requirements
+## Who It's For
+
+Remote teams (2-8 people) who brainstorm visually during meetings.
+Currently using Miro but frustrated by complexity and latency.
 
-### Validated
+## Validated
 
 - ✓ Canvas drawing tools — v1.0
 - ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
 - ✓ User authentication — v1.0
 
-### Active
-
-- [ ] Export to PNG
-- [ ] Undo/redo history
-- [ ] Shape tools (rectangles, circles)
-
-### Out of Scope
+## Out of Scope
 
 - Mobile app — web-first approach, PWA works well
 - Video chat — use external tools
 - Offline mode — real-time is core value
 
-## Context
+## Technical Context
 
 Shipped v1.0 with 2,400 LOC TypeScript.
 Tech stack: Next.js, Supabase, Canvas API.
@@ -294,10 +288,10 @@ Initial user testing showed demand for shape tools.
 
 - [ ] "What This Is" reviewed and updated if needed
 - [ ] Core Value verified as still correct
-- [ ] All shipped requirements moved to Validated
-- [ ] New requirements added to Active for next milestone
+- [ ] All shipped requirements added to Validated
+- [ ] Business context reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
 - [ ] Out of Scope reasoning audited
-- [ ] Context updated with current state
+- [ ] Technical Context updated with current state
 - [ ] All milestone decisions added to Key Decisions
 - [ ] "Last updated" footer reflects milestone completion
 
@@ -626,7 +620,7 @@ Tag: v[X.Y]
 
 Milestone completion is successful when (ordered by skip risk):
 
-- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, Requirements, Key Decisions, Context)
+- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, business context, Validated, Key Decisions, Technical Context)
 - [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
 - [ ] MILESTONES.md entry created with stats and accomplishments

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">

package/mindsystem/workflows/plan-phase.md

@@ -389,7 +389,9 @@ Standard tasks (remain in standard plans):
 → Yes: Mark as tdd_candidate=true
 → No: Standard task
 
-Read `~/.claude/mindsystem/references/tdd.md` now for TDD criteria and plan structure.
+**If any tasks were marked tdd_candidate=true:** Read `~/.claude/mindsystem/references/tdd.md` for TDD plan structure guidance.
+
+**If no TDD candidates:** Skip — the heuristic above is sufficient for detection.
 
 **Decisions:** If you identify a task that requires choosing between approaches (which auth provider, which database, etc.), use AskUserQuestion to resolve it now. Don't defer decisions to execution. For purely technical choices where the user hasn't expressed preference, make the decision and document it in the plan's objective.
 
@@ -450,6 +452,25 @@ The user may adjust, merge, or split plans. Once confirmed (or if the user proce
 **TDD plans are always standalone** — propose them as dedicated plans regardless of budget.
 </step>
 
+<step name="discover_skills">
+**Identify relevant project skills for this phase.**
+
+After the user confirms the plan structure, check if project skills could improve plan quality.
+
+**Scan:** Review the skill list in your system-reminder. Match skills against:
+- The phase's technology stack (Flutter, React, Node.js, etc.)
+- The domain of the tasks identified (UI patterns, API design, state management, etc.)
+- Keywords from RESEARCH.md or CONTEXT.md if they exist
+
+**If matches found:** Present via AskUserQuestion:
+- List each matching skill with its description
+- Always include an escape hatch option for the user to name skills manually or skip entirely
+
+**If no matches:** Skip silently — no need to ask the user.
+
+**Store result:** Keep the confirmed skill names (may be empty) for the handoff step.
+</step>
+
 <step name="handoff_to_writer">
 **Spawn ms-plan-writer subagent with task list and context.**
 
@@ -500,6 +521,10 @@ Assemble handoff payload:
   {list of services detected in task breakdown}
 </external_services>
 
+<confirmed_skills>
+  {comma-separated skill names confirmed by user, or "none"}
+</confirmed_skills>
+
 <learnings>
   <!-- Flat list from read_project_history step 6. Omit if no matches found. -->
   <learning type="debug" source=".planning/debug/resolved/{slug}.md">{root_cause} — fix: {resolution}</learning>
@@ -699,7 +724,7 @@ Tasks are instructions for Claude, not Jira tickets.
 - [ ] Prior decisions, issues, concerns synthesized
 - [ ] Tasks identified with needs/creates dependencies
 - [ ] Plan grouping proposed and presented to user
-- [ ] Task list + proposed grouping handed off to ms-plan-writer
+- [ ] Task list + proposed grouping + confirmed skills handed off to ms-plan-writer
 - [ ] PLAN files + EXECUTION-ORDER.md created (pure markdown, Must-Haves, follows proposed grouping)
 - [ ] Plans committed with maximized wave parallelism
 - [ ] Risk assessment presented (score + top factors)

package/mindsystem/workflows/transition.md

@@ -141,16 +141,17 @@ cat .planning/phases/XX-current/*-SUMMARY.md
 **Assess requirement changes:**
 
 1. **Requirements validated?**
-   - Any Active requirements shipped in this phase?
-   - Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
+   - Any requirements shipped in this phase?
+   - Add to Validated with phase reference: `- ✓ [Requirement] — Phase X`
 
 2. **Requirements invalidated?**
-   - Any Active requirements discovered to be unnecessary or wrong?
-   - Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
+   - Any requirements discovered to be unnecessary or wrong?
+   - Add to Out of Scope with reason: `- [Requirement] — [why invalidated]`
 
-3. **Requirements emerged?**
-   - Any new requirements discovered during building?
-   - Add to Active: `- [ ] [New requirement]`
+3. **Business context evolved?**
+   - Has understanding of audience, problem, or differentiation changed?
+   - Update Who It's For, Core Problem, or How It's Different if so
+   - New key flows emerged? → Update Key User Flows
 
 4. **Decisions to log?**
    - Extract decisions from SUMMARY.md files
@@ -174,13 +175,11 @@ Make the edits inline. Update "Last updated" footer:
 Before:
 
 ```markdown
-### Active
+## Validated
 
-- [ ] JWT authentication
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
+- ✓ Canvas drawing tools — Phase 1
 
-### Out of Scope
+## Out of Scope
 
 - OAuth2 — complexity not needed for v1
 ```
@@ -188,27 +187,23 @@ Before:
 After (Phase 2 shipped JWT auth, discovered rate limiting needed):
 
 ```markdown
-### Validated
+## Validated
 
+- ✓ Canvas drawing tools — Phase 1
 - ✓ JWT authentication — Phase 2
 
-### Active
-
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
-- [ ] Rate limiting on sync endpoint
-
-### Out of Scope
+## Out of Scope
 
 - OAuth2 — complexity not needed for v1
+- Offline mode — real-time is core value, discovered Phase 2
 ```
 
 **Step complete when:**
 
 - [ ] Phase summaries reviewed for learnings
-- [ ] Validated requirements moved from Active
-- [ ] Invalidated requirements moved to Out of Scope with reason
-- [ ] Emerged requirements added to Active
+- [ ] Shipped requirements added to Validated
+- [ ] Invalidated requirements added to Out of Scope with reason
+- [ ] Business context sections reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
 - [ ] New decisions logged with rationale
 - [ ] "What This Is" updated if product changed
 - [ ] "Last updated" footer reflects this transition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/scripts/doctor-scan.sh

@@ -53,6 +53,39 @@ record_result() {
   esac
 }
 
+# --- Helper: parse phase numbers from a "Phases completed" line ---
+# Outputs one phase number per line. Handles:
+#   - Range format: "1-6" → 1 2 3 4 5 6
+#   - Comma-separated: "8, 8.3, 9, 10" → 8 8.3 9 10
+#   - Mixed (multiple milestone entries each handled independently)
+parse_phase_numbers() {
+  local line="$1"
+  local range
+  range=$(echo "$line" | grep -o '[0-9]\+-[0-9]\+' || true)
+  if [ -n "$range" ]; then
+    local range_start range_end
+    range_start=$(echo "$range" | cut -d'-' -f1)
+    range_end=$(echo "$range" | cut -d'-' -f2)
+    seq "$range_start" "$range_end"
+  else
+    echo "$line" | sed 's/.*://' | grep -oE '[0-9]+(\.[0-9]+)?' || true
+  fi
+}
+
+# --- Helper: format phase number as zero-padded directory prefix ---
+# Integer (9) → "09", Decimal (8.3) → "08.3"
+format_phase_prefix() {
+  local phase="$1"
+  if echo "$phase" | grep -q '\.'; then
+    local int_part dec_part
+    int_part=$(echo "$phase" | cut -d'.' -f1)
+    dec_part=$(echo "$phase" | cut -d'.' -f2)
+    printf "%02d.%s" "$int_part" "$dec_part"
+  else
+    printf "%02d" "$phase"
+  fi
+}
+
 # ============================================================
 # CHECK 1: Subsystem Vocabulary
 # ============================================================
@@ -176,24 +209,18 @@ else
   ORPHAN_COUNT=0
   ORPHAN_LIST=""
 
-  # Parse each milestone's phase range from MILESTONES.md
+  # Parse each milestone's completed phases from MILESTONES.md
   while IFS= read -r line; do
-    # Extract range like "1-6" or "7-8"
-    range=$(echo "$line" | grep -o '[0-9]\+-[0-9]\+')
-    [ -z "$range" ] && continue
-    range_start=$(echo "$range" | cut -d'-' -f1)
-    range_end=$(echo "$range" | cut -d'-' -f2)
-
-    # Check if any phase directories in this range still exist in phases/
-    for i in $(seq "$range_start" "$range_end"); do
-      phase_prefix=$(printf "%02d" "$i")
-      for dir in "$PHASES_DIR"/${phase_prefix}-*/; do
+    while IFS= read -r phase_num; do
+      [ -z "$phase_num" ] && continue
+      prefix=$(format_phase_prefix "$phase_num")
+      for dir in "$PHASES_DIR"/${prefix}-*/; do
         [ -d "$dir" ] || continue
         dirname=$(basename "$dir")
         ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
         ORPHAN_LIST="$ORPHAN_LIST  $dirname (should be archived)"$'\n'
       done
-    done
+    done < <(parse_phase_numbers "$line")
   done < <(grep "Phases completed" "$MILESTONES_FILE")
 
   if [ "$ORPHAN_COUNT" -gt 0 ]; then
@@ -325,19 +352,15 @@ else
 
   # Check phases/ for PLANs belonging to completed milestones
   while IFS= read -r line; do
-    range=$(echo "$line" | grep -o '[0-9]\+-[0-9]\+')
-    [ -z "$range" ] && continue
-    range_start=$(echo "$range" | cut -d'-' -f1)
-    range_end=$(echo "$range" | cut -d'-' -f2)
-
-    for i in $(seq "$range_start" "$range_end"); do
-      phase_prefix=$(printf "%02d" "$i")
-      for plan in "$PHASES_DIR"/${phase_prefix}-*/*-PLAN.md; do
+    while IFS= read -r phase_num; do
+      [ -z "$phase_num" ] && continue
+      prefix=$(format_phase_prefix "$phase_num")
+      for plan in "$PHASES_DIR"/${prefix}-*/*-PLAN.md; do
         [ -f "$plan" ] || continue
         LEFTOVER_COUNT=$((LEFTOVER_COUNT + 1))
         LEFTOVER_PLANS="$LEFTOVER_PLANS  $(echo "$plan" | sed "s|$GIT_ROOT/.planning/||")"$'\n'
       done
-    done
+    done < <(parse_phase_numbers "$line")
   done < <(grep "Phases completed" "$MILESTONES_FILE")
 
   # Check archived milestone phase directories for leftover PLANs