agileflow 2.75.0 → 2.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.75.0",
+  "version": "2.76.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/agileflow-configure.js

@@ -23,7 +23,7 @@
  *   --detect                            Show current status
  *   --help                              Show help
  *
- * Features: sessionstart, precompact, archival, statusline, autoupdate
+ * Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, autoupdate
  */
 
 const fs = require('fs');
@@ -71,7 +71,8 @@ const VERSION = getVersion();
 const FEATURES = {
   sessionstart: { hook: 'SessionStart', script: 'agileflow-welcome.js', type: 'node' },
   precompact: { hook: 'PreCompact', script: 'precompact-context.sh', type: 'bash' },
-  // Note: Stop hook removed due to Claude Code reliability issues (see GitHub issues #6974, #11544)
+  ralphloop: { hook: 'Stop', script: 'ralph-loop.js', type: 'node' },
+  selfimprove: { hook: 'Stop', script: 'auto-self-improve.js', type: 'node' },
   archival: { script: 'archive-completed-stories.sh', requiresHook: 'sessionstart' },
   statusline: { script: 'agileflow-statusline.sh' },
   autoupdate: { metadataOnly: true }, // Stored in metadata.updates.autoUpdate
@@ -82,6 +83,8 @@ const ALL_SCRIPTS = {
   // Core feature scripts (linked to FEATURES)
   'agileflow-welcome.js': { feature: 'sessionstart', required: true },
   'precompact-context.sh': { feature: 'precompact', required: true },
+  'ralph-loop.js': { feature: 'ralphloop', required: true },
+  'auto-self-improve.js': { feature: 'selfimprove', required: true },
   'archive-completed-stories.sh': { feature: 'archival', required: true },
   'agileflow-statusline.sh': { feature: 'statusline', required: true },
 
@@ -119,25 +122,25 @@ const STATUSLINE_COMPONENTS = [
 
 const PROFILES = {
   full: {
-    description: 'All features enabled',
-    enable: ['sessionstart', 'precompact', 'archival', 'statusline'],
+    description: 'All features enabled (including experimental Stop hooks)',
+    enable: ['sessionstart', 'precompact', 'archival', 'statusline', 'ralphloop', 'selfimprove'],
     archivalDays: 30,
   },
   basic: {
     description: 'Essential hooks + archival (SessionStart + PreCompact + Archival)',
     enable: ['sessionstart', 'precompact', 'archival'],
-    disable: ['statusline'],
+    disable: ['statusline', 'ralphloop', 'selfimprove'],
     archivalDays: 30,
   },
   minimal: {
     description: 'SessionStart + archival only',
     enable: ['sessionstart', 'archival'],
-    disable: ['precompact', 'statusline'],
+    disable: ['precompact', 'statusline', 'ralphloop', 'selfimprove'],
     archivalDays: 30,
   },
   none: {
     description: 'Disable all AgileFlow features',
-    disable: ['sessionstart', 'precompact', 'archival', 'statusline'],
+    disable: ['sessionstart', 'precompact', 'archival', 'statusline', 'ralphloop', 'selfimprove'],
   },
 };
 
@@ -208,6 +211,8 @@ function detectConfig() {
     features: {
       sessionstart: { enabled: false, valid: true, issues: [], version: null, outdated: false },
       precompact: { enabled: false, valid: true, issues: [], version: null, outdated: false },
+      ralphloop: { enabled: false, valid: true, issues: [], version: null, outdated: false },
+      selfimprove: { enabled: false, valid: true, issues: [], version: null, outdated: false },
       archival: { enabled: false, threshold: null, version: null, outdated: false },
       statusline: { enabled: false, valid: true, issues: [], version: null, outdated: false },
     },
@@ -276,7 +281,23 @@ function detectConfig() {
           }
         }
 
-        // Note: Stop hook removed due to reliability issues
+        // Stop hooks (ralphloop and selfimprove)
+        if (settings.hooks.Stop) {
+          if (Array.isArray(settings.hooks.Stop) && settings.hooks.Stop.length > 0) {
+            const hook = settings.hooks.Stop[0];
+            if (hook.matcher !== undefined && hook.hooks) {
+              // Check for each Stop hook feature
+              for (const h of hook.hooks) {
+                if (h.command?.includes('ralph-loop')) {
+                  status.features.ralphloop.enabled = true;
+                }
+                if (h.command?.includes('auto-self-improve')) {
+                  status.features.selfimprove.enabled = true;
+                }
+              }
+            }
+          }
+        }
       }
 
       // StatusLine
@@ -370,6 +391,8 @@ function printStatus(status) {
 
   printFeature('sessionstart', 'SessionStart Hook');
   printFeature('precompact', 'PreCompact Hook');
+  printFeature('ralphloop', 'RalphLoop (Stop)');
+  printFeature('selfimprove', 'SelfImprove (Stop)');
 
   const arch = status.features.archival;
   log(
@@ -417,9 +440,9 @@ function migrateSettings() {
 
   let migrated = false;
 
-  // Migrate hooks (Stop hook removed due to reliability issues)
+  // Migrate hooks to new format
   if (settings.hooks) {
-    ['SessionStart', 'PreCompact', 'UserPromptSubmit'].forEach(hookName => {
+    ['SessionStart', 'PreCompact', 'UserPromptSubmit', 'Stop'].forEach(hookName => {
       const hook = settings.hooks[hookName];
       if (!hook) return;
 
@@ -556,16 +579,46 @@ function enableFeature(feature, options = {}) {
       return false;
     }
 
-    // Configure hook
-    const command = config.type === 'node' ? `node ${scriptPath}` : `bash ${scriptPath}`;
+    // Use absolute path so hooks work from any subdirectory
+    const absoluteScriptPath = path.join(process.cwd(), scriptPath);
+
+    // Stop hooks use error suppression to avoid blocking Claude
+    const isStoHook = config.hook === 'Stop';
+    const command = config.type === 'node'
+      ? `node ${absoluteScriptPath}${isStoHook ? ' 2>/dev/null || true' : ''}`
+      : `bash ${absoluteScriptPath}${isStoHook ? ' 2>/dev/null || true' : ''}`;
+
+    if (isStoHook) {
+      // Stop hooks stack - add to existing hooks instead of replacing
+      if (!settings.hooks.Stop) {
+        settings.hooks.Stop = [{ matcher: '', hooks: [] }];
+      } else if (!Array.isArray(settings.hooks.Stop) || settings.hooks.Stop.length === 0) {
+        settings.hooks.Stop = [{ matcher: '', hooks: [] }];
+      } else if (!settings.hooks.Stop[0].hooks) {
+        settings.hooks.Stop[0].hooks = [];
+      }
+
+      // Check if this script is already added
+      const hasHook = settings.hooks.Stop[0].hooks.some(h =>
+        h.command?.includes(config.script)
+      );
 
-    settings.hooks[config.hook] = [
-      {
-        matcher: '',
-        hooks: [{ type: 'command', command }],
-      },
-    ];
-    success(`${config.hook} hook enabled (${config.script})`);
+      if (!hasHook) {
+        settings.hooks.Stop[0].hooks.push({ type: 'command', command });
+        success(`Stop hook added (${config.script})`);
+      } else {
+        info(`${feature} already enabled`);
+      }
+    } else {
+      // Other hooks (SessionStart, PreCompact) replace entirely
+      settings.hooks[config.hook] = [
+        {
+          matcher: '',
+          hooks: [{ type: 'command', command }],
+        },
+      ];
+      success(`${config.hook} hook enabled (${config.script})`);
+    }
   }
 
   // Handle archival
@@ -579,7 +632,8 @@ function enableFeature(feature, options = {}) {
       return false;
     }
 
-    // Add to SessionStart hook
+    // Use absolute path so hooks work from any subdirectory
+    const absoluteScriptPath = path.join(process.cwd(), scriptPath);
     if (settings.hooks.SessionStart?.[0]?.hooks) {
       const hasArchival = settings.hooks.SessionStart[0].hooks.some(h =>
         h.command?.includes('archive-completed-stories')
@@ -587,7 +641,7 @@ function enableFeature(feature, options = {}) {
       if (!hasArchival) {
         settings.hooks.SessionStart[0].hooks.push({
           type: 'command',
-          command: `bash ${scriptPath} --quiet`,
+          command: `bash ${absoluteScriptPath} --quiet`,
         });
       }
     }
@@ -607,9 +661,11 @@ function enableFeature(feature, options = {}) {
       return false;
     }
 
+    // Use absolute path so hooks work from any subdirectory
+    const absoluteScriptPath = path.join(process.cwd(), scriptPath);
     settings.statusLine = {
       type: 'command',
-      command: `bash ${scriptPath}`,
+      command: `bash ${absoluteScriptPath}`,
       padding: 0,
     };
     success('Status line enabled');
@@ -656,8 +712,28 @@ function disableFeature(feature) {
 
   // Disable hook
   if (config.hook && settings.hooks?.[config.hook]) {
-    delete settings.hooks[config.hook];
-    success(`${config.hook} hook disabled`);
+    if (config.hook === 'Stop') {
+      // Stop hooks stack - remove only this script, not the entire hook
+      if (settings.hooks.Stop?.[0]?.hooks) {
+        const before = settings.hooks.Stop[0].hooks.length;
+        settings.hooks.Stop[0].hooks = settings.hooks.Stop[0].hooks.filter(
+          h => !h.command?.includes(config.script)
+        );
+        const after = settings.hooks.Stop[0].hooks.length;
+
+        if (before > after) {
+          success(`Stop hook removed (${config.script})`);
+        }
+
+        // If no more Stop hooks, remove the entire Stop hook
+        if (settings.hooks.Stop[0].hooks.length === 0) {
+          delete settings.hooks.Stop;
+        }
+      }
+    } else {
+      delete settings.hooks[config.hook];
+      success(`${config.hook} hook disabled`);
+    }
   }
 
   // Disable archival
@@ -1142,8 +1218,8 @@ ${c.cyan}Usage:${c.reset}
   node .agileflow/scripts/agileflow-configure.js [options]
 
 ${c.cyan}Profiles:${c.reset}
-  --profile=full      All features (hooks, archival, statusline)
-  --profile=basic     SessionStart + PreCompact + archival
+  --profile=full      All features (hooks, Stop hooks, archival, statusline)
+  --profile=basic     SessionStart + PreCompact + archival (no Stop hooks)
   --profile=minimal   SessionStart + archival only
   --profile=none      Disable all AgileFlow features
 
@@ -1151,7 +1227,9 @@ ${c.cyan}Feature Control:${c.reset}
   --enable=<list>     Enable features (comma-separated)
   --disable=<list>    Disable features (comma-separated)
 
-  Features: sessionstart, precompact, archival, statusline
+  Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline
+
+  Stop hooks (ralphloop, selfimprove) run when Claude completes/pauses
 
 ${c.cyan}Statusline Components:${c.reset}
   --show=<list>       Show statusline components (comma-separated)

package/scripts/agileflow-welcome.js

@@ -433,6 +433,85 @@ async function runAutoUpdate(rootDir) {
   }
 }
 
+function validateExpertise(rootDir) {
+  const result = { total: 0, passed: 0, warnings: 0, failed: 0, issues: [] };
+
+  // Find experts directory
+  let expertsDir = path.join(rootDir, '.agileflow', 'experts');
+  if (!fs.existsSync(expertsDir)) {
+    expertsDir = path.join(rootDir, 'packages', 'cli', 'src', 'core', 'experts');
+  }
+  if (!fs.existsSync(expertsDir)) {
+    return result; // No experts directory found
+  }
+
+  const STALE_DAYS = 30;
+  const MAX_LINES = 200;
+
+  try {
+    const domains = fs.readdirSync(expertsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && d.name !== 'templates')
+      .map(d => d.name);
+
+    for (const domain of domains) {
+      const filePath = path.join(expertsDir, domain, 'expertise.yaml');
+      if (!fs.existsSync(filePath)) {
+        result.total++;
+        result.failed++;
+        result.issues.push(`${domain}: missing file`);
+        continue;
+      }
+
+      result.total++;
+      const content = fs.readFileSync(filePath, 'utf8');
+      const lines = content.split('\n');
+      let status = 'pass';
+      let issue = '';
+
+      // Check required fields (use multiline flag)
+      const hasVersion = /^version:/m.test(content);
+      const hasDomain = /^domain:/m.test(content);
+      const hasLastUpdated = /^last_updated:/m.test(content);
+
+      if (!hasVersion || !hasDomain || !hasLastUpdated) {
+        status = 'fail';
+        issue = 'missing required fields';
+      }
+
+      // Check staleness
+      const lastUpdatedMatch = content.match(/^last_updated:\s*['"]?(\d{4}-\d{2}-\d{2})/m);
+      if (lastUpdatedMatch && status !== 'fail') {
+        const lastDate = new Date(lastUpdatedMatch[1]);
+        const daysSince = Math.floor((Date.now() - lastDate.getTime()) / (1000 * 60 * 60 * 24));
+        if (daysSince > STALE_DAYS) {
+          status = 'warn';
+          issue = `stale (${daysSince}d)`;
+        }
+      }
+
+      // Check file size
+      if (lines.length > MAX_LINES && status === 'pass') {
+        status = 'warn';
+        issue = `large (${lines.length} lines)`;
+      }
+
+      if (status === 'pass') {
+        result.passed++;
+      } else if (status === 'warn') {
+        result.warnings++;
+        result.issues.push(`${domain}: ${issue}`);
+      } else {
+        result.failed++;
+        result.issues.push(`${domain}: ${issue}`);
+      }
+    }
+  } catch (e) {
+    // Silently fail
+  }
+
+  return result;
+}
+
 function getFeatureVersions(rootDir) {
   const result = {
     hooks: { version: null, outdated: false },
@@ -505,7 +584,7 @@ function truncate(str, maxLen, suffix = '..') {
   return str.substring(0, cutIndex) + suffix;
 }
 
-function formatTable(info, archival, session, precompact, parallelSessions, updateInfo = {}) {
+function formatTable(info, archival, session, precompact, parallelSessions, updateInfo = {}, expertise = {}) {
   const W = 58; // inner width
   const R = W - 24; // right column width (34 chars)
   const lines = [];
@@ -662,6 +741,19 @@ function formatTable(info, archival, session, precompact, parallelSessions, upda
     }
   }
 
+  // Agent expertise validation (only show if issues exist)
+  if (expertise && expertise.total > 0) {
+    if (expertise.failed > 0) {
+      const expertStr = `❌ ${expertise.failed} failed, ${expertise.warnings} warnings`;
+      lines.push(row('Expertise', expertStr, c.dim, c.red));
+    } else if (expertise.warnings > 0) {
+      const expertStr = `⚠️ ${expertise.warnings} warnings (${expertise.passed} ok)`;
+      lines.push(row('Expertise', expertStr, c.dim, c.yellow));
+    } else {
+      lines.push(row('Expertise', `✓ ${expertise.total} valid`, c.dim, c.green));
+    }
+  }
+
   lines.push(divider());
 
   // Current story (if any) - row() auto-truncates
@@ -694,6 +786,7 @@ async function main() {
   const session = clearActiveCommands(rootDir);
   const precompact = checkPreCompact(rootDir);
   const parallelSessions = checkParallelSessions(rootDir);
+  const expertise = validateExpertise(rootDir);
 
   // Check for updates (async, cached)
   let updateInfo = {};
@@ -717,7 +810,7 @@ async function main() {
     // Update check failed - continue without it
   }
 
-  console.log(formatTable(info, archival, session, precompact, parallelSessions, updateInfo));
+  console.log(formatTable(info, archival, session, precompact, parallelSessions, updateInfo, expertise));
 
   // Show warning and tip if other sessions are active
   if (parallelSessions.otherActive > 0) {

package/scripts/auto-self-improve.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+
+/**
+ * auto-self-improve.js - Automatic Agent Expertise Updates
+ *
+ * This script runs as a Stop hook and automatically updates agent
+ * expertise files based on work performed during the session.
+ *
+ * How it works:
+ * 1. Reads session-state.json to find which agent was active
+ * 2. Analyzes git diff to see what changed
+ * 3. Detects patterns, new files, significant changes
+ * 4. Generates a learning entry
+ * 5. Appends to the agent's expertise.yaml
+ *
+ * Usage (as Stop hook):
+ *   node scripts/auto-self-improve.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ANSI colors
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  brand: '\x1b[38;2;232;104;58m',
+};
+
+// Agents that have expertise files
+const AGENTS_WITH_EXPERTISE = [
+  'accessibility', 'adr-writer', 'analytics', 'api', 'ci', 'compliance',
+  'database', 'datamigration', 'design', 'devops', 'documentation',
+  'epic-planner', 'integrations', 'mentor', 'mobile', 'monitoring',
+  'performance', 'product', 'qa', 'readme-updater', 'refactor',
+  'research', 'security', 'testing', 'ui'
+];
+
+// File patterns that suggest domain expertise
+const DOMAIN_PATTERNS = {
+  'database': [/schema/, /migration/, /\.sql$/, /prisma/, /drizzle/, /sequelize/],
+  'api': [/\/api\//, /controller/, /route/, /endpoint/, /graphql/],
+  'ui': [/component/, /\.tsx$/, /\.jsx$/, /styles/, /\.css$/, /\.scss$/],
+  'testing': [/\.test\./, /\.spec\./, /__tests__/, /jest/, /vitest/],
+  'security': [/auth/, /password/, /token/, /jwt/, /oauth/, /permission/],
+  'ci': [/\.github\/workflows/, /\.gitlab-ci/, /dockerfile/i, /docker-compose/],
+  'documentation': [/\.md$/, /readme/i, /docs\//, /jsdoc/],
+  'performance': [/cache/, /optimize/, /performance/, /benchmark/],
+  'devops': [/deploy/, /kubernetes/, /k8s/, /terraform/, /ansible/],
+};
+
+// Find project root
+function getProjectRoot() {
+  let dir = process.cwd();
+  while (!fs.existsSync(path.join(dir, '.agileflow')) && dir !== '/') {
+    dir = path.dirname(dir);
+  }
+  return dir !== '/' ? dir : process.cwd();
+}
+
+// Read session state
+function getSessionState(rootDir) {
+  const statePath = path.join(rootDir, 'docs/09-agents/session-state.json');
+  try {
+    if (fs.existsSync(statePath)) {
+      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    }
+  } catch (e) {}
+  return {};
+}
+
+// Get git diff summary
+function getGitDiff(rootDir) {
+  try {
+    // Get list of changed files (staged and unstaged)
+    const diffFiles = execSync('git diff --name-only HEAD 2>/dev/null || git diff --name-only', {
+      cwd: rootDir,
+      encoding: 'utf8',
+    }).trim().split('\n').filter(Boolean);
+
+    // Get staged files
+    const stagedFiles = execSync('git diff --cached --name-only 2>/dev/null', {
+      cwd: rootDir,
+      encoding: 'utf8',
+    }).trim().split('\n').filter(Boolean);
+
+    // Get untracked files
+    const untrackedFiles = execSync('git ls-files --others --exclude-standard 2>/dev/null', {
+      cwd: rootDir,
+      encoding: 'utf8',
+    }).trim().split('\n').filter(Boolean);
+
+    // Combine all
+    const allFiles = [...new Set([...diffFiles, ...stagedFiles, ...untrackedFiles])];
+
+    // Get diff stats
+    let additions = 0;
+    let deletions = 0;
+    try {
+      const stats = execSync('git diff --shortstat HEAD 2>/dev/null || echo ""', {
+        cwd: rootDir,
+        encoding: 'utf8',
+      });
+      const addMatch = stats.match(/(\d+) insertion/);
+      const delMatch = stats.match(/(\d+) deletion/);
+      if (addMatch) additions = parseInt(addMatch[1]);
+      if (delMatch) deletions = parseInt(delMatch[1]);
+    } catch (e) {}
+
+    return {
+      files: allFiles,
+      additions,
+      deletions,
+      hasChanges: allFiles.length > 0,
+    };
+  } catch (e) {
+    return { files: [], additions: 0, deletions: 0, hasChanges: false };
+  }
+}
+
+// Detect which domain the changes relate to
+function detectDomain(files) {
+  const domainScores = {};
+
+  for (const file of files) {
+    for (const [domain, patterns] of Object.entries(DOMAIN_PATTERNS)) {
+      for (const pattern of patterns) {
+        if (pattern.test(file.toLowerCase())) {
+          domainScores[domain] = (domainScores[domain] || 0) + 1;
+        }
+      }
+    }
+  }
+
+  // Return domain with highest score
+  const sorted = Object.entries(domainScores).sort((a, b) => b[1] - a[1]);
+  return sorted.length > 0 ? sorted[0][0] : null;
+}
+
+// Generate learning summary from changes
+function generateLearningSummary(diff, activeAgent) {
+  const { files, additions, deletions } = diff;
+
+  if (files.length === 0) return null;
+
+  // Categorize files
+  const newFiles = files.filter(f => !f.includes('/'));
+  const testFiles = files.filter(f => /\.(test|spec)\.[jt]sx?$/.test(f));
+  const configFiles = files.filter(f => /\.(json|yaml|yml|toml|config\.)/.test(f));
+  const codeFiles = files.filter(f => /\.[jt]sx?$/.test(f) && !testFiles.includes(f));
+
+  // Build summary
+  const parts = [];
+
+  if (codeFiles.length > 0) {
+    const dirs = [...new Set(codeFiles.map(f => path.dirname(f)))];
+    parts.push(`Modified ${codeFiles.length} code file(s) in: ${dirs.slice(0, 3).join(', ')}`);
+  }
+
+  if (testFiles.length > 0) {
+    parts.push(`Updated ${testFiles.length} test file(s)`);
+  }
+
+  if (configFiles.length > 0) {
+    parts.push(`Changed config: ${configFiles.slice(0, 2).join(', ')}`);
+  }
+
+  if (additions > 50 || deletions > 50) {
+    parts.push(`Significant changes: +${additions}/-${deletions} lines`);
+  }
+
+  return parts.length > 0 ? parts.join('. ') : null;
+}
+
+// Find expertise file for agent
+function getExpertisePath(rootDir, agent) {
+  // Try installed location first
+  const installedPath = path.join(rootDir, '.agileflow', 'experts', agent, 'expertise.yaml');
+  if (fs.existsSync(installedPath)) return installedPath;
+
+  // Try source location
+  const sourcePath = path.join(rootDir, 'packages', 'cli', 'src', 'core', 'experts', agent, 'expertise.yaml');
+  if (fs.existsSync(sourcePath)) return sourcePath;
+
+  return null;
+}
+
+// Append learning to expertise file
+function appendLearning(expertisePath, learning) {
+  try {
+    let content = fs.readFileSync(expertisePath, 'utf8');
+
+    // Find the learnings section
+    const learningsMatch = content.match(/^learnings:\s*$/m);
+
+    if (!learningsMatch) {
+      // No learnings section, add it at the end
+      content += `\n\nlearnings:\n${learning}`;
+    } else {
+      // Find where to insert (after "learnings:" line)
+      const insertPos = learningsMatch.index + learningsMatch[0].length;
+      content = content.slice(0, insertPos) + '\n' + learning + content.slice(insertPos);
+    }
+
+    fs.writeFileSync(expertisePath, content);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+// Format learning as YAML
+function formatLearning(summary, files, detectedDomain) {
+  const date = new Date().toISOString().split('T')[0];
+  const topFiles = files.slice(0, 5).map(f => `      - ${f}`).join('\n');
+
+  return `  - date: "${date}"
+    auto_generated: true
+    context: "Session work - ${detectedDomain || 'general'} domain"
+    insight: "${summary.replace(/"/g, '\\"')}"
+    files_touched:
+${topFiles}`;
+}
+
+// Main function
+function main() {
+  const rootDir = getProjectRoot();
+  const state = getSessionState(rootDir);
+  const diff = getGitDiff(rootDir);
+
+  // Check if there were any changes
+  if (!diff.hasChanges) {
+    return; // Silent exit - no changes to learn from
+  }
+
+  // Detect which agent was active
+  let activeAgent = null;
+
+  // Check session state for active command
+  if (state.active_command?.name) {
+    const name = state.active_command.name.replace('agileflow-', '');
+    if (AGENTS_WITH_EXPERTISE.includes(name)) {
+      activeAgent = name;
+    }
+  }
+
+  // If no agent from session, detect from file changes
+  if (!activeAgent) {
+    activeAgent = detectDomain(diff.files);
+  }
+
+  // If still no agent, skip
+  if (!activeAgent || !AGENTS_WITH_EXPERTISE.includes(activeAgent)) {
+    return; // Silent exit - can't determine which agent to update
+  }
+
+  // Find expertise file
+  const expertisePath = getExpertisePath(rootDir, activeAgent);
+  if (!expertisePath) {
+    return; // Silent exit - no expertise file found
+  }
+
+  // Generate learning summary
+  const summary = generateLearningSummary(diff, activeAgent);
+  if (!summary) {
+    return; // Silent exit - no meaningful summary
+  }
+
+  // Format and append learning
+  const learningYaml = formatLearning(summary, diff.files, activeAgent);
+  const success = appendLearning(expertisePath, learningYaml);
+
+  if (success) {
+    console.log('');
+    console.log(`${c.green}✓ Auto-learned:${c.reset} ${c.dim}${activeAgent}${c.reset}`);
+    console.log(`${c.dim}  ${summary}${c.reset}`);
+    console.log(`${c.dim}  → Updated ${path.basename(path.dirname(expertisePath))}/expertise.yaml${c.reset}`);
+    console.log('');
+  }
+}
+
+// Run if executed directly
+if (require.main === module) {
+  try {
+    main();
+  } catch (e) {
+    // Silent fail - don't break the workflow
+    if (process.env.DEBUG) {
+      console.error('auto-self-improve error:', e.message);
+    }
+  }
+}
+
+module.exports = { main, detectDomain, generateLearningSummary };