mindsystem-cc 4.3.1 → 4.4.0

package/README.md

@@ -1,10 +1,8 @@
 <div align="center">
 
-# MINDSYSTEM
+![Mindsystem Bento Grid](assets/bento-image.webp)
 
-**The full-cycle development system for Claude Code.**
-
-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 — 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,17 +19,15 @@ npx mindsystem-cc
 
 ## 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.
+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:
 
-Mindsystem is the middle ground. Each specialist role maps to a phase you control:
-
-| 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.
 
@@ -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/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>

package/commands/ms/config.md

@@ -1,6 +1,6 @@
 ---
 name: ms:config
-description: Configure Mindsystem preferences — code reviewers, mockups, browser verification, gitignore, git remote, task tracker
+description: Configure Mindsystem preferences — code reviewers, mockups, browser verification, plan mode, gitignore, git remote, task tracker
 allowed-tools:
   - Read
   - Write
@@ -12,7 +12,7 @@ allowed-tools:
 
 Configure Mindsystem preferences for the current project.
 
-Manages code reviewer agents, mockup preferences, browser verification, .gitignore patterns for `.planning/` artifacts, git remote setup, and task tracker integration. Run anytime to reconfigure — idempotent.
+Manages code reviewer agents, mockup preferences, browser verification, plan mode, .gitignore patterns for `.planning/` artifacts, git remote setup, and task tracker integration. Run anytime to reconfigure — idempotent.
 
 </objective>
 
@@ -42,7 +42,7 @@ git remote -v 2>/dev/null || echo "NO_REMOTE"
 
 <step name="route">
 
-**Setup mode:** Proceed through all setting steps sequentially (git_remote → code_reviewers → gitignore_patterns → mockup_preferences → browser_verification → task_tracker). Then go to `validation_summary`.
+**Setup mode:** Proceed through all setting steps sequentially (git_remote → code_reviewers → gitignore_patterns → mockup_preferences → browser_verification → multi_plan → task_tracker). Then go to `validation_summary`.
 
 **Edit mode:** Display all current settings with values from config.json, git remote, and .gitignore:
 
@@ -54,7 +54,8 @@ git remote -v 2>/dev/null || echo "NO_REMOTE"
 3. **Gitignore** — {current .planning/ patterns or "no .planning/ patterns"}
 4. **Mockups** — open: {auto / ask / off}
 5. **Browser verification** — {enabled / disabled}
-6. **Task tracker** — {type + cli path, or "none"}
+6. **Plan mode** — {single plan (default) / multi-plan}
+7. **Task tracker** — {type + cli path, or "none"}
 ```
 
 Ask: "Which settings would you like to change? Enter the numbers (e.g. 1, 3, 5), 'all' to reconfigure everything, or 'done' if everything looks good."
@@ -202,6 +203,34 @@ ms-tools config-set browser_verification --json '{"enabled": true}'   # or false
 
 </step>
 
+<step name="multi_plan">
+
+Read current value:
+
+```bash
+CURRENT=$(ms-tools config-get multi_plan --default "false")
+echo "Current multi_plan: $CURRENT"
+```
+
+Use AskUserQuestion:
+- header: "Plan mode"
+- question: "How should plan-phase group tasks into plans?"
+- options:
+  - "Single plan (Recommended)" — All tasks in one plan. Optimal for 1M context windows where phases already scope work tightly
+  - "Multi-plan" — Split into multiple plans with wave-based parallel execution. Use when phases have genuinely independent work streams
+
+Map selection:
+- "Single plan" → `false`
+- "Multi-plan" → `true`
+
+Update config.json:
+
+```bash
+ms-tools config-set multi_plan $VALUE   # true or false (unquoted — boolean)
+```
+
+</step>
+
 <step name="task_tracker">
 
 Read current value:
@@ -254,6 +283,7 @@ Configuration updated:
 - Code reviewers: [adhoc / phase / milestone values]
 - Mockup open: [auto / ask / off]
 - Browser verification: [enabled / disabled]
+- Plan mode: [single plan / multi-plan]
 - Gitignore: [patterns added, or "no changes"]
 - Git remote: [remote URL, or "none configured"]
 - Task tracker: [type + cli path, or "none"]

package/commands/ms/help.md

@@ -108,7 +108,7 @@ Initialize new project with brief and configuration.
 Usage: `/ms:new-project`
 
 **`/ms:config`**
-Configure Mindsystem preferences — code reviewers, mockup preferences, gitignore patterns, git remote.
+Configure Mindsystem preferences — code reviewers, mockup preferences, browser verification, plan mode, gitignore patterns, git remote.
 
 - Use when: you want to set up code review agents, mockup open behavior, manage which .planning/ artifacts are git-ignored, or push your repo to GitHub.
 - Edits `.planning/config.json` and `.gitignore`
@@ -205,12 +205,12 @@ Create detailed execution plan for a specific phase.
 - Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
 - Breaks phase into concrete, actionable tasks
 - Includes verification criteria and success measures
-- Multiple plans per phase supported (XX-01, XX-02, etc.)
+- Single plan per phase by default. Enable `multi_plan` in config for multiple plans (XX-01, XX-02, etc.)
 - After planning: calculates risk score (0-100) and offers optional plan verification
   - Skip tier (0-39): Low complexity, verification optional
   - Optional tier (40-69): Moderate complexity, verification recommended
   - Verify tier (70-100): Higher complexity, verification strongly recommended
-- Risk factors: task count, plan count, external services, CONTEXT.md, cross-cutting concerns, new deps, complex domains
+- Risk factors: task count, external services, CONTEXT.md, cross-cutting concerns, new deps, complex domains
 
 Usage: `/ms:plan-phase 1`
 Usage: `/ms:plan-phase` (auto-detect next unplanned phase)
@@ -254,22 +254,22 @@ Usage: `/ms:audit-milestone`
 ### Roadmap Management
 
 **`/ms:add-phase <description>`**
-Add new phase to end of current milestone.
+Add new phase to end of current milestone with full specification.
 
 - Use when: you discovered additional work that belongs after the currently planned phases (not an urgent insertion).
-- Appends to ROADMAP.md
-- Uses next sequential number
-- Updates phase directory structure
+- Derives goal, success criteria, and requirements (with REQ-IDs) from description
+- Updates ROADMAP.md, REQUIREMENTS.md (with traceability), and STATE.md
+- Phase is set up identically to roadmapper-created phases — full pipeline support
 
 Usage: `/ms:add-phase "Add admin dashboard"`
 
 **`/ms:insert-phase <after> <description>`**
-Insert urgent work as decimal phase between existing phases.
+Insert urgent work as decimal phase between existing phases with full specification.
 
 - Use when: you discovered work that must happen before the next integer phase, but you don’t want to renumber the roadmap.
 - Creates intermediate phase (e.g., 7.1 between 7 and 8)
-- Useful for discovered work that must happen mid-milestone
-- Maintains phase ordering
+- Derives goal, success criteria, and requirements (with REQ-IDs) from description
+- Updates ROADMAP.md, REQUIREMENTS.md (with traceability), and STATE.md
 
 Usage: `/ms:insert-phase 7 "Fix critical auth bug"`
 Result: Creates Phase 7.1
@@ -501,7 +501,7 @@ Optional: `/ms:config` — configure code reviewers, gitignore, and other prefer
 **Plan → execute loop (with optional quality gates):**
 
 ```
-/ms:plan-phase 5                 # Create one or more PLAN.md files
+/ms:plan-phase 5                 # Create PLAN.md file(s)
 /ms:execute-phase 5              # Execute; produces SUMMARY + VERIFICATION
 # If gaps found during verification, follow triage recommendation:
 # Small gaps:    /ms:adhoc "Close phase 5 gaps: ..."