npm - mindsystem-cc - Versions diffs - 4.0.0 → 4.0.1 - Mend

mindsystem-cc 4.0.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +210 -221
package/commands/ms/help.md +1 -12
package/mindsystem/references/plan-format.md +1 -1
package/mindsystem/references/plan-risk-assessment.md +1 -1
package/package.json +1 -1
package/commands/ms/check-phase.md +0 -134

package/README.md CHANGED Viewed

@@ -2,22 +2,16 @@
 # MINDSYSTEM
-**Spec-driven development for Claude Code, built for engineers who ship production code.**
+**A meta-prompting and context engineering system for Claude Code.**
-**Solves context rot — the quality degradation that happens as Claude fills its context window.**
-_Built on the philosophy of [GSD](https://github.com/glittercowboy/get-shit-done) by TÂCHES._
-[![npm version](https://img.shields.io/npm/v/mindsystem-cc?style=flat-square&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/mindsystem-cc)
-[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
-<br>
+Every piece of work makes the next one better. Mindsystem structures your Claude Code sessions into plannable, executable, verifiable phases — and compounds what it learns into persistent knowledge files that survive `/clear`. The result: context rot stops being the bottleneck, and quality stays consistent from phase 1 to phase 20.
 ```bash
 npx mindsystem-cc
 ```
-**Works on macOS, Windows, and Linux.**
+[![npm version](https://img.shields.io/npm/v/mindsystem-cc?style=flat-square&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/mindsystem-cc)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
 <br>
@@ -25,278 +19,255 @@ npx mindsystem-cc
 <br>
-[Why](#why-engineers-use-this) · [Install](#installation) · [Mental model](#mental-model) · [Playbooks](#playbooks) · [Why this works](#why-this-works) · [Config](#configuration) · [Commands](#command-index-one-liners) · [Troubleshooting](#troubleshooting)
+[How It Works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick Start](#quick-start) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
 </div>
 ---
-## Why Engineers Use This
-> _"I'm a solo developer. I don't write code — Claude Code does. Other spec-driven development tools exist; BMAD, Speckit... But they all seem to make things way more complicated than they need to be. I'm not a 50-person software company. I don't want to play enterprise theater. I'm just a creative person trying to build great things that work."_
->
-> — **TÂCHES**, creator of the original [GSD](https://github.com/glittercowboy/get-shit-done)
+## How It Works
-This philosophy resonated. GSD proved that spec-driven development could be simple and effective.
+```
+  new-milestone          Define what to build next
+       │
+  create-roadmap         Derive requirements, map to phases
+       │
+       ▼
+  ┌─────────────────┐
+  │  Per Phase:      │
+  │                  │
+  │  discuss-phase ──┤  (optional) Lock intent, validate assumptions
+  │  design-phase  ──┤  (optional) Generate mockups, pick direction
+  │  research-phase ─┤  (optional) External docs, codebase patterns, community practices
+  │                  │
+  │  plan-phase ─────┤  Break into context-budgeted plans
+  │  execute-phase ──┤  Fresh subagents run each plan autonomously
+  │  verify-work ────┤  Manual acceptance tests, inline fixes
+  │                  │
+  │  ← repeat ───────┘
+  │
+  audit-milestone        Check requirements coverage, surface tech debt
+       │
+  complete-milestone     Archive, evolve PROJECT.md, clean slate
+```
-Mindsystem takes that foundation and optimizes it for a specific kind of user: **Claude Code power users who ship production code**. You're not vibe coding. You want speed, but you also want control, reviewable diffs, and quality gates. You care about what the output code looks like.
+Each phase gets its own preparation depth. A database migration might skip straight to planning. A user-facing feature might warrant discussion, design mockups, and research first. You pick the depth; the system adapts.
-Where GSD went broad, Mindsystem goes deep — more verification, more quality gates, more ways to inspect and override. Less magic, more engineering.
+Execution happens in fresh subagent contexts — each plan gets up to 200k tokens of headroom at peak quality, regardless of how much planning you did in the main conversation.
-### What you get
+---
-- **Consistent quality across long sessions.** You plan in the main chat; work runs in fresh subagents at peak context quality.
-- **A single source of truth.** Your `.planning/` folder holds what you're building and what you've proven works — not a scrolling chat transcript.
-- **Reviewable diffs.** Every change creates a commit _and_ a `.patch` file you can inspect, apply, or throw away.
-- **Smart division of labor.** Scripts handle mechanics. Models handle judgment calls and code.
+## End-to-End Walkthrough
-### Beyond the foundation
+### 1. New Milestone
-The original GSD established the philosophy and core infrastructure. Mindsystem extends it with features you'll actually need when shipping production code:
+```
+/ms:new-milestone
+```
-- **Batched UAT with inline fixing.** `/ms:verify-work` shows you tests in batches, fixes failures on the spot (inline or via subagents), and loops until things pass.
-- **Mock-assisted testing.** Generate mock states for tricky scenarios (errors, empty states, role-based views) without shipping mock code.
-- **Patch files everywhere.** Phase execution and UAT fixes produce `.patch` files (`{phase}-changes.patch`, `{phase}-uat-fixes.patch`) so you can diff before you commit.
-- **UI quality tools.** `/ms:design-phase` writes UI/UX specs. `/ms:review-design` audits existing UI and suggests improvements.
-- **Fast research via CLI.** `ms-lookup` searches APIs (Context7 docs, Perplexity) with caching and JSON output. Example: `ms-lookup docs react "useEffect cleanup"`.
-- **Lean milestone management.** Finishing a milestone consolidates decisions into `vX.Y-DECISIONS.md` and archives the rest, keeping `.planning/` tidy.
-- **Configurable code reviews.** Reviewers run after execution and at milestone audits, creating separate commits. Milestone reviews can be report-only — you decide what gets fixed.
-- **Design mockups.** `/ms:design-phase` generates parallel HTML/CSS mockup variants to explore visual directions before locking a design spec.
-- **Cross-milestone learnings.** Milestone completion extracts curated patterns into `LEARNINGS.md` so planning in future milestones starts smarter.
-- **Structured tech debt.** `/ms:audit-milestone` maintains `TECH-DEBT.md` — a single source of truth for debt items with severity, source, and suggested fixes.
+Claude reads your project history — tech debt, deferred requirements, validated decisions — and surfaces strategic directions. You articulate the vision. The output is a `MILESTONE-CONTEXT.md` that grounds everything downstream.
----
+This is dream extraction: Claude acts as product owner, helping you think through what to build next by asking the right questions rather than prescribing answers.
-## Mental Model
+### 2. Create Roadmap
 ```
-PLAN     You decide scope, design, and break work into small tasks
-           ↓
-EXECUTE  Fresh subagents run each task (commits + .patch files)
-           ↓
-VERIFY   You test manually, Mindsystem fixes inline, repeat until done
-           ↓
-SHIP     Audit milestone, archive decisions, start fresh
+/ms:create-roadmap
 ```
----
+Claude derives requirements from your milestone context, assigns each a `REQ-ID`, and maps them to phases with success criteria. You approve scope and phase grouping.
-## Installation
-```bash
-npx mindsystem-cc
-```
+Requirements define what must be TRUE when you ship, not what to build. This goal-backward framing means verification can check outcomes, not task completion.
-This adds Mindsystem slash commands to `~/.claude/` (global) or `./.claude/` (local).
+**Creates:** `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, phase directories.
-Restart Claude Code after installing so it picks up the new commands, then run:
+### 3. Discuss Phase (optional, recommended)
 ```
-/ms:help
+/ms:discuss-phase 1
 ```
-<details>
-<summary><strong>Non-interactive install (Docker, CI, scripts)</strong></summary>
+The most impactful human moment in the pipeline. Claude loads milestone context, feature knowledge files, and competitor research — then surfaces its assumptions with confidence levels. You validate intent, make tradeoff decisions, correct misunderstandings.
-```bash
-npx mindsystem-cc --global   # Install to ~/.claude/
-npx mindsystem-cc --local    # Install to ./.claude/
-```
+Everything downstream flows from decisions made here. The assumption-based briefing catches misalignment before a single line of code is written.
-</details>
+**Creates:** `CONTEXT.md` with vision, essentials, and reasoning-backed decisions.
-<details>
-<summary><strong>Staying updated</strong></summary>
-Inside Claude Code:
+### 4. Design Phase (optional)
 ```
-/ms:release-notes
+/ms:design-phase 1
 ```
-Or via npm:
+Claude generates parallel HTML/CSS mockup variants and a side-by-side comparison page that opens in your browser. You pick a direction, iterate with feedback.
-```bash
-npx mindsystem-cc@latest
+The output is a `DESIGN.md` with exact design tokens — hex colors, px spacing, font weights — not descriptions of what things should look like. Implementable, not interpretive.
+### 5. Research Phase (optional)
+```
+/ms:research-phase 1
 ```
-</details>
+Three parallel agents investigate simultaneously: one queries external documentation through Perplexity and Context7, one analyzes your codebase for existing patterns, one surveys community best practices. Claude synthesizes findings into `RESEARCH.md` with confidence levels and source attribution.
-<details>
-<summary><strong>Development installation</strong></summary>
+You resolve library conflicts if any arise. Otherwise, this phase runs with minimal input.
-Clone and run the installer locally:
+### 6. Plan Phase
-```bash
-git clone https://github.com/rolandtolnay/mindsystem.git
-cd mindsystem
-node bin/install.js --local
+```
+/ms:plan-phase 1
 ```
-This installs to `./.claude/` so you can test changes before contributing.
+Claude breaks the phase into tasks, groups them into plans targeting 25-45% of the context budget. Plans are pure markdown — no YAML frontmatter, no XML containers. The plan IS the executable prompt, with ~90% actionable content and ~10% structure.
-</details>
+Independent plans are grouped into waves for parallel execution. A risk score (0-100) flags complex plans for optional verification before you commit to running them.
----
+You approve the plan structure and can adjust granularity.
+**Creates:** `PLAN.md` files, `EXECUTION-ORDER.md`.
+### 7. Execute Phase
+```
+/ms:execute-phase 1
+```
-## Playbooks
+Fully autonomous. Each plan runs in a fresh subagent with the full context window available. Goal-backward verification checks that the phase achieved its intended outcome — not that tasks were marked complete.
-Replace `<N>` with the phase number you're working on.
+Configurable code review produces separate commits for review changes. Patch files are generated for manual inspection.
-### New project (greenfield)
+After execution, knowledge consolidation updates subsystem-scoped knowledge files. Future phases that touch the same subsystems start with accumulated context about decisions made, patterns established, and pitfalls encountered.
-**When:** You're starting fresh — new repo or blank slate.
+**Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, knowledge file updates.
-**Run:**
+### 8. Verify Work
 ```
-/ms:new-project
-/ms:research-project        # optional (recommended when domain is new)
-/ms:create-roadmap
-/ms:plan-phase 1
-/ms:execute-phase 1
+/ms:verify-work 1
 ```
-**What you'll get:**
+The quality gate. You run manual acceptance tests presented in batches of 4. Claude fixes issues inline or via subagent, then asks you to re-test until passing.
-- `.planning/PROJECT.md` — vision and constraints
-- `.planning/REQUIREMENTS.md` — checkable scope
-- `.planning/ROADMAP.md` + `.planning/STATE.md` — plan and project memory
+For hard-to-test scenarios — error states, loading screens, role-based views — mock generation creates temporary inline states without shipping test infrastructure.
-**Tip:** For UI-heavy phases, run `/ms:design-phase 1` before `/ms:plan-phase 1`.
+Fixes compound into knowledge files through automatic consolidation. This is where edge cases, UI tweaks, and small bugs get caught before moving on.
-### Existing project (brownfield adoption)
+**Creates:** `UAT.md`, `uat-fixes.patch`, knowledge file updates.
-**When:** You have a codebase and want Mindsystem to respect its structure, conventions, and tests.
+### 9. Repeat
-**Run:**
+Run steps 3-8 for each phase. Pick the preparation depth each phase needs.
+### 10. Audit Milestone
 ```
-/ms:map-codebase
-/ms:new-project
-/ms:research-project        # optional (use for new domain areas)
-/ms:create-roadmap
-/ms:plan-phase 1
-/ms:execute-phase 1
+/ms:audit-milestone
 ```
-**What you'll get:**
-- `.planning/codebase/*` — captured conventions and structure
-- `.planning/PROJECT.md` / `.planning/REQUIREMENTS.md` / `.planning/ROADMAP.md`
-### Add feature (existing product)
+Claude checks requirements coverage against `REQ-IDs`, spawns an integration checker for cross-phase wiring, aggregates untested UAT assumptions, and consolidates tech debt into `TECH-DEBT.md` with severity tiers and `TD-IDs`.
-**When:** You already have a `.planning/` folder and want to add a traceable feature.
+Optional code review with quality-phase decisions for high-impact findings — you decide what gets fixed vs. accepted as debt.
-**Run:**
+### 11. Complete Milestone
 ```
-/ms:add-phase "Feature: <short name>"
-/ms:discuss-phase <N>       # optional (lock intent before planning)
-/ms:design-phase <N>        # optional (UI-heavy)
-/ms:plan-phase <N>
-/ms:execute-phase <N>
+/ms:complete-milestone
 ```
-**What you'll get:**
+Full `PROJECT.md` evolution: validates core value proposition, moves shipped requirements to validated, triages deferred items. Archives the milestone to `.planning/milestones/{name}/` with the roadmap, requirements, and phase summaries.
-- `.planning/ROADMAP.md` updated with the new phase
-- `.planning/phases/<N>-*/<N>-01-PLAN.md` + `*-SUMMARY.md`
+Updates `MILESTONES.md` with stats and accomplishments. Clean slate for the next `/ms:new-milestone`.
-**Tip:** Use `/ms:insert-phase <after> "..."` instead of `/ms:add-phase` when work must happen _before_ the next planned phase.
+---
-### Work on feature (plan → execute → verify loop)
+## Features
-**When:** You want real confidence — implementation, review, and manual UAT.
+### Knowledge Compounding
-**Run:**
+The core differentiator. Subsystem-scoped knowledge files are enriched after every phase. Execute-phase consolidates implementation decisions. Verify-work compounds fixes and edge cases. `/ms:compound` catches out-of-pipeline work — direct Claude sessions, manual edits, merged branches.
-```
-/ms:plan-phase <N>
-/ms:execute-phase <N>
-/ms:verify-work <N>
-```
+The effect accumulates: phase 1 starts from scratch; phase 10 starts with a knowledge base that captures what works, what failed, and why.
-**What you'll get:**
+### Context Budget Management
-- `.planning/phases/<N>-*/<N>-changes.patch` — phase implementation diff
-- `.planning/phases/<N>-*/<N>-VERIFICATION.md` — phase goal verification report
-- `.planning/phases/<N>-*/<N>-UAT.md` + `<N>-uat-fixes.patch` — manual test log and fixes diff
+Plans target 25-45% of the context window. Execution runs in fresh subagents — no inherited drift from long planning conversations. The 50% rule ensures plans complete before quality degrades.
-**How it works:** `/ms:verify-work` fixes issues in-session (inline or via subagent), commits them as `fix(<N>-uat): ...`, and asks you to re-test.
+Orchestration metadata (wave grouping, dependencies) lives in `EXECUTION-ORDER.md`, separate from plans. Plans carry only what the executor needs: context, changes, verification, must-haves.
-**Tip:** For UI that works but feels off, run `/ms:review-design <scope>` to audit and improve quality.
+### Built-in Code Review
-### Fix bug
+Configurable per tier — adhoc, phase, or milestone. Runs after execution and produces separate commits for inspection. Ships with structural analysis (`ms-code-reviewer`) and clarity-focused simplification (`ms-code-simplifier`), but you can point any tier at your own custom reviewer agent via `.planning/config.json`.
-**When:** Something's broken and you want a structured investigation that survives `/clear`.
+### Structured Debugging
-**Run:**
+`/ms:debug` creates investigation state that persists across `/clear`. Scientific method: gather evidence, form hypotheses, test. Resume any debug session by running `/ms:debug` with no arguments. Archives resolved issues to `.planning/debug/resolved/`.
-```
-/ms:debug "Describe symptoms and what you observed"
-```
+### Adhoc Execution
-**Then route the fix:**
+Work that's too coherent for a todo but too small for formal phase planning. `/ms:adhoc` reads existing knowledge files, generates a standard-format plan, executes, reviews, and consolidates learnings — all in one context. Accepts Linear ticket IDs, todo file paths, or plain descriptions.
-- **Discovered work for this context:** `/ms:adhoc "Fix <bug>"`
-- **Must happen before next phase:** `/ms:insert-phase <after> "Hotfix: <bug>"` → `/ms:plan-phase <N>` → `/ms:execute-phase <N>`
-- **Belongs in current phase after verification gaps:** `/ms:plan-phase <N> --gaps` → `/ms:execute-phase <N>`
+### Design Mockups
-### Scope change (what to use when)
+`/ms:design-phase` generates parallel HTML/CSS variant mockups with a side-by-side comparison page. Design tokens in the output are exact values (hex, px, font-weight), not descriptions. `/ms:review-design` audits existing screens using screenshots for retroactive design improvement.
-**When:** You discover new work mid-stream.
+### Project Health
-| Situation                     | Command                          |
-| ----------------------------- | -------------------------------- |
-| Non-urgent work for later     | `/ms:add-phase "..."`            |
-| Urgent work before next phase | `/ms:insert-phase <after> "..."` |
-| Task to capture for later     | `/ms:add-todo "..."`             |
-| Discovered work to do now     | `/ms:adhoc "..."`              |
+`/ms:doctor` runs 10 health checks: subsystem vocabulary, directory structure, milestone naming, knowledge files, CLI wrappers, API keys, version freshness. Fixes are applied in dependency order with atomic commits. Safe to run repeatedly.
-### Milestone ship (finishing a version)
+### Smart Routing
-**When:** A version is ready and you want to lock it down cleanly.
+`/ms:progress` reads project state and tells you what to run next. Visual progress bar, recent work summary, pending todos, active debug sessions. Reconstructs `STATE.md` from artifacts if it's missing. Also detects available updates.
-**Run:**
+### Deferred Requirements
-```
-/ms:audit-milestone
-/ms:complete-milestone
-/ms:new-milestone
-```
+Requirements you want but haven't shipped track in `PROJECT.md` with origin milestone and deferral reason. `complete-milestone` triages them before archiving; `create-roadmap` consumes them as candidates for new milestones. Nothing falls through the cracks.
-**What you'll get:**
+### Task Capture
-- `.planning/milestones/mvp/` — archived milestone (ROADMAP, REQUIREMENTS, DECISIONS, research)
-- Active docs stay lean; full detail lives in the version folder
+`/ms:add-todo` with Linear-inspired metadata: priority (1-4), estimate (XS-XL), inferred subsystem. Todos live as flat files in `.planning/todos/`. Address them later via `/ms:adhoc`, which reads the problem description, executes the work, and moves the todo to `done/`.
-**Tip:** Milestone review can be **report-only** so you stay in control. Create a quality phase, or accept tech debt explicitly — your call.
+### Codebase Mapping
+`/ms:map-codebase` spawns 4 parallel agents producing 7 structured documents: stack, architecture, conventions, testing, integrations, directory structure, and concerns. Use on brownfield projects so Mindsystem respects your existing patterns.
 ---
-## Why This Works
+## Quick Start
-**Context rot is handled structurally.** The truth lives in `.planning/` files (scope, decisions, plans, verification), not buried in a scrolling chat.
+### New project
-**Execution stays sharp.** Plans are small by design and run in fresh subagents, so implementation doesn't inherit long-chat drift.
+```
+/ms:new-project
+/ms:create-roadmap
+/ms:plan-phase 1
+/ms:execute-phase 1
+/ms:verify-work 1
+```
-**Verification is built in.** Phase verification plus `/ms:verify-work` gives you a human-in-the-loop UAT loop with inline fixes and mock support.
+You'll get `.planning/` with your project vision, requirements, roadmap, and the first phase implemented with commits, patch files, and knowledge files.
+### Existing project
+```
+/ms:new-project
+/ms:map-codebase
+/ms:create-roadmap
+/ms:plan-phase 1
+/ms:execute-phase 1
+```
-**Review fits your workflow.** Changes become commits and `.patch` files. Milestone reviews can be report-only when you want full control.
+Codebase mapping produces 7 documents covering your stack, conventions, and architecture. All downstream planning and execution respects what's already there.
-**Planning docs stay readable.** Milestones consolidate and archive decisions so active files don't grow forever.
+**Returning after a break?** Run `/ms:progress` — it shows where you left off and what to do next.
 ---
 ## Configuration
-Mindsystem stores project config in `.planning/config.json`.
+Mindsystem stores project config in `.planning/config.json`. Run `/ms:config` to set up code reviewers, mockup preferences, gitignore patterns, and git remote.
-### Code review
-After `/ms:execute-phase` (and optionally `/ms:audit-milestone`), Mindsystem runs a reviewer that produces a **separate commit** for easy inspection.
+### Code review tiers
 ```json
 {
@@ -308,48 +279,70 @@ After `/ms:execute-phase` (and optionally `/ms:audit-milestone`), Mindsystem run
 }
 ```
-**Options:**
+| Value | Behavior |
+| ----- | -------- |
+| `null` | No reviewer (default) |
+| `"ms-code-reviewer"` | Structural analysis — architectural and design issues |
+| `"ms-code-simplifier"` | Clarity-focused — improves readability and maintainability |
+| `"skip"` | Disable review for that tier |
+---
-| Value                     | What it does                                                   |
-| ------------------------- | -------------------------------------------------------------- |
-| `null`                 | No reviewer (default)                                       |
-| `"ms-code-simplifier"` | Generic reviewer — improves clarity and maintainability      |
-| `"skip"`               | Disable review for that level                                |
+## Command Reference
+Full docs live in `/ms:help`.
+| Command | What it does |
+| ------- | ------------ |
+| `/ms:help` | Show the full command reference |
+| `/ms:progress` | Show where you are and what to run next |
+| `/ms:new-project` | Initialize `.planning/` and capture project intent |
+| `/ms:config` | Configure code reviewers, mockups, gitignore, git remote |
+| `/ms:map-codebase` | Document existing repo's stack, structure, and conventions |
+| `/ms:research-project` | Domain research saved to `.planning/research/` |
+| `/ms:create-roadmap` | Define requirements and create phases mapped to them |
+| `/ms:new-milestone [name]` | Discover what to build next, start new milestone |
+| `/ms:discuss-phase <number>` | Product-informed collaborative thinking before planning |
+| `/ms:design-phase <number>` | Generate UI/UX spec and optional HTML mockups |
+| `/ms:review-design [scope]` | Audit and improve existing UI quality |
+| `/ms:research-phase <number>` | Deep research for niche phase domains |
+| `/ms:plan-phase [number]` | Create context-budgeted plans with optional risk scoring |
+| `/ms:execute-phase <number>` | Run all unexecuted plans in fresh subagents |
+| `/ms:verify-work [number]` | Batched manual UAT with inline fixes |
+| `/ms:debug [description]` | Structured debugging that survives `/clear` |
+| `/ms:adhoc <description>` | Knowledge-aware execution for discovered work |
+| `/ms:compound [input]` | Compound out-of-pipeline changes into knowledge files |
+| `/ms:add-phase <description>` | Append a new phase to the roadmap |
+| `/ms:insert-phase <after> <description>` | Insert urgent work between phases |
+| `/ms:remove-phase <number>` | Delete a future phase and renumber |
+| `/ms:add-todo [description]` | Capture a task with priority, estimate, subsystem |
+| `/ms:audit-milestone [name]` | Audit completion and surface gaps |
+| `/ms:complete-milestone [name]` | Archive milestone and prepare for next |
+| `/ms:doctor` | Health check and fix project configuration |
+| `/ms:update` | Check for and install latest version |
+| `/ms:release-notes` | Show full release notes with update status |
 ---
-## Command Index (One-Liners)
-Full docs live in `/ms:help` (same content as `commands/ms/help.md`).
-| Command                                  | What it does                                                  |
-| ---------------------------------------- | ------------------------------------------------------------- |
-| `/ms:help`                               | Show the full command reference                               |
-| `/ms:progress`                           | Show where you are and what to run next                       |
-| `/ms:new-project`                        | Initialize `.planning/` and capture intent                    |
-| `/ms:map-codebase`                       | Document existing repo's stack, structure, and conventions    |
-| `/ms:research-project`                   | Do domain research and save findings to `.planning/research/` |
-| `/ms:create-roadmap`                     | Define requirements and create phases mapped to them          |
-| `/ms:discuss-phase <number>`             | Product-informed collaborative thinking before planning       |
-| `/ms:design-phase <number>`              | Generate UI/UX spec for UI-heavy work                         |
-| `/ms:review-design [scope]`              | Audit and improve existing UI quality                         |
-| `/ms:research-phase <number>`            | Do deep research for niche phase domains                      |
-| `/ms:plan-phase [number] [--gaps]`       | Create small, verifiable plans with optional risk-based verification |
-| `/ms:check-phase <number>`               | Sanity-check plans before execution                           |
-| `/ms:execute-phase <phase-number>`       | Run all unexecuted plans in fresh subagents                   |
-| `/ms:verify-work [number]`               | Batched manual UAT with inline fixes                          |
-| `/ms:debug [issue description]`          | Structured debugging that survives `/clear`                   |
-| `/ms:adhoc <description>`              | Execute discovered work with knowledge-aware planning         |
-| `/ms:add-phase <description>`            | Append a new phase to the roadmap                             |
-| `/ms:insert-phase <after> <description>` | Insert urgent work between phases                             |
-| `/ms:remove-phase <number>`              | Delete a future phase and renumber                            |
-| `/ms:audit-milestone [version]`          | Audit completion and surface gaps                             |
-| `/ms:complete-milestone <version>`       | Archive and consolidate decisions                             |
-| `/ms:new-milestone [name]`               | Discover what to build next, start new milestone              |
-| `/ms:add-todo [description]`             | Capture a deferred task in `.planning/todos/`                 |
-| `/ms:check-todos [area]`                 | List pending todos and route into work                        |
-| `/ms:doctor`                             | Health check and fix project configuration                    |
-| `/ms:release-notes`                      | Show full release notes with update status                    |
+## Updating
+Inside Claude Code:
+```
+/ms:update
+```
+Check what changed:
+```
+/ms:release-notes
+```
+From your terminal:
+```bash
+npx mindsystem-cc@latest
+```
 ---
@@ -365,6 +358,10 @@ Full docs live in `/ms:help` (same content as `commands/ms/help.md`).
 - Run `/ms:help` to verify installation.
 - Re-run `npx mindsystem-cc` to reinstall.
+**Outdated project structure after a major update?**
+- Run `/ms:doctor` to detect and fix stale artifacts, missing config fields, and directory structure changes between versions.
 **Updating to the latest version?**
 ```bash
@@ -376,11 +373,3 @@ npx mindsystem-cc@latest
 ## License
 MIT License. See [LICENSE](LICENSE) for details.
----
-<div align="center">
-**Claude Code is powerful. Mindsystem makes it reliable.**
-</div>

package/commands/ms/help.md CHANGED Viewed

@@ -61,7 +61,7 @@ Initialize → (Optional Research) → Roadmap → Plan → Execute → Verify
 Common deviations:
 - Existing repo: `/ms:map-codebase` after `/ms:new-project` (or before — either works)
-- Plan looks wrong: `/ms:discuss-phase <phase>` or `/ms:check-phase <phase>`
+- Plan looks wrong: `/ms:discuss-phase <phase>`
 - Unknown domain: `/ms:research-project` or `/ms:research-phase <phase>`
 - Phase prep: `/ms:discuss-phase` → `/ms:design-phase` → `/ms:research-phase` → `/ms:plan-phase` (all optional before plan)
 - Execution gaps: `/ms:plan-phase <phase> --gaps` then `/ms:execute-phase <phase>`
@@ -202,16 +202,6 @@ Usage: `/ms:execute-phase 5`
 ### Verification
-**`/ms:check-phase <number>`**
-Verify phase plans before execution (optional quality gate).
-- Use when: the phase is complex or risky and you want a “will this actually achieve the goal?” sanity check before executing.
-- Spawns plan checker agent to analyze PLAN.md files
-- Checks requirement coverage, task completeness, dependencies
-- Use for complex phases before committing to execution
-Usage: `/ms:check-phase 5`
 **`/ms:verify-work [number]`**
 User acceptance testing of phase or plan.
@@ -479,7 +469,6 @@ Usage: `/ms:release-notes`
 ```
 /ms:plan-phase 5                 # Create one or more PLAN.md files
-/ms:check-phase 5                # (optional) Sanity check: plans will achieve goal
 /ms:execute-phase 5              # Execute; produces SUMMARY + VERIFICATION
 # If gaps found during verification:
 /ms:plan-phase 5 --gaps          # Create additional plans to close verifier gaps

package/mindsystem/references/plan-format.md CHANGED Viewed

@@ -195,7 +195,7 @@ Execution order lives in a single `EXECUTION-ORDER.md` file alongside the plans.
 |----------|--------|
 | How does the verifier find must-haves? | Reads `## Must-Haves` section |
 | How does the executor know the subsystem? | Reads inline metadata (`**Subsystem:**`) |
-| How does the plan-checker validate plans? | Reads EXECUTION-ORDER.md + plan structure |
+| How is plan verification done? | Reads EXECUTION-ORDER.md + plan structure |
 | What triggers TDD lazy-loading? | `**Type:** tdd` in inline metadata |
 | How does the executor know why an approach was chosen? | Reads `## Context` section |
 | How does the executor find existing utilities? | Reads `**Files:**` lines and inline references in `## Changes` |

package/mindsystem/references/plan-risk-assessment.md CHANGED Viewed

@@ -2,7 +2,7 @@
 Optional verification step for plan-phase workflow. Calculates risk score from already-loaded context and prompts user to verify or skip.
 <purpose>
-Provide lightweight risk assessment after plan creation to help users decide whether to run the ms-plan-checker before execution.
+Provide lightweight risk assessment after plan creation to help users decide whether to run plan verification before execution.
 **Key principle:** All information is already in context from earlier workflow steps. No additional file reads or subagent spawns needed for scoring.
 </purpose>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/commands/ms/check-phase.md DELETED Viewed

@@ -1,134 +0,0 @@
----
-name: ms:check-phase
-description: Verify phase plans before execution (optional quality gate)
-arguments: phase
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Task
----
-<objective>
-On-demand plan verification. Use when a plan seems large or complex and you want a structured review before executing.
-This spawns ms-plan-checker to analyze your PLAN.md files against the phase goal.
-</objective>
-<what_it_checks>
-1. **Requirement Coverage** — Does every phase requirement have tasks addressing it?
-2. **Task Completeness** — Does every change have Files, implementation details, and verification?
-3. **Dependency Correctness** — Are plan dependencies valid and acyclic?
-4. **Key Links Planned** — Are artifacts wired together, not just created in isolation?
-5. **Scope Sanity** — Are plans reasonably sized for context budget (target 25-45%)?
-6. **Verification Derivation** — Are Must-Haves user-observable, not implementation-focused?
-7. **Context Compliance** — Do plans honor decisions from CONTEXT.md?
-</what_it_checks>
-<process>
-<step name="validate_phase">
-Phase number from $ARGUMENTS (required).
-```bash
-PHASE=$ARGUMENTS
-PADDED=$(printf "%02d" $PHASE 2>/dev/null || echo "$PHASE")
-PHASE_DIR=$(ls -d .planning/phases/${PADDED}-* .planning/phases/${PHASE}-* 2>/dev/null | head -1)
-if [ -z "$PHASE_DIR" ]; then
-  echo "Error: Phase $PHASE not found in .planning/phases/"
-  exit 1
-fi
-echo "Phase directory: $PHASE_DIR"
-ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
-```
-If no PLAN.md files found, remind user to run `/ms:plan-phase` first.
-</step>
-<step name="spawn_checker">
-Spawn the plan checker agent:
-```
-Task(
-  subagent_type="ms-plan-checker",
-  prompt="""
-Verify plans for phase $ARGUMENTS.
-1. Read .planning/ROADMAP.md to get the phase goal
-2. Read all *-PLAN.md files in the phase directory
-3. Read CONTEXT.md if it exists in the phase directory
-4. Run all 7 verification dimensions (dimension 7 only if CONTEXT.md exists)
-5. Return structured result
-Phase directory: $PHASE_DIR
-""",
-  description="Verify phase $ARGUMENTS plans"
-)
-```
-</step>
-<step name="present_results">
-Present the checker's findings clearly.
-**Format for VERIFICATION PASSED:**
-```
-## Plan Verification: PASSED
-Phase: [name] | Plans: [count] | Tasks: [total count]
-All checks passed.
-Ready to execute: `/ms:execute-phase $ARGUMENTS`
-```
-**Format for ISSUES FOUND:**
-```
-## Plan Verification: ISSUES FOUND
-Phase: [name] | Plans: [count] | Issues: [X blockers, Y warnings]
-### Blockers (must fix)
-1. **[dimension]** [description]
-   Plan: [which plan] | Fix: [specific fix hint]
-### Warnings (should fix)
-1. **[dimension]** [description]
-   Fix: [hint]
----
-Options:
-- Fix the issues and run `/ms:check-phase $ARGUMENTS` again
-- Proceed anyway: `/ms:execute-phase $ARGUMENTS` (not recommended if blockers exist)
-```
-</step>
-</process>
-<examples>
-**Check before executing a complex phase:**
-```
-/ms:check-phase 5
-```
-**Typical workflow:**
-```
-/ms:plan-phase 5      # Interactive planning in main context
-# ... review and iterate ...
-/ms:check-phase 5      # Optional verification for complex plans
-/ms:execute-phase 5   # Execute
-```
-</examples>
-<success_criteria>
-- Blockers and warnings presented distinctly — blockers have plan name and fix hint
-- Output includes actionable next command (`/ms:execute-phase` or `/ms:check-phase` rerun)
-- Checker agent spawned with correct phase directory path
-</success_criteria>