mindsystem-cc 3.19.0 → 3.21.0

package/README.md

@@ -262,14 +262,14 @@ Replace `<N>` with the phase number you're working on.
 **Run:**
 
 ```
-/ms:audit-milestone 1.0.0
-/ms:complete-milestone 1.0.0
-/ms:new-milestone "v1.1"
+/ms:audit-milestone
+/ms:complete-milestone
+/ms:new-milestone
 ```
 
 **What you'll get:**
 
-- `.planning/milestones/v1.0/` — archived milestone (ROADMAP, REQUIREMENTS, DECISIONS, research)
+- `.planning/milestones/mvp/` — archived milestone (ROADMAP, REQUIREMENTS, DECISIONS, research)
 - Active docs stay lean; full detail lives in the version folder
 
 **Tip:** Milestone review can be **report-only** (e.g., Flutter structural review) so you stay in control. Create a quality phase, or accept tech debt explicitly — your call.
@@ -338,11 +338,10 @@ Full docs live in `/ms:help` (same content as `commands/ms/help.md`).
 | `/ms:map-codebase`                       | Document existing repo's stack, structure, and conventions    |
 | `/ms:research-project`                   | Do domain research and save findings to `.planning/research/` |
 | `/ms:create-roadmap`                     | Define requirements and create phases mapped to them          |
-| `/ms:discuss-phase <number>`             | Lock intent and constraints before planning                   |
+| `/ms:discuss-phase <number>`             | Product-informed collaborative thinking before planning       |
 | `/ms:design-phase <number>`              | Generate UI/UX spec for UI-heavy work                         |
 | `/ms:review-design [scope]`              | Audit and improve existing UI quality                         |
 | `/ms:research-phase <number>`            | Do deep research for niche phase domains                      |
-| `/ms:list-phase-assumptions <number>`    | Show what Mindsystem assumes before planning                  |
 | `/ms:plan-phase [number] [--gaps]`       | Create small, verifiable plans with optional risk-based verification |
 | `/ms:check-phase <number>`               | Sanity-check plans before execution                           |
 | `/ms:execute-phase <phase-number>`       | Run all unexecuted plans in fresh subagents                   |

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-mockup-designer.md

@@ -1,7 +1,7 @@
 ---
 name: ms-mockup-designer
 description: Generates self-contained HTML/CSS mockups for design direction exploration. Spawned by design-phase command.
-model: sonnet
+model: opus
 tools: Read, Write, Bash
 color: magenta
 ---

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/agents/ms-product-researcher.md

@@ -0,0 +1,69 @@
+---
+name: ms-product-researcher
+description: Researches competitor products, UX patterns, and industry best practices for phase-level product decisions. Spawned by /ms:discuss-phase.
+model: sonnet
+tools: WebSearch, WebFetch
+color: cyan
+---
+
+<input>
+You receive: `<product_context>` (Who It's For, Core Value, How It's Different), `<phase_requirements>` (phase goal + mapped requirements), `<research_focus>` (specific product questions to investigate).
+</input>
+
+<role>
+You are a Mindsystem product researcher. Deliver prescriptive, audience-grounded product intelligence — "Users expect X" beats "Consider whether X."
+
+**Prescriptive, not exploratory.** "Users expect inline editing for this type of content" beats "You could consider inline editing or modal editing or page-based editing." Make a recommendation, explain why, let the user override.
+
+**Audience-grounded.** Every recommendation ties back to the target audience from `<product_context>`. "Enterprise users expect X" is different from "Consumer app users expect Y." Never give generic advice.
+
+**Competitor-aware, not competitor-driven.** Know what exists. Recommend what fits THIS product's positioning. "Competitors do X, but given your differentiation of Y, consider Z" is the ideal output shape.
+
+**Concise and structured.** Target 2000-3000 tokens max. The orchestrator weaves your findings into a briefing — dense signal beats comprehensive coverage.
+</role>
+
+<tool_strategy>
+
+| Need | Tool | Why |
+|------|------|-----|
+| Competitor features | WebSearch | Discover what exists |
+| UX pattern details | WebFetch | Read specific articles/docs |
+| Industry best practices | WebSearch | Current standards |
+| Product comparisons | WebSearch | Side-by-side analysis |
+
+**Include current year** in search queries for freshness.
+
+**Budget:** 5-8 searches max. Prioritize breadth over depth — the user needs a landscape, not a dissertation.
+</tool_strategy>
+
+<output>
+Return structured text (do NOT write files). Use this format:
+
+```markdown
+## PRODUCT RESEARCH COMPLETE
+
+### Competitor Landscape
+[How 3-5 relevant competitors handle this. Specific features, not vague descriptions.]
+
+### UX Patterns Users Expect
+[Industry conventions for this type of feature. What feels "right" to the target audience.]
+
+### Audience Expectations
+[What the target audience specifically expects, grounded in Who It's For from `<product_context>`.]
+
+### Key Tradeoffs
+[2-3 decision points with pros/cons and recommendation for each.]
+
+### Recommendations
+[Prescriptive recommendations tied to this product's positioning. "Do X because Y."]
+```
+</output>
+
+<success_criteria>
+- Findings grounded in target audience, not generic
+- Competitor analysis names specific products and features
+- Recommendations are prescriptive with reasoning
+- Total output 2000-3000 tokens
+- No technical implementation details
+- Every recommendation connects to product positioning
+</success_criteria>

package/agents/ms-research-synthesizer.md

@@ -1,7 +1,7 @@
 ---
 name: ms-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /ms:research-project after 4 researcher agents complete.
-model: haiku
+model: sonnet
 tools: Read, Write, Bash
 color: purple
 ---

package/agents/ms-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: ms-researcher
 description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /ms:research-phase and /ms:research-project orchestrators.
-model: sonnet
+model: opus
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 color: cyan
 ---
@@ -195,18 +195,18 @@ When researching "best library for X":
 
 ## ms-lookup CLI
 
-The CLI is at `~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh`.
+The CLI is available as `ms-lookup`.
 
 ### Library Documentation
 
 ```bash
-~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh docs <library> "<query>"
+ms-lookup docs <library> "<query>"
 ```
 
 Example:
 ```bash
-~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh docs nextjs "app router file conventions"
-~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh docs "react-three-fiber" "physics setup"
+ms-lookup docs nextjs "app router file conventions"
+ms-lookup docs "react-three-fiber" "physics setup"
 ```
 
 **When to use:** Library APIs, framework features, configuration options, version-specific behavior. This is your PRIMARY source for library-specific questions — most authoritative.
@@ -216,13 +216,13 @@ Example:
 ### Deep Research
 
 ```bash
-~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh deep "<query>"
+ms-lookup deep "<query>"
 ```
 
 Example:
 ```bash
-~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh deep "authentication patterns for SaaS applications"
-~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh deep "WebGPU browser support and production readiness 2026"
+ms-lookup deep "authentication patterns for SaaS applications"
+ms-lookup deep "WebGPU browser support and production readiness 2026"
 ```
 
 **When to use:** Architecture decisions, technology comparisons, comprehensive ecosystem surveys, best practices synthesis. Use for HIGH-VALUE research questions — this costs money.

package/agents/ms-roadmapper.md

@@ -222,20 +222,16 @@ All use binary Likely/Unlikely with parenthetical reason. These are hints to use
 
 ### Discussion Indicators
 
-**Problem it solves:** User's mental model isn't documented. Planning happens without understanding what's essential vs nice-to-have.
+**Problem it solves:** Claude plans based on assumptions about user intent. Discussion surfaces those assumptions before they become embedded in plans.
 
-**Likely when ANY of:**
-- Phase goal mentions "user can [verb]" without specifying HOW
-- Success criteria have multiple valid interpretations
-- Phase involves UX decisions (not just backend)
-- Requirements mention experiential qualities ("should feel", "intuitive")
-- Novel feature not based on existing patterns
+**Default: Likely.** Every phase benefits from surfacing Claude's assumptions before planning. Discussion now provides deep artifact loading, assumptions surfacing, and product-informed questions — valuable even for seemingly "clear" phases.
 
-**Unlikely when ALL of:**
-- Requirements are specific and unambiguous
-- Backend/infrastructure only (APIs, database, CI/CD)
-- Follows clearly established patterns
-- Bug fix, performance, or technical debt work
+**When Likely**, the rationale enumerates 2-4 phase-specific assumptions or open questions (not generic labels like "ambiguous user flow"). Example: "Likely (assumes password reset uses email not SMS, unclear if social login needed, session duration unspecified)"
+
+**Unlikely only when ALL of:**
+- Fully mechanical (zero design decisions)
+- Zero ambiguity in scope or approach
+- Examples: version bump, rename-only refactor, config-only change, pure deletion/cleanup
 
 ### Design Indicators
 
@@ -273,7 +269,7 @@ All use binary Likely/Unlikely with parenthetical reason. These are hints to use
 For each phase in ROADMAP.md:
 
 ```markdown
-**Discuss**: Likely (ambiguous user flow) | Unlikely (clear requirements)
+**Discuss**: Likely (assumes X, unclear if Y, Z unspecified) | Unlikely (mechanical change, zero decisions)
 **Discuss topics**: [What to clarify] (only if Likely)
 **Design**: Likely (significant new UI) | Unlikely (backend only)
 **Design focus**: [What to design] (only if Likely)

package/bin/install.js

@@ -404,6 +404,65 @@ function cleanupOrphanedFiles(claudeDir, filesToRemove) {
   }
 }
 
+/**
+ * Generate CLI wrapper scripts and configure PATH hook
+ */
+function generateWrappers(claudeDir) {
+  const binDir = path.join(claudeDir, 'bin');
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const wrappers = {
+    'ms-tools': '#!/usr/bin/env bash\nexec uv run "$(dirname "$0")/../mindsystem/scripts/ms-tools.py" "$@"\n',
+    'ms-lookup': '#!/usr/bin/env bash\nexec "$(dirname "$0")/../mindsystem/scripts/ms-lookup-wrapper.sh" "$@"\n',
+    'ms-compare-mockups': '#!/usr/bin/env bash\nexec uv run "$(dirname "$0")/../mindsystem/scripts/compare_mockups.py" "$@"\n',
+  };
+
+  for (const [name, content] of Object.entries(wrappers)) {
+    fs.writeFileSync(path.join(binDir, name), content);
+    fs.chmodSync(path.join(binDir, name), '755');
+  }
+
+  console.log(`  ${green}✓${reset} Generated CLI wrappers (${Object.keys(wrappers).join(', ')})`);
+}
+
+function ensurePathHook(claudeDir, isGlobal, configDir) {
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionStart))
+    settings.hooks.SessionStart = [];
+
+  // Idempotent — skip if already present
+  const marker = 'mindsystem/bin';
+  if (settings.hooks.SessionStart.some(e => JSON.stringify(e).includes(marker)))
+    return;
+
+  // Build PATH expression
+  let binExpr;
+  if (isGlobal) {
+    binExpr = configDir
+      ? `${claudeDir}/bin`
+      : '$HOME/.claude/bin';
+  } else {
+    binExpr = '$CLAUDE_PROJECT_DIR/.claude/bin';
+  }
+
+  settings.hooks.SessionStart.push({
+    matcher: '',
+    hooks: [{
+      type: 'command',
+      command: `echo 'export PATH="${binExpr}:$PATH"' >> "$CLAUDE_ENV_FILE"`
+    }]
+  });
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  console.log(`  ${green}✓${reset} Configured PATH hook`);
+}
+
 /**
  * Recursively copy directory, replacing paths in .md files
  */
@@ -466,8 +525,8 @@ function installFile(srcPath, destPath, pathPrefix) {
     fs.copyFileSync(srcPath, destPath);
   }
 
-  // Make shell scripts executable
-  if (srcPath.endsWith('.sh')) {
+  // Make scripts executable
+  if (srcPath.endsWith('.sh') || srcPath.endsWith('.py')) {
     fs.chmodSync(destPath, '755');
   }
 }
@@ -563,7 +622,11 @@ async function install(isGlobal) {
   fs.writeFileSync(versionDest, pkg.version);
   console.log(`  ${green}✓${reset} Wrote VERSION (${pkg.version})`);
 
-  // Phase 7: Check Python for ms-lookup
+  // Phase 7: Generate CLI wrappers and PATH hook
+  generateWrappers(claudeDir);
+  ensurePathHook(claudeDir, isGlobal, configDir);
+
+  // Phase 8: Check Python for ms-lookup
   const msLookupPath = path.join(claudeDir, 'mindsystem', 'scripts', 'ms-lookup');
   if (fs.existsSync(msLookupPath)) {
     try {
@@ -583,13 +646,13 @@ async function install(isGlobal) {
     }
   }
 
-  // Phase 8: Cleanup orphaned files
+  // Phase 9: Cleanup orphaned files
   if (orphans.length > 0) {
     console.log('');
     cleanupOrphanedFiles(claudeDir, orphans);
   }
 
-  // Phase 9: Write new manifest
+  // Phase 10: Write new manifest
   const newManifest = {
     version: pkg.version,
     installedAt: new Date().toISOString(),

package/commands/ms/add-phase.md

@@ -66,7 +66,7 @@ Parse the roadmap to find the current milestone section:
 Example structure:
 
 ```
-## Current Milestone: v1.0 Foundation
+## Current Milestone: Foundation
 
 ### Phase 4: Focused Command System
 ### Phase 5: Path Routing & Validation
@@ -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**: Default Likely — enumerate 2-4 assumptions or open questions specific
+   to the phase. Unlikely only for fully mechanical zero-decision work (version bump,
+   rename-only refactor, config-only change, pure deletion/cleanup).
+
+   **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/adhoc.md

@@ -71,7 +71,7 @@ Single git commit with all changes (code + code review changes + PLAN.md + SUMMA
 
 <step name="generate_patch">
 Generate patch file from adhoc commit.
-Run generate-adhoc-patch.sh with commit hash and output path.
+Run `ms-tools generate-adhoc-patch` with commit hash and output path.
 </step>
 
 <step name="completion">

package/commands/ms/audit-milestone.md

@@ -1,7 +1,7 @@
 ---
 name: ms:audit-milestone
 description: Audit milestone completion against original intent before archiving
-argument-hint: "[version]"
+argument-hint: "[name]"
 allowed-tools:
   - Read
   - Glob
@@ -22,7 +22,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
 </execution_context>
 
 <context>
-Version: $ARGUMENTS (optional — defaults to current milestone)
+Milestone: $ARGUMENTS (optional — defaults to current milestone from PROJECT.md)
 
 **Original Intent:**
 @.planning/PROJECT.md
@@ -130,13 +130,13 @@ For each requirement in REQUIREMENTS.md mapped to this milestone:
 - Check phase verification status
 - Determine: satisfied | partial | unsatisfied
 
-## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
+## 6. Aggregate into MILESTONE-AUDIT.md
 
-Create `.planning/v{version}-MILESTONE-AUDIT.md` with:
+Create `.planning/MILESTONE-AUDIT.md` with:
 
 ```yaml
 ---
-milestone: {version}
+milestone: {name}
 audited: {timestamp}
 status: passed | gaps_found | tech_debt
 scores:
@@ -231,7 +231,7 @@ For agents with `mode: analyze-only` (e.g., `ms-flutter-reviewer`):
 Task(
   prompt="
   <objective>
-  Analyze code from milestone {version} for structural issues.
+  Analyze code from milestone {name} for structural issues.
   Report findings only — do NOT make changes.
   </objective>
 
@@ -341,7 +341,7 @@ Findings are already tracked in `.planning/TECH-DEBT.md` via Step 8.5. Continue
 
 ### Path B: Simplifier Agents (default)
 
-For agents without `mode: analyze-only` (e.g., `ms-code-simplifier`, `ms-flutter-simplifier`):
+For agents without `mode: analyze-only` (e.g., `ms-code-simplifier`, `ms-flutter-code-quality`):
 
 **B1. Spawn code review agent:**
 
@@ -349,7 +349,7 @@ For agents without `mode: analyze-only` (e.g., `ms-code-simplifier`, `ms-flutter
 Task(
   prompt="
   <objective>
-  Review code from milestone {version}.
+  Review code from milestone {name}.
   Focus on architectural patterns, cross-phase consistency, and structural improvements.
   Preserve all functionality. Make changes that improve clarity and maintainability.
   </objective>
@@ -402,9 +402,9 @@ After code review (all sources now available), generate or update `.planning/TEC
 ## 9. Commit Audit Report
 
 ```bash
-git add .planning/v{version}-MILESTONE-AUDIT.md .planning/TECH-DEBT.md
+git add .planning/MILESTONE-AUDIT.md .planning/TECH-DEBT.md
 git commit -m "$(cat <<'EOF'
-docs(milestone): complete v{version} audit
+docs(milestone): complete {name} audit
 
 Status: {status}
 Scores: Requirements {N}/{M} | Phases {N}/{M} | Integration {N}/{M} | Flows {N}/{M}
@@ -425,11 +425,11 @@ Read `~/.claude/mindsystem/references/routing/audit-result-routing.md` and follo
 - [ ] Tech debt collected into .planning/TECH-DEBT.md (de-duplicated, TD-{N} IDs assigned)
 - [ ] Assumptions aggregated by phase
 - [ ] Integration checker spawned for cross-phase wiring
-- [ ] v{version}-MILESTONE-AUDIT.md created with assumptions section
+- [ ] MILESTONE-AUDIT.md created with assumptions section
 - [ ] Code review completed (or skipped if config says "skip")
 - [ ] If analyze-only reviewer: YAML findings parsed and added to report
 - [ ] If analyze-only reviewer: Binary decision presented (quality phase vs tech debt)
 - [ ] If quality phase chosen: Phase directory created, ROADMAP updated with TECH-DEBT.md scope
-- [ ] MILESTONE-AUDIT.md committed to git
+- [ ] MILESTONE-AUDIT.md and TECH-DEBT.md committed to git
 - [ ] Results presented with actionable next steps
 </success_criteria>