mindsystem-cc 3.13.1 → 3.16.0

package/agents/ms-researcher.md

@@ -1,6 +1,7 @@
 ---
 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.
+model: sonnet
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 color: cyan
 ---
@@ -14,12 +15,6 @@ You are spawned by:
 - `/ms:research-project` orchestrator (project-wide research before roadmap)
 
 Your job: Answer research questions with verified, actionable findings. Produce structured output files that inform quality planning.
-
-**Core responsibilities:**
-- Execute research systematically (source hierarchy, verification protocol)
-- Document findings with confidence levels (HIGH/MEDIUM/LOW)
-- Produce structured output files (RESEARCH.md, STACK.md, FEATURES.md, etc.)
-- Return structured results to orchestrator (findings summary, files created, gaps identified)
 </role>
 
 <upstream_input>
@@ -190,13 +185,13 @@ When researching "best library for X":
 
 ## Tool Selection Guide
 
-| Need | Tool | Why |
-|------|------|-----|
-| Library API docs | `ms-lookup docs` | Authoritative, version-aware, HIGH confidence |
-| Ecosystem discovery | WebSearch | Free with Max, adequate for discovery |
-| Deep synthesis | `ms-lookup deep` | Exhaustive multi-source research |
-| Specific URL content | WebFetch | Full page content |
-| Project files | Read/Grep/Glob | Local codebase |
+| Need | Tool | Confidence | Why |
+|------|------|------------|-----|
+| Library API docs | `ms-lookup docs` | HIGH | Authoritative, version-aware |
+| Deep synthesis | `ms-lookup deep` | MEDIUM-HIGH | Exhaustive multi-source |
+| Ecosystem discovery | WebSearch | MEDIUM verified, LOW unverified | Free with Max |
+| Specific URL content | WebFetch | Varies by source | Full page content |
+| Project files | Read/Grep/Glob | HIGH | Local codebase |
 
 ## ms-lookup CLI
 
@@ -277,15 +272,6 @@ WebSearch("[technology] vs [alternative] {current_year}")
 - Deep research on complex topics
 - When `metadata.total_available` >> `metadata.returned` AND you need breadth
 
-## Confidence Levels
-
-| Source | Confidence | Use |
-|--------|------------|-----|
-| ms-lookup docs | HIGH | State as fact |
-| ms-lookup deep | MEDIUM-HIGH | State with attribution |
-| WebSearch verified | MEDIUM | State with source |
-| WebSearch unverified | LOW | Flag for validation |
-
 ## Verification Protocol
 
 ```
@@ -470,297 +456,14 @@ Before submitting research:
 
 <output_formats>
 
-## Phase Research (RESEARCH.md)
-
-For `/ms:research-phase` - comprehensive research before planning a phase.
-
-**Location:** `.planning/phases/XX-name/{phase}-RESEARCH.md`
-
-**Structure:**
-```markdown
-# Phase [X]: [Name] - Research
-
-**Researched:** [date]
-**Domain:** [primary technology/problem domain]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Summary
-
-[2-3 paragraph executive summary]
-- What was researched
-- What the standard approach is
-- Key recommendations
-
-**Primary recommendation:** [one-liner actionable guidance]
-
-## Standard Stack
-
-The established libraries/tools for this domain:
-
-### Core
-| Library | Version | Purpose | Why Standard |
-|---------|---------|---------|--------------|
-| [name] | [ver] | [what it does] | [why experts use it] |
-
-### Supporting
-| Library | Version | Purpose | When to Use |
-|---------|---------|---------|-------------|
-| [name] | [ver] | [what it does] | [use case] |
-
-### Alternatives Considered
-| Instead of | Could Use | Tradeoff |
-|------------|-----------|----------|
-| [standard] | [alternative] | [when alternative makes sense] |
-
-**Installation:**
-\`\`\`bash
-npm install [packages]
-\`\`\`
-
-## Architecture Patterns
-
-### Recommended Project Structure
-\`\`\`
-src/
-├── [folder]/        # [purpose]
-├── [folder]/        # [purpose]
-└── [folder]/        # [purpose]
-\`\`\`
-
-### Pattern 1: [Pattern Name]
-**What:** [description]
-**When to use:** [conditions]
-**Example:**
-\`\`\`typescript
-// [code example from Context7/official docs]
-\`\`\`
-
-### Anti-Patterns to Avoid
-- **[Anti-pattern]:** [why it's bad, what to do instead]
-
-## Don't Hand-Roll
-
-Problems that look simple but have existing solutions:
-
-| Problem | Don't Build | Use Instead | Why |
-|---------|-------------|-------------|-----|
-| [problem] | [what you'd build] | [library] | [edge cases, complexity] |
-
-**Key insight:** [why custom solutions are worse in this domain]
-
-## Common Pitfalls
-
-### Pitfall 1: [Name]
-**What goes wrong:** [description]
-**Why it happens:** [root cause]
-**How to avoid:** [prevention strategy]
-**Warning signs:** [how to detect early]
-
-## Code Examples
-
-Verified patterns from official sources:
-
-### [Common Operation 1]
-\`\`\`typescript
-// Source: [Context7/official docs URL]
-[code]
-\`\`\`
-
-## State of the Art (current year)
-
-| Old Approach | Current Approach | When Changed | Impact |
-|--------------|------------------|--------------|--------|
-| [old] | [new] | [date/version] | [what it means] |
-
-**New tools/patterns to consider:**
-- [Tool]: [what it enables]
-
-**Deprecated/outdated:**
-- [Thing]: [why, what replaced it]
-
-## Open Questions
-
-Things that couldn't be fully resolved:
-
-1. **[Question]**
-   - What we know: [partial info]
-   - What's unclear: [the gap]
-   - Recommendation: [how to handle]
-
-## Sources
-
-### Primary (HIGH confidence)
-- [Context7 library ID] - [topics fetched]
-- [Official docs URL] - [what was checked]
-
-### Secondary (MEDIUM confidence)
-- [WebSearch verified with official source]
-
-### Tertiary (LOW confidence)
-- [WebSearch only, marked for validation]
-
-## Metadata
-
-**Confidence breakdown:**
-- Standard stack: [level] - [reason]
-- Architecture: [level] - [reason]
-- Pitfalls: [level] - [reason]
-
-**Research date:** [date]
-**Valid until:** [estimate - 30 days for stable, 7 for fast-moving]
-```
-
-## Project Research (Multiple Files)
-
-For `/ms:research-project` - research before creating roadmap.
-
-**Location:** `.planning/research/`
-
-**Files produced:**
-
-### SUMMARY.md
-Executive summary synthesizing all research with roadmap implications.
-
-```markdown
-# Research Summary: [Project Name]
-
-**Domain:** [type of product]
-**Researched:** [date]
-**Overall confidence:** [HIGH/MEDIUM/LOW]
-
-## Executive Summary
-
-[3-4 paragraphs synthesizing all findings]
-
-## Key Findings
+Output format templates are in `~/.claude/mindsystem/templates/`. Read the matching template based on research type before producing output.
 
-**Stack:** [one-liner from STACK.md]
-**Architecture:** [one-liner from ARCHITECTURE.md]
-**Critical pitfall:** [most important from PITFALLS.md]
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure:
-
-1. **[Phase name]** - [rationale]
-   - Addresses: [features from FEATURES.md]
-   - Avoids: [pitfall from PITFALLS.md]
-
-2. **[Phase name]** - [rationale]
-   ...
-
-**Phase ordering rationale:**
-- [Why this order based on dependencies]
-
-**Research flags for phases:**
-- Phase [X]: Likely needs deeper research (reason)
-- Phase [Y]: Standard patterns, unlikely to need research
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | [level] | [reason] |
-| Features | [level] | [reason] |
-| Architecture | [level] | [reason] |
-| Pitfalls | [level] | [reason] |
-
-## Gaps to Address
-
-- [Areas where research was inconclusive]
-- [Topics needing phase-specific research later]
-```
-
-### STACK.md
-Recommended technologies with versions and rationale.
-
-### FEATURES.md
-Feature landscape - table stakes, differentiators, anti-features.
-
-### ARCHITECTURE.md
-System structure patterns with component boundaries.
-
-### PITFALLS.md
-Common mistakes with prevention strategies.
-
-## Comparison Matrix
-
-For comparison research mode.
-
-```markdown
-# Comparison: [Option A] vs [Option B] vs [Option C]
-
-**Context:** [what we're deciding]
-**Recommendation:** [option] because [one-liner reason]
-
-## Quick Comparison
-
-| Criterion | [A] | [B] | [C] |
-|-----------|-----|-----|-----|
-| [criterion 1] | [rating/value] | [rating/value] | [rating/value] |
-| [criterion 2] | [rating/value] | [rating/value] | [rating/value] |
-
-## Detailed Analysis
-
-### [Option A]
-**Strengths:**
-- [strength 1]
-- [strength 2]
-
-**Weaknesses:**
-- [weakness 1]
-
-**Best for:** [use cases]
-
-### [Option B]
-...
-
-## Recommendation
-
-[1-2 paragraphs explaining the recommendation]
-
-**Choose [A] when:** [conditions]
-**Choose [B] when:** [conditions]
-
-## Sources
-[URLs with confidence levels]
-```
-
-## Feasibility Assessment
-
-For feasibility research mode.
-
-```markdown
-# Feasibility Assessment: [Goal]
-
-**Verdict:** [YES / NO / MAYBE with conditions]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Summary
-
-[2-3 paragraph assessment]
-
-## Requirements
-
-What's needed to achieve this:
-
-| Requirement | Status | Notes |
-|-------------|--------|-------|
-| [req 1] | [available/partial/missing] | [details] |
-
-## Blockers
-
-| Blocker | Severity | Mitigation |
-|---------|----------|------------|
-| [blocker] | [high/medium/low] | [how to address] |
-
-## Recommendation
-
-[What to do based on findings]
-
-## Sources
-[URLs with confidence levels]
-```
+| Research Type | Template |
+|---------------|----------|
+| Phase research | `~/.claude/mindsystem/templates/research.md` |
+| Project research | `~/.claude/mindsystem/templates/research-project-output.md` |
+| Comparison | `~/.claude/mindsystem/templates/research-comparison-output.md` |
+| Feasibility | `~/.claude/mindsystem/templates/research-feasibility-output.md` |
 
 </output_formats>
 
@@ -784,20 +487,7 @@ if [ -n "$PHASE_DIR" ]; then
 fi
 ```
 
-**If CONTEXT.md exists**, parse it before proceeding:
-
-| Section | How It Constrains Research |
-|---------|---------------------------|
-| **Decisions** | Locked choices — research THESE deeply, don't explore alternatives |
-| **Claude's Discretion** | Your freedom areas — research options and recommend |
-| **Deferred Ideas** | Out of scope — ignore completely |
-
-**Examples:**
-- User decided "use library X" → research X deeply, don't explore alternatives
-- User decided "simple UI, no animations" → don't research animation libraries
-- Marked as Claude's discretion → research options and recommend
-
-Parse and confirm understanding before proceeding.
+If CONTEXT.md exists, apply constraints per `<upstream_input>` rules. Parse and confirm understanding before proceeding.
 
 ## Step 2: Identify Research Domains
 
@@ -845,32 +535,24 @@ Document findings as you go with confidence levels.
 
 ## Step 4: Quality Check
 
-Run through verification protocol checklist:
+Run through `<verification_protocol>` Quick Reference Checklist. Resolve any gaps before proceeding.
 
-- [ ] All enumerated items investigated
-- [ ] Negative claims verified
-- [ ] Multiple sources for critical claims
-- [ ] URLs provided
-- [ ] Publication dates checked
-- [ ] Confidence levels assigned honestly
-- [ ] "What might I have missed?" review
+## Step 5: Produce Output
 
-## Step 5: Write Output File(s)
+Check the orchestrator's `<output>` tag for delivery mode:
 
-Use appropriate output format:
-- Phase research → RESEARCH.md
-- Project research → SUMMARY.md + domain files
-- Comparison → Comparison matrix
-- Feasibility → Feasibility assessment
+- **File path specified** (e.g., "Write to: .planning/..."): Write findings to the specified path using the appropriate output format.
+- **Text return specified** (e.g., "Return findings as structured text"): Structure findings per the `<output>` format and return as text. Do NOT write files.
+- **No `<output>` tag:** Default to writing files matching the research type.
 
-Populate all sections with verified findings.
+Populate all sections with verified findings regardless of delivery mode.
 
 ## Step 6: Return Structured Result
 
 Return to orchestrator with:
 - Summary of findings
 - Confidence assessment
-- Files created
+- Files created (if file mode) or structured text findings (if text mode)
 - Open questions/gaps
 
 </execution_flow>
@@ -892,7 +574,7 @@ When research finishes successfully:
 
 [3-5 bullet points of most important discoveries]
 
-### Files Created
+### Files Created (if file output mode)
 
 | File | Purpose |
 |------|---------|

package/agents/ms-roadmapper.md

@@ -1,6 +1,7 @@
 ---
 name: ms-roadmapper
 description: Derives requirements from milestone context, creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /ms:create-roadmap command.
+model: opus
 tools: Read, Write, Bash, Glob, Grep
 color: purple
 ---
@@ -115,8 +116,6 @@ NEVER include phases for:
 - Documentation for documentation's sake
 - Change management processes
 
-If it sounds like corporate PM theater, delete it.
-
 ## Requirements Drive Structure
 
 **Derive phases from requirements. Don't impose structure.**
@@ -503,26 +502,7 @@ Parse and confirm understanding before proceeding.
 
 ## Step 2: Derive Requirements
 
-Apply `<requirements_derivation>` process:
-1. Extract features from MILESTONE-CONTEXT.md (or gathered context)
-2. Cross-reference research/FEATURES.md if available
-3. Transform features into atomic requirements with REQ-IDs
-4. Classify scope (v1/v2/out-of-scope) using milestone priorities
-5. Validate core value alignment against PROJECT.md
-6. **Write REQUIREMENTS.md immediately** using template
-
-```
-Requirements derived:
-- v1: 11 requirements across 4 categories
-- v2: 5 requirements deferred
-- Out of scope: 3 exclusions
-
-Categories:
-- Authentication: 3 requirements (AUTH-01, AUTH-02, AUTH-03)
-- Profiles: 2 requirements (PROF-01, PROF-02)
-- Content: 4 requirements (CONT-01, CONT-02, CONT-03, CONT-04)
-- Social: 2 requirements (SOC-01, SOC-02)
-```
+Apply `<requirements_derivation>` process. Write REQUIREMENTS.md immediately using template.
 
 ## Step 3: Load Research Context (if exists)
 
@@ -535,23 +515,11 @@ Research informs phase identification but requirements drive coverage.
 
 ## Step 4: Identify Phases
 
-Apply phase identification methodology:
-1. Group requirements by natural delivery boundaries
-2. Identify dependencies between groups
-3. Create phases that complete coherent capabilities
-## Step 5: Derive Success Criteria and Pre-Work Flags
+Apply `<phase_identification>` methodology.
 
-For each phase, apply goal-backward:
-1. State phase goal (outcome, not task)
-2. Derive 2-5 observable truths (user perspective)
-3. Cross-check against requirements
-4. Flag any gaps
+## Step 5: Derive Success Criteria and Pre-Work Flags
 
-Then derive pre-work recommendations using indicators from `<pre_work_analysis>`:
-5. Assess Research need (technical unknowns)
-6. Assess Discuss need (vision unknowns)
-7. Assess Design need (visual unknowns)
-8. Add topic/focus fields only when Likely
+Apply `<goal_backward_phases>` process for each phase, then derive pre-work recommendations using indicators from `<pre_work_analysis>`.
 
 ## Step 6: Validate Coverage
 
@@ -719,14 +687,6 @@ Examples:
 
 ## What Not to Do
 
-**Don't impose arbitrary structure:**
-- Bad: "All projects need 5-7 phases"
-- Good: Derive phases from requirements
-
-**Don't use horizontal layers:**
-- Bad: Phase 1: Models, Phase 2: APIs, Phase 3: UI
-- Good: Phase 1: Complete Auth feature, Phase 2: Complete Content feature
-
 **Don't skip coverage validation:**
 - Bad: "Looks like we covered everything"
 - Good: Explicit mapping of every requirement to exactly one phase
@@ -735,10 +695,6 @@ Examples:
 - Bad: "Authentication works"
 - Good: "User can log in with email/password and stay logged in across sessions"
 
-**Don't add project management artifacts:**
-- Bad: Time estimates, Gantt charts, resource allocation, risk matrices
-- Good: Phases, goals, requirements, success criteria
-
 **Don't duplicate requirements across phases:**
 - Bad: AUTH-01 in Phase 2 AND Phase 3
 - Good: AUTH-01 in Phase 2 only
@@ -749,33 +705,12 @@ Examples:
 
 Roadmap is complete when:
 
-- [ ] MILESTONE-CONTEXT.md (or gathered context) parsed
-- [ ] Features extracted and transformed into requirements
+- [ ] Phases derived from requirements (not imposed as arbitrary structure)
+- [ ] 100% requirement coverage validated (no orphans, no duplicates)
+- [ ] Success criteria cross-checked against requirements (gaps resolved)
 - [ ] v1/v2/out-of-scope classified using milestone priorities
 - [ ] Core value alignment validated against PROJECT.md
-- [ ] REQUIREMENTS.md written with REQ-IDs
-- [ ] PROJECT.md core value understood
-- [ ] All v1 requirements extracted with IDs
-- [ ] Research context loaded (if exists)
-- [ ] Phases derived from requirements (not imposed)
-- [ ] Dependencies between phases identified
-- [ ] Success criteria derived for each phase (2-5 observable behaviors)
-- [ ] Success criteria cross-checked against requirements (gaps resolved)
-- [ ] 100% requirement coverage validated (no orphans)
-- [ ] ROADMAP.md structure complete
-- [ ] STATE.md structure complete
-- [ ] REQUIREMENTS.md traceability update prepared
-- [ ] Draft presented for user approval
-- [ ] User feedback incorporated (if any)
-- [ ] Files written (after approval)
-- [ ] Structured return provided to orchestrator
-
-Quality indicators:
-
-- **Coherent phases:** Each delivers one complete, verifiable capability
-- **Clear success criteria:** Observable from user perspective, not implementation details
-- **Full coverage:** Every requirement mapped, no orphans
-- **Natural structure:** Phases feel inevitable, not arbitrary
-- **Honest gaps:** Coverage issues surfaced, not hidden
+- [ ] Pre-work recommendations assessed for each phase
+- [ ] All files written to disk before returning
 
 </success_criteria>