mindsystem-cc 4.0.4 → 4.1.0

package/commands/ms/research-milestone.md

@@ -0,0 +1,339 @@
+---
+name: ms:research-milestone
+description: Research domain ecosystem before creating roadmap
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Research milestone domain before creating roadmap. Spawns 2-5 adaptive agents based on milestone scope.
+
+**Orchestrator role:** Analyze milestone context, determine research dimensions, spawn parallel agents returning text, synthesize into MILESTONE-RESEARCH.md.
+
+**Why this exists:** Sits between `/ms:new-milestone` and `/ms:create-roadmap`. Produces a single file the roadmapper consumes to create better phase breakdowns. Research conclusions flow through ROADMAP.md so all downstream phase commands implicitly benefit.
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/templates/milestone-research.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/MILESTONE-CONTEXT.md (if exists)
+@.planning/config.json (if exists)
+</context>
+
+<process>
+
+## 1. Validate Prerequisites
+
+```bash
+[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /ms:new-project first."; exit 1; }
+[ -f .planning/MILESTONE-CONTEXT.md ] || { echo "ERROR: No MILESTONE-CONTEXT.md. Run /ms:new-milestone first."; exit 1; }
+[ -f .planning/MILESTONE-RESEARCH.md ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
+```
+
+## 2. Handle Existing Research
+
+**If RESEARCH_EXISTS:** Use AskUserQuestion:
+- header: "Existing research"
+- question: "MILESTONE-RESEARCH.md already exists. What would you like to do?"
+- options:
+  - "View existing" — Show current research
+  - "Replace" — Research from scratch (will overwrite)
+  - "Cancel" — Keep existing
+
+If "View existing": Read and display, then exit.
+If "Cancel": Exit.
+If "Replace": Continue.
+
+## 3. Analyze Milestone Scope
+
+Read MILESTONE-CONTEXT.md and PROJECT.md. Extract:
+- **Features** — what the milestone aims to build
+- **Open Questions** — unknowns flagged during discovery
+- **Vision** — the "why" behind the milestone
+- **Priorities** — must-have vs nice-to-have
+- **Scope boundaries** — what's excluded
+
+Check if this is a brownfield project:
+```bash
+[ -d .planning/codebase ] && echo "BROWNFIELD" || echo "GREENFIELD"
+```
+
+## 4. Determine Research Dimensions
+
+Select which agents to spawn based on milestone context:
+
+| Dimension | Agent | Spawn when |
+|-----------|-------|------------|
+| Ecosystem/Stack | ms-researcher | Unfamiliar tech, first milestone, or Open Questions mention stack |
+| Product Landscape | ms-product-researcher | User-facing features where competitor analysis adds value |
+| Codebase Feasibility | ms-codebase-researcher | Brownfield project with existing codebase |
+| Architecture/Dependencies | ms-researcher | 3+ features with dependencies, or system design in Open Questions |
+| Pitfalls/Risk | ms-researcher | Unfamiliar domain, external services, complex integrations |
+
+Default: lean toward spawning more agents.
+
+Present proposed agents to user:
+
+```
+Research dimensions for milestone: [Name]
+
+Spawning [N] agents:
+1. [Dimension] — [one-line reason]
+2. [Dimension] — [one-line reason]
+...
+
+Proceed? (yes / adjust)
+```
+
+Use AskUserQuestion:
+- header: "Research scope"
+- question: "These agents will research your milestone. Adjust?"
+- options:
+  - "Proceed" — Spawn agents as proposed
+  - "Add dimension" — I want more coverage
+  - "Remove dimension" — Skip some of these
+  - "Cancel" — Skip research entirely
+
+## 5. Spawn Agents in Parallel
+
+Spawn all selected agents in a single message. Each agent receives milestone and project context and returns structured text (no file writes).
+
+**Announce:** "Spawning [N] research agents... may take 2-3 minutes."
+
+### Ecosystem/Stack Agent (ms-researcher)
+
+```
+Task(
+  prompt="
+<research_type>
+Milestone Research — Ecosystem/Stack dimension.
+</research_type>
+
+<milestone_context>
+[MILESTONE-CONTEXT.md content]
+</milestone_context>
+
+<project_context>
+[PROJECT.md summary — core value, constraints, tech stack if known]
+</project_context>
+
+<focus>
+Research the technology stack for this milestone scope. Recommend specific libraries with versions and rationale. Flag what NOT to use and why. If the project has an established stack, focus on NEW libraries needed for the milestone features.
+</focus>
+
+<output>
+Return findings as structured text. Do NOT write to filesystem.
+Format:
+## ECOSYSTEM/STACK FINDINGS
+### Recommended Stack (technology, version, purpose, rationale)
+### Alternatives Rejected (what, why not, use instead)
+### Version Constraints & Compatibility
+### Confidence (HIGH/MEDIUM/LOW per recommendation with sources)
+</output>
+",
+  subagent_type="ms-researcher",
+  description="Stack research"
+)
+```
+
+### Product Landscape Agent (ms-product-researcher)
+
+```
+Task(
+  prompt="
+<milestone_context>
+[MILESTONE-CONTEXT.md content]
+</milestone_context>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<focus>
+Research the product landscape for this milestone's features. What do users expect (table stakes)? What differentiates? What should be deliberately excluded?
+</focus>
+
+Return findings as structured text:
+## PRODUCT LANDSCAPE FINDINGS
+### Table Stakes (feature, why users expect it)
+### Differentiators (feature, competitive advantage)
+### Anti-Features (feature, why excluded)
+### Confidence (HIGH/MEDIUM/LOW with sources)
+",
+  subagent_type="ms-product-researcher",
+  description="Product research"
+)
+```
+
+### Codebase Feasibility Agent (ms-codebase-researcher)
+
+```
+Task(
+  prompt="
+<objective>
+Analyze codebase feasibility for milestone features.
+</objective>
+
+<milestone_context>
+[MILESTONE-CONTEXT.md content]
+</milestone_context>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<focus>
+Assess how the existing codebase supports the milestone's planned features. Identify which components need modification vs creation. Surface feasibility constraints and integration points.
+</focus>
+",
+  subagent_type="ms-codebase-researcher",
+  description="Codebase feasibility"
+)
+```
+
+### Architecture/Dependencies Agent (ms-researcher)
+
+```
+Task(
+  prompt="
+<research_type>
+Milestone Research — Architecture/Dependencies dimension.
+</research_type>
+
+<milestone_context>
+[MILESTONE-CONTEXT.md content]
+</milestone_context>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<focus>
+Research architecture patterns and component dependencies for this milestone. Determine build order based on dependencies. Identify integration points between components.
+</focus>
+
+<output>
+Return findings as structured text. Do NOT write to filesystem.
+Format:
+## ARCHITECTURE FINDINGS
+### Components (name, responsibility)
+### Build Order (sequence with rationale)
+### Integration Points (how components connect)
+### Confidence (HIGH/MEDIUM/LOW with sources)
+</output>
+",
+  subagent_type="ms-researcher",
+  description="Architecture research"
+)
+```
+
+### Pitfalls/Risk Agent (ms-researcher)
+
+```
+Task(
+  prompt="
+<research_type>
+Milestone Research — Pitfalls/Risk dimension.
+</research_type>
+
+<milestone_context>
+[MILESTONE-CONTEXT.md content]
+</milestone_context>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<focus>
+Research common pitfalls and risks for this milestone's domain and features. For each pitfall: severity, prevention strategy, and which components/phases it affects.
+</focus>
+
+<output>
+Return findings as structured text. Do NOT write to filesystem.
+Format:
+## PITFALLS/RISK FINDINGS
+### Pitfalls (pitfall, severity, prevention, affects)
+### Feasibility Assessment (feasible YES/CONDITIONALLY/NO, constraints)
+### Open Questions (needing resolution)
+### Confidence (HIGH/MEDIUM/LOW with sources)
+</output>
+",
+  subagent_type="ms-researcher",
+  description="Pitfalls research"
+)
+```
+
+## 6. Synthesize into MILESTONE-RESEARCH.md
+
+After all agents return, synthesize findings into `.planning/MILESTONE-RESEARCH.md` using template.
+
+Map agent returns to template sections:
+- Ecosystem/Stack → Technology Decisions
+- Product Landscape → Product Landscape
+- Codebase Feasibility → Feasibility Assessment + Architecture & Dependencies
+- Architecture → Architecture & Dependencies
+- Pitfalls/Risk → Pitfalls & Risks + Feasibility Assessment
+
+Write Executive Summary (2-3 paragraphs) synthesizing all findings.
+
+Merge overlapping findings. Resolve conflicts by preferring higher-confidence sources.
+
+## 7. Present Results and Commit
+
+```bash
+git add .planning/MILESTONE-RESEARCH.md
+git commit -m "$(cat <<'EOF'
+docs: complete milestone research
+
+Key findings:
+- Stack: [one-liner]
+- Architecture: [one-liner]
+- Critical pitfall: [one-liner]
+EOF
+)"
+```
+
+Present summary:
+
+```
+Research complete:
+
+File: .planning/MILESTONE-RESEARCH.md
+
+Key findings:
+- Stack: [one-liner]
+- Architecture: [one-liner]
+- Critical pitfall: [one-liner]
+- Feasibility: [YES/CONDITIONALLY/NO]
+
+---
+## ▶ Next Up
+`/ms:create-roadmap` — define requirements and create roadmap
+<sub>`/clear` first → fresh context window</sub>
+---
+```
+
+## 8. Update Last Command
+
+```bash
+ms-tools set-last-command "ms:research-milestone"
+```
+
+</process>
+
+<success_criteria>
+- [ ] PROJECT.md and MILESTONE-CONTEXT.md validated
+- [ ] Research dimensions determined and approved by user
+- [ ] 2-5 agents spawned in parallel (adaptive selection)
+- [ ] All agent results received and synthesized
+- [ ] MILESTONE-RESEARCH.md created using template
+- [ ] Research committed to git
+- [ ] User routed to /ms:create-roadmap
+</success_criteria>

package/mindsystem/references/questioning.md

@@ -16,7 +16,7 @@ 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: product domain, target audience, core problem, what unknowns exist
+- **research-milestone** 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

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

@@ -36,7 +36,7 @@ Ready to plan the next milestone.
 
 **Next milestone flow:**
 1. `/ms:new-milestone` — discover what to build, update PROJECT.md
-2. `/ms:research-project` — (optional) research ecosystem
+2. `/ms:research-milestone` — (optional) research ecosystem
 3. `/ms:create-roadmap` — plan how to build it
 
 ---

package/mindsystem/templates/milestone-context.md

@@ -69,7 +69,7 @@ Empty section if none — that's fine.]
 - If user didn't express priorities, derive from emphasis during conversation
 
 **Open Questions:**
-- Feed into `/ms:research-project` if research is needed
+- Feed into `/ms:research-milestone` if research is needed
 - Empty section is fine — not every milestone has unknowns
 - Questions should be specific enough to research
 

package/mindsystem/templates/milestone-research.md

@@ -0,0 +1,89 @@
+# Milestone Research Template
+
+Template for `.planning/MILESTONE-RESEARCH.md` — milestone-scoped research between `/ms:new-milestone` and `/ms:create-roadmap`.
+
+**Purpose:** Inform the roadmapper with technology decisions, product landscape, architecture constraints, and risk assessment. Each section maps to a specific roadmapper decision.
+
+**Created by:** `/ms:research-milestone` command
+
+**Consumed by:** `ms-roadmapper` agent during `/ms:create-roadmap`
+
+---
+
+## Template
+
+```markdown
+# Milestone Research: [Name]
+
+**Generated:** [date]
+**Source:** /ms:research-milestone
+
+## Executive Summary
+[2-3 paragraphs: what type of problem, recommended approach, key risks]
+
+## Technology Decisions
+### Recommended Stack
+| Technology | Version | Purpose | Rationale |
+|------------|---------|---------|-----------|
+| [lib] | [ver] | [what it does] | [why this choice] |
+
+### Alternatives Rejected
+| Rejected | Reason | Use Instead |
+|----------|--------|-------------|
+| [lib] | [why not] | [recommendation] |
+
+## Product Landscape
+### Table Stakes
+- [Feature]: [why users expect this]
+
+### Differentiators
+- [Feature]: [competitive advantage]
+
+### Anti-Features
+- [Feature]: [why deliberately excluded]
+
+## Architecture & Dependencies
+### Components
+- [Component]: [responsibility]
+
+### Build Order
+1. [First]: [rationale — what it unblocks]
+2. [Second]: [rationale]
+
+### Integration Points
+- [Integration]: [how components connect]
+
+## Feasibility Assessment
+### Feasible: [YES/CONDITIONALLY/NO]
+### Constraints
+- [Constraint and impact]
+
+### Open Questions
+- [Question needing resolution before or during implementation]
+
+## Pitfalls & Risks
+| Pitfall | Severity | Prevention | Affects |
+|---------|----------|------------|---------|
+| [risk] | [HIGH/MEDIUM/LOW] | [how to avoid] | [which phases/components] |
+
+## Sources
+### HIGH Confidence
+- [Source]: [what it verified]
+
+### MEDIUM Confidence
+- [Source]: [what it informed]
+
+### LOW Confidence
+- [Source]: [what it suggested — needs validation]
+```
+
+## Section-to-Roadmapper Mapping
+
+| Section | Roadmapper Decision |
+|---------|-------------------|
+| Technology Decisions | Phase content — what tools each phase uses |
+| Product Landscape | Requirements derivation — table stakes = v1 candidates |
+| Architecture & Dependencies | Phase ordering — build order drives phase sequence |
+| Feasibility Assessment | Phase boundaries and constraints |
+| Pitfalls & Risks | Pre-work Research indicators per phase |
+| Open Questions | Per-phase Research topics |

package/mindsystem/templates/requirements.md

@@ -82,7 +82,7 @@ Which phases cover which requirements. Updated by create-roadmap.
 - Checkbox: Only for v1 requirements (v2 are not yet actionable)
 
 **Categories:**
-- Derive from research FEATURES.md categories
+- Derive from MILESTONE-RESEARCH.md Product Landscape categories
 - Keep consistent with domain conventions
 - Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin
 

package/mindsystem/templates/roadmap.md

@@ -11,6 +11,21 @@ Template for `.planning/ROADMAP.md`.
 
 [One paragraph describing the journey from start to finish]
 
+## Research Conclusions
+[Present only when /ms:research-milestone informed the roadmap]
+
+### Technology Stack
+- [Technology]: [purpose] — [rationale]
+
+### Key Constraints
+- [Constraint and impact]
+
+### Architecture Decisions
+- [Decision and rationale]
+
+### Risk Mitigations
+- Phase [N]: [pitfall] — [prevention]
+
 ## Phases
 
 **Phase Numbering:**
@@ -122,6 +137,11 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 ```
 
 <guidelines>
+**Research Conclusions section:**
+- Populated by roadmapper when MILESTONE-RESEARCH.md exists
+- Downstream commands (plan-phase, discuss-phase, research-phase) consume this implicitly by reading ROADMAP.md
+- Omitted entirely when no milestone research was performed
+
 **Initial planning:**
 - Phase count derived from actual work (not a target number)
 - Each phase delivers something coherent

package/mindsystem/templates/tech-debt.md

@@ -10,7 +10,7 @@ Created and updated by `/ms:audit-milestone`. Items persist across milestones. U
 
 **Item IDs** use `TD-{N}` format — monotonically increasing, never reused. New items continue from highest existing ID.
 
-**Sources:** Phase verifications (anti-patterns, non-critical gaps), code review findings, integration checker bugs, unfixed UAT issues.
+**Sources:** Phase verifications (anti-patterns, non-critical gaps), code review findings, cross-phase wiring gaps, unfixed UAT issues.
 
 ---
 
@@ -30,7 +30,7 @@ Created and updated by `/ms:audit-milestone`. Items persist across milestones. U
 - **Location:** {file:line or component}
 - **Impact:** {what this causes and why it matters}
 - **Fix:** {how to address}
-- <sub>Phase {source phase} | {verification | integration-check | code-review} | v{milestone}</sub>
+- <sub>Phase {source phase} | {verification | wiring-check | code-review} | v{milestone}</sub>
 
 ---
 
@@ -47,13 +47,13 @@ Created and updated by `/ms:audit-milestone`. Items persist across milestones. U
 ## Guidelines
 
 **Severity levels:**
-- `Critical` — Breaks behavior or risks data loss. Integration checker bugs (broken cross-phase wiring, failed E2E flows) always map here.
+- `Critical` — Breaks behavior or risks data loss. Cross-phase wiring gaps (broken cross-phase connections, orphaned artifacts spanning phases) always map here.
 - `High` — Causes cascading changes if left unaddressed. Fragile patterns that spread to new code, missing abstractions forcing workarounds.
 - `Medium` — Contained friction. TODOs, missing validation, incomplete error handling. Impact stays local.
 - `Low` — Won't compound. Style inconsistencies, minor naming issues, improvement opportunities.
 
 **Severity mapping from sources:**
-- Integration checker bugs → Critical
+- Cross-phase wiring gaps → Critical
 - Unfixed UAT issues → Critical (blocker) / High (major) / Medium (minor) / Low (cosmetic)
 - Code review findings → pass through reviewer severity (High/Medium/Low)
 - Phase verification anti-patterns → Medium or Low (blockers go to `gaps`, not tech debt)

package/mindsystem/workflows/complete-milestone.md

@@ -538,7 +538,7 @@ Archived to milestones/{slug}/:
 - phases/ (phase directories moved from .planning/phases/)
 - MILESTONE-AUDIT.md (if audit was run)
 - CONTEXT.md (if milestone context existed)
-- research/ (if research existed)
+- MILESTONE-RESEARCH.md (if existed)
 
 Cleaned:
 - Raw phase artifacts deleted (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
@@ -548,7 +548,7 @@ Cleaned:
 Deleted (fresh for next milestone):
 - ROADMAP.md
 - REQUIREMENTS.md
-- .planning/research/ (archived to milestone)
+- MILESTONE-RESEARCH.md (archived to milestone)
 
 Updated:
 - MILESTONES.md (new entry)
@@ -574,7 +574,7 @@ Shipped:
 Archived to milestones/{slug}/:
 - ROADMAP.md
 - REQUIREMENTS.md
-- research/ (if existed)
+- MILESTONE-RESEARCH.md (if existed)
 
 Summary: .planning/MILESTONES.md
 
@@ -590,7 +590,7 @@ Summary: .planning/MILESTONES.md
 
 **Next milestone flow:**
 1. `/ms:new-milestone` — discover what to build, update PROJECT.md with goals
-2. `/ms:research-project` — (optional) research ecosystem
+2. `/ms:research-milestone` — (optional) research ecosystem
 3. `/ms:create-roadmap` — define requirements and plan how to build it
 
 ---

package/mindsystem/workflows/define-requirements.md

@@ -2,7 +2,7 @@
 Define concrete, checkable requirements for v1.
 
 Two modes:
-1. **With research** — Transform FEATURES.md into scoped requirements
+1. **With research** — Transform MILESTONE-RESEARCH.md Product Landscape into scoped requirements
 2. **Without research** — Gather requirements through questioning
 </purpose>
 
@@ -11,8 +11,7 @@ Two modes:
 
 1. ~/.claude/mindsystem/templates/requirements.md
 2. .planning/PROJECT.md
-3. .planning/research/FEATURES.md (if exists)
-4. .planning/research/SUMMARY.md (if exists)
+3. .planning/MILESTONE-RESEARCH.md (if exists)
 </required_reading>
 
 <process>
@@ -20,7 +19,7 @@ Two modes:
 <step name="detect_mode">
 Check for research:
 ```bash
-[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
+[ -f .planning/MILESTONE-RESEARCH.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
 ```
 
 **If HAS_RESEARCH:** Follow steps load_context → present_features → scope_categories
@@ -33,17 +32,16 @@ Read PROJECT.md and extract:
 - Stated constraints (budget, timeline, tech limitations)
 - Any explicit scope boundaries from project definition
 
-Read research/FEATURES.md and extract:
+Read MILESTONE-RESEARCH.md and extract from Product Landscape:
 - Table stakes (users expect these)
 - Differentiators (competitive advantage)
 - Anti-features (commonly requested, often problematic)
-- Feature dependencies
-- MVP vs full product recommendations
 
-Read research/SUMMARY.md for:
-- Overall confidence level
-- Key architectural constraints
-- Suggested phase structure (informational only)
+Extract from other sections:
+- Technology constraints and decisions
+- Architecture dependencies
+- Feasibility constraints
+- Key risks and pitfalls
 </step>
 
 <step name="load_project" mode="without_research">
@@ -105,7 +103,7 @@ Here are the features for [domain]:
 - OAuth (Google, GitHub)
 - 2FA
 
-**Research notes:** [any relevant notes from FEATURES.md]
+**Research notes:** [any relevant notes from MILESTONE-RESEARCH.md]
 
 ---
 
@@ -114,8 +112,8 @@ Here are the features for [domain]:
 ```
 
 For each category, include:
-- Table stakes from FEATURES.md
-- Differentiators from FEATURES.md
+- Table stakes from MILESTONE-RESEARCH.md
+- Differentiators from MILESTONE-RESEARCH.md
 - Any anti-features flagged (with warnings)
 - Complexity notes where relevant
 </step>