mindsystem-cc 4.0.4 → 4.1.0

package/README.md

@@ -31,6 +31,9 @@ npx mindsystem-cc
 [ new-milestone ]       Define what to build next
         │
         ▼
+[ research-milestone ]  (optional) Research domain before roadmapping
+        │
+        ▼
 [ create-roadmap ]      Derive requirements, map to phases
         │
         ▼
@@ -82,7 +85,17 @@ Claude reads your project history (tech debt, deferred requirements, validated d
 
 Think of it as guided brainstorming: Claude asks the right questions rather than prescribing answers, helping you figure out what to build next.
 
-### 2. Create roadmap
+### 2. Research milestone (optional)
+
+```
+/ms:research-milestone
+```
+
+Spawns 2-5 research agents adapted to your milestone scope — ecosystem/stack, product landscape, codebase feasibility, architecture, pitfalls. You approve which dimensions to research, then agents run in parallel.
+
+Produces `MILESTONE-RESEARCH.md` that the roadmapper consumes for better phase breakdowns. Valuable when entering unfamiliar domains, evaluating new tech stacks, or starting a project's first milestone.
+
+### 3. Create roadmap
 
 ```
 /ms:create-roadmap
@@ -94,7 +107,7 @@ Requirements define what must be TRUE when you ship, not what to build. This goa
 
 **Creates:** `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, phase directories.
 
-### 3. Discuss phase (optional, recommended)
+### 4. Discuss phase (optional, recommended)
 
 ```
 /ms:discuss-phase 1
@@ -106,7 +119,7 @@ Worth taking seriously. Decisions here propagate through everything that follows
 
 **Creates:** `CONTEXT.md` with vision, essentials, and reasoning-backed decisions.
 
-### 4. Design phase (optional)
+### 5. Design phase (optional)
 
 ```
 /ms:design-phase 1
@@ -116,7 +129,7 @@ Claude generates parallel HTML/CSS mockup variants and a side-by-side comparison
 
 The output is a `DESIGN.md` with exact design tokens (hex colors, px spacing, font weights), not descriptions of what things should look like.
 
-### 5. Research phase (optional)
+### 6. Research phase (optional)
 
 ```
 /ms:research-phase 1
@@ -126,7 +139,7 @@ Three parallel agents investigate at once: one queries external documentation th
 
 You resolve library conflicts if any come up. Otherwise, this runs with minimal input.
 
-### 6. Plan phase
+### 7. Plan phase
 
 ```
 /ms:plan-phase 1
@@ -140,7 +153,7 @@ You approve the plan structure and can adjust granularity.
 
 **Creates:** `PLAN.md` files, `EXECUTION-ORDER.md`.
 
-### 7. Execute phase
+### 8. Execute phase
 
 ```
 /ms:execute-phase 1
@@ -154,7 +167,7 @@ After execution, knowledge consolidation updates subsystem-scoped knowledge file
 
 **Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, knowledge file updates.
 
-### 8. Verify work
+### 9. Verify work
 
 ```
 /ms:verify-work 1
@@ -168,21 +181,21 @@ Fixes compound into knowledge files through automatic consolidation. This is whe
 
 **Creates:** `UAT.md`, `uat-fixes.patch`, knowledge file updates.
 
-### 9. Repeat
+### 10. Repeat
 
-Run steps 3-8 for each phase. Pick the preparation depth each phase needs.
+Run steps 4-9 for each phase. Pick the preparation depth each phase needs.
 
-### 10. Audit milestone
+### 11. Audit milestone
 
 ```
 /ms:audit-milestone
 ```
 
-Claude checks requirements coverage against `REQ-IDs`, spawns an integration checker for cross-phase wiring, aggregates untested UAT assumptions, and consolidates tech debt into `TECH-DEBT.md` with severity tiers and `TD-IDs`.
+Claude checks requirements coverage against `REQ-IDs`, verifies cross-phase wiring from verification artifacts, aggregates untested UAT assumptions, and consolidates tech debt into `TECH-DEBT.md` with severity tiers and `TD-IDs`.
 
 Optional code review with quality-phase decisions for high-impact findings. You decide what gets fixed vs. accepted as debt.
 
-### 11. Complete milestone
+### 12. Complete milestone
 
 ```
 /ms:complete-milestone
@@ -346,12 +359,8 @@ Every artifact Mindsystem generates lives in `.planning/` — a markdown knowled
 │       ├── CONTEXT.md                #   discussed, not yet planned
 │       └── 02-01-PLAN.md             #   planned, not yet executed
 │
-├── research/                         # /ms:research-project → domain ecosystem
-│   ├── STACK.md                      # Technology recommendations for this domain
-│   ├── ARCHITECTURE.md               # Common system structure patterns
-│   ├── FEATURES.md                   # Feature landscape in this domain
-│   ├── PITFALLS.md                   # Mistakes to avoid
-│   └── SUMMARY.md                    # Synthesized findings with roadmap implications
+├── MILESTONE-RESEARCH.md              # /ms:research-milestone → domain ecosystem
+│                                      #   Technology, product landscape, architecture, risks
 │
 ├── adhoc/                            # /ms:adhoc → out-of-pipeline work
 │   └── 2026-01-15-fix-token/
@@ -373,10 +382,9 @@ Every artifact Mindsystem generates lives in `.planning/` — a markdown knowled
         ├── ROADMAP.md                # Historical phase breakdown
         ├── REQUIREMENTS.md           # Final requirement status
         ├── PHASE-SUMMARIES.md        # Consolidated execution summaries
-        ├── MILESTONE-AUDIT.md        # Requirements coverage, integration check
+        ├── MILESTONE-AUDIT.md        # Requirements coverage, cross-phase wiring check
         ├── CONTEXT.md                # Original milestone brainstorm
-        ├── research/                 # Archived domain research
-        │   └── ...
+        ├── MILESTONE-RESEARCH.md     # Archived domain research (if existed)
         └── phases/                   # Archived phase artifacts
             └── 01-foundation/
                 ├── 01-changes.patch  #   code diffs retained
@@ -438,7 +446,7 @@ Full docs live in `/ms:help`.
 | `/ms:new-project` | Initialize `.planning/` and capture project intent |
 | `/ms:config` | Configure code reviewers, mockups, gitignore, git remote |
 | `/ms:map-codebase` | Document existing repo's stack, structure, and conventions |
-| `/ms:research-project` | Domain research saved to `.planning/research/` |
+| `/ms:research-milestone` | Milestone-scoped research saved to `.planning/MILESTONE-RESEARCH.md` |
 | `/ms:create-roadmap` | Define requirements and create phases mapped to them |
 | `/ms:new-milestone [name]` | Discover what to build next, start new milestone |
 | `/ms:discuss-phase <number>` | Product-informed collaborative thinking before planning |

package/agents/ms-researcher.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /ms:research-phase and /ms:research-milestone orchestrators.
 model: opus
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 color: cyan
@@ -12,7 +12,7 @@ You are a Mindsystem researcher. You conduct comprehensive research using system
 You are spawned by:
 
 - `/ms:research-phase` orchestrator (phase-specific research before planning)
-- `/ms:research-project` orchestrator (project-wide research before roadmap)
+- `/ms:research-milestone` orchestrator (milestone-scoped research before roadmap)
 
 Your job: Answer research questions with verified, actionable findings. Produce structured output files that inform quality planning.
 </role>
@@ -461,7 +461,7 @@ Output format templates are in `~/.claude/mindsystem/templates/`. Read the match
 | Research Type | Template |
 |---------------|----------|
 | Phase research | `~/.claude/mindsystem/templates/research.md` |
-| Project research | `~/.claude/mindsystem/templates/research-project-output.md` |
+| Milestone research | `~/.claude/mindsystem/templates/milestone-research.md` |
 | Comparison | `~/.claude/mindsystem/templates/research-comparison-output.md` |
 | Feasibility | `~/.claude/mindsystem/templates/research-feasibility-output.md` |
 

package/agents/ms-roadmapper.md

@@ -52,7 +52,7 @@ Parse the milestone context for:
 
 If PROJECT.md has a `## Deferred` section, treat those items as v1 candidates for this milestone. Cross-reference deferred items with milestone context — if the milestone naturally covers a deferred item, promote to v1; if not relevant to this milestone, keep deferred.
 
-If research/FEATURES.md exists, cross-reference:
+If MILESTONE-RESEARCH.md exists, cross-reference Product Landscape:
 - Table stakes → strong v1 candidates
 - Differentiators → contextual (include if aligned with milestone priorities)
 - Anti-features → out of scope
@@ -413,9 +413,12 @@ Use template from `~/.claude/mindsystem/templates/roadmap.md`.
 
 Key sections:
 - Overview (2-3 sentences)
+- Research Conclusions (when MILESTONE-RESEARCH.md was provided)
 - Phases with Goal, Dependencies, Requirements, Success Criteria
 - Progress table
 
+**Research Conclusions:** When MILESTONE-RESEARCH.md is provided, add a `## Research Conclusions` section between Overview and Phases. Subsections: Technology Stack, Key Constraints, Architecture Decisions, Risk Mitigations. Extract from MILESTONE-RESEARCH.md sections. This is the mechanism for downstream passthrough — plan-phase, discuss-phase, and research-phase consume this implicitly by reading ROADMAP.md.
+
 ## STATE.md Structure
 
 Use template from `~/.claude/mindsystem/templates/state.md`.
@@ -492,8 +495,7 @@ Approve roadmap or provide feedback for revision.
 Orchestrator provides:
 - MILESTONE-CONTEXT.md content (or gathered context from user questioning)
 - PROJECT.md content (core value, constraints)
-- research/FEATURES.md content (if exists - feature categorization)
-- research/SUMMARY.md content (if exists - phase suggestions)
+- MILESTONE-RESEARCH.md content (if exists - technology decisions, product landscape, architecture, risks)
 - config.json (starting phase number)
 
 Parse and confirm understanding before proceeding.
@@ -506,9 +508,12 @@ Apply `<requirements_derivation>` process. Write REQUIREMENTS.md immediately usi
 
 ## Step 3: Load Research Context (if exists)
 
-If research/SUMMARY.md provided:
-- Extract suggested phase structure from "Implications for Roadmap"
-- Note research flags (which phases need deeper research)
+If MILESTONE-RESEARCH.md provided:
+- Extract technology decisions and constraints
+- Use Architecture & Dependencies for phase ordering
+- Use Pitfalls for pre-work Research indicator enrichment
+- Use Feasibility constraints for phase boundary decisions
+- Use Open Questions to populate per-phase Research topics
 - Use as input, not mandate
 
 Research informs phase identification but requirements drive coverage.

package/commands/ms/audit-milestone.md

@@ -9,12 +9,13 @@ allowed-tools:
   - Bash
   - Task
   - Write
+  - AskUserQuestion
 ---
 
 <objective>
 Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
 
-**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), generates/updates `.planning/TECH-DEBT.md` as single source of truth for tech debt, then spawns integration checker for cross-phase wiring.
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), generates/updates `.planning/TECH-DEBT.md` as single source of truth for tech debt, then checks cross-phase wiring inline from verification and summary artifacts.
 </objective>
 
 <execution_context>
@@ -37,7 +38,7 @@ Glob: .planning/phases/*/*-SUMMARY.md
 Glob: .planning/phases/*/*-VERIFICATION.md
 
 **Tech Debt:**
-Read `.planning/TECH-DEBT.md` at Step 8.5 (lazy — only needed for de-duplication)
+Read `.planning/TECH-DEBT.md` at Step 7.5 (lazy — only needed for de-duplication)
 </context>
 
 <process>
@@ -100,37 +101,33 @@ assumptions:
           reason: "Can't manipulate time in tests"
 ```
 
-## 3. Spawn Integration Checker
+## 3. Cross-Phase Wiring Check
 
-With phase context collected:
+Check aggregate cross-phase connections that per-phase verifiers miss.
 
-```
-Task(
-  prompt="Check cross-phase integration and E2E flows.
+From the SUMMARY.md and VERIFICATION.md files already loaded in Step 2:
 
-Phases: {phase_dirs}
-Phase exports: {from SUMMARYs}
-API routes: {routes created}
+1. **Build provides/consumes map** — For each phase SUMMARY, extract key exports, files created, APIs defined. Identify what each phase provides and what it consumes from other phases.
 
-Verify cross-phase wiring and E2E user flows.",
-  subagent_type="ms-integration-checker"
-)
-```
+2. **Cross-reference verification results** — For each cross-phase dependency (Phase N consumes something Phase M provides), check Phase M's VERIFICATION.md:
+   - Provider artifact is VERIFIED → connection satisfied
+   - Provider artifact is STUB, MISSING, or ORPHANED → wiring gap
 
-## 4. Collect Results
+3. **Flag aggregate patterns** — Multiple orphaned artifacts across phases (systemic wiring issue). APIs/exports created but consumed by no other phase's SUMMARY. A phase depending on another phase with status: gaps_found.
 
-Combine:
-- Phase-level gaps and tech debt (from step 2)
-- Integration checker's report (wiring gaps, broken flows)
+Produce a wiring summary:
+- **Connected:** N cross-phase dependencies satisfied
+- **Gaps:** N unsatisfied (list each: from-phase → to-phase, what's missing)
+- **Score:** wiring = connected / (connected + gaps)
 
-## 5. Check Requirements Coverage
+## 4. Check Requirements Coverage
 
 For each requirement in REQUIREMENTS.md mapped to this milestone:
 - Find owning phase
 - Check phase verification status
 - Determine: satisfied | partial | unsatisfied
 
-## 6. Aggregate into MILESTONE-AUDIT.md
+## 5. Aggregate into MILESTONE-AUDIT.md
 
 Create `.planning/MILESTONE-AUDIT.md` with:
 
@@ -142,12 +139,10 @@ status: passed | gaps_found | tech_debt
 scores:
   requirements: N/M
   phases: N/M
-  integration: N/M
-  flows: N/M
+  wiring: N/M
 gaps:  # Critical blockers
   requirements: [...]
-  integration: [...]
-  flows: [...]
+  wiring: [...]
 tech_debt: see .planning/TECH-DEBT.md
 assumptions:  # Tests skipped during UAT
   count: [N]
@@ -182,11 +177,11 @@ Plus full markdown report with tables for requirements, phases, integration, and
 - `gaps_found` — critical blockers exist
 - `tech_debt` — no blockers but accumulated deferred items need review
 
-## 7. Present Results
+## 6. Present Audit Summary
 
-Route by status (see `<offer_next>`).
+Present the audit summary (status, scores, gaps) to the user. Continue to Step 7.
 
-## 8. Code Review (Milestone)
+## 7. Code Review (Milestone)
 
 Read code review agent from config:
 
@@ -202,7 +197,7 @@ Proceed to next steps.
 Report: "No milestone reviewer configured. Run `/ms:config` to set one."
 Skip code review step (proceed to next steps).
 
-### Step 8.1: Get Changed Files
+### Step 7.1: Get Changed Files
 
 ```bash
 # Find first commit in milestone (first phase commit)
@@ -213,7 +208,7 @@ FIRST_COMMIT=$(git log --oneline --grep="(${FIRST_PHASE}-" --format="%H" | tail
 CHANGED_FILES=$(git diff --name-only ${FIRST_COMMIT}^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')
 ```
 
-### Step 8.2: Spawn Code Review Agent
+### Step 7.2: Spawn Code Review Agent
 
 ```
 Task(
@@ -246,7 +241,7 @@ Task(
 )
 ```
 
-### Step 8.3: Handle Results
+### Step 7.3: Handle Results
 
 The agent controls its own behavior — it may modify files, report findings, or both. React to what actually happened.
 
@@ -295,7 +290,7 @@ Add markdown section to report body:
 {Include full findings report from reviewer}
 ```
 
-Code review findings flow into `.planning/TECH-DEBT.md` via Step 8.5 — do NOT add them to `tech_debt` YAML.
+Code review findings flow into `.planning/TECH-DEBT.md` via Step 7.5 — do NOT add them to `tech_debt` YAML.
 
 **If any findings were reported**, present a decision gate. Recommend based on findings profile:
 
@@ -360,16 +355,16 @@ Continue to offer_next section.
 
 **If user chooses "Accept as tech debt":**
 
-Findings are already tracked in `.planning/TECH-DEBT.md` via Step 8.5. Continue to offer_next section.
+Findings are already tracked in `.planning/TECH-DEBT.md` via Step 7.5. Continue to offer_next section.
 
-## 8.5. Generate/Update TECH-DEBT.md
+## 7.5. Generate/Update TECH-DEBT.md
 
 After code review (all sources now available), generate or update `.planning/TECH-DEBT.md`:
 
 1. **Read existing** `.planning/TECH-DEBT.md` (if exists) — parse active items and dismissed list, note highest `TD-{N}` ID
 2. **Read template** from `@~/.claude/mindsystem/templates/tech-debt.md`
 3. **Collect tech debt** from all sources with severity mapping:
-   - Integration checker bugs → **Critical**
+   - Cross-phase wiring gaps → **Critical**
    - Unfixed UAT issues (result: `issue`, fix_status ≠ `verified`) → **Critical** (blocker) / **High** (major) / **Medium** (minor) / **Low** (cosmetic)
    - Code review findings → pass through reviewer severity (**High** / **Medium** / **Low**)
    - Phase VERIFICATION.md anti-patterns → **Medium** or **Low** (blockers go to `gaps`, not tech debt)
@@ -378,7 +373,7 @@ After code review (all sources now available), generate or update `.planning/TEC
 5. **Assign `TD-{N}` IDs** continuing from highest existing ID
 6. **Write/update** `.planning/TECH-DEBT.md` — group items under `## Critical`, `## High`, `## Medium`, `## Low` sections per template. Omit empty sections.
 
-## 9. Commit Audit Report
+## 8. Commit Audit Report
 
 ```bash
 git add .planning/MILESTONE-AUDIT.md .planning/TECH-DEBT.md
@@ -386,7 +381,7 @@ git commit -m "$(cat <<'EOF'
 docs(milestone): complete {name} audit
 
 Status: {status}
-Scores: Requirements {N}/{M} | Phases {N}/{M} | Integration {N}/{M} | Flows {N}/{M}
+Scores: Requirements {N}/{M} | Phases {N}/{M} | Wiring {N}/{M}
 EOF
 )"
 ```
@@ -402,12 +397,10 @@ Read `~/.claude/mindsystem/references/routing/audit-result-routing.md` and follo
 - [ ] If quality phase chosen: Phase directory created, ROADMAP updated with TECH-DEBT.md scope
 - [ ] If files modified by reviewer: changes committed
 - [ ] If findings reported: parsed and added to MILESTONE-AUDIT.md
-- [ ] MILESTONE-AUDIT.md and TECH-DEBT.md committed to git
-- [ ] Tech debt collected into .planning/TECH-DEBT.md (de-duplicated, TD-{N} IDs assigned)
-- [ ] UAT assumptions collected and aggregated by phase
-- [ ] Integration checker spawned for cross-phase wiring
 - [ ] Code review completed (or skipped if config says "skip")
-- [ ] All phase VERIFICATION.md files read
-- [ ] MILESTONE-AUDIT.md created with assumptions section
+- [ ] Tech debt collected into .planning/TECH-DEBT.md (de-duplicated, TD-{N} IDs assigned)
+- [ ] UAT assumptions collected, aggregated by phase, and included in MILESTONE-AUDIT.md
+- [ ] MILESTONE-AUDIT.md and TECH-DEBT.md committed to git
+- [ ] Cross-phase wiring checked from all phase verification and summary artifacts
 - [ ] Results presented with actionable next steps
 </success_criteria>

package/commands/ms/create-roadmap.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 Define project requirements and create roadmap with phase breakdown.
 
-Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-project`.
+Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-milestone`.
 </objective>
 
 <execution_context>
@@ -23,8 +23,7 @@ Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-proj
 <context>
 @.planning/PROJECT.md
 @.planning/MILESTONE-CONTEXT.md (if exists)
-@.planning/research/FEATURES.md (if exists)
-@.planning/research/SUMMARY.md (if exists)
+@.planning/MILESTONE-RESEARCH.md (if exists)
 </context>
 
 <process>
@@ -36,7 +35,7 @@ Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-proj
 
 # Detect available context
 [ -f .planning/MILESTONE-CONTEXT.md ] && echo "HAS_MILESTONE_CONTEXT" || echo "NO_MILESTONE_CONTEXT"
-[ -d .planning/research ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
+[ -f .planning/MILESTONE-RESEARCH.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
 [ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
 [ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
 ```
@@ -64,7 +63,7 @@ If "Replace": Continue
 
 **If MILESTONE-CONTEXT.md exists:** Skip (context ready for agent).
 
-**If no MILESTONE-CONTEXT.md but HAS_RESEARCH:** Skip (research provides feature context).
+**If no MILESTONE-CONTEXT.md but HAS_RESEARCH:** Skip (MILESTONE-RESEARCH.md provides feature context).
 
 **If neither exists (first milestone, no research):**
 
@@ -122,8 +121,7 @@ Task(
 **Starting phase number:** $START_PHASE
 
 **Research (if exists):**
-@.planning/research/FEATURES.md
-@.planning/research/SUMMARY.md
+@.planning/MILESTONE-RESEARCH.md
 
 **Config:**
 @.planning/config.json

package/commands/ms/help.md

@@ -30,7 +30,7 @@ Output ONLY the reference content below. Do NOT add:
 
 1. `/ms:new-project` — Initialize project with brief
 2. `/ms:config` — (optional) Configure code reviewers and gitignore
-3. `/ms:research-project` — (optional) Research domain ecosystem
+3. `/ms:research-milestone` — (optional) Research domain ecosystem
 4. `/ms:create-roadmap` — Define requirements and create roadmap
 5. `/ms:plan-phase 1` — Create detailed plan for first phase
 6. `/ms:execute-phase 1` — Execute with parallel agents
@@ -62,7 +62,7 @@ Initialize → (Optional Research) → Roadmap → Plan → Execute → Verify
 Common deviations:
 - Existing repo: `/ms:map-codebase` after `/ms:new-project` (or before — either works)
 - Plan looks wrong: `/ms:discuss-phase <phase>`
-- Unknown domain: `/ms:research-project` or `/ms:research-phase <phase>`
+- Unknown domain: `/ms:research-milestone` before roadmap, or `/ms:research-phase <phase>` before planning
 - Phase prep: `/ms:discuss-phase` → `/ms:design-phase` → `/ms:research-phase` → `/ms:plan-phase` (all optional before plan)
 - New urgent work: `/ms:insert-phase <after> "<desc>"`
 - New non-urgent work: `/ms:add-todo "<desc>"`
@@ -109,15 +109,15 @@ Configure Mindsystem preferences — code reviewers, mockup preferences, gitigno
 
 Usage: `/ms:config`
 
-**`/ms:research-project`**
-Research domain ecosystem before creating roadmap.
+**`/ms:research-milestone`**
+Research milestone domain before creating roadmap.
 
 - Use when: you’re unsure about stack choices, common pitfalls, or “what good looks like” in this domain.
-- Spawns parallel agents to investigate stack, features, architecture, pitfalls
-- Creates `.planning/research/` with ecosystem knowledge
-- Recommended for best results; skip only if you need speed over thoroughness
+- Spawns 2-5 adaptive agents based on milestone scope (stack, product landscape, codebase feasibility, architecture, pitfalls)
+- Creates `.planning/MILESTONE-RESEARCH.md` — single file consumed by roadmapper
+- Research conclusions flow through ROADMAP.md to all downstream phase commands
 
-Usage: `/ms:research-project`
+Usage: `/ms:research-milestone`
 
 **`/ms:create-roadmap`**
 Define requirements and create roadmap with phases.
@@ -236,7 +236,7 @@ Audit milestone completion against original intent.
 
 - Use when: you think you’re “done” and want cross-phase integration + requirements coverage checked before archiving.
 - Reads phase VERIFICATION.md files and aggregates results
-- Spawns integration checker for cross-phase wiring
+- Checks cross-phase wiring from verification artifacts
 - Maintains TECH-DEBT.md as single source of truth for debt items
 - Creates MILESTONE-AUDIT.md with gaps and tech debt
 
@@ -287,7 +287,7 @@ Discover what to build next and start a new milestone.
 - Collaborative discovery through adaptive questioning
 - Updates PROJECT.md with new goals
 - Creates MILESTONE-CONTEXT.md for downstream consumption (roadmap, planning)
-- Routes to create-roadmap or research-project
+- Routes to create-roadmap or research-milestone
 
 Usage: `/ms:new-milestone`
 Usage: `/ms:new-milestone "Push Notifications"`
@@ -423,7 +423,7 @@ Usage: `/ms:release-notes`
 ├── ROADMAP.md            # Current phase breakdown
 ├── STATE.md              # Project memory & context
 ├── config.json           # Workflow settings
-├── research/             # Domain ecosystem research
+├── MILESTONE-RESEARCH.md # Domain ecosystem research (from /ms:research-milestone)
 ├── todos/                # Captured ideas and tasks
 │   ├── *.md              # Pending todos (flat files)
 │   └── done/             # Completed todos
@@ -460,7 +460,7 @@ Usage: `/ms:release-notes`
 ```
 /ms:new-project                 # Extract your idea through questions
 /ms:config                      # (optional) Configure code reviewers and gitignore
-/ms:research-project            # (recommended) Research domain ecosystem
+/ms:research-milestone            # (recommended) Research domain ecosystem
 /ms:create-roadmap              # Define requirements and create phases
 /ms:plan-phase 1                # Create detailed plan
 /ms:execute-phase 1             # Execute with parallel agents
@@ -472,7 +472,7 @@ Usage: `/ms:release-notes`
 /ms:new-project                 # Step 1: Questions focus on business context and vision
 /ms:map-codebase                # Step 2: Analyze existing code
 /ms:config                      # (optional) Configure code reviewers and gitignore
-/ms:research-project            # (optional) Research new domain areas
+/ms:research-milestone            # (optional) Research new domain areas
 /ms:create-roadmap              # Define requirements and create roadmap
 /ms:plan-phase 1                # Codebase docs load automatically
 /ms:execute-phase 1             # Claude knows your patterns & conventions
@@ -526,7 +526,7 @@ Common options:
 
 ```
 /ms:new-milestone                     # Discover what to build, update PROJECT.md
-/ms:research-project                  # (optional) Domain / stack research
+/ms:research-milestone                  # (optional) Domain / stack research
 /ms:create-roadmap                    # New phases mapped to requirements
 /ms:plan-phase                        # Auto-detect next unplanned phase
 /ms:execute-phase <phase>

package/commands/ms/new-milestone.md

@@ -16,7 +16,7 @@ Start a new milestone by helping the user discover what to build next, then upda
 
 Self-contained command — three phases: Orient (load context, present directions), Deepen (collaborative discovery), Commit (update files, route forward).
 
-Output: Updated PROJECT.md, new MILESTONE-CONTEXT.md, routes to create-roadmap or research-project
+Output: Updated PROJECT.md, new MILESTONE-CONTEXT.md, routes to create-roadmap or research-milestone
 </objective>
 
 <execution_context>
@@ -278,7 +278,7 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 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`.
+    Based on the conversation, recommend ONE path. If unfamiliar domains or open questions surfaced during discovery, recommend `/ms:research-milestone`. Otherwise recommend `/ms:create-roadmap`.
 
     ```
     Milestone [Name] initialized.
@@ -311,5 +311,5 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 - MILESTONE-CONTEXT.md created with vision, features, scope, priorities
 - STATE.md reset for new milestone
 - Git commit made
-- User routed to create-roadmap (or research-project if unknowns surfaced)
+- User routed to create-roadmap (or research-milestone if unknowns surfaced)
 </success_criteria>