mindsystem-cc 3.6.0 → 3.10.1

package/README.md

@@ -2,12 +2,12 @@
 
 # MINDSYSTEM
 
-**A lightweight, opinionated spec-driven development system for Claude Code.**
-
-*Based on [GSD](https://github.com/glittercowboy/get-shit-done) by TÂCHES.*
+**Spec-driven development for Claude Code, built for engineers who ship production 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)
 
@@ -25,41 +25,59 @@ npx mindsystem-cc
 
 <br>
 
-[Why](#why-this-exists) · [Install](#installation) · [Quickstart](#quickstart) · [Workflows](#common-workflows) · [Commands](#command-index) · [Troubleshooting](#troubleshooting--advanced)
+[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)
 
 </div>
 
 ---
 
-## Why This Exists
+## 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."*
+> _"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)
 
-Mindsystem is a fork of GSD that shares the same “keep it simple” philosophy, but is tuned for a specific audience: **Claude Code power users who prefer to design in plain English**.
+This philosophy resonated. GSD proved that spec-driven development could be simple and effective.
 
-You already understand architecture, trade-offs, and quality. Mindsystem focuses on turning your intent into stable outputs over long sessions: it externalizes project memory into files and pushes execution into fresh contexts so quality stays high.
+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.
 
-## Philosophy
+Where GSD went broad, Mindsystem goes deep - more verification, more review checkpoints, more ways to inspect and override. Less magic, more engineering.
 
-### Opinionated, modular commands
-Mindsystem avoids mega-flows. Commands stay small, explicit, and composable — you pick the depth you need for this task (quick fix vs. new feature vs. UI-heavy system).
+### What you get
 
-### Collaboration stays in the main chat
-Planning and back-and-forth happen with you. Subagents are for autonomous execution, not for hiding key decisions or reasoning.
+- **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.
 
-### Scripts for mechanics, prompts for judgment
-Deterministic chores live in scripts; language models do what they’re good at: interpreting intent, making trade-offs, and writing code you can review.
+### Beyond the foundation
 
-## What's New (Fork Highlights)
+The original GSD established the philosophy and core infrastructure. Mindsystem extends it with features you'll actually need when shipping production code:
 
-- **Quality-control pipeline**: execution produces reviewable artifacts and verification steps.
-- **Design phase**: `/ms:design-phase` generates a UI/UX spec (flows, components, wireframes) before implementation.
-- **Research tooling**: `scripts/ms-lookup/` can be used standalone or inside workflows.
-- **Enhanced verification**: better UAT batching and debugging support when gaps are found.
-- **Automatic code review**: after phase execution (and optionally at milestone completion), a code review agent reviews code for clarity and maintainability. Stack-aware (Flutter gets specialized guidance) with generic fallback. Produces separate commit for easy review. See [Configuration](#configuration).
-- **Skills distribution**: bundled skills (like `flutter-senior-review`) are installed to `~/.claude/skills/` and provide domain-specific expertise for code reviews and audits.
+- **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.
+
+---
+
+## Mental Model
+
+```
+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
+```
 
 ---
 
@@ -69,30 +87,31 @@ Deterministic chores live in scripts; language models do what they’re good at:
 npx mindsystem-cc
 ```
 
-This installs Mindsystem slash commands into `~/.claude/` (global) or `./.claude/` (local).
+This adds Mindsystem slash commands to `~/.claude/` (global) or `./.claude/` (local).
 
-After install, restart Claude Code (so it reloads slash commands) and verify with:
+Restart Claude Code after installing so it picks up the new commands, then run:
 
 ```
 /ms:help
 ```
 
-### Non-interactive install (Docker, CI, scripts)
+<details>
+<summary><strong>Non-interactive install (Docker, CI, scripts)</strong></summary>
 
 ```bash
 npx mindsystem-cc --global   # Install to ~/.claude/
 npx mindsystem-cc --local    # Install to ./.claude/
 ```
 
-Use `--global` (`-g`) or `--local` (`-l`) to skip the interactive prompt.
+</details>
 
-### Staying updated
+<details>
+<summary><strong>Staying updated</strong></summary>
 
 Inside Claude Code:
 
 ```
-/ms:whats-new
-/ms:update
+/ms:release-notes
 ```
 
 Or via npm:
@@ -101,9 +120,12 @@ Or via npm:
 npx mindsystem-cc@latest
 ```
 
-### Development installation
+</details>
+
+<details>
+<summary><strong>Development installation</strong></summary>
 
-Clone the repository and run the installer locally:
+Clone and run the installer locally:
 
 ```bash
 git clone https://github.com/rolandtolnay/mindsystem.git
@@ -111,180 +133,170 @@ cd mindsystem
 node bin/install.js --local
 ```
 
-Installs to `./.claude/` for testing modifications before contributing.
+This installs to `./.claude/` so you can test changes before contributing.
 
----
+</details>
 
-## Quickstart
+---
 
-### New project (greenfield MVP)
+## Playbooks
 
-```
-/ms:new-project
-/ms:research-project
-/ms:define-requirements
-/ms:create-roadmap
-/ms:plan-phase 1
-/ms:execute-phase 1
-```
+Replace `<N>` with the phase number you're working on.
 
-At a high level: `/ms:new-project` captures intent and creates the project workspace, `/ms:research-project` pulls in ecosystem knowledge and common pitfalls, `/ms:define-requirements` turns “what you want” into checkable scope, and `/ms:create-roadmap` converts that scope into phases plus persistent project memory. `/ms:plan-phase` then breaks a phase into small, verifiable tasks, and `/ms:execute-phase` runs those tasks in fresh subagent contexts with verification and reviewable artifacts. The payoff is less context rot, fewer forgotten decisions, and more repeatable output than “just keep chatting until it works”.
+### New project (greenfield)
 
-`/ms:research-project` is part of the default flow. Skip it only when you already know the domain and stack choices.
+**When:** You're starting fresh — new repo or blank slate.
 
-### Existing project (brownfield)
+**Run:**
 
 ```
-/ms:map-codebase
 /ms:new-project
-/ms:research-project
-/ms:define-requirements
+/ms:research-project        # optional (recommended when domain is new)
 /ms:create-roadmap
 /ms:plan-phase 1
 /ms:execute-phase 1
 ```
 
-`/ms:map-codebase` is the “adoption” step: it teaches Mindsystem your repo’s conventions, structure, and testing patterns so plans land in the right places.
+**What you'll get:**
 
----
+- `.planning/PROJECT.md` — vision and constraints
+- `.planning/REQUIREMENTS.md` — checkable scope
+- `.planning/ROADMAP.md` + `.planning/STATE.md` — plan and project memory
 
-## Common Workflows
+**Tip:** For UI-heavy phases, run `/ms:design-phase 1` before `/ms:plan-phase 1`.
 
-Replace `<N>` with the phase you’re working on (usually `1` when you’re starting).
+### Existing project (brownfield adoption)
 
-### 1) Ship an MVP (fast, structured)
+**When:** You have a codebase and want Mindsystem to respect its structure, conventions, and tests.
+
+**Run:**
 
 ```
+/ms:map-codebase
 /ms:new-project
-/ms:define-requirements
+/ms:research-project        # optional (use for new domain areas)
 /ms:create-roadmap
 /ms:plan-phase 1
 /ms:execute-phase 1
 ```
 
-Use when you already know the shape of the product and want momentum with guardrails (planning + verification).
+**What you'll get:**
+
+- `.planning/codebase/*` — captured conventions and structure
+- `.planning/PROJECT.md` / `.planning/REQUIREMENTS.md` / `.planning/ROADMAP.md`
 
-### 2) Add a feature to an existing codebase
+### Add feature (existing product)
+
+**When:** You already have a `.planning/` folder and want to add a traceable feature.
+
+**Run:**
 
 ```
-/ms:map-codebase
-/ms:new-project
-/ms:discuss-phase <N>
+/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>
 ```
 
-Use `/ms:discuss-phase` when you have strong opinions about UX/behavior and want them captured before planning.
+**What you'll get:**
+
+- `.planning/ROADMAP.md` updated with the new phase
+- `.planning/phases/<N>-*/<N>-01-PLAN.md` + `*-SUMMARY.md`
 
-### 3) Fix a bug / hotfix with traceability
+**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)
+
+**When:** You want real confidence — implementation, review, and manual UAT.
+
+**Run:**
 
 ```
-/ms:debug "Describe the bug and what you observed"
-/ms:insert-phase <after> "Hotfix: <short description>"
 /ms:plan-phase <N>
 /ms:execute-phase <N>
+/ms:verify-work <N>
 ```
 
-If execution verifies with gaps:
+**What you'll get:**
 
-```
-/ms:plan-phase <N> --gaps
-/ms:execute-phase <N>
-```
+- `.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
+
+**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.
+
+**Tip:** For UI that works but feels off, run `/ms:review-design <scope>` to audit and improve quality.
+
+### Fix bug
+
+**When:** Something's broken and you want a structured investigation that survives `/clear`.
 
-### 4) Complex UI/UX feature (design first)
+**Run:**
 
 ```
-/ms:discuss-phase <N>
-/ms:design-phase <N>
-/ms:plan-phase <N>
-/ms:execute-phase <N>
-/ms:verify-work <N>
+/ms:debug "Describe symptoms and what you observed"
 ```
 
-Use when the UI is the product (new interaction patterns, multiple screens, hard edge cases). Design is optional; this is the “pay the thinking cost up front” path.
+**Then route the fix:**
+
+- **Small and urgent (1–2 tasks):** `/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>`
+
+### Scope change (what to use when)
+
+**When:** You discover new work mid-stream.
 
-`/ms:verify-work` guides you through manual UI verification (UAT). When issues are found, it can spin up subagents to investigate and fix them, then re-present the checks until you’re satisfied.
+| 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 "..."`             |
+| Small fix to do right now     | `/ms:adhoc "..."`              |
 
-### 5) Milestone-driven iteration in an existing product
+### Milestone ship (finishing a version)
+
+**When:** A version is ready and you want to lock it down cleanly.
+
+**Run:**
 
 ```
 /ms:audit-milestone 1.0.0
 /ms:complete-milestone 1.0.0
 /ms:new-milestone "v1.1"
-/ms:add-phase "Next feature"
 ```
 
-Use when you’re shipping continuously: audit what’s “actually done”, archive cleanly, then start the next milestone with explicit phases.
+**What you'll get:**
 
----
+- `.planning/milestones/v1.0-DECISIONS.md` — consolidated decisions for future reference
+- `.planning/milestones/v1.0-ROADMAP.md` / `v1.0-REQUIREMENTS.md` — archived detail to keep active docs lean
 
-## Appendix: How Mindsystem Works (High-Level)
+**Tip:** Milestone review can be **report-only** (e.g., Flutter structural review) so you stay in control. Create a quality phase, or accept tech debt explicitly — your call.
 
-### Context rot → external memory
-Long Claude Code sessions degrade. Mindsystem pushes project “truth” into files that persist across sessions (vision, requirements, roadmap, state, plans), so you’re not relying on chat history as the only source of reality.
+---
 
-### Fresh contexts for execution
-Planning and discussion happen with you; execution happens in fresh subagent contexts, so implementation doesn’t inherit the accumulated noise of a long conversation.
+## Why This Works
 
-### Small plans + verification loops
-Mindsystem keeps plans intentionally small and explicit, with concrete “verify” criteria. When verification finds gaps, you can generate targeted follow-up work (e.g. `/ms:plan-phase <N> --gaps`). For UI-heavy work, `/ms:verify-work` guides manual UAT and can use subagents to investigate and fix issues as they’re found.
+**Context rot is handled structurally.** The truth lives in `.planning/` files (scope, decisions, plans, verification), not buried in a scrolling chat.
 
-If you want the authoritative, up-to-date guide, run `/ms:help` inside Claude Code (or read `commands/ms/help.md`).
+**Execution stays sharp.** Plans are small by design and run in fresh subagents, so implementation doesn't inherit long-chat drift.
 
----
+**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.
 
-## Command Index
-
-Commands are grouped by workflow domain (start → plan → execute → ship → maintain).
-
-| Command | What it does |
-|--------:|--------------|
-| `/ms:help` | Show the full command reference and usage guide. |
-| `/ms:progress` | Show where you are and what’s next. |
-| `/ms:new-project` | Initialize `.planning/` and capture project intent. |
-| `/ms:map-codebase` | Analyze an existing repo and capture conventions + structure. |
-| `/ms:research-project` | Research the overall domain ecosystem (optional). |
-| `/ms:define-requirements` | Scope v1/v2/out-of-scope requirements with checkboxes. |
-| `/ms:create-roadmap` | Create roadmap phases and persistent state tracking. |
-|  |  |
-| `/ms:discuss-phase <N>` | Gather context before planning a phase. |
-| `/ms:list-phase-assumptions <N>` | Show what Claude assumes before planning/execution. |
-| `/ms:research-phase <N>` | Deep research for unfamiliar or niche phase domains. |
-| `/ms:design-phase <N>` | Produce a UI/UX design spec for a phase. |
-| `/ms:plan-phase [N] [--gaps]` | Generate task plans for a phase (or close gaps). |
-| `/ms:check-phase <N>` | Verify phase plans before execution (optional). |
-|  |  |
-| `/ms:execute-phase <N>` | Execute all plans in a phase (parallel, checkpointed). |
-| `/ms:verify-work [N]` | User acceptance test of a phase or a plan. |
-| `/ms:debug [desc]` | Run a systematic debugging workflow with persistent state. |
-| `/ms:review-design [scope]` | Audit and improve design quality of implemented features. |
-| `/ms:do-work <desc>` | Execute small discovered work (kept intentionally small). |
-|  |  |
-| `/ms:add-phase <desc>` | Append a phase to the roadmap. |
-| `/ms:insert-phase <after> <desc>` | Insert urgent work between phases (renumbers). |
-| `/ms:remove-phase <N>` | Remove a future phase and renumber subsequent phases. |
-|  |  |
-| `/ms:discuss-milestone` | Gather context for the next milestone. |
-| `/ms:new-milestone [name]` | Create a new milestone with phases. |
-| `/ms:audit-milestone [version]` | Audit milestone completion before archiving. |
-| `/ms:complete-milestone <version>` | Archive the milestone and prep the next version. |
-| `/ms:plan-milestone-gaps` | Create phases to close gaps from a milestone audit. |
-|  |  |
-| `/ms:add-todo [desc]` | Capture an idea/task for later. |
-| `/ms:check-todos [area]` | List pending todos and pick one to work on. |
-| `/ms:whats-new` | See what changed since your installed version. |
-| `/ms:update` | Update Mindsystem and show the changelog. |
+**Review fits your workflow.** Changes become commits and `.patch` files. Milestone reviews can be report-only when you want full control.
+
+**Planning docs stay readable.** Milestones consolidate and archive decisions so active files don't grow forever.
 
 ---
 
 ## Configuration
 
-Mindsystem stores project configuration in `.planning/config.json`. This file is created when you initialize a project and can be edited to customize behavior.
+Mindsystem stores project config in `.planning/config.json`.
 
-### Code Review
+### Code review
 
-After phase execution (and optionally at milestone completion), Mindsystem runs a code review agent to review changes for clarity and maintainability. Configure this in `config.json`:
+After `/ms:execute-phase` (and optionally `/ms:audit-milestone`), Mindsystem runs a reviewer that produces a **separate commit** for easy inspection.
 
 ```json
 {
@@ -296,106 +308,77 @@ After phase execution (and optionally at milestone completion), Mindsystem runs
 }
 ```
 
-**Configuration levels:**
+**Options:**
 
-| Level | When it runs | Config key | Default |
-|-------|--------------|------------|---------|
-| Adhoc | After `/ms:do-work` completes | `code_review.adhoc` | Falls back to `phase`, then `ms-code-simplifier` |
-| Phase | After `/ms:execute-phase` completes | `code_review.phase` | `ms-code-simplifier` |
-| Milestone | After `/ms:audit-milestone` completes | `code_review.milestone` | `ms-flutter-reviewer` |
+| Value                     | What it does                                                   |
+| ------------------------- | -------------------------------------------------------------- |
+| `null`                    | Use the default (stack-aware when available)                   |
+| `"ms-code-simplifier"`    | Generic reviewer — improves clarity and maintainability        |
+| `"ms-flutter-simplifier"` | Flutter/Dart-specific — strong widget and Riverpod conventions |
+| `"ms-flutter-reviewer"`   | Flutter structural analysis (report-only, no code changes)     |
+| `"skip"`                  | Disable review for that level                                  |
 
-**Available values for each level:**
+**Flutter-specific tools (built-in):**
 
-| Value | Behavior |
-|-------|----------|
-| `null` (default) | Uses level-specific default (see table above) |
-| `"ms-flutter-simplifier"` | Flutter/Dart-specific reviewer with Riverpod and widget patterns |
-| `"ms-flutter-reviewer"` | Flutter/Dart structural analysis (reports only, does not modify code). When used at milestone level, offers binary choice: create quality phase or accept as tech debt. |
-| `"ms-code-simplifier"` | Generic code reviewer for any language |
-| `"skip"` | Skip code review at this level |
-| `"my-custom-agent"` | Use any custom agent you've defined |
+- **`ms-flutter-simplifier`** — pragmatic refactors that preserve behavior
+- **`ms-flutter-reviewer`** — milestone-level structural audit with actionable report (you control the fixes)
+- **`flutter-senior-review` skill** — domain principles that raise review quality beyond generic lint advice
 
-**Example: Flutter project with separate adhoc and phase reviewers**
-```json
-{
-  "code_review": {
-    "adhoc": "ms-flutter-simplifier",
-    "phase": "ms-flutter-simplifier",
-    "milestone": "ms-flutter-reviewer"
-  }
-}
-```
-
-**Example: Skip all code review**
-```json
-{
-  "code_review": {
-    "adhoc": "skip",
-    "phase": "skip",
-    "milestone": "skip"
-  }
-}
-```
+---
 
-Code review runs automatically and creates a separate commit for easy review. Changes are purely cosmetic (clarity, consistency) — functionality is preserved.
+## 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>`             | Lock intent and constraints 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:list-phase-assumptions <number>`    | Show what Mindsystem assumes before planning                  |
+| `/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 a small fix now with review                           |
+| `/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:plan-milestone-gaps`                | Turn audit gaps into fix phases                               |
+| `/ms:add-todo [description]`             | Capture a deferred task in `.planning/todos/`                 |
+| `/ms:check-todos [area]`                 | List pending todos and route into work                        |
+| `/ms:release-notes`                      | Show full release notes with update status                    |
 
 ---
 
-## Troubleshooting & Advanced
+## Troubleshooting
 
 **Commands not found after install?**
+
 - Restart Claude Code to reload slash commands.
-- Verify files exist in `~/.claude/commands/ms/` (global) or `./.claude/commands/ms/` (local).
+- Check that files exist in `~/.claude/commands/ms/` (global) or `./.claude/commands/ms/` (local).
 
 **Commands not working as expected?**
+
 - Run `/ms:help` to verify installation.
 - Re-run `npx mindsystem-cc` to reinstall.
 
 **Updating to the latest version?**
-```bash
-npx mindsystem-cc@latest
-```
-
-<details>
-<summary><strong>Claude Code permissions (optional)</strong></summary>
 
-If you use Claude Code’s permissions allowlist, you can add a small set of shell commands Mindsystem commonly needs. Example:
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(date:*)",
-      "Bash(echo:*)",
-      "Bash(cat:*)",
-      "Bash(ls:*)",
-      "Bash(mkdir:*)",
-      "Bash(wc:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(sort:*)",
-      "Bash(grep:*)",
-      "Bash(tr:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git status:*)",
-      "Bash(git log:*)",
-      "Bash(git diff:*)",
-      "Bash(git tag:*)"
-    ]
-  }
-}
-```
-
-</details>
-
-**Using Docker or containerized environments?**
-
-If file reads fail with tilde paths (`~/.claude/...`), set `CLAUDE_CONFIG_DIR` before installing:
 ```bash
-CLAUDE_CONFIG_DIR=/home/youruser/.claude npx mindsystem-cc --global
+npx mindsystem-cc@latest
 ```
-This ensures absolute paths are used instead of `~` which may not expand correctly in containers.
 
 ---
 

package/agents/ms-code-simplifier.md

@@ -1,6 +1,6 @@
 ---
 name: ms-code-simplifier
-description: Simplifies code for clarity, consistency, and maintainability. Technology-agnostic fallback simplifier spawned by execute-phase/do-work after code changes.
+description: Simplifies code for clarity, consistency, and maintainability. Technology-agnostic fallback simplifier spawned by execute-phase/adhoc after code changes.
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: cyan