mindsystem-cc 4.0.1 → 4.0.2

package/README.md

@@ -4,7 +4,7 @@
 
 **A meta-prompting and context engineering system for Claude Code.**
 
-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.
+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`. Context rot stops being the bottleneck. Every prompt in the system is tested against research on how LLMs actually follow instructions, so quality stays consistent from phase 1 to phase 20.
 
 ```bash
 npx mindsystem-cc
@@ -19,57 +19,70 @@ npx mindsystem-cc
 
 <br>
 
-[How It Works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick Start](#quick-start) · [Config](#configuration) · [Commands](#command-reference) · [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>
 
 ---
 
-## How It Works
-
-```
-  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
-```
-
-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.
-
-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.
+## How it works
+
+```
+[ new-milestone ]       Define what to build next
+        │
+        ▼
+[ create-roadmap ]      Derive requirements, map to phases
+        │
+        ▼
+╔══════════════════════════════════════════════════════════════════╗
+║ Per Phase:                                                       ║
+║                                                                  ║
+║ [ discuss-phase ]       (optional) Lock intent, validate context ║
+║         │                                                        ║
+║         ▼                                                        ║
+║ [ design-phase ]        (optional) Generate mockups, pick path   ║
+║         │                                                        ║
+║         ▼                                                        ║
+║ [ research-phase ]      (optional) External docs, code patterns  ║
+║         │                                                        ║
+║         ▼                                                        ║
+║ [ plan-phase ]          Break into context-budgeted plans        ║
+║         │                                                        ║
+║         ▼                                                        ║
+║ [ execute-phase ]       Fresh subagents run each plan            ║
+║         │                                                        ║
+║         ▼                                                        ║
+║ [ verify-work ]         Manual acceptance tests, inline fixes    ║
+║         │                                                        ║
+║         └────── repeat for next phase ──────────────────────┐    ║
+╚═════════╦═══════════════════════════════════════════════════╧════╝
+          │
+          ▼
+[ audit-milestone ]     Check requirements coverage, surface tech debt
+          │
+          ▼
+[ complete-milestone ]  Archive, evolve PROJECT.md, start fresh
+```
+
+Each phase gets its own preparation depth. A database migration might skip straight to planning. A user-facing feature might need discussion, design mockups, and research first. You pick the depth.
+
+Execution happens in fresh subagent contexts, so each plan gets up to 200k tokens of headroom regardless of how much planning happened in the main conversation.
 
 ---
 
-## End-to-End Walkthrough
+## End-to-end walkthrough
 
-### 1. New Milestone
+### 1. New milestone
 
 ```
 /ms:new-milestone
 ```
 
-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.
+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.
+Think of it as guided brainstorming: Claude asks the right questions rather than prescribing answers, helping you figure out what to build next.
 
-### 2. Create Roadmap
+### 2. Create roadmap
 
 ```
 /ms:create-roadmap
@@ -77,23 +90,23 @@ This is dream extraction: Claude acts as product owner, helping you think throug
 
 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.
 
-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.
+Requirements define what must be TRUE when you ship, not what to build. This goal-backward framing means verification checks outcomes, not task completion.
 
 **Creates:** `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, phase directories.
 
-### 3. Discuss Phase (optional, recommended)
+### 3. Discuss phase (optional, recommended)
 
 ```
 /ms:discuss-phase 1
 ```
 
-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.
+This is where you catch misalignment before writing any code. 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.
 
-Everything downstream flows from decisions made here. The assumption-based briefing catches misalignment before a single line of code is written.
+Worth taking seriously. Decisions here propagate through everything that follows.
 
 **Creates:** `CONTEXT.md` with vision, essentials, and reasoning-backed decisions.
 
-### 4. Design Phase (optional)
+### 4. Design phase (optional)
 
 ```
 /ms:design-phase 1
@@ -101,55 +114,55 @@ Everything downstream flows from decisions made here. The assumption-based brief
 
 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.
 
-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.
+The output is a `DESIGN.md` with exact design tokens (hex colors, px spacing, font weights), not descriptions of what things should look like.
 
-### 5. Research Phase (optional)
+### 5. Research phase (optional)
 
 ```
 /ms:research-phase 1
 ```
 
-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.
+Three parallel agents investigate at once: 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.
 
-You resolve library conflicts if any arise. Otherwise, this phase runs with minimal input.
+You resolve library conflicts if any come up. Otherwise, this runs with minimal input.
 
-### 6. Plan Phase
+### 6. Plan phase
 
 ```
 /ms:plan-phase 1
 ```
 
-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.
+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, roughly 90% actionable content and 10% structure.
 
-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.
+Independent plans get grouped into waves for parallel execution. A risk score (0-100) flags complex plans so you can verify them before committing.
 
 You approve the plan structure and can adjust granularity.
 
 **Creates:** `PLAN.md` files, `EXECUTION-ORDER.md`.
 
-### 7. Execute Phase
+### 7. Execute phase
 
 ```
 /ms:execute-phase 1
 ```
 
-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.
+Runs without intervention. 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 just that tasks got marked complete.
 
 Configurable code review produces separate commits for review changes. Patch files are generated for manual inspection.
 
-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.
+After execution, knowledge consolidation updates subsystem-scoped knowledge files. Future phases touching the same subsystems start with accumulated context: decisions made, patterns established, pitfalls encountered.
 
 **Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, knowledge file updates.
 
-### 8. Verify Work
+### 8. Verify work
 
 ```
 /ms:verify-work 1
 ```
 
-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.
+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.
 
-For hard-to-test scenarios — error states, loading screens, role-based views — mock generation creates temporary inline states without shipping test infrastructure.
+For hard-to-test scenarios (error states, loading screens, role-based views), mock generation creates temporary inline states without shipping test infrastructure.
 
 Fixes compound into knowledge files through automatic consolidation. This is where edge cases, UI tweaks, and small bugs get caught before moving on.
 
@@ -159,7 +172,7 @@ Fixes compound into knowledge files through automatic consolidation. This is whe
 
 Run steps 3-8 for each phase. Pick the preparation depth each phase needs.
 
-### 10. Audit Milestone
+### 10. Audit milestone
 
 ```
 /ms:audit-milestone
@@ -167,9 +180,9 @@ Run steps 3-8 for each phase. Pick the preparation depth each phase needs.
 
 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`.
 
-Optional code review with quality-phase decisions for high-impact findings — you decide what gets fixed vs. accepted as debt.
+Optional code review with quality-phase decisions for high-impact findings. You decide what gets fixed vs. accepted as debt.
 
-### 11. Complete Milestone
+### 11. Complete milestone
 
 ```
 /ms:complete-milestone
@@ -177,118 +190,138 @@ Optional code review with quality-phase decisions for high-impact findings — y
 
 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.
 
-Updates `MILESTONES.md` with stats and accomplishments. Clean slate for the next `/ms:new-milestone`.
+Updates `MILESTONES.md` with stats and accomplishments. Fresh start for the next `/ms:new-milestone`.
 
 ---
 
 ## Features
 
-### Knowledge Compounding
+### Knowledge compounding
 
-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.
+This is the thing that makes the whole system worth using. Subsystem-scoped knowledge files get enriched after every phase. Execute-phase consolidates implementation decisions. Verify-work compounds fixes and edge cases. `/ms:compound` catches out-of-pipeline work like direct Claude sessions, manual edits, or merged branches.
 
-The effect accumulates: phase 1 starts from scratch; phase 10 starts with a knowledge base that captures what works, what failed, and why.
+Phase 1 starts from scratch. Phase 10 starts with a knowledge base that knows what works, what failed, and why.
 
-### Context Budget Management
+### Context budget management
 
-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.
+Plans target 25-45% of the context window. Execution runs in fresh subagents with no inherited drift from long planning conversations. The 50% rule ensures plans complete before quality degrades.
 
 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.
 
-### Built-in Code Review
+### Research-backed prompts
+
+Unnecessary instructions aren't wasted space — they interfere with the ones that matter. Each instruction passes a reliability test: does removing this degrade output in the actual runtime context? Every command, workflow, and agent definition gets audited to cut that interference. Audited agents show 35-39% context reduction with no behavioral regression.
 
-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`.
+### Built-in code review
 
-### Structured Debugging
+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`.
+
+### Structured debugging
 
 `/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/`.
 
-### Adhoc Execution
+### Adhoc execution
 
-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.
+For work that's too coherent for a todo but too small for a full phase. `/ms:adhoc` reads existing knowledge files, generates a plan, executes, reviews, and consolidates learnings in one context. Accepts Linear ticket IDs, todo file paths, or plain descriptions.
 
-### Design Mockups
+### Design mockups
 
 `/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.
 
-### Project Health
+### Project health
 
 `/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.
 
-### Smart Routing
+### Smart routing
 
 `/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.
 
-### Deferred Requirements
+### Deferred requirements
 
-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.
+Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with origin milestone and deferral reason. `complete-milestone` triages them before archiving. `create-roadmap` picks them up as candidates for new milestones. They don't get lost.
 
-### Task Capture
+### Task capture
 
 `/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/`.
 
-### Codebase Mapping
+### 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.
 
 ---
 
-## Quick Start
+## Quick start
 
 ### New project
 
 ```
 /ms:new-project
+/ms:new-milestone
 /ms:create-roadmap
 /ms:plan-phase 1
 /ms:execute-phase 1
 /ms:verify-work 1
 ```
 
-You'll get `.planning/` with your project vision, requirements, roadmap, and the first phase implemented with commits, patch files, and knowledge files.
+You'll get `.planning/` with your project vision, milestone context, requirements, roadmap, and the first phase implemented with commits, patch files, and knowledge files.
 
 ### Existing project
 
 ```
 /ms:new-project
 /ms:map-codebase
+/ms:new-milestone
 /ms:create-roadmap
 /ms:plan-phase 1
 /ms:execute-phase 1
 ```
 
-Codebase mapping produces 7 documents covering your stack, conventions, and architecture. All downstream planning and execution respects what's already there.
+Codebase mapping produces 7 documents covering your stack, conventions, and architecture. Then you define what to build, and all downstream planning respects what's already there.
 
-**Returning after a break?** Run `/ms:progress` — it shows where you left off and what to do next.
+**Returning after a break?** Run `/ms:progress` to see where you left off and what to do next.
 
 ---
 
 ## Configuration
 
-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 tiers
+Mindsystem stores project config in `.planning/config.json`. Run `/ms:config` to change these interactively.
 
-```json
+```jsonc
 {
+  // Canonical subsystem names. Drives knowledge file scoping.
+  // Populated by /ms:new-project, refined by /ms:doctor.
+  "subsystems": ["auth", "api", "database"],
+
+  // Code review after execution. One reviewer per tier.
+  //   null                  → falls back to "ms-code-simplifier" (default)
+  //   "ms-code-reviewer"    → structural: architecture and design issues
+  //   "ms-code-simplifier"  → clarity: readability and maintainability
+  //   "skip"                → explicitly disable review
+  //   "<custom-agent>"      → your own reviewer agent
   "code_review": {
     "adhoc": null,
     "phase": null,
     "milestone": null
+  },
+
+  // How /ms:design-phase opens the mockup comparison page.
+  //   "auto" (default) | "ask" | "off"
+  "open_mockups": "auto",
+
+  // External task tracker integration (Linear only for now).
+  //   null → disabled (default)
+  "task_tracker": {
+    "type": "linear",
+    "cli": "path/to/linear-cli"
   }
 }
 ```
 
-| 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 |
+Linear integration requires the [Linear CLI skill](https://github.com/rolandtolnay/llm-toolkit/tree/main/skills/linear). Point `task_tracker.cli` at the downloaded script.
 
 ---
 
-## Command Reference
+## Command reference
 
 Full docs live in `/ms:help`.
 
@@ -373,3 +406,7 @@ npx mindsystem-cc@latest
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+Inspired by [GSD](https://github.com/gsd-build/get-shit-done) and [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin).

package/agents/ms-debugger.md

@@ -12,7 +12,6 @@ You are a Mindsystem debugger. You investigate bugs using systematic scientific
 You are spawned by:
 
 - `/ms:debug` command (interactive debugging)
-- `diagnose-issues` workflow (parallel UAT diagnosis)
 
 Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode).
 
@@ -94,7 +93,7 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 2. `mkdir -p .planning/debug`
 3. Read project context for frontmatter:
    ```bash
-   jq -r '.subsystems[]' .planning/config.json 2>/dev/null
+   ms-tools config-get subsystems
    grep "^Phase:" .planning/STATE.md 2>/dev/null | head -1
    ```
 4. Create file with initial state including all 10 frontmatter fields:
@@ -368,7 +367,7 @@ Check for mode flags in prompt context:
 - Diagnose but don't fix
 - Stop after confirming root cause
 - Skip fix_and_verify step
-- Return root cause to caller (for plan-phase --gaps to handle)
+- Return root cause to caller
 
 **goal: find_and_fix** (default)
 - Find root cause, then fix and verify

package/agents/ms-verifier.md

@@ -257,7 +257,7 @@ score = (verified_truths / total_truths)
 
 ## Step 9: Structure Gap Output (If Gaps Found)
 
-When gaps are found, structure them in YAML frontmatter for consumption by `/ms:plan-phase --gaps`. Use the `gaps:` format shown in the VERIFICATION.md template below.
+When gaps are found, structure them in YAML frontmatter for gap triage. Use the `gaps:` format shown in the VERIFICATION.md template below.
 
 **Gap fields:** `truth` (observable truth that failed), `status` (failed | partial), `reason` (why it failed), `artifacts` (files with issues), `missing` (specific things to add/fix).
 
@@ -383,7 +383,7 @@ Consider `/ms:verify-work {phase}` to validate these through UAT.
 2. **{Truth 2}** — {reason}
    - Missing: {what needs to be added}
 
-Structured gaps in VERIFICATION.md frontmatter for `/ms:plan-phase --gaps`.
+Structured gaps in VERIFICATION.md frontmatter for gap triage.
 ```
 
 </output>
@@ -396,7 +396,7 @@ Structured gaps in VERIFICATION.md frontmatter for `/ms:plan-phase --gaps`.
 
 **DO NOT skip key link verification.** This is where 80% of stubs hide. The pieces exist but aren't connected.
 
-**Structure gaps in YAML frontmatter.** The planner (`/ms:plan-phase --gaps`) creates plans from your analysis.
+**Structure gaps in YAML frontmatter.** Gap triage routes gaps to the appropriate primitive based on scope analysis.
 
 **DO keep verification fast.** Use grep/file checks, not running the app. Goal is structural verification, not functional testing.
 
@@ -406,7 +406,7 @@ Structured gaps in VERIFICATION.md frontmatter for `/ms:plan-phase --gaps`.
 
 <success_criteria>
 
-- [ ] Gaps structured in YAML frontmatter (if gaps_found) — planner depends on this
+- [ ] Gaps structured in YAML frontmatter (if gaps_found) — gap triage depends on this
 - [ ] Key links verified — not just artifact existence; this is where stubs hide
 - [ ] Artifacts checked at all three levels (exists → substantive → wired)
 - [ ] SUMMARY.md claims verified against actual code, not trusted

package/bin/install.js

@@ -150,6 +150,10 @@ function isInteractive() {
  * @param {string} destPrefix - The destination prefix (e.g., 'commands/ms', 'agents')
  * @returns {Array<{relativePath: string, absolutePath: string}>}
  */
+// Directories and file patterns excluded from installation
+const EXCLUDED_DIRS = new Set(['.pytest_cache', '__pycache__', 'fixtures', 'node_modules', '.git', '.venv']);
+const EXCLUDED_FILE_PATTERNS = [/^test_/, /\.test\./, /\.spec\./];
+
 function collectFiles(baseDir, currentDir, destPrefix) {
   const files = [];
   if (!fs.existsSync(currentDir)) {
@@ -158,13 +162,17 @@ function collectFiles(baseDir, currentDir, destPrefix) {
 
   const entries = fs.readdirSync(currentDir, { withFileTypes: true });
   for (const entry of entries) {
+    if (EXCLUDED_DIRS.has(entry.name)) {
+      continue;
+    }
+
     const absolutePath = path.join(currentDir, entry.name);
     const relativeToCurrent = path.relative(baseDir, absolutePath);
     const relativePath = path.join(destPrefix, relativeToCurrent);
 
     if (entry.isDirectory()) {
       files.push(...collectFiles(baseDir, absolutePath, destPrefix));
-    } else {
+    } else if (!EXCLUDED_FILE_PATTERNS.some(p => p.test(entry.name))) {
       files.push({ relativePath, absolutePath });
     }
   }

package/commands/ms/add-todo.md

@@ -58,7 +58,7 @@ Infer priority, estimate, and subsystem from description and conversation contex
 | L | 5 | Multi-file feature, new subsystem area |
 | XL | 8 | Cross-cutting concern, architectural change |
 
-**Subsystem:** Read `jq -r '.subsystems[]' .planning/config.json 2>/dev/null`. Match against description and conversation context. Must match config.json vocabulary.
+**Subsystem:** Read `ms-tools config-get subsystems`. Match against description and conversation context. Must match config.json vocabulary.
 </step>
 
 <step name="confirm">

package/commands/ms/audit-milestone.md

@@ -191,7 +191,7 @@ Route by status (see `<offer_next>`).
 Read code review agent from config:
 
 ```bash
-CODE_REVIEW=$(cat .planning/config.json 2>/dev/null | jq -r '.code_review.milestone // empty')
+CODE_REVIEW=$(ms-tools config-get code_review.milestone)
 ```
 
 **If CODE_REVIEW = "skip":**

package/commands/ms/config.md

@@ -76,12 +76,10 @@ If "Custom": use AskUserQuestion for each tier (adhoc, phase, milestone) individ
 
 If "Skip code review": set all three values to `"skip"`.
 
-Update config.json with selected values via jq:
+Update config.json:
 
 ```bash
-jq '.code_review = {"adhoc": $a, "phase": $p, "milestone": $m}' \
-  --arg a "$ADHOC" --arg p "$PHASE" --arg m "$MILESTONE" \
-  .planning/config.json > .planning/config.tmp && mv .planning/config.tmp .planning/config.json
+ms-tools config-set code_review --json '{"adhoc": "'"$ADHOC"'", "phase": "'"$PHASE"'", "milestone": "'"$MILESTONE"'"}'
 ```
 
 </step>
@@ -119,7 +117,7 @@ If no selections: skip gitignore changes.
 Read current value:
 
 ```bash
-CURRENT=$(cat .planning/config.json 2>/dev/null | jq -r '.open_mockups // "auto"')
+CURRENT=$(ms-tools config-get open_mockups --default "auto")
 echo "Current open_mockups: $CURRENT"
 ```
 
@@ -136,10 +134,10 @@ Map selection to config value:
 - "Ask first" → `"ask"`
 - "Don't open" → `"off"`
 
-Update config.json with selected value via jq:
+Update config.json:
 
 ```bash
-jq --arg v "$VALUE" '.open_mockups = $v' .planning/config.json > .planning/config.tmp && mv .planning/config.tmp .planning/config.json
+ms-tools config-set open_mockups "$VALUE"
 ```
 
 </step>
@@ -149,7 +147,7 @@ jq --arg v "$VALUE" '.open_mockups = $v' .planning/config.json > .planning/confi
 Read current value:
 
 ```bash
-CURRENT=$(cat .planning/config.json 2>/dev/null | jq -r '.task_tracker.type // "not configured"')
+CURRENT=$(ms-tools config-get task_tracker.type --default "not configured")
 echo "Current task_tracker: $CURRENT"
 ```
 
@@ -175,13 +173,13 @@ If "Custom path": ask user for path via AskUserQuestion.
 Write to config.json:
 
 ```bash
-jq '.task_tracker = {"type": "linear", "cli": $cli}' --arg cli "$CLI_PATH" .planning/config.json > .planning/config.tmp && mv .planning/config.tmp .planning/config.json
+ms-tools config-set task_tracker --json '{"type": "linear", "cli": "'"$CLI_PATH"'"}'
 ```
 
 If "None / not yet":
 
 ```bash
-jq '.task_tracker = null' .planning/config.json > .planning/config.tmp && mv .planning/config.tmp .planning/config.json
+ms-tools config-delete task_tracker
 ```
 
 </step>

package/commands/ms/debug.md

@@ -93,7 +93,7 @@ Task(
 - Display root cause and evidence summary
 - Offer options:
   - "Fix now" — spawn ms-debugger with `goal: find_and_fix` and the debug file
-  - "Plan fix" — suggest /ms:plan-phase --gaps
+  - "Plan fix" — suggest `/ms:adhoc` for small fixes, `/ms:insert-phase` for larger scope
   - "Done" — leave the diagnosis
 
 **If `## CHECKPOINT REACHED`:**

package/commands/ms/design-phase.md

@@ -132,7 +132,7 @@ If exists, extract:
 Match subsystem(s) to this phase by comparing ROADMAP phase description against subsystem names in config.json. Load matching knowledge files:
 
 ```bash
-jq -r '.subsystems[]' .planning/config.json 2>/dev/null
+ms-tools config-get subsystems
 cat .planning/knowledge/{matched_subsystem}.md 2>/dev/null
 ```
 

package/commands/ms/execute-phase.md

@@ -75,7 +75,7 @@ ms-tools find-phase "$ARGUMENTS"
    - Creates VERIFICATION.md with detailed report
    - Route by status:
      - `passed` → continue to step 7
-     - `gaps_found` → present gaps, offer `/ms:plan-phase {X} --gaps`
+     - `gaps_found` → present gaps, route via gap-closure-routing.md triage
 
 7. **Code review (optional)**
    - Read `code_review.phase` from config.json (default: `ms-code-simplifier`)