mindsystem-cc 4.3.0 → 4.4.0

package/README.md

@@ -1,10 +1,8 @@
 <div align="center">
 
-# MINDSYSTEM
+![Mindsystem Bento Grid](assets/bento-image.webp)
 
-**The engineer's meta-prompting 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.
+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 lean teams and solo builders who want to multiply their output without giving up control.
 
 ```bash
 npx mindsystem-cc
@@ -13,12 +11,6 @@ npx mindsystem-cc
 [![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>
-
-![Mindsystem Install](assets/terminal.svg)
-
-<br>
-
 [Why Mindsystem](#why-mindsystem) · [How it works](#how-it-works) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Quick start](#quick-start) · [.planning](#the-planning-directory) · [Config](#configuration) · [Commands](#command-reference) · [Troubleshooting](#troubleshooting)
 
 </div>
@@ -27,9 +19,7 @@ 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.
-
-Mindsystem takes the opposite approach. It follows the same workflow a thorough engineer already uses — and amplifies each step:
+Fully autonomous coding tools take a spec and run until a product emerges. That works for prototypes. Mindsystem takes the opposite approach — it follows the workflow a thorough engineer already uses, and amplifies each step:
 
 | What you'd do manually | What Mindsystem does |
 |---|---|
@@ -136,7 +126,7 @@ Requirements define what must be TRUE when you ship, not what to build. This goa
 ### 4. Discuss phase (optional, recommended)
 
 ```
-/ms:discuss-phase 1
+/ms:discuss-phase <phase>
 ```
 
 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.
@@ -148,7 +138,7 @@ Worth taking seriously. Decisions here propagate through everything that follows
 ### 5. Design phase (optional)
 
 ```
-/ms:design-phase 1
+/ms:design-phase <phase>
 ```
 
 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.
@@ -158,7 +148,7 @@ The output is a `DESIGN.md` with exact design tokens (hex colors, px spacing, fo
 ### 6. Research phase (optional)
 
 ```
-/ms:research-phase 1
+/ms:research-phase <phase>
 ```
 
 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.
@@ -168,21 +158,19 @@ You resolve library conflicts if any come up. Otherwise, this runs with minimal
 ### 7. Plan phase
 
 ```
-/ms:plan-phase 1
+/ms:plan-phase <phase>
 ```
 
-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 get grouped into waves for parallel execution. A risk score (0-100) flags complex plans so you can verify them before committing.
+Claude breaks the phase into tasks and writes a single PLAN.md — pure markdown, no YAML frontmatter, no XML containers. The plan is the executable prompt, roughly 90% actionable content and 10% structure.
 
-You approve the plan structure and can adjust granularity.
+A risk score (0-100) flags complex plans so you can verify them before committing. For phases with genuinely independent work streams, enable `multi_plan` in config to restore multi-plan breakdown with wave-based parallel execution.
 
 **Creates:** `PLAN.md` files, `EXECUTION-ORDER.md`.
 
 ### 8. Execute phase
 
 ```
-/ms:execute-phase 1
+/ms:execute-phase <phase>
 ```
 
 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.
@@ -198,7 +186,7 @@ After execution, knowledge consolidation updates subsystem-scoped knowledge file
 ### 9. Verify work
 
 ```
-/ms:verify-work 1
+/ms:verify-work <phase>
 ```
 
 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.
@@ -470,6 +458,11 @@ Mindsystem stores project config in `.planning/config.json`. Run `/ms:config` to
     "enabled": true   // default: true for web projects
   },
 
+  // Plan mode for plan-phase.
+  //   false (default) → single plan per phase, optimal for 1M context
+  //   true            → multi-plan with wave-based parallel execution
+  "multi_plan": false,
+
   // External task tracker integration (Linear only for now).
   //   null → disabled (default)
   "task_tracker": {
@@ -492,7 +485,7 @@ Full docs live in `/ms:help`.
 | `/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:config` | Configure code reviewers, mockups, plan mode, gitignore, git remote |
 | `/ms:map-codebase` | Document existing repo's stack, structure, and conventions |
 | `/ms:research-milestone` | Milestone-scoped research saved to `.planning/MILESTONE-RESEARCH.md` |
 | `/ms:create-roadmap` | Define requirements and create phases mapped to them |

package/agents/ms-browser-verifier.md

@@ -1,6 +1,6 @@
 ---
 name: ms-browser-verifier
-description: Visual PR review via browser. Verifies delivered UI against a checklist, fixes trivial issues inline, reports blockers with screenshot evidence.
+description: Visual PR review via browser. Completes user journeys end-to-end, fixes trivial issues inline, reports blockers with screenshot evidence.
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob
 skills:
@@ -9,9 +9,9 @@ color: green
 ---
 
 <role>
-You are a senior engineer doing a visual PR review. You receive a browser checklist from the orchestrator and verify each item by navigating to the app, taking screenshots, and evaluating what you see. Fix clear visual mismatches in project source code. Report blockers with screenshot evidence.
+You are a senior engineer doing a visual PR review. You receive user journeys from the orchestrator and complete each journey end-to-end — clicking through UI, filling forms, submitting actions, verifying outcomes. Fix clear visual mismatches in project source code. Report blockers with screenshot evidence.
 
-**Critical mindset:** Verify delivered views, not framework internals. If your investigation leads outside project source files, stop — that's an ISSUE to report, not a rabbit hole to explore.
+**Critical mindset:** Use each feature as a real user would, not framework internals. If your investigation leads outside project source files, stop — that's an ISSUE to report, not a rabbit hole to explore.
 </role>
 
 <process>
@@ -53,11 +53,11 @@ Evaluate:
 - Stop — no point testing individual items
 
 **If app loads with minor warnings:**
-- Note warnings and proceed to checklist verification
+- Note warnings and proceed to journey testing
 </step>
 
-<step name="verify_checklist">
-Single loop over all checklist items with an integrated decision tree.
+<step name="test_journeys">
+Single loop over all user journeys with an integrated decision tree.
 
 Create the screenshots directory:
 
@@ -65,39 +65,52 @@ Create the screenshots directory:
 mkdir -p {screenshots_dir}
 ```
 
-For each checklist item:
+For each journey:
 
 ```
-agent-browser errors --clear   ← isolate errors per item
+agent-browser errors --clear   ← isolate errors per journey
+
+1. Navigate to journey's start page via UI (sidebar, nav — NOT by typing URL)
+   → Cannot reach start page? → UNREACHABLE with screenshot evidence, next journey
+2. Screenshot starting state
+3. Execute each step in order:
+   - Perform action (click, fill, select, toggle)
+   - Wait for response (networkidle, element change)
+   - Screenshot key states (after significant interactions)
+   - Check errors after state-modifying actions:
+     agent-browser errors
+     agent-browser console
+     agent-browser network requests
 
-Navigate to route → Screenshot → Evaluate
+4. After all steps: evaluate success criteria against final state
 
-Match expected?
-YES → PASSED, next item
+Success criteria met?
+YES → PASSED, next journey
 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
+     YES → ENVIRONMENT_BLOCKED for this journey
+           Same error on 2+ consecutive journeys? → stop, return report
+           Otherwise → next journey
      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
+          → Hit a stop signal? (see Investigation boundaries + Fix discipline) → ISSUE with screenshot and diagnostic evidence, next journey
+          → Root cause found → Fix attempt → resume journey from fixed step → re-screenshot
+            Fix worked? → FIXED (commit), next journey
             Fix failed? → Different root-cause theory available?
               YES → Second fix attempt (same flow)
-              NO → revert all changes (git checkout -- {files}), ISSUE, next item
+              NO → revert all changes (git checkout -- {files}), ISSUE, next journey
 ```
 
-**Per-item screenshots:**
-- `{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)
+**Per-journey screenshots:**
+- `{NN}-{journey-slug}.webp` — starting state (`.png` if cwebp unavailable)
+- `{NN}-{journey-slug}-{step}.webp` — key interaction states
+- `{NN}-{journey-slug}-result.webp` — final state after journey completion
+- `{NN}-{journey-slug}-fixed.webp` — after fix (if applicable)
 
-**Interactions:** If the checklist item includes an interaction (click, type, submit), perform it and screenshot the result.
+**Actions are COMPLETED:** Forms are submitted (not just filled). Modals are confirmed (not just opened). Toggles are toggled back. Every journey ends with verifying the outcome.
 </step>
 
 <step name="close_and_report">
@@ -107,15 +120,16 @@ Close the browser. Return a structured report to the orchestrator:
 ## Browser Verification Report
 
 **Status:** {all_passed | has_issues | has_fixes | environment_blocked}
-**Tested:** {count} | **Passed:** {count} | **Fixed:** {count} | **Issues:** {count} | **Blocked:** {count}
+**Tested:** {count} | **Passed:** {count} | **Fixed:** {count} | **Issues:** {count} | **Blocked:** {count} | **Unreachable:** {count}
 
 ### Screenshots
 
-| # | Item | Status | Screenshot |
-|---|------|--------|------------|
-| 1 | {name} | PASSED | {filename} |
-| 2 | {name} | FIXED | {filename} |
-| 3 | {name} | ISSUE | {filename} |
+| # | Journey | Status | Screenshots |
+|---|---------|--------|-------------|
+| 1 | {name} | PASSED | {start}, {result} |
+| 2 | {name} | FIXED | {start}, {result}, {fixed} |
+| 3 | {name} | ISSUE | {start}, {result} |
+| 4 | {name} | UNREACHABLE | {start} |
 
 ### Fixes Applied
 - {what was wrong} → {what was fixed} | Commit: {hash}
@@ -123,6 +137,9 @@ Close the browser. Return a structured report to the orchestrator:
 ### Issues Found
 - {description} | Screenshot: {filename} | Evidence: {what the screenshot shows} | Diagnostics: {console errors, failed network requests, or "none"}
 
+### Unreachable Features
+- {journey name} | Screenshot: {filename} | Dead-end: {where navigation broke down — e.g., "no link to /settings found in sidebar or nav"}
+
 ### Environment Blockers
 - {description} | Screenshot: {filename} | Diagnostics: {error messages, failed requests}
 ```
@@ -132,6 +149,12 @@ Close the browser. Return a structured report to the orchestrator:
 
 <rules>
 
+## Navigation
+- Never navigate by typing a URL into the browser
+- Always reach pages through UI clicks (sidebar, nav links, buttons)
+- Only exception: the app root URL during environment_preflight
+- If a journey's start page cannot be reached via UI navigation, report as UNREACHABLE
+
 ## Screenshots
 - Save all screenshots to `{screenshots_dir}` — never to temp or working directory
 - Re-snapshot after every DOM change (element refs go stale)
@@ -145,12 +168,12 @@ Close the browser. Return a structured report to the orchestrator:
 - 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
 - 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
+- If 2+ consecutive journeys show the same failure pattern, identify the shared root cause rather than investigating each individually
 
 ## Fix discipline
 - Fix the specific visual mismatch — don't restructure, refactor, or "improve" surrounding code
 - A second fix attempt must be based on a different root-cause theory, not a variation of the first
-- After 3 edit-screenshot cycles on one item without resolution, it's an ISSUE regardless
+- After 3 edit-screenshot cycles on one journey without resolution, it's an ISSUE regardless
 - Revert all failed fix attempts (`git checkout -- {files}`) before moving on
 - Commit each successful fix atomically with `fix({phase}-browser): {description}` prefix
 

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
 ---
 
@@ -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/commands/ms/add-phase.md

@@ -6,19 +6,21 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - AskUserQuestion
 ---
 
 <objective>
-Add a new integer phase to the end of the current milestone in the roadmap.
+Add a new integer phase to the end of the current milestone, fully specified with goal, success criteria, and requirements.
 
-This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.
+The phase is set up identically to phases created by the roadmapper — same ROADMAP.md entry format, same requirements in REQUIREMENTS.md with traceability mapping. Downstream commands (discuss-phase, plan-phase, execute-phase, verify-work) work without degradation.
 
-Purpose: Add planned work discovered during execution that belongs at the end of current milestone.
+Purpose: Add discovered work at the end of current milestone with full pipeline support.
 </objective>
 
 <execution_context>
 @.planning/ROADMAP.md
 @.planning/STATE.md
+@.planning/REQUIREMENTS.md
 </execution_context>
 
 <process>
@@ -40,8 +42,8 @@ Example: /ms:add-phase Add authentication system
 Exit.
 </step>
 
-<step name="load_roadmap">
-Load the roadmap file:
+<step name="load_context">
+Load project context:
 
 ```bash
 if [ -f .planning/ROADMAP.md ]; then
@@ -50,9 +52,33 @@ else
   echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
   exit 1
 fi
+
+if [ ! -f .planning/REQUIREMENTS.md ]; then
+  echo "ERROR: No REQUIREMENTS.md found"
+  exit 1
+fi
+```
+
+If REQUIREMENTS.md is missing, display:
+
+```
+Phase addition requires an active milestone with requirements tracking.
+No .planning/REQUIREMENTS.md found.
+
+Instead, consider:
+- `/ms:new-milestone` — start a new milestone with requirements
+- `/ms:create-roadmap` — if milestone context exists but roadmap wasn't created yet
+- `/ms:adhoc "<description>"` — for work that doesn't need milestone tracking
 ```
 
-Read roadmap content for parsing.
+Exit command.
+
+Read ROADMAP.md and REQUIREMENTS.md.
+
+From REQUIREMENTS.md, extract:
+- Existing REQ-ID categories and their prefixes (e.g., AUTH, SUB, CONTENT)
+- Highest REQ-ID number per category (e.g., AUTH-04 → next is AUTH-05)
+- Traceability table structure
 </step>
 
 <step name="find_current_milestone">
@@ -88,6 +114,14 @@ Example: If phases are 4, 5, 5.1, 6 → next is 7
 Format as two-digit: `printf "%02d" $next_phase`
 </step>
 
+<step name="derive_phase_specification">
+Read `~/.claude/mindsystem/references/derive-phase-specification.md` and follow its algorithm.
+
+Variables: `{PHASE_ID}` = `{N}`, `{PHASE_MARKER}` = (empty).
+
+Input: user's description + project context (PROJECT.md, ROADMAP.md phases, REQUIREMENTS.md categories).
+</step>
+
 <step name="generate_slug">
 Convert the phase description to a kebab-case slug:
 
@@ -114,50 +148,51 @@ mkdir -p "$phase_dir"
 Confirm: "Created directory: $phase_dir"
 </step>
 
+<step name="update_requirements">
+Follow the requirements update procedure in `~/.claude/mindsystem/references/derive-phase-specification.md`.
+
+Use Phase `{N}` for traceability table references and footer dating.
+</step>
+
 <step name="update_roadmap">
 Add the new phase entry to the roadmap:
 
-1. Find the insertion point (after last phase in current milestone, before "---" separator)
-
-2. Before writing the phase entry, analyze the description to determine pre-work flags:
+**1. Update phase checklist** (under `## Phases`):
 
-   **Discuss**: Default Likely — enumerate 2-4 assumptions or open questions specific
-   to the phase. Unlikely only for fully mechanical zero-decision work (version bump,
-   rename-only refactor, config-only change, pure deletion/cleanup).
+Find the last `- [ ]` or `- [x]` phase line in the current milestone and append:
+```
+- [ ] **Phase {N}: {Name}** - {One-line description}
+```
 
-   **Design**: Likely when description involves UI work, visual elements, forms,
-   dashboards, or multi-screen flows. Unlikely for backend-only, API, infrastructure,
-   or established UI patterns.
+**2. Add phase details** (under `## Phase Details`):
 
-   **Research**: Likely when description mentions external APIs/services, new
-   libraries/frameworks, or unclear technical approach. Unlikely for established
-   internal patterns or well-documented conventions.
+Find the insertion point (after last phase in current milestone, before "---" separator or `## Progress`).
 
-   Use binary Likely/Unlikely with parenthetical reason. Include topics/focus only when Likely.
+Insert full phase entry matching roadmapper format:
 
-3. Insert new phase heading with pre-work flags:
+```
+### Phase {N}: {Name}
+**Goal**: {approved goal}
+**Depends on**: Phase {N-1}
+**Requirements**: {REQ-IDs comma-separated}
+**Success Criteria** (what must be TRUE):
+  1. {criterion}
+  2. {criterion}
+  3. {criterion}
+**Discuss**: {Likely (reason) | Unlikely (reason)}
+**Discuss topics**: {topics} ← only if Likely
+**Design**: {Likely (reason) | Unlikely (reason)}
+**Design focus**: {focus} ← only if Likely
+**Research**: {Likely (reason) | Unlikely (reason)}
+**Research topics**: {topics} ← only if Likely
+```
 
-   ```
-   ### Phase {N}: {Description}
-
-   **Goal:** [To be planned]
-   **Depends on:** Phase {N-1}
-   **Discuss**: {Likely (reason) | Unlikely (reason)}
-   **Discuss topics**: {topics} ← only if Likely
-   **Design**: {Likely (reason) | Unlikely (reason)}
-   **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]
-   ```
+**3. Update progress table** — append row:
+```
+| {N}. {Name} | Not started | - |
+```
 
-4. Write updated roadmap back to file
+Write updated roadmap back to file.
 
 Preserve all other content exactly (formatting, spacing, other phases).
 </step>
@@ -180,13 +215,16 @@ Present completion summary:
 
 ```
 Phase {N} added to current milestone:
-- Description: {description}
+- Goal: {goal}
+- Requirements: {REQ-IDs}
+- Success criteria: {count}
 - Directory: .planning/phases/{phase-num}-{slug}/
 - Status: Not planned yet
 
-Roadmap updated: {roadmap-path}
-Project state updated: .planning/STATE.md
-
+Files updated:
+- .planning/ROADMAP.md
+- .planning/REQUIREMENTS.md
+- .planning/STATE.md
 ```
 
 Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions
@@ -211,15 +249,17 @@ ms-tools set-last-command "ms:add-phase $ARGUMENTS"
 - Don't use decimal numbering (that's /ms:insert-phase)
 - Don't create plans yet (that's /ms:plan-phase)
 - Don't commit changes (user decides when to commit)
-  </anti_patterns>
+- Don't write skeletal "[To be planned]" entries — derive a real goal and success criteria
+</anti_patterns>
 
 <success_criteria>
 Phase addition is complete when:
 
-- [ ] Phase directory created: `.planning/phases/{NN}-{slug}/`
-- [ ] Roadmap updated with new phase entry
+- [ ] Specification derived with outcome-focused goal and 2-5 observable success criteria
+- [ ] Requirements derived with REQ-IDs and REQUIREMENTS.md updated with traceability mapping
+- [ ] Phase directory and roadmap entry created at end of current milestone with correct sequential number
+- [ ] Roadmap entry matches roadmapper format (Goal, Requirements, Success Criteria, pre-work flags)
 - [ ] STATE.md updated with roadmap evolution note
-- [ ] New phase appears at end of current milestone
-- [ ] Next phase number calculated correctly (ignoring decimals)
+- [ ] User approved specification before writing
 - [ ] User informed of next steps
-      </success_criteria>
+</success_criteria>