mindsystem-cc 3.22.0 → 4.0.0

package/commands/ms/new-milestone.md

@@ -66,7 +66,8 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 1. **Load context:**
    - Read PROJECT.md (existing project, validated requirements, decisions)
    - Read MILESTONES.md (what shipped previously)
-   - Read STATE.md (pending todos, blockers)
+   - Read STATE.md (blockers)
+   - Scan `.planning/todos/` for pending todos
    - Read config.json (project settings)
    - Identify previous milestone name from MILESTONES.md (e.g., last shipped was "MVP")
 
@@ -111,9 +112,9 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
    - Tech debt from TECH-DEBT.md, MILESTONE-AUDIT.md, or knowledge file Pitfalls sections
    - Settled decisions and patterns from knowledge files
    - Untested assumptions from previous audit
-   - Unaddressed requirements from previous milestones
+   - Deferred items from PROJECT.md `## Deferred` section (carried forward from previous milestones)
    - Strategic features inferred from PROJECT.md: Who It's For, Core Problem, How It's Different
-   - Pending todos from STATE.md
+   - Pending todos from `.planning/todos/`
 
    If no meaningful artifacts exist (first milestone), base suggestions purely on PROJECT.md.
 

package/commands/ms/progress.md

@@ -38,7 +38,7 @@ Reconstruct STATE.md from artifacts:
 1. Read PROJECT.md → Extract "What This Is" and Core Value
 2. Read ROADMAP.md → Determine phases, find current position
 3. Scan *-SUMMARY.md files → Extract recent decisions, concerns
-4. Count pending todos in .planning/todos/pending/
+4. Count pending todos in .planning/todos/
 
 Write reconstructed STATE.md, then proceed to "load" step.
 
@@ -55,6 +55,22 @@ This means a milestone was completed and archived. Go to **Route F** (between mi
 If missing both ROADMAP.md and PROJECT.md: suggest `/ms:new-project`.
 </step>
 
+<step name="check_version">
+**Check for Mindsystem updates (non-blocking):**
+
+```bash
+# Installed version
+cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/mindsystem/VERSION" 2>/dev/null || cat ./.claude/mindsystem/VERSION 2>/dev/null
+```
+
+```bash
+# Latest from npm
+npm view mindsystem-cc version 2>/dev/null
+```
+
+Compare versions. Store result for the report step. If npm fails or versions match, skip — do not block progress.
+</step>
+
 <step name="load">
 **Load full project context:**
 
@@ -79,7 +95,7 @@ If missing both ROADMAP.md and PROJECT.md: suggest `/ms:new-project`.
 - Note any blockers or concerns
 - Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
 - Check for DESIGN.md: For UI-heavy phases, check if `{phase}-DESIGN.md` exists in phase directory
-- Count pending todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l`
+- Count pending todos: `ls .planning/todos/*.md 2>/dev/null | wc -l`
 - Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
   </step>
 
@@ -109,12 +125,16 @@ DESIGN: [✓ if DESIGN.md exists | - if not]
 - [any blockers or concerns from STATE.md]
 
 ## Pending Todos
-- [count] pending — /ms:check-todos to review
+- [count] pending — /ms:add-todo to capture, /ms:adhoc to work on
 
 ## Active Debug Sessions
 - [count] active — /ms:debug to continue
 (Only show this section if count > 0)
 
+## Update Available
+⬆ v{installed} → v{latest} — run `/ms:update`
+(Only show this section if installed < latest)
+
 ## What's Next
 [Next phase/plan objective from ROADMAP]
 ```

package/commands/ms/update.md

@@ -0,0 +1,102 @@
+---
+name: ms:update
+description: Check for updates and install latest Mindsystem version
+allowed-tools: [Bash, AskUserQuestion]
+---
+
+<objective>
+Check installed Mindsystem version against npm registry and offer to update if behind. Detects local vs global install mode automatically.
+
+Run when the user wants to update Mindsystem or check if a newer version is available.
+</objective>
+
+<process>
+
+<step name="detect_version_and_mode">
+Detect installed version and install mode:
+
+```bash
+# Check local first (takes precedence)
+cat ./.claude/mindsystem/VERSION 2>/dev/null
+```
+
+```bash
+# If not found, check global (respect CLAUDE_CONFIG_DIR)
+cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/mindsystem/VERSION" 2>/dev/null
+```
+
+- If local VERSION exists → `mode = "local"`
+- Else if global VERSION exists → `mode = "global"`
+- If neither found:
+
+```
+Mindsystem not installed. Run `npx mindsystem-cc` to install.
+```
+
+STOP.
+
+Store the installed version (strip whitespace).
+</step>
+
+<step name="fetch_latest_version">
+Fetch latest version from npm:
+
+```bash
+npm view mindsystem-cc version
+```
+
+If the command fails (network error, timeout), report the error and STOP.
+</step>
+
+<step name="compare_versions">
+Compare installed version against latest:
+
+- If installed == latest → "You are using the latest version (v{installed})." STOP.
+- If installed > latest → "Development version (v{installed} > v{latest})." STOP.
+- If installed < latest → proceed to next step.
+
+Use semantic version comparison (split on `.`, compare major/minor/patch numerically).
+</step>
+
+<step name="ask_user">
+Use AskUserQuestion:
+
+- header: "Update"
+- question: "Update available: v{installed} → v{latest}. Update now?"
+- options:
+  - "Update" — install latest version
+  - "Skip" — leave current version
+
+If "Skip" → STOP.
+</step>
+
+<step name="run_install">
+Build the install command based on mode:
+
+- Global: `npx mindsystem-cc@latest --force --global`
+- Local: `npx mindsystem-cc@latest --force --local`
+
+Also pass `--config-dir "$CLAUDE_CONFIG_DIR"` if `CLAUDE_CONFIG_DIR` is set.
+
+Run the command. If exit code != 0, show the error output and STOP.
+</step>
+
+<step name="post_update_guidance">
+Show success message:
+
+```
+Updated to v{latest}.
+
+Restart Claude Code for changes to take effect, then run `/ms:doctor` to check for breaking changes.
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Post-update message includes restart and /ms:doctor instructions
+- [ ] Passes correct --force and mode flags to installer
+- [ ] Skips update when already on latest or development version
+- [ ] Reports "not installed" when no VERSION file exists
+- [ ] Handles npm fetch failures gracefully
+</success_criteria>

package/mindsystem/references/linear-cli.md

@@ -0,0 +1,71 @@
+<linear_cli>
+CLI prefix: provided via `task_tracker.cli` in config.json
+
+## Operations
+
+| Command        | Usage                                   |
+|----------------|-----------------------------------------|
+| get            | `{cli} get <ID> [-c for comments]`      |
+| comment        | `{cli} comment <ID> "<body>"`           |
+| done           | `{cli} done <ID>`                       |
+| attach-commit  | `{cli} attach-commit <ID> [sha]`        |
+
+Ticket ID pattern: `[A-Z]{2,4}-\d+` (e.g., MIN-123, PROJ-42)
+
+## Ticket Detection
+
+When `$ARGUMENTS` matches the ticket ID pattern:
+
+```bash
+TICKET_ID=$(echo "$ARGUMENTS" | grep -oE '[A-Z]{2,4}-[0-9]+' | head -1)
+TICKET_JSON=$($TRACKER_CLI get "$TICKET_ID" 2>/dev/null)
+```
+
+Parse JSON response — extract `title` and `description` fields. Use ticket title as work description; append ticket description as additional context.
+
+If fetch fails: treat full `$ARGUMENTS` as free-text description. No error — proceed normally.
+
+## Planner Context
+
+When spawning the plan writer with ticket context, include in the prompt:
+- Ticket ID, title, and description
+- Instruct planner to use title format: `# Adhoc: {Ticket Title} [{TICKET-ID}]`
+- Instruct planner to include ticket description in the Context section
+
+## Executor Instructions
+
+When spawning the executor with a ticket ID, instruct it to append `[TICKET-ID]` to commit messages (e.g., `feat(adhoc-auth): description [MIN-140]`).
+
+## Finalization
+
+Run after knowledge consolidation. Each is a separate CLI call — verify exit code 0. If any fails, log a warning but continue.
+
+**Comment on ticket:** Extract solution summary from SUMMARY.md (key decisions, files modified). Post via:
+```bash
+$TRACKER_CLI comment "$TICKET_ID" "$COMMENT_BODY"
+```
+
+**Attach commit:**
+```bash
+$TRACKER_CLI attach-commit "$TICKET_ID"
+```
+
+**Mark done:**
+```bash
+$TRACKER_CLI done "$TICKET_ID"
+```
+
+## Commit Message Suffix
+
+Append ` [TICKET-ID]` to the consolidation commit message when ticket-driven.
+
+## Report Additions
+
+When ticket was finalized, append to completion report:
+```
+**Ticket:** [TICKET-ID]
+- Comment posted: [yes/failed]
+- Commit attached: [yes/failed]
+- State → Done: [yes/failed]
+```
+</linear_cli>

package/mindsystem/references/routing/audit-result-routing.md

@@ -72,7 +72,11 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 
 ## ▶ Next Up
 
-`/ms:plan-milestone-gaps` — create phases to complete milestone
+Review the gaps above, then choose the right tool:
+
+- `/ms:adhoc` — for discovered fixes (missing wiring, edge cases)
+- `/ms:add-phase "<description>"` — for a coherent set of related gaps
+- `/ms:insert-phase <after> "<description>"` — if gaps must be fixed before a specific phase
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -96,8 +100,8 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 **Tech debt tracked:** .planning/TECH-DEBT.md ({tech_debt_count} active items)
 
 Address items using:
-- `/ms:adhoc` — for small fixes (1-2 tasks)
-- `/ms:insert-phase` — for larger remediation
+- `/ms:adhoc` — for single-context fixes
+- `/ms:insert-phase` — for multi-phase remediation
 
 {If assumptions_count > 0:}
 ### Untested Assumptions: {assumptions_count} items
@@ -110,7 +114,8 @@ See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
 ## ▶ Options
 
 - `/ms:complete-milestone` — accept debt, track in backlog
-- `/ms:plan-milestone-gaps` — address debt before completing
+- `/ms:adhoc` — for single-context fixes
+- `/ms:add-phase` — for multi-phase remediation
 
 <sub>`/clear` first → fresh context window</sub>
 ```

package/mindsystem/references/todo-file.md

@@ -0,0 +1,63 @@
+<todo_file>
+
+## Todo Detection
+
+When `$ARGUMENTS` matches a `.planning/todos/*.md` file path and the file exists:
+
+Read the file and parse:
+- **YAML frontmatter:** `title`, `subsystem`, `priority`, `estimate`
+- **Body:** `## Problem` and `## Solution` sections
+
+Use todo title as work description. Feed problem/solution as additional context.
+
+If the file doesn't exist: treat `$ARGUMENTS` as free-text description. No error — proceed normally.
+
+## Planner Context
+
+When spawning the plan writer with todo context, include in the prompt:
+- Todo title, subsystem, problem, and solution hints
+- Instruct planner to use title format: `# Adhoc: {Todo Title}`
+- Instruct planner to include todo problem/solution in the Context section
+- Instruct planner to use todo's subsystem for plan inline metadata (`**Subsystem:**`)
+
+## Executor Instructions
+
+When spawning the executor with a todo, instruct it to include the todo filename (without path or extension) in commit message suffixes (e.g., `feat(adhoc-auth): description (2026-02-20-add-logout)`).
+
+## Finalization
+
+Run after knowledge consolidation. Move the todo file to `done/` and append an outcome section.
+
+**Move to done:**
+```bash
+TODO_DIR=$(dirname "$TODO_PATH")
+mkdir -p "${TODO_DIR}/done"
+mv "$TODO_PATH" "${TODO_DIR}/done/$(basename "$TODO_PATH")"
+```
+
+**Append outcome:** Read SUMMARY.md and extract solution summary (key decisions, files modified). Append to the moved file:
+
+```markdown
+
+## Outcome
+[Solution summary from SUMMARY.md — key decisions, files modified]
+```
+
+**Stage moved file:**
+```bash
+git add "${TODO_DIR}/done/$(basename "$TODO_PATH")"
+```
+
+## Commit Message Suffix
+
+Append ` (todo-filename)` to the consolidation commit message when todo-driven, where `todo-filename` is the basename without `.md` extension.
+
+## Report Additions
+
+When todo was finalized, append to completion report:
+```
+**Todo:** [filename]
+- Moved to: .planning/todos/done/[filename]
+- Outcome appended: yes
+```
+</todo_file>

package/mindsystem/templates/adhoc-summary.md

@@ -1,6 +1,6 @@
 # Adhoc Summary Template
 
-Template for `.planning/adhoc/{timestamp}-{slug}-SUMMARY.md` — documentation for small work items executed via `/ms:adhoc`.
+Template for `.planning/adhoc/{timestamp}-{slug}-SUMMARY.md` — documentation for work items executed via `/ms:adhoc`.
 
 ---
 
@@ -45,7 +45,7 @@ learnings:
 
 <purpose>
 
-Adhoc summaries document small work items executed outside the normal phase workflow.
+Adhoc summaries document work items executed outside the normal phase workflow.
 
 **Differences from phase SUMMARY.md:**
 - Simplified frontmatter (no waves, depends_on, requires, provides, affects)
@@ -146,9 +146,8 @@ learnings:
 - Required output from adhoc workflow
 
 **Size:**
-- Keep brief — adhoc work is small by definition
-- 1-2 accomplishments typical
-- 1-3 files typical
+- Keep brief — proportional to work scope
+- Summarize key accomplishments, not every file touched
 
 **Commit reference:**
 - Always include commit hash in frontmatter

package/mindsystem/templates/knowledge.md

@@ -4,7 +4,7 @@ Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge fi
 
 **Purpose:** Curated reference per domain area. Bridges phase-scoped execution artifacts to topic-scoped knowledge. Each file contains decisions, architecture, design, pitfalls, and key files for one subsystem.
 
-**Created by:** `ms-consolidator` agent during `execute-phase`
+**Created by:** `ms-consolidator` agent during `execute-phase`, or `ms-compounder` agent during `ms:compound`
 
 **Referenced by:** All pre-planning phases (discuss-phase, design-phase, research-phase, plan-phase)
 

package/mindsystem/templates/project.md

@@ -35,6 +35,9 @@ Template for `.planning/PROJECT.md` — the living project context document.
 - [Exclusion 1] — [why]
 - [Exclusion 2] — [why]
 
+## Deferred
+- [Requirement] — deferred from [Milestone], [brief reason]
+
 ## Constraints
 - **[Type]**: [What] — [Why]
 - **[Type]**: [What] — [Why]
@@ -100,7 +103,14 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 **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
+- Explicitly excluded items only — use Deferred for "wanted but not yet"
+
+**Deferred:**
+- Items the user wants to build but haven't shipped yet
+- Each entry includes origin milestone and reason for deferral
+- Audited at each milestone completion: promote to current milestone, keep deferred, move to Out of Scope, or discard
+- Consumed by create-roadmap as v1 candidates for new milestones
+- Format: `- [Requirement] — deferred from [Milestone], [brief reason]`
 
 **Constraints:**
 - Hard limits on implementation choices
@@ -148,9 +158,10 @@ PROJECT.md evolves throughout the project lifecycle.
 **After each milestone:**
 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 Technical Context with current state (users, feedback, metrics)
-5. Key User Flows — validated against what users actually do?
+3. Audit Deferred — still desired? Promote to current milestone, keep deferred, reclassify to Out of Scope, or discard
+4. Audit Out of Scope — reasons still valid?
+5. Update Technical Context with current state (users, feedback, metrics)
+6. Key User Flows — validated against what users actually do?
 
 </evolution>
 

package/mindsystem/templates/state.md

@@ -55,15 +55,9 @@ Recent decisions affecting current work:
 - [Phase X]: [Decision summary]
 - [Phase Y]: [Decision summary]
 
-### Pending Todos
-
-[From .planning/todos/pending/ — ideas captured during sessions]
-
-None yet.
-
 ### Recent Adhoc Work
 
-[Small work items executed via /ms:adhoc]
+[Work items executed via /ms:adhoc]
 
 None yet.
 
@@ -155,12 +149,7 @@ Updated after each plan completion.
 
 **Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
 
-**Pending Todos:** Ideas captured via /ms:add-todo
-- Count of pending todos
-- Reference to .planning/todos/pending/
-- Brief list if few, count if many (e.g., "5 pending todos — see /ms:check-todos")
-
-**Recent Adhoc Work:** Small fixes executed via /ms:adhoc
+**Recent Adhoc Work:** Discovered work executed via /ms:adhoc
 - Last 5 adhoc work entries
 - Format: `- [date]: [description] (.planning/adhoc/[file]-SUMMARY.md)`
 - Full history remains in .planning/adhoc/ directory
@@ -212,6 +201,6 @@ The goal is "read once, know where we are" — if it's too long, that fails.
 - Project Reference: Pointer to PROJECT.md with core value
 - Current Position: Where we are now (phase, plan, status)
 - Performance Metrics: Velocity tracking
-- Accumulated Context: Recent decisions, pending todos, adhoc work, blockers
+- Accumulated Context: Recent decisions, adhoc work, blockers
 
 </guidelines>

package/mindsystem/templates/tech-debt.md

@@ -6,7 +6,7 @@ Template for `.planning/TECH-DEBT.md` — single source of truth for all tech de
 
 ## Usage
 
-Created and updated by `/ms:audit-milestone`. Items persist across milestones. Users reference items manually via `/ms:adhoc` (small fixes) or `/ms:insert-phase` (larger remediation). Loaded automatically by `/ms:plan-phase` for quality/cleanup phases.
+Created and updated by `/ms:audit-milestone`. Items persist across milestones. Users reference items manually via `/ms:adhoc` (single context work) or `/ms:insert-phase` (multi-phase remediation). Loaded automatically by `/ms:plan-phase` for quality/cleanup phases.
 
 **Item IDs** use `TD-{N}` format — monotonically increasing, never reused. New items continue from highest existing ID.
 
@@ -21,7 +21,7 @@ Created and updated by `/ms:audit-milestone`. Items persist across milestones. U
 # Tech Debt
 
 > Single source of truth for tech debt. Updated by `/ms:audit-milestone`.
-> Address items via `/ms:adhoc` (1-2 tasks) or `/ms:insert-phase` (larger work).
+> Address items via `/ms:adhoc` (single context) or `/ms:insert-phase` (multi-phase work).
 
 ## {Severity}
 <!-- Sections in order: Critical, High, Medium, Low. Omit empty sections. -->