mother-brain 0.0.22 → 0.0.24

package/dist/cli.js

@@ -653,7 +653,7 @@ async function uninstall(options) {
 // src/cli.ts
 import { exec as exec3 } from "child_process";
 var program = new Command();
-var VERSION = "0.0.22";
+var VERSION = "0.0.24";
 program.name("mother-brain").description("AI-powered project management framework for GitHub Copilot 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.0.22",
+  "version": "0.0.24",
   "description": "AI-powered project management framework for GitHub Copilot CLI",
   "type": "module",
   "main": "dist/index.js",

package/skills/child-brain/SKILL.md

@@ -13,6 +13,40 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 
 **The Feedback Expert & Learning Orchestrator**
 
+## 🚨 HARD RULES (MANDATORY)
+
+### RULE 1: TRIGGER ON ALL FREEFORM
+- **ANY freeform response = INVOKE CHILD BRAIN IMMEDIATELY**
+- Don't wait for friction - preferences, hints, feedback are ALL learning opportunities
+- If user typed text instead of selecting an option → Child Brain MUST run
+- Trigger keywords: "I prefer", "I like", "I think", "actually", "instead", "rather", "maybe", "what about"
+
+### RULE 2: ALWAYS RETURN TO CALLER
+- Child Brain is INVOKED by Mother Brain
+- After completing analysis, you MUST return control to Mother Brain
+- NEVER stop after analysis - Mother Brain menu must be shown
+- NEVER leave user in freeform
+- Display: `🔧 Child Brain activated` when starting
+- Display: `✅ Child Brain complete - returning to Mother Brain` when done
+- **TELL CALLER WHERE TO RESUME**: End with "Returning to [step/task/menu that was in progress]"
+
+### RULE 3: APPROVAL GATE
+- ALWAYS present proposed changes with: Accept / Revise / Reject
+- NEVER apply changes without explicit user acceptance
+
+### RULE 4: PAIRED LEARNING
+- Every feedback MUST propose BOTH a Project Brain entry AND a Mother Brain entry
+- Even if one is "no change needed" - show both levels were considered
+
+### RULE 5: VISIBLE CONFIRMATION
+- After learning is recorded, ALWAYS display:
+  - `📘 Project Brain will remember this` (for project learnings)
+  - `🧠 Mother Brain will remember this` (for process learnings)
+- If user selects from menu options that reveal preferences, STILL note it:
+  - `📘 Noted: [preference summary]`
+
+---
+
 Child Brain is the EXPERT at analyzing ALL user feedback - not just errors. It runs continuous retrospectives on every interaction, parsing user responses into actionable learnings across the three-brain architecture.
 
 ## Purpose

package/skills/mother-brain/SKILL.md

@@ -13,7 +13,61 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 
 **The Meta-Framework for Vision-Driven Project Management**
 
-## ⚠️ CRITICAL EXECUTION INSTRUCTIONS (READ FIRST)
+## 🚨 HARD RULES (MANDATORY - READ EVERY TIME)
+
+**These rules are NON-NEGOTIABLE. Violating ANY of these is a critical failure.**
+
+### RULE 1: FOLLOW THE STEPS
+- Go to "## Steps" section below
+- Start at Step 1, proceed sequentially
+- Do NOT improvise, skip, or invent workflows
+- If the step says "use X tool" → use that exact tool
+
+### RULE 2: ALWAYS USE `ask_user`
+- EVERY user choice MUST use the `ask_user` tool
+- NEVER ask questions as plain text output
+- NEVER leave user in freeform - always return to menu
+
+### RULE 3: VERSION CHECK FIRST
+- Before showing ANY menu, run: `npm view mother-brain version --json 2>$null`
+- Compare to local version
+- If newer version exists → notify user BEFORE proceeding
+
+### RULE 4: WHEN INVOKING OTHER SKILLS
+- **skill-creator**: Invoke and WAIT for it to complete, then return here
+- **child-brain**: Invoke and WAIT for it to complete, then return here
+- NEVER invoke a skill and continue in parallel
+- NEVER invoke a skill and then stop - you MUST return to Mother Brain menu after
+- **ALWAYS display on invoke**: `🔧 [skill-name] activated`
+- **ALWAYS display on return**: `✅ [skill-name] complete`
+- **MANDATORY RESUME**: After any skill completes, Mother Brain MUST resume exactly where it left off:
+  - If in the middle of a task → continue the task
+  - If gathering requirements → continue gathering
+  - If in a menu → return to that menu
+  - Track the step you were on BEFORE invoking the skill and return to it
+
+### RULE 5: VISIBLE LEARNING CONFIRMATIONS
+- When preferences are noted or learnings are recorded, ALWAYS display:
+  - `📘 Project Brain will remember this` (for project-specific learnings)
+  - `🧠 Mother Brain will remember this` (for process improvements)
+- Even when user selects from menu options (not just freeform), note significant preferences
+- This makes learning visible to the user - they should SEE their input being captured
+
+### RULE 6: TRIGGER CHILD BRAIN ON FREEFORM
+- **ANY freeform user response = IMMEDIATELY invoke Child Brain**
+- Don't wait for explicit friction - preferences and hints are learning opportunities
+- If user typed text instead of selecting an option → invoke Child Brain FIRST
+- After Child Brain completes, continue with whatever Mother Brain was doing
+- Trigger keywords to watch for: "I prefer", "I like", "actually", "instead", "maybe", "what about"
+
+### RULE 7: SELF-CHECK
+- If you're about to do something NOT in the Steps section → STOP
+- If you're about to ask the user something without `ask_user` → STOP
+- If you've completed an action but have no menu to show → STOP and return to Step 2
+
+---
+
+## ⚠️ CRITICAL EXECUTION INSTRUCTIONS
 
 **YOU MUST follow the Steps section EXACTLY as written. Do not improvise, skip steps, or invent your own workflow.**
 
@@ -22,6 +76,12 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 3. **Use `ask_user` for ALL choices** - Never ask questions as plain text
 4. **Execute tool calls as specified** - When a step says "use X tool", use that exact tool
 5. **Do not summarize or paraphrase** - Display the exact text templates shown in steps
+6. **NEVER leave user in freeform** - After completing ANY action (release, task, review, etc.), ALWAYS return to the appropriate menu. User should always have clear next options, never an empty prompt waiting for input.
+7. **MANDATORY VERSION CHECK ON STARTUP** - Before showing ANY menu, you MUST check for updates:
+   ```powershell
+   npm view mother-brain version --json 2>$null
+   ```
+   Compare against local version in `.mother-brain/version.json` or `cli/package.json`. If a newer version exists, notify the user BEFORE proceeding. This is NOT optional - skipping this check is a violation.
 
 **If you find yourself doing something NOT described in the Steps section below, STOP and return to the documented workflow.**
 
@@ -343,7 +403,32 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
 
 ### 2. **Detect Project State & Show Progress**
    
-   **🧬 META-MODE DETECTION (FIRST CHECK - BEFORE EVERYTHING)**:
+   **🚨 MANDATORY VERSION CHECK (FIRST - BEFORE ANYTHING ELSE)**:
+   - This check is NON-NEGOTIABLE. Do this BEFORE any other detection.
+   - Run version check:
+     ```powershell
+     npm view mother-brain version --json 2>$null
+     ```
+   - Compare against:
+     - If in framework repo: `cli/package.json` version field
+     - If in project: `.mother-brain/version.json` version field
+   - **If newer version exists**:
+     ```
+     ⚠️ Mother Brain Update Available
+     
+     Installed: v[current]
+     Latest: v[npm version]
+     
+     Update recommended before continuing.
+     ```
+     - Use `ask_user` with choices:
+       - "Update now (recommended)"
+       - "Skip this time"
+     - **If "Update now"**: Run auto-update (see update commands below), then continue
+     - **If "Skip"**: Continue but note version mismatch
+   - **If current or check fails**: Continue silently
+   
+   **🧬 META-MODE DETECTION (AFTER VERSION CHECK)**:
    - Detect if we are IN the Mother Brain framework repo itself:
      1. Check for `cli/` folder with `package.json` containing `"name": "mother-brain"`
      2. Check for `.github/skills/mother-brain/SKILL.md` (this file)
@@ -453,20 +538,16 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - Question: "What would you like to do?"
      - Choices (MUST be provided as array):
        - "Continue where I left off"
-       - "Start next task"
        - "Review/update roadmap"
        - "Realign with vision"
-       - "View all skills"
-       - "Create new skill"
-       - "📤 Send improvement to Mother Brain"
-       - "Release Mother Brain (commit & PR)"
+       - "🧠 Improve Mother Brain"
        - "Archive project (save & reset for new project)"
        - "Eject project (reset to framework + learnings)"
-       - "🚨 Report Issue (something's not working)"
    - **CRITICAL**: Do NOT ask what to do as freeform text. ALWAYS use the `ask_user` tool.
    - Freeform automatically available for custom actions
+   - **If "Improve Mother Brain"**: Jump to **Step 2A: Improve Mother Brain Menu**
    - **If "Send improvement"**: Jump to **Step 2A: Send Improvement to Mother Brain**
-   
+
    **If existing project WITHOUT Mother Brain artifacts (ONBOARDING):**
    - Detect: Files exist in directory, but NO `.mother-brain/` folder and NO `docs/vision.md`
    - Display:
@@ -481,11 +562,9 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    - Use `ask_user` with choices:
      - "Yes, onboard Mother Brain into this project"
      - "No, start fresh (ignore existing files)"
-     - "📤 Send improvement to Mother Brain"
-   
+
    - **If user selects onboarding**: Jump to **Step 2.2: Existing Project Onboarding**
-   - **If "Send improvement"**: Jump to **Step 2A: Send Improvement to Mother Brain**
-   
+
    **If new project (empty directory or user chose fresh start):**
    - Display welcome:
      ```
@@ -505,10 +584,8 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
        - "I just want to brainstorm an idea"
        - "I have a vision document already (import it)"
        - "Show me what Mother Brain can do"
-       - "📤 Send improvement to Mother Brain"
    - **CRITICAL**: Do NOT ask "Ready to begin?" as freeform text. ALWAYS use the `ask_user` tool with the choices above.
    - Proceed based on selection
-   - **If "Send improvement"**: Jump to **Step 2A: Send Improvement to Mother Brain**
 
 ### 2.3. **Meta-Mode (Framework Improvement)**
    - When user selects "Improve Mother Brain" from the framework repo menu:
@@ -524,7 +601,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - "📥 Review community improvements"
      - "Continue previous meta-work"
    
-   - **If "Review community improvements"**: Jump to **Step 2A.1: Review Community Improvements**
+   - **If "Review community improvements"**: Jump to **Step 2A.2: Review Community Improvements**
    
    **Step 2.3.2: Track Meta-Work**
    - Update `.mother-brain/meta-mode.json` with focus:
@@ -639,14 +716,89 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    
    - Proceed to normal workflow (Step 8+)
 
-### 2A. **Send Improvement to Mother Brain** (Automatic One-Click Contribution)
-   - When user selects "📤 Send improvement to Mother Brain":
+### 2A. **Improve Mother Brain Menu** (From Any Project)
+   - When user selects "🧠 Improve Mother Brain" from the existing project menu:
+   
+   **Purpose**: Entry point for reporting issues, suggesting improvements, or contributing fixes to Mother Brain from within any project.
+   
+   **Step 2A.0: Show Improvement Menu**
+   
+   - Display:
+     ```
+     🧠 Improve Mother Brain
+     
+     Encountered friction or have ideas for improvement?
+     ```
+   
+   - Use `ask_user` with choices:
+     - "Something broke or didn't work"
+     - "A feature is missing"
+     - "The workflow is confusing"
+     - "I have a suggestion for improvement"
+     - "📤 Send my local improvements (auto-detect changes)"
+     - "⬅️ Back to project"
+   
+   **Step 2A.0.1: Friction Auto-Detection (for "Something broke")**
+   
+   - **If user selects "Something broke or didn't work"**:
+     - Scan recent conversation for:
+       - Error messages
+       - User frustration signals ("this doesn't work", "wrong", "broken")
+       - Tool failures
+       - Unexpected behavior
+     - Display detected issues:
+       ```
+       🔍 Analyzing recent session for issues...
+       
+       Found:
+       - [Issue 1]: [description]
+       - [Issue 2]: [description]
+       
+       Would you like me to fix these locally?
+       ```
+     - Use `ask_user` with choices:
+       - "Yes, fix these issues"
+       - "No, let me describe the problem"
+       - "Back to menu"
+     - **If "Yes, fix"**: Work on the fix, then offer to send improvement
+     - **If "No, let me describe"**: Ask user to describe, then work on fix
+   
+   **Step 2A.0.2: Missing Feature (for "A feature is missing")**
+   
+   - **If user selects "A feature is missing"**:
+     - Ask user to describe what's missing
+     - Determine if it can be added locally or needs to be an issue
+     - Work on adding the feature if appropriate
+     - Offer to send improvement when done
+   
+   **Step 2A.0.3: Confusing Workflow (for "The workflow is confusing")**
+   
+   - **If user selects "The workflow is confusing"**:
+     - Ask user to describe what's confusing
+     - Analyze the current workflow for that area
+     - Suggest clarifications or improvements
+     - Work on improving it if appropriate
+   
+   **Step 2A.0.4: Suggestion (for "I have a suggestion")**
+   
+   - **If user selects "I have a suggestion for improvement"**:
+     - Ask user to describe their suggestion
+     - Analyze feasibility
+     - Work on implementing if appropriate
+     - Offer to send improvement when done
+   
+   - **If "Send my local improvements"**: Continue to Step 2A.1 (Auto-Detect)
+   
+   - **If "Back to project"**: Return to main menu (Step 2)
+
+### 2A.1 **Send Improvement** (Automatic One-Click Contribution)
+   - When user selects "📤 Send my local improvements":
    
    **Purpose**: Automatically detect local Mother Brain improvements, gather context from learning logs, and submit a fully-formed GitHub issue in one click. No questions asked - just send.
    
    **AUTOMATIC WORKFLOW (No User Prompts)**:
    
-   **Step 2A.1: Auto-Detect Local Changes**
+   **Step 2A.1.1: Auto-Detect Local Changes**
    
    - Silently scan for changes to core files:
      ```powershell
@@ -663,17 +815,17 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    
    - **If no changes detected**:
      - Display: "📭 No local Mother Brain changes to send. Make improvements first, then come back here."
-     - Return to main menu (Step 2)
-   
-   **Step 2A.2: Auto-Generate Diff Summary**
+     - Return to Step 2A (Improve Mother Brain Menu)
    
+   **Step 2A.1.2: Auto-Generate Diff Summary**
+
    - For each changed file, get the diff silently
    - AI generates a human-readable summary:
      - What was changed
      - Why it was changed (inferred from diff context)
      - Expected benefit
    
-   **Step 2A.3: Auto-Extract Learning Context**
+   **Step 2A.1.3: Auto-Extract Learning Context**
    
    - Check `.mother-brain/project-brain.md` for recent learnings:
      - Extract last 3-5 relevant learning entries
@@ -684,7 +836,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - How it was resolved
      - What insight led to the improvement
    
-   **Step 2A.4: Auto-Create GitHub Issue**
+   **Step 2A.1.4: Auto-Create GitHub Issue**
    
    - Generate complete issue automatically:
      ```markdown
@@ -730,7 +882,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      labels: ["improvement", "community-contribution"]
      ```
    
-   **Step 2A.5: Confirm and Offer Revert**
+   **Step 2A.1.5: Confirm and Offer Revert**
    
    - Display success message:
      ```
@@ -756,10 +908,10 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    
    - Return to main menu (Step 2)
 
-### 2A.1 **Review Community Improvements** (Maintainer Workflow)
+### 2A.2 **Review Community Improvements** (Maintainer Workflow)
    - **Access**: Only shown when meta-mode is active (in Mother Brain framework repo)
    
-   **Step 2A.1.1: List Open Improvement Issues**
+   **Step 2A.2.1: List Open Improvement Issues**
    
    - Fetch issues with "improvement" or "community-contribution" labels:
      ```
@@ -787,10 +939,10 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    
    - Use `ask_user` with issue numbers as choices + "Back to menu"
    
-   **Step 2A.1.2: Review Selected Issue**
-   
+   **Step 2A.2.2: Review Selected Issue**
+
    - Fetch full issue details
-   
+
    - Display with AI-generated analysis:
      ```
      📋 Issue #[number]: [title]
@@ -824,8 +976,8 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - "💬 Request changes - ask for modifications"
      - "⏭️ Skip - review later"
    
-   **Step 2A.1.3: Accept Improvement**
-   
+   **Step 2A.2.3: Accept Improvement**
+
    - If accepted:
      1. Parse the diffs from the issue body
      2. Apply changes using `edit` tool
@@ -846,7 +998,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    
    - Display: "✅ Improvement from #[number] integrated. Ready for release."
    
-   **Step 2A.1.4: Reject Improvement**
+   **Step 2A.2.4: Reject Improvement**
    
    - If rejected:
      1. Use `ask_user` to get brief reason (or offer common reasons):
@@ -872,7 +1024,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    
    - Display: "Issue #[number] closed with explanation."
    
-   **Step 2A.1.5: Request Changes**
+   **Step 2A.2.5: Request Changes**
    
    - If "Request changes" selected:
      1. Use `ask_user` to get feedback text

package/skills/skill-creator/SKILL.md

@@ -11,6 +11,29 @@ allowed-tools: bash node view grep glob web_search ask_user powershell create ed
 
 # Skill Creator
 
+## 🚨 HARD RULES (MANDATORY)
+
+### RULE 1: ALWAYS RETURN TO CALLER
+- Skill Creator is INVOKED by Mother Brain or Child Brain
+- After completing skill creation/update, you MUST return control to the caller
+- NEVER stop after creating a skill - the invoking workflow must continue
+- NEVER leave user in freeform
+- Display: `🔧 Skill Creator activated` when starting
+- Display: `✅ Skill [name] created - returning to [caller]` when done
+- **TELL CALLER WHERE TO RESUME**: End with "Returning to [step/task/menu that was in progress]"
+
+### RULE 2: COMPLETE THE SKILL
+- Every skill MUST have: SKILL.md, examples/, references/, scripts/
+- Empty folders are NOT acceptable
+- Research MUST be performed and saved to references/
+
+### RULE 3: SYNCHRONOUS EXECUTION
+- When invoked, complete the skill creation fully
+- Do NOT run in background or parallel
+- The caller is waiting for you to finish
+
+---
+
 Use this skill when the user wants a new reusable capability, or when you notice repeated work that should be turned into a skill.
 
 ## Purpose