mother-brain 0.6.0 → 0.6.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.6.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.6.0",
+  "version": "0.6.2",
   "description": "AI-powered project management framework for GitHub Copilot CLI",
   "type": "module",
   "main": "dist/index.js",

package/skills/mother-brain/SKILL.md

@@ -277,6 +277,21 @@ Mother Brain transforms high-level visions into executable reality by:
 - **AGENT RUNTIME CONTEXT IN ISSUES**: When documenting friction, bugs, or improvements, always note the agent runtime (e.g., "Copilot CLI + Claude Sonnet", "Codex CLI + GPT-5"). Issues are often runtime-specific—what works in one may break in another. This context is essential for reproducing and scoping fixes.
 - **EMOJI AS ENHANCEMENT, NOT IDENTIFIER**: Emoji rendering varies across agent runtimes and models. Always include text labels alongside emoji markers (e.g., "🧠 Mother Brain" not just "🧠"). Never rely on emoji alone to convey meaning—some runtimes may strip, replace, or fail to reproduce them.
 - **VERIFICATION OVER TRUST**: When user completes a setup/configuration step that CAN be programmatically verified, ALWAYS verify before proceeding. Don't trust "done" when verification is possible. Verification methods: API calls, CLI commands, file existence checks, service health endpoints, build artifact validation.
+- **STORY ANCHOR TRACKING (CRITICAL)**: Session state MUST track `currentStory` (the outcome being worked on) and `storyApproved` (boolean). Before ANY response, check: "Is there an unapproved story in progress?" If yes, ALWAYS show story context header: "📋 Current Story: [Ability to X] — Status: [In Progress/Awaiting Approval]". Feedback during story execution is a sub-task, NOT a context switch. Never lose track of the active story.
+- **VISUAL/DESIGN DISCOVERY GATE (BLOCKING)**: Before implementing ANY story with visual/UI elements, run MANDATORY discovery:
+  1. "What style/aesthetic are you imagining?"
+  2. "Any references, examples, or inspiration?"
+  3. "What should it definitely NOT look like?"
+  Block implementation until user provides direction. Never make styling decisions autonomously — visual choices are user-driven, not AI-driven.
+- **BLOCKING DEPENDENCIES UPFRONT**: At story start, identify ALL user-dependent actions the AI cannot perform (API keys, app setup, external configs, account creation). Ask for ALL of these upfront: "Before I can work autonomously, I need: [list]". Do not start implementation until blocking dependencies are resolved.
+- **STORY CONFIDENCE CHECK (MINI-DISCOVERY)**: Before implementing ANY story, assess: "Do I have enough information to implement this correctly?" Technical details = usually yes. Creative/UX/style details = usually no. If uncertain on ANY user-facing aspect, ask targeted questions BEFORE implementing. Never assume layout, styling, content, or interaction patterns — ask first.
+- **SUB-TASK CLASSIFICATION (MID-STORY FEEDBACK)**: When bugs or feedback arise during story execution:
+  1. Ask: "Is this essential to meet the outcome's acceptance criteria, or a separate improvement?"
+  2. If ESSENTIAL to outcome → treat as immediate sub-task, fix before continuing
+  3. If NOT essential to outcome → add to backlog, continue with story
+  Keep story focused on its acceptance criteria. Don't let scope creep derail completion.
+- **STORY-FIRST TERMINOLOGY**: In ALL user-facing output, use "story" (user outcome) not "task" (internal implementation). Stories = outcomes with acceptance criteria that users validate. Tasks = internal implementation details never shown to users for validation. User validates: "Can I now do X?" not "Does this code work?"
+- **CONSERVATIVE VERSIONING**: Use patch versions (0.X.Y) for at least 20 releases before incrementing minor version. Prevents version number inflation. Example: 0.6.1 → 0.6.2 → ... → 0.6.21 → 0.7.0.
 
 ### Output Formatting Rules (CRITICAL)
 
@@ -600,75 +615,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:
@@ -753,217 +702,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)
@@ -1324,92 +1066,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)":
@@ -2977,99 +2637,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
@@ -3128,7 +2701,7 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    
    Before implementing ANY task, you MUST complete this gate:
    
-   **Step 9.0: Task Start Assessment**
+   **Step 9.0: Story Start Assessment**
    
    1. **Load Project Brain** (if exists):
       - Read `.mother-brain/project-brain.md`
@@ -3171,6 +2744,33 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
         - 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:
@@ -3595,6 +3195,64 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
    
    **Key Principle**: Mother Brain orchestrates; Child Brain analyzes and routes. This separation keeps Mother Brain clean.
 
+### 10A.1 **Mid-Story Sub-Task Classification (MANDATORY)**
+
+When bugs, issues, or feedback arise DURING story execution (before outcome validation):
+
+**Step 10A.1.1: Display Story Context Header**
+Always remind user of the active story:
+```
+📋 Current Story: [Outcome Name]
+Status: In Progress | [X/Y] acceptance criteria verified
+
+⚠️ Issue Detected: [brief description of issue/feedback]
+```
+
+**Step 10A.1.2: Classify the Issue**
+Ask user to classify:
+```
+Is this issue essential to meet the outcome, or a separate improvement?
+
+1. 🎯 Essential — must fix before this outcome can be considered complete
+2. 📋 Improvement — add to backlog, continue with current story
+3. ❓ Not sure — let's discuss
+```
+
+**Step 10A.1.3: Handle Based on Classification**
+
+**If ESSENTIAL:**
+- Treat as immediate sub-task
+- Add to session-state.json: `currentStory.subTasks` with `essential: true`
+- Fix before continuing with story
+- Display: "📌 Adding as essential sub-task, fixing now..."
+
+**If IMPROVEMENT (not essential):**
+- Add to backlog (roadmap.md or backlog section)
+- Mark in session-state.json: `currentStory.subTasks` with `essential: false, status: "backlog"`
+- Continue with current story
+- Display: "📋 Added to backlog — continuing with [story name]..."
+
+**If NOT SURE:**
+- Ask clarifying question:
+  ```
+  Let me help clarify:
+  
+  The current story's acceptance criteria are:
+  1. [Criterion A]
+  2. [Criterion B]
+  
+  Does this issue block any of these specific criteria from being met?
+  ```
+- Based on response, classify as essential or improvement
+
+**Step 10A.1.4: Maintain Story Focus**
+After handling sub-task:
+- Always return to story context
+- Show: "📋 Returning to: [Outcome Name]"
+- Display remaining acceptance criteria to verify
+
+**Key Principle**: Stories stay focused on their acceptance criteria. Scope creep is routed to backlog, not allowed to derail completion.
+
 ### 10B. **Post-Task Reflection via Child Brain** (Proactive Improvement)
    - **When to run**: ALWAYS after task is marked complete by user - this is mandatory, not optional
    - **Trigger**: Step 10 task completion → Step 10B runs automatically → then Step 11
@@ -3789,9 +3447,25 @@ Key rules: Use `allow_freeform: true` on all `ask_user` calls. Check freeform re
      ```json
      {
        "projectName": "Gaming Backlog Manager",
+       "currentStory": {
+         "id": "outcome-001",
+         "name": "Ability to track my game backlog",
+         "approved": false,
+         "acceptanceCriteria": [
+           {"criterion": "I can add games to my backlog", "verified": true},
+           {"criterion": "I can mark games as completed", "verified": false},
+           {"criterion": "I can see my backlog list", "verified": true}
+         ],
+         "subTasks": [
+           {"id": "sub-001", "description": "Fix mobile layout", "essential": true, "status": "done"},
+           {"id": "sub-002", "description": "Add dark mode", "essential": false, "status": "backlog"}
+         ],
+         "blockingDependencies": []
+       },
        "lastTask": "003-localstorage-data-layer",
        "lastTaskStatus": "DONE",
        "currentPhase": "Phase 1",
+       "completedStories": ["outcome-001"],
        "completedTasks": ["001", "002", "003"],
        "totalTasks": 9,
        "skillsCreated": ["pwa-builder"],

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.