mindsystem-cc 3.19.0 → 3.21.0

package/mindsystem/templates/project.md

@@ -8,60 +8,50 @@ Template for `.planning/PROJECT.md` — the living project context document.
 # [Project Name]
 
 ## What This Is
-
-[Current accurate description — 2-3 sentences. What does this product do and who is it for?
-Use the user's language and framing. Update whenever reality drifts from this description.]
+[2-3 sentences. Product identity in plain language.]
 
 ## Core Value
+[Single sentence: the ONE thing that cannot fail.]
 
-[The ONE thing that matters most. If everything else fails, this must work.
-One sentence that drives prioritization when tradeoffs arise.]
-
-## Requirements
-
-### Validated
-
-<!-- Shipped and confirmed valuable. -->
-
-(None yet — ship to validate)
-
-### Active
+## Who It's For
+[Target audience — who they are, their context, how they work today. 2-4 sentences.]
 
-<!-- Current scope. Building toward these. -->
+## Core Problem
+[Why this exists — what pain or desire drives it. 1-2 sentences.]
 
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
+## How It's Different
+[What makes this not another [category]. Include competitive context if relevant.]
+- [Differentiator 1]
+- [Differentiator 2]
+- [Differentiator 3]
 
-### Out of Scope
-
-<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
+## Key User Flows
+[The 2-3 core interactions users perform.]
+- [Flow 1]
+- [Flow 2]
+- [Flow 3]
 
+## Out of Scope
 - [Exclusion 1] — [why]
 - [Exclusion 2] — [why]
 
-## Context
-
-[Background information that informs implementation:
-- Technical environment or ecosystem
-- Relevant prior work or experience
-- User research or feedback themes
-- Known issues to address]
-
 ## Constraints
-
 - **[Type]**: [What] — [Why]
 - **[Type]**: [What] — [Why]
 
 Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
 
-## Key Decisions
+## Technical Context
+[Tech stack, integrations, prior work, known issues/debt.]
 
-<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+## Validated
+(None yet — ship to validate)
+
+## Key Decisions
 
 | Decision | Rationale | Outcome |
 |----------|-----------|---------|
-| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
+| [Choice] | [Why] | — Pending |
 
 ---
 *Last updated: [date] after [trigger]*
@@ -83,32 +73,51 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 - Drives prioritization when tradeoffs arise
 - Rarely changes; if it does, it's a significant pivot
 
-**Requirements — Validated:**
-- Requirements that shipped and proved valuable
-- Format: `- ✓ [Requirement] — [version/phase]`
-- These are locked — changing them requires explicit discussion
-
-**Requirements — Active:**
-- Current scope being built toward
-- These are hypotheses until shipped and validated
-- Move to Validated when shipped, Out of Scope if invalidated
-
-**Requirements — Out of Scope:**
+**Who It's For:**
+- Specific enough to find 10 of these people
+- Include their context: what they do today, what tools they use, what frustrates them
+- Avoid broad categories ("developers", "small businesses") — narrow to who needs this MOST
+- Update as real user data replaces assumptions
+
+**Core Problem:**
+- The pain or desire that makes this product necessary
+- Should explain why existing alternatives don't suffice
+- One sentence is better than two — forces precision
+- If you can't articulate the problem, the product isn't ready to build
+
+**How It's Different:**
+- 2-3 concrete differentiators, not marketing language
+- Include what people use today instead (even manual workarounds)
+- "Nothing else does this" is almost always wrong — probe alternatives
+- Competitive context folds in here — no standalone section needed
+
+**Key User Flows:**
+- The 2-3 core interactions that make the product valuable
+- One line each — verb-driven ("Log workout → view history → track progress")
+- Bridges abstract identity and concrete architecture
+- Update as flows are validated or new ones emerge
+
+**Out of Scope:**
 - Explicit boundaries on what we're not building
 - Always include reasoning (prevents re-adding later)
 - Includes: considered and rejected, deferred to future, explicitly excluded
 
-**Context:**
-- Background that informs implementation decisions
-- Technical environment, prior work, user feedback
-- Known issues or technical debt to address
-- Update as new context emerges
-
 **Constraints:**
 - Hard limits on implementation choices
 - Tech stack, timeline, budget, compatibility, dependencies
 - Include the "why" — constraints without rationale get questioned
 
+**Technical Context:**
+- Background that informs implementation decisions
+- Tech stack, integrations, prior work, known issues/debt
+- Update as new technical context emerges
+- Purely technical — business context lives in Layer 1 sections
+
+**Validated:**
+- Requirements that shipped and proved valuable
+- Format: `- ✓ [Requirement] — [Milestone Name]`
+- These are locked — changing them requires explicit discussion
+
 **Key Decisions:**
 - Significant choices that affect future work
 - Add decisions as they're made throughout the project
@@ -119,7 +128,7 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 
 **Last Updated:**
 - Always note when and why the document was updated
-- Format: `after Phase 2` or `after v1.0 milestone`
+- Format: `after Phase 2` or `after [Name] milestone`
 - Triggers review of whether content is still accurate
 
 </guidelines>
@@ -131,15 +140,17 @@ PROJECT.md evolves throughout the project lifecycle.
 **After each phase transition:**
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
-3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
-5. "What This Is" still accurate? → Update if drifted
+3. Decisions to log? → Add to Key Decisions
+4. "What This Is" still accurate? → Update if drifted
+5. Has understanding of audience, problem, or differentiation evolved? → Update Who It's For, Core Problem, or How It's Different
+6. New key flows emerged? → Update Key User Flows
 
 **After each milestone:**
-1. Full review of all sections
+1. Full review of all sections including business context (Who It's For, Core Problem, How It's Different)
 2. Core Value check — still the right priority?
 3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state (users, feedback, metrics)
+4. Update Technical Context with current state (users, feedback, metrics)
+5. Key User Flows — validated against what users actually do?
 
 </evolution>
 
@@ -154,15 +165,10 @@ For existing codebases:
    - What patterns are established?
    - What's clearly working and relied upon?
 
-3. **Gather Active requirements** from user:
-   - Present inferred current state
-   - Ask what they want to build next
-
-4. **Initialize:**
+3. **Initialize:**
    - Validated = inferred from existing code
-   - Active = user's goals for this work
    - Out of Scope = boundaries user specifies
-   - Context = includes current codebase state
+   - Technical Context = populated from codebase map
 
 </brownfield>
 

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

@@ -33,8 +33,8 @@ Phase Research — External Documentation focus.
 <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>'
+  ms-lookup docs <library> '<query>'
+  ms-lookup deep '<query>'
 Use WebSearch for ecosystem discovery.
 Focus on finding authoritative, current documentation for the libraries and tools
 needed to implement this phase.
@@ -129,7 +129,7 @@ Phase Research — Best Practices & Community Consensus focus.
 <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>'
+  ms-lookup deep '<query>'
 Use WebSearch for community articles, blog posts, Stack Overflow patterns.
 Focus on what practitioners recommend and what mistakes to avoid.
 </focus>

package/mindsystem/templates/roadmap-milestone.md

@@ -7,14 +7,14 @@ Template for reorganizing `ROADMAP.md` after first milestone ships. Collapse com
 
 ## 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)
+- ✅ **MVP** - Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **[Name]** - Phases 5-6 (in progress)
+- 📋 **[Name]** - Phases 7-10 (planned)
 
 ## Phases
 
 <details>
-<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
+<summary>✅ MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
 
 ### Phase 1: [Name]
 **Goal**: [What this phase delivers]
@@ -25,13 +25,13 @@ Plans:
 - [x] 01-02: [Brief description]
 - [x] 01-03: [Brief description]
 
-[... remaining v1.0 phases ...]
+[... remaining phases ...]
 
 </details>
 
-### 🚧 v1.1 [Name] (In Progress)
+### 🚧 [Name] (In Progress)
 
-**Milestone Goal:** [What v1.1 delivers]
+**Milestone Goal:** [What this milestone delivers]
 
 #### Phase 5: [Name]
 **Goal**: [What this phase delivers]
@@ -42,21 +42,21 @@ Plans:
 - [ ] 05-01: [Brief description]
 - [ ] 05-02: [Brief description]
 
-[... remaining v1.1 phases ...]
+[... remaining phases ...]
 
-### 📋 v2.0 [Name] (Planned)
+### 📋 [Name] (Planned)
 
-**Milestone Goal:** [What v2.0 delivers]
+**Milestone Goal:** [What this milestone delivers]
 
-[... v2.0 phases ...]
+[... 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 | - |
+| 1. Foundation | MVP | 3/3 | Complete | YYYY-MM-DD |
+| 2. Features | MVP | 2/2 | Complete | YYYY-MM-DD |
+| 5. Security | Security & Polish | 0/2 | Not started | - |
 ```
 
 **Notes:**

package/mindsystem/templates/roadmap.md

@@ -2,7 +2,7 @@
 
 Template for `.planning/ROADMAP.md`.
 
-## Initial Roadmap (v1.0 Greenfield)
+## Initial Roadmap (Greenfield)
 
 ```markdown
 # Roadmap: [Project Name]
@@ -34,7 +34,7 @@ Decimal phases appear between their surrounding integers in numeric order.
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
   3. [Observable behavior from user perspective]
-**Discuss**: Unlikely (clear requirements)
+**Discuss**: Unlikely (mechanical setup, zero design decisions)
 **Design**: Unlikely (backend only)
 **Research**: Unlikely (established patterns)
 **Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
@@ -51,7 +51,7 @@ Plans:
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
-**Discuss**: Likely (ambiguous user flow)
+**Discuss**: Likely (assumes email/password only, unclear if social login needed, session duration unspecified)
 **Discuss topics**: [What to clarify]
 **Design**: Likely (significant new UI)
 **Design focus**: [What to design]
@@ -81,7 +81,8 @@ Plans:
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
   3. [Observable behavior from user perspective]
-**Discuss**: Unlikely (established patterns)
+**Discuss**: Likely (assumes standard REST patterns, error handling strategy unspecified, rate limiting approach unclear)
+**Discuss topics**: [Integration scope, error UX, retry behavior]
 **Design**: Unlikely (API only)
 **Research**: Likely (external API)
 **Research topics**: [What needs investigating]
@@ -98,7 +99,8 @@ Plans:
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
   2. [Observable behavior from user perspective]
-**Discuss**: Unlikely (clear requirements)
+**Discuss**: Likely (assumes priority ordering of requirements, unclear if batch processing needed, edge case handling unspecified)
+**Discuss topics**: [Priority rules, batch vs individual, error recovery]
 **Design**: Unlikely (backend only)
 **Research**: Unlikely (internal patterns)
 **Plans**: [Number of plans]
@@ -120,7 +122,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 ```
 
 <guidelines>
-**Initial planning (v1.0):**
+**Initial planning:**
 - Phase count derived from actual work (not a target number)
 - Each phase delivers something coherent
 - Phases can have 1+ plans (split by orchestrator judgment — multiple subsystems, context budget, vertical slices)
@@ -137,7 +139,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Format: "User can [action]" or "[Thing] works/exists"
 
 **Pre-work indicators** (all use Likely/Unlikely with parenthetical reason):
-- `Discuss` - Vision unknowns: ambiguous requirements, UX decisions, novel features
+- `Discuss` - Default Likely. Surfaces Claude's assumptions before planning. Unlikely only for fully mechanical zero-decision work (version bump, rename-only refactor, config-only change, pure deletion/cleanup). When Likely, rationale enumerates 2-4 phase-specific assumptions or open questions.
 - `Design` - Visual unknowns: significant new UI, novel interactions, multi-screen flows
 - `Research` - Technical unknowns: external APIs, new libraries, architectural decisions
 - Include topic/focus fields only when Likely

package/mindsystem/workflows/adhoc.md

@@ -381,7 +381,7 @@ Generate patch file from the adhoc commit:
 ```bash
 patch_file=".planning/adhoc/${timestamp}-${slug}.patch"
 
-~/.claude/mindsystem/scripts/generate-adhoc-patch.sh "$commit_hash" "$patch_file"
+ms-tools generate-adhoc-patch "$commit_hash" "$patch_file"
 ```
 
 If patch generated (file exists and non-empty):