mindsystem-cc 4.3.1 → 4.4.1

package/README.md

@@ -1,43 +1,55 @@
 <div align="center">
 
-# MINDSYSTEM
+![Mindsystem Bento Grid](assets/bento-image.webp)
 
-**The full-cycle development system for Claude Code.**
+# Mindsystem
 
-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.
+Amplifies every step of the development workflow you already follow.
+
+[![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)
+[![npm downloads](https://img.shields.io/npm/dm/mindsystem-cc?style=flat-square)](https://www.npmjs.com/package/mindsystem-cc)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![Built for Claude Code](https://img.shields.io/badge/built_for-Claude_Code-D97706?style=flat-square)](https://docs.anthropic.com/en/docs/claude-code)
+
+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.
+
+[Quick start](#quick-start) · [Walkthrough](#end-to-end-walkthrough) · [Features](#features) · [Commands](#command-reference)
+
+</div>
+
+---
+
+## Quick start
 
 ```bash
 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>
+Then `/ms:new-project` to initialize. See the [full walkthrough](#end-to-end-walkthrough) for the complete feature-building loop, or `/ms:progress` to pick up where you left off.
 
-![Mindsystem Install](assets/terminal.svg)
+---
 
-<br>
+## What's new in v4.4
 
-[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)
+- **User journey browser verification** — end-to-end click/fill/submit testing instead of screenshot-only observation. Catches unreachable pages with no navigation path from the UI.
+- **Single-plan mode (default)** — one plan per phase, eliminating multi-agent orchestration overhead with 1M context windows.
+- **Full phase specification** for add-phase and insert-phase — both commands now derive goal, success criteria, and requirements mapping.
 
-</div>
+See [CHANGELOG.md](CHANGELOG.md) for the complete history.
 
 ---
 
 ## Why Mindsystem
 
-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 is the middle ground. Each specialist role maps to a phase you control:
+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:
 
-| 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 |
+| 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 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.
 
@@ -97,7 +109,7 @@ Execution happens in fresh subagent contexts, so each plan gets up to 200k token
 
 ### Project setup
 
-Before building features, initialize the project once with `/ms:new-project`. For existing codebases, also run `/ms:map-codebase` (analyzes your stack, conventions, and architecture into 7 structured documents) and `/ms:doctor` (validates config and generates per-subsystem knowledge files from source code). See [Quick start](#quick-start) for the exact sequences.
+Before building features, initialize the project once with `/ms:new-project`. For existing codebases, also run `/ms:map-codebase` (analyzes your stack, conventions, and architecture into 7 structured documents) and `/ms:doctor` (validates config and generates per-subsystem knowledge files from source code). See [Getting started](#getting-started) for the exact sequences.
 
 Everything below is the feature-building loop, identical for new and existing projects.
 
@@ -136,7 +148,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 +160,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 +170,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 +180,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.
+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.
 
-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.
+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 +208,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.
@@ -289,6 +299,10 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 
 `/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/`.
 
+### Task tracker integration
+
+Configure a Linear connection via `/ms:config` and pass ticket IDs directly to `/ms:adhoc` (e.g., `/ms:adhoc MIN-123`). The system auto-fetches the ticket's title and description as work context, tags commits with the ticket ID, and on completion posts a solution summary, attaches the commit, and marks the ticket done. Zero overhead when unconfigured — the integration is lazy-loaded only when a ticket ID is detected.
+
 ### 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.
@@ -309,7 +323,7 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 
 ---
 
-## Quick start
+## Getting started
 
 ### Project setup (one-time)
 
@@ -336,6 +350,7 @@ Once the project is set up, the workflow is the same for new and existing codeba
 ```
 /ms:new-milestone               # Discover what to build next
 /ms:create-roadmap              # Define requirements, map to phases
+/ms:discuss-phase 1             # Gather context before planning
 /ms:plan-phase 1                # Create detailed plan
 /ms:execute-phase 1             # Run in fresh subagents
 /ms:verify-work 1               # Manual acceptance testing
@@ -470,6 +485,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 +512,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 |
@@ -505,7 +525,7 @@ Full docs live in `/ms:help`.
 | `/ms:execute-phase <number>` | Run all unexecuted plans in fresh subagents |
 | `/ms:verify-work [number]` | Batched manual UAT with inline fixes |
 | `/ms:debug [description]` | Structured debugging that survives `/clear` |
-| `/ms:adhoc <description>` | Knowledge-aware execution for discovered work |
+| `/ms:adhoc <description>` | Knowledge-aware execution for discovered work or Linear ticket IDs |
 | `/ms:compound [input]` | Compound out-of-pipeline changes into knowledge files |
 | `/ms:add-phase <description>` | Append a new phase to the roadmap |
 | `/ms:insert-phase <after> <description>` | Insert urgent work between phases |

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/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,46 +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
-
-   **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>
@@ -176,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
@@ -207,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>