mindsystem-cc 4.1.1 → 4.2.0

package/agents/ms-browser-verifier.md

@@ -0,0 +1,102 @@
+---
+name: ms-browser-verifier
+description: Automated functional verification via browser. Tests observable truths, fixes issues inline, reports patterns for knowledge compounding.
+model: sonnet
+tools: Read, Write, Edit, Bash, Grep, Glob
+skills:
+  - agent-browser
+color: green
+---
+
+<role>
+You are a Mindsystem browser verifier. You test observable truths from VERIFICATION.md by interacting with the app in a real browser. When you find issues, you fix them inline and re-verify.
+
+**Critical mindset:** Test what users see, not what code claims. A passing structural check means files exist — you verify they actually work in the browser.
+</role>
+
+<process>
+
+<step name="start_dev_server">
+Check if dev server is already running by probing common ports (5173, 3000, 8080, 4200, 3001).
+
+If not running:
+1. Read `package.json` scripts for dev command (`dev`, `start`, `serve`)
+2. Start via `npm run {script}` or `yarn {script}` based on lock file presence
+3. Retry port probe with backoff (1s, 2s, 4s) until ready or timeout (30s)
+</step>
+
+<step name="check_auth_state">
+Auth is handled by the orchestrator before spawning this agent. If the orchestrator provides a storage state file path, load it when launching the browser to restore the authenticated session.
+
+Open the app URL headless. If redirected to login, report auth failure and exit — do not attempt to automate auth.
+</step>
+
+<step name="extract_testable_truths">
+Read VERIFICATION.md from the phase directory. Extract observable truths and filter for browser-testable ones.
+
+Read plans and summaries to understand pages, routes, and components involved.
+
+**Browser-testable:** UI renders, navigation works, form submission succeeds, data displays correctly, interactions produce expected state changes.
+
+**Not browser-testable:** API internals, database state, background job execution, server-side logging.
+</step>
+
+<step name="verify_each_truth">
+Create the screenshots directory:
+
+```bash
+mkdir -p {screenshots_dir}
+```
+
+For each testable truth:
+1. Navigate to the relevant page/route
+2. Take a screenshot, save to `{screenshots_dir}/{truth-slug}.png`
+3. Interact as needed (click, type, submit)
+4. Wait for `networkidle` before verifying expected state
+5. Verify expected state (element exists, text matches, route changed)
+6. Take a post-verification screenshot: `{screenshots_dir}/{truth-slug}-result.png`
+
+**Critical:** Re-snapshot after every DOM change. Element references go stale after navigation or dynamic updates.
+</step>
+
+<step name="fix_issues">
+If an issue is found:
+1. Investigate: read source files for the component/page
+2. Fix: use Edit/Write to correct the issue
+3. Wait for hot reload (probe dev server)
+4. Re-verify in browser
+5. If fixed: commit with `fix({phase}-browser): {description}`
+6. If fix fails after one retry: flag as unresolved, continue to next truth
+</step>
+
+<step name="close_and_report">
+Close the browser when all truths are verified.
+
+Return a structured report to the orchestrator:
+
+```
+## Browser Verification Report
+
+**Tested:** {count} | **Passed:** {count} | **Fixed:** {count} | **Unresolved:** {count}
+
+### Fixes Applied
+- {what was wrong} → {what was fixed} | Files: {changed files}
+
+### Unresolved Issues
+- {description} | Attempted: {what was tried}
+
+### Patterns for Knowledge
+- {recurring pattern observed across multiple truths}
+```
+</step>
+
+</process>
+
+<rules>
+- Save all screenshots to `{screenshots_dir}` — never to temp or working directory
+- Re-snapshot after every DOM change (refs go stale)
+- Wait for networkidle before verifying
+- Do not attempt to automate auth (orchestrator handles it)
+- One retry per fix, then flag and move on
+- Commit each fix atomically with `fix({phase}-browser):` prefix
+</rules>

package/agents/ms-researcher.md

@@ -15,6 +15,8 @@ You are spawned by:
 - `/ms:research-milestone` orchestrator (milestone-scoped research before roadmap)
 
 Your job: Answer research questions with verified, actionable findings. Produce structured output files that inform quality planning.
+
+**Tool selection:** Match tool to question type. Library API docs → `ms-lookup docs`. Deep synthesis → `ms-lookup deep` (3-4 calls max). Discovery/trends → WebSearch. Follow the orchestrator's `<focus>` rules.
 </role>
 
 <upstream_input>

package/bin/install.js

@@ -25,9 +25,8 @@ ${cyan}   ███╗   ███╗██╗███╗   ██╗███
    ╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═════╝ ╚══════╝   ╚═╝   ╚══════╝   ╚═╝   ╚══════╝╚═╝     ╚═╝${reset}
 
   Mindsystem ${dim}v${pkg.version}${reset}
-  A meta-prompting, context engineering and spec-driven
-  development system for Claude Code by Roland Tolnay.
-  Based on GSD by TÂCHES.
+  The engineer's meta-prompting system for Claude Code.
+  Amplify your workflow. Compound your knowledge.
 `;
 
 // Parse args

package/commands/ms/audit-milestone.md

@@ -202,7 +202,7 @@ Skip code review step (proceed to next steps).
 ```bash
 # Find first commit in milestone (first phase commit)
 FIRST_PHASE=$(ls -d .planning/phases/*/ | sort -V | head -1 | xargs basename | cut -d- -f1)
-FIRST_COMMIT=$(git log --oneline --grep="(${FIRST_PHASE}-" --format="%H" | tail -1)
+FIRST_COMMIT=$(ms-tools find-phase-commits ${FIRST_PHASE} | tail -1)
 
 # Get all implementation files changed since first commit
 CHANGED_FILES=$(git diff --name-only ${FIRST_COMMIT}^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')

package/commands/ms/config.md

@@ -1,6 +1,6 @@
 ---
 name: ms:config
-description: Configure Mindsystem preferences — code reviewers, mockups, gitignore, git remote, task tracker
+description: Configure Mindsystem preferences — code reviewers, mockups, browser verification, 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, .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, .gitignore patterns for `.planning/` artifacts, git remote setup, and task tracker integration. Run anytime to reconfigure — idempotent.
 
 </objective>
 
@@ -33,6 +33,36 @@ Manages code reviewer agents, mockup preferences, .gitignore patterns for `.plan
 git remote -v 2>/dev/null || echo "NO_REMOTE"
 ```
 
+**Determine mode** from `code_review` values in config.json:
+
+- **Setup mode** — all `code_review` values are null (or no config file): first-time configuration.
+- **Edit mode** — any `code_review` value is non-null: reconfiguration.
+
+</step>
+
+<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`.
+
+**Edit mode:** Display all current settings with values from config.json, git remote, and .gitignore:
+
+```
+## Current Settings
+
+1. **Git remote** — {remote URL or "none configured"}
+2. **Code reviewers** — adhoc: {value or "not set"}, phase: {value or "not set"}, milestone: {value or "not set"}
+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"}
+```
+
+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."
+
+- **"done"** → skip to `validation_summary` (no changes)
+- **"all"** → proceed through all setting steps sequentially
+- **Specific numbers** → proceed through only the corresponding setting steps, skip the rest
+
 </step>
 
 <step name="git_remote">
@@ -100,12 +130,14 @@ Use AskUserQuestion (multiSelect):
 - options:
   - "Phase patch files (`.planning/phases/**/*.patch`)" — Large binary diffs, regeneratable
   - "Design mockups (`.planning/phases/**/*.html`)" — Generated HTML mockups from design-phase
+  - "Browser screenshots (`.planning/phases/**/screenshots/`)" — Browser verification screenshots
 
 Apply selected patterns to `.gitignore`. Create the file if needed:
 
 ```bash
-echo '.planning/phases/**/*.patch' >> .gitignore  # if selected
-echo '.planning/phases/**/*.html' >> .gitignore   # if selected
+echo '.planning/phases/**/*.patch' >> .gitignore       # if selected
+echo '.planning/phases/**/*.html' >> .gitignore        # if selected
+echo '.planning/phases/**/screenshots/' >> .gitignore  # if selected
 ```
 
 If no selections: skip gitignore changes.
@@ -142,6 +174,34 @@ ms-tools config-set open_mockups "$VALUE"
 
 </step>
 
+<step name="browser_verification">
+
+Read current value:
+
+```bash
+CURRENT=$(ms-tools config-get browser_verification.enabled --default "true")
+echo "Current browser_verification.enabled: $CURRENT"
+```
+
+Use AskUserQuestion:
+- header: "Browser verification"
+- question: "Enable automated browser verification during execute-phase? (Tests your web UI after code changes)"
+- options:
+  - "Enabled (Recommended)" — Automatically test web UI after phase execution
+  - "Disabled" — Skip browser verification
+
+Map selection:
+- "Enabled" → `true`
+- "Disabled" → `false`
+
+Update config.json:
+
+```bash
+ms-tools config-set browser_verification --json '{"enabled": true}'   # or false
+```
+
+</step>
+
 <step name="task_tracker">
 
 Read current value:
@@ -193,6 +253,7 @@ Configuration updated:
 
 - Code reviewers: [adhoc / phase / milestone values]
 - Mockup open: [auto / ask / off]
+- Browser verification: [enabled / disabled]
 - Gitignore: [patterns added, or "no changes"]
 - Git remote: [remote URL, or "none configured"]
 - Task tracker: [type + cli path, or "none"]
@@ -217,28 +278,17 @@ EOF
 
 </step>
 
-<step name="done">
-
-Present next steps using the "Next Up" format:
-
-- **If PROJECT.md exists:** recommend `/ms:new-milestone` — Discover what to build next, create requirements and roadmap
-- **If no PROJECT.md:** recommend `/ms:new-project` — Initialize project with business context and vision
-
-Also list: `/ms:doctor` — Verify subsystems and artifact health
-
-</step>
-
 </process>
 
 <success_criteria>
 
+- [ ] Setup mode triggered when all code_review values null; edit mode otherwise
+- [ ] Edit mode displays numbered settings with current values
+- [ ] Only user-selected settings modified in edit mode
 - [ ] Changes committed (if any)
-- [ ] User routed to next step
 - [ ] Gitignore patterns applied (if selected)
 - [ ] Git remote offered (if missing)
 - [ ] Validation summary displayed
-- [ ] Config.json code_review values set (or preserved if skipped)
-- [ ] Config.json open_mockups value set (or preserved if skipped)
-- [ ] Config.json task_tracker value set (or preserved if skipped)
+- [ ] Terminates after commit/summary — no Next Up routing
 
 </success_criteria>

package/commands/ms/create-roadmap.md

@@ -292,6 +292,19 @@ EOF
 ```
 </step>
 
+<step name="create_phase_dirs">
+Create phase directories from the roadmap:
+
+```bash
+ms-tools create-phase-dirs
+```
+
+```bash
+git add .planning/phases/
+git commit -m "chore: create phase directories from roadmap"
+```
+</step>
+
 <step name="done">
 ```
 Requirements and roadmap created:

package/commands/ms/doctor.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <objective>
-Run health checks on project configuration. Detect and fix structural drift across 10 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers and environment diagnostics, research API keys, and Mindsystem version.
+Run health checks on project configuration. Detect and fix structural drift across 12 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers and environment diagnostics, research API keys, phase directory naming, browser verification prerequisites, and Mindsystem version.
 
 Idempotent.
 </objective>
@@ -119,6 +119,8 @@ Display results as a markdown table:
 | PLAN cleanup             | FAIL   | 9 leftover PLAN.md files         |
 | CLI wrappers             | FAIL   | Not resolvable; bin dir not in PATH |
 | Research API Keys        | WARN   | PERPLEXITY_API_KEY not set        |
+| Phase directory naming   | FAIL   | 1 non-canonical directory         |
+| Browser Verification     | WARN   | Web project, missing agent-browser CLI |
 | Mindsystem version       | WARN   | v3.21.0 → v3.22.1 available       |
 ```
 
@@ -141,7 +143,7 @@ If "Skip" → go to `report`.
 
 If "Review each" → use AskUserQuestion for each failed check with its details and options: "Fix" / "Skip". Only run fixes for accepted checks.
 
-Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
+Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_phase_dirs → fix_knowledge. Skip any fix whose check passed or was skipped by user.
 
 Phase summaries are resolved by fix_phase_archival. CLI wrapper failures have specific fixes: bin dir not in PATH → restart Claude Code session; missing wrappers or bin dir → re-run `npx mindsystem-cc`; uv not found → `curl -LsSf https://astral.sh/uv/install.sh | sh`. WARN checks (Research API Keys, missing uv) are informational — no automated fix, only displayed in the report.
 </step>
@@ -179,6 +181,8 @@ Final summary table:
 | PLAN cleanup             | PASS   | ...                              |
 | CLI wrappers             | PASS   | ...                              |
 | Research API Keys        | PASS   | ...                              |
+| Phase directory naming   | PASS   | ...                              |
+| Browser Verification     | PASS   | ...                              |
 | Mindsystem version       | PASS   | ...                              |
 
 All checks passed.
@@ -195,6 +199,6 @@ Include counts: checks total, passed, warned, fixed during this run.
 - [ ] Re-scan verifies all checks pass after fixes
 - [ ] Each fix group committed atomically
 - [ ] Fixes applied in dependency order: subsystems → dirs → milestone naming → archival → cleanup → knowledge
-- [ ] All 10 categories reported with PASS/FAIL/WARN/SKIP
+- [ ] All 12 categories reported with PASS/FAIL/WARN/SKIP
 - [ ] Clean project reports all PASS with no fix prompts
 </success_criteria>

package/commands/ms/execute-phase.md

@@ -77,29 +77,35 @@ ms-tools find-phase "$ARGUMENTS"
      - `passed` → continue to step 7
      - `gaps_found` → present gaps, route via gap-closure-routing.md triage
 
-7. **Code review (optional)**
+7. **Browser verification (web projects)**
+   - Run `ms-tools browser-check` for prerequisites
+   - If ready: handle auth, spawn `ms-browser-verifier` for functional testing
+   - Verifier tests observable truths in browser, fixes issues inline
+   - If skipped: not a web project or browser verification disabled
+
+8. **Code review (optional)**
    - Read `code_review.phase` from config.json (default: `ms-code-simplifier`)
-   - If `"skip"`: proceed to step 8
+   - If `"skip"`: proceed to step 9
    - Spawn code review agent with phase file scope
    - If changes made: commit as `refactor({phase}): code review improvements`
 
-8. **Generate phase patch**
+9. **Generate phase patch**
    - Run: `ms-tools generate-phase-patch ${PHASE_NUMBER}`
    - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`
    - Verify: patch file exists OR skip message logged
    - Note: Patch captures all changes including simplifications
 
-9. **Consolidate knowledge**
-   - Spawn `ms-consolidator` with phase directory and number
-   - Consolidator reads phase artifacts and existing knowledge files
-   - Produces updated `.planning/knowledge/{subsystem}.md` files
-   - Deletes PLAN.md files (execution instructions consumed)
-   - Verify: knowledge files written to `.planning/knowledge/`
+10. **Consolidate knowledge**
+    - Spawn `ms-consolidator` with phase directory and number
+    - Consolidator reads phase artifacts and existing knowledge files
+    - Produces updated `.planning/knowledge/{subsystem}.md` files
+    - Deletes PLAN.md files (execution instructions consumed)
+    - Verify: knowledge files written to `.planning/knowledge/`
 
-10. **Update roadmap and state**
+11. **Update roadmap and state**
     - Update ROADMAP.md, STATE.md
 
-11. **Update requirements**
+12. **Update requirements**
     Mark phase requirements as Complete:
     - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
     - Read REQUIREMENTS.md traceability table
@@ -107,7 +113,7 @@ ms-tools find-phase "$ARGUMENTS"
     - Write updated REQUIREMENTS.md
     - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
-12. **Commit phase completion**
+13. **Commit phase completion**
     Bundle all phase metadata updates in one commit:
     - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
     - Stage knowledge files: `git add .planning/knowledge/*.md`
@@ -115,10 +121,10 @@ ms-tools find-phase "$ARGUMENTS"
     - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
     - Commit: `docs({phase}): complete {phase-name} phase`
 
-13. **Offer next steps**
+14. **Offer next steps**
     - Route to next action (see `<offer_next>`)
 
-14. **Update last command:** `ms-tools set-last-command "ms:execute-phase $ARGUMENTS"`
+15. **Update last command:** `ms-tools set-last-command "ms:execute-phase $ARGUMENTS"`
 </process>
 
 <offer_next>
@@ -247,6 +253,7 @@ After all plans in phase complete:
 - [ ] All incomplete plans in phase executed
 - [ ] Code review completed (or skipped if config says "skip")
 - [ ] Phase goal verified (Must-Haves checked against codebase)
+- [ ] Browser verification completed or skipped (non-web/disabled)
 - [ ] VERIFICATION.md created in phase directory
 - [ ] Patch file generated OR explicitly skipped with message
 - [ ] Knowledge files written to .planning/knowledge/ (consolidation complete)

package/commands/ms/research-phase.md

@@ -123,12 +123,12 @@ Phase Research — External Documentation focus.
 
 <focus>
 Library documentation, APIs, version-specific behavior, verified code examples.
-Use the ms-lookup CLI for library docs and deep research:
-  ms-lookup docs <library> '<query>'
-  ms-lookup deep '<query>'
-Use WebSearch for ecosystem discovery.
-Focus on finding authoritative, current documentation for the libraries and tools
-needed to implement this phase.
+Focus on finding authoritative, current documentation for the libraries and tools needed to implement this phase.
+
+Tool selection rules:
+- Library API docs, syntax, configuration → `ms-lookup docs <library> '<query>'`
+- Complex architecture/approach synthesis → `ms-lookup deep '<query>'` (limit: 3-4 calls)
+- Library discovery, trends, ecosystem survey → WebSearch
 </focus>
 
 <existing_tech>
@@ -225,10 +225,12 @@ Phase Research — Best Practices & Community Consensus focus.
 
 <focus>
 Community consensus, common pitfalls, proven approaches, state of the art.
-Use the ms-lookup CLI for deep research on high-value questions:
-  ms-lookup deep '<query>'
-Use WebSearch for community articles, blog posts, Stack Overflow patterns.
 Focus on what practitioners recommend and what mistakes to avoid.
+
+Tool selection rules:
+- Complex best-practices synthesis, architecture decisions → `ms-lookup deep '<query>'` (limit: 3-4 calls)
+- Community opinions, blog posts, trends, library discovery → WebSearch
+- Library-specific API verification (when confirming a recommendation) → `ms-lookup docs <library> '<query>'`
 </focus>
 
 <existing_tech>

package/mindsystem/references/browser-verification.md

@@ -0,0 +1,76 @@
+<browser_verification>
+
+# Browser Verification Reference
+
+Lazily loaded by execute-phase when `ms-tools browser-check` returns READY (exit 0).
+
+## Auth Flow
+
+Handle browser authentication before spawning the verifier agent.
+
+**Step 1: Check for existing auth state**
+
+```bash
+AUTH_STATE=".agent-browser-state.json"
+[ -f "$AUTH_STATE" ] && echo "HAS_STATE" || echo "NO_STATE"
+```
+
+**Step 2: Detect dev server URL**
+
+Probe common ports to find the running dev server:
+
+```bash
+for PORT in 5173 3000 8080 4200 3001; do
+  curl -s -o /dev/null -w "%{http_code}" "http://localhost:$PORT" 2>/dev/null | grep -q "200\|301\|302" && echo "http://localhost:$PORT" && break
+done
+```
+
+Store the result as `{dev_url}`.
+
+**Step 3: Validate or establish auth**
+
+If `HAS_STATE`:
+1. Open app headless at `{dev_url}`
+2. Check current URL — if redirected to a login/auth path, auth has expired
+3. If still on app pages: auth valid, proceed to Spawn
+
+If `NO_STATE` or auth expired:
+1. Close headless browser
+2. Open `{dev_url}` in **headed** mode (visible browser)
+3. Use AskUserQuestion:
+   - header: "Browser authentication"
+   - question: "Please log in to the app in the browser window. Select 'Done' when you've logged in."
+   - options: ["Done — I'm logged in", "Skip browser verification"]
+4. If user logged in: save browser state to `.agent-browser-state.json`, close headed browser, ensure gitignored:
+   ```bash
+   grep -q "\.agent-browser-state\.json" .gitignore 2>/dev/null || echo '.agent-browser-state.json' >> .gitignore
+   ```
+5. If user skips: proceed to code_review, skip browser verification
+
+## Spawn
+
+Spawn the browser verifier agent after auth is established:
+
+```
+Task(
+  prompt="Run browser verification for phase {phase_number}.
+
+Phase directory: {phase_dir}
+Phase goal: {phase_goal}
+VERIFICATION.md: {verification_path}
+Dev URL: {dev_url}
+Auth state: .agent-browser-state.json
+Screenshots directory: {phase_dir}/screenshots
+
+Read VERIFICATION.md for observable truths. Test browser-testable ones.
+Save all screenshots to {phase_dir}/screenshots/.
+Fix issues inline. Return structured report.",
+  subagent_type="ms-browser-verifier"
+)
+```
+
+**After verifier returns:**
+
+If fixes were made, include the report summary in the consolidator prompt (step `consolidate_knowledge`) so browser-discovered patterns are captured in knowledge files.
+
+</browser_verification>

package/mindsystem/templates/config.json

@@ -5,5 +5,8 @@
     "phase": null,
     "milestone": null
   },
-  "open_mockups": "auto"
+  "open_mockups": "auto",
+  "browser_verification": {
+    "enabled": true
+  }
 }

package/mindsystem/templates/research-subagent-prompt.md

@@ -32,12 +32,12 @@ Phase Research — External Documentation focus.
 
 <focus>
 Library documentation, APIs, version-specific behavior, verified code examples.
-Use the ms-lookup CLI for library docs and deep research:
-  ms-lookup docs <library> '<query>'
-  ms-lookup deep '<query>'
-Use WebSearch for ecosystem discovery.
-Focus on finding authoritative, current documentation for the libraries and tools
-needed to implement this phase.
+Focus on finding authoritative, current documentation for the libraries and tools needed to implement this phase.
+
+Tool selection rules:
+- Library API docs, syntax, configuration → `ms-lookup docs <library> '<query>'`
+- Complex architecture/approach synthesis → `ms-lookup deep '<query>'` (limit: 3-4 calls)
+- Library discovery, trends, ecosystem survey → WebSearch
 </focus>
 
 <existing_tech>
@@ -128,10 +128,12 @@ Phase Research — Best Practices & Community Consensus focus.
 
 <focus>
 Community consensus, common pitfalls, proven approaches, state of the art.
-Use the ms-lookup CLI for deep research on high-value questions:
-  ms-lookup deep '<query>'
-Use WebSearch for community articles, blog posts, Stack Overflow patterns.
 Focus on what practitioners recommend and what mistakes to avoid.
+
+Tool selection rules:
+- Complex best-practices synthesis, architecture decisions → `ms-lookup deep '<query>'` (limit: 3-4 calls)
+- Community opinions, blog posts, trends, library discovery → WebSearch
+- Library-specific API verification (when confirming a recommendation) → `ms-lookup docs <library> '<query>'`
 </focus>
 
 <existing_tech>

package/mindsystem/workflows/complete-milestone.md

@@ -38,7 +38,7 @@ When a milestone completes, this workflow:
 
 **PHASE-SUMMARIES** consolidates all `*-SUMMARY.md` files from phase directories, organized by phase and plan, before artifacts are deleted.
 
-**phases/** contains the phase directories themselves (with remaining files like `.patch`, `mockups/`) moved from `.planning/phases/`.
+**phases/** contains the phase directories themselves (with remaining files like `.patch`, `mockups/`, `screenshots/`) moved from `.planning/phases/`.
 
 **REQUIREMENTS archive** contains:
 - All v1 requirements marked complete with outcomes

package/mindsystem/workflows/doctor-fixes.md

@@ -80,7 +80,7 @@ For each flat file like `milestones/v0.1-ROADMAP.md`:
 3. `git mv` the file, stripping the version prefix from the filename:
    `git mv .planning/milestones/v0.1-ROADMAP.md .planning/milestones/v0.1/ROADMAP.md`
 
-**Note:** New milestones use slug-based directories (e.g., `milestones/mvp/`, `milestones/push-notifications/`). Old v-prefixed directories from previous format are valid and handled.
+New milestones use slug-based directories (e.g., `milestones/mvp/`, `milestones/push-notifications/`). Old v-prefixed directories from previous format are valid and handled.
 
 Commit:
 
@@ -106,7 +106,7 @@ EOF
 2. **Resolve slugs** — For each versioned dir, match to MILESTONES.md name mapping:
    - Standard dirs: version matches directly (v0.1 → "MVP" → slug "mvp")
    - Nested dirs: match sub-directory name to the milestone name in MILESTONES.md (v2.0.0/quests → "Quests Feature" → slug "quests-feature")
-   - Derive short slugs from names (Claude proposes, user confirms)
+   - Derive slugs from names: lowercase, hyphenated (e.g., "Demo Release" → "demo-release"). Claude proposes, user confirms
 
 3. **Present mapping** to user with AskUserQuestion:
 
@@ -236,6 +236,35 @@ EOF
 ```
 </step>
 
+<step name="fix_phase_dirs">
+**Only if Phase Directory Naming failed or warned.**
+
+1. Create any missing phase directories:
+
+```bash
+ms-tools create-phase-dirs
+```
+
+2. For non-canonical directories (reported as FAIL), rename using `git mv`:
+
+Parse each non-canonical suggestion from the doctor check output (format: `{old} → git mv .planning/phases/{old} .planning/phases/{canonical}`) and execute the `git mv`.
+
+Commit:
+
+```bash
+git add .planning/phases/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): fix phase directory naming
+
+Created missing and renamed non-canonical phase directories.
+EOF
+)"
+```
+</step>
+
 <step name="fix_knowledge">
 **Only if Knowledge Files failed.**
 
@@ -253,7 +282,7 @@ If `SUMMARIES > 0`: **artifact mode**. If `SUMMARIES == 0`: **source code mode**
 
 ### 2. Spawn subagent
 
-Spawn a `general-purpose` subagent (Task tool) with the following structured prompt. Inject detected mode, subsystem list from config.json, and environment flags into the prompt.
+Spawn a `general-purpose` subagent (Task tool) with the following structured prompt. Inject detected mode, subsystem list from config.json, and detection results (SUMMARIES, HAS_CODEBASE_DOCS, HAS_PROJECT) into the prompt.
 
 ---