mindsystem-cc 3.10.0 → 3.11.0

package/commands/ms/create-roadmap.md

@@ -1,6 +1,6 @@
 ---
 name: ms:create-roadmap
-description: Create roadmap with phases for the project
+description: Define requirements and create roadmap with phases
 allowed-tools:
   - Read
   - Write
@@ -11,17 +11,19 @@ allowed-tools:
 ---
 
 <objective>
-Create project roadmap with phase breakdown.
+Define project requirements and create roadmap with phase breakdown.
 
-Roadmaps define what work happens in what order. Phases map to requirements.
+Derives REQUIREMENTS.md from MILESTONE-CONTEXT.md (or through lightweight questioning for first milestones), then maps requirements to phases.
 
-Run after `/ms:define-requirements`.
+Run after `/ms:new-milestone` or `/ms:new-project` + optional `/ms:research-project`.
 
-**Improvement:** Spawns ms-roadmapper agent for heavy lifting, presents roadmap for approval before committing.
+**How it works:** Spawns ms-roadmapper agent which derives requirements AND creates roadmap in one pass, then presents combined results for approval.
 </objective>
 
 <execution_context>
 @~/.claude/mindsystem/references/principles.md
+@~/.claude/mindsystem/workflows/define-requirements.md
+@~/.claude/mindsystem/templates/requirements.md
 @~/.claude/mindsystem/templates/roadmap.md
 @~/.claude/mindsystem/templates/state.md
 @~/.claude/mindsystem/references/goal-backward.md
@@ -30,7 +32,8 @@ Run after `/ms:define-requirements`.
 <context>
 @.planning/PROJECT.md
 @.planning/config.json
-@.planning/REQUIREMENTS.md
+@.planning/MILESTONE-CONTEXT.md (if exists)
+@.planning/research/FEATURES.md (if exists)
 @.planning/research/SUMMARY.md (if exists)
 </context>
 
@@ -41,32 +44,58 @@ Run after `/ms:define-requirements`.
 # Verify project exists
 [ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /ms:new-project first."; exit 1; }
 
-# Verify requirements exist
-[ -f .planning/REQUIREMENTS.md ] || { echo "ERROR: No REQUIREMENTS.md found. Run /ms:define-requirements first."; exit 1; }
+# 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/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
+[ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
 ```
 </step>
 
 <step name="check_existing">
-Check if roadmap already exists:
+Check if requirements or roadmap already exist:
 
-```bash
-[ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
-```
-
-**If ROADMAP_EXISTS:**
+**If REQUIREMENTS_EXISTS or ROADMAP_EXISTS:**
 Use AskUserQuestion:
-- header: "Roadmap exists"
-- question: "A roadmap already exists. What would you like to do?"
+- header: "Files exist"
+- question: "Existing planning files found. What would you like to do?"
 - options:
-  - "View existing" — Show current roadmap
-  - "Replace" — Create new roadmap (will overwrite)
-  - "Cancel" — Keep existing roadmap
+  - "View existing" — Show current files
+  - "Replace" — Define requirements and create roadmap fresh (will overwrite)
+  - "Cancel" — Keep existing files
 
-If "View existing": `cat .planning/ROADMAP.md` and exit
+If "View existing": Read and display existing files, then exit
 If "Cancel": Exit
 If "Replace": Continue
 </step>
 
+<step name="gather_context">
+**Thin path — only when no MILESTONE-CONTEXT.md and no research exist.**
+
+**If MILESTONE-CONTEXT.md exists:** Skip (context ready for agent).
+
+**If no MILESTONE-CONTEXT.md but HAS_RESEARCH:** Skip (research provides feature context).
+
+**If neither exists (first milestone, no research):**
+
+Lightweight questioning in main context to gather enough feature context for the agent:
+
+1. Read PROJECT.md for core value and stated requirements/constraints
+2. Ask inline: "What are the main things users need to do in v1?"
+3. For each capability mentioned, probe for specifics with AskUserQuestion
+4. Ask about scope boundaries: "Anything you explicitly want to exclude?"
+5. Ask about priorities: "What's most important to get right first?"
+
+Capture responses as gathered context to pass to the agent.
+
+Use AskUserQuestion before spawning:
+- header: "Ready?"
+- question: "Ready to generate requirements and roadmap from this context?"
+- options:
+  - "Generate" — Spawn agent with gathered context
+  - "Add more" — I want to share more details
+</step>
+
 <step name="spawn_roadmapper">
 **Calculate starting phase number:**
 
@@ -96,12 +125,14 @@ Task(
 **Project:**
 @.planning/PROJECT.md
 
-**Requirements:**
-@.planning/REQUIREMENTS.md
+**Milestone context:**
+{If MILESTONE-CONTEXT.md exists: @.planning/MILESTONE-CONTEXT.md}
+{If no MILESTONE-CONTEXT.md: gathered context from questioning step}
 
 **Starting phase number:** $START_PHASE
 
 **Research (if exists):**
+@.planning/research/FEATURES.md
 @.planning/research/SUMMARY.md
 
 **Config:**
@@ -110,19 +141,19 @@ Task(
 </planning_context>
 
 <instructions>
-Create roadmap:
-1. Derive phases from requirements (don't impose structure)
-2. **Start phase numbering at $START_PHASE** (not 1, unless this is the first milestone)
-3. Map every v1 requirement to exactly one phase
-4. Derive 2-5 success criteria per phase (observable user behaviors)
-5. Validate 100% coverage
-6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-7. Return ROADMAP CREATED with summary
+1. Derive REQUIREMENTS.md from milestone context (apply requirements_derivation process)
+2. Derive phases from those requirements (don't impose structure)
+3. **Start phase numbering at $START_PHASE** (not 1, unless this is the first milestone)
+4. Map every v1 requirement to exactly one phase
+5. Derive 2-5 success criteria per phase (observable user behaviors)
+6. Validate 100% coverage
+7. Write files immediately (REQUIREMENTS.md, ROADMAP.md, STATE.md)
+8. Return ROADMAP CREATED with combined requirements + roadmap summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
 """,
-  description="Create roadmap"
+  description="Derive requirements and create roadmap"
 )
 ```
 </step>
@@ -135,14 +166,31 @@ Write files first, then return. This ensures artifacts persist even if context i
 
 **If `## ROADMAP CREATED`:**
 
-Read the created ROADMAP.md and present it inline:
+Read the created REQUIREMENTS.md and ROADMAP.md and present both inline:
 
 ```
 ---
 
-## Proposed Roadmap
+## Requirements & Roadmap
+
+### v1 Requirements
+
+**{X} requirements** across {N} categories
+
+{For each category:}
+**{Category}**
+- [ ] **{REQ-ID}**: {description}
+- [ ] **{REQ-ID}**: {description}
+
+{If v2 requirements exist:}
+**v2 (deferred):** {count} requirements
+**Out of scope:** {count} exclusions
+
+---
+
+### Roadmap
 
-**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓
+**{M} phases** | All v1 requirements covered ✓
 
 | # | Phase | Goal | Requirements | Success Criteria |
 |---|-------|------|--------------|------------------|
@@ -161,15 +209,6 @@ Success criteria:
 Pre-work: Research [Likely/Unlikely] | Discuss [Likely/Unlikely] | Design [Likely/Unlikely]
 {If any Likely: topics/focus on next line}
 
-**Phase 2: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-Pre-work: Research [Likely/Unlikely] | Discuss [Likely/Unlikely] | Design [Likely/Unlikely]
-{If any Likely: topics/focus on next line}
-
 [... continue for all phases ...]
 
 ---
@@ -181,14 +220,40 @@ Pre-work: Research [Likely/Unlikely] | Discuss [Likely/Unlikely] | Design [Likel
 
 Use AskUserQuestion:
 - header: "Roadmap"
-- question: "Does this roadmap structure work for you?"
+- question: "Do these requirements and roadmap work for you?"
 - options:
   - "Approve" — Commit and continue
-  - "Adjust phases" — Tell me what to change
-  - "Review full file" — Show raw ROADMAP.md
+  - "Adjust requirements" — Change what's in/out of scope
+  - "Adjust phases" — Change phase structure
+  - "Review full files" — Show raw REQUIREMENTS.md and ROADMAP.md
 
 **If "Approve":** Continue to commit step.
 
+**If "Adjust requirements":**
+- Get user's adjustment notes (ask inline what they want to change)
+- Re-spawn roadmapper with revision context:
+  ```
+  Task(
+    subagent_type="ms-roadmapper",
+    prompt="""
+<revision>
+User feedback on requirements:
+[user's notes]
+
+Current REQUIREMENTS.md: @.planning/REQUIREMENTS.md
+Current ROADMAP.md: @.planning/ROADMAP.md
+
+Update requirements based on feedback, then re-derive phases if needed.
+Edit files in place.
+Return ROADMAP REVISED with changes made.
+</revision>
+""",
+    description="Revise requirements and roadmap"
+  )
+  ```
+- Present revised output
+- Loop until user approves
+
 **If "Adjust phases":**
 - Get user's adjustment notes (ask inline what they want to change)
 - Re-spawn roadmapper with revision context:
@@ -197,9 +262,10 @@ Use AskUserQuestion:
     subagent_type="ms-roadmapper",
     prompt="""
 <revision>
-User feedback on roadmap:
+User feedback on roadmap phases:
 [user's notes]
 
+Current REQUIREMENTS.md: @.planning/REQUIREMENTS.md
 Current ROADMAP.md: @.planning/ROADMAP.md
 
 Update the roadmap based on feedback. Edit files in place.
@@ -212,16 +278,19 @@ Return ROADMAP REVISED with changes made.
 - Present revised roadmap
 - Loop until user approves
 
-**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask approval.
+**If "Review full files":** Display raw REQUIREMENTS.md and ROADMAP.md, then re-ask approval.
 </step>
 
 <step name="commit">
 After user approval:
 
 ```bash
-git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+git add .planning/REQUIREMENTS.md .planning/ROADMAP.md .planning/STATE.md
 git commit -m "$(cat <<'EOF'
-docs: create roadmap ([N] phases)
+docs: define requirements and create roadmap
+
+[X] v1 requirements across [N] categories.
+[M] phases mapped to requirements.
 
 Phases:
 1. [phase-name]: [requirements covered]
@@ -236,11 +305,12 @@ EOF
 
 <step name="done">
 ```
-Roadmap created:
+Requirements and roadmap created:
 
+- Requirements: .planning/REQUIREMENTS.md
 - Roadmap: .planning/ROADMAP.md
 - State: .planning/STATE.md
-- [N] phases defined
+- [X] v1 requirements, [M] phases defined
 
 ---
 
@@ -273,12 +343,12 @@ Update `.planning/STATE.md` Last Command field:
 
 <success_criteria>
 - [ ] PROJECT.md validated
-- [ ] REQUIREMENTS.md validated
+- [ ] Context gathered (from MILESTONE-CONTEXT.md, research, or questioning)
 - [ ] ms-roadmapper spawned with context
+- [ ] REQUIREMENTS.md created with REQ-IDs and scope classification
 - [ ] All v1 requirements mapped to phases (no orphans)
 - [ ] Success criteria derived for each phase (2-5 observable behaviors)
-- [ ] Roadmap presented to user for approval
+- [ ] Requirements and roadmap presented to user for approval
 - [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md, STATE.md committed after approval
-- [ ] REQUIREMENTS.md traceability section updated
+- [ ] REQUIREMENTS.md, ROADMAP.md, STATE.md committed after approval
 </success_criteria>

package/commands/ms/design-phase.md

@@ -12,7 +12,7 @@ allowed-tools:
 <objective>
 Create design specifications for a phase. Spawns ms-designer agent with phase context.
 
-**Orchestrator role:** Parse phase, validate against roadmap, check existing design, gather context chain (CONTEXT.md → implement-ui → codebase), adaptive Q&A if gaps, spawn designer agent, enable conversational refinement.
+**Orchestrator role:** Parse phase, validate against roadmap, check existing design, gather context chain (CONTEXT.md → project UI skill → codebase), adaptive Q&A if gaps, spawn designer agent, enable conversational refinement.
 
 **Why subagent:** Design requires focused attention with quality-forcing patterns. Fresh 200k context for design generation. Main context reserved for user refinement conversation.
 
@@ -107,14 +107,16 @@ If exists, extract:
 - What Must Be Nailed (essentials)
 - Specific Ideas (references to products)
 
-**3c. Optional context - implement-ui skill:**
+**3c. Optional context — project UI skill:**
 
+Discover project-level skills:
 ```bash
-# Check for implement-ui skill
-ls .claude/skills/*implement-ui* 2>/dev/null
+ls .claude/skills/*/SKILL.md 2>/dev/null
 ```
 
-If exists, load it as the authoritative source of 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, read its full content. Extract aesthetic patterns (colors, components, spacing, typography) for the `<existing_aesthetic>` block passed to ms-designer.
 
 **3d. Optional context - codebase analysis:**
 
@@ -140,7 +142,7 @@ Document discovered patterns for the designer.
 
 Assess context coverage:
 - Can platform be inferred? (from codebase or PROJECT.md)
-- Can visual style be inferred? (from implement-ui or codebase)
+- Can visual style be inferred? (from project UI skill or codebase)
 - Can design priorities be inferred? (from CONTEXT.md or phase requirements)
 
 **If everything can be inferred:** Skip to step 5.
@@ -240,15 +242,15 @@ Reference products: [From Q&A if asked, or "None specified"]
 </user_vision>
 
 <existing_aesthetic>
-[If implement-ui skill exists:]
+[If project UI skill exists:]
 
-Authoritative patterns from implement-ui skill:
+Authoritative patterns from project UI skill:
 - Color palette: [exact values]
 - Typography: [font families, sizes]
 - Spacing system: [scale values]
 - Component library: [named components]
 
-[If no skill, from codebase analysis:]
+[If no UI skill, from codebase analysis:]
 
 Discovered patterns from codebase:
 - Colors found: [hex values from theme/styles]
@@ -393,7 +395,7 @@ Update `.planning/STATE.md` Last Command field:
 - [ ] Phase validated against roadmap
 - [ ] Existing design checked and handled appropriately
 - [ ] Context chain loaded (PROJECT.md, ROADMAP.md, CONTEXT.md if exists)
-- [ ] implement-ui skill loaded if exists
+- [ ] Project UI skill discovered and loaded if exists
 - [ ] Codebase analyzed for existing patterns
 - [ ] Adaptive Q&A completed if gaps existed
 - [ ] Mockup generation offered if phase has significant new UI

package/commands/ms/execute-phase.md

@@ -173,15 +173,6 @@ All three run in parallel. Task tool blocks until all complete.
 **No polling.** No background agents. No TaskOutput loops.
 </wave_execution>
 
-<checkpoint_handling>
-Plans with `autonomous: false` have checkpoints. The execute-phase.md workflow handles the full checkpoint flow:
-- Subagent pauses at checkpoint, returns structured state
-- Orchestrator presents to user, collects response
-- Spawns fresh continuation agent (not resume)
-
-See `@~/.claude/mindsystem/workflows/execute-phase.md` step `checkpoint_handling` for complete details.
-</checkpoint_handling>
-
 <deviation_rules>
 During execution, handle discoveries automatically:
 

package/commands/ms/help.md

@@ -31,16 +31,15 @@ Output ONLY the reference content below. Do NOT add:
 
 1. `/ms:new-project` - Initialize project with brief
 2. `/ms:research-project` - (optional) Research domain ecosystem
-3. `/ms:define-requirements` - Scope v1/v2/out of scope
-4. `/ms:create-roadmap` - Create roadmap and phases
-5. `/ms:plan-phase 1` - Create detailed plan for first phase
-6. `/ms:execute-phase 1` - Execute with parallel agents
+3. `/ms:create-roadmap` - Define requirements and create roadmap
+4. `/ms:plan-phase 1` - Create detailed plan for first phase
+5. `/ms:execute-phase 1` - Execute with parallel agents
 
 ### Brownfield (existing codebase)
 
 1. `/ms:map-codebase` - Analyze existing code first
 2. `/ms:new-project` - Questions focus on what you’re adding/changing
-3. Continue with steps 2-6 above (codebase docs load automatically)
+3. Continue with steps 2-5 above (codebase docs load automatically)
 
 ## Staying Updated
 
@@ -59,7 +58,7 @@ npx mindsystem-cc@latest
 ## Core Workflow
 
 ```
-Initialize → (Optional Research) → Requirements → Roadmap → Plan → Execute → Verify → Milestone
+Initialize → (Optional Research) → Roadmap → Plan → Execute → Verify → Milestone
 ```
 
 Common deviations:
@@ -93,20 +92,12 @@ Research domain ecosystem before creating roadmap.
 
 Usage: `/ms:research-project`
 
-**`/ms:define-requirements`**
-Define what "done" looks like with checkable requirements.
-
-- Use when: you’re ready to lock v1 scope (and explicitly defer v2/out-of-scope).
-- Scopes features as v1, v2, or out of scope
-- Works with or without prior research
-- Creates `.planning/REQUIREMENTS.md` with traceability
-
-Usage: `/ms:define-requirements`
-
 **`/ms:create-roadmap`**
-Create roadmap and state tracking for initialized project.
+Define requirements and create roadmap with phases.
 
-- Use when: requirements are defined and you want phases mapped to them.
+- Use when: project is initialized and you want to scope requirements and map them to phases.
+- Derives REQUIREMENTS.md from MILESTONE-CONTEXT.md (or through questioning)
+- Creates `.planning/REQUIREMENTS.md` (scoped requirements)
 - Creates `.planning/ROADMAP.md` (phase breakdown)
 - Creates `.planning/STATE.md` (project memory)
 - Creates `.planning/phases/` directories
@@ -141,7 +132,7 @@ Create visual/UX design specifications for UI-heavy phases.
 - Produces DESIGN.md with layouts, components, flows, verification criteria
 - Optionally generates parallel HTML mockup variants for visual direction exploration
 - Applies quality-forcing patterns to prevent generic AI output
-- Checks for existing implement-ui skill and harmonizes with codebase
+- Discovers project UI skill dynamically and harmonizes with codebase
 - Use for phases with significant UI work, novel components, or cross-platform design
 
 Usage: `/ms:design-phase 3`
@@ -203,7 +194,6 @@ Execute all unexecuted plans in a phase with wave-based parallelization.
 
 - Use when: the phase has PLAN.md files and you want Mindsystem to run them (including verification and possible gap-closure loop).
 - Spawns parallel agents for independent plans
-- Handles checkpoints with user interaction
 - Resumes automatically from interrupted execution
 - Creates SUMMARY.md for each completed plan
 - Respects max_concurrent_agents from config.json
@@ -212,7 +202,6 @@ Usage: `/ms:execute-phase 5`
 
 Options (via `.planning/config.json` parallelization section):
 - `max_concurrent_agents`: Limit parallel agents (default: 3)
-- `skip_checkpoints`: Skip human checkpoints in background (default: true)
 - `min_plans_for_parallel`: Minimum plans to trigger parallelization (default: 2)
 
 ### Verification
@@ -285,14 +274,17 @@ Result: Phase 17 deleted, phases 18-20 become 17-19
 
 ### Milestone Management
 
-**`/ms:new-milestone <name>`**
-Create a new milestone with phases for an existing project.
+**`/ms:new-milestone [name]`**
+Discover what to build next and start a new milestone.
 
-- Use when: you shipped a version and want to scope the next one (or you want guided discovery for what to build next).
-- Adds milestone section to ROADMAP.md
-- Creates phase directories
-- Updates STATE.md for new milestone
+- Use when: you shipped a version and want to figure out what's next — or you already know and want to make it official.
+- Loads previous milestone context and suggests directions
+- 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
 
+Usage: `/ms:new-milestone`
 Usage: `/ms:new-milestone "v2.0 Features"`
 
 **`/ms:complete-milestone <version>`**
@@ -446,8 +438,7 @@ Usage: `/ms:release-notes`
 ```
 /ms:new-project                 # Extract your idea through questions
 /ms:research-project            # (recommended) Research domain ecosystem
-/ms:define-requirements         # Scope v1/v2/out of scope
-/ms:create-roadmap              # Create phases mapped to requirements
+/ms:create-roadmap              # Define requirements and create phases
 /ms:plan-phase 1                # Create detailed plan
 /ms:execute-phase 1             # Execute with parallel agents
 ```
@@ -458,8 +449,7 @@ Usage: `/ms:release-notes`
 /ms:map-codebase                # Step 1: Analyze existing code
 /ms:new-project                 # Step 2: Questions focus on what you're adding/changing
 /ms:research-project            # (optional) Research new domain areas
-/ms:define-requirements         # Scope what's changing
-/ms:create-roadmap              # Create roadmap
+/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
 ```
@@ -506,14 +496,13 @@ Common options:
 - Add work later: `/ms:add-phase "…"`
 - Insert urgent work before the next phase: `/ms:insert-phase <after> "…"`
 - Cut future work: `/ms:remove-phase <phase>`
-- Re-scope v1/v2/out-of-scope: `/ms:define-requirements` (choose Replace) → `/ms:create-roadmap` (choose Replace)
+- Re-scope v1/v2/out-of-scope: `/ms:create-roadmap` (choose Replace)
 
 **Implementing a new feature after shipping (new milestone):**
 
 ```
-/ms:new-milestone "v1.1 New feature"  # Choose discovery mode if you want help scoping
+/ms:new-milestone                     # Discover what to build, update PROJECT.md
 /ms:research-project                  # (optional) Domain / stack research
-/ms:define-requirements               # Re-scope v1/v2 for this milestone
 /ms:create-roadmap                    # New phases mapped to requirements
 /ms:plan-phase                        # Auto-detect next unplanned phase
 /ms:execute-phase <phase>
@@ -524,7 +513,7 @@ Common options:
 ```
 /ms:audit-milestone 1.0.0       # Verify before completing
 /ms:complete-milestone 1.0.0    # Archive and tag
-/ms:new-milestone "v1.1 Features"
+/ms:new-milestone               # Discover and start next milestone
 ```
 
 **Closing gaps from audit:**