mother-brain 0.1.0 → 0.2.0

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

package/skills/child-brain/SKILL.md

@@ -34,16 +34,23 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 - 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 4: FOUR-LAYER CONSIDERATION
+- Every feedback MUST be analyzed across ALL FOUR layers:
+  1. **Elder Brain**: Is this domain/tech knowledge?
+  2. **Project Brain**: Is this project-specific?
+  3. **Mother Brain**: Is this about thinking process?
+  4. **Skills**: Is execution capability missing?
+- Even if some are "no change needed" - show all layers were considered
+- Display which layers received updates
 
 ### RULE 5: VISIBLE CONFIRMATION
-- After learning is recorded, ALWAYS display:
+- After learning is recorded, ALWAYS display which layers were updated:
+  - `🧙 Elder Brain will remember this` (for domain/tech gotchas)
   - `📘 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]`
+  - `🧠 Mother Brain will remember this` (for thinking process)
+  - `🛠️ [skill-name] created/updated` (for execution capability)
+- Show "No changes" for layers that weren't updated
+- If user selects from menu options that reveal preferences, STILL note it
 
 ---
 
@@ -51,18 +58,30 @@ Child Brain is the EXPERT at analyzing ALL user feedback - not just errors. It r
 
 ## Purpose
 
-Child Brain ensures learnings go to the right place:
-- **Project-specific learnings** → Project Brain (`.mother-brain/project-brain.md`)
-  - Course corrections for this project's trajectory
-  - Style/tone preferences discovered
-  - Skill adjustments needed
-  - Vision document updates
-- **Behavioral/process learnings** → Mother Brain (`.github/skills/mother-brain/SKILL.md`)
-  - How to better facilitate user vision
-  - Process improvements for ALL projects
-  - NEVER domain knowledge or project specifics
-- **Domain knowledge gaps** → Skills (via skill-creator)
-  - When expertise is missing, create a skill
+Child Brain ensures learnings go to the right place across FOUR layers:
+
+1. **Elder Brain** (`experience-vault/`) → **Domain Knowledge**
+   - Technology-specific gotchas (Firebase, React, Vercel)
+   - Platform patterns (Windows paths, auth flows)
+   - Cross-project wisdom that applies to ALL projects of a type
+   - Example: "Firebase Auth needs Console click-through"
+
+2. **Project Brain** (`.mother-brain/project-brain.md`) → **Project-Specific**
+   - Style/tone/design preferences for THIS project
+   - Vision refinements discovered during execution
+   - Validation checks for this project's domain
+   - Example: "This game uses warm cozy Stardew Valley aesthetic"
+
+3. **Mother Brain** (`.github/skills/mother-brain/SKILL.md`) → **Meta-Behavioral**
+   - HOW to think, WHEN to research, WHAT to consider
+   - Process improvements for facilitating ALL projects
+   - Cognition and adaptation patterns
+   - Example: "When learning about outcome, research failure modes"
+
+4. **Skills** (via skill-creator) → **Execution Capability**
+   - Domain-specific execution knowledge
+   - Created when expertise gaps are detected
+   - Example: pixel-art-renderer skill with game art knowledge
 
 Child Brain NEVER stores knowledge itself. It analyzes, routes, and creates.
 
@@ -104,26 +123,42 @@ Child Brain is invoked by Mother Brain for ALL of these (not just errors):
   This ensures both levels are always considered and visible to user.
 - **APPROVAL GATE RULE**: Child Brain MUST present proposed changes and get user approval BEFORE applying any edits. Use three options: Accept / Revise / Reject. NEVER apply changes without explicit user acceptance.
 
-## The Three Questions for Every Learning
-
-When analyzing feedback, Child Brain asks:
-
-1. **Is this about THIS PROJECT specifically?**
-   - Style preferences, design choices, domain conventions
-   - → Route to Project Brain for course correction
-   - → May trigger skill updates for this project
-
-2. **Is this about HOW MOTHER BRAIN FACILITATED?**
-   - Did it consider enough at vision phase?
-   - Did it anticipate what would be needed later?
-   - Did it make the right choices based on user's stated needs?
-   - → Route to Mother Brain as behavioral improvement
-   - → Must be completely project-agnostic
-
-3. **Is this about MISSING EXPERTISE?**
-   - Agent didn't know how to do something well
-   - → Create or update a skill via skill-creator
-   - → Skills hold the domain knowledge
+## The Four Questions for Every Learning
+
+When analyzing feedback, Child Brain asks (IN THIS ORDER):
+
+1. **Is this DOMAIN KNOWLEDGE (technology/platform-specific)?**
+   - Mentions specific technology name? (Firebase, React, Vercel, Windows)
+   - Platform-specific gotcha or pattern?
+   - Cross-project wisdom for this tech stack?
+   - → Route to **Elder Brain** (experience-vault/)
+   - Example: "Firebase Auth needs Console click-through before use"
+
+2. **Is this about THIS PROJECT specifically?**
+   - Style preferences, aesthetic choices, design direction
+   - Vision refinements or missed requirements
+   - Project-specific validation needs
+   - → Route to **Project Brain** for course correction
+   - Example: "This game uses warm cozy Stardew Valley aesthetic"
+
+3. **Is this about HOW MOTHER BRAIN THINKS?**
+   - WHEN to research? WHAT to consider? HOW to anticipate?
+   - Information processing and adaptation patterns
+   - NOT about what to think, but how to approach thinking
+   - → Route to **Mother Brain** as cognitive improvement
+   - Example: "When user mentions outcome, research failure modes first"
+
+4. **Is this about MISSING EXECUTION CAPABILITY?**
+   - Agent didn't know how to execute something well
+   - Need specialized domain knowledge for execution
+   - → Create or update a **Skill** via skill-creator
+   - Example: Need pixel-art-renderer skill with game art knowledge
+
+**The Test (CRITICAL):**
+- Does it mention a technology name? → Elder Brain
+- Is it about this project's style/preferences? → Project Brain  
+- Is it about WHEN/HOW to think? → Mother Brain
+- Is it about execution capability? → Skill
 
 ## Friction Analysis Flow
 
@@ -172,38 +207,110 @@ Determine the **layer** where the issue originated:
 - **Missing Validation**: No check was in place to catch this before user saw it
 - **Process Gap**: Mother Brain's workflow skipped a necessary step
 
-### Step 4: Split the Learning
+### Step 4: Split the Learning (Four-Way Analysis)
 
 Based on root cause, determine what goes where:
 
-**PROJECT-LEVEL Learning (→ Project Brain) - Course Correction:**
-- "This project uses [specific style/tone/approach]"
-- "For this project, always [specific check or validation]"
-- "This project's vision includes [specific requirement]"
-- References, examples, style guides specific to this project
-- Validation checks specific to this project's domain
-- **Course corrections for future tasks:**
-  - "User prefers X over Y - update design skills accordingly"
-  - "Vision document needs to reflect [preference]"
-  - "Flag for Task [N] - incorporate this preference"
-
-**META-LEVEL Learning (→ Mother Brain) - Behavioral Only:**
-- Process improvements that help ALL projects
-- Did Mother Brain consider enough during vision discovery?
-- Did Mother Brain anticipate what would be needed later?
-- Did Mother Brain make the right choices based on user's stated needs?
-- When to create skills (patterns that warrant skill creation)
-- When to ask discovery questions (before implementing creative work)
-- When to research (domains that need external knowledge)
-- Validation gates (when to pause and check with user)
-- **NEVER domain specifics** - those go to skills
-
-**Skill Creation/Update Decision:**
-If root cause is "Missing Skill" or "Insufficient Skill":
-- Invoke skill-creator to create/enhance the skill
-- Skill gets the domain knowledge, NOT Mother Brain
+**ELDER BRAIN (experience-vault/) - Technology/Platform Gotchas:**
+- Check: Does this mention a specific technology or platform name?
+- "Firebase Auth requires Console click-through"
+- "Vercel needs .env.production for build-time vars"
+- "Windows PowerShell needs -Force flag for directories"
+- "React refs don't work with functional components"
+- Cross-project patterns for specific tech stacks
+- Platform-specific workarounds and requirements
+
+**PROJECT BRAIN (.mother-brain/project-brain.md) - This Project's Identity:**
+- "This project uses warm cozy Stardew Valley aesthetic"
+- "This game has horses as central character, not just background"
+- "User prefers Tailwind over CSS modules"
+- Style/tone/design preferences specific to this project
+- Vision refinements discovered during execution
+- Validation checks for this project's domain
+- **Course corrections for future tasks**
+
+**MOTHER BRAIN (.github/skills/mother-brain/SKILL.md) - Thinking Process:**
+- Check: Is this about WHEN/HOW/WHAT to consider? (not about specific content)
+- "When user mentions outcome, research failure modes first"
+- "Before creative work, ask user about style preferences"
+- "When outcome involves data, consider exposure risks"
+- Information processing patterns
+- Research triggers and anticipation
+- **NOT hardcoded rules for domains** - those go to Elder Brain
+
+**SKILL CREATION/UPDATE:**
+- If execution capability is missing
+- If domain knowledge needs to be embedded in tooling
+- Route research findings + user preferences to skill-creator
 - Log skill creation in Project Brain
 
+**The Critical Test:**
+1. Does it mention Firebase/React/Vercel/Windows/etc.? → **Elder Brain**
+2. Is it about this project's aesthetic/style/preferences? → **Project Brain**
+3. Is it about WHEN to research or HOW to think? → **Mother Brain**
+4. Is it about execution tooling? → **Skill**
+
+### Step 4.5: Apply Elder Brain Learning (Domain Gotchas)
+
+**When learning is domain/technology-specific:**
+
+**Step 4.5.1: Identify Domain Category**
+- Security (auth, data exposure, vulnerabilities)
+- Deployment (platform-specific requirements, config)
+- APIs (integration patterns, rate limiting)
+- Databases (schema, ORMs, query patterns)
+- UI (accessibility, responsive, design systems)
+- Platforms (Windows, macOS, Linux, mobile, web)
+
+**Step 4.5.2: Check if Knowledge Already Exists**
+- Search `experience-vault/[category]/` for related files
+- Use grep to check for technology mentions
+- If exists → update existing file
+- If new → create new file
+
+**Step 4.5.3: Document the Gotcha**
+
+Create/update `experience-vault/[category]/[tech-name].md`:
+
+```markdown
+# [Technology Name] - [Brief Title]
+
+## Problem
+[What goes wrong - the error/failure user experiences]
+
+## Gotcha
+[The non-obvious thing - why it happens, what's unexpected]
+
+## Solution
+[How to fix/prevent - code examples, config, steps]
+
+**When to Consult**: [Which Mother Brain steps should reference this]
+
+## Related Gotchas
+See also:
+- [Link to related experience-vault files]
+
+## Sources
+- [Link to official docs]
+- [Link to community resources]
+```
+
+**Step 4.5.4: Display Simple Confirmation**
+
+Display to user:
+```
+🧙 Elder Brain will remember this
+```
+
+**Step 4.5.5: Update Mother Brain Reference (If Needed)**
+
+If this is a common gotcha that Mother Brain should ALWAYS check for:
+- Add reference to appropriate Mother Brain step
+- Example: "Before deploying, consult experience-vault/deployment/"
+- Mother Brain doesn't store the gotcha - just knows WHERE to look
+
+**Key Principle**: Elder Brain stores domain facts. Mother Brain learns to consult Elder Brain at the right times.
+
 ### Step 5: Apply Project-Level Learning (Course Correction) - ACTIVE
 
 **Project Brain is ACTIVE, not passive.** It doesn't just store learnings - it TAKES ACTION:

package/skills/mother-brain/SKILL.md

@@ -668,9 +668,11 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - "Improve documentation"
      - "Refactor or clean up code"
      - "📥 Review community improvements"
+     - "💭 Brainstorm (thinking partner mode)"
      - "Continue previous meta-work"
    
    - **If "Review community improvements"**: Jump to **Step 2A.2: Review Community Improvements**
+   - **If "Brainstorm"**: Jump to **Step 2E: Brainstorm Mode** (framework-focused version)
    
    **Step 2.3.2: Track Meta-Work**
    - Update `.mother-brain/meta-mode.json` with focus:
@@ -2189,19 +2191,33 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      
      **Step 5.4.1: Technology Pitfalls & Gotchas Research (MANDATORY)**
      - For EACH technology/platform/tool identified in vision or research:
+       
+       **First, check Elder Brain (experience-vault/) for existing knowledge:**
+       - Use grep to search: `grep -r "[technology]" experience-vault/`
+       - If gotchas exist in Elder Brain:
+         - Load the relevant .md files
+         - Use this knowledge to inform skill creation
+         - No need to re-research what's already known
+       
+       **If NOT in Elder Brain, research and contribute:**
        - Use `web_search` to research:
-         1. "common [technology] mistakes and pitfalls"
+         1. "common [technology] mistakes and pitfalls [current year]"
          2. "[technology] gotchas first-time users encounter"
          3. "[technology] troubleshooting guide"
          4. "[technology] deployment issues and solutions" (if applicable)
-       - Save findings to `.mother-brain/docs/research/[technology]-gotchas.md`
+       - Save findings to BOTH:
+         1. `.mother-brain/docs/research/[technology]-gotchas.md` (project-specific)
+         2. `experience-vault/[category]/[technology].md` (for all future projects)
        - Document:
          - **Common Mistakes**: What do beginners get wrong?
          - **Setup Traps**: First-time setup issues (permissions, configuration, prerequisites)
          - **Known Failures**: Transient errors vs real failures
          - **Workarounds**: Standard solutions to known problems
+       
+       **Result:**
        - This research gets embedded in skills created for this technology
        - Skills become defensive, anticipating known issues instead of only happy-path
+       - Future projects benefit immediately from Elder Brain knowledge
      
      **Step 5.5: Extract Technical Insights from Research**
      - Parse research results to identify:
@@ -2417,13 +2433,46 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - **Create Initial 3 Skills** (Upfront - minimum viable skill set):
        - Display: "🔨 Creating initial 3 skills for project..."
        - Select 3 most critical skills from essential list (based on immediate MVP needs)
+       
+       - **CHECKPOINT: Consult Elder Brain for Each Skill**
+         - Before invoking skill-creator for each skill:
+           1. Identify domains/technologies this skill will work with
+              - Example: "firebase-deployer" → Firebase, deployment
+           2. Check Elder Brain for related knowledge:
+              ```powershell
+              grep -r "Firebase" experience-vault/
+              grep -r "deployment" experience-vault/
+              ```
+           3. If gotcha files found:
+              - Load content from experience-vault/
+              - Prepare Elder Brain context for skill-creator
+           4. If no gotchas found:
+              - Note this for later research during task execution
+       
        - For each of the 3 initial skills:
          - Show progress: "Creating [skill-name]..."
-         - Invoke skill-creator with context from research findings:
-           - Role/pattern/need from Step 5 analysis
-           - Relevant gotchas research from Step 5.4.1 (if skill involves specific technology)
-           - Example: "firebase-deployer skill should include gotchas about permission propagation, environment config, console prerequisites"
-         - Let skill-creator run its wizard with gotchas knowledge
+         - Invoke skill-creator with THREE knowledge sources:
+           1. **Research findings** from Step 5 analysis (role/pattern/need)
+           2. **Gotchas research** from Step 5.4.1 (project-specific research)
+           3. **Elder Brain knowledge** (cross-project domain wisdom)
+         - Example context for skill-creator:
+           ```
+           Skill: firebase-deployer
+           
+           From Research (Step 5):
+           - Role: DevOps automation
+           - Pattern: Deployment with retry logic
+           
+           From Gotchas Research (Step 5.4.1):
+           - Firebase CLI auth expires after 7 days
+           - Large deployments may timeout
+           
+           From Elder Brain (experience-vault/):
+           - Firebase Auth needs Console click-through first
+           - Environment variables need both dashboard + .env.production
+           - Authorized domains must be configured for production
+           ```
+         - Let skill-creator run its wizard with all three knowledge sources
          - **Store created skills in `.github/skills/`** (CLI-discoverable location)
          - **Track in session-state.json**: Add skill name to `skillsCreated` array
          - **VALIDATE SKILL** (CRITICAL - prevents task execution failures):
@@ -2633,6 +2682,52 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      **Estimated Timeline**: [From vision document]
      ```
    
+   **Step 7.3.5: CHECKPOINT - Review Roadmap Against Elder Brain**
+   - **Purpose**: Surface known pitfalls for the tech stack BEFORE task execution begins
+   
+   - For EACH technology/platform identified in roadmap tasks:
+     1. Extract tech mentions from task descriptions
+        - Example: "Set up Firebase Auth" → Firebase, Authentication
+        - Example: "Deploy to Vercel" → Vercel, Deployment
+        - Example: "Create React components" → React, UI
+     
+     2. Check Elder Brain for relevant gotchas:
+        ```powershell
+        grep -ri "Firebase" experience-vault/
+        grep -ri "Vercel" experience-vault/
+        grep -ri "React" experience-vault/
+        ```
+     
+     3. For EACH gotcha file found:
+        - Load content from experience-vault/
+        - Identify which roadmap tasks are affected
+        - Add defensive note to those task descriptions
+     
+     4. Example transformation:
+        ```markdown
+        # BEFORE Elder Brain check:
+        - [ ] Task 003: Set up Firebase Authentication
+        
+        # AFTER Elder Brain check:
+        - [ ] Task 003: Set up Firebase Authentication
+             ⚠️ Prerequisites: Enable Auth in Firebase Console first
+             📚 See: experience-vault/platforms/firebase-auth.md
+        ```
+     
+     5. If NO Elder Brain knowledge exists for a technology:
+        - Note this in Project Brain for future contribution
+        - Expect to research during task execution
+   
+   - Display:
+     ```
+     🧙 Elder Brain consulted
+     - [X] technologies checked
+     - [Y] known gotchas surfaced in roadmap
+     ```
+   
+   - Update roadmap.md with Elder Brain references
+   - This makes pitfalls visible BEFORE tasks start, not during failures
+   
    **Step 7.4: Display Roadmap Summary** (No Approval Required)
      - Show roadmap structure to user (for transparency, not approval)
      - Display:
@@ -2856,6 +2951,43 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
       - What creative/visual/narrative elements does this task involve?
       - What domain knowledge is required?
       - What style/tone preferences apply?
+      - **What technologies/platforms does this task use?** (for Elder Brain check)
+   
+   2.5. **CHECKPOINT: Consult Elder Brain for This Task**
+      - Extract technology/platform mentions from task:
+        - Task title: "Set up Firebase Auth" → Firebase, Authentication
+        - Task description: "Deploy React app to Vercel" → React, Vercel, Deployment
+        - Task deliverables: "PostgreSQL schema" → PostgreSQL, Database
+      
+      - For EACH technology identified:
+        ```powershell
+        grep -ri "[technology]" experience-vault/
+        ```
+      
+      - If gotcha files found:
+        1. Load content from experience-vault/
+        2. Display relevant gotchas to Mother Brain (for awareness)
+        3. Apply defensive patterns automatically during execution
+        
+        Example:
+        ```
+        🧙 Elder Brain: Firebase Auth
+        
+        Known gotchas for this task:
+        - Firebase Auth requires Console click-through before API works
+        - Environment variables need both dashboard + .env.production
+        - Authorized domains required for production
+        
+        Applying defensive patterns:
+        ✓ Will verify Console setup before implementing
+        ✓ Will check for .env.production file
+        ✓ Will add domain authorization to task checklist
+        ```
+      
+      - If NO gotchas found:
+        - Note: "No Elder Brain knowledge for [technology]"
+        - Expect to research during execution if issues arise
+        - Plan to contribute back to Elder Brain after task
    
    3. **Skill Sufficiency Check** (CRITICAL):
       - List existing skills in `.github/skills/`
@@ -3010,7 +3142,40 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
 ### 9A. **Error Detection & Self-Healing**
    - When errors occur during task execution:
    
-   - **Document the Issue**:
+   - **FIRST: Check Elder Brain for Known Solution**:
+     1. Extract technology/error context from error message:
+        - "Firebase permission denied" → Firebase, permissions
+        - "Vercel build failed: env var undefined" → Vercel, environment variables
+        - "PowerShell directory exists error" → PowerShell, Windows
+     
+     2. Search Elder Brain for this pattern:
+        ```powershell
+        grep -ri "[technology]" experience-vault/
+        grep -ri "[error keyword]" experience-vault/
+        ```
+     
+     3. If matching gotcha found:
+        ```
+        🧙 Elder Brain: Known Issue Found
+        
+        Pattern: [gotcha title]
+        Location: experience-vault/[category]/[file].md
+        
+        Known Solution:
+        [Solution from Elder Brain]
+        
+        Applying fix...
+        ```
+        - Apply the documented solution immediately
+        - Skip root cause analysis (already known)
+        - Resume task execution
+        - DONE - no further steps needed
+     
+     4. If NO Elder Brain knowledge:
+        - Continue to root cause analysis below
+        - Plan to contribute solution to Elder Brain after fixing
+   
+   - **Document the Issue** (if NOT in Elder Brain):
      - What broke (error message, unexpected behavior)
      - What was being attempted
      - What the expected outcome was
@@ -3020,6 +3185,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - Was it a task definition issue? (unclear instructions)
      - Was it a Mother Brain issue? (missing step, wrong assumption)
      - Was it an environment issue? (dependencies, configuration)
+     - **Was it a known domain gotcha?** (technology-specific pattern)
    
    - **Log & Learn**:
      - Add entry to `docs/learning-log.md`:
@@ -3030,15 +3196,22 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
        **Root Cause**: [Why it happened]
        **Fix Applied**: [How it was resolved]
        **Prevention**: [What to update to prevent recurrence]
+       **Elder Brain Contribution**: [If domain gotcha, note for contribution]
        ```
    
    - **Self-Correction**:
      - Use `ask_user` with choices:
+       - "Contribute to Elder Brain (domain gotcha)"
        - "Update [affected skill] to prevent this"
        - "Update Mother Brain process"
        - "Update task definition"
        - "Just fix it this time (one-off issue)"
      
+     - If "Contribute to Elder Brain":
+       - Invoke Child Brain to route the learning
+       - Child Brain will create Elder Brain entry
+       - Display: `🧙 Elder Brain will remember this`
+     
      - If updating skill/Mother Brain:
        - Jump to **Step 2A: Update Mother Brain** (if Mother Brain issue)
        - Or invoke skill-creator with "heal" mode (if skill issue)