v3/implementation/adrs/v3-adrs.md
Project: Claude-Flow v3 Reimagining Date Range: 2026-01-03 onwards Status: Proposed Decision Authority: Architecture Team
| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-001 | Adopt agentic-flow as Core Foundation | In Progress | 2026-01-03 |
| ADR-002 | Implement Domain-Driven Design Structure | Implemented ✅ | 2026-01-03 |
| ADR-003 | Single Coordination Engine | Implemented ✅ | 2026-01-03 |
| ADR-004 | Plugin-Based Architecture | Implemented ✅ | 2026-01-03 |
| ADR-005 | MCP-First API Design | Implemented ✅ | 2026-01-03 |
| ADR-006 | Unified Memory Service | Implemented ✅ | 2026-01-03 |
| ADR-007 | Event Sourcing for State Changes | In Progress | 2026-01-03 |
| ADR-008 | Vitest Over Jest | Implemented ✅ | 2026-01-03 |
| ADR-009 | Hybrid Memory Backend as Default | Implemented ✅ | 2026-01-03 |
| ADR-010 | Remove Deno Support | Implemented ✅ | 2026-01-03 |
| ADR-011 | LLM Provider System | Implemented ✅ | 2026-01-05 |
| ADR-012 | MCP Security Features | Implemented ✅ | 2026-01-05 |
| ADR-013 | Core Security Module | Implemented ✅ | 2026-01-05 |
| ADR-014 | Cross-Platform Workers System | Implemented ✅ | 2026-01-05 |
Status: Proposed Date: 2026-01-03 Decision Makers: Architecture Team Context Owner: Lead Architect
Claude-Flow v2.x implements its own agent orchestration, coordination, and execution systems. This duplicates significant functionality available in agentic-flow, our primary dependency. The current architecture treats agentic-flow as an optional add-on rather than the foundation.
Current State:
Analysis:
Functionality Overlap:
┌─────────────────────────────────────┐
│ claude-flow │ agentic-flow │
├─────────────────────────────────────┤
│ SwarmCoordinator │ Swarm System │ 80% overlap
│ AgentManager │ Agent Lifecycle │ 70% overlap
│ TaskScheduler │ Task Execution │ 60% overlap
│ SessionManager │ Session Mgmt │ 50% overlap
└─────────────────────────────────────┘
We will adopt agentic-flow as the core foundation for v3, building claude-flow as a specialized extension rather than a parallel implementation.
Specifically:
Pros:
Cons:
Alternatives Considered:
Status Quo (Keep Custom Implementation)
Fork agentic-flow
Build Abstraction Over Both
Phase 1: Foundation (Week 1-2)
// Create agentic-flow adapter layer
import { Agent as AgenticFlowAgent } from 'agentic-flow';
export class ClaudeFlowAgent extends AgenticFlowAgent {
// Add claude-flow specific capabilities
async handleClaudeFlowTask(task: ClaudeTask): Promise<TaskResult> {
// Claude-specific logic
}
}
Phase 2: Migration (Week 3-8)
Phase 3: Optimization (Week 9-12)
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| agentic-flow breaking changes | Medium | High | Pin version, maintain adapter |
| Performance regression | Low | Medium | Benchmark continuously |
| Feature limitations | Medium | Medium | Contribute upstream |
| Migration complexity | High | Medium | Phased approach, compatibility layer |
Status: Proposed Date: 2026-01-03
Current v2 structure organizes code by technical layer (cli/, core/, mcp/, swarm/), making it difficult to understand complete features and leading to high coupling between layers.
Problems:
Example: Agent Management Feature
Current (scattered):
├── cli/commands/agent.ts # CLI interface
├── core/orchestrator.ts # Orchestration logic
├── agents/agent-manager.ts # Management logic
├── mcp/tools.ts # MCP tools
└── swarm/coordinator.ts # Coordination logic
Proposed (cohesive):
└── agent-lifecycle/
├── api/cli/agent-commands.ts
├── api/mcp/agent-tools.ts
├── application/agent-service.ts
├── domain/agent.ts
└── infrastructure/agent-repository.ts
We will restructure v3 using Domain-Driven Design (DDD) principles with clear bounded contexts.
Structure:
src/
├── agent-lifecycle/ # Bounded Context 1
│ ├── domain/ # Business logic, entities
│ ├── application/ # Use cases, services
│ ├── infrastructure/ # Persistence, external systems
│ └── api/ # External interfaces (CLI, MCP)
├── task-execution/ # Bounded Context 2
├── memory-management/ # Bounded Context 3
├── coordination/ # Bounded Context 4
├── shared-kernel/ # Shared types and utilities
└── infrastructure/ # Cross-cutting concerns
Layer Rules:
Benefits:
Costs:
Directory Template:
domain-name/
├── domain/
│ ├── models/ # Entities, value objects
│ ├── interfaces/ # Repository interfaces
│ ├── events/ # Domain events
│ └── services/ # Domain services
├── application/
│ ├── services/ # Application services
│ ├── handlers/ # Event handlers
│ └── queries/ # Query services (CQRS)
├── infrastructure/
│ ├── repositories/ # Repository implementations
│ ├── adapters/ # External system adapters
│ └── persistence/ # Persistence implementations
└── api/
├── cli/ # CLI commands
├── mcp/ # MCP tools
└── dto/ # Data transfer objects
Example: Task Execution Domain
// domain/models/task.ts
export class Task {
constructor(
readonly id: TaskId,
readonly type: TaskType,
private status: TaskStatus
) {}
assign(agentId: AgentId): void {
if (this.status !== TaskStatus.Created) {
throw new InvalidStateError('Task already assigned');
}
this.status = TaskStatus.Assigned;
this.emit(new TaskAssigned(this.id, agentId));
}
}
// application/services/task-service.ts
export class TaskExecutionService {
constructor(
private taskRepo: ITaskRepository,
private agentService: AgentLifecycleService,
private eventBus: IEventBus
) {}
async createTask(spec: TaskSpec): Promise<TaskId> {
const task = Task.create(spec);
await this.taskRepo.save(task);
return task.id;
}
}
// api/cli/task-commands.ts
export class CreateTaskCommand {
constructor(private taskService: TaskExecutionService) {}
async execute(args: CreateTaskArgs): Promise<void> {
const taskId = await this.taskService.createTask(args);
console.log(`Task created: ${taskId}`);
}
}
Status: Proposed Date: 2026-01-03
v2 has four overlapping coordination systems:
This creates:
We will consolidate to a single CoordinationEngine with pluggable strategies.
Architecture:
class CoordinationEngine {
constructor(
private topology: ITopologyStrategy,
private scheduler: ITaskScheduler,
private consensus: IConsensusProtocol,
private loadBalancer: ILoadBalancer
) {}
// Core coordination methods
async assignTask(task: Task): Promise<AgentId>;
async electLeader(): Promise<AgentId>;
async rebalanceLoad(): Promise<void>;
}
// Topology strategies (pluggable)
interface ITopologyStrategy {
type: 'mesh' | 'hierarchical' | 'centralized';
// ... methods
}
// Specialized behaviors as plugins
class HiveMindPlugin implements ClaudeFlowPlugin {
enhance(engine: CoordinationEngine): void {
engine.addConsensusProtocol(new ByzantineConsensus());
engine.addStrategy('queen-led', new QueenLedStrategy());
}
}
Pros:
Cons:
Strategy Selection Guide:
Use Case → Topology Strategy
├── Simple tasks → Centralized
├── Large teams → Hierarchical
├── Resilience → Mesh
└── Consensus → Byzantine (via plugin)
Phase 1: Core Engine
class CoordinationEngine {
private strategies = new Map<string, ITopologyStrategy>();
registerStrategy(name: string, strategy: ITopologyStrategy): void {
this.strategies.set(name, strategy);
}
async initialize(config: CoordinationConfig): Promise<void> {
const strategy = this.strategies.get(config.topology);
if (!strategy) throw new Error('Unknown topology');
this.topology = strategy;
await this.topology.initialize();
}
}
Phase 2: Built-in Strategies
Phase 3: Plugin Strategies
Status: Proposed Date: 2026-01-03
v2 bundles all features (Hive Mind, Maestro, Neural, Verification) into core, making the system large and complex even for users who only need basic features.
We will adopt a microkernel architecture with plugins for optional features.
Core:
Plugins:
interface ClaudeFlowPlugin {
name: string;
version: string;
dependencies?: string[];
initialize(context: PluginContext): Promise<void>;
shutdown(): Promise<void>;
// Optional extensions
registerAgentTypes?(): AgentTypeDefinition[];
registerTaskTypes?(): TaskTypeDefinition[];
registerMCPTools?(): MCPTool[];
registerCLICommands?(): Command[];
registerMemoryBackends?(): MemoryBackendFactory[];
}
// Plugin loading
const core = new ClaudeFlowCore();
await core.loadPlugin(new HiveMindPlugin());
await core.initialize();
Benefits:
Costs:
Status: Proposed Date: 2026-01-03
v2 CLI commands contain business logic, making it hard to use claude-flow programmatically or via other interfaces.
All functionality will be exposed as MCP tools first, with CLI as a thin wrapper.
Architecture:
MCP Tools (primary interface)
↓
Application Services (business logic)
↓
Domain Models
CLI Commands = MCP tool wrappers
Programmatic API = Direct service access
// MCP tool (primary)
const spawnAgentTool: MCPTool = {
name: 'agent/spawn',
handler: async (input, context) => {
return context.agentService.spawnAgent(input);
}
};
// CLI command (wrapper)
class SpawnCommand {
async execute(args: SpawnArgs): Promise<void> {
const result = await mcpClient.callTool('agent/spawn', args);
console.log(result);
}
}
Status: Proposed Date: 2026-01-03
v2 has 6 memory implementations: MemoryManager, DistributedMemory, SwarmMemory, AdvancedMemoryManager, SQLiteBackend, MarkdownBackend.
Single MemoryService with pluggable backends.
class MemoryService {
constructor(
private backend: IMemoryBackend, // SQLite, AgentDB, or Hybrid
private cache: MemoryCache,
private indexer: MemoryIndexer
) {}
}
// Backend selection via config
{
memory: {
backend: 'hybrid', // 'sqlite' | 'agentdb' | 'hybrid'
cacheSize: 100,
indexing: true
}
}
| Backend | Use Case | Pros | Cons |
|---|---|---|---|
| SQLite | Structured queries, ACID | Fast, reliable | No vector search |
| AgentDB | Semantic search, RAG | Vector similarity | Requires setup |
| Hybrid | General purpose | Best of both | Higher memory |
Status: Proposed Date: 2026-01-03
v2 uses direct state mutation, making it hard to:
Use event sourcing pattern for critical state changes.
// Domain events
class AgentSpawned extends DomainEvent {
constructor(
readonly agentId: AgentId,
readonly type: AgentType,
readonly timestamp: Date
) {}
}
// Event store
interface IEventStore {
append(event: DomainEvent): Promise<void>;
getEvents(aggregateId: string): Promise<DomainEvent[]>;
subscribe(handler: EventHandler): void;
}
// Rebuild state from events
class Agent {
static fromEvents(events: DomainEvent[]): Agent {
const agent = new Agent();
events.forEach(e => agent.apply(e));
return agent;
}
private apply(event: DomainEvent): void {
if (event instanceof AgentSpawned) {
this.id = event.agentId;
this.type = event.type;
}
// ... more events
}
}
Apply to:
Don't apply to:
Status: Proposed Date: 2026-01-03
v2 uses Jest for testing. Vitest is a modern alternative that's faster and has better ESM support.
Migrate to Vitest for v3.
Vitest Advantages:
Migration:
// package.json
{
"devDependencies": {
"vitest": "^1.0.0",
"vite": "^5.0.0"
},
"scripts": {
"test": "vitest",
"test:ui": "vitest --ui"
}
}
Status: Proposed Date: 2026-01-03
Need to choose default memory backend for v3.
HybridBackend (SQLite + AgentDB) as default.
SQLite: Reliable, fast for structured queries AgentDB: Vector search for semantic queries Together: Best of both worlds
Configuration:
{
memory: {
backend: 'hybrid',
sqlite: {
path: './claude-flow.db'
},
agentdb: {
dimensions: 1536, // OpenAI embeddings
indexType: 'HNSW'
}
}
}
class HybridBackend implements IMemoryBackend {
constructor(
private structured: SQLiteBackend,
private vector: AgentDBBackend
) {}
async store(entry: MemoryEntry): Promise<void> {
// Store in both
await Promise.all([
this.structured.store(entry),
this.vector.store(entry)
]);
}
async query(query: MemoryQuery): Promise<MemoryEntry[]> {
if (query.semantic) {
// Use vector search
return this.vector.query(query);
} else {
// Use SQL
return this.structured.query(query);
}
}
}
Status: Proposed Date: 2026-01-03
v2 attempted to support both Node.js and Deno runtimes. This added complexity without clear benefit.
Issues:
v3 will support Node.js 20+ only. Deno support removed.
Focus on Node.js:
If Deno support needed:
// Remove Deno-specific code
- src/cli/main.deno.ts ❌
- deno.json ❌
- Deno imports ❌
// Keep Node-only
+ src/cli/main.ts ✅
+ package.json ✅
+ Node imports ✅
For future ADRs, use this template:
Status: Proposed | Accepted | Deprecated | Superseded Date: YYYY-MM-DD
What is the issue we're trying to solve?
What are we going to do?
Why this decision? What alternatives did we consider?
What are the trade-offs?
How will we do this?
How do we know it worked?
Links to other ADRs
Document Maintained By: Architecture Team Last Updated: 2026-01-05 Next Review: After Sprint 4 (2026-02-01)