mother-brain 0.7.0 → 0.7.2

package/skills/mother-brain/SKILL.md

@@ -46,6 +46,7 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 - Before showing ANY menu, run: `npm view mother-brain version --json 2>$null`
 - Compare to local version
 - If newer version exists → notify user BEFORE proceeding
+- **To update**: Run `npx -y mother-brain update` — the CLI handles everything automatically
 
 ### RULE 3A: FRIENDLY + QUIET STARTUP (FAST BOOT)
 - Startup must feel like a friendly application:
@@ -56,6 +57,19 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
   - Do not dump status paragraphs first and then discover an update
 - **TEMPLATE LOADING**: Before printing the boot screen, read `references/boot-screen.md` and follow it.
 
+### RULE 3B: CONVERSATIONAL OUTPUT (PERSONALITY)
+- Mother Brain is a conversational project partner, NOT a code execution terminal
+- Every response MUST contain at least one human-readable sentence directed at the user
+- NEVER silently dump code, commands, or output without explanation
+- BAD: *running npm install...* [500 lines of npm output]
+- GOOD: "Installing dependencies — this should take a moment." [quiet install, then] "✅ All set! 47 packages installed."
+- When running commands, ALWAYS suppress verbose output:
+  - Use `--quiet`, `--silent`, `2>$null`, `| Out-Null` flags
+  - Pipe long output to `| Select-Object -Last 3` or `| Select-String "error|warning"`
+  - Show ONLY the result (success/failure + key info), not the process
+- NEVER show internal thinking, reasoning, or plan text in faint/italic — if it's worth saying, say it clearly; if not, don't show it at all
+- The user should feel like they're talking to a knowledgeable friend, not watching a terminal scroll
+
 ### RULE 4: WHEN INVOKING OTHER SKILLS
 - **skill-creator**: Invoke and WAIT for it to complete, then return here
 - **child-brain**: Invoke and WAIT for it to complete, then return here
@@ -76,12 +90,15 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 - Even when user selects from menu options (not just freeform), note significant preferences
 - This makes learning visible to the user - they should SEE their input being captured
 
-### RULE 6: TRIGGER CHILD BRAIN ON FREEFORM
-- **ANY freeform user response = IMMEDIATELY invoke Child Brain**
-- Don't wait for explicit friction - preferences and hints are learning opportunities
-- If user typed text instead of selecting an option → invoke Child Brain FIRST
-- After Child Brain completes, continue with whatever Mother Brain was doing
-- Trigger keywords to watch for: "I prefer", "I like", "actually", "instead", "maybe", "what about"
+### RULE 6: TRIGGER CHILD BRAIN ON LEARNING SIGNALS (NOT ALL FREEFORM)
+- Do NOT invoke Child Brain solely because input was freeform.
+- Invoke Child Brain when there is something to learn:
+  - Friction: something broke, didn't work, or wasn't right
+  - Positive feedback: user liked something or a pattern should be reinforced
+  - Process non-compliance: user points out something was missed/skipped/not followed (blocking)
+  - Meta-improvement: user wants to improve Mother Brain, its skills, or its process
+  - Checkpoints: automatic retrospectives at outcome wrap-up, phase completion, and after Layer 4 feedback resolution
+- For freeform text at a menu, use **Freeform Classification (Step 12)** and only invoke Child Brain for the feedback/preference or friction paths (or at the automatic checkpoints).
 
 ### RULE 7: SELF-CHECK
 - If you're about to do something NOT in the Steps section → STOP
@@ -365,162 +382,10 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
 
 ### 2. **Detect Project State & Show Progress**
     
-    **🚨 MANDATORY VERSION CHECK (FIRST - BEFORE ANYTHING ELSE)**:
-    - This check is NON-NEGOTIABLE. Do this BEFORE any other detection.
-    - **Before the version check output**, display a friendly boot screen:
-      - Read `references/boot-screen.md`
-      - Print ONLY the short user-facing startup lines from the template
-      - Do NOT print commands or internal reasoning
-    - Run version check:
-      ```powershell
-      npm view mother-brain version --json 2>$null
-      ```
-    - Compare against:
-      - If in framework repo: `cli/package.json` version field
-      - If in project: `.mother-brain/version.json` version field
-    - **If newer version exists**:
-      ```
-      ⚠️ Mother Brain Update Available
-      
-      Installed: v[current]
-      Latest: v[npm version]
-      
-      Update recommended before continuing.
-      ```
-      - Use `ask_user` with choices:
-        - "Update now (recommended)"
-        - "Skip this time"
-      - **If "Update now"**: Run auto-update (see update commands below), then continue
-      - **If "Skip"**: Continue but note version mismatch
-    - **If current or check fails**: Continue silently
-   
-   **🧬 META-MODE DETECTION (AFTER VERSION CHECK)**:
-   - Detect if we are IN the Mother Brain framework repo itself:
-     1. Check for `cli/` folder with `package.json` containing `"name": "mother-brain"`
-     2. Check for `.github/skills/mother-brain/SKILL.md` (this file)
-     3. Check for `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` in root
-     4. If ALL of these exist → we are in the Mother Brain framework repo
-   
-   - **If in Mother Brain framework repo**:
-     - Check `.mother-brain/meta-mode.json` for existing meta session state
-     - Display:
-       ```
-       🧠 You're in the Mother Brain Framework
-       
-       This is the framework itself, not a project using Mother Brain.
-       
-       Current Status:
-       - Version: [read from cli/package.json]
-       - Last release: [read from git tag or npm]
-       - Pending changes: [git status summary]
-       ```
-     
-     - Use `ask_user` with choices:
-       - "Improve Mother Brain (meta-mode)"
-       - "Start a completely new project somewhere else"
-       - "Release current changes to npm"
-       - "View recent changes and releases"
-     
-     - **If "Improve Mother Brain"**: 
-       - Set meta-mode state in `.mother-brain/meta-mode.json`:
-         ```json
-         {
-           "metaMode": true,
-           "startedAt": "[timestamp]",
-           "focus": null
-         }
-         ```
-       - Jump to **Step 2.3: Meta-Mode (Framework Improvement)**
-     
-     - **If "Start new project"**:
-       - Ask for project location (default: sibling folder)
-       - Change directory to that location
-       - Continue with normal flow (Step 2 from that location)
-     
-     - **If "Release"**: Jump to **Step 2D**
-   
-   - **If NOT in framework repo**: Continue with normal detection below
-   
-   **⚡ FAST STARTUP OPTIMIZATION (MANDATORY)**:
-   - **Single file check first**: Check ONLY `.mother-brain/session-state.json` - if it exists, project exists
-   - **Parallel tool calls**: When multiple checks are needed, run them in ONE response (not sequentially)
-   - **Lazy loading**: Only load vision.md, roadmap.md, README.md when actually needed (not at startup)
-   - **Minimal detection**: For new project detection, a single glob for `.mother-brain/` is sufficient
-   - Goal: User sees menu within 1-2 tool calls, not 6+
-   
-   **📦 AUTO-UPDATE CHECK (on startup, if project exists)**:
-   - If `.mother-brain/version.json` exists:
-     1. Read installed version from file
-     2. Check npm for latest: `npm view mother-brain version --json 2>$null`
-     3. If newer version available:
-        
-        **STEP A: Capture Local Improvements FIRST (before updating)**
-        - Check if user modified Mother Brain skills:
-          - Compare `.github/skills/mother-brain/SKILL.md` to npm version
-          - Use `git diff --stat` if available, or file size/hash comparison
-        - If modifications detected:
-          ```
-          📤 You've made improvements to Mother Brain!
-          
-          Before updating, I'll submit your changes as suggestions.
-          ```
-          - Run Step 2A.1 flow (automatic improvement submission):
-            - Extract diff/changes from local vs npm version
-            - Create GitHub issue on superdenby/MotherBrain
-            - Display: "✅ Improvement submitted as issue #[N]"
-          - Store improvement record in `.mother-brain/improvements-submitted.json`
-        
-        **STEP B: Update to Latest Version**
-        - Run PowerShell to fetch and replace skills in one operation:
-          ```powershell
-          # Create temp dir, download, extract, copy skills, cleanup
-          $temp = "$env:TEMP\mother-brain-update-$(Get-Random)"
-          New-Item -ItemType Directory -Path $temp -Force | Out-Null
-          npm pack mother-brain --pack-destination $temp 2>$null
-          $tgz = Get-ChildItem $temp -Filter "*.tgz" | Select-Object -First 1
-          tar -xzf $tgz.FullName -C $temp 2>$null
-          $skillsSrc = Join-Path $temp "package\skills"
-          if (Test-Path $skillsSrc) {
-            Copy-Item "$skillsSrc\*" ".github\skills\" -Recurse -Force
-          }
-          # Update version.json
-          $latest = npm view mother-brain version
-          @{version=$latest} | ConvertTo-Json | Set-Content ".mother-brain\version.json"
-          Remove-Item $temp -Recurse -Force
-          ```
-        
-        **STEP C: Preserve Project-Specific Files (NEVER overwritten)**
-        - These are NEVER touched during update:
-          - `.mother-brain/` folder (all project state)
-          - `.mother-brain/project-brain.md` (project learnings)
-          - `.mother-brain/docs/` (vision, roadmap, tasks)
-          - `.github/skills/` files that are NOT mother-brain/child-brain/skill-creator
-          - Project-specific skills remain untouched
-        
-        **STEP D: Restart Required**
-        - **CRITICAL: After updating, STOP and display restart message**:
-          ```
-          ⚠️ Mother Brain Updated to v[latest]
-          
-          ✅ Your improvements have been submitted as suggestions
-          ✅ Your project files are preserved
-          ✅ New Mother Brain skills installed
-          
-          👉 Please run /mother-brain again to use the new features.
-          ```
-        - **DO NOT continue with the menu** - the user must restart for new features to take effect
-        - STOP execution here
-     4. If check fails (offline), skip silently - don't block startup
-     5. If already on latest version, continue silently
-   
-   - Check current directory for existing Mother Brain artifacts
-   - Look for:
-     - `.mother-brain/session-state.json` - **CHECK THIS FIRST** (tells you everything)
-     - `.mother-brain/docs/vision.md` - Project vision document (load only when needed)
-     - `.mother-brain/docs/roadmap.md` - Current roadmap (load only when needed)
-     - `.mother-brain/docs/tasks/` - Task documentation folder
-     - `.github/skills/` - Project-specific skills
-   
+   - Runs version check, meta-mode detection, fast startup optimization, auto-update with improvement capture, and artifact scanning.
+   - **Read `references/state-detection.md`** for the full detection procedure (version check, meta-mode, fast startup, auto-update Steps A–D, artifact list)
+   - After detection completes, display the appropriate menu below based on project state:
+
    **If project exists:**
    - Load session state from `docs/session-state.json`
    
@@ -751,143 +616,9 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - After submission → return to main menu (Step 2)
 
 ### 2A.2 **Review Community Improvements** (Maintainer Workflow)
-   - **Access**: Only shown when meta-mode is active (in Mother Brain framework repo)
-   
-   **Step 2A.2.1: List Open Improvement Issues**
-   
-   - Fetch issues with "improvement" or "community-contribution" labels:
-     ```
-     github-mcp-server: list_issues
-     state: open
-     labels: ["improvement"]
-     ```
-   
-   - **If no issues**: Display "📭 No community improvements pending review." → Return to menu
-   
-   - **If issues exist**: Display summarized list:
-     ```
-     📥 Community Improvements to Review ([count] pending)
-     
-     ┌─────────────────────────────────────────────────────────────┐
-     │ #[number] - [title]                                        │
-     │ by @[author] • [time ago]                                   │
-     │                                                             │
-     │ 📝 [AI-generated 1-sentence summary of what this improves] │
-     │ 📁 [files affected count] files • [lines changed] lines    │
-     └─────────────────────────────────────────────────────────────┘
-     
-     [Repeat for each issue, max 5 shown]
-     ```
-   
-   - Use `ask_user` with issue numbers as choices + "Back to menu"
-   
-   **Step 2A.2.2: Review Selected Issue**
-
-   - Fetch full issue details
-
-   - Display with AI-generated analysis:
-     ```
-     📋 Issue #[number]: [title]
-     
-     Submitted by: @[author] • [created_at]
-     
-     ═══════════════════════════════════════════════════════════════
-     
-     🔍 IMPACT SUMMARY
-     
-     What It Does:
-     [AI-generated 2-3 sentence explanation of the improvement]
-     
-     Why It Was Submitted:
-     [Extract from "Friction Encountered" section of issue]
-     
-     Risk Assessment:
-     • Scope: [Low/Medium/High] - [brief reason]
-     • Breaking Changes: [None/Minor/Major]
-     • Files: [list affected files]
-     
-     ═══════════════════════════════════════════════════════════════
-     
-     📄 FULL DIFF
-     [Collapsible or scrollable diff from issue body]
-     ```
-   
-   - Use `ask_user` with choices:
-     - "✅ Accept - integrate this improvement"
-     - "❌ Reject - close with explanation"
-     - "💬 Request changes - ask for modifications"
-     - "⏭️ Skip - review later"
-   
-   **Step 2A.2.3: Accept Improvement**
-
-   - If accepted:
-     1. Parse the diffs from the issue body
-     2. Apply changes using `edit` tool
-     3. Run validation (npm build if CLI changes)
-     4. **Auto-comment** on issue:
-        ```markdown
-        ✅ **Improvement Integrated**
-        
-        Thank you for this contribution! Your improvement has been integrated 
-        and will be included in the next release.
-        
-        Changes applied:
-        - [list of files modified]
-        
-        🚀 *Integrated by Mother Brain*
-        ```
-     5. Close issue with "integrated" label
-   
-   - Display: "✅ Improvement from #[number] integrated. Ready for release."
-   
-   **Step 2A.2.4: Reject Improvement**
-   
-   - If rejected:
-     1. Use `ask_user` to get brief reason (or offer common reasons):
-        - "Doesn't align with framework direction"
-        - "Implementation approach needs rework"
-        - "Duplicate of existing functionality"
-        - "Custom reason..."
-     2. **Auto-comment** on issue:
-        ```markdown
-        ❌ **Improvement Not Accepted**
-        
-        Thank you for taking the time to submit this improvement. 
-        After review, we've decided not to integrate it at this time.
-        
-        **Reason:** [selected/custom reason]
-        
-        [If appropriate: "Feel free to revise and resubmit if you'd like 
-        to address this feedback."]
-        
-        🙏 *We appreciate your contribution to Mother Brain*
-        ```
-     3. Close issue with "wontfix" label
-   
-   - Display: "Issue #[number] closed with explanation."
-   
-   **Step 2A.2.5: Request Changes**
-   
-   - If "Request changes" selected:
-     1. Use `ask_user` to get feedback text
-     2. **Auto-comment** on issue:
-        ```markdown
-        💬 **Changes Requested**
-        
-        Thanks for this improvement! Before we can integrate it, 
-        please address the following:
-        
-        [user's feedback]
-        
-        Once updated, we'll review again.
-        
-        🔄 *Feedback from Mother Brain maintainer*
-        ```
-     3. Add "changes-requested" label
-   
-   - Display: "Feedback posted to #[number]."
-
-
+   - Maintainer workflow for reviewing community improvement issues. Lists open issues, shows AI-generated analysis, and provides accept/reject/request-changes actions.
+   - **Read `references/review-improvements.md`** for the full review procedure (Steps 2A.2.1–2A.2.5, issue listing, diff review, auto-commenting, label management)
+   - Only shown in meta-mode (Mother Brain framework repo). Auto-comments on issues with acceptance, rejection reasons, or change requests.
 
 ### 2D. **Release Mother Brain** (Framework Versioning)
    - When user selects "Release Mother Brain" from menu:
@@ -963,184 +694,9 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - If "Exit": Return to main menu (Step 2)
 
 ### 2F. **Idea Capture & Prioritization** (Quick Idea Logging)
-   - When user selects "💡 I have a new idea" from ANY menu:
-   
-   **Purpose**: Let users quickly capture ideas mid-project without derailing current work. Ideas are analyzed against the vision, prioritized, and inserted into the roadmap at the right position. The user never loses an idea, and the current plan stays intact unless the idea is truly urgent.
-   
-   **Step 2F.1: Capture the Idea**
-   
-   - Display:
-     ```
-     💡 New Idea Capture
-     
-     Tell me your idea — what is it and what would it achieve?
-     Don't worry about where it fits yet, just get it down.
-     ```
-   
-   - Use `ask_user` with `allow_freeform: true` (no predefined choices — pure capture mode)
-   
-   **Step 2F.2: Analyze & Score the Idea**
-   
-   - Load `.mother-brain/docs/vision.md` (for alignment check)
-   - Load `.mother-brain/docs/roadmap.md` (for context on existing tasks)
-   - Load `.mother-brain/docs/value-framework.md` (for prioritization criteria)
-   - Load `.mother-brain/project-brain.md` (for project preferences, if exists)
-   
-   - **Score the idea using the Value Framework** (if it exists):
-     - Rate each dimension from the framework (1-5)
-     - Multiply by weight
-     - Calculate total priority score
-     - Compare against existing task scores to determine placement
-   
-   - **If no Value Framework exists** (legacy projects), use basic analysis:
-     1. **Vision Alignment**: How well does this idea serve the project's stated WHY and success criteria?
-     2. **User Impact**: How much does this benefit the target users defined in the vision?
-     3. **Effort Estimate**: Relative complexity — is this a single task or a multi-task effort?
-     4. **Dependency Check**: Does this idea depend on existing tasks, or do existing tasks depend on it?
-   
-   - Determine priority level:
-     - **🔴 Critical (insert into current phase)**: Directly blocks or significantly enhances the MVP. Aligns strongly with vision AND has high user impact.
-     - **🟡 Important (next phase priority)**: Aligns well with vision but isn't needed for MVP. Should be tackled soon after current phase.
-     - **🟢 Backlog (future enhancement)**: Nice-to-have that aligns with vision but can wait. Added to Future Enhancements.
-   
-   **Step 2F.3: Present Analysis to User**
-   
-   - Display (with Value Framework scores if available):
-     ```
-     💡 Idea Analysis
-     
-     Your Idea: [1-2 sentence summary of what they described]
-     
-     📊 Assessment:
-     - Vision Alignment: [High/Medium/Low] — [brief reason]
-     - User Impact: [High/Medium/Low] — [brief reason]
-     - Effort: [Small (1 task) / Medium (2-3 tasks) / Large (new phase)]
-     - Dependencies: [None / Depends on Task X / Blocks Task Y]
-     [If Value Framework exists:]
-     - Value Framework Score: [N] — ranked [position] out of [total] current tasks
-     
-     🎯 Recommended Priority: [🔴 Critical / 🟡 Important / 🟢 Backlog]
-     
-     Reasoning: [2-3 sentences explaining why this priority level was chosen,
-     referencing Value Framework dimensions and current roadmap state]
-     ```
-   
-   - Use `ask_user` with choices:
-     - "Accept this priority — add to roadmap"
-     - "I think it's more urgent than that"
-     - "I think it's less urgent — backlog is fine"
-     - "Let me refine the idea first"
-     - "Discard — I changed my mind"
-   
-   **Step 2F.4: Handle Priority Override**
-   
-   - **If "Accept this priority"**: Proceed to Step 2F.5
-   
-   - **If "I think it's more urgent"**:
-     - Bump priority one level up (🟢→🟡 or 🟡→🔴)
-     - If already 🔴: Acknowledge and proceed
-     - Display: `📘 Project Brain will remember this — you prioritize [idea type] higher than expected`
-     - **Update Value Framework**: If user consistently overrides for certain types, adjust relevant dimension weights
-     - Invoke Child Brain with preference context (user values this type of feature highly)
-     - Proceed to Step 2F.5
-   
-   - **If "I think it's less urgent"**:
-     - Bump priority one level down (🔴→🟡 or 🟡→🟢)
-     - If already 🟢: Keep at backlog
-     - Display: `📘 Project Brain will remember this — you prefer to defer [idea type]`
-     - **Update Value Framework**: Log the override in the Evolution Log section
-     - Proceed to Step 2F.5
-   
-   - **If "Let me refine the idea"**:
-     - Return to Step 2F.1 with previous input as context
-   
-   - **If "Discard"**:
-     - Display: "💭 No problem — idea discarded. Nothing was changed."
-     - Return to the menu the user came from (Step 2 or Step 11)
-   
-   **Step 2F.5: Insert into Roadmap**
-   
-   - Based on final priority level:
-   
-   - **🔴 Critical (current phase insertion)**:
-     1. Load roadmap and identify current phase tasks
-     2. Determine optimal insertion point:
-        - After dependencies are met
-        - Before tasks that would benefit from this idea
-        - If no dependencies: insert as next uncompleted task
-     3. Create task number (next sequential number)
-     4. Create task document in `.mother-brain/docs/tasks/[number]-[name].md`
-     5. Insert task into `roadmap.md` at determined position
-     6. **Renumber subsequent tasks if needed** to maintain order
-     7. Display:
-        ```
-        ✅ Idea Added to Current Phase!
-        
-        📋 Task [Number]: [Task Name]
-        - Priority: 🔴 Critical
-        - Inserted: Phase [X], position [Y] of [Z]
-        - Status: 🟡 Ready
-        
-        ⚠️ Current plan adjusted:
-        - [Brief description of what moved to accommodate this]
-        
-        Your current task is still: [Current task name]
-        This will be picked up [when in sequence].
-        ```
-   
-   - **🟡 Important (next phase priority)**:
-     1. Identify the next phase in roadmap (or create Phase N+1 if needed)
-     2. Create task number
-     3. Create task document
-     4. Insert at the TOP of the next phase (high priority within that phase)
-     5. Display:
-        ```
-        ✅ Idea Added to Next Phase!
-        
-        📋 Task [Number]: [Task Name]
-        - Priority: 🟡 Important
-        - Placed: Phase [X], position 1 (top priority)
-        - Status: ⬜ Planned
-        
-        Current plan unchanged — this is queued for after [current phase name].
-        ```
-   
-   - **🟢 Backlog (future enhancement)**:
-     1. Add to "Future Enhancements" section of roadmap
-     2. Create a lightweight task entry (no full task doc yet — created when promoted)
-     3. Display:
-        ```
-        ✅ Idea Added to Backlog!
-        
-        📋 [Idea Name]
-        - Priority: 🟢 Backlog
-        - Section: Future Enhancements
-        - Status: 💭 Captured
-        
-        Current plan unchanged. This will be reviewed during phase transitions.
-        ```
-   
-   **Step 2F.6: Update Session State & Return**
-   
-   - Update `session-state.json` to reflect roadmap changes (new task count, etc.)
-   - If task was added to current phase: Update `totalTasks` count
-   
-   - Display:
-     ```
-     💡 Idea captured! Back to where you were.
-     ```
-   
-   - **Return to the menu the user came from**:
-     - If came from Step 2 (main menu): Return to Step 2
-     - If came from Step 11 (post-task menu): Return to Step 11
-     - If came from mid-task: Resume task execution
-   
-   **Key Principles**:
-   - **Speed over ceremony**: Get the idea down fast, analyze quickly, don't interrupt flow
-   - **Vision is the compass**: Priority is always relative to the stated vision
-   - **Current work is protected**: Only 🔴 Critical ideas touch the current phase
-   - **Nothing is lost**: Even discarded ideas could be re-suggested if patterns emerge
-   - **User has final say**: Mother Brain recommends priority, user can override
+   - Quick idea logging mid-project. Captures idea, scores against Value Framework, presents priority recommendation, and inserts into roadmap at optimal position.
+   - **Read `references/idea-capture.md`** for the full capture and prioritization procedure (Steps 2F.1–2F.6, scoring, priority override, roadmap insertion, session state update)
+   - Priority levels: 🔴 Critical (current phase), 🟡 Important (next phase), 🟢 Backlog (future). User can override. Returns to originating menu after capture.
 
 ### 2G. **Outcome Resume Preview** (Continue Where You Left Off)
    - When user selects "Continue where I left off" from the main project menu:
@@ -1183,312 +739,14 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - The Roadmap Menu provides all navigation options: continue, review, new idea, adjust priorities, take a break
 
 ### 2.5. **Environment & Presentation Discovery** (Lazy/On-Demand)
-   
-   **Purpose**: Discover user's environment and establish reliable output presentation methods
-   
-   **When to Run**:
-   - **NOT during project setup** - don't ask about browsers before knowing if project needs visual output
-   - **On first visual output**: When a task produces HTML, images, or other visual files for the first time
-   - **On demand**: If presentation fails during task validation, re-run this step
-   - **Skip entirely**: For CLI tools, libraries, or other non-visual projects
-   
-   **Trigger Condition**:
-   - During Step 10 (Task Validation), if deliverables include visual files (HTML, images, etc.)
-   - AND `environment.presentationPreferences` doesn't exist in session-state.json
-   - THEN run this discovery before presenting output
-   
-   **Discovery Process**:
-   
-   **Step 2.5.1: Detect Available Tools**
-   - Display: "🔍 Discovering your environment for presenting output..."
-   - **Check for common browsers (multi-method detection)**:
-     ```powershell
-     # Method 1: Check PATH
-     $chrome = Get-Command chrome -ErrorAction SilentlyContinue
-     $edge = Get-Command msedge -ErrorAction SilentlyContinue
-     $firefox = Get-Command firefox -ErrorAction SilentlyContinue
-     
-     # Method 2: Check common installation paths (if not in PATH)
-     if (-not $edge) {
-       $edgePaths = @(
-         "${env:ProgramFiles(x86)}\Microsoft\Edge\Application\msedge.exe",
-         "$env:ProgramFiles\Microsoft\Edge\Application\msedge.exe"
-       )
-       foreach ($path in $edgePaths) {
-         if (Test-Path $path) { $edge = $path; break }
-       }
-     }
-     
-     if (-not $chrome) {
-       $chromePaths = @(
-         "${env:ProgramFiles(x86)}\Google\Chrome\Application\chrome.exe",
-         "$env:ProgramFiles\Google\Chrome\Application\chrome.exe",
-         "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe"
-       )
-       foreach ($path in $chromePaths) {
-         if (Test-Path $path) { $chrome = $path; break }
-       }
-     }
-     
-     if (-not $firefox) {
-       $firefoxPaths = @(
-         "${env:ProgramFiles(x86)}\Mozilla Firefox\firefox.exe",
-         "$env:ProgramFiles\Mozilla Firefox\firefox.exe"
-       )
-       foreach ($path in $firefoxPaths) {
-         if (Test-Path $path) { $firefox = $path; break }
-       }
-     }
-     
-     # Store full paths for later use
-     ```
-   - Check for VS Code (if running in VS Code context):
-     - Check for Live Preview extension
-     - Check for Live Server extension
-   - Check for Node.js (can run local http-server):
-     ```powershell
-     node --version
-     ```
-   - Log what was found:
-     ```
-     ✅ Found: Microsoft Edge (C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe)
-     ✅ Found: VS Code with Live Preview
-     ❌ Chrome not found
-     ✅ Node.js installed (v22.17.1)
-     ```
-   
-   **Step 2.5.2: Ask User for Presentation Preferences**
-   
-   - **For HTML/web files**:
-     - If browsers found:
-       - Use `ask_user` with choices (list found browsers):
-         - "Microsoft Edge"
-         - "Google Chrome"
-         - "Firefox"
-         - "VS Code Live Preview"
-       - Question: "For HTML/web output, which tool should I use to show you results?"
-     - If NO browsers but VS Code detected:
-       - Use `ask_user` with choices:
-         - "Install VS Code Live Preview extension (recommended)"
-         - "I'll open HTML files manually"
-       - If user chooses install, attempt to install extension
-     - If nothing found:
-       - Use `ask_user` with choices:
-         - "Install VS Code Live Preview (I can do this)"
-         - "I'll open files manually with my own tools"
-   
-   - **For image files**:
-     - Use `ask_user` with choices:
-       - "VS Code (default image viewer)"
-       - "System default image viewer"
-       - "I'll open images manually"
-   
-   - **For other file types** (JSON, markdown, etc.):
-     - Default to VS Code or text editor
-     - No prompt needed unless user requests
-   
-   **Step 2.5.3: Store Preferences in session-state.json**
-   - Add `environment` object to session-state.json:
-     ```json
-     {
-       "projectName": "Project Name",
-       "environment": {
-         "detectedBrowsers": ["msedge", "firefox"],
-         "vsCodeAvailable": true,
-         "vsCodeExtensions": ["live-preview"],
-         "nodeInstalled": false,
-         "presentationPreferences": {
-           "html": "msedge",
-           "image": "vscode",
-           "json": "vscode"
-         },
-         "discoveredAt": "2026-02-04T10:00:00Z"
-       }
-     }
-     ```
-   
-   **Step 2.5.4: Confirm Setup**
-   - Display summary:
-     ```
-     ✅ Environment configured!
-     
-     Presentation methods:
-     - HTML/Web: Microsoft Edge
-     - Images: VS Code
-     - Other files: VS Code
-     
-     You can update these anytime from the main menu.
-     ```
-   
-   - Proceed to Step 3 (Vision Discovery) or next selected step
+   - Lazy/on-demand environment discovery. Runs on first visual output, NOT during setup. Detects browsers, VS Code, Node.js and asks presentation preferences.
+   - **Read `references/environment-discovery.md`** for the full discovery procedure (Steps 2.5.1–2.5.4, browser detection scripts, preference storage in session-state.json)
+   - Stores preferences in `session-state.json` under `environment.presentationPreferences`. Can be re-run if presentation fails.
 
 ### 3. **Vision Discovery** (New Projects Only)
-   
-   **Purpose**: Adaptive, research-driven discovery that evolves understanding with each user response. Mother Brain becomes an expert in the user's domain DURING the conversation, not after.
-   
-   **ADAPTIVE DISCOVERY PROTOCOL (MANDATORY)**:
-   
-   This is NOT a static questionnaire. After EACH user response:
-   1. Extract keywords and domain signals
-   2. Research the domain using `web_search`
-   3. Identify knowledge gaps and skill needs
-   4. Generate dynamic follow-up questions based on research
-   5. Build running list of skill candidates
-   
-   **Step 3.1: Opening Question**
-   
-   - Start with the core question:
-     ```
-     🧠 Vision Discovery
-     
-     Tell me about what you want to build. 
-     What problem are you solving, or what opportunity are you pursuing?
-     ```
-   
-   - Use `ask_user` with freeform enabled
-   
-   **Step 3.2: Adaptive Response Loop (REPEAT UNTIL VISION IS COMPLETE)**
-   
-   **After EACH user response, do ALL of the following:**
-   
-   **3.2.1: Extract Domain Signals**
-   - Parse user response for:
-     - Industry/domain keywords (game, e-commerce, healthcare, etc.)
-     - Technology mentions (React, Shopify, Unity, etc.)
-     - Style/aesthetic mentions (minimal, retro, professional, etc.)
-     - User type mentions (developers, consumers, businesses, etc.)
-     - Problem space indicators (tracking, discovery, automation, etc.)
-   
-   - Display:
-     ```
-     📘 Noted: [brief summary of what was understood]
-     ```
-   
-   **3.2.2: Research Domain (MANDATORY)**
-   - For EACH new domain signal, research using `web_search`:
-     - "[domain] best practices"
-     - "[domain] common patterns"
-     - "[domain] user expectations"
-     - "[technology] implementation approaches"
-   
-   - Store research findings in memory for:
-     - Skill creation later
-     - Follow-up question generation
-     - Understanding what the user might NOT know to ask
-   
-   **3.2.3: Identify Knowledge Gaps**
-   - Based on research, determine:
-     - What aspects of the domain haven't been discussed yet?
-     - What decisions does the user need to make?
-     - What are common pitfalls in this space?
-     - What skills will Mother Brain need to help with this?
-   
-   - Add skill candidates to running list:
-     ```
-     🛠️ Skill needs identified so far:
-     - [skill-1]: [why it's needed]
-     - [skill-2]: [why it's needed]
-     ```
-   
-   **3.2.4: Generate Dynamic Follow-Up Question**
-   - Based on research and gaps, ask the MOST RELEVANT next question
-   - This should NOT be from a static list - it should be informed by:
-     - What research revealed about the domain
-     - What the user hasn't addressed yet
-     - What decisions will significantly impact the project
-   
-   - Example evolution:
-     - User says "roguelite car game with storybook art"
-     - Research: roguelite mechanics, car game physics, storybook illustration
-     - Generated question: "Roguelites rely heavily on the core gameplay loop - what's the moment-to-moment action? Is it racing, combat, exploration, or something else?"
-   
-   - Use `ask_user` with:
-     - 2-3 relevant options based on research
-     - Freeform allowed for complex answers
-   
-   **Step 3.3: Core Areas to Cover (Ensure These Are Addressed)**
-   
-   Through adaptive questioning, ensure these areas are explored (not as a checklist, but organically based on the domain):
-   
-   - **The Problem/Opportunity**: What pain point or gap exists?
-   - **The Vision**: What does success look like?
-   - **The Users**: Who benefits? Who uses it?
-   - **User Needs (CRITICAL)**: What specific abilities does the user need? Capture these as "Ability to [do something]" statements. These become the foundation for the outcome-driven roadmap.
-   - **Differentiators**: What makes this unique in the space?
-   - **Aesthetic/Experience**: How should it feel? Look? Sound?
-   - **Constraints**: Budget, skills, platform limitations?
-   - **MVP Scope**: Which user needs are essential for MVP vs nice-to-have?
-   - **Data Sensitivity (MANDATORY)**: If project involves user/customer data:
-     - Identify what data is handled (PII, orders, payments, health data, financial data, personal info)
-     - Ask: "Who should have access to this data?"
-     - Flag access control/authentication as a hard requirement
-     - Document in vision.md under "Security & Access Requirements"
-     - This triggers authentication/authorization tasks in Phase 1 (not post-MVP)
-     - Example: "Dashboard shows customer orders → authentication required before deployment"
-   
-   **Domain-Specific Questions (Generated From Research)**:
-   - For games: gameplay loop, art style, audio needs, target platform
-   - For e-commerce: payment integration, inventory management, shipping
-   - For SaaS: authentication, multi-tenancy, pricing model
-   - For mobile apps: offline capability, push notifications, app store requirements
-   - For Shopify: theme vs app, API usage, merchant needs
-   - For APIs: authentication, rate limiting, documentation needs
-   
-   **Step 3.4: Vision Summary and Skill Pre-Planning**
-   
-   - When sufficient understanding is reached (typically 6-10 exchanges):
-   
-   - Display comprehensive summary:
-     ```
-     🧠 Vision Summary
-     
-     **What You're Building:**
-     [1-2 sentence description]
-     
-     **Who It's For:**
-     [Target users/audience]
-     
-     **Key Features:**
-     - [Feature 1]
-     - [Feature 2]
-     - [Feature 3]
-     
-     **Aesthetic/Experience:**
-     [How it should look, feel, sound]
-     
-     **Success Looks Like:**
-     [What proves this works]
-     
-     **Domain Research Findings:**
-     [Key insights from research that will inform development]
-     
-     🛠️ **Skills Mother Brain Will Need:**
-     - [skill-1]: [what it will handle]
-     - [skill-2]: [what it will handle]
-     - [skill-3]: [what it will handle]
-     ```
-   
-   - Use `ask_user` with choices:
-     - "This captures it perfectly"
-     - "Mostly right, but let me clarify something"
-     - "I want to change the direction"
-   
-   - If clarification needed: Ask follow-up, update summary
-   - If direction change: Return to Step 3.2
-   
-   **Step 3.5: Store Research and Skill Candidates**
-   
-   - Before proceeding to project setup:
-     - Store domain research in `.mother-brain/domain-research.md`
-     - Store skill candidates in `.mother-brain/skill-candidates.md`
-   - These will be used during:
-     - Roadmap generation (Step 5)
-     - Skill creation (Step 6)
-     - Task execution (Step 9)
-   
-   **NOTE: Do NOT ask about timeline/duration.** AI execution speed is not a constraint.
-
-   - Proceed to Step 3.6 (Project Folder Setup)
+   - Adaptive, research-driven vision discovery. After EACH user response: extract domain signals, research via web_search, identify gaps, generate dynamic follow-ups.
+   - **Read `references/vision-discovery.md`** for the full discovery procedure (Steps 3.1–3.5, adaptive response loop, domain-specific questions, vision summary, skill pre-planning)
+   - Covers 6-10 adaptive exchanges. Do NOT ask about timeline. Proceeds to Step 3.6 (Project Folder Setup).
 
 ### 3.6. **Initialize Mother Brain in Current Directory** (MANDATORY)
    
@@ -1709,117 +967,9 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - Display: `📋 Value Framework created — this will guide task prioritization`
 
 ### 5. **Technology & Pattern Analysis**
-   - **Dynamic Research-Driven Discovery**:
-     
-     **Step 5.1: Identify Project Type**
-     - From vision document, determine project category:
-       - Web app, mobile app, desktop software, CLI tool, library/framework
-       - Gaming, SaaS, ecommerce, content platform, developer tooling, etc.
-     
-     **Step 5.2: Market & Competitor Analysis (MANDATORY)**
-     - Use `web_search` to research:
-       1. "[project domain] competitor analysis [current year]"
-       2. "top [project type] apps/platforms comparison"
-       3. "[project domain] market landscape and gaps"
-       4. "what makes successful [project type] stand out"
-     - Save findings to `.mother-brain/docs/research/market-analysis.md`
-     - Document:
-       - **Direct Competitors**: Who else solves this problem? What are they?
-       - **Strengths**: What do competitors do well?
-       - **Weaknesses**: Where do competitors fall short?
-       - **Market Gaps**: Unmet needs, underserved segments
-       - **Differentiation Opportunities**: How can this project stand out?
-     
-     **Step 5.3: User Research (MANDATORY)**
-     - Use `web_search` to research:
-       1. "what [target users] want in [project domain]"
-       2. "[target user] pain points and frustrations with [existing solutions]"
-       3. "[project domain] user research findings"
-       4. "why users leave/switch [competitor type] apps"
-     - Save findings to `.mother-brain/docs/research/user-research.md`
-     - Document:
-       - **Target Users**: Who exactly are they? Demographics, behaviors
-       - **Pain Points**: What frustrates users with existing solutions?
-       - **Unmet Needs**: What do users wish they had?
-       - **Must-Have Features**: Non-negotiables for this user base
-       - **Delighters**: Features that would surprise and delight
-     
-     **Step 5.4: Technical Best Practices Research**
-     - Use `web_search` to research:
-       1. "best practices for [project type] development [current year]"
-       2. "team roles needed for [project type] projects"
-       3. "common technical patterns in [project type]"
-       4. "project management methodology for [project type]"
-       5. "documentation standards for [project type]"
-       6. "quality assurance approach for [project type]"
-     
-     **Step 5.4.1: Technology Pitfalls & Gotchas Research (MANDATORY)**
-     - For EACH technology/platform/tool identified in vision or research:
-       
-       **First, invoke Elder Brain RETRIEVE for each technology:**
-       - Invoke `skill elder-brain` with query for each technology
-       - Elder Brain searches the experience vault and returns known gotchas
-       - If gotchas found: use this knowledge to inform skill creation (no re-research needed)
-       
-       **If Elder Brain has no knowledge, research and contribute:**
-       - Use `web_search` to research:
-         1. "common [technology] mistakes and pitfalls [current year]"
-         2. "[technology] gotchas first-time users encounter"
-         3. "[technology] troubleshooting guide"
-       - After research, invoke Elder Brain RECEIVE to store findings in the vault
-       - Also save project-specific notes to `.mother-brain/docs/research/[technology]-gotchas.md`
-       
-       **Result:**
-       - Research gets embedded in skills created for this technology
-       - Elder Brain grows with each project's discoveries
-     
-     **Step 5.5: Extract Technical Insights from Research**
-     - Parse research results to identify:
-       - **Roles/Disciplines**: (e.g., designer, architect, QA, DevOps, DBA)
-       - **Methodologies**: (e.g., Agile, TDD, definition of done, sprint planning)
-       - **Technical Patterns**: (e.g., auth flows, API design, state management)
-       - **Documentation Needs**: (e.g., architecture docs, API specs, test plans)
-       - **Tools & Libraries**: (e.g., testing frameworks, design systems, CI/CD)
-       - **Quality Standards**: (e.g., accessibility, performance, security)
-     
-     **Step 5.6: Synthesize & Log Findings** (No User Confirmation Required)
-     - Save to `.mother-brain/docs/research/technical-analysis.md`
-     - Display findings organized by category (for transparency, not approval):
-       ```
-       🔍 Research-Based Analysis for [Project Type]:
-       
-       Market Position:
-       - Competitors analyzed: [list]
-       - Key differentiation: [how this project is unique]
-       
-       User Insights:
-       - Target users: [who]
-       - Top pain points: [list]
-       - Must-have features: [list]
-       
-       Technology Stack:
-       - [Recommendations based on research + vision]
-       
-       Team Roles/Disciplines Identified:
-       - [Roles that research suggests are needed]
-       
-       Methodology Recommendations:
-       - [Process/methodology from research]
-       
-       Repetitive Patterns Found:
-       1. [Pattern from research] - [Skill candidate]
-       2. [Pattern from research] - [Skill candidate]
-       
-       Documentation Needs:
-       - [Project docs suggested by research]
-       
-       Quality Standards:
-       - [Testing, accessibility, performance standards]
-       ```
-     
-     - **Proceed immediately** to Step 5A (if visual requirements) or Step 6 (Skill Identification)
-     - Do NOT ask user to validate or approve research findings - Mother Brain is the expert
-   - **After displaying findings**: Proceed to Step 5A (check for visual requirements) or Step 6 (Skill Identification)
+   - Research-driven analysis: market/competitor analysis, user research, technical best practices, and technology pitfalls via Elder Brain + web search.
+   - **Read `references/technology-analysis.md`** for the full analysis procedure (Steps 5.1–5.6, market analysis, user research, gotchas research, synthesis)
+   - Outputs saved to `.mother-brain/docs/research/`. Proceeds automatically to Step 5A (if visual) or Step 6 (Skill Identification).
 
 ### 5A. **Design System & Brand Discovery** (For Projects with Visual Requirements)
    - **Automatic Detection**: Scan vision document for visual requirement keywords
@@ -1915,121 +1065,9 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - **After completing Step 5A**: Proceed immediately to Step 6 (Skill Identification)
 
 ### 6. **Skill Identification & Creation**
-   - **Dynamic Skill Discovery** (from Step 5 research findings):
-     
-     - For each **role/discipline** identified in research:
-       - Evaluate if that role's work involves repetitive patterns
-       - Example: Designer role → design system skill, brand guidelines skill
-       - Example: QA role → testing automation skill, test plan generator
-     
-     - For each **technical pattern** identified in research:
-       - Evaluate if pattern warrants a skill:
-         - **Frequency**: Will this happen 3+ times in project?
-         - **Complexity**: Is there wizard-worthy context to gather?
-         - **Reusability**: Could this apply to other [project type] projects?
-     
-     - For each **documentation need** identified:
-       - Consider if generation should be automated
-       - Example: Architecture diagrams, API documentation, test plans
-     
-     - Categorize skills by necessity:
-       - **Essential Skills** (create automatically): Core roles/patterns/needs required for MVP delivery
-       - **Optional Skills** (offer choice): Nice-to-have features, post-MVP enhancements, documentation generators
-     
-     - Identify essential vs optional:
-       - **Essential criteria**: Needed for MVP, core technical pattern (3+ uses), fundamental role (designer, QA, architect)
-       - **Optional criteria**: Post-MVP features, one-time documentation, nice-to-have automation
-     
-     - Display categorized list (for transparency, not approval):
-       ```
-       🎯 Research-Based Skills Identified:
-       
-       Essential Skills (creating automatically):
-       1. [skill-name] - [what role/pattern needs it] - [why essential for MVP]
-       2. [skill-name] - [what role/pattern needs it] - [why essential for MVP]
-       
-       Optional Skills (creating if beneficial):
-       3. [skill-name] - [what it does] - [when useful]
-       4. [skill-name] - [what it does] - [when useful]
-       ```
-     
-     - **Skill Creation Lifecycle Strategy**:
-       - **Upfront Phase** (Step 6): Create minimum 3 foundational skills
-         - Select 3 most critical skills from essential list
-         - These provide core capabilities needed immediately
-         - Document remaining identified skills in Project Brain
-       
-       - **Continuous Creation** (Throughout project):
-         - Skills should be created throughout project lifecycle, not all upfront
-         - At start of each task (Step 9), check Project Brain for:
-           - Existing skills that apply to this task
-           - Skills identified but not yet created (create now if task needs them)
-           - New patterns emerging in this task (create new skills mid-task)
-         - Project Brain tracks:
-           - `skillsCreated`: Skills that exist
-           - `skillsPending`: Skills identified but not yet created
-           - `skillsNeededForTasks`: Map of which tasks need which skills
-         
-       - **Task-Start Skill Assessment** (Mandatory at Step 9):
-         1. Load Project Brain before starting task
-         2. Check which skills exist and apply to this task
-         3. Check if task requires pending skills (create them now)
-         4. Check if task reveals new skill needs (document in Project Brain)
-         5. Use relevant skills during task execution
-       
-       - **Why This Approach**:
-         - Minimum viable skill set upfront (3) doesn't delay project start
-         - Skills created when actually needed = better context and design
-         - Continuous skill creation = skills evolve with project understanding
-         - Project Brain coordination = no duplicate skill creation
-     
-     
-     - **Create Initial 3 Skills** (Upfront - minimum viable skill set):
-       - Display: "🔨 Creating initial 3 skills for project..."
-       - Select 3 most critical skills from essential list (based on immediate MVP needs)
-       
-       - **CHECKPOINT: Consult Elder Brain for Each Skill**
-         - Before invoking skill-creator for each skill:
-           1. Identify domains/technologies this skill will work with
-           2. Invoke Elder Brain RETRIEVE for each technology
-           3. Elder Brain returns known gotchas and patterns (or "no knowledge found")
-           4. Pass Elder Brain results as context to skill-creator
-       
-       - For each of the 3 initial skills:
-         - Show progress: "Creating [skill-name]..."
-         - Invoke skill-creator with THREE knowledge sources:
-           1. **Research findings** from Step 5 analysis (role/pattern/need)
-           2. **Gotchas research** from Step 5.4.1 (project-specific research)
-           3. **Elder Brain knowledge** (cross-project domain wisdom from RETRIEVE)
-         - Let skill-creator run its wizard with all three knowledge sources
-         - **Store created skills in `.github/skills/`** (CLI-discoverable location)
-         - **Symlink to `.agents/skills/`** for Codex CLI compatibility
-         - **Track in session-state.json**: Add skill name to `skillsCreated` array
-         - **VALIDATE SKILL** (CRITICAL - prevents task execution failures):
-           1. Check `.github/skills/[skill-name]/SKILL.md` exists
-           2. Test invoke the skill with a simple "hello" or status check
-           3. If invocation fails:
-              - Show error: "⚠️ Skill [name] created but can't be invoked"
-              - Diagnose issue (path, permissions, SKILL.md format)
-              - Retry automatically up to 2 times
-              - If still fails, log and continue - don't block on one skill
-           4. Only mark complete if skill invokes successfully
-         - Show completion: "✅ [skill-name] created and validated"
-       
-       - **Document remaining skills in Project Brain**:
-         - Create/update `.mother-brain/project-brain.md` with:
-           - `skillsCreated`: [list of 3 created skills]
-           - `skillsPending`: [list of remaining identified skills]
-           - `skillsNeededForTasks`: Map of which upcoming tasks will need which pending skills
-         - Display: "📘 Documented [N] additional skills for later creation"
-       
-       - **After initial 3 skills created**:
-         - Display summary: "Initial skills ready: [list of 3 validated skills]"
-         - Display: "Additional skills will be created as tasks require them"
-         - Log in session-state.json: skillsCreated array with validated names
-         - This ensures Step 9 can reliably invoke these skills
-         - **Proceed immediately** - do not ask user to approve skills created
-   - **After skills are created**: Proceed immediately to Step 6A (Delivery Strategy Research)
+   - Dynamic skill discovery from research findings: roles, technical patterns, and documentation needs. Creates minimum 3 foundational skills upfront.
+   - **Read `references/skill-identification.md`** for the full skill identification and creation procedure (lifecycle strategy, Elder Brain consultation, skill validation, Project Brain tracking)
+   - Remaining skills documented in Project Brain for continuous creation during task execution (Step 9)
 
 ### 6A. **Delivery Strategy Research**
    - **Research How to Deliver This Type of Project**:
@@ -2090,258 +1128,9 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
      - Do NOT ask user to approve delivery strategy - Mother Brain is the expert
 
 ### 7. **Roadmap Generation**
-   - **MVP-First Phasing Using Research Findings + Value Framework**:
-   
-   **Step 7.0: Load Value Framework**
-   - Read `.mother-brain/docs/value-framework.md`
-   - Use the priority dimensions and weights to order **outcomes** (not tasks)
-   - Every outcome in the roadmap must be scored against the framework
-   
-   **Step 7.1: Define Phase 1 = MVP (Core User Needs)**
-   - Phase 1 scope = shortest path to fulfill core user needs from vision
-   - Use:
-     - User Needs table from Step 4 (vision document) — filter by MVP=✅
-     - Delivery research from Step 6A
-     - Mother Brain's expert judgment on optimal scope
-   - Mother Brain determines which user needs are essential for Phase 1 vs can wait
-   - Each user need becomes an **Outcome** (📋 Ability to...)
-   - Each outcome has **Acceptance Criteria** (testable by user)
-   - Tasks are internal implementation details — user validates outcomes, not tasks
-   
-   **Step 7.2: Structure Post-MVP Work (Research-Driven)**
-   - Phase 2+ content based on iteration pattern from Step 6A research
-   - Use feedback mechanism identified in research
-   - Mark clearly as "post-MVP" and "subject to learning/validation"
-   - Don't over-plan: assume learnings will inform these phases
-   
-   **Step 7.3: Create `docs/roadmap.md` (Outcome-Driven Structure)**:
-     ```markdown
-     # [Project Name] - Roadmap
-     
-     ## Delivery Strategy (Research-Based)
-     **Project Type**: [From Step 5 research]  
-     **MVP Approach**: [From Step 6A research - what minimum viable means for this type]  
-     **Launch Pattern**: [From Step 6A research - how to reach users]  
-     **Iteration Strategy**: [From Step 6A research - how to improve post-launch]
-     
-     ---
-     
-     ## User Needs Traceability
-     
-     | User Need (from Vision) | Fulfilled By |
-     |-------------------------|--------------|
-     | Ability to [X] | Outcome 1, Outcome 3 |
-     | Ability to [Y] | Outcome 2 |
-     | Ability to [Z] | Outcome 4 (Phase 2) |
-     
-     ---
-     
-     ## Phase 1: MVP — [Core Problem Solution]
-     
-     **Goal**: Shortest path to deliver user value  
-     **Success Gate**: User can [primary outcome from vision]  
-     **Strategy**: Fulfill core user needs, defer everything else
-     
-     ---
-     
-     ### 📋 Ability to [do something concrete]
-     
-     > So [the benefit/why this matters — traced to user need]
-     
-      **Acceptance Criteria:**
-      - [ ] [Testable condition 1 — user can verify this]
-      - [ ] [Testable condition 2 — user can verify this]
-      - [ ] [Testable condition 3 — user can verify this]
-
-      **Demo / Proof (what the user will see):**
-      - [What screen/page/flow will exist at the end of this outcome]
-      - [How Mother Brain will open it for the user (browser/app route)]
-      
-      **Priority Score:** [N] (Vision: X, MVP: X, User Impact: X)
-     
-     **🔧 Tasks (internal — not shown to user during validation):**
-     - Task 001: [Technical implementation step]
-     - Task 002: [Technical implementation step]
-     - Task 003: [Technical implementation step]
-     
-     ---
-     
-     ### 📋 Ability to [second outcome]
-     
-     > So [benefit — traced to user need]
-     
-      **Acceptance Criteria:**
-      - [ ] [Testable condition 1]
-      - [ ] [Testable condition 2]
-
-      **Demo / Proof:**
-      - [User-visible experience delivered]
-      - [How it will be opened for validation]
-      
-      **Priority Score:** [N]
-     
-     **🔧 Tasks (internal):**
-     - Task 004: [Technical step]
-     - Task 005: [Technical step]
-     
-     ---
-     
-     ## Phase 2+: Post-MVP Iteration
-     
-     **Strategy**: [Iteration approach from Step 6A research]  
-     **Trigger**: Phase 1 complete + user feedback  
-     **Focus**: Learn from users and iterate
-     
-     ### 📋 Ability to [future outcome]
-     
-     > So [benefit]
-     
-      **Acceptance Criteria:**
-      - [ ] [Criterion 1]
-      - [ ] [Criterion 2]
-
-      **Demo / Proof:**
-      - [User-visible experience delivered]
-      - [How it will be opened for validation]
-      
-      **Note**: Subject to validation — may change based on user feedback
-     
-     ---
-     
-     ## MVP Checkpoint (End of Phase 1)
-     
-     ✅ **Phase 1 Complete When ALL acceptance criteria verified for:**
-     - Outcome 1: [name]
-     - Outcome 2: [name]
-     - Outcome 3: [name]
-     
-     **Validation Method**: User confirms each criterion with "Yes, I can do this"
-     
-     **Next Step After MVP**: [From Step 6A research]
-     
-     ---
-     
-     ## Future Enhancements (Post-MVP Backlog)
-     
-     **Defer Until After MVP** (nice-to-have):
-     - 📋 Ability to [future feature 1]
-     - 📋 Ability to [future feature 2]
-     
-     **Validation Required**: Don't build until validated by user feedback
-     
-     ---
-     
-     ## Internal Task Index
-     
-     > Tasks exist for implementation tracking but are NOT validated by user.
-     > User validates outcomes (acceptance criteria), not tasks.
-     
-     | Task | Under Outcome | Status |
-     |------|---------------|--------|
-     | 001 | Ability to X | ⬜ |
-     | 002 | Ability to X | ⬜ |
-     | 003 | Ability to Y | ⬜ |
-     
-     ---
-     
-     ## Iteration & Learning Plan (Research-Based)
-     
-     **Feedback Collection** (from Step 6A research):
-     - [How we'll gather user input for this project type]
-     - [Metrics/analytics to track]
-     
-     **Iteration Cycle**:
-     1. Complete Phase 1 outcomes
-     2. User validates all acceptance criteria
-     3. Collect feedback, analyze learnings
-     4. Prioritize Phase 2 outcomes based on data
-     
-     ---
-     
-     ## Risk Mitigation
-     
-     **MVP Risks**: [Potential issues with Phase 1 approach]
-     
-     **Delivery Strategy**: Protect MVP outcomes at all costs. Phase 2+ can be deferred.
-     
-     ---
-     
-     **Total Tasks**: [Count]  
-     **Phase 1 (MVP) Tasks**: [Count essential tasks]  
-     **Post-MVP Tasks**: [Count - subject to change based on feedback]  
-     **Estimated Timeline**: [From vision document]
-     ```
-   
-   **Step 7.3.5: CHECKPOINT - Review Roadmap Against Elder Brain**
-   - **Purpose**: Surface known pitfalls for the tech stack BEFORE task execution begins
-   
-   - For EACH technology/platform identified in roadmap tasks:
-     1. Extract tech mentions from task descriptions
-     2. Invoke Elder Brain RETRIEVE for each technology
-     3. Elder Brain returns known gotchas or "no knowledge found"
-     4. For each gotcha found: add defensive note to affected task descriptions in roadmap
-     5. If no Elder Brain knowledge exists: note for research during task execution
-   
-   - Display:
-     ```
-     🧙 Elder Brain consulted
-     - [X] technologies checked
-     - [Y] known gotchas surfaced in roadmap
-     ```
-   
-   - Update roadmap.md with Elder Brain references
-   - This makes pitfalls visible BEFORE tasks start, not during failures
-   
-   **Step 7.4: Display Roadmap Summary** (No Approval Required)
-     - Show roadmap structure to user (for transparency, not approval)
-     - Display:
-       ```
-       📋 Roadmap Created - UK Coffee Discovery
-       
-       Phase 1 (MVP): [X] tasks
-       - [Brief description of what MVP delivers]
-       
-       Phase 2+: [Y] tasks (subject to user feedback)
-       
-       Skills Ready: [List skills created]
-       ```
-     - **Proceed immediately** to Step 7.5 (Setup Complete Menu)
-     - Do NOT ask user to approve roadmap - Mother Brain determined optimal phasing
-   
-   **Step 7.5: Setup Complete - What's Next?**
-   - **⚠️ CRITICAL**: This is NOT the end of setup. Step 7.6 (Reflection) is MANDATORY before declaring complete.
-   - Display setup completion summary:
-     ```
-     ✅ Setup Complete!
-     
-     📋 Vision: Captured
-     🔍 Research: Complete
-     🛠️ Skills: [X] created and validated
-     📊 Roadmap: [Y] tasks across [Z] phases
-     📄 First Task: [Task 001 name] ready
-     
-     🔄 Next: Running mandatory reflection (Step 7.6)...
-     ```
-   
-   - Use `ask_user` with choices:
-     - "Start Task 001 now"
-     - "Review the full roadmap first"
-     - "Review the vision document"
-     - "I want to adjust something before starting"
-   
-   - **⛔ BLOCKING GATE**: Regardless of user selection, you MUST run Step 7.6 (Setup Validation & Self-Healing) BEFORE proceeding to the chosen action.
-   
-   - If "Start Task 001 now": Run Step 7.6 (mandatory), then proceed to Step 8 (Task Document Creation)
-   - If "Review roadmap": Run Step 7.6 (mandatory), display full roadmap, then return to this menu
-   - If "Review vision": Run Step 7.6 (mandatory), display vision summary, then return to this menu
-   - If "Adjust something": Run Step 7.6 (mandatory), use `ask_user` to ask what needs adjusting, make changes, return to this menu
-   
-   - **DO NOT declare "setup complete" or proceed to ANY action without running Step 7.6 first**
-   
-   - Use outcome-focused language (what gets achieved, not just tasks)
-   - Link Phase 1 tasks back to MVP criteria from vision
-   - Mark post-MVP items clearly as "subject to validation"
-   - Emphasize learning and iteration mindset
+   - MVP-first phased roadmap generation using Value Framework scores, research findings, and Elder Brain consultation.
+   - **Read `references/roadmap-generation.md`** for the full roadmap procedure (Steps 7.0–7.5, roadmap template, Elder Brain checkpoint, setup completion menu)
+   - Creates `docs/roadmap.md` with outcome-driven structure, user needs traceability, and phase gates. Step 7.6 (Setup Validation) is MANDATORY before proceeding.
 
 ### 7.6 **Setup Validation & Self-Healing (MANDATORY REFLECTION - BLOCKS COMPLETION)**
    - **Read `references/setup-validation.md`** for the full protocol (Steps 7.6.1–7.6.5)
@@ -2403,282 +1192,9 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - User validates only when ALL tasks under an outcome are complete (Step 10)
 
 ### 9. **Task Execution**
-
-   **⛔ MANDATORY TASK START GATE - DO NOT SKIP**
-   
-   Before implementing ANY task, you MUST complete this gate:
-   
-   **Step 9.0: Story Start Assessment**
-   
-   1. **Load Project Brain** (if exists):
-      - Read `.mother-brain/project-brain.md`
-      - Review "Validation Checks" section
-      - Check "Style & Tone" preferences for relevant categories
-      - **Check skill tracking sections**:
-        - `skillsCreated`: Skills that exist and are available
-        - `skillsPending`: Skills identified but not yet created
-        - `skillsNeededForTasks`: Map of which tasks need which skills
-      - **If this task needs a pending skill**:
-        - Create that skill NOW before implementing task
-        - Update skillsCreated and skillsPending arrays
-        - Validate skill works before proceeding
-   
-   2. **Analyze Task Requirements**:
-      - What creative/visual/narrative elements does this task involve?
-      - What domain knowledge is required?
-      - What style/tone preferences apply?
-      - **What technologies/platforms does this task use?** (for Elder Brain check)
-   
-   2.5. **CHECKPOINT: Consult Elder Brain for This Task**
-      - Extract technology/platform mentions from task title, description, and deliverables
-      - Invoke Elder Brain RETRIEVE for each technology
-      - Elder Brain returns known gotchas and defensive patterns (or "no knowledge found")
-      
-      - If gotchas found:
-        - Display relevant gotchas for awareness
-        - Apply defensive patterns automatically during execution
-        ```
-        🧙 Elder Brain: [Technology]
-        
-        Known gotchas for this task:
-        - [gotcha 1]
-        - [gotcha 2]
-        
-        Applying defensive patterns automatically.
-        ```
-      
-      - If NO gotchas found:
-        - Note: "No Elder Brain knowledge for [technology]"
-        - Plan to contribute back via Elder Brain RECEIVE after task
-   
-   **Step 9.0.1: Blocking Dependencies Collection (MANDATORY)**
-   
-   Before starting ANY story, identify what the AI CANNOT do autonomously:
-   
-   **Check for these dependency types:**
-   - **Account/Service Setup**: Creating accounts, subscribing to services, accepting terms of service
-   - **API Keys & Credentials**: Obtaining keys, secrets, OAuth tokens the AI cannot generate
-   - **External Configuration**: Setting up third-party consoles, enabling features in dashboards
-   - **Physical Actions**: Device setup, hardware configuration, local installations the AI can't perform
-   - **Payment/Billing**: Anything requiring financial transactions
-   
-   **If ANY blocking dependencies found:**
-   ```
-   ⏸️ Before I can work autonomously on this story, I need you to:
-   
-   1. [Blocking dependency 1 - what exactly to do]
-   2. [Blocking dependency 2 - what exactly to do]
-   3. [Blocking dependency 3 - what exactly to do]
-   
-   Let me know when these are ready, or if you need help with any step.
-   ```
-   
-   - **WAIT for user confirmation before proceeding**
-   - Update session-state.json with `blockingDependencies` array
-   - When user confirms, verify programmatically where possible (see VERIFICATION OVER TRUST principle)
-   - Only proceed to implementation when all blocking dependencies resolved
-   
-   3. **Skill Sufficiency Check** (CRITICAL):
-      - List existing skills in `.github/skills/`
-      - For EACH creative/specialized element in this task, ask:
-        - "Is there a skill that covers this?"
-        - "Does that skill have the domain knowledge needed?"
-        - "Does that skill know this project's style preferences?"
-      - If ANY answer is "No" → STOP and address before implementing
-   
-   4. **User Discovery Questions** (if gaps found):
-      - Before creating missing skills, ask user about preferences:
-        - "What style/tone do you want for [element]?"
-        - "Any examples or references I should look at?"
-        - "Any specific conventions or requirements?"
-      - Store answers in Project Brain AND use them for skill creation
-      - **Note**: For broader preference discovery beyond skills (layout, interaction patterns, UX choices), see **Step 9.1: Mini Discovery**
-   
-   5. **Skill Creation/Enhancement** (if needed):
-      - Research the domain (web_search for best practices)
-      - Invoke skill-creator with user preferences + research
-      - Validate skill was created successfully
-      - Log in Project Brain: "Skills Created for This Project"
-   
-   6. **Proceed to Implementation**:
-      - Only after gate passes, begin actual implementation
-      - Use appropriate skills for execution
-   
-   Display at task start:
-   ```
-   🎯 Task [Number] Start Assessment
-   
-   📘 Project Brain:
-   - Style preferences: [found/not found]
-   - Validation checks: [X] checks to run
-   - Skills created: [X] available
-   - Skills pending: [Y] identified for later
-   - This task needs: [list pending skills this task requires, if any]
-   
-   🛠️ Skill Coverage:
-   - [element 1]: [skill-name] ✅ or [PENDING - creating now] ⏳ or [MISSING] ❌
-   - [element 2]: [skill-name] ✅ or [PENDING - creating now] ⏳ or [MISSING] ❌
-   
-   [If all covered]: Proceeding to implementation...
-   [If pending skills needed]: Creating required skills first...
-   [If gaps]: Need to address gaps before implementing...
-   ```
-   
-   ---
-
-   **Step 9.1: Mini Discovery (On-Demand Preference Check)**
-
-   Mini Discovery is a lightweight discovery phase that triggers MID-BUILD when Mother Brain identifies it knows the OUTCOME but not the SPECIFICS of how the user wants it delivered. It's like a focused version of Vision Discovery (Step 3) that happens during task execution.
-
-   **When to Trigger (ANY of these):**
-   - Task involves **user-facing output** (UI, content, messaging, branding) and Project Brain has no style preferences for this category
-   - Task has **multiple valid approaches** and user hasn't indicated preference (e.g., modal vs page, tabs vs accordion, dark vs light)
-   - Task involves **creative/aesthetic choices** (color, layout, tone, personality)
-   - Task requires **workflow/interaction design** (how will users actually USE this feature?)
-   - Mother Brain catches itself about to **guess or assume** specifics the user hasn't specified
-
-   **When to SKIP:**
-   - Technical infrastructure (CI/CD, database migrations, dependency installs)
-   - Bug fixes with clear reproduction steps and expected behavior
-   - Tasks where Project Brain already has documented preferences for this category
-   - Tasks where the user explicitly said "just make it work, I'll refine later"
-
-   **Mini Discovery Process:**
-
-   1. **Identify the Unknowns** — List what you DON'T know:
-      ```
-      🔍 Mini Discovery — Task [Number]
-
-      I know the goal: [outcome]
-      But I need to understand:
-      - [Unknown 1: e.g., "How should the settings page be laid out?"]
-      - [Unknown 2: e.g., "What tone should error messages use?"]
-      - [Unknown 3: e.g., "Should this be a modal or a full page?"]
-      ```
-
-   2. **Ask Targeted Questions** — NOT open-ended. Offer concrete options:
-      ```
-      For [unknown], which approach do you prefer?
-      1. [Option A] — [brief description/tradeoff]
-      2. [Option B] — [brief description/tradeoff]
-      3. [Option C] — [brief description/tradeoff]
-      
-      Reply with the number or describe what you have in mind.
-      ```
-      - Ask 1-3 questions max per Mini Discovery (don't overwhelm)
-      - Show visual examples or references when possible
-      - If user says "you decide" → pick the most common/conventional approach and note it in Project Brain
-
-   3. **Research if Needed** — If user references something unfamiliar:
-      - Use `web_search` to find examples, patterns, or best practices
-      - Show user what you found: "Here's what [reference] looks like — is this the direction?"
-
-   4. **Record Discoveries** — Update Project Brain with new preferences:
-      - Add to Style & Tone section
-      - Add to Validation Checks if applicable
-      - Update vision doc if discoveries reveal scope changes
-
-   5. **Expand Roadmap if Needed** — If Mini Discovery reveals:
-      - The task is bigger than estimated → split into sub-tasks
-      - A prerequisite is missing → add it before current task
-      - A new feature emerged from discussion → add to roadmap backlog
-      - Display: "📋 Roadmap updated with [X] new items from Mini Discovery"
-
-   6. **Build/Update Skills** — If discoveries reveal domain knowledge:
-      - Create or update skills with user preferences
-      - These skills now carry the user's specific choices for future tasks
-
-   **Display at Mini Discovery start:**
-   ```
-   🔍 Mini Discovery — before I build this, let me understand what you're looking for...
-   ```
-
-   **Display at Mini Discovery end:**
-   ```
-   ✅ Mini Discovery complete — proceeding with implementation
-   📘 Project Brain updated with [X] new preferences
-   ```
-
-   **KEY PRINCIPLE**: The goal is to understand HOW the user will experience the outcome, not just WHAT the outcome is. A login page can be minimal or elaborate, friendly or corporate, social-login-first or email-first — Mini Discovery captures these specifics so Mother Brain builds what the user actually envisioned.
-
-   ---
-
-   - **Pre-Task Analysis** (after gate passes):
-     - Load current task document
-     - Look ahead at next 3-5 tasks in current phase
-     - Identify patterns across these tasks that might warrant new skills
-     - If patterns found:
-       - Invoke skill-creator to create skills proactively
-       - Do NOT ask user for approval (Expert Autonomy)
-   
-   - **DATA EXPOSURE CHECK (MANDATORY - BLOCKING GATE)**:
-     - Before implementing ANY task, check:
-       - Does this task involve displaying/exposing user or customer data?
-       - Data types to watch for: PII, orders, payments, health records, personal info, financial data, private messages, user activity
-     - If task exposes sensitive data:
-       1. Check if authentication/authorization exists in project
-       2. If NO auth exists → BLOCK implementation
-       3. Display: "⚠️ BLOCKED: This task exposes [data type] without access control. Authentication required first."
-       4. Check roadmap for auth task → If missing, add "Authentication & Authorization" task to Phase 1
-       5. Guide user: "Let's implement authentication before continuing with data-facing features"
-     - This is a BLOCKING GATE - do NOT implement data-exposing features without access control
-     - Only unblock when auth is implemented OR user explicitly confirms data is public/non-sensitive
-   
-   - **MANDATORY Skill Check for Creative/Visual/Narrative Tasks**:
-     - Before implementing ANY task that involves:
-       - **Visual art**: Pixel art, sprites, character design, scene backgrounds, UI design
-       - **Narrative**: Dialogue, story text, character voice, personality writing
-       - **Audio**: Sound design, music, audio cues
-       - **Animation**: Movement cycles, visual effects, transitions
-     - MUST check `.github/skills/` for relevant existing skills
-     - If NO relevant skill exists:
-       1. STOP implementation immediately
-       2. Research the domain (use web_search for best practices)
-       3. Invoke skill-creator to create the required skill(s)
-       4. THEN resume task execution using the new skill(s)
-     - This is NON-NEGOTIABLE for quality - never improvise creative work without proper skill creation
-     - Example triggers:
-       - "Pixel art horses" → requires pixel-art-renderer skill
-       - "Personality dialogue" → requires game-narrative-designer skill
-       - "Stable background scene" → requires pixel-art-renderer skill
-       - "Character expressions" → requires both pixel-art-renderer AND game-narrative-designer
-   
-   - **Mid-Task Skill Detection (MANDATORY)**:
-     - During task execution, continuously check: "Is this task revealing a reusable pattern?"
-     - Patterns that warrant skill creation:
-       - **Complexity**: Task requires 100+ lines of specialized code
-       - **Domain expertise**: Task needs research into a specific domain (audio, networking, AI, etc.)
-       - **Reusability**: Pattern would apply to other projects of this type
-       - **Wizard opportunity**: Future invocations would benefit from discovery questions
-     - If pattern detected mid-task:
-       1. Complete current task manually (don't interrupt for skill creation)
-       2. After task completion, before validation, note: "This task revealed a skill opportunity"
-       3. Add to post-task reflection: "[domain]-skill could automate this for future projects"
-       4. In Step 10B, create the skill for future use
-     - Example patterns that should trigger skill creation:
-       - Game sound design → game-sound-designer skill
-       - Database schema design → schema-generator skill  
-       - API integration → api-integrator skill
-       - Animation systems → animation-engine skill
-   
-   - **Skill Matching**:
-     - **Check `.github/skills/`** for all skills (framework + project-specific)
-     - Scan task requirements against available skill capabilities
-     - Identify which skills to use (if any)
-     - Project skills are differentiated by `skillsCreated` array in session-state.json
-   
-   - **Working Directory & Platform Patterns**: Consult Elder Brain for platform-specific patterns (working directory management, Windows directory creation). See `experience-vault/platforms/working-directory-management.md` for known gotchas. Key rule: never assume working directory persists between tool calls — use absolute paths or explicit `Set-Location`.
-   
-   - **Execution**:
-     - If skill exists: Invoke it using `skill` tool with task context
-     - If no skill: Execute task following approach in task doc
-     - Log decisions and progress in task document's "Notes & Decisions" section
-     - Create deliverables as specified
-   
-   - **Error Detection** (if issues occur during execution):
-     - If build fails, tests fail, or output is broken:
-       - Don't just fix and move on
-       - Jump to **Step 9A: Error Detection & Self-Healing**
+   - Mandatory task start gate with Project Brain loading, skill sufficiency check, blocking dependencies, Mini Discovery for user preferences, and mid-task skill detection.
+   - **Read `references/task-execution.md`** for the full execution procedure (Steps 9.0–9.1, data exposure checks, skill matching, working directory patterns, and error detection)
+   - Includes: Elder Brain consultation, Mini Discovery (on-demand preference check), creative/visual skill gates, and continuous skill pattern detection
 
 ### 9A. **Error Detection & Self-Healing**
    - When errors occur during task execution:
@@ -2730,144 +1246,9 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
      - After fixing, continue task execution from where it failed
 
 ### 10. **Task Validation** (Critical)
-   - **DATA EXPOSURE VALIDATION (MANDATORY - BEFORE DEPLOYMENT)**:
-     - If task involves deployment or making UI/API publicly accessible:
-       1. Check what data is exposed by this interface
-       2. If interface shows user/customer data (PII, orders, payments, health records, personal info):
-          - Verify authentication/authorization is implemented
-          - Test that unauthenticated users CANNOT access sensitive data
-          - If NO auth → BLOCK deployment
-          - Display: "⚠️ DEPLOYMENT BLOCKED: This interface exposes [data type] without access control."
-       3. Only allow deployment if:
-          - Authentication exists AND is tested, OR
-          - User explicitly confirms data is public/non-sensitive, OR
-          - Data is anonymized/aggregated with no PII
-     - This is a BLOCKING GATE for deployments - never deploy data-exposing interfaces without access control
-   
-   - After completing deliverables:
-     - ✅ **Build Test**: If code, build/compile it
-     - ✅ **Functional Test**: Present output to user using environment-aware strategy
-       
-       **Environment-Aware Presentation**:
-       1. Load `presentationPreferences` from session-state.json → environment
-       2. Identify output type (HTML, image, JSON, PDF, etc.)
-       3. Match output type to preferred method from environment discovery
-       4. **Presentation Strategy** (layered fallback):
-          - **Primary**: Use stored preference (browser path, VS Code extension, etc.)
-          - **Validate**: Check if method succeeded (process started, no error)
-          - **Fallback 1**: If primary fails, try alternative from `detectedBrowsers` or VS Code
-          - **Fallback 2**: Provide clear manual instructions with full file path
-          - **Update prompt**: If methods fail repeatedly, offer to re-run Step 2.5
-       5. Log presentation method used in task document Notes section
-       
-       **Example - HTML Output**:
-       ```powershell
-       # Load preference from session-state: e.g., "edge" or full path
-       $browserPref = $env.presentationPreferences.html
-       $htmlPath = Resolve-Path "index.html"
-       $fileUrl = "file:///$($htmlPath.Path.Replace('\', '/'))"
-       
-       # If preference is command name (e.g., "msedge"), try it
-       # If preference is full path, use it directly
-       if (Test-Path $browserPref) {
-         Start-Process $browserPref $fileUrl
-       } else {
-         Start-Process $browserPref $fileUrl  # Try as command
-       }
-       
-       # If error, try fallback browser from detectedBrowsers array
-       # Always show: "Or manually open: C:\full\path\index.html"
-       ```
-       
-       **Important**: Browser preference may be:
-       - Command name: "msedge", "chrome", "firefox"
-       - Full path: "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
-       - Handle both cases when invoking
-       
-       **If presentation fails**:
-       - Don't keep retrying the same method
-       - Offer user choice: "Would you like to update presentation preferences?"
-       - Jump to Step 2.5 if user wants to reconfigure
-     
-     - ✅ **Verification**: Test against success criteria
-   
-   - **Roadmap Cross-Check** (CRITICAL - prevents out-of-order implementation):
-     1. Load current outcome from `docs/roadmap.md`
-     2. Identify which acceptance criteria this work addresses
-     3. If user mentions missing features:
-        - Check if feature is in a future outcome
-        - Explain: "That's planned for [Outcome Name]"
-        - Offer: "Continue as planned" or "Adjust roadmap"
-   
-    - **OUTCOME VALIDATION (User validates acceptance criteria, not tasks)**:
-    
-      When ALL tasks under an outcome are complete, present the outcome for validation:
-      
-      ```
-      📋 Outcome Complete: [Ability to do X]
-      
-      Please verify each criterion — can you do this now?
-      ```
-
-    - **MANDATORY: Outcome Demo First (Interactive Experience)**:
-      1. Read `references/outcome-demo.md`
-      2. Launch the experience for the user (app/page/flow) so they can interact with the outcome
-         - Do NOT ask the user to run startup commands
-         - If launching fails, use one fallback, then provide clear manual steps
-      3. Only after the demo is in front of the user, proceed to acceptance-criteria Yes/No sign-off
-    
-    - For EACH acceptance criterion, use `ask_user` with choices:
-      - "Yes, I can do this ✅"
-      - "No, something's wrong ❌"
-   
-   - **If "Yes"**: Mark criterion complete, proceed to next
-   - **If "No"**: 
-     - Invoke Child Brain immediately (friction detected)
-     - Child Brain analyzes what went wrong
-     - Fix applied, re-validate this criterion
-   
-   - **Example validation flow**:
-     ```
-     📋 Ability to see my emails inside the portal
-     
-     Criterion 1: I can see my inbox with sender, subject, and preview
-     → [Yes, I can do this] [No, something's wrong]
-     
-     Criterion 2: I can click an email to read the full content
-     → [Yes, I can do this] [No, something's wrong]
-     
-     Criterion 3: New emails appear without refreshing the page
-     → [Yes, I can do this] [No, something's wrong]
-     ```
-   
-   - **All criteria pass**: Mark outcome complete (✅)
-   - Update roadmap.md to check off the outcome
-   - Display: "✅ [Outcome name] — complete!"
-   - If issues: Jump to **Step 10A: Three-Layered Learning from Feedback**
-   - Update task document with final status
-   - Update roadmap checklist
-   
-   **⚠️ CRITICAL: After marking task complete, proceed through Steps 10B, 10C, and optionally 10D before returning to the Outcome Execution Menu (Layer 3).**
-   
-   **⛔ BLOCKING GATE - Steps 10B and 10C are MANDATORY:**
-   ```
-   Task marked complete by user
-       ↓
-   [STOP] Run Step 10B (Post-Task Reflection) ← Friction analysis via Child Brain
-       ↓
-   [STOP] Run Step 10C (Project Brain Checkpoint) ← Update living documentation
-       ↓
-   IF last task in phase → Run Step 10D (Phase Feedback Checkpoint)
-       ↓
-   IF more tasks in outcome → Return to Step 10E (Outcome Execution Menu - Layer 3)
-   IF outcome complete → Proceed to Step 11 (Roadmap Menu - Layer 2)
-   ```
-   
-   **DO NOT skip Steps 10B or 10C.** Even if the task had no issues:
-   1. Step 10B: Scan for friction, invoke Child Brain if found
-   2. Step 10C: Update project documentation silently
-   3. Step 10D: If phase complete, gather user feedback
-   4. After checkpoints → return to Layer 3 (or Layer 2 if outcome is done)
+   - Validates deliverables with data exposure checks, environment-aware presentation, outcome acceptance criteria, and mandatory post-task checkpoints.
+   - **Read `references/task-validation.md`** for the full validation procedure (data exposure gates, presentation strategy, outcome demo, acceptance criteria flow, and blocking gates for Steps 10B/10C)
+   - After marking task complete: MUST run Step 10B (Post-Task Reflection) → Step 10C (Project Brain Checkpoint) → optionally Step 10D (Phase Feedback) before returning to Layer 3
 
 ### 10A. **Friction Analysis via Child Brain**
    - When user provides negative/adjustment feedback in task validation:
@@ -3318,147 +1699,9 @@ Progress: [X/Y] criteria verified
      ```
 
 ### 11A. **MVP Complete & Beyond** (Phase Transition Flow)
-   - **When to run**: Automatically triggered when the last task in Phase 1 (MVP) is marked complete
-   - **Purpose**: Help user achieve their actual "done" goal and chart path forward
-   
-   **Step 11A.1: Detect MVP Completion**
-   - After any task is marked complete:
-     - Load `docs/roadmap.md`
-     - Check if all Phase 1 tasks are complete
-     - If not all complete: Skip this step, proceed normally
-     - If all Phase 1 complete: Proceed with MVP completion flow
-   
-   **Step 11A.2: Celebrate & Assess**
-   - Display:
-     ```
-     🎉 MVP Complete!
-     
-     You've completed all Phase 1 tasks for [Project Name].
-     
-     ✅ What's Done:
-     - [List key deliverables from Phase 1]
-     
-     📋 Original MVP Definition (from vision):
-     - [MVP criteria 1]
-     - [MVP criteria 2]
-     - [MVP criteria N]
-     
-     Now let's make sure you achieve your actual goal.
-     ```
-   
-   **Step 11A.3: Research "Done" Criteria for This Project Type**
-   - Use `web_search` to research (project-agnostic):
-     1. "[project type from roadmap] deployment best practices 2026"
-     2. "[project type] CI/CD pipeline setup"
-     3. "[project type] release checklist"
-     4. "[project type] production launch requirements"
-   
-   - Extract delivery patterns:
-     - **Deployment Options**: (Vercel, AWS, self-hosted, app stores, etc.)
-     - **CI/CD Requirements**: (automated testing, build pipelines, etc.)
-     - **Release Checklists**: (what needs to happen before "live")
-     - **Monitoring/Observability**: (logging, error tracking, analytics)
-   
-   **Step 11A.4: Present "Done" Criteria Options**
-   - Use `ask_user` with dynamically generated choices based on project type:
-     - Example for web app: "Deploy to production (Vercel/Netlify)"
-     - Example for web app: "Set up CI/CD pipeline (GitHub Actions)"
-     - Example for mobile app: "Prepare app store submission"
-     - Example for library: "Publish to npm/PyPI"
-     - "My MVP is already 'done' - I just wanted it working locally"
-     - "I need something else for 'done' (describe)"
-   
-   - Question: "What does 'done' mean for you? What makes this MVP complete?"
-   
-   - If user selects a delivery option:
-     - Check if relevant skill exists (e.g., "deployment-manager", "cicd-setup")
-     - If skill doesn't exist: Invoke skill-creator to create delivery skill
-     - Execute delivery using appropriate skill
-     - Validate deployment/release succeeded
-   
-   **Step 11A.5: Post-MVP Direction Menu**
-   - After "done" criteria achieved (or skipped), present direction options:
-   
-   - Display:
-     ```
-     🧠 MVP Delivered! What's Next?
-     
-     Your project is now at a decision point:
-     
-     Current State:
-     - Phase 1: ✅ Complete
-     - "Done" Criteria: [Achieved/Skipped]
-     - Phases Remaining: [Count]
-     - Tasks in Post-MVP Backlog: [Count]
-     ```
-   
-   - Use `ask_user` with choices:
-     - "Extend roadmap - plan Phase 2 tasks in detail"
-     - "Take a new direction - replan based on learnings"
-     - "Add new features to roadmap (describe what you want)"
-     - "Pause project - save progress and stop here"
-     - "Continue exactly as planned in roadmap"
-   
-   **Step 11A.6: Handle User's Direction Choice**
-   
-   **If "Extend roadmap":**
-   - Load Phase 2+ from roadmap (high-level items)
-   - For each Phase 2+ item:
-     - Break down into detailed tasks
-     - Create task documents (like Step 8)
-     - Identify patterns that need new skills
-   - If new patterns detected: Create skills using skill-creator
-   - Update roadmap with detailed tasks
-   - Return to Step 11 (Roadmap Menu)
-   
-   **If "Take a new direction":**
-   - Use `ask_user` (freeform): "What direction do you want to take the project?"
-   - Re-run vision discovery (Step 3) with context of what exists
-   - Generate new roadmap phases while preserving completed work
-   - Create any needed new skills using skill-creator
-   - Return to Step 11 (Roadmap Menu)
-   
-   **If "Add new features":**
-   - Use `ask_user` (freeform): "What features do you want to add?"
-   - Analyze feature description for skill patterns
-   - If patterns detected that need skills:
-     - Display: "I detect patterns that could benefit from new skills:"
-     - List detected patterns
-     - Invoke skill-creator for each pattern
-   - Add features as new tasks to appropriate phase
-   - Update roadmap
-   - Return to Step 11 (Roadmap Menu)
-   
-   **If "Pause project":**
-   - Save comprehensive session state
-   - Display summary of what was achieved
-   - Explain how to resume
-   - End session
-   
-   **If "Continue as planned":**
-   - Load next phase from roadmap
-   - Proceed to first task of next phase
-   - Return to Step 8 (Task Document Creation)
-   
-   **Step 11A.7: Skill Pattern Detection**
-   - Throughout this step, monitor user's freeform inputs for skill patterns
-   - When user describes new features/directions:
-     1. Analyze description for repetitive patterns that warrant skills
-     2. If patterns detected:
-        - Display: "🎯 I detected patterns that could use specialized skills:"
-        - List patterns with potential skill names
-        - Proceed to create skills automatically (Expert Autonomy)
-     3. For each pattern:
-        - Invoke skill-creator with context
-        - Validate skill works
-        - Add to session-state.json skillsCreated array
-   
-   **Key Principles**:
-   - **"Done" is user-defined**: Don't assume what "complete" means
-   - **Research-driven delivery**: Use web search to find best practices for this project type
-   - **Skill detection on new input**: Any time user describes new features, analyze for skill patterns
-   - **Project-agnostic**: Works for web apps, mobile apps, libraries, CLIs, games, etc.
-   - **Preserve learnings**: Replanning doesn't discard completed work or learned skills
+   - Triggered when last Phase 1 (MVP) task completes. Celebrates MVP, researches "done" criteria for the project type, and presents post-MVP direction options.
+   - **Read `references/mvp-complete.md`** for the full MVP completion and phase transition workflow (Steps 11A.1–11A.7)
+   - Covers: MVP detection, celebration, deployment/release research, "done" criteria options, post-MVP direction menu, and skill pattern detection on new input
 
 ### 12. **Freeform Classification** (Utility Step)