mother-brain 0.0.21 → 0.0.23

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.21";
+var VERSION = "0.0.23";
 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.21",
+  "version": "0.0.23",
   "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)
@@ -639,20 +724,22 @@ 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** (GitHub Issue-Based Contribution)
+### 2A. **Send Improvement to Mother Brain** (Automatic One-Click Contribution)
    - When user selects "📤 Send improvement to Mother Brain":
    
-   **Purpose**: Instead of directly modifying Mother Brain files, improvements are submitted as GitHub issues. This prevents users from overwriting each other's changes and ensures all improvements are reviewed.
+   **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: Detect Local Changes**
+   **Step 2A.1: Auto-Detect Local Changes**
    
-   - Scan for local changes to Mother Brain core files:
+   - Silently scan for changes to core files:
      ```powershell
-     git diff --name-only HEAD -- ".github/skills/mother-brain/" "cli/"
-     git status --porcelain -- ".github/skills/mother-brain/" "cli/"
+     git diff --name-only HEAD -- ".github/skills/mother-brain/" ".github/skills/child-brain/" ".github/skills/skill-creator/" "cli/"
+     git status --porcelain -- ".github/skills/mother-brain/" ".github/skills/child-brain/" ".github/skills/skill-creator/" "cli/"
      ```
    
-   - **Core files to check**:
+   - **Core files checked**:
      - `.github/skills/mother-brain/SKILL.md`
      - `.github/skills/child-brain/SKILL.md`
      - `.github/skills/skill-creator/SKILL.md`
@@ -660,100 +747,97 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - `cli/package.json`
    
    - **If no changes detected**:
-     - Display: "No local Mother Brain changes detected."
-     - Ask if user wants to describe an improvement anyway
+     - Display: "📭 No local Mother Brain changes to send. Make improvements first, then come back here."
+     - Return to main menu (Step 2)
    
-   **Step 2A.2: Summarize Changes**
+   **Step 2A.2: Auto-Generate Diff Summary**
    
-   - For each changed file, get the diff:
-     ```powershell
-     git diff HEAD -- [file]
-     ```
+   - 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
    
-   - Create a summary of changes in human-readable format:
-     ```
-     📝 Local Mother Brain Changes Detected
-     
-     Files Changed:
-     - [file1]: [brief description of change]
-     - [file2]: [brief description of change]
-     
-     Summary:
-     [AI-generated summary of what the changes accomplish]
-     ```
+   **Step 2A.3: Auto-Extract Learning Context**
    
-   **Step 2A.3: Gather Context from Learning Log**
+   - Check `.mother-brain/project-brain.md` for recent learnings:
+     - Extract last 3-5 relevant learning entries
+     - Focus on friction that triggered Mother Brain improvements
    
-   - Check `.mother-brain/project-brain.md` for recent learnings that triggered this improvement
-   - Check conversation history for friction that led to the changes
-   - Compile into "Why This Improvement" section:
-     ```
-     Why This Improvement:
-     - Friction encountered: [description]
-     - Learning from project: [what was learned]
-     - Expected benefit: [how this helps all users]
-     ```
+   - Check conversation history for:
+     - What friction was encountered
+     - How it was resolved
+     - What insight led to the improvement
    
-   **Step 2A.4: Create GitHub Issue**
+   **Step 2A.4: Auto-Create GitHub Issue**
    
-   - Generate issue title and body:
+   - Generate complete issue automatically:
      ```markdown
-     Title: [Improvement] [Brief description of improvement]
+     Title: [Improvement] [AI-generated brief title from changes]
      
      ## Summary
-     [AI-generated summary of the improvement]
+     [AI-generated summary explaining the improvement in 2-3 sentences]
      
-     ## Changes Proposed
-     [Detailed diff or description of each change]
+     ## Changes
+     [Collapsible diff for each file]
+     <details>
+     <summary>[filename] - [brief description]</summary>
+     
+     ```diff
+     [actual diff]
+     ```
+     </details>
      
      ## Why This Improvement
-     - **Friction Encountered**: [What problem was faced]
-     - **Context**: [Relevant learnings or examples]
-     - **Expected Benefit**: [How this helps all Mother Brain users]
+     **Friction Encountered:**
+     [Extracted from learning log - what problem was faced]
+     
+     **Resolution:**
+     [How the improvement addresses the friction]
      
-     ## Files Affected
-     - [ ] `.github/skills/mother-brain/SKILL.md`
-     - [ ] [other files]
+     **Expected Benefit:**
+     [How this helps all Mother Brain users]
      
-     ## Testing Notes
-     [Any notes on how to test this improvement]
+     ## Learning Log Context
+     [Relevant excerpts from project-brain.md that led to this improvement]
      
      ---
-     *Submitted via Mother Brain "Send Improvement" workflow*
+     *Submitted automatically via Mother Brain v[version]*
      ```
    
-   - Use GitHub MCP server to create the issue:
+   - Create issue using GitHub MCP:
      ```
      github-mcp-server: create_issue
-     owner: [Mother Brain repo owner]
+     owner: [Mother Brain repo owner from git remote]
      repo: [Mother Brain repo name]
      title: [Generated title]
      body: [Generated body]
      labels: ["improvement", "community-contribution"]
      ```
    
-   - Display confirmation:
+   **Step 2A.5: Confirm and Offer Revert**
+   
+   - Display success message:
      ```
      ✅ Improvement Submitted!
      
-     Issue Created: #[number] - [title]
-     URL: [issue URL]
+     Issue #[number]: [title]
+     [issue URL]
      
-     The Mother Brain maintainers will review your improvement.
-     Your local changes have been preserved.
+     Changes detected:
+     • [file1] - [brief change description]
+     • [file2] - [brief change description]
      ```
    
-   **Step 2A.5: Offer to Revert Local Changes**
-   
    - Use `ask_user` with choices:
-     - "Keep local changes (for further testing)"
+     - "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 last commit."
+     - Display: "✨ Local Mother Brain files reverted to clean slate."
    
    - Return to main menu (Step 2)
 
@@ -769,81 +853,130 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      labels: ["improvement"]
      ```
    
-   - Display issue list:
+   - **If no issues**: Display "📭 No community improvements pending review." → Return to menu
+   
+   - **If issues exist**: Display summarized list:
      ```
-     📥 Community Improvements to Review
+     📥 Community Improvements to Review ([count] pending)
      
-     1. #[number] - [title] (by @[author], [date])
-        Status: [open/in review]
-     2. #[number] - [title] (by @[author], [date])
-        Status: [open/in review]
-     [...]
+     ┌─────────────────────────────────────────────────────────────┐
+     │ #[number] - [title]                                        │
+     │ by @[author] • [time ago]                                   │
+     │                                                             │
+     │ 📝 [AI-generated 1-sentence summary of what this improves] │
+     │ 📁 [files affected count] files • [lines changed] lines    │
+     └─────────────────────────────────────────────────────────────┘
      
-     Select an issue to review, or go back.
+     [Repeat for each issue, max 5 shown]
      ```
    
    - Use `ask_user` with issue numbers as choices + "Back to menu"
    
    **Step 2A.1.2: Review Selected Issue**
    
-   - Fetch full issue details:
-     ```
-     github-mcp-server: get_issue
-     issue_number: [selected]
-     ```
+   - Fetch full issue details
    
-   - Display issue content with analysis:
+   - Display with AI-generated analysis:
      ```
      📋 Issue #[number]: [title]
      
-     Submitted by: @[author]
-     Date: [created_at]
+     Submitted by: @[author] • [created_at]
      
-     [Issue body]
+     ═══════════════════════════════════════════════════════════════
      
-     ---
-     🔍 Impact Analysis:
-     - Files affected: [list]
-     - Risk level: [low/medium/high]
-     - Dependencies: [any]
+     🔍 IMPACT SUMMARY
+     
+     What It Does:
+     [AI-generated 2-3 sentence explanation of the improvement]
+     
+     Why It Was Submitted:
+     [Extract from "Friction Encountered" section of issue]
+     
+     Risk Assessment:
+     • Scope: [Low/Medium/High] - [brief reason]
+     • Breaking Changes: [None/Minor/Major]
+     • Files: [list affected files]
+     
+     ═══════════════════════════════════════════════════════════════
+     
+     📄 FULL DIFF
+     [Collapsible or scrollable diff from issue body]
      ```
    
    - Use `ask_user` with choices:
-     - "Accept and integrate this improvement"
-     - "Request changes (comment on issue)"
-     - "Reject (close with explanation)"
-     - "Skip for now"
+     - "✅ Accept - integrate this improvement"
+     - "❌ Reject - close with explanation"
+     - "💬 Request changes - ask for modifications"
+     - "⏭️ Skip - review later"
    
-   **Step 2A.1.3: Integrate Accepted Improvement**
+   **Step 2A.1.3: Accept Improvement**
    
    - If accepted:
-     1. Apply the proposed changes using `edit` tool
-     2. Run any tests if they exist
-     3. Comment on issue: "Integrated in [version]"
-     4. Close issue with "integrated" label
-   
-   - Display:
-     ```
-     ✅ Improvement Integrated
-     
-     Changes applied from issue #[number].
-     Ready for release when you choose "Release Mother Brain".
-     ```
-   
-   **Step 2A.1.4: Request Changes**
+     1. Parse the diffs from the issue body
+     2. Apply changes using `edit` tool
+     3. Run validation (npm build if CLI changes)
+     4. **Auto-comment** on issue:
+        ```markdown
+        ✅ **Improvement Integrated**
+        
+        Thank you for this contribution! Your improvement has been integrated 
+        and will be included in the next release.
+        
+        Changes applied:
+        - [list of files modified]
+        
+        🚀 *Integrated by Mother Brain*
+        ```
+     5. Close issue with "integrated" label
+   
+   - Display: "✅ Improvement from #[number] integrated. Ready for release."
+   
+   **Step 2A.1.4: Reject Improvement**
+   
+   - If rejected:
+     1. Use `ask_user` to get brief reason (or offer common reasons):
+        - "Doesn't align with framework direction"
+        - "Implementation approach needs rework"
+        - "Duplicate of existing functionality"
+        - "Custom reason..."
+     2. **Auto-comment** on issue:
+        ```markdown
+        ❌ **Improvement Not Accepted**
+        
+        Thank you for taking the time to submit this improvement. 
+        After review, we've decided not to integrate it at this time.
+        
+        **Reason:** [selected/custom reason]
+        
+        [If appropriate: "Feel free to revise and resubmit if you'd like 
+        to address this feedback."]
+        
+        🙏 *We appreciate your contribution to Mother Brain*
+        ```
+     3. Close issue with "wontfix" label
+   
+   - Display: "Issue #[number] closed with explanation."
+   
+   **Step 2A.1.5: Request Changes**
    
    - If "Request changes" selected:
-     - Use `ask_user` to get feedback text
-     - Comment on issue with feedback
-     - Display confirmation
-   
-   **Step 2A.1.5: Reject Improvement**
-   
-   - If "Reject" selected:
-     - Use `ask_user` to get rejection reason
-     - Comment on issue with explanation
-     - Close issue with "wontfix" label
-     - Display confirmation
+     1. Use `ask_user` to get feedback text
+     2. **Auto-comment** on issue:
+        ```markdown
+        💬 **Changes Requested**
+        
+        Thanks for this improvement! Before we can integrate it, 
+        please address the following:
+        
+        [user's feedback]
+        
+        Once updated, we'll review again.
+        
+        🔄 *Feedback from Mother Brain maintainer*
+        ```
+     3. Add "changes-requested" label
+   
+   - Display: "Feedback posted to #[number]."
 
 
 

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