mindsystem-cc 3.0.0

package/commands/ms/research-phase.md

@@ -0,0 +1,175 @@
+---
+name: ms:research-phase
+description: Research how to implement a phase before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+---
+
+<objective>
+Research how to implement a phase. Spawns ms-researcher agent with phase context.
+
+**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
+
+**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
+</objective>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Check for existing research:
+```bash
+ls .planning/phases/${PHASE}-*/*RESEARCH.md 2>/dev/null
+```
+</context>
+
+<process>
+
+## 1. Parse and Validate Phase
+
+```bash
+grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
+```
+
+**If not found:** Error and exit. **If found:** Extract phase number, name, description.
+
+## 2. Check Existing Research
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+```
+
+**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
+
+**If doesn't exist:** Continue.
+
+## 3. Gather Phase Context
+
+```bash
+grep -A20 "Phase ${PHASE}:" .planning/ROADMAP.md
+cat .planning/REQUIREMENTS.md 2>/dev/null
+cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
+cat .planning/phases/${PHASE}-*/${PHASE}-DESIGN.md 2>/dev/null
+grep -A30 "### Decisions Made" .planning/STATE.md 2>/dev/null
+```
+
+Present summary with phase description, requirements, prior decisions.
+
+**If DESIGN.md exists:** Research should address:
+- Libraries needed for specified interactions (animations, gestures, charts)
+- Technical feasibility of design requirements
+- Platform-specific implementation approaches
+- Component libraries that match the design system
+
+## 4. Spawn ms-researcher Agent
+
+Research modes: ecosystem (default), feasibility, implementation, comparison.
+
+```markdown
+<research_type>
+Phase Research — investigating HOW to implement a specific phase well.
+</research_type>
+
+<key_insight>
+The question is NOT "which library should I use?"
+
+The question is: "What do I not know that I don't know?"
+
+For this phase, discover:
+- What's the established architecture pattern?
+- What libraries form the standard stack?
+- What problems do people commonly hit?
+- What's SOTA vs what Claude's training thinks is SOTA?
+- What should NOT be hand-rolled?
+</key_insight>
+
+<objective>
+Research implementation approach for Phase {phase_number}: {phase_name}
+Mode: ecosystem
+</objective>
+
+<context>
+**Phase description:** {phase_description}
+**Requirements:** {requirements_list}
+**Prior decisions:** {decisions_if_any}
+**Phase context:** {context_md_content}
+**Design specs:** {design_md_content_if_exists}
+</context>
+
+<downstream_consumer>
+Your RESEARCH.md will be loaded by `/ms:plan-phase` which uses specific sections:
+- `## Standard Stack` → Plans use these libraries
+- `## Architecture Patterns` → Task structure follows these
+- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
+- `## Common Pitfalls` → Verification steps check for these
+- `## Code Examples` → Task actions reference these patterns
+
+Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
+</downstream_consumer>
+
+<quality_gate>
+Before declaring complete, verify:
+- [ ] All domains investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources for critical claims
+- [ ] Confidence levels assigned honestly
+- [ ] Section names match what plan-phase expects
+</quality_gate>
+
+<output>
+Write to: .planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
+</output>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="ms-researcher",
+  description="Research Phase {phase}"
+)
+```
+
+## 5. Handle Agent Return
+
+**`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
+
+**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
+
+**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
+
+## 6. Spawn Continuation Agent
+
+```markdown
+<objective>
+Continue research for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+Research file: @.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="ms-researcher",
+  description="Continue research Phase {phase}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Existing research checked
+- [ ] ms-researcher spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] User knows next steps
+</success_criteria>

package/commands/ms/research-project.md

@@ -0,0 +1,339 @@
+---
+name: ms:research-project
+description: Research domain ecosystem before creating roadmap
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Research domain ecosystem. Spawns 4 parallel ms-researcher agents for comprehensive coverage.
+
+**Orchestrator role:** Analyze project, generate research questions, spawn 4 parallel agents, synthesize SUMMARY.md.
+
+**Why subagents:** Research burns context fast. Fresh 200k context per domain. Main context stays lean.
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.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/ROADMAP.md ] && echo "WARNING: ROADMAP.md exists. Research is typically done before roadmap."
+[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
+```
+
+## 2. Handle Existing Research
+
+**If RESEARCH_EXISTS:** Use AskUserQuestion (View existing / Replace / Cancel)
+
+## 3. Analyze Project
+
+Read PROJECT.md, extract domain/stack/core value/constraints. Present for approval:
+```
+Domain analysis:
+- Type: [domain]
+- Stack: [stated or TBD]
+- Core: [core value]
+Does this look right? (yes / adjust)
+```
+
+## 4. Generate Research Questions
+
+| Dimension | Question |
+|-----------|----------|
+| Stack | "What's the standard 2026 stack for [domain]?" |
+| Features | "What features do [domain] products have?" |
+| Architecture | "How are [domain] systems structured?" |
+| Pitfalls | "What do [domain] projects get wrong?" |
+
+Present for approval.
+
+## 5. Spawn Research Agents
+
+```bash
+mkdir -p .planning/research
+```
+
+**Determine milestone context:**
+- If no "Validated" requirements in REQUIREMENTS.md → Greenfield (v1.0)
+- If "Validated" requirements exist → Subsequent milestone (v1.1+)
+
+Spawn all 4 in parallel with rich context:
+
+```
+Task(prompt="
+<research_type>
+Project Research — Stack dimension for [domain].
+</research_type>
+
+<milestone_context>
+{greenfield OR subsequent}
+
+**Greenfield (v1.0):**
+Research the standard stack for building [domain] from scratch. Full ecosystem investigation.
+
+**Subsequent (v1.1+):**
+Research what's needed to add [target features] to an existing [domain] app.
+
+IMPORTANT for subsequent milestones:
+- DON'T re-research the existing system (validated requirements already work)
+- DON'T question established stack choices (they're proven)
+- DO research new libraries/patterns needed for [target features] specifically
+- DO investigate how [target features] integrate with the existing architecture
+- DO surface any compatibility concerns with current stack
+</milestone_context>
+
+<question>
+[stack question from step 4]
+</question>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<downstream_consumer>
+Your STACK.md feeds into /ms:create-roadmap. Be prescriptive:
+- Specific libraries with versions
+- Clear rationale for each choice
+- What NOT to use and why
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Versions are current (not Claude's training data)
+- [ ] Rationale explains WHY, not just WHAT
+- [ ] Confidence levels assigned
+</quality_gate>
+
+<output>
+Write to: .planning/research/STACK.md
+Use template: ~/.claude/mindsystem/templates/research-project/STACK.md
+</output>
+", subagent_type="ms-researcher", description="Stack research")
+
+Task(prompt="
+<research_type>
+Project Research — Features dimension for [domain].
+</research_type>
+
+<milestone_context>
+{greenfield OR subsequent}
+
+**Greenfield (v1.0):**
+What features do [domain] products have? What's table stakes vs differentiating?
+
+**Subsequent (v1.1+):**
+How do [target features] typically work? What's expected behavior?
+
+IMPORTANT for subsequent milestones:
+- Focus ONLY on [target features] - the new capabilities being added
+- DON'T list features the system already has (see Validated requirements)
+- DO research user expectations for [target features] specifically
+- DO identify table stakes vs differentiators within [target features] scope
+</milestone_context>
+
+<question>
+[features question from step 4]
+</question>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<downstream_consumer>
+Your FEATURES.md feeds into /ms:define-requirements. Categorize clearly:
+- Table stakes (must have or users leave)
+- Differentiators (competitive advantage)
+- Anti-features (things to deliberately NOT build)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Categories are clear
+- [ ] Complexity noted for each
+- [ ] Dependencies between features identified
+</quality_gate>
+
+<output>
+Write to: .planning/research/FEATURES.md
+Use template: ~/.claude/mindsystem/templates/research-project/FEATURES.md
+</output>
+", subagent_type="ms-researcher", description="Features research")
+
+Task(prompt="
+<research_type>
+Project Research — Architecture dimension for [domain].
+</research_type>
+
+<milestone_context>
+{greenfield OR subsequent}
+
+**Greenfield (v1.0):**
+How are [domain] systems typically structured? What are major components?
+
+**Subsequent (v1.1+):**
+How do [target features] integrate with existing [domain] architecture?
+
+IMPORTANT for subsequent milestones:
+- The existing architecture is KNOWN (from previous milestones)
+- Research how [target features] should connect to existing components
+- Identify which existing components need modification vs new components needed
+- Surface any architectural concerns (scaling, coupling, migration)
+</milestone_context>
+
+<question>
+[architecture question from step 4]
+</question>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<downstream_consumer>
+Your ARCHITECTURE.md informs phase structure in roadmap. Include:
+- Component boundaries (what talks to what)
+- Data flow (how information moves)
+- Suggested build order (dependencies between components)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Components clearly defined
+- [ ] Boundaries explicit
+- [ ] Build order implications noted
+</quality_gate>
+
+<output>
+Write to: .planning/research/ARCHITECTURE.md
+Use template: ~/.claude/mindsystem/templates/research-project/ARCHITECTURE.md
+</output>
+", subagent_type="ms-researcher", description="Architecture research")
+
+Task(prompt="
+<research_type>
+Project Research — Pitfalls dimension for [domain].
+</research_type>
+
+<milestone_context>
+{greenfield OR subsequent}
+
+**Greenfield (v1.0):**
+What do [domain] projects commonly get wrong? Critical mistakes?
+
+**Subsequent (v1.1+):**
+What are common mistakes when adding [target features] to [domain]?
+
+IMPORTANT for subsequent milestones:
+- Focus on integration pitfalls, not greenfield mistakes
+- Research upgrade/migration pitfalls (existing users, data migration)
+- Identify feature interaction bugs (new features breaking existing ones)
+- Surface performance concerns when [target features] are added to existing load
+</milestone_context>
+
+<question>
+[pitfalls question from step 4]
+</question>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<downstream_consumer>
+Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
+- Warning signs (how to detect early)
+- Prevention strategy (how to avoid)
+- Which phase should address it
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Pitfalls are specific, not generic
+- [ ] Prevention is actionable
+- [ ] Phase mapping included
+</quality_gate>
+
+<output>
+Write to: .planning/research/PITFALLS.md
+Use template: ~/.claude/mindsystem/templates/research-project/PITFALLS.md
+</output>
+", subagent_type="ms-researcher", description="Pitfalls research")
+```
+
+**Announce:** "Spawning 4 research agents... may take 2-3 minutes."
+
+## 6. Wait for Completion and Synthesize
+
+After all 4 agents return:
+
+```bash
+# Verify all research files exist
+ls .planning/research/STACK.md .planning/research/FEATURES.md \
+   .planning/research/ARCHITECTURE.md .planning/research/PITFALLS.md
+```
+
+**If any missing:** Report which agent failed, offer to retry.
+
+**If all present:** Spawn synthesizer:
+
+```
+Task(
+  prompt="
+Synthesize research outputs into SUMMARY.md.
+
+Read all 4 files in .planning/research/:
+- STACK.md
+- FEATURES.md
+- ARCHITECTURE.md
+- PITFALLS.md
+
+Create SUMMARY.md with:
+- Executive summary (2-3 paragraphs)
+- Key findings from each file
+- Roadmap implications (suggested phase structure)
+- Confidence assessment
+- Gaps to address
+
+Then commit ALL research files together:
+git add .planning/research/
+git commit -m 'docs: complete [domain] project research'
+",
+  subagent_type="ms-research-synthesizer",
+  description="Synthesize research"
+)
+```
+
+## 7. Present Results
+
+```
+Research complete:
+
+Files: SUMMARY.md, STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md
+
+Key findings:
+- Stack: [one-liner]
+- Architecture: [one-liner]
+- Critical pitfall: [one-liner]
+
+---
+## > Next Up
+**Define requirements** - `/ms:define-requirements`
+<sub>`/clear` first</sub>
+---
+```
+
+</process>
+
+<success_criteria>
+- [ ] PROJECT.md validated
+- [ ] Domain identified and approved
+- [ ] 4 ms-researcher agents spawned in parallel
+- [ ] All 4 research files created (STACK, FEATURES, ARCHITECTURE, PITFALLS)
+- [ ] ms-research-synthesizer spawned to create SUMMARY.md
+- [ ] All research files committed atomically by synthesizer
+</success_criteria>

package/commands/ms/resume-work.md

@@ -0,0 +1,40 @@
+---
+name: ms:resume-work
+description: Resume work from previous session with full context restoration
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+  - SlashCommand
+---
+
+<objective>
+Restore complete project context and resume work seamlessly from previous session.
+
+Routes to the resume-project workflow which handles:
+
+- STATE.md loading (or reconstruction if missing)
+- Checkpoint detection (.continue-here files)
+- Incomplete work detection (PLAN without SUMMARY)
+- Status presentation
+- Context-aware next action routing
+  </objective>
+
+<execution_context>
+@~/.claude/mindsystem/workflows/resume-project.md
+</execution_context>
+
+<process>
+**Follow the resume-project workflow** from `@~/.claude/mindsystem/workflows/resume-project.md`.
+
+The workflow handles all resumption logic including:
+
+1. Project existence verification
+2. STATE.md loading or reconstruction
+3. Checkpoint and incomplete work detection
+4. Visual status presentation
+5. Context-aware option offering (checks CONTEXT.md before suggesting plan vs discuss)
+6. Routing to appropriate next command
+7. Session continuity updates
+   </process>