elsabro 2.3.0 → 3.8.0

package/references/collaboration-patterns.md

@@ -0,0 +1,851 @@
+# Agent Collaboration Patterns (v3.3)
+
+Patrones avanzados de colaboración entre agentes para orquestación de tareas complejas.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    COLLABORATION PATTERNS                                │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    PATTERN LIBRARY                               │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │ Supervisor  │  │ Hierarchical│  │  Consensus  │              │    │
+│  │  │  (1 coord)  │  │ (tree)      │  │  (voting)   │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │   Debate    │  │ Round-Robin │  │   Swarm     │              │    │
+│  │  │ (adversary) │  │ (rotation)  │  │ (emergent)  │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    COLLABORATION MANAGER                         │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │  Pattern Selection  →  Team Assembly  →  Execution      │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    COMMUNICATION LAYER                           │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │  Messages   │  │  Shared     │  │  Blackboard │              │    │
+│  │  │  (direct)   │  │  Memory     │  │  (broadcast)│              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Patrones Disponibles
+
+### 1. Supervisor Pattern
+
+Un agente supervisor coordina y delega a agentes workers.
+
+```
+         ┌─────────────┐
+         │ Supervisor  │
+         │   (Opus)    │
+         └──────┬──────┘
+                │
+     ┌──────────┼──────────┐
+     │          │          │
+     ▼          ▼          ▼
+┌─────────┐ ┌─────────┐ ┌─────────┐
+│ Worker1 │ │ Worker2 │ │ Worker3 │
+│ (Haiku) │ │ (Haiku) │ │ (Haiku) │
+└─────────┘ └─────────┘ └─────────┘
+```
+
+```typescript
+interface SupervisorConfig {
+  supervisor: {
+    agentType: string;
+    model: 'opus' | 'sonnet';
+    maxDelegations: number;
+  };
+  workers: {
+    agentTypes: string[];
+    model: 'haiku' | 'sonnet';
+    maxConcurrent: number;
+  };
+  routing: 'round-robin' | 'capability' | 'load-balance';
+}
+
+class SupervisorPattern implements CollaborationPattern {
+  name = 'supervisor';
+
+  async execute(task: Task, config: SupervisorConfig): Promise<CollaborationResult> {
+    const supervisor = await this.createAgent(config.supervisor);
+    const workers = await this.createWorkerPool(config.workers);
+
+    // Supervisor analyzes task
+    const plan = await supervisor.analyze(task);
+
+    // Delegate subtasks to workers
+    const results: SubtaskResult[] = [];
+
+    for (const subtask of plan.subtasks) {
+      const worker = this.selectWorker(workers, subtask, config.routing);
+      const result = await worker.execute(subtask);
+      results.push(result);
+
+      // Supervisor can re-delegate on failure
+      if (!result.success && plan.allowRetry) {
+        const retryResult = await this.retryWithDifferentWorker(
+          workers, subtask, worker
+        );
+        results.push(retryResult);
+      }
+    }
+
+    // Supervisor synthesizes results
+    const finalResult = await supervisor.synthesize(results);
+
+    return {
+      pattern: 'supervisor',
+      success: finalResult.success,
+      result: finalResult,
+      metrics: {
+        delegations: plan.subtasks.length,
+        workerUtilization: this.calculateUtilization(workers)
+      }
+    };
+  }
+}
+```
+
+**Uso ideal**: Tareas con subtareas claras e independientes.
+
+---
+
+### 2. Hierarchical Pattern
+
+Estructura de árbol con múltiples niveles de supervisión.
+
+```
+              ┌─────────────┐
+              │   Leader    │
+              │   (Opus)    │
+              └──────┬──────┘
+                     │
+         ┌───────────┼───────────┐
+         │                       │
+         ▼                       ▼
+   ┌─────────────┐         ┌─────────────┐
+   │ Team Lead A │         │ Team Lead B │
+   │  (Sonnet)   │         │  (Sonnet)   │
+   └──────┬──────┘         └──────┬──────┘
+          │                       │
+    ┌─────┼─────┐           ┌─────┼─────┐
+    │     │     │           │     │     │
+    ▼     ▼     ▼           ▼     ▼     ▼
+   W1    W2    W3          W4    W5    W6
+```
+
+```typescript
+interface HierarchicalConfig {
+  levels: HierarchyLevel[];
+  communicationMode: 'strict' | 'skip-level-allowed';
+  escalationPolicy: EscalationPolicy;
+}
+
+interface HierarchyLevel {
+  name: string;
+  agentType: string;
+  model: string;
+  maxChildren: number;
+  responsibilities: string[];
+}
+
+class HierarchicalPattern implements CollaborationPattern {
+  name = 'hierarchical';
+
+  async execute(task: Task, config: HierarchicalConfig): Promise<CollaborationResult> {
+    // Build hierarchy tree
+    const root = await this.buildHierarchy(config.levels);
+
+    // Top-down task decomposition
+    const taskTree = await this.decomposeTask(task, root);
+
+    // Bottom-up execution
+    const result = await this.executeBottomUp(taskTree);
+
+    // Rollup results
+    return this.rollupResults(result);
+  }
+
+  private async executeBottomUp(node: TaskNode): Promise<NodeResult> {
+    // Execute children first (if any)
+    if (node.children.length > 0) {
+      const childResults = await Promise.all(
+        node.children.map(child => this.executeBottomUp(child))
+      );
+
+      // Parent synthesizes child results
+      return node.agent.synthesize(childResults);
+    }
+
+    // Leaf node executes directly
+    return node.agent.execute(node.task);
+  }
+}
+```
+
+**Uso ideal**: Proyectos grandes con equipos especializados.
+
+---
+
+### 3. Consensus Pattern
+
+Múltiples agentes votan para tomar decisiones.
+
+```
+┌─────────┐  ┌─────────┐  ┌─────────┐
+│ Agent 1 │  │ Agent 2 │  │ Agent 3 │
+│ (Opus)  │  │ (Opus)  │  │ (Opus)  │
+└────┬────┘  └────┬────┘  └────┬────┘
+     │            │            │
+     ▼            ▼            ▼
+     └────────────┼────────────┘
+                  │
+           ┌──────▼──────┐
+           │   Voting    │
+           │   System    │
+           └──────┬──────┘
+                  │
+           ┌──────▼──────┐
+           │  Consensus  │
+           │   Result    │
+           └─────────────┘
+```
+
+```typescript
+interface ConsensusConfig {
+  voters: {
+    count: number;
+    agentType: string;
+    model: string;
+  };
+  votingStrategy: 'majority' | 'unanimous' | 'weighted' | 'quorum';
+  quorumThreshold?: number;  // For 'quorum' strategy
+  weights?: Record<string, number>;  // For 'weighted' strategy
+  maxRounds: number;
+  tieBreaker: 'random' | 'first' | 'supervisor';
+}
+
+interface Vote {
+  agentId: string;
+  decision: string;
+  confidence: number;
+  reasoning: string;
+}
+
+class ConsensusPattern implements CollaborationPattern {
+  name = 'consensus';
+
+  async execute(task: Task, config: ConsensusConfig): Promise<CollaborationResult> {
+    const voters = await this.createVoters(config.voters);
+
+    let round = 0;
+    let consensus: string | null = null;
+
+    while (round < config.maxRounds && !consensus) {
+      round++;
+
+      // Each voter analyzes independently
+      const votes = await Promise.all(
+        voters.map(voter => voter.vote(task))
+      );
+
+      // Count votes
+      consensus = this.countVotes(votes, config);
+
+      // If no consensus, share reasoning and re-vote
+      if (!consensus) {
+        await this.shareReasoning(voters, votes);
+      }
+    }
+
+    // Handle tie
+    if (!consensus) {
+      consensus = await this.breakTie(votes, config.tieBreaker);
+    }
+
+    return {
+      pattern: 'consensus',
+      success: true,
+      result: consensus,
+      metrics: {
+        rounds: round,
+        votes: votes,
+        consensusReached: round < config.maxRounds
+      }
+    };
+  }
+
+  private countVotes(votes: Vote[], config: ConsensusConfig): string | null {
+    const counts = new Map<string, number>();
+
+    for (const vote of votes) {
+      const weight = config.weights?.[vote.agentId] || 1;
+      const current = counts.get(vote.decision) || 0;
+      counts.set(vote.decision, current + weight);
+    }
+
+    const totalWeight = votes.reduce(
+      (sum, v) => sum + (config.weights?.[v.agentId] || 1), 0
+    );
+
+    for (const [decision, count] of counts) {
+      switch (config.votingStrategy) {
+        case 'majority':
+          if (count > totalWeight / 2) return decision;
+          break;
+        case 'unanimous':
+          if (count === totalWeight) return decision;
+          break;
+        case 'quorum':
+          if (count >= totalWeight * (config.quorumThreshold || 0.66)) return decision;
+          break;
+        case 'weighted':
+          if (count > totalWeight / 2) return decision;
+          break;
+      }
+    }
+
+    return null;
+  }
+}
+```
+
+**Uso ideal**: Decisiones críticas, code reviews, evaluaciones.
+
+---
+
+### 4. Debate Pattern
+
+Agentes argumentan posiciones opuestas para refinar decisiones.
+
+```
+┌─────────────┐           ┌─────────────┐
+│  Advocate   │ ◄──────► │   Critic    │
+│   (Pro)     │  Debate   │   (Con)     │
+└──────┬──────┘           └──────┬──────┘
+       │                         │
+       └───────────┬─────────────┘
+                   │
+            ┌──────▼──────┐
+            │    Judge    │
+            │   (Opus)    │
+            └──────┬──────┘
+                   │
+            ┌──────▼──────┐
+            │   Refined   │
+            │   Decision  │
+            └─────────────┘
+```
+
+```typescript
+interface DebateConfig {
+  advocate: {
+    agentType: string;
+    model: string;
+    position: 'pro' | 'assigned';
+  };
+  critic: {
+    agentType: string;
+    model: string;
+    position: 'con' | 'devils-advocate';
+  };
+  judge: {
+    agentType: string;
+    model: string;
+  };
+  rounds: number;
+  format: 'structured' | 'free-form';
+}
+
+interface DebateRound {
+  round: number;
+  advocateArgument: string;
+  criticArgument: string;
+  advocateRebuttal?: string;
+  criticRebuttal?: string;
+}
+
+class DebatePattern implements CollaborationPattern {
+  name = 'debate';
+
+  async execute(task: Task, config: DebateConfig): Promise<CollaborationResult> {
+    const advocate = await this.createAgent(config.advocate);
+    const critic = await this.createAgent(config.critic);
+    const judge = await this.createAgent(config.judge);
+
+    const rounds: DebateRound[] = [];
+
+    // Initial positions
+    const advocatePosition = await advocate.formPosition(task);
+    const criticPosition = await critic.formPosition(task);
+
+    for (let i = 0; i < config.rounds; i++) {
+      const round: DebateRound = {
+        round: i + 1,
+        advocateArgument: '',
+        criticArgument: ''
+      };
+
+      // Advocate presents argument
+      round.advocateArgument = await advocate.argue(
+        task,
+        criticPosition,
+        rounds
+      );
+
+      // Critic responds
+      round.criticArgument = await critic.argue(
+        task,
+        advocatePosition,
+        rounds
+      );
+
+      // Rebuttals (if structured format)
+      if (config.format === 'structured') {
+        round.advocateRebuttal = await advocate.rebut(round.criticArgument);
+        round.criticRebuttal = await critic.rebut(round.advocateArgument);
+      }
+
+      rounds.push(round);
+    }
+
+    // Judge evaluates debate
+    const judgment = await judge.evaluate({
+      task,
+      advocatePosition,
+      criticPosition,
+      rounds
+    });
+
+    return {
+      pattern: 'debate',
+      success: true,
+      result: judgment.decision,
+      metrics: {
+        rounds: rounds.length,
+        judgment: judgment,
+        strengthOfArguments: {
+          advocate: judgment.advocateScore,
+          critic: judgment.criticScore
+        }
+      }
+    };
+  }
+}
+```
+
+**Uso ideal**: Decisiones de arquitectura, trade-off analysis, risk assessment.
+
+---
+
+### 5. Round-Robin Pattern
+
+Agentes toman turnos procesando partes de una tarea.
+
+```
+┌─────────┐    ┌─────────┐    ┌─────────┐
+│ Agent 1 │───►│ Agent 2 │───►│ Agent 3 │
+└────┬────┘    └────┬────┘    └────┬────┘
+     │              │              │
+     ▼              ▼              ▼
+   Part 1        Part 2         Part 3
+     │              │              │
+     └──────────────┼──────────────┘
+                    │
+             ┌──────▼──────┐
+             │   Combined  │
+             │   Result    │
+             └─────────────┘
+```
+
+```typescript
+interface RoundRobinConfig {
+  agents: {
+    agentType: string;
+    model: string;
+    specialty?: string;
+  }[];
+  rotationMode: 'sequential' | 'by-specialty' | 'adaptive';
+  handoffMode: 'full-context' | 'summary-only' | 'delta-only';
+  maxRounds?: number;
+}
+
+class RoundRobinPattern implements CollaborationPattern {
+  name = 'round-robin';
+
+  async execute(task: Task, config: RoundRobinConfig): Promise<CollaborationResult> {
+    const agents = await this.createAgents(config.agents);
+    const parts = await this.partitionTask(task, agents.length);
+
+    let context = { task, previousResults: [] as PartResult[] };
+    const results: PartResult[] = [];
+
+    for (let i = 0; i < parts.length; i++) {
+      const agent = this.selectAgent(agents, parts[i], config.rotationMode, i);
+
+      // Prepare handoff context
+      const handoff = this.prepareHandoff(context, config.handoffMode);
+
+      // Execute part
+      const result = await agent.execute(parts[i], handoff);
+      results.push(result);
+
+      // Update context
+      context.previousResults.push(result);
+    }
+
+    // Combine results
+    const combined = await this.combineResults(results);
+
+    return {
+      pattern: 'round-robin',
+      success: combined.success,
+      result: combined,
+      metrics: {
+        partsProcessed: parts.length,
+        agentUtilization: this.calculateUtilization(agents, results)
+      }
+    };
+  }
+
+  private prepareHandoff(
+    context: Context,
+    mode: string
+  ): Handoff {
+    switch (mode) {
+      case 'full-context':
+        return { ...context };
+      case 'summary-only':
+        return {
+          task: context.task,
+          previousSummary: this.summarize(context.previousResults)
+        };
+      case 'delta-only':
+        return {
+          task: context.task,
+          lastResult: context.previousResults.slice(-1)[0]
+        };
+      default:
+        return context;
+    }
+  }
+}
+```
+
+**Uso ideal**: Pipelines de procesamiento, iteraciones de refinamiento.
+
+---
+
+### 6. Swarm Pattern
+
+Agentes auto-organizados trabajan en paralelo con comunicación emergente.
+
+```
+     ┌─────┐   ┌─────┐   ┌─────┐
+     │  A  │───│  B  │───│  C  │
+     └──┬──┘   └──┬──┘   └──┬──┘
+        │         │         │
+     ┌──┼─────────┼─────────┼──┐
+     │  │  BLACKBOARD (shared) │
+     │  │    ┌─────────┐       │
+     │  └───►│ Problem │◄──────┤
+     │       │ Space   │       │
+     │       └─────────┘       │
+     │           │             │
+     │     ┌─────┼─────┐       │
+     │     ▼     ▼     ▼       │
+     │  ┌────┐┌────┐┌────┐     │
+     │  │Sol1││Sol2││Sol3│     │
+     │  └────┘└────┘└────┘     │
+     └─────────────────────────┘
+```
+
+```typescript
+interface SwarmConfig {
+  agents: {
+    count: number;
+    agentType: string;
+    model: string;
+  };
+  blackboard: {
+    enabled: boolean;
+    capacity: number;
+  };
+  termination: {
+    mode: 'solution-found' | 'convergence' | 'timeout' | 'iterations';
+    threshold?: number;
+    timeout?: number;
+    maxIterations?: number;
+  };
+  communication: {
+    mode: 'broadcast' | 'neighbor' | 'pheromone';
+    frequency: 'continuous' | 'periodic';
+  };
+}
+
+class SwarmPattern implements CollaborationPattern {
+  name = 'swarm';
+
+  async execute(task: Task, config: SwarmConfig): Promise<CollaborationResult> {
+    const agents = await this.createSwarm(config.agents);
+    const blackboard = new Blackboard(config.blackboard);
+
+    // Initialize problem space
+    await blackboard.initialize(task);
+
+    let iterations = 0;
+    let converged = false;
+
+    while (!this.shouldTerminate(blackboard, config, iterations, converged)) {
+      iterations++;
+
+      // All agents work in parallel
+      const contributions = await Promise.all(
+        agents.map(agent => agent.contribute(blackboard.getState()))
+      );
+
+      // Update blackboard with contributions
+      for (const contribution of contributions) {
+        await blackboard.apply(contribution);
+      }
+
+      // Check for convergence
+      converged = this.checkConvergence(blackboard.getHistory());
+
+      // Communicate based on mode
+      if (config.communication.mode === 'pheromone') {
+        await this.updatePheromones(blackboard, contributions);
+      }
+    }
+
+    // Extract best solution
+    const solution = blackboard.getBestSolution();
+
+    return {
+      pattern: 'swarm',
+      success: solution !== null,
+      result: solution,
+      metrics: {
+        iterations,
+        converged,
+        contributionCount: blackboard.getContributionCount(),
+        solutionQuality: blackboard.getSolutionQuality()
+      }
+    };
+  }
+}
+
+class Blackboard {
+  private state: BlackboardState;
+  private contributions: Contribution[];
+  private solutions: Solution[];
+
+  initialize(task: Task): void {
+    this.state = {
+      problem: task,
+      partialSolutions: [],
+      constraints: [],
+      insights: []
+    };
+    this.contributions = [];
+    this.solutions = [];
+  }
+
+  apply(contribution: Contribution): void {
+    this.contributions.push(contribution);
+
+    switch (contribution.type) {
+      case 'partial-solution':
+        this.state.partialSolutions.push(contribution.data);
+        break;
+      case 'constraint':
+        this.state.constraints.push(contribution.data);
+        break;
+      case 'insight':
+        this.state.insights.push(contribution.data);
+        break;
+      case 'solution':
+        this.solutions.push(contribution.data);
+        break;
+    }
+  }
+
+  getState(): BlackboardState {
+    return { ...this.state };
+  }
+
+  getBestSolution(): Solution | null {
+    if (this.solutions.length === 0) return null;
+    return this.solutions.sort((a, b) => b.quality - a.quality)[0];
+  }
+}
+```
+
+**Uso ideal**: Problemas de optimización, exploración creativa, brainstorming.
+
+---
+
+## CollaborationManager
+
+```typescript
+class CollaborationManager {
+  private patterns: Map<string, CollaborationPattern>;
+  private config: CollaborationConfig;
+
+  constructor(config: CollaborationConfig) {
+    this.config = config;
+    this.patterns = this.registerPatterns();
+  }
+
+  // Execute collaboration with pattern
+  async execute(
+    patternName: string,
+    task: Task,
+    config?: Record<string, unknown>
+  ): Promise<CollaborationResult> {
+    const pattern = this.patterns.get(patternName);
+    if (!pattern) {
+      throw new Error(`Unknown pattern: ${patternName}`);
+    }
+
+    // Validate config
+    const validatedConfig = this.validateConfig(pattern, config);
+
+    // Create execution context
+    const context: ExecutionContext = {
+      task,
+      pattern: patternName,
+      startedAt: new Date(),
+      metrics: {}
+    };
+
+    // Emit start event
+    EventBus.publish('collaboration.started', {
+      pattern: patternName,
+      task: task.id
+    });
+
+    try {
+      // Execute pattern
+      const result = await pattern.execute(task, validatedConfig);
+
+      // Record metrics
+      context.metrics = result.metrics;
+      context.completedAt = new Date();
+
+      // Emit completion event
+      EventBus.publish('collaboration.completed', {
+        pattern: patternName,
+        task: task.id,
+        success: result.success
+      });
+
+      return result;
+    } catch (error) {
+      // Emit failure event
+      EventBus.publish('collaboration.failed', {
+        pattern: patternName,
+        task: task.id,
+        error: (error as Error).message
+      });
+
+      throw error;
+    }
+  }
+
+  // Auto-select best pattern for task
+  async autoSelect(task: Task): Promise<string> {
+    const analysis = await this.analyzeTask(task);
+
+    // Pattern selection rules
+    if (analysis.needsConsensus) return 'consensus';
+    if (analysis.needsDebate) return 'debate';
+    if (analysis.isLargeScale) return 'hierarchical';
+    if (analysis.hasIndependentParts) return 'supervisor';
+    if (analysis.needsIteration) return 'round-robin';
+    if (analysis.needsCreativity) return 'swarm';
+
+    return 'supervisor'; // Default
+  }
+
+  // Get available patterns
+  getPatterns(): string[] {
+    return Array.from(this.patterns.keys());
+  }
+
+  private registerPatterns(): Map<string, CollaborationPattern> {
+    return new Map([
+      ['supervisor', new SupervisorPattern()],
+      ['hierarchical', new HierarchicalPattern()],
+      ['consensus', new ConsensusPattern()],
+      ['debate', new DebatePattern()],
+      ['round-robin', new RoundRobinPattern()],
+      ['swarm', new SwarmPattern()]
+    ]);
+  }
+}
+```
+
+---
+
+## Comandos
+
+```bash
+/elsabro:collab list                    # Listar patrones
+/elsabro:collab info supervisor         # Detalles de patrón
+/elsabro:collab run debate              # Ejecutar con patrón
+/elsabro:collab auto                    # Auto-seleccionar patrón
+```
+
+---
+
+## Configuración
+
+```json
+{
+  "collaboration": {
+    "enabled": true,
+    "defaultPattern": "supervisor",
+    "patterns": {
+      "supervisor": {
+        "supervisorModel": "opus",
+        "workerModel": "haiku",
+        "maxWorkers": 4
+      },
+      "consensus": {
+        "voterCount": 3,
+        "strategy": "majority"
+      },
+      "debate": {
+        "rounds": 3,
+        "judgeModel": "opus"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Changelog
+
+- **v3.3.0**: Initial Collaboration Patterns
+  - 6 patterns: supervisor, hierarchical, consensus, debate, round-robin, swarm
+  - CollaborationManager with auto-selection
+  - Blackboard communication for swarm