mindsystem-cc 3.18.1 → 3.20.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
-
-<!-- Current scope. Building toward these. -->
+## Who It's For
+[Target audience — who they are, their context, how they work today. 2-4 sentences.]
 
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
+## Core Problem
+[Why this exists — what pain or desire drives it. 1-2 sentences.]
 
-### Out of Scope
+## How It's Different
+[What makes this not another [category]. Include competitive context if relevant.]
+- [Differentiator 1]
+- [Differentiator 2]
+- [Differentiator 3]
 
-<!-- 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] — [version/phase]`
+- 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
@@ -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/roadmap.md

@@ -123,7 +123,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 **Initial planning (v1.0):**
 - Phase count derived from actual work (not a target number)
 - Each phase delivers something coherent
-- Phases can have 1+ plans (split if budget exceeds 45% or multiple subsystems)
+- Phases can have 1+ plans (split by orchestrator judgment — multiple subsystems, context budget, vertical slices)
 - Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
 - No time estimates (this isn't enterprise PM)
 - Progress table updated by execute workflow

package/mindsystem/templates/verification-report.md

@@ -180,7 +180,7 @@ None — all verifiable items checked programmatically.
 **Fix plan generation:**
 - Only generate if gaps_found
 - Group related fixes into single plans
-- Budget-based grouping (weights within 45%)
+- Budget-aware grouping (target 25-45% per plan)
 - Include verification task in each plan
 
 ---

package/mindsystem/workflows/complete-milestone.md

@@ -184,30 +184,31 @@ cat .planning/phases/*-*/*-SUMMARY.md
 3. **Requirements audit:**
 
    **Validated section:**
-   - All Active requirements shipped in this milestone → Move to Validated
+   - All requirements shipped in this milestone → Add to Validated
    - Format: `- ✓ [Requirement] — v[X.Y]`
 
-   **Active section:**
-   - Remove requirements that moved to Validated
-   - Add any new requirements for next milestone
-   - Keep requirements that weren't addressed yet
-
    **Out of Scope audit:**
    - Review each item — is the reasoning still valid?
    - Remove items that are no longer relevant
    - Add any requirements invalidated during this milestone
 
-4. **Context update:**
+4. **Business context review:**
+   - Who It's For — has understanding of audience evolved?
+   - Core Problem — still the right framing?
+   - How It's Different — new competitors or differentiators?
+   - Key User Flows — validated against what users actually do?
+
+5. **Technical Context update:**
    - Current codebase state (LOC, tech stack)
    - User feedback themes (if any)
    - Known issues or technical debt to address
 
-5. **Key Decisions audit:**
+6. **Key Decisions audit:**
    - Extract all decisions from milestone phase summaries
    - Add to Key Decisions table with outcomes where known
    - Mark ✓ Good, ⚠️ Revisit, or — Pending for each
 
-6. **Constraints check:**
+7. **Constraints check:**
    - Any constraints that changed during development?
    - Update as needed
 
@@ -233,20 +234,16 @@ A real-time collaborative whiteboard for remote teams.
 
 Real-time sync that feels instant.
 
-## Requirements
+## Who It's For
 
-### Validated
-
-(None yet — ship to validate)
+Remote teams who need to brainstorm visually during meetings.
+Currently using Miro or physical whiteboards.
 
-### Active
+## Validated
 
-- [ ] Canvas drawing tools
-- [ ] Real-time sync < 500ms
-- [ ] User authentication
-- [ ] Export to PNG
+(None yet — ship to validate)
 
-### Out of Scope
+## Out of Scope
 
 - Mobile app — web-first approach
 - Video chat — use external tools
@@ -263,27 +260,24 @@ A real-time collaborative whiteboard for remote teams with instant sync and draw
 
 Real-time sync that feels instant.
 
-## Requirements
+## Who It's For
+
+Remote teams (2-8 people) who brainstorm visually during meetings.
+Currently using Miro but frustrated by complexity and latency.
 
-### Validated
+## Validated
 
 - ✓ Canvas drawing tools — v1.0
 - ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
 - ✓ User authentication — v1.0
 
-### Active
-
-- [ ] Export to PNG
-- [ ] Undo/redo history
-- [ ] Shape tools (rectangles, circles)
-
-### Out of Scope
+## Out of Scope
 
 - Mobile app — web-first approach, PWA works well
 - Video chat — use external tools
 - Offline mode — real-time is core value
 
-## Context
+## Technical Context
 
 Shipped v1.0 with 2,400 LOC TypeScript.
 Tech stack: Next.js, Supabase, Canvas API.
@@ -294,10 +288,10 @@ Initial user testing showed demand for shape tools.
 
 - [ ] "What This Is" reviewed and updated if needed
 - [ ] Core Value verified as still correct
-- [ ] All shipped requirements moved to Validated
-- [ ] New requirements added to Active for next milestone
+- [ ] All shipped requirements added to Validated
+- [ ] Business context reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
 - [ ] Out of Scope reasoning audited
-- [ ] Context updated with current state
+- [ ] Technical Context updated with current state
 - [ ] All milestone decisions added to Key Decisions
 - [ ] "Last updated" footer reflects milestone completion
 
@@ -626,7 +620,7 @@ Tag: v[X.Y]
 
 Milestone completion is successful when (ordered by skip risk):
 
-- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, Requirements, Key Decisions, Context)
+- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, business context, Validated, Key Decisions, Technical Context)
 - [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
 - [ ] MILESTONES.md entry created with stats and accomplishments

package/mindsystem/workflows/execute-phase.md

@@ -245,72 +245,6 @@ After all waves complete, aggregate results:
 ```
 </step>
 
-<step name="code_review">
-Read code review agent name from config:
-
-```bash
-CODE_REVIEW=$(cat .planning/config.json 2>/dev/null | jq -r '.code_review.phase // empty')
-```
-
-**If CODE_REVIEW = "skip":**
-Report: "Code review skipped (config: skip)"
-Proceed to verify_phase_goal.
-
-**If CODE_REVIEW = empty/null:**
-Use default: `CODE_REVIEW="ms-code-simplifier"`
-
-**Otherwise:**
-Use CODE_REVIEW value directly as agent name.
-
-1. **Gather changed files:**
-   ```bash
-   # Get all files changed in this phase's commits
-   PHASE_COMMITS=$(git log --oneline --grep="(${PHASE_NUMBER}-" --format="%H")
-   CHANGED_FILES=$(git diff --name-only $(echo "$PHASE_COMMITS" | tail -1)^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')
-   ```
-
-2. **Spawn code review agent (from config):**
-   ```
-   Task(
-     prompt="
-     <objective>
-     Review code modified in phase {phase_number}.
-     Preserve all functionality. Improve clarity and consistency.
-     </objective>
-
-     <scope>
-     Files to analyze:
-     {CHANGED_FILES}
-     </scope>
-
-     <output>
-     After review and simplifications, run static analysis and tests.
-     Report what was improved and verification results.
-     </output>
-     ",
-     subagent_type="{CODE_REVIEW}"
-   )
-   ```
-
-3. **Handle result:**
-   - If changes made: Stage and commit
-   - If no changes: Report "No improvements needed"
-
-4. **Commit review changes (if any):**
-   ```bash
-   git add [modified files]
-   git commit -m "$(cat <<'EOF'
-   refactor({phase}): code review improvements
-
-   Reviewer: {agent_type}
-   Files reviewed: {count}
-   EOF
-   )"
-   ```
-
-Report: "Code review complete. Proceeding to verification."
-</step>
-
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed its TASKS.
 
@@ -339,13 +273,13 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 
 | Status | Action |
 |--------|--------|
-| `passed` | Continue to update_roadmap |
+| `passed` | Continue to code_review |
 | `human_needed` | Present items to user, get approval or feedback |
 | `gaps_found` | Present gap summary, offer `/ms:plan-phase {phase} --gaps` |
 
 **If passed:**
 
-Phase goal verified. Proceed to update_roadmap.
+Phase goal verified. Proceed to code_review.
 
 **If human_needed:**
 
@@ -361,11 +295,11 @@ All automated checks passed. {N} items need human testing:
 ---
 
 **After testing:**
-- "approved" → continue to update_roadmap
+- "approved" → continue to code_review
 - Report issues → will route to gap closure planning
 ```
 
-If user approves → continue to update_roadmap.
+If user approves → continue to code_review.
 If user reports issues → treat as gaps_found.
 
 **If gaps_found:**
@@ -407,6 +341,72 @@ User runs `/ms:plan-phase {X} --gaps` which:
 User stays in control at each decision point.
 </step>
 
+<step name="code_review">
+Read code review agent name from config:
+
+```bash
+CODE_REVIEW=$(cat .planning/config.json 2>/dev/null | jq -r '.code_review.phase // empty')
+```
+
+**If CODE_REVIEW = "skip":**
+Report: "Code review skipped (config: skip)"
+Proceed to generate_phase_patch.
+
+**If CODE_REVIEW = empty/null:**
+Use default: `CODE_REVIEW="ms-code-simplifier"`
+
+**Otherwise:**
+Use CODE_REVIEW value directly as agent name.
+
+1. **Gather changed files:**
+   ```bash
+   # Get all files changed in this phase's commits
+   PHASE_COMMITS=$(git log --oneline --grep="(${PHASE_NUMBER}-" --format="%H")
+   CHANGED_FILES=$(git diff --name-only $(echo "$PHASE_COMMITS" | tail -1)^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')
+   ```
+
+2. **Spawn code review agent (from config):**
+   ```
+   Task(
+     prompt="
+     <objective>
+     Review code modified in phase {phase_number}.
+     Preserve all functionality. Improve clarity and consistency.
+     </objective>
+
+     <scope>
+     Files to analyze:
+     {CHANGED_FILES}
+     </scope>
+
+     <output>
+     After review and simplifications, run static analysis and tests.
+     Report what was improved and verification results.
+     </output>
+     ",
+     subagent_type="{CODE_REVIEW}"
+   )
+   ```
+
+3. **Handle result:**
+   - If changes made: Stage and commit
+   - If no changes: Report "No improvements needed"
+
+4. **Commit review changes (if any):**
+   ```bash
+   git add [modified files]
+   git commit -m "$(cat <<'EOF'
+   refactor({phase}): code review improvements
+
+   Reviewer: {agent_type}
+   Files reviewed: {count}
+   EOF
+   )"
+   ```
+
+Report: "Code review complete. Proceeding to patch generation."
+</step>
+
 <step name="generate_phase_patch">
 Generate a patch file with all implementation changes from this phase.
 

package/mindsystem/workflows/execute-plan.md

@@ -28,7 +28,7 @@ cat .planning/STATE.md 2>/dev/null
 <step name="load_plan">
 Read the plan file provided in your prompt context.
 
-Parse inline metadata from header: `**Subsystem:**` and `**Type:**` values.
+Parse inline metadata from header: `**Subsystem:**`, `**Type:**`, and `**Skills:**` values.
 
 Parse plan sections:
 - Context (files to read, @-references)
@@ -44,11 +44,9 @@ Parse plan sections:
 </step>
 
 <step name="load_skills">
-Scan the skill list in your system message for skills matching the plan's technology or domain. Invoke each match via the Skill tool before proceeding — skills contain project-specific conventions and patterns that change what you produce during implementation.
+**If `**Skills:**` is present in plan metadata:** Invoke each listed skill via the Skill tool before proceeding. These were confirmed by the user during planning — load them without further confirmation.
 
-- One clear match → invoke it directly
-- Multiple candidates → use AskUserQuestion to let the user choose
-- No match → proceed without
+**If `**Skills:**` is absent:** Proceed without loading skills. Skill discovery happens during `/ms:plan-phase` — absence means no skills were relevant.
 </step>
 
 <step name="execute">

package/mindsystem/workflows/mockup-generation.md

@@ -39,16 +39,32 @@ Read `~/.claude/mindsystem/references/design-directions.md`. Follow the 3-step d
 2. **Pick most valuable exploration axes** from feature context
 3. **Generate 3 directions** — each with name, one-sentence philosophy, and 2-3 concrete layout/component choices
 
-Present all 3 directions to user via AskUserQuestion:
-> "Here are 3 design directions for [screen]. Generate mockups for all 3?"
->
-> **A: {Direction A name}** — {one-sentence philosophy}
-> **B: {Direction B name}** — {one-sentence philosophy}
-> **C: {Direction C name}** — {one-sentence philosophy}
->
+Present directions as text output first, then collect the choice separately. Do NOT put direction details inside AskUserQuestion — text output has no truncation limits and renders full markdown.
+
+**Output format** (as regular text, before the question):
+
+```
+Here are 3 design directions for the {screen}:
+
+**A: {name}** — {philosophy}
+{2-3 concrete layout/component choices as flowing text, ~1-2 lines}
+→ Optimized for: {what this direction prioritizes — one phrase}
+
+**B: {name}** — {philosophy}
+{2-3 concrete layout/component choices as flowing text, ~1-2 lines}
+→ Optimized for: {what this direction prioritizes — one phrase}
+
+**C: {name}** — {philosophy}
+{2-3 concrete layout/component choices as flowing text, ~1-2 lines}
+→ Optimized for: {what this direction prioritizes — one phrase}
+```
+
+**Then** use AskUserQuestion with short options only — no direction details repeated:
+
+> "Generate mockups for all 3 directions?"
 > 1. **Generate mockups** — Spawn 3 parallel agents, one per direction
 > 2. **Tweak directions first** — Adjust before generating
-> 3. **Let me describe different directions** — Replace with your own
+> 3. **Describe different directions** — Replace with your own ideas
 
 If user picks option 2 or 3, incorporate their input, re-derive or adjust directions, and present again.
 </step>