mindsystem-cc 3.10.0 → 3.11.0

package/commands/ms/new-milestone.md

@@ -1,29 +1,32 @@
 ---
 name: ms:new-milestone
-description: Start a new milestone cycle — update PROJECT.md and route to requirements
+description: Start a new milestone — discover what to build, update PROJECT.md, create context for downstream
 argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
 allowed-tools:
   - Read
   - Write
   - Bash
+  - Glob
+  - Grep
   - AskUserQuestion
 ---
 
 <objective>
-Start a new milestone by updating PROJECT.md with new goals, then routing to the requirements → roadmap cycle.
+Start a new milestone by helping the user discover what to build next, then updating PROJECT.md and creating MILESTONE-CONTEXT.md for downstream consumption.
 
-This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and updates PROJECT.md to reflect the new milestone's goals.
+Self-contained command — three phases: Orient (load context, present directions), Deepen (collaborative discovery), Commit (update files, route forward).
 
-Output: Updated PROJECT.md, routes to research-project or define-requirements
+Output: Updated PROJECT.md, new MILESTONE-CONTEXT.md, routes to create-roadmap or research-project
 </objective>
 
 <execution_context>
 @~/.claude/mindsystem/references/questioning.md
 @~/.claude/mindsystem/templates/project.md
+@~/.claude/mindsystem/templates/milestone-context.md
 </execution_context>
 
 <context>
-Milestone name: $ARGUMENTS (optional - will prompt if not provided)
+Milestone name: $ARGUMENTS (optional — will emerge during discovery if not provided)
 
 **Load project context:**
 @.planning/PROJECT.md
@@ -34,149 +37,249 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
 <process>
 
+## Phase 1: Orient
+
 1. **Load context:**
-   - Read PROJECT.md (existing project, Validated requirements, decisions)
+   - Read PROJECT.md (existing project, validated requirements, decisions)
    - Read MILESTONES.md (what shipped previously)
    - Read STATE.md (pending todos, blockers)
+   - Read config.json (project settings)
    - Calculate previous milestone version from MILESTONES.md (e.g., if last shipped was v1.0, previous=1.0)
 
-2. **Strategic assessment (internal — do not output this step):**
-   - Load PROJECT.md (vision, audience, USP, problem space)
-   - Load MILESTONES.md (what shipped)
-   - Load STATE.md (pending todos, blockers)
-   - Check for previous milestone artifacts using the version calculated in step 1:
+2. **Check for active milestone:**
+
+   If STATE.md or ROADMAP.md indicates a milestone is in progress:
+
+   Use AskUserQuestion:
+   - header: "Active milestone"
+   - question: "There's a milestone in progress (v[X.Y]). What do you want to do?"
+   - options:
+     - "Complete it first" — run /ms:complete-milestone
+     - "Add phases to it" — run /ms:add-phase
+     - "Continue anyway" — discuss next milestone scope
+
+   If "Complete it first" or "Add phases to it": present the relevant command and stop.
+   If "Continue anyway": proceed.
+
+3. **Strategic assessment (silent — do not output this step):**
+   - Check for previous milestone artifacts using calculated version:
      - `.planning/milestones/v{VERSION}-DECISIONS.md` (if exists)
      - `.planning/milestones/v{VERSION}-MILESTONE-AUDIT.md` (if exists)
      - `.planning/TECH-DEBT.md` (if exists)
-   - Identify outstanding tech debt, unaddressed requirements, high-impact gaps
-   - This is background analysis — synthesize silently, surface through suggestions in step 3
-
-3. **Present suggested directions:**
+     - `.planning/LEARNINGS.md` (if exists)
+   - Identify: outstanding tech debt, untested assumptions, high-impact gaps, unaddressed requirements
+   - This is background analysis — synthesize silently, surface through suggestions in step 4
 
-   Output a brief markdown summary:
+4. **Present brief context and suggested directions:**
 
    ```
+   ## Last Milestone
+
+   v[X.Y] [Name] — [key accomplishments, 1-2 lines]
+
    ## Suggested Directions
 
-   - **[Direction 1]** — [brief rationale]
+   - **[Direction 1]** — [brief rationale from tech debt, audit, or strategic gaps]
    - **[Direction 2]** — [brief rationale]
    - **[Direction 3]** — [brief rationale]
    ```
 
    Sources for suggestions:
    - High-impact tech debt from TECH-DEBT.md or MILESTONE-AUDIT.md
+   - Untested assumptions from previous audit
    - Unaddressed requirements from previous milestones
    - Strategic features inferred from PROJECT.md's problem/audience/USP
-
-   Evaluate each by impact on user engagement, revenue, or growth.
+   - Pending todos from STATE.md
 
    If no meaningful artifacts exist (first milestone after v1.0), base suggestions purely on PROJECT.md.
 
-4. **Freeform opening:**
+5. **Freeform opening:**
 
    Ask inline (freeform text, NOT AskUserQuestion):
 
    "What do you want to build next?"
 
-   The user can pick from suggestions, combine them, or go a completely different direction.
+   The user can pick a suggestion, combine them, describe their own idea, share external context (specs, docs, analytics), or ask for help thinking it through.
 
-5. **Follow threads:**
-   - Based on what the user said, ask follow-up questions using AskUserQuestion
-   - Challenge vagueness, make abstract concrete
-   - Consult `questioning.md` for techniques
-   - Weave in relevant previous context (tech debt, pending todos) as natural follow-ups when relevant, not as a wall of info upfront
-   - Continue until clear goals emerge
+## Phase 2: Deepen
 
-6. **Decision gate:**
+6. **Adaptive depth based on response clarity:**
 
-   Use AskUserQuestion:
-   - header: "Ready?"
-   - question: "I think I understand what you want to build. Ready to update PROJECT.md?"
-   - options:
-     - "Update PROJECT.md" — Let's move forward
-     - "Keep exploring" — I want to share more / ask me more
+   - **Clear, detailed response** → brief confirmation ("Sounds like you want X, Y, Z — let me confirm a few things"), then move toward Phase 3 quickly
+   - **Vague response** → probe with AskUserQuestion, explore features, challenge vagueness
+   - **External context shared** → integrate it, clarify implications, ask follow-ups
 
-   Loop until "Update PROJECT.md" selected.
+7. **Follow the thread:**
+   - Dig into what they said before switching topics
+   - Challenge vagueness, make abstract concrete (questioning.md techniques)
+   - "When you say X, do you mean A or B?"
+   - "Walk me through what that looks like"
+   - "What's the simplest version of this that would be useful?"
 
-7. **Determine milestone version:**
-   - Parse last version from MILESTONES.md
-   - Suggest next version (v1.0 → v1.1, or v2.0 for major)
-   - Confirm with user
+8. **Probe for edges:**
+   - Simplest useful version vs full vision
+   - MVP vs complete — what can wait?
+   - Constraints: technical, time, dependencies
+   - What's explicitly NOT part of this milestone?
 
-8. **Update PROJECT.md:**
+9. **Surface previous context organically:**
+   - When relevant to what the user described, weave in tech debt, untested assumptions, pending todos
+   - NOT as a wall of info upfront — only when it connects to their stated direction
+   - "That relates to [tech debt item] from last milestone — want to address that too?"
 
-   Add/update these sections:
+10. **Synthesize periodically:**
 
-   ```markdown
-   ## Current Milestone: v[X.Y] [Name]
+    When you have a clear picture forming:
 
-   **Goal:** [One sentence describing milestone focus]
+    ```
+    Here's what I'm hearing:
 
-   **Target features:**
-   - [Feature 1]
-   - [Feature 2]
-   - [Feature 3]
-   ```
+    **Features:**
+    - [Feature 1]: [brief description]
+    - [Feature 2]: [brief description]
 
-   Update Active requirements section with new goals.
+    **Priority:** [what matters most]
+    **Scope boundary:** [what's NOT included]
+    ```
 
-   Update "Last updated" footer.
+11. **Decision gate:**
 
-9. **Update STATE.md:**
+    Use AskUserQuestion:
+    - header: "Ready?"
+    - question: "Ready to create the milestone?"
+    - options:
+      - "Create milestone" — update PROJECT.md and generate context
+      - "Keep exploring" — I want to share more or ask me more
+      - "Let me add context" — I have specs/docs/details to share
 
-   ```markdown
-   ## Current Position
+    If "Keep exploring" or "Let me add context" → loop back to step 6.
+    Loop until "Create milestone" selected.
 
-   Phase: Not started (run /ms:create-roadmap)
-   Plan: —
-   Status: Defining requirements
-   Last activity: [today] — Milestone v[X.Y] started
-   ```
+## Phase 3: Commit
 
-10. **Git commit:**
-   ```bash
-   git add .planning/PROJECT.md .planning/STATE.md
-   git commit -m "docs: start milestone v[X.Y] [Name]"
-   ```
+12. **Determine milestone version:**
+    - Parse last version from MILESTONES.md
+    - Suggest next version (v1.0 → v1.1, or v2.0 for major shifts)
+    - Confirm with user via AskUserQuestion
 
-11. **Calculate next phase for context:**
+13. **Present milestone summary:**
 
-   ```bash
-   LAST_PHASE=$(ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1)
-   if [ -n "$LAST_PHASE" ]; then
-     NEXT_PHASE=$((10#$LAST_PHASE + 1))
-   else
-     NEXT_PHASE=1
-   fi
-   echo "Next milestone phases will start at: Phase $NEXT_PHASE"
-   ```
+    ```
+    ## Milestone Summary
+
+    **Version:** v[X.Y] [Name]
+    **Goal:** [One sentence]
+    **Target features:**
+    - [Feature 1]
+    - [Feature 2]
+    - [Feature 3]
+    ```
+
+    Use AskUserQuestion:
+    - header: "Confirm"
+    - question: "Look good?"
+    - options:
+      - "Looks good" — proceed
+      - "Adjust" — let me change something
+
+    If "Adjust" → ask what to change, update, re-confirm.
+
+14. **Update PROJECT.md:**
 
-12. **Route to next step:**
+    Add/update these sections:
 
-    Based on the conversation, recommend ONE path. If unfamiliar domains or open technical questions surfaced, recommend `/ms:research-project`. Otherwise recommend `/ms:define-requirements`.
+    ```markdown
+    ## Current Milestone: v[X.Y] [Name]
+
+    **Goal:** [One sentence describing milestone focus]
+
+    **Target features:**
+    - [Feature 1]
+    - [Feature 2]
+    - [Feature 3]
+    ```
+
+    Update Active requirements section with new goals.
+    Update "Last updated" footer.
+
+15. **Write MILESTONE-CONTEXT.md:**
+
+    Create `.planning/MILESTONE-CONTEXT.md` using template from `~/.claude/mindsystem/templates/milestone-context.md`.
+
+    Populate from the conversation:
+    - Vision — the "why" in user's words
+    - Features — with rationale and scope notes
+    - External context — any specs, docs, or references shared
+    - Scope boundaries — what's explicitly excluded
+    - Priorities — must-have vs nice-to-have
+    - Open questions — things needing research
+
+16. **Update STATE.md:**
+
+    ```markdown
+    ## Current Position
+
+    Phase: Not started (run /ms:create-roadmap)
+    Plan: —
+    Status: Defining requirements
+    Last activity: [today] — Milestone v[X.Y] started
+
+    Progress: ░░░░░░░░░░ 0%
+    ```
+
+    Keep Accumulated Context (decisions, blockers) from previous milestone.
+
+17. **Git commit:**
+
+    ```bash
+    git add .planning/PROJECT.md .planning/STATE.md .planning/MILESTONE-CONTEXT.md
+    git commit -m "$(cat <<'EOF'
+    docs: start milestone v[X.Y] [Name]
+    EOF
+    )"
+    ```
+
+18. **Calculate next phase number:**
+
+    ```bash
+    LAST_PHASE=$(ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1)
+    if [ -n "$LAST_PHASE" ]; then
+      NEXT_PHASE=$((10#$LAST_PHASE + 1))
+    else
+      NEXT_PHASE=1
+    fi
+    echo "Next milestone phases will start at: Phase $NEXT_PHASE"
+    ```
+
+19. **Route to next step:**
+
+    Based on the conversation, recommend ONE path. If unfamiliar domains or open questions surfaced during discovery, recommend `/ms:research-project`. Otherwise recommend `/ms:create-roadmap`.
 
     ```
     Milestone v[X.Y] [Name] initialized.
 
     PROJECT.md updated with new goals.
+    Context saved to MILESTONE-CONTEXT.md
     Phases will start at: Phase $NEXT_PHASE
 
     ---
 
     ## ▶ Next Up
 
-    **[Recommended command name]** — [one-line reason from conversation]
+    **[Recommended command]** — [one-line reason from conversation]
 
     `/ms:[recommended-command]`
 
-    `/clear` first — fresh context window
+    <sub>`/clear` first → fresh context window</sub>
 
     ---
 
     **Also available:** `/ms:[alternative-command]`
+
+    ---
     ```
 
-13. **Update last command**
+20. **Update last command:**
     - Update `.planning/STATE.md` Last Command field
     - Format: `Last Command: ms:new-milestone $ARGUMENTS | YYYY-MM-DD HH:MM`
 
@@ -185,7 +288,8 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 <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
-- User routed to define-requirements (or research-project)
+- User routed to create-roadmap (or research-project if unknowns surfaced)
 </success_criteria>

package/commands/ms/new-project.md

@@ -305,10 +305,10 @@ Research ecosystem → define requirements → create roadmap. Discovers standar
 
 `/ms:research-project`
 
-**Option B: Define requirements directly** (familiar domains)
-Skip research, define requirements from what you know, then create roadmap.
+**Option B: Define requirements and roadmap directly** (familiar domains)
+Skip research, define requirements and create roadmap from what you know.
 
-`/ms:define-requirements`
+`/ms:create-roadmap`
 
 <sub>`/clear` first → fresh context window</sub>
 

package/commands/ms/research-project.md

@@ -150,7 +150,7 @@ IMPORTANT for subsequent milestones:
 </project_context>
 
 <downstream_consumer>
-Your FEATURES.md feeds into /ms:define-requirements. Categorize clearly:
+Your FEATURES.md feeds into /ms:create-roadmap. Categorize clearly:
 - Table stakes (must have or users leave)
 - Differentiators (competitive advantage)
 - Anti-features (things to deliberately NOT build)
@@ -336,7 +336,7 @@ Key findings:
 
 ---
 ## > Next Up
-**Define requirements** - `/ms:define-requirements`
+**Define requirements and create roadmap** - `/ms:create-roadmap`
 <sub>`/clear` first</sub>
 ---
 ```

package/commands/ms/review-design.md

@@ -117,12 +117,16 @@ ls .planning/phases/${PHASE_ARG}-*/*-DESIGN.md 2>/dev/null
 
 ### Step 2.3: Optional Context
 
-**implement-ui skill (if exists):**
+**Project UI skill (if exists):**
+
+Discover project-level skills:
 ```bash
-ls .claude/skills/*implement-ui* 2>/dev/null
+ls .claude/skills/*/SKILL.md 2>/dev/null
 ```
 
-If exists, load as authoritative source for existing patterns.
+If skills found, read the YAML frontmatter (name + description) of each SKILL.md. Identify any skill whose description indicates it provides UI implementation patterns (screens, widgets, components, theming, spacing, visual patterns).
+
+If a UI skill is found, load as authoritative source for existing patterns.
 
 **Codebase analysis:**
 - Detect platform (Flutter, React, etc.)
@@ -192,7 +196,7 @@ Apply quality-forcing patterns from `ai-driven-ui-design-system.md`:
 
 ### 3.5: Pattern Alignment
 
-If implement-ui skill or codebase patterns exist:
+If project UI skill or codebase patterns exist:
 - Check for consistent color usage
 - Check for consistent component patterns
 - Check for consistent spacing scale
@@ -478,7 +482,7 @@ Apply these patterns throughout the review:
 
 <success_criteria>
 - [ ] Target code scope clarified (via arguments or AskUserQuestion)
-- [ ] Context chain loaded (PROJECT.md, DESIGN.md if exists, implement-ui skill)
+- [ ] Context chain loaded (PROJECT.md, DESIGN.md if exists, project UI skill)
 - [ ] Code analyzed across all quality dimensions
 - [ ] Retroactive DESIGN.md created if missing
 - [ ] Improvements presented with benefits AND trade-offs

package/commands/ms/verify-work.md

@@ -41,7 +41,7 @@ Phase: $ARGUMENTS (optional)
 2. **Check for active UAT sessions** — Resume or start new
 3. **Find SUMMARY.md files** for the phase
 4. **Extract testable deliverables** from summaries
-5. **Classify tests by mock requirements** — Infer mock_type from test descriptions
+5. **Classify tests by mock requirements** — Use SUMMARY.md mock_hints when available; classify inline with keyword heuristics when absent. Confirm data availability with user before batching.
 6. **Group into batches** — By mock type, max 4 per batch, no-mock tests first
    - If any tests require mocks: Read `~/.claude/mindsystem/references/mock-patterns.md` and `~/.claude/mindsystem/workflows/generate-mocks.md` for mock generation guidance
 7. **For each batch:**

package/mindsystem/references/continuation-format.md

@@ -167,16 +167,15 @@ All 4 phases shipped
 
 ## ▶ Next Up
 
-**Plan v1.1** — Enhanced features and optimizations
+**Start v1.1** — discover what to build next
 
-`/ms:discuss-milestone`
+`/ms:new-milestone`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/ms:new-milestone` — create directly if scope is clear
 - Review accomplishments before moving on
 
 ---

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 (implement-ui skill, established codebase patterns):
+When the project has an existing visual aesthetic (project UI skill, established codebase patterns):
 
 **ALL variants use the same colors, fonts, and component shapes.** Directions differ ONLY in:
 - Layout and spatial organization

package/mindsystem/references/mock-patterns.md

@@ -16,6 +16,47 @@ Without mocks, testing "error message display" requires actually triggering serv
 4. **Removable** — Delete file + remove imports = clean
 </philosophy>
 
+<classification_framework>
+
+**Two-question framework for mock classification:**
+
+For each test, ask two questions in order:
+
+1. **Is the observable state transient?**
+   - Does it appear briefly during async operations? (loading skeleton, spinner, transition animation)
+   - Does it require precise timing to observe? (appears for <1s before real data loads)
+   - If YES → `mock_type: "transient_state"` — needs delay/force mock strategy
+
+2. **Does the test depend on external data?**
+   - Does the feature fetch from an API, database, or external service?
+   - Would the test fail without specific data existing locally?
+   - If YES → `mock_type: "external_data"` — confirm data availability with user first
+
+**Two-tier classification priority:**
+
+| Priority | Source | When used |
+|----------|--------|-----------|
+| 1 | SUMMARY.md `mock_hints` | Executor captured hints at build time (including `none` for explicit no-mock) |
+| 2 | Inline classification + keyword heuristics | No `mock_hints` key (legacy summaries) — classify in main context using two-question framework + keywords |
+
+**Why keyword matching alone fails:**
+
+Domain terms don't map reliably to mock types. "View recipe list" needs external_data mocks but contains no keywords. "Loading skeleton" is transient_state but keyword matching might miss the underlying async dependency. The two-question framework traces UI elements to their data sources instead of pattern-matching descriptions.
+
+**Category examples:**
+
+| Test | Classification | Reasoning |
+|------|---------------|-----------|
+| "Recipe list loading skeleton" | transient_state | Brief UI state during async fetch — resolves in <1s |
+| "View recipe list" | external_data | Fetches from /api/recipes — data may not exist locally |
+| "Login error message" | error_state | Error response from auth endpoint |
+| "Empty favorites placeholder" | empty_response | Requires zero items in collection |
+| "Premium badge display" | premium_user | Requires premium subscription state |
+| "Offline sync indicator" | offline_state | Requires network disconnection |
+| "Tap login button" | no mock needed | Happy path with available test credentials |
+
+</classification_framework>
+
 <git_stash_lifecycle>
 
 **Why stash?**
@@ -95,10 +136,12 @@ class TestOverrides {
   static bool forceErrorState = false;
   static bool forceEmptyResponse = false;
   static bool forceLoadingState = false;
+  static bool forceTransientState = false;
 
   // === MOCK DATA ===
   static String mockErrorMessage = 'Simulated error for testing';
   static Duration mockLoadingDelay = const Duration(seconds: 3);
+  static Duration mockTransientDelay = const Duration(seconds: 5);
 
   static Map<String, dynamic> mockPremiumUser = {
     'id': 'test-user-001',
@@ -113,6 +156,7 @@ class TestOverrides {
     forceErrorState = false;
     forceEmptyResponse = false;
     forceLoadingState = false;
+    forceTransientState = false;
   }
 }
 ```
@@ -142,6 +186,10 @@ class UserService {
     if (TestOverrides.forceErrorState) {
       throw Exception(TestOverrides.mockErrorMessage);
     }
+    // TEST OVERRIDE - Extend transient state (loading skeleton stays visible)
+    if (TestOverrides.forceTransientState) {
+      await Future.delayed(TestOverrides.mockTransientDelay);
+    }
 
     // Real implementation
     final response = await _api.get('/items');