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

package/.claude/skills/v3-ddd-architecture/SKILL.md

@@ -0,0 +1,442 @@
+---
+name: "V3 DDD Architecture"
+description: "Domain-Driven Design architecture for claude-flow v3. Implements modular, bounded context architecture with clean separation of concerns and microkernel pattern."
+---
+
+# V3 DDD Architecture
+
+## What This Skill Does
+
+Designs and implements Domain-Driven Design (DDD) architecture for claude-flow v3, decomposing god objects into bounded contexts, implementing clean architecture patterns, and enabling modular, testable code structure.
+
+## Quick Start
+
+```bash
+# Initialize DDD architecture analysis
+Task("Architecture analysis", "Analyze current architecture and design DDD boundaries", "core-architect")
+
+# Domain modeling (parallel)
+Task("Domain decomposition", "Break down orchestrator god object into domains", "core-architect")
+Task("Context mapping", "Map bounded contexts and relationships", "core-architect")
+Task("Interface design", "Design clean domain interfaces", "core-architect")
+```
+
+## DDD Implementation Strategy
+
+### Current Architecture Analysis
+```
+├── PROBLEMATIC: core/orchestrator.ts (1,440 lines - GOD OBJECT)
+│   ├── Task management responsibilities
+│   ├── Session management responsibilities
+│   ├── Health monitoring responsibilities
+│   ├── Lifecycle management responsibilities
+│   └── Event coordination responsibilities
+│
+└── TARGET: Modular DDD Architecture
+    ├── core/domains/
+    │   ├── task-management/
+    │   ├── session-management/
+    │   ├── health-monitoring/
+    │   ├── lifecycle-management/
+    │   └── event-coordination/
+    └── core/shared/
+        ├── interfaces/
+        ├── value-objects/
+        └── domain-events/
+```
+
+### Domain Boundaries
+
+#### 1. Task Management Domain
+```typescript
+// core/domains/task-management/
+interface TaskManagementDomain {
+  // Entities
+  Task: TaskEntity;
+  TaskQueue: TaskQueueEntity;
+
+  // Value Objects
+  TaskId: TaskIdVO;
+  TaskStatus: TaskStatusVO;
+  Priority: PriorityVO;
+
+  // Services
+  TaskScheduler: TaskSchedulingService;
+  TaskValidator: TaskValidationService;
+
+  // Repository
+  TaskRepository: ITaskRepository;
+}
+```
+
+#### 2. Session Management Domain
+```typescript
+// core/domains/session-management/
+interface SessionManagementDomain {
+  // Entities
+  Session: SessionEntity;
+  SessionState: SessionStateEntity;
+
+  // Value Objects
+  SessionId: SessionIdVO;
+  SessionStatus: SessionStatusVO;
+
+  // Services
+  SessionLifecycle: SessionLifecycleService;
+  SessionPersistence: SessionPersistenceService;
+
+  // Repository
+  SessionRepository: ISessionRepository;
+}
+```
+
+#### 3. Health Monitoring Domain
+```typescript
+// core/domains/health-monitoring/
+interface HealthMonitoringDomain {
+  // Entities
+  HealthCheck: HealthCheckEntity;
+  Metric: MetricEntity;
+
+  // Value Objects
+  HealthStatus: HealthStatusVO;
+  Threshold: ThresholdVO;
+
+  // Services
+  HealthCollector: HealthCollectionService;
+  AlertManager: AlertManagementService;
+
+  // Repository
+  MetricsRepository: IMetricsRepository;
+}
+```
+
+## Microkernel Architecture Pattern
+
+### Core Kernel
+```typescript
+// core/kernel/claude-flow-kernel.ts
+export class ClaudeFlowKernel {
+  private domains: Map<string, Domain> = new Map();
+  private eventBus: DomainEventBus;
+  private dependencyContainer: Container;
+
+  async initialize(): Promise<void> {
+    // Load core domains
+    await this.loadDomain('task-management', new TaskManagementDomain());
+    await this.loadDomain('session-management', new SessionManagementDomain());
+    await this.loadDomain('health-monitoring', new HealthMonitoringDomain());
+
+    // Wire up domain events
+    this.setupDomainEventHandlers();
+  }
+
+  async loadDomain(name: string, domain: Domain): Promise<void> {
+    await domain.initialize(this.dependencyContainer);
+    this.domains.set(name, domain);
+  }
+
+  getDomain<T extends Domain>(name: string): T {
+    const domain = this.domains.get(name);
+    if (!domain) {
+      throw new DomainNotLoadedError(name);
+    }
+    return domain as T;
+  }
+}
+```
+
+### Plugin Architecture
+```typescript
+// core/plugins/
+interface DomainPlugin {
+  name: string;
+  version: string;
+  dependencies: string[];
+
+  initialize(kernel: ClaudeFlowKernel): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+// Example: Swarm Coordination Plugin
+export class SwarmCoordinationPlugin implements DomainPlugin {
+  name = 'swarm-coordination';
+  version = '3.0.0';
+  dependencies = ['task-management', 'session-management'];
+
+  async initialize(kernel: ClaudeFlowKernel): Promise<void> {
+    const taskDomain = kernel.getDomain<TaskManagementDomain>('task-management');
+    const sessionDomain = kernel.getDomain<SessionManagementDomain>('session-management');
+
+    // Register swarm coordination services
+    this.swarmCoordinator = new UnifiedSwarmCoordinator(taskDomain, sessionDomain);
+    kernel.registerService('swarm-coordinator', this.swarmCoordinator);
+  }
+}
+```
+
+## Domain Events & Integration
+
+### Event-Driven Communication
+```typescript
+// core/shared/domain-events/
+abstract class DomainEvent {
+  public readonly eventId: string;
+  public readonly aggregateId: string;
+  public readonly occurredOn: Date;
+  public readonly eventVersion: number;
+
+  constructor(aggregateId: string) {
+    this.eventId = crypto.randomUUID();
+    this.aggregateId = aggregateId;
+    this.occurredOn = new Date();
+    this.eventVersion = 1;
+  }
+}
+
+// Task domain events
+export class TaskAssignedEvent extends DomainEvent {
+  constructor(
+    taskId: string,
+    public readonly agentId: string,
+    public readonly priority: Priority
+  ) {
+    super(taskId);
+  }
+}
+
+export class TaskCompletedEvent extends DomainEvent {
+  constructor(
+    taskId: string,
+    public readonly result: TaskResult,
+    public readonly duration: number
+  ) {
+    super(taskId);
+  }
+}
+
+// Event handlers
+@EventHandler(TaskCompletedEvent)
+export class TaskCompletedHandler {
+  constructor(
+    private metricsRepository: IMetricsRepository,
+    private sessionService: SessionLifecycleService
+  ) {}
+
+  async handle(event: TaskCompletedEvent): Promise<void> {
+    // Update metrics
+    await this.metricsRepository.recordTaskCompletion(
+      event.aggregateId,
+      event.duration
+    );
+
+    // Update session state
+    await this.sessionService.markTaskCompleted(
+      event.aggregateId,
+      event.result
+    );
+  }
+}
+```
+
+## Clean Architecture Layers
+
+```typescript
+// Architecture layers
+┌─────────────────────────────────────────┐
+│              Presentation               │  ← CLI, API, UI
+├─────────────────────────────────────────┤
+│              Application                │  ← Use Cases, Commands
+├─────────────────────────────────────────┤
+│               Domain                    │  ← Entities, Services, Events
+├─────────────────────────────────────────┤
+│            Infrastructure               │  ← DB, MCP, External APIs
+└─────────────────────────────────────────┘
+
+// Dependency direction: Outside → Inside
+// Domain layer has NO external dependencies
+```
+
+### Application Layer (Use Cases)
+```typescript
+// core/application/use-cases/
+export class AssignTaskUseCase {
+  constructor(
+    private taskRepository: ITaskRepository,
+    private agentRepository: IAgentRepository,
+    private eventBus: DomainEventBus
+  ) {}
+
+  async execute(command: AssignTaskCommand): Promise<TaskResult> {
+    // 1. Validate command
+    await this.validateCommand(command);
+
+    // 2. Load aggregates
+    const task = await this.taskRepository.findById(command.taskId);
+    const agent = await this.agentRepository.findById(command.agentId);
+
+    // 3. Business logic (in domain)
+    task.assignTo(agent);
+
+    // 4. Persist changes
+    await this.taskRepository.save(task);
+
+    // 5. Publish domain events
+    task.getUncommittedEvents().forEach(event =>
+      this.eventBus.publish(event)
+    );
+
+    // 6. Return result
+    return TaskResult.success(task);
+  }
+}
+```
+
+## Module Configuration
+
+### Bounded Context Modules
+```typescript
+// core/domains/task-management/module.ts
+export const taskManagementModule = {
+  name: 'task-management',
+
+  entities: [
+    TaskEntity,
+    TaskQueueEntity
+  ],
+
+  valueObjects: [
+    TaskIdVO,
+    TaskStatusVO,
+    PriorityVO
+  ],
+
+  services: [
+    TaskSchedulingService,
+    TaskValidationService
+  ],
+
+  repositories: [
+    { provide: ITaskRepository, useClass: SqliteTaskRepository }
+  ],
+
+  eventHandlers: [
+    TaskAssignedHandler,
+    TaskCompletedHandler
+  ]
+};
+```
+
+## Migration Strategy
+
+### Phase 1: Extract Domain Services
+```typescript
+// Extract services from orchestrator.ts
+const extractionPlan = {
+  week1: [
+    'TaskManager → task-management domain',
+    'SessionManager → session-management domain'
+  ],
+  week2: [
+    'HealthMonitor → health-monitoring domain',
+    'LifecycleManager → lifecycle-management domain'
+  ],
+  week3: [
+    'EventCoordinator → event-coordination domain',
+    'Wire up domain events'
+  ]
+};
+```
+
+### Phase 2: Implement Clean Interfaces
+```typescript
+// Clean separation with dependency injection
+export class TaskController {
+  constructor(
+    @Inject('AssignTaskUseCase') private assignTask: AssignTaskUseCase,
+    @Inject('CompleteTaskUseCase') private completeTask: CompleteTaskUseCase
+  ) {}
+
+  async assign(request: AssignTaskRequest): Promise<TaskResponse> {
+    const command = AssignTaskCommand.fromRequest(request);
+    const result = await this.assignTask.execute(command);
+    return TaskResponse.fromResult(result);
+  }
+}
+```
+
+### Phase 3: Plugin System
+```typescript
+// Enable plugin-based extensions
+const pluginSystem = {
+  core: ['task-management', 'session-management', 'health-monitoring'],
+  optional: ['swarm-coordination', 'learning-integration', 'performance-monitoring']
+};
+```
+
+## Testing Strategy
+
+### Domain Testing (London School TDD)
+```typescript
+// Pure domain logic testing
+describe('Task Entity', () => {
+  let task: TaskEntity;
+  let mockAgent: jest.Mocked<AgentEntity>;
+
+  beforeEach(() => {
+    task = new TaskEntity(TaskId.create(), 'Test task');
+    mockAgent = createMock<AgentEntity>();
+  });
+
+  it('should assign to agent when valid', () => {
+    mockAgent.canAcceptTask.mockReturnValue(true);
+
+    task.assignTo(mockAgent);
+
+    expect(task.assignedAgent).toBe(mockAgent);
+    expect(task.status.value).toBe('assigned');
+  });
+
+  it('should emit TaskAssignedEvent when assigned', () => {
+    mockAgent.canAcceptTask.mockReturnValue(true);
+
+    task.assignTo(mockAgent);
+
+    const events = task.getUncommittedEvents();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toBeInstanceOf(TaskAssignedEvent);
+  });
+});
+```
+
+## Success Metrics
+
+- [ ] **God Object Elimination**: orchestrator.ts (1,440 lines) → 5 focused domains (<300 lines each)
+- [ ] **Bounded Context Isolation**: 100% domain independence
+- [ ] **Plugin Architecture**: Core + optional modules loading
+- [ ] **Clean Architecture**: Dependency inversion maintained
+- [ ] **Event-Driven Communication**: Loose coupling between domains
+- [ ] **Test Coverage**: >90% domain logic coverage
+
+## Related V3 Skills
+
+- `v3-core-implementation` - Implementation of DDD domains
+- `v3-memory-unification` - AgentDB integration within bounded contexts
+- `v3-swarm-coordination` - Swarm coordination as domain plugin
+- `v3-performance-optimization` - Performance optimization across domains
+
+## Usage Examples
+
+### Complete Domain Extraction
+```bash
+# Full DDD architecture implementation
+Task("DDD architecture implementation",
+     "Extract orchestrator into DDD domains with clean architecture",
+     "core-architect")
+```
+
+### Plugin Development
+```bash
+# Create domain plugin
+npm run create:plugin -- --name swarm-coordination --template domain
+```

package/.claude/skills/v3-integration-deep/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: "V3 Deep Integration"
+description: "Deep agentic-flow@alpha integration implementing ADR-001. Eliminates 10,000+ duplicate lines by building claude-flow as specialized extension rather than parallel implementation."
+---
+
+# V3 Deep Integration
+
+## What This Skill Does
+
+Transforms claude-flow from parallel implementation to specialized extension of agentic-flow@alpha, eliminating massive code duplication while achieving performance improvements and feature parity.
+
+## Quick Start
+
+```bash
+# Initialize deep integration
+Task("Integration architecture", "Design agentic-flow@alpha adapter layer", "v3-integration-architect")
+
+# Feature integration (parallel)
+Task("SONA integration", "Integrate 5 SONA learning modes", "v3-integration-architect")
+Task("Flash Attention", "Implement 2.49x-7.47x speedup", "v3-integration-architect")
+Task("AgentDB coordination", "Setup 150x-12,500x search", "v3-integration-architect")
+```
+
+## Code Deduplication Strategy
+
+### Current Overlap → Integration
+```
+┌─────────────────────────────────────────┐
+│  claude-flow          agentic-flow      │
+├─────────────────────────────────────────┤
+│ SwarmCoordinator  →   Swarm System      │ 80% overlap (eliminate)
+│ AgentManager      →   Agent Lifecycle   │ 70% overlap (eliminate)
+│ TaskScheduler     →   Task Execution    │ 60% overlap (eliminate)
+│ SessionManager    →   Session Mgmt      │ 50% overlap (eliminate)
+└─────────────────────────────────────────┘
+
+TARGET: <5,000 lines (vs 15,000+ currently)
+```
+
+## agentic-flow@alpha Feature Integration
+
+### SONA Learning Modes
+```typescript
+class SONAIntegration {
+  async initializeMode(mode: SONAMode): Promise<void> {
+    switch(mode) {
+      case 'real-time':   // ~0.05ms adaptation
+      case 'balanced':    // general purpose
+      case 'research':    // deep exploration
+      case 'edge':        // resource-constrained
+      case 'batch':       // high-throughput
+    }
+    await this.agenticFlow.sona.setMode(mode);
+  }
+}
+```
+
+### Flash Attention Integration
+```typescript
+class FlashAttentionIntegration {
+  async optimizeAttention(): Promise<AttentionResult> {
+    return this.agenticFlow.attention.flashAttention({
+      speedupTarget: '2.49x-7.47x',
+      memoryReduction: '50-75%',
+      mechanisms: ['multi-head', 'linear', 'local', 'global']
+    });
+  }
+}
+```
+
+### AgentDB Coordination
+```typescript
+class AgentDBIntegration {
+  async setupCrossAgentMemory(): Promise<void> {
+    await this.agentdb.enableCrossAgentSharing({
+      indexType: 'HNSW',
+      speedupTarget: '150x-12500x',
+      dimensions: 1536
+    });
+  }
+}
+```
+
+### MCP Tools Integration
+```typescript
+class MCPToolsIntegration {
+  async integrateBuiltinTools(): Promise<void> {
+    // Leverage 213 pre-built tools
+    const tools = await this.agenticFlow.mcp.getAvailableTools();
+    await this.registerClaudeFlowSpecificTools(tools);
+
+    // Use 19 hook types
+    const hookTypes = await this.agenticFlow.hooks.getTypes();
+    await this.configureClaudeFlowHooks(hookTypes);
+  }
+}
+```
+
+## Migration Implementation
+
+### Phase 1: Adapter Layer
+```typescript
+import { Agent as AgenticFlowAgent } from 'agentic-flow@alpha';
+
+export class ClaudeFlowAgent extends AgenticFlowAgent {
+  async handleClaudeFlowTask(task: ClaudeTask): Promise<TaskResult> {
+    return this.executeWithSONA(task);
+  }
+
+  // Backward compatibility
+  async legacyCompatibilityLayer(oldAPI: any): Promise<any> {
+    return this.adaptToNewAPI(oldAPI);
+  }
+}
+```
+
+### Phase 2: System Migration
+```typescript
+class SystemMigration {
+  async migrateSwarmCoordination(): Promise<void> {
+    // Replace SwarmCoordinator (800+ lines) with agentic-flow Swarm
+    const swarmConfig = await this.extractSwarmConfig();
+    await this.agenticFlow.swarm.initialize(swarmConfig);
+  }
+
+  async migrateAgentManagement(): Promise<void> {
+    // Replace AgentManager (1,736+ lines) with agentic-flow lifecycle
+    const agents = await this.extractActiveAgents();
+    for (const agent of agents) {
+      await this.agenticFlow.agent.create(agent);
+    }
+  }
+
+  async migrateTaskExecution(): Promise<void> {
+    // Replace TaskScheduler with agentic-flow task graph
+    const tasks = await this.extractTasks();
+    await this.agenticFlow.task.executeGraph(this.buildTaskGraph(tasks));
+  }
+}
+```
+
+### Phase 3: Cleanup
+```typescript
+class CodeCleanup {
+  async removeDeprecatedCode(): Promise<void> {
+    // Remove massive duplicate implementations
+    await this.removeFile('src/core/SwarmCoordinator.ts');    // 800+ lines
+    await this.removeFile('src/agents/AgentManager.ts');      // 1,736+ lines
+    await this.removeFile('src/task/TaskScheduler.ts');       // 500+ lines
+
+    // Total reduction: 10,000+ → <5,000 lines
+  }
+}
+```
+
+## RL Algorithm Integration
+
+```typescript
+class RLIntegration {
+  algorithms = [
+    'PPO', 'DQN', 'A2C', 'MCTS', 'Q-Learning',
+    'SARSA', 'Actor-Critic', 'Decision-Transformer'
+  ];
+
+  async optimizeAgentBehavior(): Promise<void> {
+    for (const algorithm of this.algorithms) {
+      await this.agenticFlow.rl.train(algorithm, {
+        episodes: 1000,
+        rewardFunction: this.claudeFlowRewardFunction
+      });
+    }
+  }
+}
+```
+
+## Performance Integration
+
+### Flash Attention Targets
+```typescript
+const attentionBenchmark = {
+  baseline: 'current attention mechanism',
+  target: '2.49x-7.47x improvement',
+  memoryReduction: '50-75%',
+  implementation: 'agentic-flow@alpha Flash Attention'
+};
+```
+
+### AgentDB Search Performance
+```typescript
+const searchBenchmark = {
+  baseline: 'linear search in current systems',
+  target: '150x-12,500x via HNSW indexing',
+  implementation: 'agentic-flow@alpha AgentDB'
+};
+```
+
+## Backward Compatibility
+
+### Gradual Migration
+```typescript
+class BackwardCompatibility {
+  // Phase 1: Dual operation
+  async enableDualOperation(): Promise<void> {
+    this.oldSystem.continue();
+    this.newSystem.initialize();
+    this.syncState(this.oldSystem, this.newSystem);
+  }
+
+  // Phase 2: Feature-by-feature migration
+  async migrateGradually(): Promise<void> {
+    const features = this.getAllFeatures();
+    for (const feature of features) {
+      await this.migrateFeature(feature);
+      await this.validateFeatureParity(feature);
+    }
+  }
+
+  // Phase 3: Complete transition
+  async completeTransition(): Promise<void> {
+    await this.validateFullParity();
+    await this.deprecateOldSystem();
+  }
+}
+```
+
+## Success Metrics
+
+- **Code Reduction**: <5,000 lines orchestration (vs 15,000+)
+- **Performance**: 2.49x-7.47x Flash Attention speedup
+- **Search**: 150x-12,500x AgentDB improvement
+- **Memory**: 50-75% usage reduction
+- **Feature Parity**: 100% v2 functionality maintained
+- **SONA**: <0.05ms adaptation time
+- **Integration**: All 213 MCP tools + 19 hook types available
+
+## Related V3 Skills
+
+- `v3-memory-unification` - Memory system integration
+- `v3-performance-optimization` - Performance target validation
+- `v3-swarm-coordination` - Swarm system migration
+- `v3-security-overhaul` - Secure integration patterns