mindsystem-cc 3.13.1 → 3.16.0

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.

package/mindsystem/workflows/complete-milestone.md

@@ -22,16 +22,16 @@ This is the ritual that separates "development" from "shipped."
 
 When a milestone completes, this workflow:
 
-1. Consolidates phase decisions into `.planning/milestones/v[X.Y]-DECISIONS.md`
-2. Cleans up phase artifacts (PLAN, CONTEXT, RESEARCH, DESIGN files deleted)
-3. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
-4. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
-5. Archives milestone context to `.planning/milestones/v[X.Y]-CONTEXT.md`
-6. Updates ROADMAP.md to replace milestone details with one-line summary
-7. Deletes REQUIREMENTS.md (fresh one created for next milestone)
-8. Extracts learnings into `.planning/LEARNINGS.md` (curated one-line patterns with source refs)
-9. Performs full PROJECT.md evolution review
-10. Routes to `/ms:new-milestone` for next milestone
+1. Cleans up raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER deleted)
+2. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
+3. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+4. Archives milestone context to `.planning/milestones/v[X.Y]-CONTEXT.md`
+5. Updates ROADMAP.md to replace milestone details with one-line summary
+6. Deletes REQUIREMENTS.md (fresh one created for next milestone)
+7. Performs full PROJECT.md evolution review
+8. Routes to `/ms:new-milestone` for next milestone
+
+Knowledge files in `.planning/knowledge/` persist across milestones (maintained by phase-level consolidation in execute-phase).
 
 **Context Efficiency:**
 
@@ -102,136 +102,25 @@ cat .planning/config.json 2>/dev/null
 Proceeding to stats gathering...
 ```
 
-Proceed directly to consolidate_decisions step.
+Proceed directly to cleanup_artifacts step.
 
 </step>
 
-<step name="consolidate_decisions">
-
-Consolidate phase decisions before archiving.
-
-**Spawn ms-consolidator agent:**
-
-```
-Task(
-  prompt="Consolidate decisions from milestone v[X.Y] [Name].
-
-Phase range: [PHASE_START]-[PHASE_END]
-Phase directories:
-- .planning/phases/01-foundation
-- .planning/phases/02-auth
-- [etc. for all phases in milestone]
-
-Extract decisions from PLAN, CONTEXT, RESEARCH, DESIGN files.
-Create v[X.Y]-DECISIONS.md in .planning/milestones/.
-Delete source files (preserve SUMMARY, VERIFICATION, UAT).",
-  subagent_type="ms-consolidator"
-)
-```
-
-**Wait for completion and verify:**
-
-```bash
-ls .planning/milestones/v[X.Y]-DECISIONS.md
-```
-
-**Present consolidation summary:**
-
-```
-✓ Decisions consolidated: [N] decisions in [M] categories
-✓ Source files cleaned: PLAN, CONTEXT, RESEARCH, DESIGN deleted
-✓ Preserved: SUMMARY, VERIFICATION, UAT files
-
-Report: .planning/milestones/v[X.Y]-DECISIONS.md
-```
-
-Continue to extract_learnings step.
-
-</step>
-
-<step name="extract_learnings">
-
-Extract reusable patterns from milestone artifacts into `.planning/LEARNINGS.md`.
-
-**Runs in main context** (not subagent) — curation requires judgment.
-
-**Reference:** `~/.claude/mindsystem/templates/learnings.md`
-
-**1. Scan source artifacts:**
+<step name="cleanup_artifacts">
 
-All sources are PRESERVED by ms-consolidator (only PLAN, CONTEXT, RESEARCH, DESIGN are deleted).
+Delete remaining raw artifacts from phase directories. Knowledge files are already current from phase-level consolidation in execute-phase — no consolidation or learnings extraction needed.
 
 ```bash
-# Debug resolutions — parse frontmatter for root_cause, resolution, subsystem, prevention
-ls .planning/debug/resolved/*.md 2>/dev/null
+~/.claude/mindsystem/scripts/cleanup-phase-artifacts.sh $PHASE_START $PHASE_END
 ```
 
-```bash
-# Adhoc summaries — parse frontmatter for learnings array, subsystem
-ls .planning/adhoc/*-SUMMARY.md 2>/dev/null
-```
+Knowledge files in `.planning/knowledge/` persist (they ARE the milestone's knowledge output).
 
-```bash
-# Phase summaries in milestone range — read Deviations/Issues sections, parse subsystem
-ls .planning/phases/{PHASE_START}*/{PHASE_START}*-SUMMARY.md .planning/phases/{PHASE_END}*/{PHASE_END}*-SUMMARY.md 2>/dev/null
-# (expand to all phases in milestone range)
-```
+**Present cleanup summary:**
 
-```bash
-# Completed todos — scan for reusable patterns (lower priority)
-ls .planning/todos/done/*.md 2>/dev/null
 ```
-
-For each source found, read frontmatter and relevant sections. Extract candidate learnings.
-
-**2. Curate entries:**
-
-- Select 4-8 entries max from candidates
-- Exclude: decisions (belong in DECISIONS.md), trivial fixes, one-time issues
-- Prefer prevention framing: "Always validate X before Y" over "We found a bug in X"
-- Deduplicate: if two sources surface the same pattern, keep the more prescriptive version
-
-**3. Group by subsystem:**
-
-```bash
-jq -r '.subsystems[]' .planning/config.json 2>/dev/null
-```
-
-Group entries under subsystem headings from config.json vocabulary.
-
-**4. Write to LEARNINGS.md:**
-
-Format per entry:
-```
-- **{Brief title}**: {Prescriptive action} → `{source_ref}`
-```
-
-If `.planning/LEARNINGS.md` does not exist (first milestone):
-- Create file with header from template
-- Add milestone section
-
-If `.planning/LEARNINGS.md` exists (subsequent milestone):
-- Prepend new milestone section after header (reverse chronological)
-- Update "Last updated" footer
-
-**5. Handle "no learnings" gracefully:**
-
-If no meaningful patterns found across all sources:
-- Do NOT create or modify LEARNINGS.md
-- Present informational message:
-  ```
-  ℹ No reusable learnings found for v[X.Y]
-    Sources scanned: [N] debug docs, [N] adhoc summaries, [N] phase summaries, [N] completed todos
-    Skipping LEARNINGS.md update
-  ```
-
-**6. Present summary:**
-
-```
-✓ Learnings extracted: [N] entries across [M] subsystems
-  - [subsystem1]: [count] entries
-  - [subsystem2]: [count] entries
-  Written to: .planning/LEARNINGS.md
+Raw artifacts cleaned from phase directories
+Knowledge files persist in .planning/knowledge/
 ```
 
 Continue to gather_stats step.
@@ -757,21 +646,17 @@ Commit milestone completion including archive files and deletions.
 
 ```bash
 # Stage archive files (new)
-git add .planning/milestones/v[X.Y]-DECISIONS.md
 git add .planning/milestones/v[X.Y]-ROADMAP.md
 git add .planning/milestones/v[X.Y]-REQUIREMENTS.md
 git add .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
 git add .planning/milestones/v[X.Y]-CONTEXT.md 2>/dev/null || true
 
-# Stage learnings (may not exist if no learnings found)
-git add .planning/LEARNINGS.md 2>/dev/null || true
-
 # Stage updated files
 git add .planning/MILESTONES.md
 git add .planning/PROJECT.md
 git add .planning/STATE.md
 
-# Stage deletions
+# Stage deletions (raw artifacts cleaned from phase directories)
 git add -u .planning/
 
 # Commit with descriptive message
@@ -779,13 +664,13 @@ git commit -m "$(cat <<'EOF'
 chore: complete v[X.Y] milestone
 
 Archived:
-- milestones/v[X.Y]-DECISIONS.md (consolidated decisions)
 - milestones/v[X.Y]-ROADMAP.md
 - milestones/v[X.Y]-REQUIREMENTS.md
 - milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
 
 Cleaned:
-- Phase PLAN, CONTEXT, RESEARCH, DESIGN files (consolidated into DECISIONS.md)
+- Raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
+- Knowledge files persist in .planning/knowledge/
 
 Deleted (fresh for next milestone):
 - ROADMAP.md
@@ -795,7 +680,6 @@ Updated:
 - MILESTONES.md (new entry)
 - PROJECT.md (requirements → Validated)
 - STATE.md (reset for next milestone)
-- LEARNINGS.md (curated patterns, if any found)
 
 Tagged: v[X.Y]
 EOF
@@ -886,9 +770,8 @@ If yes → milestone. If no → keep working.
 
 Milestone completion is successful when:
 
-- [ ] Decisions consolidated (milestones/v[X.Y]-DECISIONS.md created)
-- [ ] Phase artifacts cleaned (PLAN, CONTEXT, RESEARCH, DESIGN deleted)
-- [ ] Learnings extracted to .planning/LEARNINGS.md (or gracefully skipped if none found)
+- [ ] Raw artifacts cleaned from phase directories (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
+- [ ] Knowledge files persist in .planning/knowledge/
 - [ ] MILESTONES.md entry created with stats and accomplishments
 - [ ] PROJECT.md full evolution review completed
 - [ ] All shipped requirements moved to Validated in PROJECT.md

package/mindsystem/workflows/define-requirements.md

@@ -4,8 +4,6 @@ Define concrete, checkable requirements for v1.
 Two modes:
 1. **With research** — Transform FEATURES.md into scoped requirements
 2. **Without research** — Gather requirements through questioning
-
-This is the bridge between "what's possible/wanted" and "what we're committing to."
 </purpose>
 
 <required_reading>
@@ -318,13 +316,11 @@ Requirements defined:
 </quality_criteria>
 
 <success_criteria>
-- [ ] PROJECT.md core value extracted
-- [ ] Features gathered (from research OR conversation)
-- [ ] All categories presented to user
-- [ ] User scoped each category (v1/v2/out of scope)
-- [ ] User had opportunity to add requirements
 - [ ] Core value alignment validated
+- [ ] User had opportunity to add requirements
+- [ ] User scoped each category (v1/v2/out of scope)
+- [ ] All categories presented to user
 - [ ] REQUIREMENTS.md created with REQ-IDs
 - [ ] v1, v2, and out of scope clearly separated
-- [ ] Requirements committed to git
+- [ ] Features gathered (from research OR conversation)
 </success_criteria>