claude-flow 3.25.5 → 3.25.6

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.25.4
+3.23.0

package/.claude/helpers/helpers.manifest.json

@@ -1,12 +1,12 @@
 {
   "manifest": {
-    "version": "3.25.4",
+    "version": "3.23.0",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "bc4d2d26823d49b3ab1dded2946b66369f1f67bd76b4c30dca9f3b6df3cca8f0",
-      "intelligence.cjs": "bd1f8e4b034944aee1df0391dc47ac2e8cc4b3aa542c65407a59d49620bbf76b"
+      "intelligence.cjs": "760cb82ed2000031abc1ac1fa90a014e7d91d93966e3aa4741b07ab7aff8d066"
     }
   },
-  "signature": "F3TIRoNcQTCkNeMEk5Isah5CWkV/zddUKR/6pieOlAWoYgI2BEUO7avQj8B8UP4vhvgT9TSgbYsis2UnnnQyBg==",
+  "signature": "of5l9RP68iPcmcC5dckDv+KIOiENJKifWxYKwQTwAiXiyRNNZuMwQ8y8Bd8+wGviTRxIzBfSuxL1nuJ/rX3xDQ==",
   "algorithm": "ed25519"
 }

package/.claude/helpers/intelligence.cjs

@@ -587,16 +587,6 @@ function recordEdit(file, success) {
     sessionId: sessionGet('sessionId') || null,
   });
   fs.appendFileSync(PENDING_PATH, entry + '\n', 'utf-8');
-  // Runaway-storage guard: pending-insights is append-only and only drained by
-  // consolidation. If it grows past ~512KB (thousands of un-consolidated edits
-  // — e.g. the daemon never ran), keep only the most recent 2000 lines so it
-  // can never grow unbounded. Cheap (a statSync per edit; rewrite only when over).
-  try {
-    if (fs.statSync(PENDING_PATH).size > 512 * 1024) {
-      const lines = fs.readFileSync(PENDING_PATH, 'utf-8').split('\n').filter(Boolean);
-      if (lines.length > 2000) fs.writeFileSync(PENDING_PATH, lines.slice(-2000).join('\n') + '\n', 'utf-8');
-    }
-  } catch (e) { /* non-fatal */ }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.25.5",
+  "version": "3.25.6",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/commands/doctor.js

@@ -442,53 +442,98 @@ async function checkMcpServers() {
         '.mcp.json',
     ];
     const isRufloKey = (k) => k === 'ruflo' || k === 'ruflo_alpha' || k === 'claude-flow' || k === 'claude-flow_alpha';
+    // Canonical MCP-server key is `claude-flow` — matches the `mcp__claude-flow__*`
+    // prefix that ~166 plugin tool references depend on (#2206). A `ruflo`-keyed
+    // entry pointing at the same binary is the legacy duplicate created by
+    // pre-rename setup docs that #2612 tracks; doctor treats it as removable.
+    const isCurrentRufloKey = (k) => k === 'claude-flow' || k === 'claude-flow_alpha';
+    const isLegacyRufloKey = (k) => k === 'ruflo' || k === 'ruflo_alpha';
+    const isRufloServer = (server) => {
+        if (!server || typeof server !== 'object')
+            return false;
+        const entry = server;
+        const command = typeof entry.command === 'string' ? entry.command : '';
+        const args = Array.isArray(entry.args)
+            ? entry.args.filter((arg) => typeof arg === 'string')
+            : [];
+        const haystack = [command, ...args].join(' ');
+        return /\b(?:ruflo|claude-flow|@claude-flow\/cli)(?:@[\w.-]+)?\b/.test(haystack);
+    };
+    let totalServersSeen = 0;
+    const rufloLocations = [];
+    const duplicateLocations = [];
+    const legacyLocations = [];
+    const currentLocations = [];
+    const inspectServers = (servers, location) => {
+        if (!servers || typeof servers !== 'object')
+            return { total: 0, hasRuflo: false };
+        const entries = Object.entries(servers);
+        const activeRufloEntries = entries.filter(([key, server]) => isRufloKey(key) && isRufloServer(server));
+        const hasLegacy = activeRufloEntries.some(([key]) => isLegacyRufloKey(key));
+        const hasCurrent = activeRufloEntries.some(([key]) => isCurrentRufloKey(key));
+        if (activeRufloEntries.length > 0) {
+            rufloLocations.push(`${location}: ${activeRufloEntries.map(([key]) => key).join(', ')}`);
+        }
+        if (hasLegacy && hasCurrent) {
+            duplicateLocations.push(`${location}: ${activeRufloEntries.map(([key]) => key).join(' + ')}`);
+        }
+        for (const [key] of activeRufloEntries) {
+            if (isLegacyRufloKey(key))
+                legacyLocations.push(`${location}: ${key}`);
+            if (isCurrentRufloKey(key))
+                currentLocations.push(`${location}: ${key}`);
+        }
+        return { total: entries.length, hasRuflo: activeRufloEntries.length > 0 };
+    };
     for (const configPath of mcpConfigPaths) {
         if (!existsSync(configPath))
             continue;
         try {
             const content = JSON.parse(readFileSync(configPath, 'utf8'));
             // Top-level mcpServers (legacy / desktop form)
-            const topServers = content.mcpServers || content.servers || {};
-            const topServerKeys = Object.keys(topServers);
-            const topHasRuflo = topServerKeys.some(isRufloKey);
+            const topResult = inspectServers(content.mcpServers || content.servers || {}, `${configPath} top-level`);
+            totalServersSeen += topResult.total;
             // Project-scoped (Claude Code shape): projects[*].mcpServers.ruflo
-            let projectHits = 0;
-            let projectScannedServers = 0;
             if (content.projects && typeof content.projects === 'object') {
-                for (const projectVal of Object.values(content.projects)) {
+                for (const [projectKey, projectVal] of Object.entries(content.projects)) {
                     const pm = projectVal?.mcpServers;
                     if (pm && typeof pm === 'object') {
-                        const keys = Object.keys(pm);
-                        projectScannedServers += keys.length;
-                        if (keys.some(isRufloKey))
-                            projectHits += 1;
+                        const projectResult = inspectServers(pm, `${configPath} projects[${projectKey}]`);
+                        totalServersSeen += projectResult.total;
                     }
                 }
             }
-            const totalServers = topServerKeys.length + projectScannedServers;
-            if (topHasRuflo || projectHits > 0) {
-                const where = topHasRuflo
-                    ? 'top-level'
-                    : `${projectHits} project-scoped`;
-                return {
-                    name: 'MCP Servers',
-                    status: 'pass',
-                    message: `${totalServers} servers (ruflo configured: ${where})`,
-                };
-            }
-            if (totalServers > 0) {
-                return {
-                    name: 'MCP Servers',
-                    status: 'warn',
-                    message: `${totalServers} servers (ruflo not found)`,
-                    fix: 'claude mcp add ruflo -- npx -y ruflo@latest mcp start',
-                };
-            }
         }
         catch {
             // continue to next path
         }
     }
+    if (duplicateLocations.length > 0 || (legacyLocations.length > 0 && currentLocations.length > 0)) {
+        const locations = duplicateLocations.length > 0
+            ? duplicateLocations.join('; ')
+            : `legacy ${legacyLocations.join('; ')} + current ${currentLocations.join('; ')}`;
+        return {
+            name: 'MCP Servers',
+            status: 'warn',
+            message: `Duplicate Ruflo MCP registrations found (${locations}) — Claude Code will start both tool schemas`,
+            fix: 'Remove the legacy `ruflo`-keyed MCP registration (pre-rename duplicate) and keep the canonical `claude-flow` entry: `claude mcp add claude-flow -- npx -y ruflo@latest mcp start`. The canonical key stays `claude-flow` so the ~166 `mcp__claude-flow__*` plugin tool references keep resolving (#2206).',
+        };
+    }
+    if (rufloLocations.length > 0) {
+        return {
+            name: 'MCP Servers',
+            status: 'pass',
+            message: `${totalServersSeen} servers (ruflo configured: ${rufloLocations.join('; ')})`,
+        };
+    }
+    if (totalServersSeen > 0) {
+        return {
+            name: 'MCP Servers',
+            status: 'warn',
+            message: `${totalServersSeen} servers (ruflo not found)`,
+            fix: 'claude mcp add claude-flow -- npx -y ruflo@latest mcp start',
+        };
+    }
     return {
         name: 'MCP Servers',
         status: 'warn',

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

@@ -807,7 +807,7 @@ async function writeSettings(targetDir, options, result) {
  * "same MCP server twice under two different prefixes" duplication the
  * issue describes.
  *
- * Returns the path of the file that already declares `ruflo` (so we can
+ * Returns the path of the file that already declares `ruflo`/`claude-flow` (so we can
  * surface it in the skipped-message), or null if none found.
  */
 function detectExistingRufloMCP(targetDir) {
@@ -840,10 +840,9 @@ function detectExistingRufloMCP(targetDir) {
             if (!parsed || typeof parsed !== 'object')
                 continue;
             // (a) Top-level mcpServers (legacy / global form).
-            // #2207: accept BOTH the old 'ruflo' key AND the new 'claude-flow' key so that
-            // a prior install with either key is correctly detected as already-initialized.
-            // This also avoids the reverse problem: after #2206 fixed the generator to write
-            // 'claude-flow', a second `ruflo init` must still recognise the existing install.
+            // Accept BOTH names so init does not add a second server for the same
+            // binary when a project carries a pre-rename `claude-flow` registration
+            // and the current generator would write `ruflo` (#2612).
             if (parsed.mcpServers && typeof parsed.mcpServers === 'object') {
                 const servers = parsed.mcpServers;
                 // #2369: also recognise the legacy dist-tag keys generated by
@@ -859,10 +858,9 @@ function detectExistingRufloMCP(targetDir) {
             }
             // (b) #1840: Claude Code project-scoped registrations under
             //     parsed.projects[<projectPath>].mcpServers. Match by
-            //     normalized path against targetDir or any of its ancestors so
-            //     a `claude mcp add claude-flow` (or legacy `ruflo`) in this repo is
+            //     normalized path against targetDir or any of its ancestors so an
+            //     existing `claude-flow` or `ruflo` registration in this repo is
             //     detected even when Claude stored the key with different casing/slash style.
-            // #2207: accept both keys here too.
             if (parsed.projects && typeof parsed.projects === 'object') {
                 for (const [projectKey, projectVal] of Object.entries(parsed.projects)) {
                     if (!projectVal || typeof projectVal !== 'object')
@@ -925,16 +923,18 @@ async function writeMCPConfig(targetDir, options, result) {
         result.skipped.push('.mcp.json');
         return;
     }
-    // #1779 — Skip writing if the user already has a `ruflo`-keyed MCP
-    // server registered elsewhere (parent .mcp.json, ~/.claude.json, etc).
-    // Writing our `claude-flow`-keyed entry on top of that produces the
-    // duplicate-registration the issue describes (~250 duplicate tools).
-    // Force-mode (`--force`) bypasses this guard for users who actually
-    // want both registrations.
+    // #1779/#2612 — Skip writing if the user already has this MCP server
+    // registered elsewhere (parent .mcp.json, ~/.claude.json, etc). The
+    // canonical key is `claude-flow` (per #2206 — matches mcp__claude-flow__*
+    // plugin tool refs); a stray `ruflo`-keyed entry pointing at the same
+    // binary is the legacy-duplicate form that #2612 healed. Writing our
+    // fresh `claude-flow` entry on top of either variant starts the same
+    // binary twice under two tool namespaces. Force-mode (`--force`)
+    // bypasses this guard for users who actually want both registrations.
     if (!options.force) {
         const existingRufloPath = detectExistingRufloMCP(targetDir);
         if (existingRufloPath) {
-            result.skipped.push(`.mcp.json (existing 'ruflo' MCP registration found at ${existingRufloPath} — would create duplicate; pass --force to write anyway)`);
+            result.skipped.push(`.mcp.json (existing ruflo/claude-flow MCP registration found at ${existingRufloPath} — would create duplicate; pass --force to write anyway)`);
             return;
         }
     }
@@ -1880,7 +1880,7 @@ npx @claude-flow/cli@latest hive-mind consensus --propose "task"
 ### MCP Server Setup
 \`\`\`bash
 # Add Ruflo MCP
-claude mcp add ruflo -- npx -y ruflo@latest
+claude mcp add ruflo -- npx -y ruflo@latest mcp start
 
 # Optional servers
 claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start

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

@@ -40,10 +40,15 @@ export function generateMCPConfig(options) {
     const npmEnv = {
         npm_config_update_notifier: 'false',
     };
-    // Ruflo MCP server (core) — uses ruflo wrapper for portable npm-resolved invocation.
-    // #2206: key MUST be 'claude-flow' so all plugins resolve as mcp__claude-flow__*.
-    // The command args (ruflo@latest mcp start) are the correct wrapper invocation — only the
-    // registration KEY changes here.
+    // Ruflo MCP server (core) — the registration KEY is intentionally
+    // `claude-flow` (not `ruflo`) because #2206 established that all ~166
+    // plugin tool references use `mcp__claude-flow__*`. The invoked binary
+    // is `ruflo@latest` (the post-rename wrapper) — only the registration
+    // name stays legacy so plugin tool resolution keeps working.
+    // #2612 (duplicate `claude-flow` + `ruflo` registrations after users
+    // followed pre-rename setup docs) is healed by `ruflo doctor`, which
+    // detects the duplicate and instructs the operator to remove the
+    // extra `ruflo`-keyed entry — NOT by flipping the canonical key here.
     if (config.claudeFlow) {
         mcpServers['claude-flow'] = createMCPServerEntry(['ruflo@latest', 'mcp', 'start'], {
             ...npmEnv,
@@ -79,7 +84,7 @@ export function generateMCPCommands(options) {
     const config = options.mcp;
     if (isWindows()) {
         if (config.claudeFlow) {
-            // #2206: registration name must be 'claude-flow' to match mcp__claude-flow__* tool naming
+            // #2206: registration name must be `claude-flow` to match mcp__claude-flow__* plugin tool references
             commands.push('claude mcp add claude-flow -- cmd /c npx -y ruflo@latest mcp start');
         }
         if (config.ruvSwarm) {
@@ -91,7 +96,7 @@ export function generateMCPCommands(options) {
     }
     else {
         if (config.claudeFlow) {
-            // #2206: registration name must be 'claude-flow' to match mcp__claude-flow__* tool naming
+            // #2206: registration name must be `claude-flow` to match mcp__claude-flow__* plugin tool references
             commands.push("claude mcp add claude-flow -- npx -y ruflo@latest mcp start");
         }
         if (config.ruvSwarm) {

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

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.25.5",
+  "version": "3.25.6",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -88,7 +88,10 @@
     "test": "vitest run",
     "test:plugin-store": "npx tsx src/plugins/tests/standalone-test.ts",
     "test:pattern-store": "npx tsx src/transfer/store/tests/standalone-test.ts",
-    "postinstall": "node ./scripts/postinstall.cjs"
+    "postinstall": "node ./scripts/postinstall.cjs",
+    "prepublishOnly": "cp ../../../README.md ./README.md && rm -rf plugins && mkdir -p plugins && cp -r ../../../plugins/ruflo-metaharness plugins/ && node scripts/sign-helpers.mjs && node scripts/verify-helpers.mjs",
+    "release": "npm version prerelease --preid=alpha && npm run publish:all",
+    "publish:all": "./scripts/publish.sh"
   },
   "devDependencies": {
     "typescript": "^5.3.0",

package/v3/README.md

@@ -0,0 +1,493 @@
+# Claude Flow V3
+
+> **Modular AI Agent Coordination System** - A complete reimagining of Claude-Flow with 15-agent hierarchical mesh swarm coordination.
+
+[![Version](https://img.shields.io/badge/version-3.0.0--alpha.1-blue.svg)](https://github.com/ruvnet/claude-flow)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-green.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-purple.svg)](../LICENSE)
+
+## Introduction
+
+Claude Flow V3 is a next-generation AI agent coordination system built on 10 Architecture Decision Records (ADRs). It provides a modular, security-first, high-performance platform for orchestrating multi-agent swarms with hierarchical mesh topology.
+
+V3 represents a complete architectural overhaul:
+- **10x faster testing** with Vitest
+- **150x-12,500x faster search** with HNSW indexing
+- **2.49x-7.47x Flash Attention speedup**
+- **50-75% memory reduction**
+
+## Features
+
+### Core Capabilities
+
+- **15-Agent Hierarchical Mesh** - Queen-led coordination with specialized worker agents
+- **Domain-Driven Design** - Clean bounded contexts with separation of concerns
+- **Plugin Architecture** - Microkernel pattern for extensibility
+- **MCP-First API** - Consistent interfaces across all modules
+- **Event Sourcing** - Full audit trail for state changes
+- **Hybrid Memory Backend** - SQLite + AgentDB for optimal performance
+
+### Security
+
+- **CVE Remediation** - All known vulnerabilities addressed
+- **Input Validation** - Zod-based schema validation
+- **Secure ID Generation** - Cryptographic random IDs
+- **Path Security** - Traversal protection
+- **SQL Injection Prevention** - Parameterized queries
+
+### Performance
+
+| Metric | Target | Achieved |
+|--------|--------|----------|
+| Event Bus (100k events) | <50ms | ~6ms |
+| Map Lookup (100k gets) | <20ms | ~16ms |
+| Array.find vs Map O(1) | N/A | 978x speedup |
+| Flash Attention | 2.49x-7.47x | Validated |
+| AgentDB Search | 150x-12,500x | HNSW indexed |
+
+## Architecture
+
+### Architecture Decision Records (ADRs)
+
+| ADR | Decision |
+|-----|----------|
+| ADR-001 | Adopt agentic-flow as core foundation |
+| ADR-002 | Domain-Driven Design structure |
+| ADR-003 | Single coordination engine (UnifiedSwarmCoordinator) |
+| ADR-004 | Plugin-based architecture (microkernel) |
+| ADR-005 | MCP-first API design |
+| ADR-006 | Unified memory service (AgentDB) |
+| ADR-007 | Event sourcing for state changes |
+| ADR-008 | Vitest over Jest (10x faster) |
+| ADR-009 | Hybrid memory backend default |
+| ADR-010 | Remove Deno support (Node.js 20+ only) |
+
+### Module Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     @claude-flow/v3-monorepo                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │   security   │  │    memory    │  │    swarm     │          │
+│  │  CVE fixes   │  │   AgentDB    │  │ 15-agent     │          │
+│  │  validation  │  │   HNSW       │  │ coordination │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │ integration  │  │  performance │  │    neural    │          │
+│  │ agentic-flow │  │ Flash Attn   │  │   SONA       │          │
+│  │  bridge      │  │ benchmarks   │  │  learning    │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │     cli      │  │   testing    │  │  deployment  │          │
+│  │  commands    │  │ TDD London   │  │   release    │          │
+│  │  prompts     │  │   School     │  │    CI/CD     │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                       shared                             │   │
+│  │  types • events • core • hooks • resilience • plugins   │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Directory Structure
+
+```
+v3/
+├── @claude-flow/                    # Modular packages
+│   ├── security/                    # Security module
+│   │   └── src/
+│   │       ├── index.ts             # Password hashing, validators
+│   │       └── ...
+│   │
+│   ├── memory/                      # Memory module
+│   │   ├── src/
+│   │   │   ├── agentdb-backend.ts   # AgentDB integration
+│   │   │   ├── hnsw-index.ts        # HNSW vector indexing
+│   │   │   ├── hybrid-backend.ts    # SQLite + AgentDB
+│   │   │   ├── sqlite-backend.ts    # SQLite backend
+│   │   │   ├── cache-manager.ts     # Caching layer
+│   │   │   └── domain/              # DDD entities
+│   │   ├── benchmarks/              # Performance benchmarks
+│   │   └── examples/                # Usage examples
+│   │
+│   ├── swarm/                       # Swarm coordination
+│   │   └── src/
+│   │       ├── unified-coordinator.ts  # Main coordinator
+│   │       ├── topology-manager.ts     # Topology management
+│   │       ├── consensus/              # Consensus protocols
+│   │       └── domain/                 # DDD entities
+│   │
+│   ├── integration/                 # agentic-flow integration
+│   │   └── src/
+│   │       ├── agentic-flow-bridge.ts  # Core bridge
+│   │       ├── agent-adapter.ts        # Agent adaptation
+│   │       └── sona-adapter.ts         # SONA learning
+│   │
+│   ├── performance/                 # Performance module
+│   │   ├── src/
+│   │   │   └── framework/           # Benchmark framework
+│   │   └── benchmarks/
+│   │       ├── startup/             # Startup benchmarks
+│   │       └── attention/           # Flash Attention
+│   │
+│   ├── neural/                      # Neural/SONA module
+│   │   └── src/
+│   │       ├── algorithms/          # Learning algorithms
+│   │       └── modes/               # Neural modes
+│   │
+│   ├── cli/                         # CLI module
+│   │   ├── bin/                     # Executable
+│   │   └── src/
+│   │       └── commands/            # Command handlers
+│   │
+│   ├── testing/                     # Testing framework
+│   │   └── src/
+│   │       ├── fixtures/            # Test fixtures
+│   │       ├── mocks/               # Mock services
+│   │       ├── helpers/             # Test helpers
+│   │       └── regression/          # Regression tests
+│   │
+│   ├── shared/                      # Shared utilities
+│   │   └── src/
+│   │       ├── types/               # Shared types
+│   │       ├── events/              # Event system
+│   │       ├── core/                # Core interfaces
+│   │       ├── hooks/               # Hook system
+│   │       ├── resilience/          # Retry, circuit breaker
+│   │       ├── plugins/             # Plugin system
+│   │       └── security/            # Security utilities
+│   │
+│   └── deployment/                  # Deployment module
+│       └── src/                     # Release management
+│
+├── mcp/                             # MCP Server
+│   ├── server.ts                    # Main server
+│   ├── tools/                       # MCP tools
+│   │   ├── agent-tools.ts
+│   │   ├── swarm-tools.ts
+│   │   ├── memory-tools.ts
+│   │   └── hooks-tools.ts
+│   └── transport/                   # Transport layers
+│       ├── stdio.ts
+│       ├── http.ts
+│       └── websocket.ts
+│
+├── __tests__/                       # Integration tests
+│   └── integration/
+│       ├── memory-integration.test.ts
+│       ├── swarm-integration.test.ts
+│       ├── mcp-integration.test.ts
+│       └── workflow-integration.test.ts
+│
+├── docs/                            # Documentation
+│   ├── README.md                    # Docs overview
+│   ├── guides/                      # User guides
+│   └── implementation/              # Implementation details
+│
+├── helpers/                         # Cross-platform helpers
+│   ├── claude-flow-v3.sh            # Master helper (Linux/macOS)
+│   ├── claude-flow-v3.ps1           # Master helper (Windows)
+│   └── templates/                   # Helper templates
+│
+├── scripts/                         # Utility scripts
+│   └── quick-benchmark.mjs          # Quick perf test
+│
+├── index.ts                         # Main entry point
+├── swarm.config.ts                  # Swarm configuration
+├── vitest.config.ts                 # Test configuration
+└── package.json                     # Monorepo package
+```
+
+## Modules
+
+### @claude-flow/security
+Security-first implementation with CVE fixes, input validation, and credential management.
+
+```typescript
+import { PasswordHasher, validateInput, sanitizePath } from '@claude-flow/security';
+
+const hasher = new PasswordHasher();
+const hash = await hasher.hash('password');
+const valid = await hasher.verify('password', hash);
+```
+
+### @claude-flow/memory
+Unified memory service with AgentDB, HNSW indexing, and 150x-12,500x faster search.
+
+```typescript
+import { HybridMemoryRepository, HNSWIndex } from '@claude-flow/memory';
+
+const memory = new HybridMemoryRepository({
+  backend: 'agentdb',
+  vectorSearch: true
+});
+
+await memory.store({ key: 'knowledge', value: 'context', embedding: [...] });
+const results = await memory.search({ query: 'knowledge', limit: 10 });
+```
+
+### @claude-flow/swarm
+15-agent hierarchical mesh coordination with consensus protocols.
+
+```typescript
+import { UnifiedSwarmCoordinator } from '@claude-flow/swarm';
+
+const coordinator = new UnifiedSwarmCoordinator({
+  topology: 'hierarchical-mesh',
+  maxAgents: 15
+});
+
+await coordinator.initialize();
+await coordinator.spawnAgent({ type: 'queen-coordinator' });
+```
+
+### @claude-flow/integration
+Deep integration with agentic-flow@alpha per ADR-001.
+
+```typescript
+import { AgenticFlowBridge } from '@claude-flow/integration';
+
+const bridge = new AgenticFlowBridge();
+await bridge.initialize();
+const agent = await bridge.createAgent({ type: 'coder' });
+```
+
+### @claude-flow/performance
+Benchmarking framework with Flash Attention validation.
+
+```typescript
+import { BenchmarkRunner, formatTime } from '@claude-flow/performance';
+
+const runner = new BenchmarkRunner();
+const result = await runner.run('map-lookup', () => map.get(key), {
+  iterations: 100000,
+  targetTime: 20
+});
+```
+
+### @claude-flow/neural
+SONA learning integration for self-optimizing agents.
+
+```typescript
+import { SONAAdapter } from '@claude-flow/neural';
+
+const sona = new SONAAdapter();
+await sona.train({ patterns: learningData });
+const prediction = await sona.predict(context);
+```
+
+### @claude-flow/cli
+Modern CLI with interactive prompts and formatted output.
+
+```bash
+npx @claude-flow/cli swarm init --topology hierarchical-mesh
+npx @claude-flow/cli agent spawn --type queen-coordinator
+npx @claude-flow/cli memory search "knowledge"
+```
+
+### @claude-flow/testing
+TDD London School framework with mocks, fixtures, and regression testing.
+
+```typescript
+import { createMockAgent, createTestFixture } from '@claude-flow/testing';
+
+const mockAgent = createMockAgent({ type: 'coder' });
+const fixture = createTestFixture('swarm-coordination');
+```
+
+### @claude-flow/shared
+Common types, events, utilities, and core interfaces.
+
+```typescript
+import { EventBus, Result, success, failure } from '@claude-flow/shared';
+import type { AgentId, TaskStatus } from '@claude-flow/shared/types';
+```
+
+### @claude-flow/deployment
+Release management and CI/CD automation.
+
+```typescript
+import { ReleaseManager } from '@claude-flow/deployment';
+
+const release = new ReleaseManager();
+await release.prepare({ version: '3.0.0', changelog: '...' });
+```
+
+## Usage
+
+### Quick Start
+
+```typescript
+import { initializeV3Swarm } from '@claude-flow/v3';
+
+// Initialize the swarm
+const swarm = await initializeV3Swarm();
+
+// Spawn agents
+await swarm.spawnAllAgents();
+
+// Submit a task
+const task = swarm.submitTask({
+  type: 'implementation',
+  title: 'Implement feature X',
+  description: 'Detailed description...',
+  domain: 'core',
+  phase: 'phase-2-core',
+  priority: 'high'
+});
+
+// Wait for completion
+const result = await swarm.waitForTask(task.id);
+```
+
+### Import Specific Modules
+
+```typescript
+// Import everything
+import * as claudeFlow from '@claude-flow/v3';
+
+// Or import specific modules for tree-shaking
+import { UnifiedSwarmCoordinator } from '@claude-flow/swarm';
+import { PasswordHasher } from '@claude-flow/security';
+import { HNSWIndex } from '@claude-flow/memory';
+```
+
+### MCP Server
+
+```typescript
+import { createMCPServer } from '@claude-flow/v3/mcp';
+
+const server = createMCPServer({
+  transport: 'stdio',
+  tools: ['agent', 'swarm', 'memory', 'hooks']
+});
+
+await server.start();
+```
+
+## Helper System
+
+Cross-platform automation for V3 development:
+
+```bash
+# Linux/macOS
+./helpers/claude-flow-v3.sh init
+./helpers/claude-flow-v3.sh status
+./helpers/claude-flow-v3.sh update domain 3
+
+# Windows (PowerShell)
+.\helpers\claude-flow-v3.ps1 init
+.\helpers\claude-flow-v3.ps1 status
+.\helpers\claude-flow-v3.ps1 update domain 3
+```
+
+Features:
+- **Progress Tracking**: Real-time domain/agent/performance metrics
+- **Checkpointing**: Auto-commit with development milestones
+- **Validation**: Environment and configuration verification
+- **GitHub Integration**: PR management and issue tracking
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ruvnet/claude-flow.git
+cd claude-flow/v3
+
+# Install dependencies
+pnpm install
+
+# Build all modules
+pnpm build
+```
+
+## Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Run integration tests
+pnpm test:integration
+
+# Run specific module tests
+pnpm test:memory
+pnpm test:swarm
+pnpm test:security
+
+# Run benchmarks
+pnpm bench
+
+# Quick benchmark (no dependencies)
+node scripts/quick-benchmark.mjs
+
+# Coverage report
+pnpm test:coverage
+```
+
+## Performance Targets
+
+| Category | Metric | Target |
+|----------|--------|--------|
+| **Search** | AgentDB HNSW | 150x-12,500x faster |
+| **Attention** | Flash Attention | 2.49x-7.47x speedup |
+| **Memory** | Reduction | 50-75% |
+| **Code** | Total lines | <5,000 |
+| **Startup** | Cold start | <500ms |
+| **Learning** | SONA adaptation | <0.05ms |
+
+## Links
+
+### Documentation
+- [Docs Overview](./docs/README.md)
+- [Implementation Details](./docs/implementation/)
+- [User Guides](./docs/guides/)
+- [Helper System](./helpers/README.md)
+
+### Modules
+- [@claude-flow/security](./@claude-flow/security/)
+- [@claude-flow/memory](./@claude-flow/memory/)
+- [@claude-flow/swarm](./@claude-flow/swarm/)
+- [@claude-flow/integration](./@claude-flow/integration/)
+- [@claude-flow/performance](./@claude-flow/performance/)
+- [@claude-flow/neural](./@claude-flow/neural/)
+- [@claude-flow/cli](./@claude-flow/cli/)
+- [@claude-flow/testing](./@claude-flow/testing/)
+- [@claude-flow/shared](./@claude-flow/shared/)
+- [@claude-flow/deployment](./@claude-flow/deployment/)
+
+### Examples
+- [AgentDB Example](./@claude-flow/memory/examples/agentdb-example.ts)
+- [Cross-Platform Usage](./@claude-flow/memory/examples/cross-platform-usage.ts)
+
+### MCP Tools
+- [Agent Tools](./mcp/tools/agent-tools.ts)
+- [Swarm Tools](./mcp/tools/swarm-tools.ts)
+- [Memory Tools](./mcp/tools/memory-tools.ts)
+- [Hooks Tools](./mcp/tools/hooks-tools.ts)
+
+### External
+- [GitHub Repository](https://github.com/ruvnet/claude-flow)
+- [agentic-flow Integration](https://github.com/ruvnet/agentic-flow)
+- [AgentDB](https://github.com/ruvnet/agentdb)
+
+## Requirements
+
+- **Node.js**: >=20.0.0
+- **pnpm**: >=8.0.0
+- **TypeScript**: >=5.3.0
+
+## License
+
+MIT License - See [LICENSE](../LICENSE) for details.
+
+---
+
+**Built with the SPARC methodology and 15-agent hierarchical mesh coordination.**