elsabro 2.2.0 → 3.7.0

package/references/flow-orchestration.md

@@ -0,0 +1,940 @@
+---
+name: flow-orchestration
+description: Sistema de orquestacion basado en grafos inspirado en LangGraph
+version: 1.0.0
+---
+
+# ELSABRO Flow-Based Orchestration
+
+## Vision General
+
+El sistema de Flow Orchestration permite definir workflows complejos como grafos dirigidos, con soporte para:
+- **Nodos**: Agentes, funciones, decisiones
+- **Edges**: Transiciones condicionales o incondicionales
+- **Subflows**: Workflows reutilizables anidados
+- **Parallel branches**: Ejecución paralela de ramas independientes
+- **Interrupts**: Pausas programáticas para intervención humana
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                         FLOW ARCHITECTURE                                 │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│    ┌───────────┐                                                         │
+│    │   START   │                                                         │
+│    └─────┬─────┘                                                         │
+│          │                                                               │
+│          ▼                                                               │
+│    ┌───────────┐      condition=true      ┌───────────┐                 │
+│    │  Analyst  │ ──────────────────────►  │  Planner  │                 │
+│    └───────────┘                          └─────┬─────┘                 │
+│          │                                      │                        │
+│          │ condition=false                      │                        │
+│          ▼                                      ▼                        │
+│    ┌───────────┐                    ┌─────────────────────┐             │
+│    │   Quick   │                    │   PARALLEL BRANCH   │             │
+│    │   Mode    │                    ├─────────────────────┤             │
+│    └─────┬─────┘                    │ ┌─────┐   ┌─────┐  │             │
+│          │                          │ │Exec │   │ QA  │  │             │
+│          │                          │ └──┬──┘   └──┬──┘  │             │
+│          │                          │    │         │     │             │
+│          │                          │    └────┬────┘     │             │
+│          │                          │         │          │             │
+│          │                          └─────────┼──────────┘             │
+│          │                                    │                         │
+│          │                                    ▼                         │
+│          │                          ┌───────────────┐                   │
+│          │                          │   Verifier    │                   │
+│          │                          └───────┬───────┘                   │
+│          │                                  │                           │
+│          └──────────────────────────────────┤                           │
+│                                             │                           │
+│                                             ▼                           │
+│                                       ┌───────────┐                     │
+│                                       │    END    │                     │
+│                                       └───────────┘                     │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Definición de Flows
+
+### Flow Definition Schema
+
+```json
+{
+  "id": "flow_feature_dev",
+  "name": "Feature Development Flow",
+  "version": "1.0.0",
+  "description": "Workflow completo para desarrollar una feature",
+
+  "config": {
+    "timeout": 3600000,
+    "maxRetries": 3,
+    "checkpointEnabled": true,
+    "interruptEnabled": true
+  },
+
+  "inputs": {
+    "featureDescription": { "type": "string", "required": true },
+    "complexity": { "type": "enum", "values": ["low", "medium", "high"], "default": "medium" }
+  },
+
+  "outputs": {
+    "filesCreated": { "type": "array" },
+    "testsCreated": { "type": "array" },
+    "success": { "type": "boolean" }
+  },
+
+  "nodes": [
+    {
+      "id": "start",
+      "type": "entry",
+      "next": "analyze"
+    },
+    {
+      "id": "analyze",
+      "type": "agent",
+      "agent": "elsabro-analyst",
+      "config": {
+        "model": "opus",
+        "timeout": 300000
+      },
+      "inputs": {
+        "task": "{{inputs.featureDescription}}"
+      },
+      "outputs": ["analysis", "complexity", "scope"]
+    },
+    {
+      "id": "route_complexity",
+      "type": "router",
+      "condition": "{{nodes.analyze.outputs.complexity}}",
+      "routes": {
+        "low": "quick_implement",
+        "medium": "plan_implement",
+        "high": "detailed_plan"
+      },
+      "default": "plan_implement"
+    },
+    {
+      "id": "quick_implement",
+      "type": "agent",
+      "agent": "elsabro-quick-dev",
+      "next": "verify"
+    },
+    {
+      "id": "plan_implement",
+      "type": "subflow",
+      "flow": "planning_subflow",
+      "next": "parallel_dev"
+    },
+    {
+      "id": "detailed_plan",
+      "type": "sequence",
+      "steps": [
+        { "agent": "elsabro-analyst", "as": "deep_analysis" },
+        { "agent": "elsabro-planner", "as": "architecture" }
+      ],
+      "next": "interrupt_approval"
+    },
+    {
+      "id": "interrupt_approval",
+      "type": "interrupt",
+      "reason": "Plan requires approval for high complexity feature",
+      "display": {
+        "title": "Plan Approval Required",
+        "content": "{{nodes.detailed_plan.outputs.architecture}}",
+        "options": ["approve", "modify", "reject"]
+      },
+      "routes": {
+        "approve": "parallel_dev",
+        "modify": "detailed_plan",
+        "reject": "end_rejected"
+      }
+    },
+    {
+      "id": "parallel_dev",
+      "type": "parallel",
+      "branches": [
+        {
+          "id": "implementation",
+          "agent": "elsabro-executor",
+          "config": { "model": "opus" }
+        },
+        {
+          "id": "testing",
+          "agent": "elsabro-qa",
+          "config": { "model": "opus" }
+        }
+      ],
+      "joinType": "all",
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "type": "agent",
+      "agent": "elsabro-verifier",
+      "config": { "model": "opus" }
+    },
+    {
+      "id": "verify_check",
+      "type": "condition",
+      "condition": "{{nodes.verify.outputs.passed}}",
+      "true": "end_success",
+      "false": "fix_issues"
+    },
+    {
+      "id": "fix_issues",
+      "type": "agent",
+      "agent": "elsabro-debugger",
+      "next": "verify",
+      "maxIterations": 3,
+      "onMaxIterations": "interrupt_manual"
+    },
+    {
+      "id": "interrupt_manual",
+      "type": "interrupt",
+      "reason": "Auto-fix failed after 3 attempts",
+      "display": {
+        "title": "Manual Intervention Required",
+        "errors": "{{nodes.verify.outputs.errors}}"
+      }
+    },
+    {
+      "id": "end_success",
+      "type": "exit",
+      "status": "success",
+      "outputs": {
+        "filesCreated": "{{collectOutputs('filesCreated')}}",
+        "testsCreated": "{{collectOutputs('testsCreated')}}",
+        "success": true
+      }
+    },
+    {
+      "id": "end_rejected",
+      "type": "exit",
+      "status": "rejected",
+      "outputs": {
+        "success": false,
+        "reason": "Plan rejected by user"
+      }
+    }
+  ],
+
+  "edges": [
+    { "from": "start", "to": "analyze" },
+    { "from": "analyze", "to": "route_complexity" },
+    { "from": "verify", "to": "verify_check" }
+  ]
+}
+```
+
+---
+
+## Tipos de Nodos
+
+### 1. Entry Node
+
+Punto de entrada del flow.
+
+```json
+{
+  "id": "start",
+  "type": "entry",
+  "next": "first_node"
+}
+```
+
+### 2. Agent Node
+
+Ejecuta un agente ELSABRO.
+
+```json
+{
+  "id": "analyze",
+  "type": "agent",
+  "agent": "elsabro-analyst",
+  "config": {
+    "model": "opus",
+    "timeout": 300000,
+    "retries": 2
+  },
+  "inputs": {
+    "task": "{{inputs.description}}",
+    "context": "{{state.previousAnalysis}}"
+  },
+  "outputs": ["result", "decisions"],
+  "next": "next_node"
+}
+```
+
+### 3. Router Node
+
+Enruta basado en condiciones.
+
+```json
+{
+  "id": "complexity_router",
+  "type": "router",
+  "condition": "{{nodes.analyze.outputs.complexity}}",
+  "routes": {
+    "low": "quick_path",
+    "medium": "normal_path",
+    "high": "detailed_path"
+  },
+  "default": "normal_path"
+}
+```
+
+### 4. Condition Node
+
+Bifurcación binaria simple.
+
+```json
+{
+  "id": "check_tests",
+  "type": "condition",
+  "condition": "{{nodes.test.outputs.passed}} === true",
+  "true": "deploy",
+  "false": "fix_tests"
+}
+```
+
+### 5. Parallel Node
+
+Ejecuta múltiples ramas en paralelo.
+
+```json
+{
+  "id": "parallel_work",
+  "type": "parallel",
+  "branches": [
+    { "id": "code", "agent": "elsabro-executor" },
+    { "id": "tests", "agent": "elsabro-qa" },
+    { "id": "docs", "agent": "elsabro-tech-writer" }
+  ],
+  "joinType": "all",
+  "timeout": 600000,
+  "next": "merge_results"
+}
+```
+
+**Join Types**:
+- `all`: Espera que todas terminen
+- `any`: Continúa cuando cualquiera termine
+- `quorum`: Continúa cuando >50% termine
+- `first_success`: Continúa con el primer éxito
+
+### 6. Sequence Node
+
+Ejecuta pasos en secuencia.
+
+```json
+{
+  "id": "analysis_sequence",
+  "type": "sequence",
+  "steps": [
+    { "agent": "elsabro-analyst", "as": "market" },
+    { "agent": "elsabro-analyst", "as": "tech" },
+    { "agent": "elsabro-planner", "as": "plan" }
+  ],
+  "next": "implementation"
+}
+```
+
+### 7. Subflow Node
+
+Ejecuta otro flow como subrutina.
+
+```json
+{
+  "id": "auth_feature",
+  "type": "subflow",
+  "flow": "authentication_flow",
+  "inputs": {
+    "provider": "nextauth",
+    "features": ["email", "oauth"]
+  },
+  "next": "continue"
+}
+```
+
+### 8. Interrupt Node
+
+Pausa para intervención humana.
+
+```json
+{
+  "id": "approval_gate",
+  "type": "interrupt",
+  "reason": "Approval required before deployment",
+  "display": {
+    "title": "Deployment Approval",
+    "content": "Review changes before proceeding",
+    "data": "{{nodes.review.outputs.summary}}",
+    "options": [
+      { "id": "approve", "label": "Approve & Deploy" },
+      { "id": "reject", "label": "Reject" },
+      { "id": "modify", "label": "Request Changes" }
+    ]
+  },
+  "routes": {
+    "approve": "deploy",
+    "reject": "end_rejected",
+    "modify": "make_changes"
+  },
+  "timeout": 86400000
+}
+```
+
+### 9. Loop Node
+
+Repite hasta condición.
+
+```json
+{
+  "id": "fix_loop",
+  "type": "loop",
+  "body": [
+    { "agent": "elsabro-debugger" },
+    { "agent": "elsabro-verifier" }
+  ],
+  "condition": "{{nodes.verifier.outputs.passed}} === false",
+  "maxIterations": 5,
+  "onMaxIterations": "escalate"
+}
+```
+
+### 10. Exit Node
+
+Punto de salida del flow.
+
+```json
+{
+  "id": "end_success",
+  "type": "exit",
+  "status": "success",
+  "outputs": {
+    "files": "{{collectOutputs('files')}}",
+    "duration": "{{duration()}}"
+  }
+}
+```
+
+---
+
+## API del Flow Engine
+
+### FlowEngine
+
+```javascript
+/**
+ * FlowEngine
+ * Motor de ejecución de flows basados en grafos
+ */
+class FlowEngine {
+  constructor(options = {}) {
+    this.checkpointManager = options.checkpointManager || new CheckpointManager();
+    this.memoryManager = options.memoryManager || new MemoryManager();
+    this.agentRegistry = options.agentRegistry || new AgentRegistry();
+
+    this.state = {
+      currentNode: null,
+      variables: {},
+      nodeOutputs: {},
+      history: [],
+      interrupts: []
+    };
+  }
+
+  /**
+   * Carga y valida una definición de flow
+   */
+  async loadFlow(flowDefinition) {
+    // Validar schema
+    this.validateFlowSchema(flowDefinition);
+
+    // Construir grafo
+    this.flow = flowDefinition;
+    this.graph = this.buildGraph(flowDefinition);
+
+    // Validar grafo (ciclos, nodos huérfanos, etc.)
+    this.validateGraph();
+
+    return this;
+  }
+
+  /**
+   * Ejecuta el flow desde el inicio
+   */
+  async execute(inputs = {}) {
+    // Inicializar estado
+    this.state.variables = { ...inputs };
+    this.state.startedAt = new Date().toISOString();
+
+    // Crear checkpoint inicial
+    await this.checkpointManager.createCheckpoint({
+      flowId: this.flow.id,
+      execution: { status: 'ACTIVE', currentNode: 'start' },
+      state: this.state
+    }, 'FLOW_START');
+
+    // Encontrar nodo de entrada
+    const entryNode = this.findEntryNode();
+
+    // Ejecutar desde entrada
+    return this.executeNode(entryNode);
+  }
+
+  /**
+   * Resume un flow desde un checkpoint
+   */
+  async resume(checkpointId) {
+    const checkpoint = await this.checkpointManager.loadCheckpoint(checkpointId);
+
+    // Restaurar estado
+    this.state = checkpoint.state;
+
+    // Encontrar nodo donde quedó
+    const currentNode = this.graph.getNode(checkpoint.execution.currentNode);
+
+    // Continuar ejecución
+    return this.executeNode(currentNode);
+  }
+
+  /**
+   * Resume desde un interrupt
+   */
+  async resumeFromInterrupt(interruptId, response) {
+    const interrupt = this.state.interrupts.find(i => i.id === interruptId);
+
+    if (!interrupt) {
+      throw new Error(`Interrupt ${interruptId} not found`);
+    }
+
+    // Determinar siguiente nodo basado en respuesta
+    const nextNode = interrupt.routes[response];
+
+    if (!nextNode) {
+      throw new Error(`Invalid response: ${response}`);
+    }
+
+    // Marcar interrupt como resuelto
+    interrupt.resolvedAt = new Date().toISOString();
+    interrupt.response = response;
+
+    // Continuar ejecución
+    return this.executeNode(this.graph.getNode(nextNode));
+  }
+
+  /**
+   * Ejecuta un nodo específico
+   */
+  async executeNode(node) {
+    this.state.currentNode = node.id;
+    this.state.history.push({
+      nodeId: node.id,
+      startedAt: new Date().toISOString()
+    });
+
+    // Checkpoint antes de ejecutar
+    await this.checkpointManager.updateCheckpoint({
+      execution: { currentNode: node.id },
+      state: this.state
+    }, 'NODE_START');
+
+    try {
+      // Ejecutar según tipo de nodo
+      const result = await this.executeByType(node);
+
+      // Guardar output
+      this.state.nodeOutputs[node.id] = result;
+
+      // Actualizar historial
+      const historyEntry = this.state.history[this.state.history.length - 1];
+      historyEntry.completedAt = new Date().toISOString();
+      historyEntry.status = 'completed';
+      historyEntry.output = result;
+
+      // Checkpoint después de ejecutar
+      await this.checkpointManager.updateCheckpoint({
+        state: this.state
+      }, 'NODE_COMPLETE');
+
+      // Determinar siguiente nodo
+      const nextNode = await this.determineNextNode(node, result);
+
+      if (nextNode) {
+        return this.executeNode(nextNode);
+      }
+
+      // Si no hay siguiente, terminamos
+      return this.finalize(result);
+
+    } catch (error) {
+      return this.handleNodeError(node, error);
+    }
+  }
+
+  /**
+   * Ejecuta nodo según su tipo
+   */
+  async executeByType(node) {
+    switch (node.type) {
+      case 'entry':
+        return this.executeEntryNode(node);
+
+      case 'agent':
+        return this.executeAgentNode(node);
+
+      case 'router':
+        return this.executeRouterNode(node);
+
+      case 'condition':
+        return this.executeConditionNode(node);
+
+      case 'parallel':
+        return this.executeParallelNode(node);
+
+      case 'sequence':
+        return this.executeSequenceNode(node);
+
+      case 'subflow':
+        return this.executeSubflowNode(node);
+
+      case 'interrupt':
+        return this.executeInterruptNode(node);
+
+      case 'loop':
+        return this.executeLoopNode(node);
+
+      case 'exit':
+        return this.executeExitNode(node);
+
+      default:
+        throw new Error(`Unknown node type: ${node.type}`);
+    }
+  }
+
+  /**
+   * Ejecuta nodo de agente
+   */
+  async executeAgentNode(node) {
+    // Resolver inputs con template
+    const inputs = this.resolveTemplate(node.inputs);
+
+    // Obtener contexto de memoria
+    const context = await this.memoryManager.getFullContext({
+      description: inputs.task || inputs.description,
+      context: node.context || []
+    });
+
+    // Ejecutar agente
+    const result = await this.agentRegistry.execute(node.agent, {
+      ...inputs,
+      memoryContext: context,
+      config: node.config
+    });
+
+    // Procesar resultado con memoria
+    await this.memoryManager.processAgentResult(node.agent, result);
+
+    return result;
+  }
+
+  /**
+   * Ejecuta nodo paralelo
+   */
+  async executeParallelNode(node) {
+    const branches = node.branches;
+    const joinType = node.joinType || 'all';
+
+    // Lanzar todas las ramas en paralelo
+    const promises = branches.map(branch =>
+      this.executeBranch(branch).catch(error => ({
+        branchId: branch.id,
+        error: error.message,
+        status: 'failed'
+      }))
+    );
+
+    // Esperar según joinType
+    let results;
+
+    switch (joinType) {
+      case 'all':
+        results = await Promise.all(promises);
+        break;
+
+      case 'any':
+        results = [await Promise.race(promises)];
+        break;
+
+      case 'quorum':
+        results = await this.waitForQuorum(promises);
+        break;
+
+      case 'first_success':
+        results = [await this.waitForFirstSuccess(promises)];
+        break;
+    }
+
+    // Combinar resultados
+    return {
+      branches: results.reduce((acc, r, i) => {
+        acc[branches[i].id] = r;
+        return acc;
+      }, {}),
+      completedCount: results.filter(r => !r.error).length,
+      totalCount: branches.length
+    };
+  }
+
+  /**
+   * Ejecuta nodo de interrupt
+   */
+  async executeInterruptNode(node) {
+    const interrupt = {
+      id: `int_${Date.now()}`,
+      nodeId: node.id,
+      reason: node.reason,
+      display: this.resolveTemplate(node.display),
+      routes: node.routes,
+      createdAt: new Date().toISOString()
+    };
+
+    // Guardar interrupt
+    this.state.interrupts.push(interrupt);
+
+    // Guardar checkpoint especial
+    await this.checkpointManager.saveInterrupt(node.reason, {
+      nodeId: node.id,
+      interruptId: interrupt.id,
+      display: interrupt.display
+    });
+
+    // Retornar para que el caller maneje
+    return {
+      type: 'interrupt',
+      interrupt: interrupt
+    };
+  }
+
+  /**
+   * Ejecuta subflow
+   */
+  async executeSubflowNode(node) {
+    // Cargar definición del subflow
+    const subflowDef = await this.loadSubflowDefinition(node.flow);
+
+    // Crear engine para subflow
+    const subEngine = new FlowEngine({
+      checkpointManager: this.checkpointManager,
+      memoryManager: this.memoryManager,
+      agentRegistry: this.agentRegistry
+    });
+
+    await subEngine.loadFlow(subflowDef);
+
+    // Ejecutar subflow con inputs
+    const inputs = this.resolveTemplate(node.inputs);
+    return subEngine.execute(inputs);
+  }
+
+  // ==================== Helpers ====================
+
+  resolveTemplate(template) {
+    if (typeof template === 'string') {
+      return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+        return this.resolvePath(path.trim());
+      });
+    }
+
+    if (Array.isArray(template)) {
+      return template.map(item => this.resolveTemplate(item));
+    }
+
+    if (typeof template === 'object' && template !== null) {
+      const resolved = {};
+      for (const [key, value] of Object.entries(template)) {
+        resolved[key] = this.resolveTemplate(value);
+      }
+      return resolved;
+    }
+
+    return template;
+  }
+
+  resolvePath(path) {
+    const parts = path.split('.');
+    let current;
+
+    if (parts[0] === 'inputs') {
+      current = this.state.variables;
+      parts.shift();
+    } else if (parts[0] === 'nodes') {
+      current = this.state.nodeOutputs;
+      parts.shift();
+    } else if (parts[0] === 'state') {
+      current = this.state;
+      parts.shift();
+    }
+
+    for (const part of parts) {
+      if (current === undefined) return undefined;
+      current = current[part];
+    }
+
+    return current;
+  }
+
+  buildGraph(flowDefinition) {
+    const graph = new Map();
+
+    for (const node of flowDefinition.nodes) {
+      graph.set(node.id, {
+        ...node,
+        inEdges: [],
+        outEdges: []
+      });
+    }
+
+    // Procesar edges explícitos
+    for (const edge of flowDefinition.edges || []) {
+      const fromNode = graph.get(edge.from);
+      const toNode = graph.get(edge.to);
+
+      if (fromNode && toNode) {
+        fromNode.outEdges.push(edge);
+        toNode.inEdges.push(edge);
+      }
+    }
+
+    // Procesar edges implícitos (next)
+    for (const [id, node] of graph) {
+      if (node.next && !node.outEdges.find(e => e.to === node.next)) {
+        node.outEdges.push({ from: id, to: node.next });
+        const nextNode = graph.get(node.next);
+        if (nextNode) {
+          nextNode.inEdges.push({ from: id, to: node.next });
+        }
+      }
+    }
+
+    return {
+      nodes: graph,
+      getNode: (id) => graph.get(id),
+      getEdges: (from) => graph.get(from)?.outEdges || []
+    };
+  }
+
+  findEntryNode() {
+    for (const [id, node] of this.graph.nodes) {
+      if (node.type === 'entry') {
+        return node;
+      }
+    }
+    throw new Error('No entry node found in flow');
+  }
+
+  async determineNextNode(currentNode, result) {
+    // Si el resultado es un interrupt, no hay siguiente
+    if (result?.type === 'interrupt') {
+      return null;
+    }
+
+    // Router determina siguiente basado en condición
+    if (currentNode.type === 'router') {
+      const route = currentNode.routes[result.route];
+      return route ? this.graph.getNode(route) : this.graph.getNode(currentNode.default);
+    }
+
+    // Condition determina siguiente basado en true/false
+    if (currentNode.type === 'condition') {
+      const nextId = result.value ? currentNode.true : currentNode.false;
+      return this.graph.getNode(nextId);
+    }
+
+    // Exit no tiene siguiente
+    if (currentNode.type === 'exit') {
+      return null;
+    }
+
+    // Default: usar next o primer outEdge
+    if (currentNode.next) {
+      return this.graph.getNode(currentNode.next);
+    }
+
+    const outEdges = this.graph.getEdges(currentNode.id);
+    if (outEdges.length > 0) {
+      return this.graph.getNode(outEdges[0].to);
+    }
+
+    return null;
+  }
+}
+```
+
+---
+
+## Flows Predefinidos
+
+### development_flow.json
+
+Flow estándar para desarrollo de features.
+
+### quick_flow.json
+
+Flow simplificado para tareas rápidas.
+
+### review_flow.json
+
+Flow para code review multi-agente.
+
+### debug_flow.json
+
+Flow para debugging sistemático.
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:flow
+
+```bash
+/elsabro:flow list                    # Listar flows disponibles
+/elsabro:flow run <name> [inputs]     # Ejecutar flow
+/elsabro:flow status                  # Ver estado del flow actual
+/elsabro:flow resume [checkpoint]     # Resumir flow pausado
+/elsabro:flow cancel                  # Cancelar flow actual
+/elsabro:flow create                  # Crear nuevo flow (interactivo)
+```
+
+---
+
+## Configuración
+
+### .planning/flows/config.json
+
+```json
+{
+  "flows": {
+    "defaultFlow": "development_flow",
+    "timeout": 3600000,
+    "checkpointing": {
+      "enabled": true,
+      "interval": "node"
+    },
+    "parallelism": {
+      "maxConcurrent": 4,
+      "defaultJoinType": "all"
+    },
+    "interrupts": {
+      "timeout": 86400000,
+      "defaultAction": "pause"
+    }
+  }
+}
+```