mindsystem-cc 3.14.0 → 3.16.1

package/mindsystem/templates/research-comparison-output.md

@@ -0,0 +1,50 @@
+# Comparison Output Template
+
+Template for comparison research — side-by-side evaluation of alternatives.
+
+**Purpose:** Provide a structured comparison matrix with clear recommendation for technology/approach decisions.
+
+**Created by:** `ms-researcher` agent during comparison research mode
+
+---
+
+## File Template
+
+```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]
+```

package/mindsystem/templates/research-feasibility-output.md

@@ -0,0 +1,43 @@
+# Feasibility Assessment Output Template
+
+Template for feasibility research — can we actually do this?
+
+**Purpose:** Provide a clear yes/no/maybe verdict with evidence for technical feasibility decisions.
+
+**Created by:** `ms-researcher` agent during feasibility research mode
+
+---
+
+## File Template
+
+```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]
+```

package/mindsystem/templates/research-project-output.md

@@ -0,0 +1,81 @@
+# Project Research Output Template
+
+Template for `.planning/research/` files — research before creating roadmap.
+
+**Purpose:** Document ecosystem-level findings for a whole project, informing phase structure and technology choices.
+
+**Created by:** `ms-researcher` agent during `/ms:research-project`
+
+---
+
+## Output Files
+
+### 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
+
+**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.

package/mindsystem/templates/research-subagent-prompt.md

@@ -1,92 +1,208 @@
-# Research Subagent Prompt Template
+# Research Subagent Prompt Templates
 
-Template for spawning ms-researcher agent. The agent contains all research expertise - this template provides research context only.
+Templates for the 3 parallel agents spawned by `/ms:research-phase`. The orchestrator constructs prompts inline. These templates serve as reference documentation.
 
 ---
 
-## Template
+## Common Context (injected into all 3 agents)
 
-```markdown
-<objective>
-Research: {research_question}
+| Placeholder | Source |
+|-------------|--------|
+| `{existing_tech}` | Dependency file (pubspec.yaml / package.json / etc.) |
+| `{phase_description}` | ROADMAP.md phase entry |
+| `{requirements}` | REQUIREMENTS.md |
+| `{locked_decisions}` | CONTEXT.md + STATE.md decisions |
+| `{design_specs}` | DESIGN.md (if exists) |
+| `{mode}` | Research mode: ecosystem / feasibility / implementation / comparison |
+| `{framed_question}` | Mode + phase description combined into research question |
+| `{scan_hints}` | Keywords extracted from phase description |
 
-Mode: {research_mode}
-</objective>
+---
 
-<context>
-**Phase:** {phase_number} - {phase_name}
-**Description:** {phase_description}
+## Template 1: External Docs (ms-researcher)
 
-**Requirements:**
-{phase_requirements}
+**Focus:** Library documentation, APIs, verified code examples
+**Tools emphasized:** ms-lookup docs (Context7), ms-lookup deep (Perplexity), WebSearch, WebFetch
+**Returns:** Structured findings (not files)
 
-**Constraints:**
-{constraints_from_state}
+```markdown
+<research_type>
+Phase Research — External Documentation focus.
+</research_type>
+
+<focus>
+Library documentation, APIs, version-specific behavior, verified code examples.
+Use the ms-lookup CLI for library docs and deep research:
+  ~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh docs <library> '<query>'
+  ~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh deep '<query>'
+Use WebSearch for ecosystem discovery.
+Focus on finding authoritative, current documentation for the libraries and tools
+needed to implement this phase.
+</focus>
+
+<existing_tech>
+{existing_tech}
+</existing_tech>
 
-**Phase context (if available):**
-{context_md_content}
+<objective>
+Research external documentation for Phase {N}: {name}
+Mode: {mode}
+</objective>
+
+<context>
+{phase_description, requirements, locked_decisions, design_specs}
 </context>
 
+<downstream_consumer>
+Your findings feed into orchestrator synthesis -> RESEARCH.md sections:
+- Standard Stack (libraries, versions, install commands)
+- Architecture Patterns (library-recommended patterns)
+- Don't Hand-Roll (library solutions for common problems)
+- Code Examples (verified from official docs)
+- State of the Art (latest approaches, deprecated patterns)
+Be prescriptive. Specific versions. Verified code.
+</downstream_consumer>
+
 <output>
-Write research findings to: {output_path}
-Use RESEARCH.md template structure for phase research.
+Return findings as structured text. Do NOT write to filesystem.
+Format:
+## EXTERNAL DOCS FINDINGS
+### Recommended Libraries (name, version, purpose, install)
+### API Patterns & Code Examples (verified from docs)
+### Architecture Recommendations (from library docs)
+### Don't Hand-Roll (library solutions exist for these)
+### Version Constraints & Compatibility
+### Confidence (HIGH/MEDIUM/LOW per section with sources)
+Complete your built-in verification protocol and quality checklist before returning findings.
 </output>
 ```
 
 ---
 
-## Placeholders
+## Template 2: Codebase Patterns (ms-codebase-researcher)
+
+**Focus:** Existing patterns, learnings, established conventions
+**Tools emphasized:** Grep, Glob, Read
+**Returns:** Structured findings (not files)
+
+```markdown
+<objective>
+Analyze project codebase for patterns relevant to Phase {N}: {name}
+</objective>
+
+<research_question>
+{framed_question}
+</research_question>
+
+<phase_context>
+{phase_description, requirements, locked_decisions}
+</phase_context>
+
+<existing_tech>
+{existing_tech}
+</existing_tech>
 
-| Placeholder | Source | Example |
-|-------------|--------|---------|
-| `{research_question}` | Phase description | `How to implement 3D visualization` |
-| `{research_mode}` | Orchestrator sets | `ecosystem` |
-| `{phase_number}` | From roadmap | `5` |
-| `{phase_name}` | From roadmap | `3d-visualization` |
-| `{phase_description}` | From roadmap | `Add interactive 3D model viewer` |
-| `{phase_requirements}` | From REQUIREMENTS.md | `VIZ-01: Support GLB format` |
-| `{constraints_from_state}` | From STATE.md decisions | `Using React, not Vue` |
-| `{context_md_content}` | From CONTEXT.md | User's vision notes |
-| `{output_path}` | Generated | `.planning/phases/5-viz/5-RESEARCH.md` |
+<scan_hints>
+{scan_hints}
+</scan_hints>
+
+<quality>
+Complete your built-in success criteria checklist before returning findings.
+</quality>
+```
+
+The agent's built-in `<what_to_scan>` section handles the systematic scan checklist (dependency file, source patterns, codebase docs, learnings, summaries, debug resolutions, adhoc summaries). The prompt only needs to provide context.
 
 ---
 
-## Usage
+## Template 3: Best Practices (ms-researcher)
+
+**Focus:** Community consensus, pitfalls, SOTA
+**Tools emphasized:** ms-lookup deep (Perplexity), WebSearch
+**Returns:** Structured findings (not files)
+
+```markdown
+<research_type>
+Phase Research — Best Practices & Community Consensus focus.
+</research_type>
+
+<focus>
+Community consensus, common pitfalls, proven approaches, state of the art.
+Use the ms-lookup CLI for deep research on high-value questions:
+  ~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh deep '<query>'
+Use WebSearch for community articles, blog posts, Stack Overflow patterns.
+Focus on what practitioners recommend and what mistakes to avoid.
+</focus>
+
+<existing_tech>
+{existing_tech}
+</existing_tech>
 
-**From /ms:research-phase:**
-```python
-Task(
-  prompt=filled_template,
-  subagent_type="ms-researcher",
-  description="Research Phase {phase}"
-)
+<objective>
+Research best practices for Phase {N}: {name}
+Mode: {mode}
+</objective>
+
+<context>
+{phase_description, requirements, locked_decisions, design_specs}
+</context>
+
+<downstream_consumer>
+Your findings feed into orchestrator synthesis -> RESEARCH.md sections:
+- Common Pitfalls (community war stories, warning signs)
+- State of the Art (current vs deprecated approaches)
+- Architecture Patterns (industry patterns, not library-specific)
+- Don't Hand-Roll (community-known solved problems)
+- Alternatives Considered (why X over Y)
+Be prescriptive. Cite sources. Flag confidence levels.
+</downstream_consumer>
+
+<output>
+Return findings as structured text. Do NOT write to filesystem.
+Format:
+## BEST PRACTICES FINDINGS
+### Recommended Approaches (community consensus)
+### Common Pitfalls (what goes wrong, warning signs, prevention)
+### State of the Art (current vs deprecated, when things changed)
+### Alternative Approaches (what else exists, why not chosen)
+### Industry Patterns (architecture, testing, deployment)
+### Confidence (HIGH/MEDIUM/LOW per section with sources)
+Complete your built-in verification protocol and quality checklist before returning findings.
+</output>
 ```
 
 ---
 
-## Continuation
+## Continuation (for checkpoints)
 
-For checkpoints, spawn fresh agent with:
+If an agent returns a CHECKPOINT, spawn a fresh agent of the same type with:
+
+`{partial_findings}` = the checkpointed agent's full text response (inline content, not a file reference). The orchestrator captures this from the Task result and injects it directly.
 
 ```markdown
 <objective>
-Continue research for Phase {phase_number}: {phase_name}
+Continue research for Phase {N}: {name}
 </objective>
 
+<existing_tech>
+{existing_tech}
+</existing_tech>
+
+<phase_context>
+{phase_description, requirements, locked_decisions}
+</phase_context>
+
 <prior_state>
-Research file: @{output_path}
+Research findings so far:
+{partial_findings}
 </prior_state>
 
 <checkpoint_response>
 **Type:** {checkpoint_type}
 **Response:** {user_response}
 </checkpoint_response>
-
-<mode>
-Continue: {research_mode}
-</mode>
 ```
 
 ---
 
-**Note:** Research methodology, tool strategy (Context7 > Official > WebSearch), and verification protocols are baked into the ms-researcher agent. This template only passes context.
+**Note:** Research methodology, tool strategy (ms-lookup docs > Official > ms-lookup deep > WebSearch), verification protocols, and source confidence levels are baked into `ms-researcher`. Codebase scan methodology is baked into `ms-codebase-researcher`. These templates pass context only — and reinforce that built-in quality processes still apply.

package/mindsystem/templates/roadmap-milestone.md

@@ -0,0 +1,67 @@
+# Milestone-Grouped Roadmap Template
+
+Template for reorganizing `ROADMAP.md` after first milestone ships. Collapse completed milestones, expand current/future work.
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
+- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Plans**: 3 plans
+
+Plans:
+- [x] 01-01: [Brief description]
+- [x] 01-02: [Brief description]
+- [x] 01-03: [Brief description]
+
+[... remaining v1.0 phases ...]
+
+</details>
+
+### 🚧 v1.1 [Name] (In Progress)
+
+**Milestone Goal:** [What v1.1 delivers]
+
+#### Phase 5: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 4
+**Plans**: 2 plans
+
+Plans:
+- [ ] 05-01: [Brief description]
+- [ ] 05-02: [Brief description]
+
+[... remaining v1.1 phases ...]
+
+### 📋 v2.0 [Name] (Planned)
+
+**Milestone Goal:** [What v2.0 delivers]
+
+[... v2.0 phases ...]
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
+| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
+| 5. Security | v1.1 | 0/2 | Not started | - |
+```
+
+**Notes:**
+- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
+- Completed milestones collapsed in `<details>` for readability
+- Current/future milestones expanded
+- Continuous phase numbering (01-99)
+- Progress table includes milestone column

package/mindsystem/templates/roadmap.md

@@ -157,70 +157,6 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - `Deferred` - Pushed to later (with reason)
 </status_values>
 
-## Milestone-Grouped Roadmap (After v1.0 Ships)
+## Milestone-Grouped Roadmap
 
-After completing first milestone, reorganize with milestone groupings:
-
-```markdown
-# Roadmap: [Project Name]
-
-## Milestones
-
-- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
-- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
-- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
-
-## Phases
-
-<details>
-<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
-
-### Phase 1: [Name]
-**Goal**: [What this phase delivers]
-**Plans**: 3 plans
-
-Plans:
-- [x] 01-01: [Brief description]
-- [x] 01-02: [Brief description]
-- [x] 01-03: [Brief description]
-
-[... remaining v1.0 phases ...]
-
-</details>
-
-### 🚧 v1.1 [Name] (In Progress)
-
-**Milestone Goal:** [What v1.1 delivers]
-
-#### Phase 5: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 4
-**Plans**: 2 plans
-
-Plans:
-- [ ] 05-01: [Brief description]
-- [ ] 05-02: [Brief description]
-
-[... remaining v1.1 phases ...]
-
-### 📋 v2.0 [Name] (Planned)
-
-**Milestone Goal:** [What v2.0 delivers]
-
-[... v2.0 phases ...]
-
-## Progress
-
-| Phase | Milestone | Plans Complete | Status | Completed |
-|-------|-----------|----------------|--------|-----------|
-| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
-| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
-| 5. Security | v1.1 | 0/2 | Not started | - |
-```
-
-**Notes:**
-- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
-- Completed milestones collapsed in `<details>` for readability
-- Current/future milestones expanded
-- Continuous phase numbering (01-99)
-- Progress table includes milestone column
+After first milestone ships, reorganize with milestone groupings. Read `templates/roadmap-milestone.md` for the milestone-grouped format.