mother-brain 0.4.7 → 0.4.9

package/dist/cli.js

@@ -79,9 +79,26 @@ async function init(options = {}) {
   const agentsFile = path.join(cwd, "AGENTS.md");
   const sourceAgentsFile = path.join(packageRoot, "AGENTS.md");
   if (await fs.pathExists(sourceAgentsFile)) {
-    const agentsExists = await fs.pathExists(agentsFile);
-    if (!agentsExists || options.force) {
-      await fs.copy(sourceAgentsFile, agentsFile, { overwrite: true });
+    const mbContent = await fs.readFile(sourceAgentsFile, "utf-8");
+    const markerStart = "<!-- mother-brain:start -->";
+    const markerEnd = "<!-- mother-brain:end -->";
+    const wrappedContent = `${markerStart}
+${mbContent}
+${markerEnd}`;
+    if (await fs.pathExists(agentsFile)) {
+      const existing = await fs.readFile(agentsFile, "utf-8");
+      const startIdx = existing.indexOf(markerStart);
+      const endIdx = existing.indexOf(markerEnd);
+      if (startIdx !== -1 && endIdx !== -1) {
+        const merged = existing.substring(0, startIdx) + wrappedContent + existing.substring(endIdx + markerEnd.length);
+        await fs.writeFile(agentsFile, merged);
+        console.log(chalk.green("Updated Mother Brain section in AGENTS.md (user content preserved)"));
+      } else {
+        await fs.writeFile(agentsFile, existing.trimEnd() + "\n\n" + wrappedContent + "\n");
+        console.log(chalk.green("Appended Mother Brain rules to existing AGENTS.md"));
+      }
+    } else {
+      await fs.writeFile(agentsFile, wrappedContent + "\n");
       console.log(chalk.green("Created AGENTS.md (always-active rules for Codex/Copilot)"));
     }
   }
@@ -215,7 +232,26 @@ async function update() {
     const extractedAgentsFile = path2.join(tempDir, "package", "AGENTS.md");
     const agentsFile = path2.join(cwd, "AGENTS.md");
     if (await fs2.pathExists(extractedAgentsFile)) {
-      await fs2.copy(extractedAgentsFile, agentsFile, { overwrite: true });
+      const mbContent = await fs2.readFile(extractedAgentsFile, "utf-8");
+      const markerStart = "<!-- mother-brain:start -->";
+      const markerEnd = "<!-- mother-brain:end -->";
+      const wrappedContent = `${markerStart}
+${mbContent}
+${markerEnd}`;
+      if (await fs2.pathExists(agentsFile)) {
+        const existing = await fs2.readFile(agentsFile, "utf-8");
+        const startIdx = existing.indexOf(markerStart);
+        const endIdx = existing.indexOf(markerEnd);
+        if (startIdx !== -1 && endIdx !== -1) {
+          const merged = existing.substring(0, startIdx) + wrappedContent + existing.substring(endIdx + markerEnd.length);
+          await fs2.writeFile(agentsFile, merged);
+        } else {
+          await fs2.writeFile(agentsFile, existing.trimEnd() + "\n\n" + wrappedContent + "\n");
+        }
+      } else {
+        await fs2.writeFile(agentsFile, wrappedContent + "\n");
+      }
+      console.log(chalk2.green("  \u2713 Updated AGENTS.md (user content preserved)"));
     }
     await fs2.remove(tempDir);
     await fs2.writeJSON(versionFile, {
@@ -762,7 +798,7 @@ async function uninstall(options) {
 // src/cli.ts
 import { exec as exec3 } from "child_process";
 var program = new Command();
-var VERSION = "0.4.7";
+var VERSION = "0.4.9";
 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.4.7",
+  "version": "0.4.9",
   "description": "AI-powered project management framework for GitHub Copilot CLI",
   "type": "module",
   "main": "dist/index.js",

package/skills/child-brain/SKILL.md

@@ -53,6 +53,16 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 - Show "No changes" for layers that weren't updated
 - If user selects from menu options that reveal preferences, STILL note it
 
+### RULE 6: PROCESS-CALLOUT PREEMPTION
+- If the user flags workflow/process non-compliance, Child Brain MUST be the first response action
+- Do not allow menus, status narration, or execution updates before Child Brain activation
+- Treat process-callout feedback as a blocking interrupt, not a normal branch
+
+### RULE 7: MENU CONTINUITY ON RETURN
+- When returning control to Mother Brain, require explicit restoration of the numbered menu
+- Child Brain completion must always include resume target + menu continuity expectation
+- If completion would end without a menu, instruct caller to restore it immediately
+
 ---
 
 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.

package/skills/mother-brain/SKILL.md

@@ -198,6 +198,7 @@ Mother Brain transforms high-level visions into executable reality by:
 - **Wizard pattern for all interactions**: Use `ask_user` tool with numbered, selectable choices (2-3 options) for ALL user decisions—never ask freeform yes/no questions in text
 - **No question duplication**: When using `ask_user`, do NOT repeat the question in text output before calling the tool. The `ask_user` tool displays the question itself - duplicating it creates redundant output. Only include context/explanation text, not the question.
 - **User-driven evolution**: Provide "Send improvement" option that creates GitHub issues instead of direct changes
+- **Improvement propagation completeness**: When sending improvements upstream, include concrete updates across all impacted layers (Mother Brain, Child Brain, Skill Creator, Elder Brain) rather than learning-log entries alone. Each layer must receive actionable artifact changes.
 - **Spatial UI Clarification**: When implementing UI elements with positioning requirements, always ask user to describe placement relative to SPECIFIC existing elements before implementing (e.g., "inside player card" vs "above card" vs "overlay"). Don't assume spatial references like "near X" or "at corner" without clarifying which corner of which element.
 - **Visual Quality First**: When vision mentions visual/aesthetic/beauty/UI/design requirements, automatically trigger design system research and enforce consistency through skills. Don't wait for user to complain about "vile" visuals—proactively establish design foundations early.
 - **Branded Menu Styling**: Use simple header format (🧠 **MOTHER BRAIN**) for consistent identity. Avoid ASCII boxes and code fences which cause terminal styling issues.
@@ -208,6 +209,8 @@ Mother Brain transforms high-level visions into executable reality by:
 - **Research Before Questions Principle (MANDATORY)**: When a skill gap is identified, ALWAYS complete research BEFORE asking user about implementation approach. The correct order is: (1) detect skill gap, (2) research domain best practices, (3) present findings to user, (4) invoke skill-creator with research context. NEVER ask "how would you like to proceed?" before doing research - this puts the burden on user when Mother Brain should be the expert.
 - **Skill Creation Protocol (MANDATORY)**: Mother Brain MUST use the skill-creator skill to create ALL new skills. Never create skills inline or manually. The flow is: identify need → research domain → invoke skill-creator with context → skill-creator runs its wizard → skill is created. This ensures consistent skill quality and structure.
 - **Child Brain for ALL Feedback (MANDATORY)**: Child Brain is invoked not just for errors, but for ANY user feedback. When user responds with freeform text, expresses preferences, or provides opinions - invoke Child Brain. Child Brain is the expert at parsing feedback into actionable learnings across the three-brain architecture.
+- **Strategic Freeform Routing**: When a user provides major directional input during active delivery (vision shifts, design pivots, priority changes), immediately route through Child Brain and synchronize vision + roadmap before continuing UI/feature work. Don't let strategic input get lost mid-stream.
+- **Process Callout Preemption (BLOCKING)**: When a user flags workflow/process non-compliance (e.g., "you skipped a step", "why didn't you invoke Child Brain?"), this is a BLOCKING interrupt. Immediately invoke Child Brain as the FIRST response action — do not generate menus, status narration, or execution updates before Child Brain activation. Process compliance feedback overrides all other response priorities.
 - **Project Brain for Project-Specific Learning**: Each project has a `.mother-brain/project-brain.md` file that stores:
   - Style/tone preferences discovered during the project
   - Validation checks derived from past friction
@@ -228,6 +231,7 @@ Mother Brain transforms high-level visions into executable reality by:
 - **ASSET EXISTENCE GATE (BLOCKING)**: Before starting ANY task that requires visual assets (sprites, UI, tiles, animations), MUST verify those assets exist OR that a skill capable of creating them exists. "Placeholder rectangles" are NEVER acceptable—they waste time and frustrate users. If assets don't exist and can't be created, the task is BLOCKED. Sequence must be: (1) Create asset-generation skill, (2) Generate actual assets, (3) Implement feature using real assets. This applies to ALL projects with visual components.
 - **SKILL SUFFICIENCY CHECK (STEP 9 GATE)**: At Step 9 (before starting any task), MUST check: "Do I have the skills needed to create quality output for this task?" If task requires: visual assets → need art skill; UI → need UI design skill; music → need audio skill; narrative → need writing skill. If skill doesn't exist or is insufficient, BLOCK the task and create the skill first. Never proceed with "I'll use placeholders."
 - **BLOCKING WORKFLOW GATE**: The flow after task validation is: Step 10 (user confirms) → Step 10B (Post-Task Reflection - MANDATORY) → Step 11 (Next Action Menu). You CANNOT skip Step 10B. Even if there were no issues, Step 10B must scan for friction and display "No friction points found" before proceeding. If you find yourself about to show the "What would you like to do?" menu without having run Step 10B, STOP and run it first.
+- **Menu Continuity After Closeout Actions**: After commit, deploy, release, or any closeout operation, you MUST return to the numbered action menu. Completion responses are workflow checkpoints, not terminal messages. Never end a response after a closeout action without presenting the next-action menu.
 - **RESEARCH DEPTH PRINCIPLE (MANDATORY)**: Every new project MUST receive deep research before any implementation. "Deep research" means:
   - **Market Analysis**: Research existing competitors, what they do well/poorly, market gaps
   - **User Research**: What do users in this domain actually want? Pain points? Unmet needs?

package/skills/skill-creator/SKILL.md

@@ -32,6 +32,15 @@ allowed-tools: bash node view grep glob web_search ask_user powershell create ed
 - Do NOT run in background or parallel
 - The caller is waiting for you to finish
 
+### RULE 4: FOUR-LAYER PROPAGATION FOR HEAL LEARNINGS
+- When healing reveals framework-level improvements, Skill Creator MUST route updates across:
+  1. Mother Brain (process/orchestration)
+  2. Child Brain (learning orchestration behavior)
+  3. Skill Creator itself (generation/healing safeguards)
+  4. Elder Brain (`experience-vault/`) for domain/platform gotchas
+- Do not treat `learning-log.md` entries as sufficient completion on their own
+- Require concrete artifact updates (skills/docs) before declaring healing complete
+
 ---
 
 Use this skill when the user wants a new reusable capability, or when you notice repeated work that should be turned into a skill.
@@ -66,6 +75,7 @@ This skill is optimized for *minimal prompts, maximal clarity*, and iterative im
 - **Error handling**: Skills must handle failures gracefully with actionable error messages, not silent failures.
 - **TEST OUTPUT**: Skills MUST verify their output actually works before claiming success. Build it, run it, test it. Don't assume—prove.
 - **Continuous self-improvement**: When the Heal function fixes a skill execution issue, extract the general lesson and update skill-creator itself to prevent creating skills with similar flaws in the future.
+- **Propagation completeness**: For framework-impacting fixes, ensure updates are proposed/applied to all affected layers, not just local logs.
 - **Skill composition**: Skills should detect when they need expertise from another skill and invoke it using the `skill` tool. This allows skills to collaborate and combine their capabilities for better results.
 - **Guided external service setup**: When skills require external services (databases, APIs, cloud platforms), NEVER dump technical instructions on the user. Instead:
   - Explain in plain language WHAT the service does and WHY it's needed