mindsystem-cc 3.19.0 → 3.21.0

package/commands/ms/research-project.md

@@ -65,8 +65,8 @@ mkdir -p .planning/research
 ```
 
 **Determine milestone context:**
-- If no "Validated" requirements in REQUIREMENTS.md → Greenfield (v1.0)
-- If "Validated" requirements exist → Subsequent milestone (v1.1+)
+- If no "Validated" requirements in REQUIREMENTS.md → Greenfield
+- If "Validated" requirements exist → Subsequent milestone
 
 Spawn all 4 in parallel with rich context:
 
@@ -79,10 +79,10 @@ Project Research — Stack dimension for [domain].
 <milestone_context>
 {greenfield OR subsequent}
 
-**Greenfield (v1.0):**
+**Greenfield (first milestone):**
 Research the standard stack for building [domain] from scratch. Full ecosystem investigation.
 
-**Subsequent (v1.1+):**
+**Subsequent (later milestones):**
 Research what's needed to add [target features] to an existing [domain] app.
 
 IMPORTANT for subsequent milestones:
@@ -128,10 +128,10 @@ Project Research — Features dimension for [domain].
 <milestone_context>
 {greenfield OR subsequent}
 
-**Greenfield (v1.0):**
+**Greenfield (first milestone):**
 What features do [domain] products have? What's table stakes vs differentiating?
 
-**Subsequent (v1.1+):**
+**Subsequent (later milestones):**
 How do [target features] typically work? What's expected behavior?
 
 IMPORTANT for subsequent milestones:
@@ -176,10 +176,10 @@ Project Research — Architecture dimension for [domain].
 <milestone_context>
 {greenfield OR subsequent}
 
-**Greenfield (v1.0):**
+**Greenfield (first milestone):**
 How are [domain] systems typically structured? What are major components?
 
-**Subsequent (v1.1+):**
+**Subsequent (later milestones):**
 How do [target features] integrate with existing [domain] architecture?
 
 IMPORTANT for subsequent milestones:
@@ -224,10 +224,10 @@ Project Research — Pitfalls dimension for [domain].
 <milestone_context>
 {greenfield OR subsequent}
 
-**Greenfield (v1.0):**
+**Greenfield (first milestone):**
 What do [domain] projects commonly get wrong? Critical mistakes?
 
-**Subsequent (v1.1+):**
+**Subsequent (later milestones):**
 What are common mistakes when adding [target features] to [domain]?
 
 IMPORTANT for subsequent milestones:
@@ -303,8 +303,8 @@ After creating SUMMARY.md, update config.json code_review fields with agent name
 1. Read recommended stack from STACK.md
 2. Map 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:
      - adhoc: \"ms-code-simplifier\"

package/mindsystem/references/continuation-format.md

@@ -59,7 +59,7 @@ When there's meaningful additional context (like a phase identifier), add it as
 
 **Also available:**
 - Review plans before executing
-- `/ms:list-phase-assumptions 2` — check assumptions
+- `/ms:discuss-phase 2` — gather context and validate assumptions
 
 ---
 ```
@@ -84,7 +84,7 @@ Add note that this is the last phase and what comes after:
 
 **After this completes:**
 - Milestone complete
-- Next: `/ms:complete-milestone` — archive and tag
+- Next: `/ms:complete-milestone` — archive milestone
 
 ---
 ```
@@ -168,7 +168,7 @@ When there's no clear primary action:
 ```
 ---
 
-## 🎉 Milestone v1.0 Complete
+## 🎉 Milestone Complete
 
 All 4 phases shipped
 

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/principles.md

@@ -54,7 +54,7 @@ No enterprise process. No approval gates.
 
 Plan → Execute → Ship → Learn → Repeat
 
-Milestones mark shipped versions (v1.0 → v1.1 → v2.0).
+Milestones mark shipped work (MVP → Push Notifications → ...).
 </ship_fast>
 
 <anti_enterprise>

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/references/routing/audit-result-routing.md

@@ -9,7 +9,8 @@ Route user to appropriate next action based on audit status (passed, gaps_found,
 ## Variables
 
 From calling context:
-- `{version}` — milestone version
+- `{name}` — milestone name
+- `{slug}` — milestone slug (for file paths)
 - `{N}/{M}` — requirements score
 - `{status}` — audit result: passed | gaps_found | tech_debt
 - `{assumptions_count}` — number of untested assumptions (from UAT)
@@ -21,10 +22,10 @@ Read the audit status and present the matching section below.
 ## If Passed
 
 ```markdown
-## ✓ Milestone {version} — Audit Passed
+## ✓ Milestone {name} — Audit Passed
 
 **Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+**Report:** .planning/MILESTONE-AUDIT.md
 
 All requirements covered. Cross-phase integration verified. E2E flows complete.
 
@@ -38,7 +39,7 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 
 ## ▶ Next Up
 
-`/ms:complete-milestone {version}` — archive and tag
+`/ms:complete-milestone` — archive milestone
 
 <sub>`/clear` first → fresh context window</sub>
 ```
@@ -46,10 +47,10 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 ## If Gaps Found
 
 ```markdown
-## ⚠ Milestone {version} — Gaps Found
+## ⚠ Milestone {name} — Gaps Found
 
 **Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+**Report:** .planning/MILESTONE-AUDIT.md
 
 ### Unsatisfied Requirements
 
@@ -78,17 +79,17 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 ---
 
 **Also available:**
-- `cat .planning/v{version}-MILESTONE-AUDIT.md` — see full report
-- `/ms:complete-milestone {version}` — proceed anyway (accept tech debt)
+- `cat .planning/MILESTONE-AUDIT.md` — see full report
+- `/ms:complete-milestone` — proceed anyway (accept tech debt)
 ```
 
 ## If Tech Debt (no blockers but accumulated debt)
 
 ```markdown
-## ⚡ Milestone {version} — Tech Debt Review
+## ⚡ Milestone {name} — Tech Debt Review
 
 **Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+**Report:** .planning/MILESTONE-AUDIT.md
 
 All requirements met. No critical blockers. Accumulated tech debt needs review.
 
@@ -108,7 +109,7 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 
 ## ▶ Options
 
-- `/ms:complete-milestone {version}` — accept debt, track in backlog
+- `/ms:complete-milestone` — accept debt, track in backlog
 - `/ms:plan-milestone-gaps` — address debt before completing
 
 <sub>`/clear` first → fresh context window</sub>

package/mindsystem/references/routing/between-milestones-routing.md

@@ -15,14 +15,14 @@ cat .planning/MILESTONES.md 2>/dev/null
 ```
 
 Extract:
-- `{X.Y}` — last completed milestone version
+- `{name}` — last completed milestone name from MILESTONES.md
 
 ## Output Format
 
 ```markdown
 ---
 
-## ✓ Milestone v{X.Y} Complete
+## ✓ Milestone {name} Complete
 
 Ready to plan the next milestone.
 

package/mindsystem/references/routing/milestone-complete-routing.md

@@ -10,7 +10,7 @@ Celebrate milestone completion and guide user toward audit or archive.
 
 From calling context:
 - `{N}` — total number of phases in milestone
-- `{version}` — milestone version (if known)
+- `{name}` — milestone name (if known)
 
 ## Output Format
 

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

@@ -108,7 +108,7 @@ ELSE:
 
 ### Suggested
 
-`/ms:discuss-phase 3` — ambiguous user flow
+`/ms:discuss-phase 3` — assumes grid layout, unclear what metrics matter
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -130,17 +130,19 @@ ELSE:
 
 | Pre-work | Status | Topics/Focus |
 |----------|--------|--------------|
+| Discuss | Likely | assumes one-time payments only, unclear if subscriptions needed, refund policy unspecified |
 | Research | Likely | Stripe API, webhook handling, idempotency |
 
 ### Suggested
 
-`/ms:research-phase 4` — external API integration
+`/ms:discuss-phase 4` — assumes one-time payments, subscription model unclear
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
+- `/ms:research-phase 4` — external API integration
 - `/ms:plan-phase 4` — plan directly
 ```
 

package/mindsystem/templates/context.md

@@ -53,10 +53,10 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's
 <decisions>
 ## Decisions (Locked)
 
-[Concrete implementation decisions made during discussion. These are NOT optional — plans must implement these exactly.]
+[Concrete implementation decisions made during discussion. These are NOT optional — plans must implement these exactly. Each decision includes inline reasoning grounded in vision, audience, or tradeoff analysis.]
 
-- [Decision 1]
-- [Decision 2]
+- [Decision 1] — [Why: grounded in vision, audience, or tradeoff]
+- [Decision 2] — [Reasoning from product analysis or user preference]
 
 ### Claude's Discretion
 
@@ -128,9 +128,9 @@ Priority is clarity over features. Better to show less and make it obvious than
 <decisions>
 ## Decisions (Locked)
 
-- Card layout for projects (not a list)
-- "Today" section at top showing urgent items
-- Dark mode support (already exists from Phase 2)
+- Card layout for projects (not a list) — Why: user wants personal feel, cards feel more like a notebook than enterprise software; Linear uses cards successfully for similar "what's mine" views
+- "Today" section at top showing urgent items — Why: at-a-glance clarity is the #1 essential; surfacing urgency immediately matches user's "what should I work on today" mental model
+- Dark mode support (already exists from Phase 2) — Why: user considers this essential for the calm aesthetic
 
 ### Claude's Discretion
 
@@ -173,6 +173,7 @@ Vision sections capture the user's own words — how they imagine it, what they
 - Concrete choices (not vague preferences)
 - Checkable by downstream agents
 - Clear about what's locked vs discretionary
+- Include inline reasoning ("— Why: ...") grounded in vision, audience needs, competitor patterns, or explicit tradeoff analysis
 
 **Content should NOT read like:**
 - A technical specification

package/mindsystem/templates/milestone-archive.md

@@ -6,7 +6,7 @@ This template is used by the complete-milestone workflow to create archive files
 
 ## File Template
 
-# Milestone v{{VERSION}}: {{MILESTONE_NAME}}
+# Milestone: {{MILESTONE_NAME}}
 
 **Status:** ✅ SHIPPED {{DATE}}
 **Phases:** {{PHASE_START}}-{{PHASE_END}}
@@ -97,13 +97,13 @@ _For current project status, see .planning/PROJECT.md_
 
 <guidelines>
 **When to create milestone archives:**
-- After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
+- After completing all phases in a milestone
 - Triggered by complete-milestone workflow
 - Before planning next milestone work
 
 **How to fill template:**
 
-- Replace {{PLACEHOLDERS}} with actual values
+- Replace {{PLACEHOLDERS}} with actual values ({{MILESTONE_NAME}}, {{MILESTONE_SLUG}} for paths)
 - Extract phase details from ROADMAP.md
 - Document decimal phases with (INSERTED) marker
 - Include key decisions from PROJECT-STATE.md or SUMMARY files
@@ -112,8 +112,8 @@ _For current project status, see .planning/PROJECT.md_
 
 **Archive location:**
 
-- Save to `.planning/milestones/v{VERSION}/ROADMAP.md`
-- Example: `.planning/milestones/v1.0/ROADMAP.md`
+- Save to `.planning/milestones/{MILESTONE_SLUG}/ROADMAP.md`
+- Example: `.planning/milestones/mvp/ROADMAP.md`
 
 **After archiving:**
 

package/mindsystem/templates/milestone-context.md

@@ -5,7 +5,7 @@ Template for `.planning/MILESTONE-CONTEXT.md` — captures brainstorming context
 <template>
 
 ```markdown
-# Milestone Context: v[X.Y] [Name]
+# Milestone Context: [Name]
 
 **Generated:** [date]
 **Source:** /ms:new-milestone brainstorming session

package/mindsystem/templates/milestone.md

@@ -3,7 +3,7 @@
 Add this entry to `.planning/MILESTONES.md` when completing a milestone:
 
 ```markdown
-## v[X.Y] [Name] (Shipped: YYYY-MM-DD)
+## [Name] (Shipped: YYYY-MM-DD)
 
 **Delivered:** [One sentence describing what shipped]
 
@@ -40,9 +40,9 @@ If MILESTONES.md doesn't exist, create it with header:
 
 <guidelines>
 **When to create milestones:**
-- Initial v1.0 MVP shipped
-- Major version releases (v2.0, v3.0)
-- Significant feature milestones (v1.1, v1.2)
+- Initial MVP shipped
+- Major feature sets complete
+- Significant feature milestones
 - Before archiving planning (capture what was shipped)
 
 **Don't create milestones for:**
@@ -65,7 +65,7 @@ If MILESTONES.md doesn't exist, create it with header:
 ```markdown
 # Project Milestones: WeatherBar
 
-## v1.1 Security & Polish (Shipped: 2025-12-10)
+## Security & Polish (Shipped: 2025-12-10)
 
 **Delivered:** Security hardening with Keychain integration and comprehensive error handling
 
@@ -81,15 +81,15 @@ If MILESTONES.md doesn't exist, create it with header:
 - 23 files modified
 - 650 lines of Swift added
 - 2 phases, 3 plans, 12 tasks
-- 8 days from v1.0 to v1.1
+- 8 days
 
 **Git range:** `feat(05-01)` → `feat(06-02)`
 
-**What's next:** v2.0 SwiftUI redesign with widget support
+**What's next:** SwiftUI redesign with widget support
 
 ---
 
-## v1.0 MVP (Shipped: 2025-11-25)
+## MVP (Shipped: 2025-11-25)
 
 **Delivered:** Menu bar weather app with current conditions and 3-day forecast
 
@@ -110,6 +110,6 @@ If MILESTONES.md doesn't exist, create it with header:
 
 **Git range:** `feat(01-01)` → `feat(04-01)`
 
-**What's next:** Security audit and hardening for v1.1
+**What's next:** Security audit and hardening
 ```
 </example>