@claude-flow/cli 3.0.2 → 3.1.0-alpha.10

package/dist/src/init/executor.js

@@ -9,12 +9,12 @@ import { dirname } from 'path';
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-import { detectPlatform } from './types.js';
+import { detectPlatform, DEFAULT_INIT_OPTIONS } from './types.js';
 import { generateSettingsJson } from './settings-generator.js';
 import { generateMCPJson } from './mcp-generator.js';
 import { generateStatuslineScript, generateStatuslineHook } from './statusline-generator.js';
 import { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, } from './helpers-generator.js';
-import { generateClaudeMd, generateMinimalClaudeMd } from './claudemd-generator.js';
+import { generateClaudeMd } from './claudemd-generator.js';
 /**
  * Skills to copy based on configuration
  */
@@ -29,6 +29,8 @@ const SKILLS_MAP = {
         'stream-chain',
         'skill-builder',
     ],
+    browser: ['browser'], // agent-browser integration
+    dualMode: ['dual-mode'], // Claude Code + Codex hybrid execution
     agentdb: [
         'agentdb-advanced',
         'agentdb-learning',
@@ -85,6 +87,26 @@ const AGENTS_MAP = {
     hiveMind: ['hive-mind'],
     sparc: ['sparc'],
     swarm: ['swarm'],
+    browser: ['browser'], // agent-browser integration
+    dualMode: ['dual-mode'], // Claude Code + Codex hybrid execution
+    // V3-specific agents
+    v3: ['v3'],
+    optimization: ['optimization'],
+    templates: ['templates'],
+    testing: ['testing'],
+    sublinear: ['sublinear'],
+    flowNexus: ['flow-nexus'],
+    analysis: ['analysis'],
+    architecture: ['architecture'],
+    development: ['development'],
+    devops: ['devops'],
+    documentation: ['documentation'],
+    specialized: ['specialized'],
+    goal: ['goal'],
+    sona: ['sona'],
+    payments: ['payments'],
+    data: ['data'],
+    custom: ['custom'],
 };
 /**
  * Directory structure to create
@@ -165,6 +187,10 @@ export async function executeInit(options) {
         if (options.components.runtime) {
             await writeRuntimeConfig(targetDir, options, result);
         }
+        // Create initial metrics for statusline (prevents "all zeros" display)
+        if (options.components.statusline) {
+            await writeInitialMetrics(targetDir, options, result);
+        }
         // Generate CLAUDE.md
         if (options.components.claudeMd) {
             await writeClaudeMd(targetDir, options, result);
@@ -178,6 +204,223 @@ export async function executeInit(options) {
     }
     return result;
 }
+/**
+ * Execute upgrade - updates helpers and creates missing metrics without losing data
+ * This is safe for existing users who want the latest statusline fixes
+ */
+export async function executeUpgrade(targetDir) {
+    const result = {
+        success: true,
+        updated: [],
+        created: [],
+        preserved: [],
+        errors: [],
+    };
+    try {
+        // Ensure required directories exist
+        const dirs = [
+            '.claude/helpers',
+            '.claude-flow/metrics',
+            '.claude-flow/security',
+            '.claude-flow/learning',
+        ];
+        for (const dir of dirs) {
+            const fullPath = path.join(targetDir, dir);
+            if (!fs.existsSync(fullPath)) {
+                fs.mkdirSync(fullPath, { recursive: true });
+            }
+        }
+        // 1. ALWAYS update statusline helper (force overwrite)
+        const statuslinePath = path.join(targetDir, '.claude', 'helpers', 'statusline.cjs');
+        // Use default options with statusline config
+        const upgradeOptions = {
+            ...DEFAULT_INIT_OPTIONS,
+            targetDir,
+            force: true,
+            statusline: {
+                ...DEFAULT_INIT_OPTIONS.statusline,
+                refreshInterval: 5000,
+            },
+        };
+        const statuslineContent = generateStatuslineScript(upgradeOptions);
+        if (fs.existsSync(statuslinePath)) {
+            result.updated.push('.claude/helpers/statusline.cjs');
+        }
+        else {
+            result.created.push('.claude/helpers/statusline.cjs');
+        }
+        fs.writeFileSync(statuslinePath, statuslineContent, 'utf-8');
+        // 2. Create MISSING metrics files only (preserve existing data)
+        const metricsDir = path.join(targetDir, '.claude-flow', 'metrics');
+        const securityDir = path.join(targetDir, '.claude-flow', 'security');
+        // v3-progress.json
+        const progressPath = path.join(metricsDir, 'v3-progress.json');
+        if (!fs.existsSync(progressPath)) {
+            const progress = {
+                version: '3.0.0',
+                initialized: new Date().toISOString(),
+                domains: { completed: 0, total: 5, status: 'INITIALIZING' },
+                ddd: { progress: 0, modules: 0, totalFiles: 0, totalLines: 0 },
+                swarm: { activeAgents: 0, maxAgents: 15, topology: 'hierarchical-mesh' },
+                learning: { status: 'READY', patternsLearned: 0, sessionsCompleted: 0 },
+                _note: 'Metrics will update as you use Claude Flow'
+            };
+            fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
+            result.created.push('.claude-flow/metrics/v3-progress.json');
+        }
+        else {
+            result.preserved.push('.claude-flow/metrics/v3-progress.json');
+        }
+        // swarm-activity.json
+        const activityPath = path.join(metricsDir, 'swarm-activity.json');
+        if (!fs.existsSync(activityPath)) {
+            const activity = {
+                timestamp: new Date().toISOString(),
+                processes: { agentic_flow: 0, mcp_server: 0, estimated_agents: 0 },
+                swarm: { active: false, agent_count: 0, coordination_active: false },
+                integration: { agentic_flow_active: false, mcp_active: false },
+                _initialized: true
+            };
+            fs.writeFileSync(activityPath, JSON.stringify(activity, null, 2), 'utf-8');
+            result.created.push('.claude-flow/metrics/swarm-activity.json');
+        }
+        else {
+            result.preserved.push('.claude-flow/metrics/swarm-activity.json');
+        }
+        // learning.json
+        const learningPath = path.join(metricsDir, 'learning.json');
+        if (!fs.existsSync(learningPath)) {
+            const learning = {
+                initialized: new Date().toISOString(),
+                routing: { accuracy: 0, decisions: 0 },
+                patterns: { shortTerm: 0, longTerm: 0, quality: 0 },
+                sessions: { total: 0, current: null },
+                _note: 'Intelligence grows as you use Claude Flow'
+            };
+            fs.writeFileSync(learningPath, JSON.stringify(learning, null, 2), 'utf-8');
+            result.created.push('.claude-flow/metrics/learning.json');
+        }
+        else {
+            result.preserved.push('.claude-flow/metrics/learning.json');
+        }
+        // audit-status.json
+        const auditPath = path.join(securityDir, 'audit-status.json');
+        if (!fs.existsSync(auditPath)) {
+            const audit = {
+                initialized: new Date().toISOString(),
+                status: 'PENDING',
+                cvesFixed: 0,
+                totalCves: 3,
+                lastScan: null,
+                _note: 'Run: npx @claude-flow/cli@latest security scan'
+            };
+            fs.writeFileSync(auditPath, JSON.stringify(audit, null, 2), 'utf-8');
+            result.created.push('.claude-flow/security/audit-status.json');
+        }
+        else {
+            result.preserved.push('.claude-flow/security/audit-status.json');
+        }
+    }
+    catch (error) {
+        result.success = false;
+        result.errors.push(error instanceof Error ? error.message : String(error));
+    }
+    return result;
+}
+/**
+ * Execute upgrade with --add-missing flag
+ * Adds any new skills, agents, and commands that don't exist yet
+ */
+export async function executeUpgradeWithMissing(targetDir) {
+    // First do the normal upgrade
+    const result = await executeUpgrade(targetDir);
+    if (!result.success) {
+        return result;
+    }
+    // Initialize tracking arrays
+    result.addedSkills = [];
+    result.addedAgents = [];
+    result.addedCommands = [];
+    try {
+        // Ensure target directories exist
+        const skillsDir = path.join(targetDir, '.claude', 'skills');
+        const agentsDir = path.join(targetDir, '.claude', 'agents');
+        const commandsDir = path.join(targetDir, '.claude', 'commands');
+        for (const dir of [skillsDir, agentsDir, commandsDir]) {
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+        }
+        // Find source directories
+        const sourceSkillsDir = findSourceDir('skills');
+        const sourceAgentsDir = findSourceDir('agents');
+        const sourceCommandsDir = findSourceDir('commands');
+        // Debug: Log source directories found
+        if (process.env.DEBUG || process.env.CLAUDE_FLOW_DEBUG) {
+            console.log('[DEBUG] Source directories:');
+            console.log(`  Skills: ${sourceSkillsDir || 'NOT FOUND'}`);
+            console.log(`  Agents: ${sourceAgentsDir || 'NOT FOUND'}`);
+            console.log(`  Commands: ${sourceCommandsDir || 'NOT FOUND'}`);
+        }
+        // Add missing skills
+        if (sourceSkillsDir) {
+            const allSkills = Object.values(SKILLS_MAP).flat();
+            const debugMode = process.env.DEBUG || process.env.CLAUDE_FLOW_DEBUG;
+            if (debugMode) {
+                console.log(`[DEBUG] Checking ${allSkills.length} skills from SKILLS_MAP`);
+            }
+            for (const skillName of [...new Set(allSkills)]) {
+                const sourcePath = path.join(sourceSkillsDir, skillName);
+                const targetPath = path.join(skillsDir, skillName);
+                const sourceExists = fs.existsSync(sourcePath);
+                const targetExists = fs.existsSync(targetPath);
+                if (debugMode) {
+                    console.log(`[DEBUG] Skill '${skillName}': source=${sourceExists}, target=${targetExists}`);
+                }
+                if (sourceExists && !targetExists) {
+                    copyDirRecursive(sourcePath, targetPath);
+                    result.addedSkills.push(skillName);
+                    result.created.push(`.claude/skills/${skillName}`);
+                }
+            }
+        }
+        // Add missing agents
+        if (sourceAgentsDir) {
+            const allAgents = Object.values(AGENTS_MAP).flat();
+            for (const agentCategory of [...new Set(allAgents)]) {
+                const sourcePath = path.join(sourceAgentsDir, agentCategory);
+                const targetPath = path.join(agentsDir, agentCategory);
+                if (fs.existsSync(sourcePath) && !fs.existsSync(targetPath)) {
+                    copyDirRecursive(sourcePath, targetPath);
+                    result.addedAgents.push(agentCategory);
+                    result.created.push(`.claude/agents/${agentCategory}`);
+                }
+            }
+        }
+        // Add missing commands
+        if (sourceCommandsDir) {
+            const allCommands = Object.values(COMMANDS_MAP).flat();
+            for (const cmdName of [...new Set(allCommands)]) {
+                const sourcePath = path.join(sourceCommandsDir, cmdName);
+                const targetPath = path.join(commandsDir, cmdName);
+                if (fs.existsSync(sourcePath) && !fs.existsSync(targetPath)) {
+                    if (fs.statSync(sourcePath).isDirectory()) {
+                        copyDirRecursive(sourcePath, targetPath);
+                    }
+                    else {
+                        fs.copyFileSync(sourcePath, targetPath);
+                    }
+                    result.addedCommands.push(cmdName);
+                    result.created.push(`.claude/commands/${cmdName}`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        result.errors.push(`Add missing failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return result;
+}
 /**
  * Create directory structure
  */
@@ -241,8 +484,12 @@ async function copySkills(targetDir, options, result) {
             skillsToCopy.push(...SKILLS_MAP.github);
         if (skillsConfig.flowNexus)
             skillsToCopy.push(...SKILLS_MAP.flowNexus);
+        if (skillsConfig.browser)
+            skillsToCopy.push(...SKILLS_MAP.browser);
         if (skillsConfig.v3)
             skillsToCopy.push(...SKILLS_MAP.v3);
+        if (skillsConfig.dualMode)
+            skillsToCopy.push(...SKILLS_MAP.dualMode);
     }
     // Find source skills directory
     const sourceSkillsDir = findSourceDir('skills', options.sourceBaseDir);
@@ -346,6 +593,18 @@ async function copyAgents(targetDir, options, result) {
             agentsToCopy.push(...AGENTS_MAP.sparc);
         if (agentsConfig.swarm)
             agentsToCopy.push(...AGENTS_MAP.swarm);
+        if (agentsConfig.browser)
+            agentsToCopy.push(...AGENTS_MAP.browser);
+        // V3-specific agent categories
+        if (agentsConfig.v3)
+            agentsToCopy.push(...(AGENTS_MAP.v3 || []));
+        if (agentsConfig.optimization)
+            agentsToCopy.push(...(AGENTS_MAP.optimization || []));
+        if (agentsConfig.testing)
+            agentsToCopy.push(...(AGENTS_MAP.testing || []));
+        // Dual-mode agents (Claude Code + Codex hybrid)
+        if (agentsConfig.dualMode)
+            agentsToCopy.push(...(AGENTS_MAP.dualMode || []));
     }
     // Find source agents directory
     const sourceAgentsDir = findSourceDir('agents', options.sourceBaseDir);
@@ -360,9 +619,10 @@ async function copyAgents(targetDir, options, result) {
         if (fs.existsSync(sourcePath)) {
             if (!fs.existsSync(targetPath) || options.force) {
                 copyDirRecursive(sourcePath, targetPath);
-                // Count agent files
-                const agentFiles = countFiles(sourcePath, '.md');
-                result.summary.agentsCount += agentFiles;
+                // Count agent files (.yaml and .md)
+                const yamlFiles = countFiles(sourcePath, '.yaml');
+                const mdFiles = countFiles(sourcePath, '.md');
+                result.summary.agentsCount += yamlFiles + mdFiles;
                 result.created.files.push(`.claude/agents/${agentCategory}`);
             }
             else {
@@ -371,35 +631,79 @@ async function copyAgents(targetDir, options, result) {
         }
     }
 }
+/**
+ * Find source helpers directory
+ */
+function findSourceHelpersDir(sourceBaseDir) {
+    const possiblePaths = [];
+    // If explicit source base directory is provided, check it first
+    if (sourceBaseDir) {
+        possiblePaths.push(path.join(sourceBaseDir, '.claude', 'helpers'));
+    }
+    // IMPORTANT: Check the package's own .claude/helpers directory
+    // This is the primary path when running as an npm package
+    // __dirname is typically /path/to/node_modules/@claude-flow/cli/dist/src/init
+    // We need to go up 3 levels to reach the package root (dist/src/init -> dist/src -> dist -> root)
+    const packageRoot = path.resolve(__dirname, '..', '..', '..');
+    const packageHelpers = path.join(packageRoot, '.claude', 'helpers');
+    if (fs.existsSync(packageHelpers)) {
+        possiblePaths.unshift(packageHelpers); // Add to beginning (highest priority)
+    }
+    // From dist/src/init -> go up to project root
+    let currentDir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        const parentDir = path.dirname(currentDir);
+        const helpersPath = path.join(parentDir, '.claude', 'helpers');
+        if (fs.existsSync(helpersPath)) {
+            possiblePaths.push(helpersPath);
+        }
+        currentDir = parentDir;
+    }
+    // Also check relative to process.cwd() for development
+    const cwdBased = [
+        path.join(process.cwd(), '.claude', 'helpers'),
+        path.join(process.cwd(), '..', '.claude', 'helpers'),
+        path.join(process.cwd(), '..', '..', '.claude', 'helpers'),
+    ];
+    possiblePaths.push(...cwdBased);
+    for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    return null;
+}
 /**
  * Write helper scripts
  */
 async function writeHelpers(targetDir, options, result) {
     const helpersDir = path.join(targetDir, '.claude', 'helpers');
-    const sourceBaseDir = options.sourceBaseDir;
+    // Find source helpers directory (works for npm package and local dev)
+    const sourceHelpersDir = findSourceHelpersDir(options.sourceBaseDir);
     // Try to copy existing helpers from source first
-    if (sourceBaseDir) {
-        const sourceHelpersDir = path.join(sourceBaseDir, '.claude', 'helpers');
-        if (fs.existsSync(sourceHelpersDir)) {
-            const helperFiles = fs.readdirSync(sourceHelpersDir);
-            for (const file of helperFiles) {
-                const sourcePath = path.join(sourceHelpersDir, file);
-                const destPath = path.join(helpersDir, file);
-                // Skip directories and only copy files
-                if (!fs.statSync(sourcePath).isFile())
-                    continue;
-                if (!fs.existsSync(destPath) || options.force) {
-                    fs.copyFileSync(sourcePath, destPath);
-                    // Make shell scripts executable
-                    if (file.endsWith('.sh')) {
-                        fs.chmodSync(destPath, '755');
-                    }
-                    result.created.files.push(`.claude/helpers/${file}`);
-                }
-                else {
-                    result.skipped.push(`.claude/helpers/${file}`);
+    if (sourceHelpersDir && fs.existsSync(sourceHelpersDir)) {
+        const helperFiles = fs.readdirSync(sourceHelpersDir);
+        let copiedCount = 0;
+        for (const file of helperFiles) {
+            const sourcePath = path.join(sourceHelpersDir, file);
+            const destPath = path.join(helpersDir, file);
+            // Skip directories and only copy files
+            if (!fs.statSync(sourcePath).isFile())
+                continue;
+            if (!fs.existsSync(destPath) || options.force) {
+                fs.copyFileSync(sourcePath, destPath);
+                // Make shell scripts and mjs files executable
+                if (file.endsWith('.sh') || file.endsWith('.mjs')) {
+                    fs.chmodSync(destPath, '755');
                 }
+                result.created.files.push(`.claude/helpers/${file}`);
+                copiedCount++;
+            }
+            else {
+                result.skipped.push(`.claude/helpers/${file}`);
             }
+        }
+        if (copiedCount > 0) {
             return; // Skip generating if we copied from source
         }
     }
@@ -426,28 +730,62 @@ async function writeHelpers(targetDir, options, result) {
         }
     }
 }
+/**
+ * Find source .claude directory for statusline files
+ */
+function findSourceClaudeDir(sourceBaseDir) {
+    const possiblePaths = [];
+    // If explicit source base directory is provided, check it first
+    if (sourceBaseDir) {
+        possiblePaths.push(path.join(sourceBaseDir, '.claude'));
+    }
+    // IMPORTANT: Check the package's own .claude directory
+    // Go up 3 levels: dist/src/init -> dist/src -> dist -> root
+    const packageRoot = path.resolve(__dirname, '..', '..', '..');
+    const packageClaude = path.join(packageRoot, '.claude');
+    if (fs.existsSync(packageClaude)) {
+        possiblePaths.unshift(packageClaude); // Add to beginning (highest priority)
+    }
+    // From dist/src/init -> go up to project root
+    let currentDir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        const parentDir = path.dirname(currentDir);
+        const claudePath = path.join(parentDir, '.claude');
+        if (fs.existsSync(claudePath)) {
+            possiblePaths.push(claudePath);
+        }
+        currentDir = parentDir;
+    }
+    for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    return null;
+}
 /**
  * Write statusline configuration
  */
 async function writeStatusline(targetDir, options, result) {
     const claudeDir = path.join(targetDir, '.claude');
     const helpersDir = path.join(targetDir, '.claude', 'helpers');
+    // Find source .claude directory (works for npm package and local dev)
+    const sourceClaudeDir = findSourceClaudeDir(options.sourceBaseDir);
     // Try to copy existing advanced statusline files from source
-    const sourceBaseDir = options.sourceBaseDir;
     const advancedStatuslineFiles = [
         { src: 'statusline.sh', dest: 'statusline.sh', dir: claudeDir },
         { src: 'statusline.mjs', dest: 'statusline.mjs', dir: claudeDir },
     ];
     let copiedAdvanced = false;
-    if (sourceBaseDir) {
+    if (sourceClaudeDir) {
         for (const file of advancedStatuslineFiles) {
-            const sourcePath = path.join(sourceBaseDir, '.claude', file.src);
+            const sourcePath = path.join(sourceClaudeDir, file.src);
             const destPath = path.join(file.dir, file.dest);
             if (fs.existsSync(sourcePath)) {
                 if (!fs.existsSync(destPath) || options.force) {
                     fs.copyFileSync(sourcePath, destPath);
-                    // Make shell scripts executable
-                    if (file.src.endsWith('.sh')) {
+                    // Make shell scripts and mjs executable
+                    if (file.src.endsWith('.sh') || file.src.endsWith('.mjs')) {
                         fs.chmodSync(destPath, '755');
                     }
                     result.created.files.push(`.claude/${file.dest}`);
@@ -464,7 +802,7 @@ async function writeStatusline(targetDir, options, result) {
         const statuslineScript = generateStatuslineScript(options);
         const statuslineHook = generateStatuslineHook(options);
         const files = {
-            'statusline.js': statuslineScript,
+            'statusline.cjs': statuslineScript, // .cjs for ES module project compatibility
             'statusline-hook.sh': statuslineHook,
         };
         for (const [name, content] of Object.entries(files)) {
@@ -533,6 +871,505 @@ neural/
         fs.writeFileSync(gitignorePath, gitignore, 'utf-8');
         result.created.files.push('.claude-flow/.gitignore');
     }
+    // Write CAPABILITIES.md with full system overview
+    await writeCapabilitiesDoc(targetDir, options, result);
+}
+/**
+ * Write initial metrics files for statusline
+ * Creates baseline data so statusline shows meaningful state instead of all zeros
+ */
+async function writeInitialMetrics(targetDir, options, result) {
+    const metricsDir = path.join(targetDir, '.claude-flow', 'metrics');
+    const learningDir = path.join(targetDir, '.claude-flow', 'learning');
+    const securityDir = path.join(targetDir, '.claude-flow', 'security');
+    // Ensure directories exist
+    for (const dir of [metricsDir, learningDir, securityDir]) {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    }
+    // Create initial v3-progress.json
+    const progressPath = path.join(metricsDir, 'v3-progress.json');
+    if (!fs.existsSync(progressPath) || options.force) {
+        const progress = {
+            version: '3.0.0',
+            initialized: new Date().toISOString(),
+            domains: {
+                completed: 0,
+                total: 5,
+                status: 'INITIALIZING'
+            },
+            ddd: {
+                progress: 0,
+                modules: 0,
+                totalFiles: 0,
+                totalLines: 0
+            },
+            swarm: {
+                activeAgents: 0,
+                maxAgents: options.runtime.maxAgents,
+                topology: options.runtime.topology
+            },
+            learning: {
+                status: 'READY',
+                patternsLearned: 0,
+                sessionsCompleted: 0
+            },
+            _note: 'Metrics will update as you use Claude Flow. Run: npx @claude-flow/cli@latest daemon start'
+        };
+        fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
+        result.created.files.push('.claude-flow/metrics/v3-progress.json');
+    }
+    // Create initial swarm-activity.json
+    const activityPath = path.join(metricsDir, 'swarm-activity.json');
+    if (!fs.existsSync(activityPath) || options.force) {
+        const activity = {
+            timestamp: new Date().toISOString(),
+            processes: {
+                agentic_flow: 0,
+                mcp_server: 0,
+                estimated_agents: 0
+            },
+            swarm: {
+                active: false,
+                agent_count: 0,
+                coordination_active: false
+            },
+            integration: {
+                agentic_flow_active: false,
+                mcp_active: false
+            },
+            _initialized: true
+        };
+        fs.writeFileSync(activityPath, JSON.stringify(activity, null, 2), 'utf-8');
+        result.created.files.push('.claude-flow/metrics/swarm-activity.json');
+    }
+    // Create initial learning.json
+    const learningPath = path.join(metricsDir, 'learning.json');
+    if (!fs.existsSync(learningPath) || options.force) {
+        const learning = {
+            initialized: new Date().toISOString(),
+            routing: {
+                accuracy: 0,
+                decisions: 0
+            },
+            patterns: {
+                shortTerm: 0,
+                longTerm: 0,
+                quality: 0
+            },
+            sessions: {
+                total: 0,
+                current: null
+            },
+            _note: 'Intelligence grows as you use Claude Flow'
+        };
+        fs.writeFileSync(learningPath, JSON.stringify(learning, null, 2), 'utf-8');
+        result.created.files.push('.claude-flow/metrics/learning.json');
+    }
+    // Create initial audit-status.json
+    const auditPath = path.join(securityDir, 'audit-status.json');
+    if (!fs.existsSync(auditPath) || options.force) {
+        const audit = {
+            initialized: new Date().toISOString(),
+            status: 'PENDING',
+            cvesFixed: 0,
+            totalCves: 3,
+            lastScan: null,
+            _note: 'Run: npx @claude-flow/cli@latest security scan'
+        };
+        fs.writeFileSync(auditPath, JSON.stringify(audit, null, 2), 'utf-8');
+        result.created.files.push('.claude-flow/security/audit-status.json');
+    }
+}
+/**
+ * Write CAPABILITIES.md - comprehensive overview of all Claude Flow features
+ */
+async function writeCapabilitiesDoc(targetDir, options, result) {
+    const capabilitiesPath = path.join(targetDir, '.claude-flow', 'CAPABILITIES.md');
+    if (fs.existsSync(capabilitiesPath) && !options.force) {
+        result.skipped.push('.claude-flow/CAPABILITIES.md');
+        return;
+    }
+    const capabilities = `# Claude Flow V3 - Complete Capabilities Reference
+> Generated: ${new Date().toISOString()}
+> Full documentation: https://github.com/ruvnet/claude-flow
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [Swarm Orchestration](#swarm-orchestration)
+3. [Available Agents (60+)](#available-agents)
+4. [CLI Commands (26 Commands, 140+ Subcommands)](#cli-commands)
+5. [Hooks System (27 Hooks + 12 Workers)](#hooks-system)
+6. [Memory & Intelligence (RuVector)](#memory--intelligence)
+7. [Hive-Mind Consensus](#hive-mind-consensus)
+8. [Performance Targets](#performance-targets)
+9. [Integration Ecosystem](#integration-ecosystem)
+
+---
+
+## Overview
+
+Claude Flow V3 is a domain-driven design architecture for multi-agent AI coordination with:
+
+- **15-Agent Swarm Coordination** with hierarchical and mesh topologies
+- **HNSW Vector Search** - 150x-12,500x faster pattern retrieval
+- **SONA Neural Learning** - Self-optimizing with <0.05ms adaptation
+- **Byzantine Fault Tolerance** - Queen-led consensus mechanisms
+- **MCP Server Integration** - Model Context Protocol support
+
+### Current Configuration
+| Setting | Value |
+|---------|-------|
+| Topology | ${options.runtime.topology} |
+| Max Agents | ${options.runtime.maxAgents} |
+| Memory Backend | ${options.runtime.memoryBackend} |
+| HNSW Indexing | ${options.runtime.enableHNSW ? 'Enabled' : 'Disabled'} |
+| Neural Learning | ${options.runtime.enableNeural ? 'Enabled' : 'Disabled'} |
+
+---
+
+## Swarm Orchestration
+
+### Topologies
+| Topology | Description | Best For |
+|----------|-------------|----------|
+| \`hierarchical\` | Queen controls workers directly | Anti-drift, tight control |
+| \`mesh\` | Fully connected peer network | Distributed tasks |
+| \`hierarchical-mesh\` | V3 hybrid (recommended) | 10+ agents |
+| \`ring\` | Circular communication | Sequential workflows |
+| \`star\` | Central coordinator | Simple coordination |
+| \`adaptive\` | Dynamic based on load | Variable workloads |
+
+### Strategies
+- \`balanced\` - Even distribution across agents
+- \`specialized\` - Clear roles, no overlap (anti-drift)
+- \`adaptive\` - Dynamic task routing
+
+### Quick Commands
+\`\`\`bash
+# Initialize swarm
+npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
+
+# Check status
+npx @claude-flow/cli@latest swarm status
+
+# Monitor activity
+npx @claude-flow/cli@latest swarm monitor
+\`\`\`
+
+---
+
+## Available Agents
+
+### Core Development (5)
+\`coder\`, \`reviewer\`, \`tester\`, \`planner\`, \`researcher\`
+
+### V3 Specialized (4)
+\`security-architect\`, \`security-auditor\`, \`memory-specialist\`, \`performance-engineer\`
+
+### Swarm Coordination (5)
+\`hierarchical-coordinator\`, \`mesh-coordinator\`, \`adaptive-coordinator\`, \`collective-intelligence-coordinator\`, \`swarm-memory-manager\`
+
+### Consensus & Distributed (7)
+\`byzantine-coordinator\`, \`raft-manager\`, \`gossip-coordinator\`, \`consensus-builder\`, \`crdt-synchronizer\`, \`quorum-manager\`, \`security-manager\`
+
+### Performance & Optimization (5)
+\`perf-analyzer\`, \`performance-benchmarker\`, \`task-orchestrator\`, \`memory-coordinator\`, \`smart-agent\`
+
+### GitHub & Repository (9)
+\`github-modes\`, \`pr-manager\`, \`code-review-swarm\`, \`issue-tracker\`, \`release-manager\`, \`workflow-automation\`, \`project-board-sync\`, \`repo-architect\`, \`multi-repo-swarm\`
+
+### SPARC Methodology (6)
+\`sparc-coord\`, \`sparc-coder\`, \`specification\`, \`pseudocode\`, \`architecture\`, \`refinement\`
+
+### Specialized Development (8)
+\`backend-dev\`, \`mobile-dev\`, \`ml-developer\`, \`cicd-engineer\`, \`api-docs\`, \`system-architect\`, \`code-analyzer\`, \`base-template-generator\`
+
+### Testing & Validation (2)
+\`tdd-london-swarm\`, \`production-validator\`
+
+### Agent Routing by Task
+| Task Type | Recommended Agents | Topology |
+|-----------|-------------------|----------|
+| Bug Fix | researcher, coder, tester | mesh |
+| New Feature | coordinator, architect, coder, tester, reviewer | hierarchical |
+| Refactoring | architect, coder, reviewer | mesh |
+| Performance | researcher, perf-engineer, coder | hierarchical |
+| Security | security-architect, auditor, reviewer | hierarchical |
+| Docs | researcher, api-docs | mesh |
+
+---
+
+## CLI Commands
+
+### Core Commands (12)
+| Command | Subcommands | Description |
+|---------|-------------|-------------|
+| \`init\` | 4 | Project initialization |
+| \`agent\` | 8 | Agent lifecycle management |
+| \`swarm\` | 6 | Multi-agent coordination |
+| \`memory\` | 11 | AgentDB with HNSW search |
+| \`mcp\` | 9 | MCP server management |
+| \`task\` | 6 | Task assignment |
+| \`session\` | 7 | Session persistence |
+| \`config\` | 7 | Configuration |
+| \`status\` | 3 | System monitoring |
+| \`workflow\` | 6 | Workflow templates |
+| \`hooks\` | 17 | Self-learning hooks |
+| \`hive-mind\` | 6 | Consensus coordination |
+
+### Advanced Commands (14)
+| Command | Subcommands | Description |
+|---------|-------------|-------------|
+| \`daemon\` | 5 | Background workers |
+| \`neural\` | 5 | Pattern training |
+| \`security\` | 6 | Security scanning |
+| \`performance\` | 5 | Profiling & benchmarks |
+| \`providers\` | 5 | AI provider config |
+| \`plugins\` | 5 | Plugin management |
+| \`deployment\` | 5 | Deploy management |
+| \`embeddings\` | 4 | Vector embeddings |
+| \`claims\` | 4 | Authorization |
+| \`migrate\` | 5 | V2→V3 migration |
+| \`process\` | 4 | Process management |
+| \`doctor\` | 1 | Health diagnostics |
+| \`completions\` | 4 | Shell completions |
+
+### Example Commands
+\`\`\`bash
+# Initialize
+npx @claude-flow/cli@latest init --wizard
+
+# Spawn agent
+npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
+
+# Memory operations
+npx @claude-flow/cli@latest memory store --key "pattern" --value "data" --namespace patterns
+npx @claude-flow/cli@latest memory search --query "authentication"
+
+# Diagnostics
+npx @claude-flow/cli@latest doctor --fix
+\`\`\`
+
+---
+
+## Hooks System
+
+### 27 Available Hooks
+
+#### Core Hooks (6)
+| Hook | Description |
+|------|-------------|
+| \`pre-edit\` | Context before file edits |
+| \`post-edit\` | Record edit outcomes |
+| \`pre-command\` | Risk assessment |
+| \`post-command\` | Command metrics |
+| \`pre-task\` | Task start + agent suggestions |
+| \`post-task\` | Task completion learning |
+
+#### Session Hooks (4)
+| Hook | Description |
+|------|-------------|
+| \`session-start\` | Start/restore session |
+| \`session-end\` | Persist state |
+| \`session-restore\` | Restore previous |
+| \`notify\` | Cross-agent notifications |
+
+#### Intelligence Hooks (5)
+| Hook | Description |
+|------|-------------|
+| \`route\` | Optimal agent routing |
+| \`explain\` | Routing decisions |
+| \`pretrain\` | Bootstrap intelligence |
+| \`build-agents\` | Generate configs |
+| \`transfer\` | Pattern transfer |
+
+#### Coverage Hooks (3)
+| Hook | Description |
+|------|-------------|
+| \`coverage-route\` | Coverage-based routing |
+| \`coverage-suggest\` | Improvement suggestions |
+| \`coverage-gaps\` | Gap analysis |
+
+### 12 Background Workers
+| Worker | Priority | Purpose |
+|--------|----------|---------|
+| \`ultralearn\` | normal | Deep knowledge |
+| \`optimize\` | high | Performance |
+| \`consolidate\` | low | Memory consolidation |
+| \`predict\` | normal | Predictive preload |
+| \`audit\` | critical | Security |
+| \`map\` | normal | Codebase mapping |
+| \`preload\` | low | Resource preload |
+| \`deepdive\` | normal | Deep analysis |
+| \`document\` | normal | Auto-docs |
+| \`refactor\` | normal | Suggestions |
+| \`benchmark\` | normal | Benchmarking |
+| \`testgaps\` | normal | Coverage gaps |
+
+---
+
+## Memory & Intelligence
+
+### RuVector Intelligence System
+- **SONA**: Self-Optimizing Neural Architecture (<0.05ms)
+- **MoE**: Mixture of Experts routing
+- **HNSW**: 150x-12,500x faster search
+- **EWC++**: Prevents catastrophic forgetting
+- **Flash Attention**: 2.49x-7.47x speedup
+- **Int8 Quantization**: 3.92x memory reduction
+
+### 4-Step Intelligence Pipeline
+1. **RETRIEVE** - HNSW pattern search
+2. **JUDGE** - Success/failure verdicts
+3. **DISTILL** - LoRA learning extraction
+4. **CONSOLIDATE** - EWC++ preservation
+
+### Memory Commands
+\`\`\`bash
+# Store pattern
+npx @claude-flow/cli@latest memory store --key "name" --value "data" --namespace patterns
+
+# Semantic search
+npx @claude-flow/cli@latest memory search --query "authentication"
+
+# List entries
+npx @claude-flow/cli@latest memory list --namespace patterns
+
+# Initialize database
+npx @claude-flow/cli@latest memory init --force
+\`\`\`
+
+---
+
+## Hive-Mind Consensus
+
+### Queen Types
+| Type | Role |
+|------|------|
+| Strategic Queen | Long-term planning |
+| Tactical Queen | Execution coordination |
+| Adaptive Queen | Dynamic optimization |
+
+### Worker Types (8)
+\`researcher\`, \`coder\`, \`analyst\`, \`tester\`, \`architect\`, \`reviewer\`, \`optimizer\`, \`documenter\`
+
+### Consensus Mechanisms
+| Mechanism | Fault Tolerance | Use Case |
+|-----------|-----------------|----------|
+| \`byzantine\` | f < n/3 faulty | Adversarial |
+| \`raft\` | f < n/2 failed | Leader-based |
+| \`gossip\` | Eventually consistent | Large scale |
+| \`crdt\` | Conflict-free | Distributed |
+| \`quorum\` | Configurable | Flexible |
+
+### Hive-Mind Commands
+\`\`\`bash
+# Initialize
+npx @claude-flow/cli@latest hive-mind init --queen-type strategic
+
+# Status
+npx @claude-flow/cli@latest hive-mind status
+
+# Spawn workers
+npx @claude-flow/cli@latest hive-mind spawn --count 5 --type worker
+
+# Consensus
+npx @claude-flow/cli@latest hive-mind consensus --propose "task"
+\`\`\`
+
+---
+
+## Performance Targets
+
+| Metric | Target | Status |
+|--------|--------|--------|
+| HNSW Search | 150x-12,500x faster | ✅ Implemented |
+| Memory Reduction | 50-75% | ✅ Implemented (3.92x) |
+| SONA Integration | Pattern learning | ✅ Implemented |
+| Flash Attention | 2.49x-7.47x | 🔄 In Progress |
+| MCP Response | <100ms | ✅ Achieved |
+| CLI Startup | <500ms | ✅ Achieved |
+| SONA Adaptation | <0.05ms | 🔄 In Progress |
+
+---
+
+## Integration Ecosystem
+
+### Integrated Packages
+| Package | Version | Purpose |
+|---------|---------|---------|
+| agentic-flow | 2.0.1-alpha | Core coordination |
+| agentdb | 2.0.0-alpha.3.4 | Vector database |
+| @ruvector/attention | 0.1.3 | Flash attention |
+| @ruvector/sona | 0.1.5 | Neural learning |
+
+### Optional Integrations
+| Package | Command |
+|---------|---------|
+| ruv-swarm | \`npx ruv-swarm mcp start\` |
+| flow-nexus | \`npx flow-nexus@latest mcp start\` |
+| agentic-jujutsu | \`npx agentic-jujutsu@latest\` |
+
+### MCP Server Setup
+\`\`\`bash
+# Add Claude Flow MCP
+claude mcp add claude-flow -- npx -y @claude-flow/cli@latest
+
+# Optional servers
+claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start
+claude mcp add flow-nexus -- npx -y flow-nexus@latest mcp start
+\`\`\`
+
+---
+
+## Quick Reference
+
+### Essential Commands
+\`\`\`bash
+# Setup
+npx @claude-flow/cli@latest init --wizard
+npx @claude-flow/cli@latest daemon start
+npx @claude-flow/cli@latest doctor --fix
+
+# Swarm
+npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8
+npx @claude-flow/cli@latest swarm status
+
+# Agents
+npx @claude-flow/cli@latest agent spawn -t coder
+npx @claude-flow/cli@latest agent list
+
+# Memory
+npx @claude-flow/cli@latest memory search --query "patterns"
+
+# Hooks
+npx @claude-flow/cli@latest hooks pre-task --description "task"
+npx @claude-flow/cli@latest hooks worker dispatch --trigger optimize
+\`\`\`
+
+### File Structure
+\`\`\`
+.claude-flow/
+├── config.yaml      # Runtime configuration
+├── CAPABILITIES.md  # This file
+├── data/            # Memory storage
+├── logs/            # Operation logs
+├── sessions/        # Session state
+├── hooks/           # Custom hooks
+├── agents/          # Agent configs
+└── workflows/       # Workflow templates
+\`\`\`
+
+---
+
+**Full Documentation**: https://github.com/ruvnet/claude-flow
+**Issues**: https://github.com/ruvnet/claude-flow/issues
+`;
+    fs.writeFileSync(capabilitiesPath, capabilities, 'utf-8');
+    result.created.files.push('.claude-flow/CAPABILITIES.md');
 }
 /**
  * Write CLAUDE.md with swarm guidance
@@ -543,9 +1380,9 @@ async function writeClaudeMd(targetDir, options, result) {
         result.skipped.push('CLAUDE.md');
         return;
     }
-    // Use minimal version for minimal init, full version otherwise
-    const isMinimal = !options.components.commands && !options.components.agents;
-    const content = isMinimal ? generateMinimalClaudeMd(options) : generateClaudeMd(options);
+    // Determine template: explicit option > infer from components > 'standard'
+    const inferredTemplate = (!options.components.commands && !options.components.agents) ? 'minimal' : undefined;
+    const content = generateClaudeMd(options, inferredTemplate);
     fs.writeFileSync(claudeMdPath, content, 'utf-8');
     result.created.files.push('CLAUDE.md');
 }
@@ -559,8 +1396,16 @@ function findSourceDir(type, sourceBaseDir) {
     if (sourceBaseDir) {
         possiblePaths.push(path.join(sourceBaseDir, '.claude', type));
     }
+    // IMPORTANT: Check the package's own .claude directory first
+    // This is the primary path when running as an npm package
+    // __dirname is typically /path/to/node_modules/@claude-flow/cli/dist/src/init
+    // We need to go up 3 levels to reach the package root (dist/src/init -> dist/src -> dist -> root)
+    const packageRoot = path.resolve(__dirname, '..', '..', '..');
+    const packageDotClaude = path.join(packageRoot, '.claude', type);
+    if (fs.existsSync(packageDotClaude)) {
+        possiblePaths.unshift(packageDotClaude); // Add to beginning (highest priority)
+    }
     // From dist/src/init -> go up to project root
-    // __dirname is typically /path/to/v3/@claude-flow/cli/dist/src/init
     const distPath = __dirname;
     // Try to find the project root by looking for .claude directory
     let currentDir = distPath;
@@ -644,8 +1489,6 @@ function countEnabledHooks(options) {
         count++;
     if (hooks.notification)
         count++;
-    if (hooks.permissionRequest)
-        count++;
     return count;
 }
 export default executeInit;