mindsystem-cc 3.0.0

package/commands/ms/debug.md

@@ -0,0 +1,149 @@
+---
+name: ms:debug
+description: Systematic debugging with persistent state across context resets
+argument-hint: [issue description]
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn ms-debugger agent, handle checkpoints, spawn continuations.
+
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+</objective>
+
+<context>
+User's issue: $ARGUMENTS
+
+Check for active sessions:
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+
+## 1. Check Active Sessions
+
+If active sessions exist AND no $ARGUMENTS:
+- List sessions with status, hypothesis, next action
+- User picks number to resume OR describes new issue
+
+If $ARGUMENTS provided OR user describes new issue:
+- Continue to symptom gathering
+
+## 2. Gather Symptoms (if new issue)
+
+Use AskUserQuestion for each:
+
+1. **Expected behavior** - What should happen?
+2. **Actual behavior** - What happens instead?
+3. **Error messages** - Any errors? (paste or describe)
+4. **Timeline** - When did this start? Ever worked?
+5. **Reproduction** - How do you trigger it?
+
+After all gathered, confirm ready to investigate.
+
+## 3. Spawn ms-debugger Agent
+
+Fill prompt and spawn:
+
+```markdown
+<objective>
+Investigate issue: {slug}
+
+**Summary:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="ms-debugger",
+  description="Debug {slug}"
+)
+```
+
+## 4. Handle Agent Return
+
+**If `## ROOT CAUSE FOUND`:**
+- Display root cause and evidence summary
+- Offer options:
+  - "Fix now" - spawn fix subagent
+  - "Plan fix" - suggest /ms:plan-phase --gaps
+  - "Manual fix" - done
+
+**If `## CHECKPOINT REACHED`:**
+- Present checkpoint details to user
+- Get user response
+- Spawn continuation agent (see step 5)
+
+**If `## INVESTIGATION INCONCLUSIVE`:**
+- Show what was checked and eliminated
+- Offer options:
+  - "Continue investigating" - spawn new agent with additional context
+  - "Manual investigation" - done
+  - "Add more context" - gather more symptoms, spawn again
+
+## 5. Spawn Continuation Agent (After Checkpoint)
+
+When user responds to checkpoint, spawn fresh agent:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="ms-debugger",
+  description="Continue debug {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Active sessions checked
+- [ ] Symptoms gathered (if new)
+- [ ] ms-debugger spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] Root cause confirmed before fixing
+</success_criteria>

package/commands/ms/define-requirements.md

@@ -0,0 +1,121 @@
+---
+name: ms:define-requirements
+description: Define what "done" looks like with checkable requirements
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Define concrete, checkable requirements for v1.
+
+Two modes:
+1. **With research** — Transform FEATURES.md into scoped requirements
+2. **Without research** — Gather requirements through questioning
+
+Run before `/ms:create-roadmap`.
+
+Output: `.planning/REQUIREMENTS.md`
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/principles.md
+@~/.claude/mindsystem/workflows/define-requirements.md
+@~/.claude/mindsystem/templates/requirements.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/research/FEATURES.md (if exists)
+@.planning/research/SUMMARY.md (if exists)
+</context>
+
+<process>
+
+<step name="validate">
+```bash
+# Verify project exists
+[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /ms:new-project first."; exit 1; }
+
+# Check for research
+[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
+
+# Check if requirements already exist
+[ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
+```
+</step>
+
+<step name="check_existing">
+**If REQUIREMENTS_EXISTS:**
+
+Use AskUserQuestion:
+- header: "Requirements exist"
+- question: "Requirements already defined. What would you like to do?"
+- options:
+  - "View existing" — Show current requirements
+  - "Replace" — Define requirements fresh (will overwrite)
+  - "Cancel" — Keep existing requirements
+
+If "View existing": Read and display `.planning/REQUIREMENTS.md`, then exit
+If "Cancel": Exit
+If "Replace": Continue with workflow
+</step>
+
+<step name="execute">
+**If HAS_RESEARCH:**
+Follow the define-requirements.md workflow:
+- Load research features from FEATURES.md
+- Present features by category
+- Ask user to scope each category (v1 / v2 / out of scope)
+- Capture any additions research missed
+- Generate REQUIREMENTS.md with checkable list
+
+**If NO_RESEARCH:**
+Gather requirements through questioning:
+- Read PROJECT.md for core value and context
+- Ask: "What are the main things users need to be able to do?"
+- For each capability mentioned, probe for specifics
+- Group into categories (Authentication, Content, etc.)
+- For each category, ask what's v1 vs v2 vs out of scope
+- Generate REQUIREMENTS.md with checkable list
+
+Same output format either way — the difference is source (research vs conversation).
+</step>
+
+<step name="done">
+```
+Requirements defined:
+
+- Requirements: .planning/REQUIREMENTS.md
+- v1 scope: [N] requirements across [M] categories
+- v2 scope: [X] requirements deferred
+- Out of scope: [Y] requirements excluded
+
+---
+
+## ▶ Next Up
+
+**Create roadmap** — phases mapped to requirements
+
+`/ms:create-roadmap`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] PROJECT.md validated
+- [ ] Features gathered (from research OR questioning)
+- [ ] User scoped each category (v1/v2/out of scope)
+- [ ] User had opportunity to add missing requirements
+- [ ] REQUIREMENTS.md created with checkable list
+- [ ] Requirements committed to git
+- [ ] User knows next step (create-roadmap)
+</success_criteria>

package/commands/ms/design-phase.md

@@ -0,0 +1,341 @@
+---
+name: ms:design-phase
+description: Create visual/UX design specifications before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<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.
+
+**Why subagent:** Design requires focused attention with quality-forcing patterns. Fresh 200k context for design generation. Main context reserved for user refinement conversation.
+
+**When to use:**
+- UI-heavy phases with significant new interface work
+- Novel flows/components not deducible from existing patterns
+- Features requiring careful UX consideration
+- Cross-platform work needing coordinated design
+
+**Not needed for:**
+- Backend-only phases
+- Minor UI tweaks using existing patterns
+- Phases where established patterns suffice
+</objective>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Check for existing design:
+```bash
+ls .planning/phases/${PHASE}-*/*DESIGN.md 2>/dev/null
+```
+</context>
+
+<process>
+
+## 1. Parse and Validate Phase
+
+```bash
+# Extract phase number from arguments
+PHASE_ARG="$ARGUMENTS"
+
+# Validate phase exists in roadmap
+grep -A5 "Phase ${PHASE_ARG}:" .planning/ROADMAP.md 2>/dev/null
+```
+
+**If not found:** Error and exit with message: "Phase ${PHASE_ARG} not found in ROADMAP.md"
+
+**If found:** Extract phase number, name, description. Store for later use.
+
+## 2. Check Existing Design
+
+```bash
+# Check for existing DESIGN.md
+PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
+ls "${PHASE_DIR}"/*-DESIGN.md 2>/dev/null
+```
+
+**If exists:** Use AskUserQuestion to offer:
+1. **Update design** — Spawn designer with existing design as context
+2. **View existing** — Display current DESIGN.md
+3. **Skip** — Proceed to research/planning without changes
+
+Wait for response and act accordingly.
+
+**If doesn't exist:** Continue to gather context.
+
+## 3. Gather Context Chain
+
+Load context in order of priority:
+
+**3a. Mandatory context:**
+
+```bash
+# Load PROJECT.md for product context
+cat .planning/PROJECT.md 2>/dev/null
+
+# Load ROADMAP.md for phase requirements
+grep -A30 "Phase ${PHASE_ARG}:" .planning/ROADMAP.md 2>/dev/null
+```
+
+Extract from PROJECT.md:
+- What This Is (product type)
+- Core Value (design must serve this)
+- Context (target audience)
+- Constraints (platform, technical limits)
+
+Extract from ROADMAP.md:
+- Phase goal
+- Success criteria
+- Requirements mapped
+
+**3b. Optional context - CONTEXT.md (from discuss-phase):**
+
+```bash
+cat .planning/phases/${PHASE_ARG}-*/${PHASE_ARG}-CONTEXT.md 2>/dev/null
+```
+
+If exists, extract:
+- How This Should Work (vision)
+- What Must Be Nailed (essentials)
+- Specific Ideas (references to products)
+
+**3c. Optional context - implement-ui skill:**
+
+```bash
+# Check for implement-ui skill
+ls .claude/skills/*implement-ui* 2>/dev/null
+```
+
+If exists, load it as the authoritative source of existing patterns.
+
+**3d. Optional context - codebase analysis:**
+
+```bash
+# Platform detection
+if [ -f "package.json" ]; then
+  echo "Platform: Web (package.json found)"
+  grep -E "react|vue|angular|svelte" package.json 2>/dev/null | head -5
+fi
+
+if [ -f "pubspec.yaml" ]; then
+  echo "Platform: Flutter (pubspec.yaml found)"
+fi
+
+# Find existing component/theme files
+find src -name "*.tsx" -o -name "*.dart" 2>/dev/null | head -20
+grep -r "colors\|theme\|spacing" src/ --include="*.ts" --include="*.dart" 2>/dev/null | head -10
+```
+
+Document discovered patterns for the designer.
+
+## 4. Adaptive Q&A (If Gaps Exist)
+
+Assess context coverage:
+- Can platform be inferred? (from codebase or PROJECT.md)
+- Can visual style be inferred? (from implement-ui or codebase)
+- Can design priorities be inferred? (from CONTEXT.md or phase requirements)
+
+**If everything can be inferred:** Skip to step 5.
+
+**If gaps exist:** Use AskUserQuestion with targeted questions.
+
+Most valuable question (if reference products not in CONTEXT.md):
+> "Are there apps or sites whose design you'd like this to feel like?"
+
+Other potential questions (only if genuine gaps):
+- Visual direction (if no existing aesthetic)
+- Density preference (if not inferrable)
+- Platform priority (if multi-platform)
+
+**Decision gate after Q&A:**
+Use AskUserQuestion to confirm:
+1. **Create DESIGN.md** — Proceed to spawn designer
+2. **Ask more questions** — Continue gathering context
+3. **Add context** — Let user provide additional information
+
+## 5. Spawn ms-designer Agent
+
+Assemble the design prompt from gathered context:
+
+```markdown
+<design_context>
+Product: [From PROJECT.md - What This Is]
+Platform: [Inferred from codebase or PROJECT.md constraints]
+Phase: [N]: [Phase name from ROADMAP.md]
+
+Target audience:
+[From PROJECT.md - Context section]
+
+Core value this design must serve:
+[From PROJECT.md - Core Value section]
+
+Technical constraints:
+[From PROJECT.md - Constraints section]
+</design_context>
+
+<phase_requirements>
+Goal: [From ROADMAP.md phase entry]
+
+Success criteria:
+[From ROADMAP.md - what this phase must achieve]
+
+Requirements mapped:
+[From ROADMAP.md - specific features/behaviors]
+</phase_requirements>
+
+<user_vision>
+[If CONTEXT.md exists:]
+
+How this should work:
+[From CONTEXT.md - How This Should Work section]
+
+What must be nailed:
+[From CONTEXT.md - What Must Be Nailed section]
+
+Reference products:
+[From CONTEXT.md - Specific Ideas section, or from Q&A]
+
+[If CONTEXT.md doesn't exist:]
+
+Vision inferred from phase requirements and PROJECT.md context.
+Reference products: [From Q&A if asked, or "None specified"]
+</user_vision>
+
+<existing_aesthetic>
+[If implement-ui skill exists:]
+
+Authoritative patterns from implement-ui skill:
+- Color palette: [exact values]
+- Typography: [font families, sizes]
+- Spacing system: [scale values]
+- Component library: [named components]
+
+[If no skill, from codebase analysis:]
+
+Discovered patterns from codebase:
+- Colors found: [hex values from theme/styles]
+- Components found: [existing component names]
+- Layout patterns: [grid systems, spacing used]
+
+[If greenfield:]
+
+No existing aesthetic. Design fresh with platform conventions.
+</existing_aesthetic>
+
+<quality_expectation>
+Commercial benchmark: This design must look like a [benchmark] with intentional decisions, not defaults.
+
+Pre-emptive criticism: Assume the user will say "This looks like generic AI output." Generate something that proves them wrong.
+
+Accountability check: Could you show this design to a professional UI designer and claim it as skilled work? If not, it's not done.
+</quality_expectation>
+
+<output_specification>
+Generate: DESIGN.md following template structure
+
+Location: .planning/phases/{phase}-{slug}/{phase}-DESIGN.md
+
+Required sections:
+1. Visual Identity (philosophy, direction, inspiration)
+2. Screen Layouts (ASCII wireframes with dimensions)
+3. Component Specifications (visual, states, content)
+4. UX Flows (entry, steps, decisions, completion, errors)
+5. Design System Decisions (colors, typography, spacing with rationale)
+6. Platform-Specific Notes (responsive, touch targets, accessibility)
+7. Verification Criteria (observable behaviors proving correct implementation)
+</output_specification>
+```
+
+Spawn the agent:
+
+```
+Task(
+  prompt=assembled_design_prompt,
+  subagent_type="ms-designer",
+  description="Design Phase {phase}"
+)
+```
+
+## 6. Handle Agent Return
+
+**`## DESIGN COMPLETE`:**
+
+Commit the design file:
+
+```bash
+git add .planning/phases/${PHASE_ARG}-*/*-DESIGN.md
+git commit -m "docs: create design for phase ${PHASE_ARG}"
+```
+
+Display summary from agent response:
+- Platform designed for
+- Aesthetic source used
+- Screens designed
+- Key design decisions
+
+Then offer next steps:
+1. **Proceed to research** — `/ms:research-phase {phase}`
+2. **Refine design** — Discuss changes conversationally
+3. **View full design** — Display DESIGN.md
+4. **Done for now** — Exit
+
+**`## DESIGN NEEDS CLARIFICATION`:**
+
+Present the question to user. Get response. Spawn continuation with the clarification.
+
+## 7. Conversational Refinement
+
+After initial generation, if user wants to refine:
+
+- Read DESIGN.md directly
+- Discuss changes conversationally
+- Edit DESIGN.md directly (no subagent needed for small changes)
+- For major redesign, spawn ms-designer again with structured feedback
+
+**Refinement principles:**
+- Direct edits — Edit DESIGN.md directly, don't regenerate
+- Preserve decisions — Changes are incremental, not wholesale replacement
+- User controls pace — User decides when design is "done"
+
+**For major redesigns (multiple aspects changing):**
+
+Use the iteration template from `~/.claude/mindsystem/templates/design-iteration.md`:
+
+1. Capture feedback using the structured format:
+   - What worked well (KEEP)
+   - What needs improvement (FIX)
+   - New requirements (ADD)
+   - Primary focus for this iteration
+
+2. Spawn ms-designer with iteration context:
+   - Include `<previous_design>` with relevant sections
+   - Include `<feedback_on_previous>` with structured feedback
+   - Include `<specific_focus>` identifying the ONE thing
+   - Include `<constraints>` noting what must NOT change
+
+3. After iteration completes:
+   - Verify "what worked well" was preserved
+   - Verify "what needs improvement" was addressed
+   - Update design version in DESIGN.md frontmatter
+
+</process>
+
+<success_criteria>
+- [ ] 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
+- [ ] Codebase analyzed for existing patterns
+- [ ] Adaptive Q&A completed if gaps existed
+- [ ] ms-designer spawned with quality-forcing patterns
+- [ ] DESIGN.md created with all 7 sections
+- [ ] DESIGN.md committed
+- [ ] User informed of refinement options and next steps
+</success_criteria>

package/commands/ms/discuss-milestone.md

@@ -0,0 +1,48 @@
+---
+name: ms:discuss-milestone
+description: Gather context for next milestone through adaptive questioning
+---
+
+<objective>
+Help you figure out what to build in the next milestone through collaborative thinking.
+
+Purpose: After completing a milestone, explore what features you want to add, improve, or fix. Features first — scope and phases derive from what you want to build.
+Output: Context gathered, then routes to /ms:new-milestone
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/principles.md
+@~/.claude/mindsystem/workflows/discuss-milestone.md
+</execution_context>
+
+<context>
+**Load project state first:**
+@.planning/STATE.md
+
+**Load project:**
+@.planning/PROJECT.md
+
+**Load milestones (if exists):**
+@.planning/MILESTONES.md
+</context>
+
+<process>
+1. Verify previous milestone complete (or acknowledge active milestone)
+2. Present context from previous milestone (accomplishments, phase count)
+3. Follow discuss-milestone.md workflow with **ALL questions using AskUserQuestion**:
+   - Use AskUserQuestion: "What do you want to add, improve, or fix?" with feature categories
+   - Use AskUserQuestion to dig into features they mention
+   - Use AskUserQuestion to help them articulate what matters most
+   - Use AskUserQuestion for decision gate (ready / ask more / let me add context)
+4. Hand off to /ms:new-milestone with gathered context
+
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+</process>
+
+<success_criteria>
+
+- Project state loaded and presented
+- Previous milestone context summarized
+- Milestone scope gathered through adaptive questioning
+- Context handed off to /ms:new-milestone
+  </success_criteria>