Claude-Flow v2.7.47
├── Source Files: 376 TypeScript files (~130,000 lines)
├── Dependencies: agentic-flow (^1.9.4), ruv-swarm, flow-nexus
├── Architecture: Multi-layered (CLI, Core, MCP, Swarm, Hive-Mind)
└── Configuration: 14.2 MB across 7 directories

# Immediate fix required
npm update @anthropic-ai/claude-code@^2.0.31
npm update @modelcontextprotocol/sdk@^1.24.0
npm audit fix --force

// CURRENT (INSECURE)
const hash = crypto.createHash('sha256')
  .update('salt' + password)  // Hardcoded salt!
  .digest('hex');

// v3 FIX (SECURE)
import * as bcrypt from 'bcrypt';
const SALT_ROUNDS = 12;
const hash = await bcrypt.hash(password, SALT_ROUNDS);

// REMOVE these hardcoded credentials
email: '[email protected]'
password: 'admin123'  // CRITICAL RISK

// v3: Generate random on installation
const adminPassword = crypto.randomBytes(32).toString('hex');

┌─────────────────────────────────────────────────────────────┐
│                     Claude-Flow v3                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Compatibility Layer (v2 API)            │   │
│  │   - SwarmCoordinator wrapper                         │   │
│  │   - AgentManager adapter                             │   │
│  │   - Memory system bridge                             │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           agentic-flow@alpha Core Engine             │   │
│  │   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │   │
│  │   │  SONA   │ │  Flash  │ │ AgentDB │ │   MCP   │   │   │
│  │   │Learning │ │Attention│ │ Vector  │ │  Tools  │   │   │
│  │   └─────────┘ └─────────┘ └─────────┘ └─────────┘   │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Plugin Architecture                     │   │
│  │   - HiveMind (optional)                              │   │
│  │   - Maestro (optional)                               │   │
│  │   - Neural training (optional)                       │   │
│  │   - GitHub integration (optional)                    │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

// src/v3/integrations/agentic-flow-adapter.ts
import { EnhancedAgentDBWrapper, AttentionCoordinator } from 'agentic-flow/core';

export class AgenticFlowAdapter {
  private wrapper: EnhancedAgentDBWrapper;
  private coordinator: AttentionCoordinator;

  constructor(config: AgenticFlowConfig) {
    this.wrapper = new EnhancedAgentDBWrapper({
      enableAttention: config.enableAttention ?? true,
      enableGNN: config.enableGNN ?? true,
      attentionConfig: { type: config.attentionType ?? 'flash' },
      runtimePreference: config.runtime ?? 'napi'
    });
  }

  async initialize(): Promise<void> {
    await this.wrapper.initialize();
    this.coordinator = new AttentionCoordinator(
      this.wrapper.getAttentionService()
    );
  }

  // Backward compatible agent creation
  async createAgent(template: string, options?: AgentOptions): Promise<string> {
    return await this.wrapper.spawnAgent(template, {
      sonaProfile: options?.learning ?? 'balanced',
      reflexionEnabled: options?.reflexion ?? true
    });
  }

  // Enhanced search with GNN
  async searchPatterns(query: string, k = 5): Promise<Pattern[]> {
    return await this.wrapper.gnnEnhancedSearch(query, { k });
  }

  // Consensus-based coordination
  async coordinateAgents(outputs: AgentOutput[]): Promise<Consensus> {
    return await this.coordinator.coordinateAgents(outputs, 'flash');
  }
}

Windows Installation Failure:
- better-sqlite3 requires native compilation
- node-gyp build fails on many Windows systems
- 17 files directly use better-sqlite3

// src/v3/memory/backends/database-provider.ts
export type DatabaseProvider = 'better-sqlite3' | 'sql.js' | 'json' | 'auto';

export async function createDatabase(
  path: string,
  options: { provider?: DatabaseProvider } = {}
): Promise<Database> {
  const provider = options.provider ?? 'auto';

  if (provider === 'auto') {
    // Platform-aware selection
    if (process.platform === 'win32') {
      try {
        // Try native first (if build tools available)
        return await createBetterSqlite(path);
      } catch {
        // Fall back to sql.js (always works)
        return await createSqlJs(path);
      }
    } else {
      // Linux/macOS: native is reliable
      return await createBetterSqlite(path);
    }
  }

  // Explicit provider selection
  switch (provider) {
    case 'better-sqlite3': return await createBetterSqlite(path);
    case 'sql.js': return await createSqlJs(path);
    case 'json': return await createJsonFallback(path);
  }
}

// src/v3/memory/backends/sqljs-backend.ts
import initSqlJs, { Database as SqlJsDatabase } from 'sql.js';

export class SqlJsBackend implements DatabaseBackend {
  private db: SqlJsDatabase;
  private wasmUrl: string;

  async initialize(path: string): Promise<void> {
    const SQL = await initSqlJs({
      locateFile: file => `${this.wasmUrl}/${file}`
    });

    // Load existing data or create new
    if (await fileExists(path)) {
      const buffer = await fs.readFile(path);
      this.db = new SQL.Database(buffer);
    } else {
      this.db = new SQL.Database();
    }
  }

  // Same interface as better-sqlite3
  prepare(sql: string): Statement {
    return new SqlJsStatement(this.db.prepare(sql));
  }

  exec(sql: string): void {
    this.db.exec(sql);
  }

  // Persist changes
  async persist(): Promise<void> {
    const data = this.db.export();
    await fs.writeFile(this.path, Buffer.from(data));
  }
}

// package.json
{
  "dependencies": {
    "sql.js": "^1.10.0"  // +1.2MB (WASM)
  },
  "optionalDependencies": {
    "better-sqlite3": "^12.2.0"  // Native, optional
  }
}

#!/bin/bash
# cleanup-v3.sh

# 1. Remove build artifacts from git
git rm -r --cached dist-cjs/
echo "dist-cjs/" >> .gitignore

# 2. Remove backup files
rm -f bin/pair-old.js
rm -f bin/pair-enhanced.backup.js
rm -f bin/stream-chain.js.backup
rm -f bin/training-pipeline-old.js.bak
rm -f docs/reasoningbank/models/*/memory.db.backup

# 3. Remove duplicate lock file (choose one)
rm -f package-lock.json  # If using pnpm
# OR
rm -f pnpm-lock.yaml     # If using npm

# 4. Remove empty directory
rmdir claude-flow-wiki/

# 5. Clean up .gitignore duplicates
# (manual edit to remove 8 duplicate "hive-mind-prompt-*.txt" entries)

# 6. Commit
git add .
git commit -m "chore: v3 repository cleanup - remove 49MB of artifacts"

# Add to .gitignore
dist-cjs/
*.backup
*-old.js
*.bak

# Runtime databases (shouldn't be tracked)
.swarm/memory.db
.hive-mind/memory.db
.claude-flow/**/*.db

.claude/
├── config.json                    # Single source of truth
├── settings.prod.json             # Production (from settings-enhanced)
├── settings.dev.json              # Development with debug
├── settings.github.json           # GitHub automation
├── sparc-modes.json               # Unchanged
│
├── agents/                        # Reorganized (76 files)
│   ├── core/                      # coder, tester, reviewer, researcher, planner
│   ├── orchestration/             # swarm, hive-mind, coordinators
│   ├── platform/                  # github, flow-nexus, devops
│   ├── specialized/               # ml, mobile, backend
│   ├── methodology/               # sparc agents
│   ├── consensus/                 # byzantine, raft, gossip
│   └── testing/                   # validation, tdd
│
├── commands/                      # Reorganized (93 files → 5 categories)
│   ├── core/                      # agents, swarm, sparc
│   ├── platform/                  # github, hive-mind, flow-nexus
│   ├── operations/                # memory, training, monitoring
│   ├── automation/                # hooks, workflows, coordination
│   └── utilities/                 # analysis, optimization
│
├── skills/                        # Reorganized (28 skills → 5 domains)
│   ├── ai-coordination/           # swarm, hive-mind, orchestration
│   ├── data-processing/           # agentdb, stream-chain, reasoningbank
│   ├── development/               # pair-programming, sparc-methodology
│   ├── platform/                  # flow-nexus, github
│   └── optimization/              # performance, verification
│
├── checkpoints/
│   ├── active/                    # Last 20 only
│   └── archive/                   # Compressed older files
│
└── .meta/                         # NEW: Configuration reference
    ├── CONFIGURATION.md
    ├── MIGRATION_LOG.md
    └── OPTIMIZATION_STATUS.md

.claude-flow/
├── swarm-config.json              # Includes agent profiles
├── coordination/                  # NEW: Unified runtime
│   ├── memory.db                  # Merged swarm + hive-mind
│   ├── metrics/
│   └── sessions/
├── training/
│   ├── models/                    # Latest only
│   ├── latest-results.json        # Single rotated file
│   └── archive/                   # Compressed old data
└── validation/
    └── latest-validation.json     # Single file

# REMOVE these directories
.swarm/                            # → .claude-flow/coordination/
.hive-mind/                        # → .claude-flow/coordination/
.ruv-swarm/                        # Archive or remove

// settings.prod.json - Production configuration
{
  "hooks": {
    "PreToolUse": [...],     // Full hook suite
    "PostToolUse": [...],
    "PreCompact": [...],
    "Stop": [...]
  },
  "neural": { "enabled": true },
  "agenticFlow": { "enabled": true, "sona": "balanced" }
}

// settings.dev.json - Development configuration
{
  "hooks": {
    "PreToolUse": [...],     // Debug hooks
  },
  "debug": { "verbose": true, "tracing": true }
}

// settings.github.json - GitHub automation
{
  "hooks": {
    "PreToolUse": [...],     // GitHub-specific
  },
  "github": { "autoReview": true, "swarmReview": true }
}

# Archive old checkpoints (keep last 20)
cd .claude/checkpoints

# Count current
ls -1 | wc -l  # 3,720 files!

# Archive old ones
mkdir -p archive
find . -maxdepth 1 -name "*.json" -mtime +7 -exec mv {} archive/ \;

# Compress archive
tar -czf archive.tar.gz archive/
rm -rf archive/

# Result: 8.4MB → ~500KB

agents/
├── core/           (5)   # Essential: coder, tester, reviewer, researcher, planner
├── orchestration/  (8)   # Coordinators: hierarchical, mesh, adaptive, queen, etc.
├── platform/       (15)  # External: github-*, flow-nexus-*, devops
├── specialized/    (12)  # Domain: backend-dev, mobile-dev, ml-developer
├── methodology/    (10)  # Process: sparc-*, tdd-london, production-validator
├── consensus/      (14)  # Distributed: byzantine, raft, gossip, crdt
└── testing/        (12)  # Quality: perf-analyzer, code-analyzer, benchmark

// .claude/agents/core/coder.md (v3 enhanced)
---
name: coder
version: 3.0.0
category: core
agentic-flow:
  sona-profile: research      # +55% quality
  attention: flash            # 2.49x-7.47x speedup
  learning: enabled
  reflexion: enabled
capabilities:
  - code-generation
  - refactoring
  - debugging
  - testing
---

# Coder Agent

Implementation specialist leveraging agentic-flow@alpha for enhanced code generation.

## Enhanced Capabilities (v3)

- **SONA Learning**: Learns from past implementations
- **Flash Attention**: Faster context processing
- **Reflexion**: Self-improvement through feedback

# .claude/skills/ai-coordination/swarm-orchestration/SKILL.md
---
name: swarm-orchestration
domain: ai-coordination
version: 3.0.0
triggers:
  - "orchestrate swarm"
  - "multi-agent"
  - "parallel agents"
agentic-flow:
  required: true
  features:
    - flash-attention
    - consensus-coordination
---

commands/
├── core/           # agents, swarm, sparc (18 commands)
├── platform/       # github, hive-mind, flow-nexus (22 commands)
├── operations/     # memory, training, monitoring (25 commands)
├── automation/     # hooks, workflows, coordination (18 commands)
└── utilities/      # analysis, optimization, helpers (10 commands)

// .claude/config.json (v3)
{
  "version": "3.0.0",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "commands": ["npx claude-flow hooks pre-tool --tool=$TOOL_NAME"]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "commands": ["npx claude-flow hooks post-tool --tool=$TOOL_NAME"]
      }
    ],
    "PreCompact": [
      {
        "commands": ["npx claude-flow hooks pre-compact --session=$SESSION_ID"]
      }
    ],
    "Stop": [
      {
        "commands": ["npx claude-flow hooks session-end --export-metrics true"]
      }
    ]
  },
  // Reference from other files
  "extends": {
    "production": "./settings.prod.json",
    "development": "./settings.dev.json",
    "github": "./settings.github.json"
  }
}

// src/v3/hooks/learning-hooks.ts
export const agenticFlowHooks = {
  PreToolUse: async (context: HookContext) => {
    // Query similar past operations
    const patterns = await agenticFlow.searchPatterns(context.tool);
    if (patterns.length > 0) {
      context.suggestions = patterns.map(p => p.recommendation);
    }
  },

  PostToolUse: async (context: HookContext) => {
    // Store for learning
    await agenticFlow.storePattern(
      context.tool,
      context.result,
      context.success ? 1.0 : 0.0
    );
  },

  PostTask: async (context: HookContext) => {
    // Update agent skill library
    if (context.success && context.quality > 0.8) {
      await agenticFlow.addToSkillLibrary(
        context.agentId,
        context.taskType,
        context.output
      );
    }
  }
};

// src/v3/compatibility/v2-adapter.ts
import { SwarmCoordinator as V3Coordinator } from '../coordination';
import { AgenticFlowAdapter } from '../integrations';

/**
 * v2 API compatibility layer
 * All v2.x code continues to work unchanged
 */
export class SwarmCoordinator {
  private v3: V3Coordinator;
  private adapter: AgenticFlowAdapter;

  // v2 API method signatures preserved
  async spawnAgent(profile: AgentProfile): Promise<string> {
    // Internally uses v3 with agentic-flow
    return await this.v3.createAgent(profile.type, {
      learning: true,  // v3 enhancement, transparent to v2 callers
      ...profile
    });
  }

  async assignTask(task: Task): Promise<void> {
    // v2 behavior preserved, v3 enhancements automatic
    await this.v3.executeTask(task);
  }

  // v2 event emissions preserved
  on(event: string, handler: Function): void {
    this.v3.on(event, handler);
  }
}

// src/v3/compatibility/config-migrator.ts
export async function migrateConfig(v2Config: V2Config): Promise<V3Config> {
  return {
    version: '3.0.0',

    // Preserve all v2 settings
    ...v2Config,

    // Add v3 enhancements with sensible defaults
    agenticFlow: {
      enabled: true,
      attention: 'flash',
      sona: 'balanced',
      learning: true
    },

    // Migrate deprecated fields
    hooks: migrateHooks(v2Config.hooks),
    agents: migrateAgents(v2Config.agents)
  };
}

// Auto-migration on first run
export async function autoMigrate(): Promise<void> {
  const configPath = '.claude/config.json';
  const config = await loadConfig(configPath);

  if (!config.version || config.version < '3.0.0') {
    const migrated = await migrateConfig(config);
    await saveConfig(configPath, migrated);
    await backupConfig(configPath + '.v2.backup', config);
    console.log('✅ Configuration migrated to v3');
  }
}

// Phase 1 (v3.0.0): Warnings only
/** @deprecated Use AgenticFlowAdapter.createAgent() instead */
export async function legacySpawnAgent(profile: AgentProfile): Promise<string> {
  console.warn('⚠️ legacySpawnAgent is deprecated. Use AgenticFlowAdapter.');
  return await agenticFlow.createAgent(profile.type, profile);
}

// Phase 2 (v3.2.0): Loud warnings
// Phase 3 (v4.0.0): Remove deprecated APIs

// tests/v3/backward-compatibility.test.ts
describe('v2 API Compatibility', () => {
  it('should work with v2 SwarmCoordinator API', async () => {
    // v2 code unchanged
    const coordinator = new SwarmCoordinator();
    const agentId = await coordinator.spawnAgent({ type: 'coder' });
    await coordinator.assignTask({ description: 'test' });

    expect(agentId).toBeDefined();
  });

  it('should emit v2 events', async () => {
    const events: string[] = [];
    coordinator.on('agent:spawned', () => events.push('spawned'));
    coordinator.on('task:completed', () => events.push('completed'));

    await coordinator.spawnAgent({ type: 'coder' });
    await coordinator.assignTask({ description: 'test' });

    expect(events).toContain('spawned');
    expect(events).toContain('completed');
  });

  it('should migrate v2 config automatically', async () => {
    const v2Config = { agents: [...], hooks: [...] };  // v2 format
    const v3Config = await migrateConfig(v2Config);

    expect(v3Config.version).toBe('3.0.0');
    expect(v3Config.agenticFlow.enabled).toBe(true);
  });
});

src/v3/
├── integrations/
│   ├── agentic-flow-adapter.ts
│   └── index.ts
├── memory/
│   ├── backends/
│   │   ├── sqljs-backend.ts
│   │   └── database-provider.ts
│   └── hybrid-memory.ts
├── coordination/
│   ├── unified-coordinator.ts
│   └── consensus-engine.ts
├── compatibility/
│   ├── v2-adapter.ts
│   └── config-migrator.ts
├── hooks/
│   └── learning-hooks.ts
└── plugins/
    ├── plugin-loader.ts
    ├── hive-mind/
    ├── maestro/
    └── neural/

docs/v3/
├── CLAUDE-FLOW-V3-MASTER-PLAN.md (this file)
├── MIGRATION-GUIDE.md
├── API-REFERENCE.md
└── ARCHITECTURE.md

# Deprecated
src/api/claude-client-v2.5.ts

# Backups
bin/pair-old.js
bin/pair-enhanced.backup.js
bin/stream-chain.js.backup
bin/training-pipeline-old.js.bak
docs/reasoningbank/models/*/memory.db.backup

# Build artifacts
dist-cjs/ (remove from git)

# Empty
claude-flow-wiki/

# Duplicate settings
.claude/settings-complete.json
.claude/settings-enhanced.json (merge into settings.prod.json)
.claude/settings-checkpoint-*.json
.claude/settings.reasoningbank-*.json
.claude/settings-npx-hooks.json

package.json                    # Add sql.js, update agentic-flow
.gitignore                      # Add dist-cjs, cleanup duplicates
.claude/config.json             # Add v3 structure, unified hooks
tsconfig.json                   # Add v3 paths

# Install v3 dependencies
npm install [email protected] sql.js

# Run security fixes
npm audit fix --force

# Cleanup repository
./scripts/cleanup-v3.sh

# Run migration
npx claude-flow migrate --to v3

# Verify backward compatibility
npm run test:compatibility

# Build v3
npm run build:v3

// .claude/config.json (minimal v3)
{
  "version": "3.0.0",
  "agenticFlow": {
    "enabled": true,
    "attention": "flash",
    "sona": "balanced"
  },
  "extends": "./settings.prod.json"
}

// v3 with backward compatibility
import { SwarmCoordinator } from 'claude-flow';  // v2 API still works

// v3 native
import { AgenticFlowAdapter } from 'claude-flow/v3';
const adapter = new AgenticFlowAdapter({ sona: 'research' });
await adapter.initialize();