mindsystem-cc 4.2.1 → 4.3.1

package/README.md

@@ -2,9 +2,9 @@
 
 # MINDSYSTEM
 
-**The engineer's meta-prompting system for Claude Code.**
+**The full-cycle development system for Claude Code.**
 
-Amplifies every step of the development workflow you already follow — discovery, research, design, planning, execution, verification. Each one refined, parallelized, and compounded into persistent knowledge. Built for engineers who want to multiply their output without giving up control.
+In lean teams and solo ventures, the person writing the code is also the person deciding what to build, researching the domain, picking the layout, and verifying the result. Mindsystem amplifies each of those steps, making them deeper and faster — discovery, research, design, planning, execution, verification — so one person can cover the full cycle without cutting corners. What it learns carries forward, so phase 10 knows everything phase 1 figured out.
 
 ```bash
 npx mindsystem-cc
@@ -27,17 +27,17 @@ npx mindsystem-cc
 
 ## Why Mindsystem
 
-Fully autonomous coding tools take a spec and run for hours until a product emerges. That works for prototypes and one-shot projects.
+Larger organizations split product delivery across specialists — product owners, designers, researchers, QA engineers. Autonomous coding tools try to replace that entire chain with a single prompt. Both approaches lose something: the first requires headcount, the second loses your judgment.
 
-Mindsystem takes the opposite approach. It follows the same workflow a thorough engineer already uses — and amplifies each step:
+Mindsystem is the middle ground. Each specialist role maps to a phase you control:
 
-| What you'd do manually | What Mindsystem does |
-|---|---|
-| Talk through requirements, catch misalignment early | **Discuss phase** surfaces assumptions with confidence levels, forces tradeoff decisions before any code gets written |
-| Google libraries, read a few docs | **Research phase** runs 3 parallel agents across documentation, your codebase, and community practices — 10x more sources, synthesized in minutes |
-| Try design directions, pick the best one | **Design phase** generates parallel HTML/CSS mockups with side-by-side comparison and exact design tokens |
-| Plan from what you remember about the codebase | **Plan phase** loads knowledge files capturing every decision, pattern, and pitfall from prior phases |
-| Figure out what states to test, mock them manually | **Verify work** determines mock states automatically — you validate visually or programmatically |
+| The role | What you'd do | What Mindsystem does |
+|---|---|---|
+| **Product owner** | Talk through requirements, catch misalignment early | **Discuss phase** surfaces assumptions with confidence levels, forces tradeoff decisions before any code gets written |
+| **Technical researcher** | Google libraries, read a few docs | **Research phase** runs 3 parallel agents across documentation, your codebase, and community practices — 10x more sources, synthesized in minutes |
+| **Designer** | Try design directions, pick the best one | **Design phase** generates parallel HTML/CSS mockups with side-by-side comparison and exact design tokens |
+| **Tech lead** | Plan from what you remember about the codebase | **Plan phase** loads knowledge files capturing every decision, pattern, and pitfall from prior phases |
+| **QA engineer** | Figure out what states to test, mock them manually | **Verify work** determines mock states automatically — you validate visually or programmatically |
 
 The workflow stays yours. Each step finishes in minutes instead of hours. Everything learned compounds into knowledge that survives context resets — phase 10 starts with everything the project learned from phases 1–9.
 
@@ -187,11 +187,13 @@ You approve the plan structure and can adjust granularity.
 
 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.
 
+For web projects, browser verification launches a real browser against your dev server, derives a checklist from execution summaries, and verifies each route visually and programmatically. Clear mismatches get fixed inline; issues beyond visual fixes are reported with screenshot evidence for verify-work.
+
 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 touching the same subsystems start with accumulated context: decisions made, patterns established, pitfalls encountered.
 
-**Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, knowledge file updates.
+**Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, screenshots, knowledge file updates.
 
 ### 9. Verify work
 
@@ -251,6 +253,10 @@ Orchestration metadata (wave grouping, dependencies) lives in `EXECUTION-ORDER.m
 
 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.
 
+### Browser verification
+
+During execute-phase, web projects get automatic visual QA via [agent-browser](https://github.com/anthropics/agent-browser). A checklist is derived from execution summaries, then each route is verified with screenshots and programmatic diagnostics (console logs, JS errors, network failures). Clear mismatches get fixed inline; anything deeper is reported with screenshot evidence for verify-work. Enabled by default — disable per-project via `/ms:config`.
+
 ### Built-in code review
 
 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`.
@@ -296,6 +302,11 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 - [uv](https://docs.astral.sh/uv/) — Python package runner used by CLI scripts (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
 - Python 3.10+ (used by uv for scripts)
 
+**Optional (for web projects):**
+
+- [agent-browser](https://github.com/anthropics/agent-browser) — enables browser verification during execute-phase (`npm install -g agent-browser`)
+- `cwebp` — optimizes verification screenshots to WebP (`brew install webp`)
+
 ---
 
 ## Quick start
@@ -452,6 +463,13 @@ Mindsystem stores project config in `.planning/config.json`. Run `/ms:config` to
   //   "auto" (default) | "ask" | "off"
   "open_mockups": "auto",
 
+  // Browser verification during execute-phase (web projects only).
+  //   Launches a real browser, derives checklist from summaries,
+  //   screenshots + console/network diagnostics.
+  "browser_verification": {
+    "enabled": true   // default: true for web projects
+  },
+
   // External task tracker integration (Linear only for now).
   //   null → disabled (default)
   "task_tracker": {

package/agents/ms-browser-verifier.md

@@ -34,13 +34,22 @@ Open the app URL headless. If redirected to login, report auth failure and exit
 <step name="environment_preflight">
 Navigate to the app's main route. Screenshot `00-preflight.png`.
 
+Read diagnostics:
+```bash
+agent-browser console
+agent-browser errors
+agent-browser network requests
+```
+
 Evaluate:
-- Does the app load?
-- Visible backend errors? Console errors? Blank page?
+- Does the app load visually?
+- Console errors or uncaught exceptions?
+- Failed network requests (4xx/5xx)?
+- Blank page?
 
-**If systemic issue** (app won't load, white screen, critical error):
+**If systemic issue** (app won't load, white screen, critical error, cascade of failed requests):
 - Screenshot the failure
-- Return `environment_blocked` report to orchestrator with screenshot evidence
+- Return `environment_blocked` report to orchestrator with screenshot and diagnostic output
 - Stop — no point testing individual items
 
 **If app loads with minor warnings:**
@@ -59,16 +68,23 @@ mkdir -p {screenshots_dir}
 For each checklist item:
 
 ```
+agent-browser errors --clear   ← isolate errors per item
+
 Navigate to route → Screenshot → Evaluate
 
 Match expected?
 YES → PASSED, next item
-NO → Environment issue? (API error, 404, empty data, console network errors)
+NO → Read diagnostics:
+     agent-browser errors
+     agent-browser console
+     agent-browser network requests
+
+     Environment issue? (uncaught exception, failed API request, 4xx/5xx, empty data)
      YES → ENVIRONMENT_BLOCKED for this item
            Same error on 2+ consecutive items? → stop, return report
            Otherwise → next item
-     NO → Investigate in project source files
-          → Hit a stop signal? (see Investigation boundaries + Fix discipline) → ISSUE with screenshot evidence, next item
+     NO → Investigate in project source files (diagnostics narrow the search)
+          → Hit a stop signal? (see Investigation boundaries + Fix discipline) → ISSUE with screenshot and diagnostic evidence, next item
           → Root cause found → Fix attempt → re-screenshot
             Fix worked? → FIXED (commit), next item
             Fix failed? → Different root-cause theory available?
@@ -77,9 +93,9 @@ NO → Environment issue? (API error, 404, empty data, console network errors)
 ```
 
 **Per-item screenshots:**
-- `{NN}-{item-slug}.png` — initial state
-- `{NN}-{item-slug}-result.png` — after interaction (if applicable)
-- `{NN}-{item-slug}-fixed.png` — after fix (if applicable)
+- `{NN}-{item-slug}.webp` — initial state (`.png` if cwebp unavailable)
+- `{NN}-{item-slug}-result.webp` — after interaction (if applicable)
+- `{NN}-{item-slug}-fixed.webp` — after fix (if applicable)
 
 **Interactions:** If the checklist item includes an interaction (click, type, submit), perform it and screenshot the result.
 </step>
@@ -105,10 +121,10 @@ Close the browser. Return a structured report to the orchestrator:
 - {what was wrong} → {what was fixed} | Commit: {hash}
 
 ### Issues Found
-- {description} | Screenshot: {filename} | Evidence: {what the screenshot shows}
+- {description} | Screenshot: {filename} | Evidence: {what the screenshot shows} | Diagnostics: {console errors, failed network requests, or "none"}
 
 ### Environment Blockers
-- {description} | Screenshot: {filename}
+- {description} | Screenshot: {filename} | Diagnostics: {error messages, failed requests}
 ```
 </step>
 
@@ -120,11 +136,15 @@ Close the browser. Return a structured report to the orchestrator:
 - Save all screenshots to `{screenshots_dir}` — never to temp or working directory
 - Re-snapshot after every DOM change (element refs go stale)
 - Wait for networkidle before evaluating
+- Convert screenshots to WebP after capture:
+  1. Check once during preflight: `which cwebp`
+  2. If available, after each screenshot: `cwebp -q 80 {file}.png -o {file}.webp && rm {file}.png`
+  3. If unavailable: keep PNGs as-is
 
 ## Investigation boundaries
 - Only read project source files — never node_modules, dist, build output, or generated directories
 - Never read framework/library source to understand why something doesn't work internally
-- Check network responses and console errors before investigating code — if the data source is the problem, it's ENVIRONMENT_BLOCKED
+- Read `agent-browser errors`, `agent-browser console`, and `agent-browser network requests` before investigating source code — if diagnostics show a failed API call or server error, it's ENVIRONMENT_BLOCKED, not a code fix
 - If 2+ consecutive items show the same failure pattern, identify the shared root cause rather than investigating each individually
 
 ## Fix discipline

package/agents/ms-compounder.md

@@ -2,7 +2,7 @@
 name: ms-compounder
 description: Compounds raw code changes into per-subsystem knowledge files. Spawned by compound workflow.
 model: sonnet
-tools: Read, Write, Bash, Grep, Glob
+tools: Read, Edit, Write, Bash, Grep, Glob
 color: yellow
 ---
 
@@ -19,7 +19,7 @@ You are a Mindsystem knowledge compounder spawned by the compound workflow to up
 ## Required Context (provided by compound workflow)
 
 - **Input mode:** `git`, `file`, or `description`
-- **Change reference:** Git ref/range (git mode), file path (file mode), or description + exploration summary (description mode)
+- **Change reference:** Git ref/range (git mode), file path (file mode), or description/conversation summary (description mode)
 - **Affected subsystems:** List confirmed by user in main context
 - **Subsystem vocabulary:** From config.json (for alignment validation)
 
@@ -47,7 +47,7 @@ Retrieve the raw changes based on input mode:
 
 - **Git mode:** `git show <ref>` for single commit, `git diff <range>` for ranges. Include `--stat` for file overview.
 - **File mode:** Read the file content. Run `git log --oneline -5 -- <path>` for recent history context.
-- **Description mode:** Use the provided exploration summary as change context. No additional reads needed.
+- **Description mode:** Use the provided summary (from exploration or conversation context) as change context. No additional reads needed.
 
 ## Step 2: Read Existing Knowledge Files
 
@@ -71,23 +71,23 @@ Focus on:
 
 ## Step 4: Merge Into Existing Knowledge
 
-For each affected subsystem, merge extracted content into the knowledge file:
+For each affected subsystem, edit the knowledge file to reflect current state:
 
-- **Decisions:** Add new entries, update superseded decisions, remove contradicted ones.
-- **Architecture:** Update structural descriptions with new components and patterns.
-- **Design:** Add new specs, update changed specs.
-- **Pitfalls:** Add new entries, deduplicate with existing.
-- **Key Files:** Add new paths, remove renamed or deleted files.
+- **Decisions:** Append new entries. Edit superseded decisions in place. Delete contradicted ones.
+- **Architecture:** Edit structural descriptions with new components and patterns.
+- **Design:** Append new specs, edit changed specs.
+- **Pitfalls:** Append new entries. Delete duplicates of existing entries.
+- **Key Files:** Append new paths, delete renamed or deleted files.
 
-Rewrite the full file — not append. The result is the current state of knowledge.
+Use `Edit` for existing files — targeted changes preserve content you haven't inspected. Use `Write` only for new files (subsystem has no knowledge file yet).
 
-## Step 5: Write Knowledge Files and Return Report
+## Step 5: Update Knowledge Files and Return Report
 
 ```bash
 mkdir -p .planning/knowledge/
 ```
 
-Write one file per affected subsystem. Follow the template format from `~/.claude/mindsystem/templates/knowledge.md`. Omit sections with no content.
+For new subsystems (no existing file), use `Write` to create the file following the template format from `~/.claude/mindsystem/templates/knowledge.md`. For existing files, all changes should already be applied via `Edit` in step 4. Omit empty sections.
 
 Return a structured report to the compound workflow.
 
@@ -123,11 +123,11 @@ If changes suggest a subsystem not in the confirmed list, note it as a proposal
 
 **Preserve rationale.** The "because" part is the value. Decisions without rationale are just facts.
 
-**Rewrite, not append.** Each update produces the current state. Superseded decisions get updated, not duplicated.
+**Edit to reflect current state.** Update superseded decisions, remove outdated patterns, append new entries. Use `Edit` for existing files, `Write` only for new files.
 
 **Omit empty sections.** If a subsystem has no design work, do not include a Design section.
 
-**No commits.** Write files only — the compound workflow orchestrator handles commits.
+**No commits.** Edit/write files only — the compound workflow orchestrator handles commits.
 
 **Only write files for confirmed affected subsystems.** Do not invent subsystems or write knowledge files for subsystems not in the confirmed list.
 
@@ -136,7 +136,8 @@ If changes suggest a subsystem not in the confirmed list, note it as a proposal
 </critical_rules>
 
 <success_criteria>
-- [ ] Merge uses rewrite semantics (update, remove, deduplicate — not just add)
+- [ ] Existing files modified via Edit (not Write) — targeted changes, no full-file replacement
+- [ ] Merge reflects current state (update, remove, deduplicate — not just append)
 - [ ] No commits made
 - [ ] Report returned with update counts
 - [ ] Empty sections omitted from knowledge files

package/agents/ms-consolidator.md

@@ -2,7 +2,7 @@
 name: ms-consolidator
 description: Consolidates phase artifacts into per-subsystem knowledge files. Spawned by execute-phase after plan execution.
 model: sonnet
-tools: Read, Write, Bash, Grep, Glob
+tools: Read, Edit, Write, Bash, Grep, Glob
 color: yellow
 ---
 
@@ -137,25 +137,25 @@ Extract knowledge, not descriptions. "Using React" is not knowledge. "Using Reac
 
 ## Step 6: Merge Into Knowledge Files
 
-For each affected subsystem, merge extracted content into the knowledge file:
+For each affected subsystem, edit the knowledge file to reflect current state:
 
-- **Decisions:** Add new entries, update superseded decisions, remove contradicted ones.
-- **Architecture:** Update structural descriptions with new components and patterns.
-- **Design:** Add new specs, update changed specs.
-- **Pitfalls:** Add new entries, deduplicate with existing.
-- **Key Files:** Add new paths, remove renamed or deleted files.
+- **Decisions:** Append new entries. Edit superseded decisions in place. Delete contradicted ones.
+- **Architecture:** Edit structural descriptions with new components and patterns.
+- **Design:** Append new specs, edit changed specs.
+- **Pitfalls:** Append new entries. Delete duplicates of existing entries.
+- **Key Files:** Append new paths, delete renamed or deleted files.
 
-Rewrite the full file — not append. The result is the current state of knowledge.
+Use `Edit` for existing files — targeted changes preserve content you haven't inspected. Use `Write` only for new files (subsystem has no knowledge file yet).
 
-## Step 7: Write Knowledge Files
+## Step 7: Update Knowledge Files
 
 ```bash
 mkdir -p .planning/knowledge/
 ```
 
-Write one file per affected subsystem. Follow the template format from `~/.claude/mindsystem/templates/knowledge.md`. Omit sections with no content.
+For new subsystems (no existing file), use `Write` to create the file following the template format from `~/.claude/mindsystem/templates/knowledge.md`. For existing files, all changes should already be applied via `Edit` in step 6. Omit empty sections.
 
-Only write files for subsystems found in SUMMARY.md frontmatter.
+Only update files for subsystems found in SUMMARY.md frontmatter.
 
 ## Step 8: Delete PLAN.md Files
 
@@ -203,7 +203,7 @@ Use `+N` for new entries added, `updated` for sections rewritten with changes, `
 
 **Preserve rationale.** The "because" part is the value. Decisions without rationale are just facts.
 
-**Rewrite, not append.** Each consolidation produces the current state. Superseded decisions get updated, not duplicated.
+**Edit to reflect current state.** Update superseded decisions, remove outdated patterns, append new entries. Use `Edit` for existing files, `Write` only for new files.
 
 **Handle missing files gracefully.** Not all phases have CONTEXT, DESIGN, or RESEARCH files. This is normal.
 
@@ -220,7 +220,8 @@ Use `+N` for new entries added, `updated` for sections rewritten with changes, `
 <success_criteria>
 - [ ] Subsystem alignment validated against config.json
 - [ ] Content extracted and distributed per extraction guide
-- [ ] Knowledge files written to `.planning/knowledge/`
+- [ ] Existing knowledge files modified via Edit (not Write) — targeted changes, no full-file replacement
+- [ ] New knowledge files created with Write in `.planning/knowledge/`
 - [ ] Empty sections omitted from knowledge files
 - [ ] PLAN.md files deleted from phase directory
 - [ ] CONTEXT.md, DESIGN.md, RESEARCH.md, SUMMARY.md preserved

package/agents/ms-researcher.md

@@ -483,7 +483,8 @@ Orchestrator provides:
 
 ```bash
 # For phase research, check for CONTEXT.md from discuss-phase
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+ms-tools find-phase "${PHASE}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
 if [ -n "$PHASE_DIR" ]; then
   cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null
 fi

package/agents/ms-roadmapper.md

@@ -534,6 +534,19 @@ Verify 100% requirement mapping:
 
 If gaps found, include in draft for user decision.
 
+## Step 6b: Evaluate Subsystem Coverage
+
+Compare phase domains against config.json `subsystems` array. Phases may introduce domains not in the current subsystem vocabulary.
+
+1. Parse `subsystems` from config.json (provided in planning context)
+2. For each phase, identify its primary domain (e.g., "Payment Processing" maps to `payments`)
+3. Match against existing subsystems — exact or close synonym counts as covered
+4. Collect unmatched domains as proposed additions
+
+Include proposals in the return under `### Subsystem Proposals`. Do not modify config.json — the orchestrator handles confirmation and update.
+
+If all phase domains map to existing subsystems, omit the section.
+
 ## Step 7: Write Files Immediately
 
 **Write files first, then return.** This ensures artifacts persist even if context is lost.
@@ -613,6 +626,16 @@ When files are written and returning to orchestrator:
 
 {For phases with Likely recommendations, include topics/focus}
 
+{If new subsystems proposed:}
+
+### Subsystem Proposals
+
+New domains detected that don't match existing subsystems:
+
+| Proposed | Source Phase | Rationale |
+|----------|-------------|-----------|
+| {name}   | Phase {N}: {phase-name} | {why this needs its own subsystem} |
+
 ### Files Ready for Review
 
 User can review actual files:
@@ -644,6 +667,16 @@ After incorporating user feedback and updating files:
 - .planning/ROADMAP.md
 - .planning/STATE.md (if needed)
 
+{If new subsystems proposed:}
+
+### Subsystem Proposals
+
+New domains detected that don't match existing subsystems:
+
+| Proposed | Source Phase | Rationale |
+|----------|-------------|-----------|
+| {name}   | Phase {N}: {phase-name} | {why this needs its own subsystem} |
+
 ### Updated Summary
 
 | Phase | Goal | Requirements |

package/commands/ms/add-phase.md

@@ -148,10 +148,6 @@ Add the new phase entry to the roadmap:
    **Design focus**: {focus} ← only if Likely
    **Research**: {Likely (reason) | Unlikely (reason)}
    **Research topics**: {topics} ← only if Likely
-   **Plans:** 0 plans
-
-   Plans:
-   - [ ] TBD (run /ms:plan-phase {N} to break down)
 
    **Details:**
    [To be added during planning]

package/commands/ms/compound.md

@@ -19,7 +19,7 @@ Input modes:
 - **Git reference:** SHA, range (`HEAD~3..HEAD`), or any git ref
 - **File path:** Path to a changed file
 - **Description:** Free-text description of changes
-- **No args:** Infer from current conversation context
+- **No args:** Reflect on current conversation context + git data
 </objective>
 
 <execution_context>
@@ -34,7 +34,7 @@ Validate active project: check `.planning/config.json` exists.
 </step>
 
 <step name="resolve_change_context">
-Gather lightweight change context. Git mode: diff stats. File mode: recent git log. Description mode: spawn Explore agents to find relevant changes.
+Gather lightweight change context. Git mode: diff stats. File mode: recent git log. No-args mode: reflect on conversation context + git diff/log; if context is thin, ask user for intent. Description mode: spawn Explore agents to find relevant changes.
 </step>
 
 <step name="determine_subsystems">
@@ -50,7 +50,7 @@ Spawn ms-compounder with input mode, change reference, confirmed subsystems, and
 </step>
 
 <step name="finalize">
-Update config.json if new subsystems confirmed. Commit knowledge file changes. Set last command.
+Update config.json if new subsystems confirmed. Commit knowledge file changes. Set last command. Report results.
 </step>
 
 </process>

package/commands/ms/create-roadmap.md

@@ -136,8 +136,9 @@ Task(
 5. Map every v1 requirement to exactly one phase
 6. Derive 2-5 success criteria per phase (observable user behaviors)
 7. Validate 100% coverage
-8. Write files immediately (REQUIREMENTS.md, ROADMAP.md, STATE.md)
-9. Return ROADMAP CREATED with combined requirements + roadmap summary
+8. Evaluate subsystem coverage — compare phase domains against config.json subsystems, propose additions for unmatched domains
+9. Write files immediately (REQUIREMENTS.md, ROADMAP.md, STATE.md)
+10. Return ROADMAP CREATED with combined requirements + roadmap summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
@@ -200,6 +201,18 @@ Pre-work: Research [Likely/Unlikely] | Discuss [Likely/Unlikely] | Design [Likel
 
 [... continue for all phases ...]
 
+{If roadmapper returned Subsystem Proposals:}
+
+### New Subsystems
+
+The roadmap introduces domains not covered by current subsystems:
+
+| Proposed | Source Phase | Rationale |
+|----------|-------------|-----------|
+| {name}   | Phase {N}   | {reason}  |
+
+These will be added to config.json upon approval.
+
 ---
 ```
 </step>
@@ -275,7 +288,11 @@ Return ROADMAP REVISED with changes made.
 **Update state and commit:**
 
 ```bash
+# For each subsystem proposal the user approved (skip any rejected during revision):
+ms-tools config-set subsystems --append "{subsystem-name}"
+
 git add .planning/REQUIREMENTS.md .planning/ROADMAP.md .planning/STATE.md
+git diff --quiet .planning/config.json 2>/dev/null || git add .planning/config.json
 git commit -m "$(cat <<'EOF'
 docs: define requirements and create roadmap
 

package/commands/ms/design-phase.md

@@ -30,9 +30,14 @@ Create design specifications for a phase. Spawns ms-designer agent with phase co
 <context>
 Phase number: $ARGUMENTS (required)
 
+Resolve phase directory:
+```bash
+ms-tools find-phase "$ARGUMENTS"
+```
+
 Check for existing design:
 ```bash
-ls .planning/phases/${PHASE}-*/*DESIGN.md 2>/dev/null
+ls ${PHASE_DIR}/*DESIGN.md 2>/dev/null
 ```
 </context>
 
@@ -52,8 +57,7 @@ ms-tools find-phase "$ARGUMENTS"
 ## 2. Check Existing Design
 
 ```bash
-# Check for existing DESIGN.md
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+# PHASE_DIR already resolved from find-phase in <context>
 ls "${PHASE_DIR}"/*-DESIGN.md 2>/dev/null
 ```
 
@@ -119,7 +123,7 @@ Extract from ROADMAP.md:
 **4b. Optional context - CONTEXT.md (from discuss-phase):**
 
 ```bash
-cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
+cat ${PHASE_DIR}/*-CONTEXT.md 2>/dev/null
 ```
 
 If exists, extract:
@@ -377,7 +381,7 @@ Task(
 
 ```bash
 ms-tools set-last-command "ms:design-phase $ARGUMENTS"
-git add .planning/phases/${PHASE}-*/*-DESIGN.md .planning/STATE.md
+git add ${PHASE_DIR}/*-DESIGN.md .planning/STATE.md
 git commit -m "docs: create design for phase ${PHASE}"
 ```
 
@@ -387,12 +391,12 @@ Display summary from agent response:
 - Screens designed
 - Key design decisions
 
-Then present pre-work status: Read `~/.claude/mindsystem/references/prework-status.md` and show what's done vs still needed for this phase.
-
 Also offer:
 - **Refine design** — Discuss changes conversationally
 - **View full design** — Display DESIGN.md
 
+Read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
+
 **`## DESIGN NEEDS CLARIFICATION`:**
 
 Present the question to user. Get response. Spawn continuation with the clarification.

package/commands/ms/execute-phase.md

@@ -145,14 +145,14 @@ Then route based on status:
 | Status | Route |
 |--------|-------|
 | `gaps_found` | Route C (gap closure) |
-| `passed` + more phases | Route A (verify + next phase) |
+| `passed` + more phases | Route A (verify) |
 | `passed` + last phase | Route B (verify + milestone complete) |
 
 Thoroughness by default: verify-work is the primary "Next Up" in both routes. Assess skip context per workflow `offer_next` step.
 
 ---
 
-**Route A: Phase verified, more phases remain**
+**Shared steps (Routes A and B):**
 
 1. Show phase completion summary:
 ```
@@ -174,26 +174,33 @@ All {Y} plans finished. Phase goal verified.
 {If skip context: "Phase involved only {description} with no user-facing changes — skip if structural verification is sufficient."}
 ```
 
-4. Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` to determine the most appropriate command for Phase {Z+1}. Present next phase context and options:
-```
-**Phase {Z+1}: {Name}** — {Goal}
-{If pre-work flagged: brief note about recommendations}
+**Then branch by route:**
 
-**Also available:**
-- `/ms:{suggested} {Z+1}` — {reason}
-- `/ms:plan-phase {Z+1}` — skip pre-work, plan directly
-```
+**Route A: More phases remain**
 
----
+4. **If skip context applies:** Determine next phase's primary suggestion:
+   - From ROADMAP.md (already in context), get Phase {Z+1} pre-work flags
+   - Check: CONTEXT.md exists? DESIGN.md? RESEARCH.md? in next phase dir
+   - Priority: discuss (if Likely + no CONTEXT.md) > design (if Likely + no DESIGN.md) > research (if Likely + no RESEARCH.md) > plan-phase
+   - Present ONE "Also available" entry:
+   ```
+   ---
+   **Also available:**
+   - `/ms:{suggested} {Z+1}` — skip verify, start Phase {Z+1}: {Name}
+   ---
+   ```
+   **If skip context does NOT apply:** No "Also available" — verify-work is the sole suggestion.
 
-**Route B: Phase verified, milestone complete**
+**Route B: Milestone complete**
 
-Follow Route A steps 1-3, then present milestone options:
+4. Present milestone options:
 ```
+---
 **Also available:**
 - `/ms:audit-milestone` — verify requirements, cross-phase integration, E2E flows
 - `/ms:complete-milestone` — skip audit, archive directly
 - `/ms:add-phase <description>` — add another phase first
+---
 ```
 
 ---

package/commands/ms/help.md

@@ -136,6 +136,7 @@ Define requirements and create roadmap with phases.
 - Creates `.planning/ROADMAP.md` (phase breakdown)
 - Creates `.planning/STATE.md` (project memory)
 - Creates `.planning/phases/` directories
+- Evaluates subsystem coverage — proposes new subsystems if phases introduce unmatched domains
 
 Usage: `/ms:create-roadmap`
 

package/commands/ms/insert-phase.md

@@ -163,10 +163,6 @@ Insert the new phase entry into the roadmap:
    **Design focus**: {focus} ← only if Likely
    **Research**: {Likely (reason) | Unlikely (reason)}
    **Research topics**: {topics} ← only if Likely
-   **Plans:** 0 plans
-
-   Plans:
-   - [ ] TBD (run /ms:plan-phase {decimal_phase} to break down)
 
    **Details:**
    [To be added during planning]