mother-brain 0.5.1 → 0.5.2

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.1";
+var VERSION = "0.5.2";
 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.1",
+  "version": "0.5.2",
   "description": "AI-powered project management framework for GitHub Copilot CLI",
   "type": "module",
   "main": "dist/index.js",

package/skills/mother-brain/SKILL.md

@@ -597,75 +597,9 @@ 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:
-   
-   **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+)
+   - **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+)
 
 ### 2A. **Improve Mother Brain Menu** (From Any Project)
    - When user selects "🧠 Improve Mother Brain" from the existing project menu:
@@ -750,217 +684,10 @@ 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":
-   
-   **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)
+   - **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)
 
 ### 2A.2 **Review Community Improvements** (Maintainer Workflow)
    - **Access**: Only shown when meta-mode is active (in Mother Brain framework repo)
@@ -1321,92 +1048,10 @@ 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:
-   
-   **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
+   - **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
 
 ### 2E. **Brainstorm Mode** (Thinking Partner)
    - When user selects "Just talk (brainstorm mode)":
@@ -2797,99 +2442,12 @@ 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)**
-   - **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!
-     ```
-   
+   - **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
    - **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

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

@@ -0,0 +1,114 @@
+# 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

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,65 @@
+# 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

@@ -0,0 +1,70 @@
+# 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.