moflo 4.6.10 → 4.6.12

package/.claude/helpers/hook-handler.cjs

@@ -145,6 +145,19 @@ const handlers = {
     try {
       var projectDir = path.resolve(path.dirname(helpersDir), '..');
       var cp = require('child_process');
+      var pidFile = path.join(projectDir, '.claude-flow', 'background-pids.json');
+
+      // Kill stale background processes from previous sessions
+      try {
+        if (fs.existsSync(pidFile)) {
+          var stalePids = JSON.parse(fs.readFileSync(pidFile, 'utf-8'));
+          for (var i = 0; i < stalePids.length; i++) {
+            try { process.kill(stalePids[i].pid, 0); /* test if alive */ } catch (e) { continue; }
+            try { process.kill(stalePids[i].pid, 'SIGTERM'); } catch (e) { /* already gone */ }
+          }
+          fs.unlinkSync(pidFile);
+        }
+      } catch (e) { /* non-fatal: best-effort cleanup */ }
 
       // Read moflo.yaml auto_index flags (default: both true)
       var autoGuidance = true;
@@ -183,26 +196,33 @@ const handlers = {
         return null;
       }
 
-      function spawnBackground(script, extraArgs) {
+      // Track PIDs of background processes so next session can clean them up
+      var trackedPids = [];
+
+      function spawnBackground(script, label, extraArgs) {
         var args = [script].concat(extraArgs || []);
-        cp.spawn('node', args, {
+        var child = cp.spawn('node', args, {
           stdio: 'ignore',
           cwd: projectDir,
           detached: true,
           windowsHide: true
-        }).unref();
+        });
+        if (child.pid) {
+          trackedPids.push({ pid: child.pid, script: label, startedAt: new Date().toISOString() });
+        }
+        child.unref();
       }
 
       // 1. Index guidance docs (with embeddings for semantic search)
       if (autoGuidance) {
         var guidanceScript = findMofloScript('index-guidance.mjs');
-        if (guidanceScript) spawnBackground(guidanceScript);
+        if (guidanceScript) spawnBackground(guidanceScript, 'index-guidance');
       }
 
       // 2. Generate code map (structural index of source files)
       if (autoCodeMap) {
         var codeMapScript = findMofloScript('generate-code-map.mjs');
-        if (codeMapScript) spawnBackground(codeMapScript);
+        if (codeMapScript) spawnBackground(codeMapScript, 'generate-code-map');
       }
 
       // 3. Start learning service (pattern research on codebase)
@@ -218,7 +238,16 @@ const handlers = {
         var nmLearn = path.join(projectDir, 'node_modules', 'moflo', '.claude', 'helpers', 'learning-service.mjs');
         if (fs.existsSync(nmLearn)) learnScript = nmLearn;
       }
-      if (learnScript) spawnBackground(learnScript);
+      if (learnScript) spawnBackground(learnScript, 'learning-service');
+
+      // Persist tracked PIDs for cleanup on next session start
+      if (trackedPids.length > 0) {
+        try {
+          var pidDir = path.dirname(pidFile);
+          if (!fs.existsSync(pidDir)) fs.mkdirSync(pidDir, { recursive: true });
+          fs.writeFileSync(pidFile, JSON.stringify(trackedPids));
+        } catch (e) { /* non-fatal */ }
+      }
 
     } catch (e) { /* non-fatal: session-start indexing is best-effort */ }
   },

package/.claude/helpers/statusline.cjs

@@ -458,12 +458,13 @@ function getHooksStatus() {
   return { enabled, total };
 }
 
-// AgentDB stats (pure stat calls)
+// AgentDB stats — queries real count from sqlite when possible, falls back to file size estimate
 function getAgentDBStats() {
   let vectorCount = 0;
   let dbSizeKB = 0;
   let namespaces = 0;
   let hasHnsw = false;
+  let dbPath = null;
 
   const dbFiles = [
     path.join(CWD, '.swarm', 'memory.db'),
@@ -476,31 +477,25 @@ function getAgentDBStats() {
     const stat = safeStat(f);
     if (stat) {
       dbSizeKB = stat.size / 1024;
-      vectorCount = Math.floor(dbSizeKB / 2);
-      namespaces = 1;
+      dbPath = f;
       break;
     }
   }
 
-  if (vectorCount === 0) {
-    const dbDirs = [
-      path.join(CWD, '.claude-flow', 'agentdb'),
-      path.join(CWD, '.swarm', 'agentdb'),
-      path.join(CWD, '.agentdb'),
-    ];
-    for (const dir of dbDirs) {
+  // Try to get real count from sqlite (fast — single COUNT query)
+  if (dbPath) {
+    const countOutput = safeExec(`node -e "const S=require('sql.js');const f=require('fs');S().then(Q=>{const d=new Q.Database(f.readFileSync('${dbPath.replace(/\\/g, '/')}'));const s=d.prepare('SELECT COUNT(*) as c FROM memory_entries WHERE status=\\"active\\" AND embedding IS NOT NULL');s.step();console.log(JSON.stringify(s.getAsObject()));s.free();const n=d.prepare('SELECT COUNT(DISTINCT namespace) as n FROM memory_entries WHERE status=\\"active\\"');n.step();console.log(JSON.stringify(n.getAsObject()));n.free();d.close();})"`, 3000);
+    if (countOutput) {
       try {
-        if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
-          const files = fs.readdirSync(dir);
-          namespaces = files.filter(f => f.endsWith('.db') || f.endsWith('.sqlite')).length;
-          for (const file of files) {
-            const stat = safeStat(path.join(dir, file));
-            if (stat?.isFile()) dbSizeKB += stat.size / 1024;
-          }
-          vectorCount = Math.floor(dbSizeKB / 2);
-          break;
-        }
-      } catch { /* ignore */ }
+        const lines = countOutput.trim().split('\n');
+        vectorCount = JSON.parse(lines[0]).c || 0;
+        namespaces = lines[1] ? JSON.parse(lines[1]).n || 0 : 0;
+      } catch { /* fall back to estimate */ }
+    }
+    // Fallback to file size estimate if query failed
+    if (vectorCount === 0) {
+      vectorCount = Math.floor(dbSizeKB / 2);
+      namespaces = 1;
     }
   }
 
@@ -509,10 +504,8 @@ function getAgentDBStats() {
     path.join(CWD, '.claude-flow', 'hnsw.index'),
   ];
   for (const p of hnswPaths) {
-    const stat = safeStat(p);
-    if (stat) {
+    if (safeStat(p)) {
       hasHnsw = true;
-      vectorCount = Math.max(vectorCount, Math.floor(stat.size / 512));
       break;
     }
   }

package/.claude/settings.json

@@ -168,7 +168,7 @@
     "pr": "\ud83e\udd16 Generated with [claude-flow](https://github.com/eric-cielo/moflo)"
   },
   "claudeFlow": {
-    "version": "3.5.2",
+    "version": "4.6.12",
     "enabled": true,
     "modelPreferences": {
       "default": "claude-opus-4-6",

package/.claude/workflow-state.json

@@ -0,0 +1,9 @@
+{
+  "tasksCreated": false,
+  "taskCount": 0,
+  "memorySearched": false,
+  "memoryRequired": true,
+  "interactionCount": 10,
+  "sessionStart": null,
+  "lastBlockedAt": "2026-03-20T20:34:44.738Z"
+}

package/README.md

@@ -257,6 +257,10 @@ auto_index:
   guidance: true                     # Auto-index docs on session start
   code_map: true                     # Auto-index code on session start
 
+mcp:
+  tool_defer: true                   # Defer 150+ tool schemas; loaded on demand via ToolSearch
+  auto_start: false                  # Auto-start MCP server on session begin
+
 hooks:
   pre_edit: true                     # Track file edits for learning
   post_edit: true                    # Record edit outcomes
@@ -291,6 +295,12 @@ status_line:
   show_mcp: true
 ```
 
+### Tool Deferral
+
+By default, `tool_defer` is `true`. MoFlo exposes 150+ MCP tools — loading all their schemas at conversation start consumes significant context. With deferral enabled, only tool **names** are listed at startup (compact), and full schemas are fetched on demand via `ToolSearch` when actually needed. Hooks and CLI commands continue to work normally since they call the daemon directly, not through MCP tool schemas.
+
+Set `tool_defer: false` if you want all tool schemas available immediately (useful for offline/air-gapped environments where `ToolSearch` may not work).
+
 ### Model Routing
 
 By default, MoFlo uses **static model preferences** — each agent role uses the model specified in `models:`. This is predictable and gives you full control.

package/bin/hooks.mjs

@@ -0,0 +1,515 @@
+#!/usr/bin/env node
+/**
+ * Cross-platform Claude Code hook runner
+ * Works on Windows (cmd/powershell) and Linux/WSL (bash)
+ *
+ * Usage: node .claude/scripts/hooks.mjs <hook-type> [args...]
+ *
+ * Hook types:
+ *   pre-edit --file <path>
+ *   post-edit --file <path> --success <bool>
+ *   pre-command --command <cmd>
+ *   post-command --command <cmd> --success <bool>
+ *   pre-task --description <desc>
+ *   post-task --task-id <id> --success <bool>
+ *   session-start
+ *   session-restore --session-id <id>
+ *   route --task <prompt>
+ *   index-guidance [--file <path>] [--force]
+ *   daemon-start
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, appendFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = resolve(__dirname, '../..');
+const logFile = resolve(projectRoot, '.swarm/hooks.log');
+
+// Parse command line args
+const args = process.argv.slice(2);
+const hookType = args[0];
+
+// Simple log function - writes to .swarm/hooks.log
+function log(level, message) {
+  const timestamp = new Date().toISOString();
+  const line = `[${timestamp}] [${level.toUpperCase()}] [${hookType || 'unknown'}] ${message}\n`;
+
+  // Always log errors to stderr so they're visible in Claude
+  if (level === 'error') {
+    console.error(`[hook:${hookType}] ${message}`);
+  }
+
+  // Also append to log file for history
+  try {
+    appendFileSync(logFile, line);
+  } catch {
+    // Can't write log - that's fine, don't fail
+  }
+}
+
+// Helper to get arg value
+function getArg(name) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx !== -1 && args[idx + 1]) {
+    return args[idx + 1];
+  }
+  // Also check environment variables (Claude sets these)
+  const envName = `TOOL_INPUT_${name}`.replace(/-/g, '_');
+  return process.env[envName] || process.env[name.toUpperCase()] || null;
+}
+
+// Helper to check if arg/flag exists
+function hasArg(name) {
+  return args.includes(`--${name}`);
+}
+
+// Get the local CLI path (preferred - no network/extraction overhead)
+function getLocalCliPath() {
+  const localCli = resolve(projectRoot, 'node_modules/moflo/src/@claude-flow/cli/bin/cli.js');
+  return existsSync(localCli) ? localCli : null;
+}
+
+// Check if running on Windows
+const isWindows = process.platform === 'win32';
+
+// Run a command and return promise with exit code
+function runCommand(cmd, cmdArgs, options = {}) {
+  return new Promise((resolve) => {
+    let stderr = '';
+
+    // Use windowsHide: true directly - no PowerShell wrapper needed
+    // The wrapper can actually cause MORE flashes as PowerShell starts
+    const proc = spawn(cmd, cmdArgs, {
+      stdio: options.silent ? ['ignore', 'ignore', 'pipe'] : 'inherit',
+      shell: false,
+      cwd: projectRoot,
+      env: { ...process.env, ...options.env },
+      detached: options.background || false,
+      windowsHide: true  // This is sufficient on Windows when shell: false
+    });
+
+    // Capture stderr even in silent mode
+    if (proc.stderr) {
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+    }
+
+    proc.on('close', (code) => {
+      if (code !== 0 && stderr) {
+        log('error', `Command failed (exit ${code}): ${cmd} ${cmdArgs.join(' ')}`);
+        if (stderr.trim()) {
+          log('error', `  stderr: ${stderr.trim().substring(0, 200)}`);
+        }
+      }
+      resolve(code || 0);
+    });
+
+    proc.on('error', (err) => {
+      log('error', `Command error: ${cmd} - ${err.message}`);
+      resolve(1);
+    });
+  });
+}
+
+// Show Windows toast notification (works on native Windows and WSL)
+async function showWindowsToast(title, message) {
+  // PowerShell script to show toast notification
+  const psScript = `
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$text = $template.GetElementsByTagName('text')
+$text.Item(0).AppendChild($template.CreateTextNode('${title.replace(/'/g, "''")}')) | Out-Null
+$text.Item(1).AppendChild($template.CreateTextNode('${message.replace(/'/g, "''")}')) | Out-Null
+$toast = [Windows.UI.Notifications.ToastNotification]::new($template)
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show($toast)
+`.trim();
+
+  // Encode script as base64 for -EncodedCommand (avoids shell escaping issues)
+  const encodedScript = Buffer.from(psScript, 'utf16le').toString('base64');
+
+  try {
+    // Detect environment and use appropriate PowerShell command
+    const isWSL = process.platform === 'linux' && existsSync('/proc/version') &&
+      (await import('fs')).readFileSync('/proc/version', 'utf-8').toLowerCase().includes('microsoft');
+
+    if (process.platform === 'win32') {
+      // Native Windows - use powershell with encoded command (avoids cmd.exe escaping issues)
+      await runCommand('powershell', ['-NoProfile', '-WindowStyle', 'Hidden', '-EncodedCommand', encodedScript], { silent: true });
+      log('debug', 'Toast notification sent via PowerShell');
+    } else if (isWSL) {
+      // WSL - use powershell.exe to call Windows PowerShell
+      await runCommand('powershell.exe', ['-NoProfile', '-WindowStyle', 'Hidden', '-EncodedCommand', encodedScript], { silent: true });
+      log('debug', 'Toast notification sent via powershell.exe (WSL)');
+    } else {
+      // Linux/Mac - no Windows toast available, just log
+      log('debug', 'Windows toast not available on this platform');
+    }
+  } catch (err) {
+    // Toast notifications are nice-to-have, don't fail the hook
+    log('debug', `Toast notification failed: ${err.message}`);
+  }
+}
+
+// Run claude-flow CLI command using local installation
+async function runClaudeFlow(subcommand, cliArgs = []) {
+  const localCli = getLocalCliPath();
+
+  if (localCli) {
+    // Use local CLI (fastest, no network/extraction)
+    const fullArgs = [localCli, subcommand, ...cliArgs];
+    const exitCode = await runCommand('node', fullArgs, { silent: true });
+
+    if (exitCode !== 0) {
+      log('warn', `claude-flow ${subcommand} exited with code ${exitCode}`);
+    }
+
+    return exitCode;
+  } else {
+    log('warn', 'Local CLI not found. Install with: npm install @claude-flow/cli');
+    return 1;
+  }
+}
+
+// Main hook dispatcher
+async function main() {
+  if (!hookType) {
+    console.error('Usage: node hooks.mjs <hook-type> [args...]');
+    process.exit(1);
+  }
+
+  try {
+    switch (hookType) {
+      case 'pre-edit': {
+        const file = getArg('file') || process.env.TOOL_INPUT_file_path;
+        if (file) {
+          await runClaudeFlow('hooks', ['pre-edit', '--file', file]);
+        }
+        break;
+      }
+
+      case 'post-edit': {
+        const file = getArg('file') || process.env.TOOL_INPUT_file_path;
+        const success = getArg('success') || process.env.TOOL_SUCCESS || 'true';
+        if (file) {
+          await runClaudeFlow('hooks', ['post-edit', '--file', file, '--success', success]);
+
+          // Check if this is a guidance file that needs indexing (run in background)
+          if (file.includes('.claude/guidance/') || file.includes('.claude/skills/cl/')) {
+            runIndexGuidanceBackground(file);
+          }
+        }
+        break;
+      }
+
+      case 'pre-command': {
+        const command = getArg('command') || process.env.TOOL_INPUT_command;
+        if (command) {
+          await runClaudeFlow('hooks', ['pre-command', '--command', command]);
+        }
+        break;
+      }
+
+      case 'post-command': {
+        const command = getArg('command') || process.env.TOOL_INPUT_command;
+        const success = getArg('success') || process.env.TOOL_SUCCESS || 'true';
+        if (command) {
+          await runClaudeFlow('hooks', ['post-command', '--command', command, '--success', success]);
+        }
+        break;
+      }
+
+      case 'pre-task': {
+        const description = getArg('description') || process.env.TOOL_INPUT_prompt;
+        if (description) {
+          const taskId = `task-${Date.now()}`;
+          await runClaudeFlow('hooks', ['pre-task', '--task-id', taskId, '--description', description]);
+        }
+        break;
+      }
+
+      case 'pre-research': {
+        // Memory-first gate: remind to search memory before exploring codebase
+        // This fires on Glob/Grep to catch research-style queries
+        const pattern = process.env.TOOL_INPUT_pattern || getArg('pattern');
+        const query = process.env.TOOL_INPUT_query || getArg('query');
+        const searchTerm = pattern || query;
+
+        // Only remind if this looks like a research query (not a specific path lookup)
+        if (searchTerm && !searchTerm.includes('/') && !searchTerm.match(/\.(ts|tsx|js|json|md)$/)) {
+          console.log('[MEMORY GATE] Did you search memory first? Run: memory search --query "[topic]" --namespace guidance');
+        }
+        break;
+      }
+
+      case 'post-task': {
+        const taskId = getArg('task-id') || process.env.TOOL_RESULT_agent_id;
+        const success = getArg('success') || process.env.TOOL_SUCCESS || 'true';
+        if (taskId) {
+          await runClaudeFlow('hooks', ['post-task', '--task-id', taskId, '--success', success]);
+        }
+        break;
+      }
+
+      case 'session-start': {
+        // All startup tasks run in background (non-blocking)
+        // Start daemon quietly in background
+        runDaemonStartBackground();
+        // Index guidance files in background
+        runIndexGuidanceBackground();
+        // Generate structural code map in background
+        runCodeMapBackground();
+        // Run pretrain in background to extract patterns from repository
+        runBackgroundPretrain();
+        // Force HNSW rebuild to ensure all processes use identical fresh index
+        // This fixes agent search result mismatches (0.61 vs 0.81 similarity)
+        runHNSWRebuildBackground();
+        // Neural patterns now loaded by moflo core routing — no external patching.
+        break;
+      }
+
+      case 'session-restore': {
+        const sessionId = getArg('session-id') || process.env.SESSION_ID;
+        if (sessionId) {
+          await runClaudeFlow('hooks', ['session-restore', '--session-id', sessionId]);
+        }
+        break;
+      }
+
+      case 'route': {
+        const task = getArg('task') || process.env.PROMPT;
+        if (task) {
+          // Check for /cl command and output gate reminder
+          if (task.includes('/cl') || task.match(/^cl\s/)) {
+            const hasHelpFlag = task.includes('-h') || task.includes('--help');
+            const hasNakedFlag = task.includes('-n') || task.includes('--naked');
+
+            if (!hasHelpFlag && !hasNakedFlag) {
+              // Output visible reminder - this appears in Claude's context
+              console.log('[SWARM GATE] /cl detected. Required order: TaskList() → TaskCreate() → swarm init → Task(run_in_background)');
+              console.log('[SWARM GATE] Do NOT call GitHub/Grep/Read until tasks are created.');
+            }
+          }
+          await runClaudeFlow('hooks', ['route', '--task', task]);
+        }
+        break;
+      }
+
+      case 'index-guidance': {
+        const file = getArg('file');
+        await runIndexGuidance(file);
+        break;
+      }
+
+      case 'daemon-start': {
+        await runClaudeFlow('daemon', ['start', '--quiet']);
+        break;
+      }
+
+      case 'session-end': {
+        // Run ReasoningBank and MicroLoRA training in background on session end
+        log('info', 'Session ending - starting background learning...');
+
+        // Run session-end hook (persists state)
+        await runClaudeFlow('hooks', ['session-end', '--persist-state', 'true']);
+
+        // Start background training (non-blocking)
+        runBackgroundTraining();
+        break;
+      }
+
+
+      case 'semantic-search': {
+        // Semantic search using embeddings
+        const query = getArg('query') || args[1];
+        const searchLimit = getArg('limit') || '5';
+        const threshold = getArg('threshold') || '0.3';
+        const searchScript = resolve(projectRoot, '.claude/scripts/semantic-search.mjs');
+
+        if (query && existsSync(searchScript)) {
+          const searchArgs = [searchScript, query, '--limit', searchLimit, '--threshold', threshold];
+          if (getArg('namespace')) searchArgs.push('--namespace', getArg('namespace'));
+          if (hasArg('json')) searchArgs.push('--json');
+          // semantic-search.mjs uses better-sqlite3
+          await runCommand('node', searchArgs, { silent: false });
+        } else if (!query) {
+          console.log('Usage: node .claude/scripts/hooks.mjs semantic-search --query "your query"');
+        } else {
+          log('error', 'Semantic search script not found');
+        }
+        break;
+      }
+
+      case 'notification': {
+        // Handle notification hook - show Windows toast if possible
+        const message = process.env.NOTIFICATION_MESSAGE || getArg('message') || 'Claude Code needs your attention';
+        const title = getArg('title') || 'Claude Code';
+        await showWindowsToast(title, message);
+        log('info', 'Notification hook triggered');
+        break;
+      }
+
+      default:
+        // Unknown hook type - just pass through to claude-flow
+        log('info', `Passing through unknown hook: ${hookType}`);
+        await runClaudeFlow('hooks', args);
+    }
+  } catch (err) {
+    // Log the error but don't block Claude
+    log('error', `Hook exception: ${err.message}`);
+    process.exit(0);
+  }
+
+  process.exit(0);
+}
+
+// Run the guidance indexer (blocking - used for specific file updates)
+async function runIndexGuidance(specificFile = null) {
+  const indexScript = resolve(projectRoot, '.claude/scripts/index-guidance.mjs');
+
+  if (existsSync(indexScript)) {
+    const indexArgs = specificFile ? ['--file', specificFile] : [];
+    if (hasArg('force')) indexArgs.push('--force');
+    // index-guidance.mjs uses better-sqlite3
+    const code = await runCommand('node', [indexScript, ...indexArgs], { silent: true });
+    if (code !== 0) {
+      log('warn', `index-guidance.mjs exited with code ${code}`);
+    }
+    return code;
+  }
+
+  log('warn', 'Guidance indexer not found');
+  return 0;
+}
+
+// Spawn a background process that's truly windowless on Windows
+function spawnWindowless(cmd, args, description) {
+  const proc = spawn(cmd, args, {
+    cwd: projectRoot,
+    stdio: 'ignore',
+    detached: true,
+    shell: false,
+    windowsHide: true
+  });
+
+  proc.unref();
+  log('info', `Started ${description} (PID: ${proc.pid})`);
+  return proc;
+}
+
+// Resolve a moflo npm bin script, falling back to local .claude/scripts/ copy
+function resolveBinOrLocal(binName, localScript) {
+  // 1. npm bin from moflo package (always up to date with published version)
+  const mofloScript = resolve(projectRoot, 'node_modules/moflo/bin', localScript);
+  if (existsSync(mofloScript)) return mofloScript;
+
+  // 2. npm bin from .bin (symlinked by npm install)
+  const npmBin = resolve(projectRoot, 'node_modules/.bin', binName);
+  if (existsSync(npmBin)) return npmBin;
+
+  // 3. Local .claude/scripts/ copy (may be stale but better than nothing)
+  const localPath = resolve(projectRoot, '.claude/scripts', localScript);
+  if (existsSync(localPath)) return localPath;
+
+  return null;
+}
+
+// Run the guidance indexer in background (non-blocking - used for session start and file changes)
+function runIndexGuidanceBackground(specificFile = null) {
+  const indexScript = resolveBinOrLocal('flo-index', 'index-guidance.mjs');
+
+  if (!indexScript) {
+    log('warn', 'Guidance indexer not found (checked npm bin + .claude/scripts/)');
+    return;
+  }
+
+  const indexArgs = [indexScript];
+  if (specificFile) indexArgs.push('--file', specificFile);
+
+  const desc = specificFile ? `background indexing file: ${specificFile}` : 'background indexing (full)';
+  spawnWindowless('node', indexArgs, desc);
+}
+
+// Run structural code map generator in background (non-blocking)
+function runCodeMapBackground() {
+  const codeMapScript = resolveBinOrLocal('flo-codemap', 'generate-code-map.mjs');
+
+  if (!codeMapScript) {
+    log('warn', 'Code map generator not found (checked npm bin + .claude/scripts/)');
+    return;
+  }
+
+  spawnWindowless('node', [codeMapScript], 'background code map generation');
+}
+
+// Run ReasoningBank + MicroLoRA training + EWC++ consolidation in background (non-blocking)
+function runBackgroundTraining() {
+  const localCli = getLocalCliPath();
+  if (!localCli) {
+    log('warn', 'Local CLI not found, skipping background training');
+    return;
+  }
+
+  // Pattern types to train with MicroLoRA
+  const patternTypes = ['coordination', 'routing', 'debugging'];
+
+  for (const ptype of patternTypes) {
+    spawnWindowless('node', [localCli, 'neural', 'train', '--pattern-type', ptype, '--epochs', '2'], `MicroLoRA training: ${ptype}`);
+  }
+
+  // Run pretrain to update ReasoningBank
+  spawnWindowless('node', [localCli, 'hooks', 'pretrain'], 'ReasoningBank pretrain');
+
+  // Run EWC++ memory consolidation (prevents catastrophic forgetting)
+  spawnWindowless('node', [localCli, 'hooks', 'worker', 'dispatch', '--trigger', 'consolidate', '--background'], 'EWC++ consolidation');
+
+  // Run neural optimize (Int8 quantization, memory compression)
+  spawnWindowless('node', [localCli, 'neural', 'optimize'], 'neural optimize');
+}
+
+// Run daemon start in background (non-blocking)
+function runDaemonStartBackground() {
+  const localCli = getLocalCliPath();
+  if (!localCli) {
+    log('warn', 'Local CLI not found, skipping daemon start');
+    return;
+  }
+
+  spawnWindowless('node', [localCli, 'daemon', 'start', '--quiet'], 'daemon');
+}
+
+// Run pretrain in background on session start (non-blocking)
+function runBackgroundPretrain() {
+  const localCli = getLocalCliPath();
+  if (!localCli) {
+    log('warn', 'Local CLI not found, skipping background pretrain');
+    return;
+  }
+
+  spawnWindowless('node', [localCli, 'hooks', 'pretrain'], 'background pretrain');
+}
+
+// Force HNSW rebuild in background to ensure all processes use identical fresh index
+// This fixes the issue where spawned agents return different search results than CLI/MCP
+function runHNSWRebuildBackground() {
+  const localCli = getLocalCliPath();
+  if (!localCli) {
+    log('warn', 'Local CLI not found, skipping HNSW rebuild');
+    return;
+  }
+
+  spawnWindowless('node', [localCli, 'memory', 'rebuild', '--force'], 'HNSW rebuild');
+}
+
+// Neural pattern application — now handled by moflo core routing (learned patterns
+// loaded from routing-outcomes.json by hooks-tools.ts getSemanticRouter).
+// No external patch script needed.
+
+main().catch((err) => {
+  log('error', `Unhandled exception: ${err.message}`);
+  process.exit(0);
+});

package/bin/session-start-launcher.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Fast session-start launcher — single hook that replaces all SessionStart entries.
+ *
+ * Spawns background tasks via spawn(detached + unref) and exits immediately.
+ *
+ * Invoked by: node .claude/scripts/session-start-launcher.mjs
+ */
+
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '../..');
+
+// ── 1. Helper: fire-and-forget a background process ─────────────────────────
+function fireAndForget(cmd, args, label) {
+  try {
+    const proc = spawn(cmd, args, {
+      cwd: projectRoot,
+      stdio: 'ignore',     // Don't hold stdio pipes open
+      detached: true,       // New process group
+      shell: false,
+      windowsHide: true     // No console popup on Windows
+    });
+    proc.unref();           // Let this process exit without waiting
+  } catch {
+    // If spawn fails (e.g. node not found), don't block startup
+  }
+}
+
+// ── 2. Reset workflow state for new session ──────────────────────────────────
+import { writeFileSync, mkdirSync } from 'fs';
+const stateDir = resolve(projectRoot, '.claude');
+const stateFile = resolve(stateDir, 'workflow-state.json');
+try {
+  if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
+  writeFileSync(stateFile, JSON.stringify({
+    tasksCreated: false,
+    taskCount: 0,
+    memorySearched: false,
+    sessionStart: new Date().toISOString()
+  }, null, 2));
+} catch {
+  // Non-fatal - workflow gate will use defaults
+}
+
+// ── 3. Spawn background tasks ───────────────────────────────────────────────
+const localCli = resolve(projectRoot, 'node_modules/moflo/src/@claude-flow/cli/bin/cli.js');
+const hasLocalCli = existsSync(localCli);
+
+// hooks.mjs session-start (daemon, indexer, pretrain, HNSW, neural patterns)
+const hooksScript = resolve(projectRoot, '.claude/scripts/hooks.mjs');
+if (existsSync(hooksScript)) {
+  fireAndForget('node', [hooksScript, 'session-start'], 'hooks session-start');
+}
+
+// Patches are now baked into moflo@4.0.0 source — no runtime patching needed.
+
+// ── 4. Done — exit immediately ──────────────────────────────────────────────
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.6.10",
+  "version": "4.6.12",
   "description": "MoFlo — AI agent orchestration for Claude Code. Forked from ruflo/claude-flow with patches applied to source, plus feature-level orchestration.",
   "main": "dist/index.js",
   "type": "module",
@@ -56,7 +56,8 @@
     "security:audit": "npm audit --audit-level high",
     "security:fix": "npm audit fix",
     "security:test": "npm run test:security",
-    "moflo:security": "npm run security:audit && npm run security:test"
+    "moflo:security": "npm run security:audit && npm run security:test",
+    "version": "node -e \"const v=require('./package.json').version;const p='src/@claude-flow/cli/package.json';const j=JSON.parse(require('fs').readFileSync(p));j.version=v;require('fs').writeFileSync(p,JSON.stringify(j,null,2)+'\\n')\" && git add src/@claude-flow/cli/package.json"
   },
   "dependencies": {
     "@ruvector/learning-wasm": "^0.1.29",

package/src/@claude-flow/cli/dist/src/init/mcp-generator.js

@@ -29,6 +29,9 @@ export function generateMCPConfig(options) {
     const npmEnv = {
         npm_config_update_notifier: 'false',
     };
+    // When toolDefer is true, emit "deferred" so Claude Code loads schemas on
+    // demand via ToolSearch instead of putting 150+ schemas into context at startup.
+    const deferProps = config.toolDefer ? { toolDefer: 'deferred' } : {};
     // Claude Flow MCP server (core)
     if (config.claudeFlow) {
         mcpServers['claude-flow'] = createMCPServerEntry(['@claude-flow/cli@latest', 'mcp', 'start'], {
@@ -38,15 +41,15 @@ export function generateMCPConfig(options) {
             CLAUDE_FLOW_TOPOLOGY: options.runtime.topology,
             CLAUDE_FLOW_MAX_AGENTS: String(options.runtime.maxAgents),
             CLAUDE_FLOW_MEMORY_BACKEND: options.runtime.memoryBackend,
-        }, { autoStart: config.autoStart });
+        }, { autoStart: config.autoStart, ...deferProps });
     }
     // Ruv-Swarm MCP server (enhanced coordination)
     if (config.ruvSwarm) {
-        mcpServers['ruv-swarm'] = createMCPServerEntry(['ruv-swarm', 'mcp', 'start'], { ...npmEnv }, { optional: true });
+        mcpServers['ruv-swarm'] = createMCPServerEntry(['ruv-swarm', 'mcp', 'start'], { ...npmEnv }, { optional: true, ...deferProps });
     }
     // Flow Nexus MCP server (cloud features)
     if (config.flowNexus) {
-        mcpServers['flow-nexus'] = createMCPServerEntry(['flow-nexus@latest', 'mcp', 'start'], { ...npmEnv }, { optional: true, requiresAuth: true });
+        mcpServers['flow-nexus'] = createMCPServerEntry(['flow-nexus@latest', 'mcp', 'start'], { ...npmEnv }, { optional: true, requiresAuth: true, ...deferProps });
     }
     return { mcpServers };
 }

package/src/@claude-flow/cli/dist/src/init/moflo-init.js

@@ -20,9 +20,9 @@ import * as path from 'path';
 async function runWizard(root) {
     const { confirm, input } = await import('../prompt.js');
     // Detect project structure
-    const guidanceCandidates = ['.claude/guidance', 'docs/guides', 'docs'];
+    const guidanceCandidates = ['.claude/guidance', 'docs/guides', 'docs', 'architecture', 'adr', '.cursor/rules'];
     const detectedGuidance = guidanceCandidates.filter(d => fs.existsSync(path.join(root, d)));
-    const srcCandidates = ['src', 'packages', 'lib', 'app', 'apps', 'services'];
+    const srcCandidates = ['src', 'packages', 'lib', 'app', 'apps', 'services', 'server', 'client'];
     const detectedSrc = srcCandidates.filter(d => fs.existsSync(path.join(root, d)));
     // Ask questions
     const guidance = await confirm({
@@ -67,11 +67,11 @@ async function runWizard(root) {
  * Get default answers (--yes mode).
  */
 function defaultAnswers(root) {
-    const guidanceCandidates = ['.claude/guidance', 'docs/guides', 'docs'];
+    const guidanceCandidates = ['.claude/guidance', 'docs/guides', 'docs', 'architecture', 'adr', '.cursor/rules'];
     const guidanceDirs = guidanceCandidates.filter(d => fs.existsSync(path.join(root, d)));
     if (guidanceDirs.length === 0)
         guidanceDirs.push('.claude/guidance');
-    const srcCandidates = ['src', 'packages', 'lib', 'app', 'apps', 'services'];
+    const srcCandidates = ['src', 'packages', 'lib', 'app', 'apps', 'services', 'server', 'client'];
     const srcDirs = srcCandidates.filter(d => fs.existsSync(path.join(root, d)));
     if (srcDirs.length === 0)
         srcDirs.push('src');
@@ -180,15 +180,22 @@ hooks:
   session_restore: true        # Restore session state on start
   notification: true           # Hook into Claude Code notifications
 
+# MCP server options
+mcp:
+  tool_defer: deferred           # Defer 150+ tool schemas; loaded on demand via ToolSearch
+  auto_start: false              # Auto-start MCP server on session begin
+
 # Status line display (shown at bottom of Claude Code)
-# mode: "single-line" (concise, default) or "dashboard" (full multi-line)
+# mode: "compact" (default), "single-line", or "dashboard" (full multi-line)
 status_line:
   enabled: true
-  mode: single-line
+  mode: compact
   branding: "MoFlo V4"
   show_git: true
-  show_model: true
   show_session: true
+  show_swarm: true
+  show_agentdb: true
+  show_mcp: true
 
 # Model preferences (haiku, sonnet, opus)
 models:
@@ -401,419 +408,23 @@ function generateSkill(root, force) {
     if (!fs.existsSync(skillDir)) {
         fs.mkdirSync(skillDir, { recursive: true });
     }
-    const skillContent = `---
-name: flo
-description: MoFlo ticket workflow - analyze and execute GitHub issues
-arguments: "[options] <issue-number>"
----
-
-# /flo - MoFlo Ticket Workflow
-
-Research, enhance, and execute GitHub issues automatically.
-
-**Arguments:** $ARGUMENTS
-
-## Usage
-
-\`\`\`
-/flo <issue-number>                   # Full workflow with SWARM (default)
-/flo -e <issue-number>                # Enhance only: research and update ticket, then STOP
-/flo --enhance <issue-number>         # Same as -e
-/flo -r <issue-number>                # Research only: analyze issue, output findings
-/flo --research <issue-number>        # Same as -r
-\`\`\`
-
-Also available as \`/fl\` (shorthand alias).
-
-### Execution Mode (how work is done)
-
-\`\`\`
-/flo 123                              # SWARM mode (default) - multi-agent coordination
-/flo -sw 123                          # SWARM mode (explicit)
-/flo --swarm 123                      # Same as -sw
-/flo -hv 123                          # HIVE-MIND mode - consensus-based coordination
-/flo --hive 123                       # Same as -hv
-/flo -n 123                           # NAKED mode - single Claude, no agents
-/flo --naked 123                      # Same as -n
-\`\`\`
-
-### Epic Handling
-
-\`\`\`
-/flo 42                               # If #42 is an epic, processes all stories sequentially
-\`\`\`
-
-**Epic Detection:** Issues with \`epic\` label or containing \`## Stories\` / \`## Tasks\` sections are automatically detected as epics.
-
-**Sequential Processing:** When an epic is selected:
-1. List all child stories/tasks (from checklist or linked issues)
-2. Process each story **one at a time** in order
-3. Each story goes through the full workflow (research -> enhance -> implement -> test -> PR)
-4. After each story's PR is created, move to the next story
-5. Continue until all stories are complete
-
-### Combined Examples
-
-\`\`\`
-/flo 123                              # Swarm + full workflow (default) - includes ALL tests
-/flo 42                               # If #42 is epic, processes stories sequentially
-/flo -e 123                           # Swarm + enhance only (no implementation)
-/flo -hv -e 123                       # Hive-mind + enhance only
-/flo -n -r 123                        # Naked + research only
-/flo --swarm --enhance 123            # Explicit swarm + enhance only
-/flo -n 123                           # Naked + full workflow (still runs all tests)
-\`\`\`
-
-## SWARM IS MANDATORY BY DEFAULT
-
-Even if a task "looks simple", you MUST use swarm coordination unless
-the user explicitly passes -n/--naked. "Simple" is a trap. Tasks have
-hidden complexity. Swarm catches it.
-
-THE ONLY WAY TO SKIP SWARM: User passes -n or --naked explicitly.
-
-## COMPREHENSIVE TESTING REQUIREMENT
-
-ALL tests MUST pass BEFORE PR creation - NO EXCEPTIONS.
-- Unit Tests: MANDATORY for all new/modified code
-- Integration Tests: MANDATORY for API endpoints and services
-- E2E Tests: MANDATORY for user-facing features
-PR CANNOT BE CREATED until all relevant tests pass.
-
-## Workflow Overview
-
-\`\`\`
-Research -> Enhance -> Execute -> Testing -> Simplify -> PR+Done
-
-Research:    Fetch issue, search memory, read guidance, find files
-Enhance:     Update GitHub issue with tech analysis, affected files, impl plan
-Execute:     Assign self, create branch, implement changes
-Testing:     Unit + Integration + E2E tests (ALL MUST PASS - gate)
-Simplify:    Run /simplify on changed code (gate - must run before PR)
-PR+Done:     Create PR, update issue status, store learnings
-\`\`\`
-
-### Workflow Gates
-
-| Gate | Requirement | Blocked Action |
-|------|-------------|----------------|
-| **Testing Gate** | Unit + Integration + E2E must pass | PR creation |
-| **Simplification Gate** | /simplify must run on changed files | PR creation |
-
-### Execution Mode (applies to all phases)
-
-| Mode | Description |
-|------|-------------|
-| **SWARM** (default) | Multi-agent via Task tool: researcher, coder, tester, reviewer |
-| **HIVE-MIND** (-hv) | Consensus-based coordination for architecture decisions |
-| **NAKED** (-n) | Single Claude, no agent spawning. Only when user explicitly requests. |
-
-## Phase 1: Research (-r or default first step)
-
-### 1.1 Fetch Issue Details
-\`\`\`bash
-gh issue view <issue-number> --json number,title,body,labels,state,assignees,comments,milestone
-\`\`\`
-
-### 1.2 Check Enhancement Status
-Look for \`## Implementation Plan\` marker in issue body.
-- **If present**: Issue already enhanced, skip to execute or confirm
-- **If absent**: Proceed with research and enhancement
-
-### 1.3 Search Memory FIRST
-ALWAYS search memory BEFORE reading guidance or docs files.
-Memory has file paths, context, and patterns - often all you need.
-Only read guidance files if memory search returns zero relevant results.
-
-\`\`\`bash
-npx flo memory search --query "<issue title keywords>" --namespace patterns
-npx flo memory search --query "<domain keywords>" --namespace guidance
-\`\`\`
-
-Or via MCP: \`mcp__claude-flow__memory_search\`
-
-### 1.4 Read Guidance Docs (ONLY if memory insufficient)
-**Only if memory search returned < 3 relevant results**, read guidance files:
-- Bug -> testing patterns, error handling
-- Feature -> domain model, architecture
-- UI -> frontend patterns, components
-
-### 1.5 Research Codebase
-Use Task tool with Explore agent to find:
-- Affected files and their current state
-- Related code and dependencies
-- Existing patterns to follow
-- Test coverage gaps
-
-## Phase 2: Enhance (-e includes research + enhancement)
-
-### 2.1 Build Enhancement
-Compile research into structured enhancement:
-
-**Technical Analysis** - Root cause (bugs) or approach (features), impact, risk factors
-
-**Affected Files** - Files to modify (with line numbers), new files, deletions
-
-**Implementation Plan** - Numbered steps with clear actions, dependencies, decision points
-
-**Test Plan** - Unit tests to add/update, integration tests needed, manual testing checklist
-
-**Estimates** - Complexity (Low/Medium/High), scope (# files, # new tests)
-
-### 2.2 Update GitHub Issue
-\`\`\`bash
-gh issue edit <issue-number> --body "<original body + Technical Analysis + Affected Files + Implementation Plan + Test Plan + Estimates>"
-\`\`\`
-
-### 2.3 Add Enhancement Comment
-\`\`\`bash
-gh issue comment <issue-number> --body "Issue enhanced with implementation plan. Ready for execution."
-\`\`\`
-
-## Phase 3: Execute (default, runs automatically after enhance)
-
-### 3.1 Assign Issue and Update Status
-\`\`\`bash
-gh issue edit <issue-number> --add-assignee @me
-gh issue edit <issue-number> --add-label "in-progress"
-\`\`\`
-
-### 3.2 Create Branch
-\`\`\`bash
-git checkout main && git pull origin main
-git checkout -b <type>/<issue-number>-<short-desc>
-\`\`\`
-Types: \`feature/\`, \`fix/\`, \`refactor/\`, \`docs/\`
-
-### 3.3 Implement
-Follow the implementation plan from the enhanced issue. No prompts - execute all steps.
-
-## Phase 4: Testing (MANDATORY GATE)
-
-This is NOT optional. ALL applicable test types must pass for the change type.
-WORKFLOW STOPS HERE until tests pass. No shortcuts. No exceptions.
-
-### 4.1 Write and Run Tests
-Write unit, integration, and E2E tests as appropriate for the change type.
-Use the project's existing test runner and patterns.
-
-### 4.2 Test Auto-Fix Loop
-If any tests fail, enter the auto-fix loop (max 3 retries OR 10 minutes):
-1. Run all tests
-2. If ALL pass -> proceed to simplification
-3. If ANY fail: analyze failure, fix test or implementation code, retry
-4. If retries exhausted -> STOP and report to user
-
-## Phase 4.5: Code Simplification (MANDATORY)
-
-The built-in /simplify command reviews ALL changed code for:
-- Reuse opportunities and code quality
-- Efficiency improvements
-- Consistency with existing codebase patterns
-- Preserves ALL functionality - no behavior changes
-
-If /simplify makes changes -> re-run tests to confirm nothing broke.
-If re-tests fail -> revert changes, proceed with original code.
-
-## Phase 5: Commit and PR (only after tests pass)
-
-### 5.1 Commit
-\`\`\`bash
-git add <specific files>
-git commit -m "type(scope): description
-
-Closes #<issue-number>
-
-Co-Authored-By: Claude <noreply@anthropic.com>"
-\`\`\`
-
-### 5.2 Create PR
-\`\`\`bash
-git push -u origin <branch-name>
-gh pr create --title "type(scope): description" --body "## Summary
-<brief description>
-
-## Changes
-<bullet list>
-
-## Testing
-- [x] Unit tests pass
-- [x] Integration tests pass
-- [x] E2E tests pass
-- [ ] Manual testing done
-
-Closes #<issue-number>"
-\`\`\`
-
-### 5.3 Update Issue Status
-\`\`\`bash
-gh issue edit <issue-number> --remove-label "in-progress" --add-label "ready-for-review"
-gh issue comment <issue-number> --body "PR created: <pr-url>"
-\`\`\`
-
-## Epic Handling
-
-### Detecting Epics
-
-An issue is an **epic** if:
-1. It has the \`epic\` label, OR
-2. Its body contains \`## Stories\` or \`## Tasks\` sections, OR
-3. It has linked child issues (via \`- [ ] #123\` checklist format)
-
-### Epic Processing Flow
-
-1. DETECT EPIC - Check labels, parse body for ## Stories / ## Tasks, extract issue references
-2. LIST ALL STORIES - Extract from checklist, order top-to-bottom as listed
-3. SEQUENTIAL PROCESSING - For each story: run full /flo workflow, wait for PR, update checklist
-4. COMPLETION - All stories have PRs, epic marked as ready-for-review
-
-ONE STORY AT A TIME - NO PARALLEL STORY EXECUTION.
-Each story must complete (PR created) before starting next.
-
-### Epic Detection Code
-
-\`\`\`javascript
-function isEpic(issue) {
-  if (issue.labels?.some(l => l.name === 'epic')) return true;
-  if (issue.body?.includes('## Stories') || issue.body?.includes('## Tasks')) return true;
-  const linkedIssuePattern = /- \\[[ x]\\] #\\d+/;
-  if (linkedIssuePattern.test(issue.body)) return true;
-  return false;
-}
-
-function extractStories(epicBody) {
-  const stories = [];
-  const pattern = /- \\[[ ]\\] #(\\d+)/g;
-  let match;
-  while ((match = pattern.exec(epicBody)) !== null) {
-    stories.push(parseInt(match[1]));
-  }
-  return stories;
-}
-\`\`\`
-
-## Parse Arguments
-
-\`\`\`javascript
-const args = "$ARGUMENTS".trim().split(/\\s+/);
-let workflowMode = "full";    // full, enhance, research
-let execMode = "swarm";       // swarm (default), hive, naked
-let issueNumber = null;
-
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-
-  // Workflow mode (what to do)
-  if (arg === "-e" || arg === "--enhance") {
-    workflowMode = "enhance";
-  } else if (arg === "-r" || arg === "--research") {
-    workflowMode = "research";
-  }
-
-  // Execution mode (how to do it)
-  else if (arg === "-sw" || arg === "--swarm") {
-    execMode = "swarm";
-  } else if (arg === "-hv" || arg === "--hive") {
-    execMode = "hive";
-  } else if (arg === "-n" || arg === "--naked") {
-    execMode = "naked";
-  }
-
-  // Issue number
-  else if (/^\\d+$/.test(arg)) {
-    issueNumber = arg;
-  }
-}
-
-if (!issueNumber) {
-  throw new Error("Issue number required. Usage: /flo <issue-number>");
-}
-
-// Log execution mode to prevent silent skipping
-console.log("Execution mode: " + execMode.toUpperCase());
-if (execMode === "swarm") {
-  console.log("SWARM MODE: Will spawn agents via Task tool. Do NOT skip this.");
-}
-console.log("TESTING: Unit + Integration + E2E tests REQUIRED before PR.");
-console.log("SIMPLIFY: /simplify command runs on changed code before PR.");
-\`\`\`
-
-## Execution Flow
-
-### Workflow Modes (what to do)
-
-| Mode | Command | Steps | Stops After |
-|------|---------|-------|-------------|
-| **Full** (default) | \`/flo 123\` | Research -> Enhance -> Implement -> Test -> Simplify -> PR | PR created |
-| **Epic** | \`/flo 42\` (epic) | For each story: Full workflow sequentially | All story PRs created |
-| **Enhance** | \`/flo -e 123\` | Research -> Enhance | Issue updated |
-| **Research** | \`/flo -r 123\` | Research | Findings output |
-
-### Execution Modes (how to do it)
-
-| Mode | Flag | Description | When to Use |
-|------|------|-------------|-------------|
-| **Swarm** (DEFAULT) | \`-sw\`, \`--swarm\` | Multi-agent via Task tool | Always, unless explicitly overridden |
-| **Hive-Mind** | \`-hv\`, \`--hive\` | Consensus-based coordination | Architecture decisions, tradeoffs |
-| **Naked** | \`-n\`, \`--naked\` | Single Claude, no agents | User explicitly wants simple mode |
-
-## Execution Mode Details
-
-### SWARM Mode (Default) - ALWAYS USE UNLESS TOLD OTHERWISE
-
-You MUST use the Task tool to spawn agents. No exceptions.
-
-**Swarm spawns these agents via Task tool:**
-- \`researcher\` - Analyzes issue, searches memory, finds patterns
-- \`coder\` - Implements changes following plan
-- \`tester\` - Writes and runs tests
-- \`/simplify\` - Built-in command that reviews changed code before PR
-- \`reviewer\` - Reviews code before PR
-
-**Swarm execution pattern:**
-\`\`\`javascript
-// 1. Create task list FIRST
-TaskCreate({ subject: "Research issue #123", ... })
-TaskCreate({ subject: "Implement changes", ... })
-TaskCreate({ subject: "Test implementation", ... })
-TaskCreate({ subject: "Run /simplify on changed files", ... })
-TaskCreate({ subject: "Review and PR", ... })
-
-// 2. Init swarm
-Bash("npx flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
-
-// 3. Spawn agents with Task tool (run_in_background: true)
-Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
-Task({ prompt: "...", subagent_type: "coder", run_in_background: true })
-
-// 4. Wait for results, synthesize, continue
-\`\`\`
-
-### HIVE-MIND Mode (-hv, --hive)
-
-Use for consensus-based decisions:
-- Architecture choices
-- Approach tradeoffs
-- Design decisions with multiple valid options
-
-### NAKED Mode (-n, --naked)
-
-**Only when user explicitly requests.** Single Claude execution without agents.
-- Still uses Task tool for tracking
-- Still creates tasks for visibility
-- Just doesn't spawn multiple agents
-
----
-
-**Full mode executes without prompts.** It will:
-1. Research the issue and codebase
-2. Enhance the GitHub issue with implementation plan
-3. Assign issue to self, add "in-progress" label
-4. Create branch, implement, test
-5. Run /simplify on changed code, re-test if changes made
-6. Commit, create PR, update issue status
-7. Store learnings
-`;
+    // Copy static SKILL.md from moflo package instead of generating it
+    let skillContent = '';
+    const staticSkillCandidates = [
+        // Installed via npm
+        path.join(root, 'node_modules', 'moflo', '.claude', 'skills', 'flo', 'SKILL.md'),
+        // Running from moflo repo itself
+        path.join(path.dirname(path.dirname(path.dirname(path.dirname(path.dirname(__dirname))))), '.claude', 'skills', 'flo', 'SKILL.md'),
+    ];
+    for (const candidate of staticSkillCandidates) {
+        if (fs.existsSync(candidate)) {
+            skillContent = fs.readFileSync(candidate, 'utf-8');
+            break;
+        }
+    }
+    if (!skillContent) {
+        return { name: '.claude/skills/flo/', status: 'failed', detail: 'Could not find SKILL.md in moflo package' };
+    }
     fs.writeFileSync(skillFile, skillContent, 'utf-8');
     // Create /fl alias (same content)
     if (!fs.existsSync(aliasDir)) {

package/src/@claude-flow/cli/dist/src/init/types.d.ts

@@ -156,6 +156,8 @@ export interface MCPConfig {
     autoStart: boolean;
     /** Server port */
     port: number;
+    /** Defer tool schema loading — schemas loaded on demand via ToolSearch */
+    toolDefer: boolean;
 }
 /**
  * Runtime configuration (.claude-flow/)

package/src/@claude-flow/cli/dist/src/init/types.js

@@ -118,6 +118,7 @@ export const DEFAULT_INIT_OPTIONS = {
         flowNexus: false,
         autoStart: false,
         port: 3000,
+        toolDefer: true,
     },
     runtime: {
         topology: 'hierarchical-mesh',
@@ -245,6 +246,7 @@ export const FULL_INIT_OPTIONS = {
         flowNexus: true,
         autoStart: false,
         port: 3000,
+        toolDefer: true,
     },
     embeddings: {
         enabled: true,

package/src/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moflo/cli",
-  "version": "4.6.10",
+  "version": "4.6.12",
   "type": "module",
   "description": "MoFlo CLI — AI agent orchestration with specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",