mother-brain 0.5.2 → 0.6.0

package/dist/cli.js

@@ -798,7 +798,7 @@ async function uninstall(options) {
 // src/cli.ts
 import { exec as exec3 } from "child_process";
 var program = new Command();
-var VERSION = "0.5.2";
+var VERSION = "0.5.1";
 program.name("mother-brain").description("AI-powered project management framework for GitHub Copilot CLI and Codex CLI").version(VERSION);
 program.command("init").description("Initialize Mother Brain in the current project").option("-f, --force", "Overwrite existing skills").action(init);
 program.command("update").description("Update Mother Brain skills to the latest version").action(update);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mother-brain",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "AI-powered project management framework for GitHub Copilot CLI",
   "type": "module",
   "main": "dist/index.js",

package/skills/mother-brain/SKILL.md

@@ -211,9 +211,12 @@ Mother Brain transforms high-level visions into executable reality by:
 - **Product-first thinking**: Focus on outcomes, not implementation details
 - **Vision clarity**: Always trace back to the WHY
 - **Adaptive planning**: Roadmaps are living documents, not contracts
+- **Outcome-Driven Roadmap (CORE PRINCIPLE)**: Roadmaps are organized by **Outcomes** (user abilities), not tasks. Each outcome is an "Ability to [do something]" that fulfills a user need. Tasks exist only as internal implementation details. Users validate **acceptance criteria** for outcomes, never technical tasks. This keeps validation meaningful ("Can I now do X?") rather than abstract ("Does this code look right?").
+- **User Needs as Foundation**: During Vision Discovery, capture explicit user needs as "Ability to..." statements. These become the outcomes in the roadmap. Every outcome traces back to which user need it fulfills.
+- **Acceptance Criteria Validation**: User signs off on acceptance criteria for each outcome, not on individual tasks. For each criterion, ask: "Can you do this now? Yes/No". If "No" → invoke Child Brain to analyze and fix.
 - **Best practice structure**: Organize projects using standard dev conventions
 - **Skill automation**: Create skills for repetitive tasks proactively
-- **User validation**: Always confirm work meets expectations before marking complete
+- **User validation**: Always confirm outcomes meet expectations via acceptance criteria before marking complete
 - **Self-improvement**: Learn from user feedback and update own SKILL.md to prevent future issues
 - **Transparency**: Document decisions, rationale, and changes
 - **Wizard pattern for all interactions**: Use `ask_user` tool with numbered, selectable choices (2-3 options) for ALL user decisions—never ask freeform yes/no questions in text
@@ -597,9 +600,75 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
 
 ### 2.2. **Existing Project Onboarding**
    - When user selects to onboard Mother Brain into an existing project:
-   - **Read `references/onboarding-workflow.md`** for the full onboarding workflow (Steps 2.2.1–2.2.5)
-   - Covers: deep repo analysis, vision extraction, retrospective roadmap, skill identification, confirmation
-   - After onboarding completes → proceed to normal workflow (Step 8+)
+   
+   **Step 2.2.1: Deep Repo Analysis**
+   - Scan ALL files in the directory (not just specific ones)
+   - Use `glob` and `view` to understand:
+     - **Project Type**: What kind of project is this? (web app, game, library, CLI, etc.)
+     - **Tech Stack**: Languages, frameworks, dependencies
+     - **Architecture**: Folder structure, patterns, modules
+     - **Features Built**: What functionality already exists?
+     - **Current State**: Is it working? Partially complete? Early stage?
+   
+   - Display findings:
+     ```
+     🔍 Project Analysis Complete
+     
+     What I Found:
+     - Type: [Project type detected]
+     - Tech Stack: [Languages, frameworks]
+     - Features Built: [List of detected features]
+     - Current State: [Assessment of completeness]
+     ```
+   
+   **Step 2.2.2: Vision Extraction (Clarifying Questions)**
+   - Ask user questions to fill gaps (like vision discovery, but informed by analysis):
+     - "What is the main goal of this project?"
+     - "Who is this for? Who will use it?"
+     - "What problem does this solve?"
+     - "What inspired this project?" (to trigger domain research)
+     - "What's the most important thing to get right?"
+     - "Where are you trying to get to next? What's your next milestone?"
+   
+   - Create `.mother-brain/docs/vision.md` with extracted vision
+   
+   **Step 2.2.3: Retrospective Roadmap**
+   - Build roadmap that reflects reality:
+     - **Phase 0 (Done)**: What's already built (based on repo analysis)
+     - **Phase 1 (Current)**: What's in progress or next immediate steps
+     - **Phase 2+**: Future milestones based on user's stated goals
+   
+   - Mark completed work as DONE in roadmap
+   - Identify current position in timeline
+   
+   - Create `.mother-brain/docs/roadmap.md`
+   
+   **Step 2.2.4: Skill Identification**
+   - Analyze patterns in existing code
+   - Identify repetitive work that warrants skills
+   - Invoke skill-creator for detected patterns
+   
+   **Step 2.2.5: Confirmation**
+   - Display:
+     ```
+     ✅ Mother Brain Onboarded!
+     
+     📋 Vision: Captured
+     📊 Roadmap: [X] tasks identified
+       - [Y] already complete
+       - [Z] remaining
+     🛠️ Skills: [N] identified for creation
+     
+     Ready to help you reach your next milestone!
+     ```
+   
+   - Use `ask_user` with choices:
+     - "Start next task"
+     - "Review the roadmap"
+     - "Review the vision"
+     - "Adjust something before continuing"
+   
+   - Proceed to normal workflow (Step 8+)
 
 ### 2A. **Improve Mother Brain Menu** (From Any Project)
    - When user selects "🧠 Improve Mother Brain" from the existing project menu:
@@ -684,10 +753,217 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
 
 ### 2A.1 **Send Improvement** (Automatic Multi-Issue Contribution)
    - When user selects "📤 Send my local improvements":
-   - **Read `references/improvement-pipeline.md`** for the full pipeline (Steps 2A.1.1–2A.1.5)
-   - Covers: gather sources (learning log, core file diffs, conversation context), deduplication via issues tracker, correlate learnings with file changes, generate individual GitHub issues, submit via gh CLI (with manual fallback), update tracker
-   - Target repository: `super-state/mother-brain`
-   - After submission → return to main menu (Step 2)
+   
+   **Purpose**: Automatically detect ALL local Mother Brain improvements, parse learning logs for each distinct improvement, and submit a separate GitHub issue for each one. Handles multiple improvements in one session.
+   
+   **AUTOMATIC WORKFLOW (No User Prompts)**:
+   
+   **Step 2A.1.1: Gather All Improvement Sources**
+   
+   - Collect from THREE sources:
+   
+   **Source 1: Learning Log Entries**
+   - Read `.mother-brain/project-brain.md` or `docs/learning-log.md`
+   - Parse for individual learning entries (marked by `## [Date]` or similar)
+   - Each entry = potential improvement
+   - Extract: date, trigger, learning, resolution
+   
+   **Source 2: Core File Changes**
+   - Get changes to Mother Brain core files:
+     ```powershell
+     git diff HEAD -- ".github/skills/mother-brain/SKILL.md"
+     git diff HEAD -- ".github/skills/child-brain/SKILL.md"  
+     git diff HEAD -- ".github/skills/skill-creator/SKILL.md"
+     ```
+   - If files are new/untracked: `git diff /dev/null -- [file]`
+   
+   **Source 3: Conversation Context**
+   - Scan conversation history for:
+     - Friction points discussed
+     - Problems reported
+     - Solutions implemented
+     - Pattern: "this isn't working" → "fixed by..."
+   
+   - **If no improvements found across all sources**:
+     - Display: "📭 No local Mother Brain improvements to send."
+     - Return to Step 2A (Improve Mother Brain Menu)
+   
+   **Step 2A.1.1A: Check Issues Tracker (Deduplication)**
+   
+   - Check if `.mother-brain/issues-tracker.md` exists
+   - **If exists**: 
+     - Read file and parse submitted issues list
+     - Extract issue numbers and titles already submitted
+     - Store in memory for comparison
+   - **If doesn't exist**: 
+     - Create empty tracker file with template:
+       ```markdown
+       # Mother Brain Issues Tracker
+       
+       ## Issues Submitted to GitHub (super-state/mother-brain)
+       
+       (No issues submitted yet)
+       ```
+   
+   **Step 2A.1.2: Correlate Learnings with File Changes**
+   
+   - For each learning entry found:
+     1. Identify which file(s) were modified for this learning
+     2. Extract the relevant diff sections (not the whole file diff)
+     3. Match learning description to code changes
+   
+   - Group by improvement type:
+     - **Behavioral improvements** → Mother Brain SKILL.md changes
+     - **Feedback handling** → Child Brain SKILL.md changes
+     - **Skill creation** → Skill Creator SKILL.md changes
+   
+   **Step 2A.1.3: Generate Individual Issues (with Deduplication)**
+   
+   - **Before generating issues**: Check each improvement against issues tracker
+     - Compare improvement title/description against already-submitted issues
+     - If match found: Skip this improvement
+     - If no match: Proceed to generate issue
+   
+   - Display deduplication results:
+     ```
+     🔍 Checking for duplicate submissions...
+     
+     Found [X] improvements:
+     - [Y] new (will be submitted)
+     - [Z] already submitted (skipped)
+     ```
+   
+   - **If all improvements already submitted**:
+     - Display: "✅ All improvements already submitted! No duplicates created."
+     - Return to Step 2A (Improve Mother Brain Menu)
+   
+   - For EACH NEW (not duplicate) improvement, create a separate issue:
+   
+   ```markdown
+   Title: [Improvement] [Brief title describing THIS specific improvement]
+   
+   ## Summary
+   [2-3 sentences explaining what this specific improvement does]
+   
+   ## Problem
+   [What friction was encountered that triggered this improvement]
+   
+   ## Solution
+   [How Mother Brain addressed the friction]
+   
+   ## Changes Made
+   **File**: [filename] (lines ~X-Y)
+   
+   <details>
+   <summary>View diff</summary>
+   
+   ```diff
+   [relevant diff for THIS improvement only - not entire file]
+   ```
+   </details>
+   
+   ## Benefits
+   [How this helps all Mother Brain users]
+   
+   ## Testing
+   [How the improvement was validated]
+   
+   ---
+   *Submitted via Mother Brain v[version]*
+   ```
+   
+   **Step 2A.1.4: Submit Issues via gh CLI**
+   
+   - **Pre-flight Check**: Verify gh CLI is available and authenticated
+     ```powershell
+     gh --version
+     gh auth status
+     ```
+   
+   - **If gh CLI available and authenticated**:
+     - For each generated improvement:
+       1. Create GitHub issue using gh CLI:
+          ```powershell
+          gh issue create --repo super-state/mother-brain --title "[title]" --body "[body]"
+          ```
+       2. Parse output to get issue number and URL
+       3. Collect issue numbers and URLs
+       4. Add small delay between submissions (avoid rate limiting): `Start-Sleep -Seconds 2`
+     
+     - Target repository: `super-state/mother-brain`
+       - Detected from: git remote (if configured)
+       - Fallback: hardcoded default
+   
+   - **If gh CLI not installed or not authenticated**:
+     - **Fallback to manual submission**:
+       1. Save each issue to `.mother-brain/github-issues/issue-[N].md`
+       2. Display instructions:
+          ```
+          ⚠️ gh CLI not available
+          
+          To auto-submit improvements, install gh CLI:
+          https://cli.github.com
+          
+          Then authenticate: gh auth login
+          
+          📁 Issue content saved to:
+          - .mother-brain/github-issues/issue-1.md
+          - .mother-brain/github-issues/issue-2.md
+          
+          You can submit these manually at:
+          https://github.com/super-state/mother-brain/issues/new
+          ```
+       3. Return to main menu with saved files
+   
+   **Step 2A.1.5: Update Issues Tracker & Display Results**
+   
+   - **Update `.mother-brain/issues-tracker.md`**:
+     - Add new section for this session (if new issues were created):
+       ```markdown
+       ### Session: [Date] - [Context]
+       
+       | Issue # | Title | Status | URL |
+       |---------|-------|--------|-----|
+       | #[N] | [Title] | ✅ Submitted | [URL] |
+       ```
+     - Commit changes to git:
+       ```powershell
+       git add .mother-brain/issues-tracker.md
+       git commit -m "docs: track submitted issues from [session context]"
+       ```
+   
+   - Display summary of ALL submitted issues:
+     ```
+     ✅ Improvements Submitted!
+     
+     Created [N] new issues:
+     
+     📝 #[1]: [title1]
+        [issue URL]
+     
+     📝 #[2]: [title2]
+        [issue URL]
+     
+     📝 #[3]: [title3]
+        [issue URL]
+     
+     [If any were skipped] Skipped [Z] duplicates already submitted
+     
+     Your contributions are now visible to maintainers.
+     Tracker updated: .mother-brain/issues-tracker.md
+     ```
+   
+   - Use `ask_user` with choices:
+     - "Keep local changes (for further work)"
+     - "Revert Mother Brain files (clean slate)"
+   
+   - **If revert selected**:
+     ```powershell
+     git checkout HEAD -- ".github/skills/mother-brain/" ".github/skills/child-brain/" ".github/skills/skill-creator/" "cli/"
+     ```
+     - Display: "✨ Local Mother Brain files reverted to clean slate."
+   
+   - 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)
@@ -1048,10 +1324,92 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
 
 ### 2D. **Release Mother Brain** (Framework Versioning)
    - When user selects "Release Mother Brain" from menu or after eject:
-   - **Read `references/release-checklist.md`** for the full release workflow (Steps 2D.1–2D.7)
-   - **⚡ ONE-CLICK RELEASE FLOW**: Verify changes → auto-determine version → update all version references → sync skills → build CLI → git commit/tag/push
-   - **⛔ BLOCKING RULE**: Do NOT return to menu until ALL checklist items are completed
-   - **NEVER push to personal fork** — only super-state has npm publish token
+   
+   **Purpose**: One-click release - commit, version bump, push, tag, and publish.
+   
+   **Prerequisite**: Must be in the mother-brain framework folder (not a project folder)
+   
+   **⚡ MANDATORY RELEASE CHECKLIST (All items MUST be completed)**
+   
+   Every release MUST update ALL of the following:
+   ```
+   [ ] cli/package.json - version field
+   [ ] cli/src/cli.ts - version constant (if exists)
+   [ ] README.md - version badge AND version text
+   [ ] Git commit with changes
+   [ ] Git tag (v0.0.X)
+   [ ] Push to remote (main + tags)
+   [ ] GitHub Release (created automatically by workflow)
+   [ ] npm publish (triggered by tag push via workflow)
+   ```
+   
+   **⛔ BLOCKING RULE**: Do NOT return to menu until ALL items above are completed.
+   
+   **⚡ ONE-CLICK RELEASE FLOW (No prompts, no menus)**
+   
+   When user selects "Release Mother Brain", execute ALL of the following automatically:
+   
+   **Step 2D.1: Verify & Analyze**
+   - Check current folder is mother-brain framework folder
+   - If in a project folder: Display error and offer to return to framework
+   - Run `git status` to verify there are changes to release
+   - If no changes: Display "Nothing to release" and return to menu
+   
+   **Step 2D.2: Auto-Determine Version**
+   - Read current version from `cli/package.json`
+   - Scan learning-log.md entries since last release tag (if exists)
+   - **Auto-determine version bump**:
+     - If any entry contains "breaking" or "major" → **major** bump (X.0.0)
+     - If any entry contains "feature", "new", "add" → **minor** bump (0.X.0)
+     - Otherwise → **patch** bump (0.0.X)
+   - Do NOT ask user - auto-decide based on content
+   
+   **Step 2D.3: Update ALL Version References (MANDATORY)**
+   - Update `cli/package.json`: `"version": "[new-version]"`
+   - Update `cli/src/cli.ts`: version constant (search for old version, replace with new)
+   - Update `README.md`:
+     - Find `version-X.X.X-blue` badge and replace with new version
+     - Find `**Version**: X.X.X` text and replace with new version
+   - **Verify all files updated before proceeding**
+   
+   **Step 2D.4: Sync Skills to CLI and Agents**
+   - Copy `.github/skills/*` to `cli/skills/` (overwrite) — for npm package
+   - Verify `.agents/skills/` symlinks point to `.github/skills/` — for Codex CLI in framework repo
+   
+   **Step 2D.5: Build CLI**
+   - Run `cd cli && npm run build`
+   - If build fails: STOP and display error
+   
+   **Step 2D.6: Execute Git Operations**
+   - Stage all changes: `git add -A`
+   - Commit: `git commit -m "[type]: [description] (v[version])"`
+   - Create tag: `git tag v[version]`
+   - **Push to origin (super-state) ONLY**: `git push origin main --tags`
+   - **NEVER push to personal fork** - only super-state has npm publish token
+   
+   **Step 2D.7: Confirmation**
+   - Wait for workflow to complete (or check status)
+   - Display:
+     ```
+     ✅ Release v[version] Published!
+     
+     ✅ cli/package.json updated
+     ✅ cli/src/cli.ts updated
+     ✅ README.md updated
+     ✅ Git tag created and pushed
+     ✅ GitHub Release created (via workflow)
+     ✅ npm publish triggered (via workflow)
+     
+     Tag: v[version]
+     Release: https://github.com/superdenby/MotherBrain/releases/tag/v[version]
+     ```
+   
+   - Use `ask_user` with choices:
+     - "Open release on GitHub"
+     - "Return to main menu"
+     - "Start new project"
+   
+   - Handle selection appropriately
 
 ### 2E. **Brainstorm Mode** (Thinking Partner)
    - When user selects "Just talk (brainstorm mode)":
@@ -1700,10 +2058,11 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - **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**: What proves the concept works?
+   - **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?"
@@ -1876,8 +2235,43 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - **Proceed to Step 4** (Vision Document Creation)
 
 ### 4. **Vision Document Creation**
-   - **Read `references/doc-templates.md`** and use the Vision Document Template
-   - Create `docs/vision.md` using the loaded template, filling in content from vision discovery
+   - Create `docs/vision.md` with structured content:
+     ```markdown
+     # [Project Name] - Vision
+     
+     ## The Problem
+     [User's pain point/opportunity]
+     
+     ## The Vision
+     [3-12 month desired future state]
+     
+     ## Target Users
+     [Who benefits and how]
+     
+     ## Why This Matters
+     [The deeper purpose]
+     
+     ## User Needs
+     > These are the core abilities users need. Each becomes an outcome in the roadmap.
+     
+     | Need | Description | MVP? |
+     |------|-------------|------|
+     | Ability to [do X] | [Why this matters] | ✅/❌ |
+     | Ability to [do Y] | [Why this matters] | ✅/❌ |
+     | Ability to [do Z] | [Why this matters] | ✅/❌ |
+     
+     ## Success Looks Like
+     [Measurable outcomes - tied to user needs being fulfilled]
+     
+     ## Constraints
+     [Budget, skills, tech preferences. NOT timeline - AI has no time constraints.]
+     
+     ## MVP Definition
+     [Which user needs must be fulfilled for minimum viable success]
+     
+     ## Strategic Themes
+     [3-5 key focus areas derived from vision]
+     ```
    
    - Create `README.md` with project overview
    - Display vision summary to user
@@ -2345,17 +2739,19 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    
    **Step 7.0: Load Value Framework**
    - Read `.mother-brain/docs/value-framework.md`
-   - Use the priority dimensions and weights to order tasks
-   - Every task in the roadmap must be scored (even roughly) against the framework
+   - 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 Problem Solution)**
-   - Phase 1 scope = shortest path to solve core problem from vision
+   **Step 7.1: Define Phase 1 = MVP (Core User Needs)**
+   - Phase 1 scope = shortest path to fulfill core user needs from vision
    - Use:
-     - MVP definition from Step 4 (vision document)
+     - 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 what's essential for Phase 1 vs what can wait
-   - Break Phase 1 into tasks that deliver only MVP
+   - 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
@@ -2363,12 +2759,151 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - 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` (Research-Driven Structure)**:
-   - **Read `references/doc-templates.md`** and use the Roadmap Template
-   - Create `docs/roadmap.md` using the loaded template
-   - Fill in from research findings (Steps 5, 5A, 6A) and Value Framework (Step 4A)
-   - Order tasks by Value Framework score
-   - Include "Why this order" explanation for each phase
+   **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]
+     
+     **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]
+     
+     **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]
+     
+     **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
@@ -2442,25 +2977,150 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    - Emphasize learning and iteration mindset
 
 ### 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)
-   - **When to run**: IMMEDIATELY after Step 7.5 menu response, BEFORE proceeding to any next action
-   - **Purpose**: Detect and learn from issues during setup flow (Steps 3-7)
-   - Two-layer approach: Layer 1 fixes current project, Layer 2 extracts meta-lessons for all future projects
-   - If 0 issues → skip to user's selected action; if 1+ issues → heal, then proceed
+   - **Purpose**: This is the REFLECTION step mentioned in RULE 8. It MUST complete before declaring "setup complete".
+   - **When to run**: IMMEDIATELY after Step 7.5 displays menu and receives user response, BEFORE proceeding to any next action
+   - **Purpose**: Detect and learn from any issues that occurred during the setup flow (Steps 3-7)
+   
+   **Step 7.6.1: Scan Conversation for Setup Issues**
+   - Review the conversation history from Steps 3-7 for:
+     - **Build/Tool Failures**: Commands that failed, tools that errored
+     - **Skill Creation Failures**: Skills that failed to create or validate
+     - **Research Failures**: Web searches that returned no results
+     - **File Creation Errors**: Documents that failed to create
+     - **Retry Attempts**: Any step that had to be re-run
+     - **Partial Completions**: Steps that succeeded but with warnings
+   
+   - If 0 issues detected: Skip to Step 8 (Task Document Creation) when user selects "Start Task 001"
+   - If 1+ issues detected: Proceed with healing
+   
+   **Step 7.6.2: Layer 1 - Fix Current Project Setup**
+   - For each issue found:
+     - Identify what failed
+     - Determine root cause
+     - Apply fix to current project:
+       - Re-run failed command/tool
+       - Re-create failed file
+       - Re-validate failed skill
+       - Fix any incomplete setup
+   - Continue until all issues resolved
+   
+   **Step 7.6.3: Layer 2 - Extract Meta-Lessons for Mother Brain**
+   - For each issue, ask: "What could Mother Brain do differently to prevent this in ALL future projects?"
+   - Categories to consider:
+     - **Missing Validation**: Should a validation step exist where it doesn't?
+     - **Error Handling Gap**: Should Mother Brain catch and handle this error type?
+     - **Workflow Ordering**: Should steps be reordered to prevent this?
+     - **Missing Retry Logic**: Should automatic retry be added?
+     - **Missing Pre-Checks**: Should a prerequisite check exist?
+   
+   - Extract project-agnostic principle:
+     - ❌ Bad: "Coffee project skill creation failed"
+     - ✅ Good: "Skill creation should validate tool permissions before creating files"
+   
+   **Step 7.6.4: Auto-Apply Mother Brain Updates**
+   - For each meta-lesson extracted:
+     - Identify which step/section of SKILL.md to update
+     - Apply update using edit tool
+     - Display what was changed (transparency, not approval)
+   
+   - Log in `docs/learning-log.md`:
+     ```markdown
+     ## [Date] - Setup Self-Healing: [Project Name]
+     **Issues Found**: [Count]
+     **Layer 1 Fixes Applied**:
+     - [What was fixed in this project's setup]
+     **Layer 2 Meta-Lessons Extracted**:
+     - [Project-agnostic principle 1]
+     - [Project-agnostic principle 2]
+     **Mother Brain Updates Applied**:
+     - [Which step/section was updated]
+     - [What preventive measure was added]
+     **Impact**: Prevents [issue type] in all future projects
+     ```
+   
+   **Step 7.6.5: Display Summary**
+   - If issues were found, display:
+     ```
+     🔧 Setup Validation & Reflection Complete
+     
+     Found [X] issue(s) during setup - all resolved:
+     
+     ✅ Project Fixes:
+     - [What was fixed in this project]
+     
+     ✅ Mother Brain Improvements:
+     - [Meta-lesson applied for future projects]
+     
+     ✅ Reflection complete - setup is now truly complete!
+     ```
+   
+   - If no issues found, display:
+     ```
+     ✅ Reflection Complete
+     
+     No issues detected during setup. 
+     All steps executed successfully.
+     
+     Setup is now complete!
+     ```
+   
    - **ONLY AFTER this step completes can you proceed to user's selected action from Step 7.5 menu**
+   - This checkpoint ensures learning happens every session, not just when errors occur
+   
+   - Continue to user's selected action from Step 7.5 menu
+   
+   **Key Principle**: Every setup run improves Mother Brain for all future projects. Issues are not just fixed—they're learned from.
 
 ### 8. **Task Document Creation**
    - Create `docs/tasks/` directory
-   - **Read `references/doc-templates.md`** and use the Task Document Template
-   - For first task in Phase 1, create `docs/tasks/001-[task-name].md` using the loaded template
+   - Tasks are internal implementation details — users validate **outcomes**, not tasks
+   - For each task in Phase 1, create `docs/tasks/001-[task-name].md`:
+     ```markdown
+     # Task 001: [Task Name]
+     
+     **Status**: 🟡 In Progress  
+     **Phase**: Phase 1 - MVP  
+     **Parent Outcome**: 📋 Ability to [outcome name this task contributes to]  
+     **Assigned**: [Date]  
+     
+     ## Objective
+     [What this task achieves — how it contributes to the parent outcome]
+     
+     ## Technical Details
+     - **Type**: [Logic | UI | Animation | Integration | Testing]
+     - **Focus**: [What this task implements specifically]
+     - **NOT in scope**: [What related features are in other tasks]
+     
+     ## Implementation Notes
+     [Technical approach — user does NOT see this during validation]
+     
+     ## Dependencies
+     - [What must exist before this]
+     
+     ## Skills to Use
+     - [Relevant skill name and purpose]
+     
+     ## Deliverables
+     - [Specific files/outputs]
+     
+     ## Notes & Decisions
+     [Log decisions made during execution]
+     
+     ## Internal Verification (NOT user validation)
+     [ ] Built successfully
+     [ ] Tests pass
+     [ ] Deliverables created
+     
+     ---
+     
+     **Note**: User validates the parent outcome's acceptance criteria, 
+     not this task directly. This task is complete when deliverables 
+     are ready and internal verification passes.
+     ```
    
-   - Display task to user
-   - Use `ask_user` with choices:
-     - "Yes, start this task now"
-     - "Skip to next task"
-     - "Let me review the roadmap first"
-     - "🚨 Report Issue (something's not working)"
-   - Proceed based on selection
+   - **DO NOT ask user to validate individual tasks**
+   - Tasks complete silently when internal verification passes
+   - User validates only when ALL tasks under an outcome are complete (Step 10)
 
 ### 9. **Task Execution**
 
@@ -2825,48 +3485,50 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
      - ✅ **Verification**: Test against success criteria
    
    - **Roadmap Cross-Check** (CRITICAL - prevents out-of-order implementation):
-     1. Load current task document from `docs/tasks/[number]-[name].md`
-     2. Load roadmap from `docs/roadmap.md`
-     3. Identify:
-        - What THIS task's deliverables are (from task doc "Deliverables" section)
-        - What FUTURE tasks will deliver (scan roadmap for uncompleted tasks)
-     4. **Only validate what THIS task was supposed to deliver**
-     5. If user mentions missing features during validation:
-        - Check if feature is in a future task
-        - Explain: "That's planned for Task [X] - [Name]"
-        - Offer choices: "Continue with roadmap as planned" or "Adjust roadmap to include this now"
-        - If user chooses continue: Mark current task complete, proceed to next
-        - If user chooses adjust: Update roadmap, then implement requested feature
-   
-   - Ask user to review:
-     ```
-     ✅ Task [Number]: [Task Name] - Ready for Review
-     
-     What was created in THIS task:
-     - [List deliverables with paths - only from this task]
-     
-     Success criteria for THIS task:
-     - [✓] [Criterion met from task doc]
-     - [✓] [Criterion met from task doc]
-     
-     Coming in future tasks (not expected yet):
-     - Task [X]: [Future feature user might expect]
-     - Task [Y]: [Future feature user might expect]
-     
-     Questions about THIS task specifically:
-     1. Does this task's output look how you expected?
-     2. Does THIS task's functionality work properly?
-     3. Anything you'd like changed about THIS task?
-     ```
-   
-   - Use `ask_user` to get feedback with choices:
-     - "Looks perfect, mark as complete"
-     - "Works but needs adjustment"
-     - "Doesn't meet expectations, needs rework"
-     - "🚨 Report Issue (something's not working)"
-   - Provide freeform for detailed feedback
+     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?
+     ```
+   
+   - 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
    
-   - If user confirms: Mark task complete (🟢 Complete)
+   - **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
@@ -3387,15 +4049,86 @@ When heal fixes an issue:
 
 ## Example Session Flow
 
-**Read `examples/session-flow.md` for full new project and returning project examples.**
+**New Project:**
+```
+User: I want to build a music marketing SaaS platform
+
+Mother Brain:
+🧠 Welcome to Mother Brain!
+
+[Runs vision discovery wizard - captures user needs]
+
+User Needs Identified:
+- Ability to connect Spotify and see my artist analytics
+- Ability to schedule social media posts for releases
+- Ability to build email lists and send campaigns
+- Ability to track which promotions drive streams
+
+Creates:
+- docs/vision.md (with User Needs table)
+- docs/roadmap.md (outcomes organized by phase)
+- README.md
+
+Skills created:
+- spotify-api-integrator
+- social-media-scheduler
+- email-campaign-manager
+
+Phase 1 (MVP) Outcomes:
+📋 Ability to connect Spotify and see my artist analytics
+📋 Ability to track which promotions drive streams
+
+[Mother Brain executes tasks internally - user doesn't validate each task]
+
+When outcome tasks complete:
+
+Mother Brain: 
+📋 Outcome Complete: Ability to connect Spotify and see my artist analytics
+
+Please verify each criterion:
+
+1. I can connect my Spotify artist account
+   → [Yes, I can do this] [No, something's wrong]
+
+2. I can see my streaming numbers and top tracks
+   → [Yes, I can do this] [No, something's wrong]
+
+3. Data updates automatically each day
+   → [Yes, I can do this] [No, something's wrong]
+
+User: "Yes" to all
+
+Mother Brain: ✅ Outcome complete! Moving to next outcome...
+```
+
+**Returning to Project:**
+```
+User: /mother-brain
+
+Mother Brain:
+🧠 Welcome back to MusicMarketingSaaS!
+
+Current Status:
+Phase: 1 - MVP (2 of 4 outcomes complete)
+Current Outcome: 📋 Ability to track which promotions drive streams
+Progress: 50% of MVP outcomes validated
+Skills: 3 available
+
+What would you like to do?
+1. Continue where I left off
+2. Review roadmap
+3. 💡 I have a new idea
+...
+```
 
 ## Notes
 
-- **Not a replacement for the user**: Mother Brain guides, but user makes final decisions
-- **Living documents**: Vision and roadmap can be updated as project evolves
-- **Flexible pacing**: Work on tasks in any order if dependencies allow
-- **Session state**: All progress saved in docs/ folder
-- **Best practices**: Uses industry-standard project structure
+- **Outcome-driven**: Users validate abilities, not technical tasks
+- **User Needs as foundation**: Every outcome traces to a captured user need
+- **Living documents**: Vision and roadmap evolve with user feedback
+- **Acceptance criteria validation**: Each criterion gets explicit Yes/No
+- **Child Brain on "No"**: Any failed criterion triggers learning
+- **Session state**: All progress saved in .mother-brain/ folder
 - **Skill ecosystem**: Builds project-specific skill library over time
 
 ## Resources

package/skills/mother-brain/references/improvement-pipeline.md

@@ -1,114 +0,0 @@
-# Improvement Submission Pipeline
-
-Automatically detect ALL local Mother Brain improvements, parse learning logs for each distinct improvement, and submit a separate GitHub issue for each one.
-
-## Step 2A.1.1: Gather All Improvement Sources
-
-Collect from THREE sources:
-
-### Source 1: Learning Log Entries
-- Read `.mother-brain/project-brain.md` or `docs/learning-log.md`
-- Parse for individual learning entries (marked by `## [Date]` or similar)
-- Each entry = potential improvement
-- Extract: date, trigger, learning, resolution
-
-### Source 2: Core File Changes
-- Get changes to Mother Brain core files:
-  ```powershell
-  git diff HEAD -- ".github/skills/mother-brain/SKILL.md"
-  git diff HEAD -- ".github/skills/child-brain/SKILL.md"  
-  git diff HEAD -- ".github/skills/skill-creator/SKILL.md"
-  ```
-- If files are new/untracked: `git diff /dev/null -- [file]`
-
-### Source 3: Conversation Context
-- Scan conversation history for:
-  - Friction points discussed
-  - Problems reported
-  - Solutions implemented
-  - Pattern: "this isn't working" → "fixed by..."
-
-- **If no improvements found across all sources**:
-  - Display: "📭 No local Mother Brain improvements to send."
-  - Return to Step 2A (Improve Mother Brain Menu)
-
-## Step 2A.1.1A: Check Issues Tracker (Deduplication)
-
-- Check if `.mother-brain/issues-tracker.md` exists
-- **If exists**: Read and parse submitted issues list for comparison
-- **If doesn't exist**: Create empty tracker file
-
-## Step 2A.1.2: Correlate Learnings with File Changes
-
-- For each learning entry found:
-  1. Identify which file(s) were modified for this learning
-  2. Extract the relevant diff sections (not the whole file diff)
-  3. Match learning description to code changes
-
-- Group by improvement type:
-  - **Behavioral improvements** → Mother Brain SKILL.md changes
-  - **Feedback handling** → Child Brain SKILL.md changes
-  - **Skill creation** → Skill Creator SKILL.md changes
-
-## Step 2A.1.3: Generate Individual Issues (with Deduplication)
-
-- Check each improvement against issues tracker — skip duplicates
-- For EACH NEW improvement, create a separate issue using this template:
-
-```markdown
-Title: [Improvement] [Brief title describing THIS specific improvement]
-
-## Summary
-[2-3 sentences explaining what this specific improvement does]
-
-## Problem
-[What friction was encountered that triggered this improvement]
-
-## Solution
-[How Mother Brain addressed the friction]
-
-## Changes Made
-**File**: [filename] (lines ~X-Y)
-
-<details>
-<summary>View diff</summary>
-
-\```diff
-[relevant diff for THIS improvement only - not entire file]
-\```
-</details>
-
-## Benefits
-[How this helps all Mother Brain users]
-
-## Testing
-[How the improvement was validated]
-
----
-*Submitted via Mother Brain v[version]*
-```
-
-## Step 2A.1.4: Submit Issues via gh CLI
-
-- **Pre-flight Check**: `gh --version && gh auth status`
-
-- **If gh CLI available and authenticated**:
-  - For each improvement: `gh issue create --repo super-state/mother-brain --title "[title]" --body "[body]"`
-  - Parse output for issue number and URL
-  - Add `Start-Sleep -Seconds 2` between submissions (rate limiting)
-  - Target repository: `super-state/mother-brain`
-
-- **If gh CLI not available**:
-  - Save each issue to `.mother-brain/github-issues/issue-[N].md`
-  - Display instructions for manual submission at https://github.com/super-state/mother-brain/issues/new
-
-## Step 2A.1.5: Update Issues Tracker & Display Results
-
-- Update `.mother-brain/issues-tracker.md` with new session entries
-- Commit tracker: `git add .mother-brain/issues-tracker.md && git commit -m "docs: track submitted issues"`
-- Display summary of all submitted issues with numbers and URLs
-- Use `ask_user` with choices:
-  - "Keep local changes (for further work)"
-  - "Revert Mother Brain files (clean slate)"
-- If revert: `git checkout HEAD -- ".github/skills/mother-brain/" ".github/skills/child-brain/" ".github/skills/skill-creator/" "cli/"`
-- Return to main menu (Step 2)

package/skills/mother-brain/references/onboarding-workflow.md

@@ -1,71 +0,0 @@
-# Existing Project Onboarding Workflow
-
-When user selects to onboard Mother Brain into an existing project, follow these steps:
-
-## Step 2.2.1: Deep Repo Analysis
-- Scan ALL files in the directory (not just specific ones)
-- Use `glob` and `view` to understand:
-  - **Project Type**: What kind of project is this? (web app, game, library, CLI, etc.)
-  - **Tech Stack**: Languages, frameworks, dependencies
-  - **Architecture**: Folder structure, patterns, modules
-  - **Features Built**: What functionality already exists?
-  - **Current State**: Is it working? Partially complete? Early stage?
-
-- Display findings:
-  ```
-  🔍 Project Analysis Complete
-  
-  What I Found:
-  - Type: [Project type detected]
-  - Tech Stack: [Languages, frameworks]
-  - Features Built: [List of detected features]
-  - Current State: [Assessment of completeness]
-  ```
-
-## Step 2.2.2: Vision Extraction (Clarifying Questions)
-- Ask user questions to fill gaps (like vision discovery, but informed by analysis):
-  - "What is the main goal of this project?"
-  - "Who is this for? Who will use it?"
-  - "What problem does this solve?"
-  - "What inspired this project?" (to trigger domain research)
-  - "What's the most important thing to get right?"
-  - "Where are you trying to get to next? What's your next milestone?"
-
-- Create `.mother-brain/docs/vision.md` with extracted vision
-
-## Step 2.2.3: Retrospective Roadmap
-- Build roadmap that reflects reality:
-  - **Phase 0 (Done)**: What's already built (based on repo analysis)
-  - **Phase 1 (Current)**: What's in progress or next immediate steps
-  - **Phase 2+**: Future milestones based on user's stated goals
-
-- Mark completed work as DONE in roadmap
-- Identify current position in timeline
-- Create `.mother-brain/docs/roadmap.md`
-
-## Step 2.2.4: Skill Identification
-- Analyze patterns in existing code
-- Identify repetitive work that warrants skills
-- Invoke skill-creator for detected patterns
-
-## Step 2.2.5: Confirmation
-- Display:
-  ```
-  ✅ Mother Brain Onboarded!
-  
-  📋 Vision: Captured
-  📊 Roadmap: [X] tasks identified
-    - [Y] already complete
-    - [Z] remaining
-  🛠️ Skills: [N] identified for creation
-  
-  Ready to help you reach your next milestone!
-  ```
-
-- Use `ask_user` with choices:
-  - "Start next task"
-  - "Review the roadmap"
-  - "Review the vision"
-  - "Adjust something before continuing"
-
-- Proceed to normal workflow (Step 8+)

package/skills/mother-brain/references/release-checklist.md

@@ -1,65 +0,0 @@
-# Release Checklist — Mother Brain Framework
-
-One-click release: commit, version bump, push, tag, and publish.
-
-**Prerequisite**: Must be in the mother-brain framework folder (not a project folder)
-
-## Mandatory Checklist (ALL items MUST be completed)
-
-```
-[ ] cli/package.json - version field
-[ ] cli/src/cli.ts - version constant (if exists)
-[ ] README.md - version badge AND version text
-[ ] Git commit with changes
-[ ] Git tag (v0.0.X)
-[ ] Push to remote (main + tags)
-[ ] GitHub Release (created automatically by workflow)
-[ ] npm publish (triggered by tag push via workflow)
-```
-
-**⛔ BLOCKING RULE**: Do NOT return to menu until ALL items above are completed.
-
-## Step 2D.1: Verify & Analyze
-- Check current folder is mother-brain framework folder
-- If in a project folder: Display error and offer to return to framework
-- Run `git status` to verify there are changes to release
-- If no changes: Display "Nothing to release" and return to menu
-
-## Step 2D.2: Auto-Determine Version
-- Read current version from `cli/package.json`
-- Scan learning-log.md entries since last release tag (if exists)
-- **Auto-determine version bump**:
-  - If any entry contains "breaking" or "major" → **major** bump (X.0.0)
-  - If any entry contains "feature", "new", "add" → **minor** bump (0.X.0)
-  - Otherwise → **patch** bump (0.0.X)
-- Do NOT ask user - auto-decide based on content
-
-## Step 2D.3: Update ALL Version References (MANDATORY)
-- Update `cli/package.json`: `"version": "[new-version]"`
-- Update `cli/src/cli.ts`: version constant (search for old version, replace with new)
-- Update `README.md`:
-  - Find `version-X.X.X-blue` badge and replace with new version
-  - Find `**Version**: X.X.X` text and replace with new version
-- **Verify all files updated before proceeding**
-
-## Step 2D.4: Sync Skills to CLI and Agents
-- Copy `.github/skills/*` to `cli/skills/` (overwrite) — for npm package
-- Verify `.agents/skills/` symlinks point to `.github/skills/` — for Codex CLI in framework repo
-
-## Step 2D.5: Build CLI
-- Run `cd cli && npm run build`
-- If build fails: STOP and display error
-
-## Step 2D.6: Execute Git Operations
-- Stage all changes: `git add -A`
-- Commit: `git commit -m "[type]: [description] (v[version])"`
-- Create tag: `git tag v[version]`
-- **Push to origin (super-state) ONLY**: `git push origin main --tags`
-- **NEVER push to personal fork** - only super-state has npm publish token
-
-## Step 2D.7: Confirmation
-- Display release summary with all checkmarks
-- Use `ask_user` with choices:
-  - "Open release on GitHub"
-  - "Return to main menu"
-  - "Start new project"

package/skills/mother-brain/references/setup-validation.md

@@ -1,70 +0,0 @@
-# Setup Validation & Self-Healing Protocol
-
-**MANDATORY REFLECTION — Blocks setup completion.**
-
-This is the REFLECTION step mentioned in RULE 8. It MUST complete before declaring "setup complete".
-
-**When to run**: IMMEDIATELY after Step 7.5 menu response, BEFORE proceeding to any next action.
-**Purpose**: Detect and learn from any issues during the setup flow (Steps 3-7).
-
-## Step 7.6.1: Scan Conversation for Setup Issues
-- Review conversation history from Steps 3-7 for:
-  - **Build/Tool Failures**: Commands that failed, tools that errored
-  - **Skill Creation Failures**: Skills that failed to create or validate
-  - **Research Failures**: Web searches that returned no results
-  - **File Creation Errors**: Documents that failed to create
-  - **Retry Attempts**: Any step that had to be re-run
-  - **Partial Completions**: Steps that succeeded but with warnings
-
-- If 0 issues detected: Skip to Step 8 when user selects "Start Task 001"
-- If 1+ issues detected: Proceed with healing
-
-## Step 7.6.2: Layer 1 — Fix Current Project Setup
-- For each issue found:
-  - Identify what failed
-  - Determine root cause
-  - Apply fix: re-run failed command, re-create failed file, re-validate failed skill
-  - Continue until all issues resolved
-
-## Step 7.6.3: Layer 2 — Extract Meta-Lessons for Mother Brain
-- For each issue, ask: "What could Mother Brain do differently to prevent this in ALL future projects?"
-- Categories:
-  - **Missing Validation**: Should a validation step exist where it doesn't?
-  - **Error Handling Gap**: Should Mother Brain catch and handle this error type?
-  - **Workflow Ordering**: Should steps be reordered to prevent this?
-  - **Missing Retry Logic**: Should automatic retry be added?
-  - **Missing Pre-Checks**: Should a prerequisite check exist?
-
-- Extract project-agnostic principle:
-  - ❌ Bad: "Coffee project skill creation failed"
-  - ✅ Good: "Skill creation should validate tool permissions before creating files"
-
-## Step 7.6.4: Auto-Apply Mother Brain Updates
-- For each meta-lesson: identify SKILL.md section to update, apply edit, display changes
-- Log in `docs/learning-log.md`:
-  ```markdown
-  ## [Date] - Setup Self-Healing: [Project Name]
-  **Issues Found**: [Count]
-  **Layer 1 Fixes Applied**: [What was fixed]
-  **Layer 2 Meta-Lessons Extracted**: [Principles]
-  **Mother Brain Updates Applied**: [Steps/sections updated]
-  **Impact**: Prevents [issue type] in all future projects
-  ```
-
-## Step 7.6.5: Display Summary
-- If issues found:
-  ```
-  🔧 Setup Validation & Reflection Complete
-  Found [X] issue(s) — all resolved.
-  ✅ Project Fixes: [summary]
-  ✅ Mother Brain Improvements: [meta-lessons]
-  ```
-
-- If no issues:
-  ```
-  ✅ Reflection Complete — No issues detected. Setup is complete!
-  ```
-
-- **ONLY AFTER this step completes** → proceed to user's selected action from Step 7.5 menu
-
-**Key Principle**: Every setup run improves Mother Brain for all future projects. Issues are not just fixed—they're learned from.