elsabro 2.1.0 → 2.2.0

package/references/task-dispatcher.md

@@ -0,0 +1,388 @@
+# ELSABRO Task Dispatcher
+
+## Propósito
+
+Despacho inteligente de tareas a subagentes con **selección automática de modelo** según el tipo de tarea. Maximiza eficiencia usando el modelo correcto para cada trabajo.
+
+## Matriz de Selección de Modelo
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    MODELO SEGÚN TIPO DE TAREA                           │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  HAIKU (rápido, económico)          OPUS (máximo razonamiento)          │
+│  ─────────────────────────          ──────────────────────────          │
+│  • Buscar archivos (Glob/Grep)      • Escribir código nuevo             │
+│  • Leer y resumir código            • Code review profundo              │
+│  • Mapear estructura                • Debugging complejo                │
+│  • Exploración general              • Decisiones arquitectónicas        │
+│  • Listar dependencias              • Análisis de seguridad             │
+│  • Verificaciones simples           • Refactoring significativo         │
+│                                     • Clarificación de requisitos       │
+│                                                                         │
+│  SONNET (balance)                                                       │
+│  ────────────────                                                       │
+│  • Tests unitarios                                                      │
+│  • Documentación técnica                                                │
+│  • Cambios pequeños de código                                           │
+│  • Validación de patrones                                               │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Regla de Decisión
+
+```
+SI la tarea:
+  - NO escribe código nuevo
+  - NO toma decisiones arquitectónicas
+  - NO requiere razonamiento complejo
+  → USA HAIKU
+
+SI la tarea:
+  - Escribe tests o documentación
+  - Hace cambios menores de código
+  - Valida sin crear nuevo
+  → USA SONNET
+
+SI la tarea:
+  - Escribe código nuevo significativo
+  - Toma decisiones de arquitectura
+  - Requiere análisis profundo
+  - Hace code review crítico
+  → USA OPUS
+```
+
+## Mapeo de Agentes a Modelos
+
+### Siempre HAIKU (exploración)
+| Agente | Razón |
+|--------|-------|
+| `Explore` | Solo busca archivos y lee |
+| `Plan` (mapeo) | Estructura sin crear |
+| `feature-dev:code-explorer` | Análisis de patrones existentes |
+
+### Siempre OPUS (razonamiento profundo)
+| Agente | Razón |
+|--------|-------|
+| `elsabro-analyst` | Clarificación y entrevistas |
+| `elsabro-planner` | Diseño de arquitectura |
+| `elsabro-debugger` | Investigación metódica |
+| `elsabro-executor` | Implementación con TDD |
+| `elsabro-orchestrator` | Coordinación compleja |
+| `feature-dev:code-architect` | Decisiones de diseño |
+| `pr-review-toolkit:code-reviewer` | Review profundo |
+| `pr-review-toolkit:silent-failure-hunter` | Análisis de edge cases |
+| `pr-review-toolkit:pr-test-analyzer` | Análisis profundo de cobertura |
+
+### Siempre SONNET (balance)
+| Agente | Razón |
+|--------|-------|
+| `elsabro-verifier` | Validación estructurada |
+| `elsabro-qa` | Diseño de tests |
+| `elsabro-tech-writer` | Documentación |
+| `elsabro-scrum-master` | Gestión de sprints |
+| `elsabro-ux-designer` | Diseño UI/UX |
+| `elsabro-quick-dev` | Cambios rápidos |
+
+### Dinámico (según contexto)
+| Agente | Modelo por defecto | Escalar a OPUS si... |
+|--------|-------------------|----------------------|
+| `elsabro-yolo-dev` | SONNET | Código crítico |
+
+## Protocolo de Despacho
+
+### 1. Clasificar Tarea
+
+```javascript
+function classifyTask(task) {
+  // Exploración pura → HAIKU
+  if (task.actions.every(a => ['read', 'glob', 'grep', 'list'].includes(a))) {
+    return 'exploration';
+  }
+
+  // Escritura de código → OPUS
+  if (task.actions.some(a => ['write', 'edit', 'create'].includes(a))
+      && task.scope === 'significant') {
+    return 'implementation';
+  }
+
+  // Testing/docs → SONNET
+  if (task.type === 'test' || task.type === 'documentation') {
+    return 'validation';
+  }
+
+  // Default según complejidad
+  return task.complexity > 0.7 ? 'implementation' : 'validation';
+}
+```
+
+### 2. Seleccionar Modelo
+
+```javascript
+function selectModel(taskType) {
+  const modelMap = {
+    'exploration': 'haiku',
+    'validation': 'sonnet',
+    'implementation': 'opus'
+  };
+  return modelMap[taskType] || 'sonnet';
+}
+```
+
+### 3. Despachar a Subagente
+
+```javascript
+function dispatch(task, agent) {
+  const taskType = classifyTask(task);
+  const model = selectModel(taskType);
+
+  return Task({
+    subagent_type: agent,
+    model: model,
+    description: task.description,
+    prompt: task.prompt
+  });
+}
+```
+
+## Ejecución Paralela
+
+### Cuándo Paralelizar
+
+```
+PARALELO (un solo mensaje con múltiples Task):
+- Tareas independientes sin dependencias
+- Misma wave/fase
+- No modifican los mismos archivos
+
+SECUENCIAL:
+- Tarea B depende del output de A
+- Modifican los mismos archivos
+- Una tarea determina si otra se ejecuta
+```
+
+### Patrón de Paralelización con Tasks API
+
+```javascript
+// 1. Crear Tasks con dependencias
+const explorationTasks = [
+  TaskCreate({ subject: "Explore files", metadata: { model: "haiku" }}),
+  TaskCreate({ subject: "Map patterns", metadata: { model: "haiku" }}),
+  TaskCreate({ subject: "Analyze deps", metadata: { model: "haiku" }})
+];
+
+// 2. Crear Task agregadora
+const aggregator = TaskCreate({
+  subject: "Aggregate exploration results",
+  metadata: { type: "aggregator" }
+});
+
+// 3. Configurar dependencias
+TaskUpdate({ taskId: aggregator.id, addBlockedBy: explorationTasks.map(t => t.id) });
+
+// 4. Marcar in_progress y lanzar EN UN SOLO MENSAJE
+explorationTasks.forEach(t => TaskUpdate({ taskId: t.id, status: "in_progress" }));
+
+// 5. Lanzar agentes (PARALELO REAL)
+Task({ subagent_type: "Explore", model: "haiku", prompt: "..." }) |
+Task({ subagent_type: "feature-dev:code-explorer", model: "haiku", prompt: "..." }) |
+Task({ subagent_type: "Plan", model: "haiku", prompt: "..." })
+
+// 6. Al completar cada uno
+explorationTasks.forEach(t => TaskUpdate({ taskId: t.id, status: "completed" }));
+
+// 7. Agregador se desbloquea automáticamente
+```
+
+## Visualización del Despacho
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      TASK DISPATCH VISUALIZATION                         │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  INPUT: "Implementar validación de formulario"                          │
+│                                                                         │
+│  ┌─────────────────┐                                                    │
+│  │ CLASSIFY TASK   │                                                    │
+│  │ type: implement │                                                    │
+│  │ scope: signif.  │                                                    │
+│  └────────┬────────┘                                                    │
+│           │                                                              │
+│           ▼                                                              │
+│  ┌─────────────────┐                                                    │
+│  │ SELECT MODEL    │                                                    │
+│  │ → OPUS          │                                                    │
+│  └────────┬────────┘                                                    │
+│           │                                                              │
+│           ▼                                                              │
+│  ┌─────────────────┐                                                    │
+│  │ SELECT AGENT    │                                                    │
+│  │ → elsabro-exec  │                                                    │
+│  └────────┬────────┘                                                    │
+│           │                                                              │
+│           ▼                                                              │
+│  ┌─────────────────────────────────────┐                                │
+│  │ DISPATCH                            │                                │
+│  │ Task(elsabro-executor, opus, ...)   │                                │
+│  └─────────────────────────────────────┘                                │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Ejemplos de Despacho
+
+### Ejemplo 1: Exploración (HAIKU x3 paralelo)
+
+```javascript
+// Tarea: "Entender cómo funciona la autenticación"
+// Tipo: exploration
+// Modelo: HAIKU (x3 en paralelo)
+
+Task({
+  subagent_type: "Explore",
+  model: "haiku",
+  description: "Buscar archivos de auth",
+  prompt: "Busca archivos relacionados con autenticación..."
+}) |
+Task({
+  subagent_type: "feature-dev:code-explorer",
+  model: "haiku",
+  description: "Analizar patrones de auth",
+  prompt: "Analiza los patrones de autenticación..."
+}) |
+Task({
+  subagent_type: "Plan",
+  model: "haiku",
+  description: "Mapear flujo de auth",
+  prompt: "Mapea el flujo de autenticación..."
+})
+```
+
+### Ejemplo 2: Implementación (OPUS x2 paralelo)
+
+```javascript
+// Tarea: "Agregar validación de email"
+// Tipo: implementation
+// Modelo: OPUS (x2 en paralelo)
+
+Task({
+  subagent_type: "elsabro-executor",
+  model: "opus",
+  description: "Implementar validación",
+  prompt: "Implementa validación de email con Zod..."
+}) |
+Task({
+  subagent_type: "feature-dev:code-architect",
+  model: "opus",
+  description: "Validar arquitectura",
+  prompt: "Verifica que la implementación siga patrones..."
+})
+```
+
+### Ejemplo 3: Verificación (OPUS x3 paralelo)
+
+```javascript
+// Tarea: "Verificar calidad del código"
+// Tipo: validation (pero review profundo → OPUS)
+// Modelo: OPUS (x3 en paralelo)
+
+Task({
+  subagent_type: "pr-review-toolkit:code-reviewer",
+  model: "opus",
+  description: "Code review",
+  prompt: "Revisa el código buscando bugs..."
+}) |
+Task({
+  subagent_type: "pr-review-toolkit:silent-failure-hunter",
+  model: "opus",
+  description: "Buscar errores ocultos",
+  prompt: "Busca errores silenciosos..."
+}) |
+Task({
+  subagent_type: "pr-review-toolkit:pr-test-analyzer",
+  model: "opus",
+  description: "Analizar tests",
+  prompt: "Verifica cobertura de tests..."
+})
+```
+
+## Métricas de Eficiencia
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      EFFICIENCY METRICS                                  │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ANTES (sin dispatcher):                                                │
+│  - Todo con OPUS → Alto costo, lento                                    │
+│  - Sin paralelismo → Secuencial                                         │
+│  - Sin tracking → Estado perdido                                        │
+│                                                                         │
+│  DESPUÉS (con dispatcher):                                              │
+│  - HAIKU para exploración → 70% más rápido, 90% más barato              │
+│  - OPUS solo para código → Calidad donde importa                        │
+│  - 3+ agentes paralelos → Fase 2x-3x más rápida                         │
+│  - Tasks API → Estado persistente entre sesiones                        │
+│                                                                         │
+│  AHORRO ESTIMADO POR SESIÓN:                                            │
+│  - Tokens: -40% (HAIKU en exploración)                                  │
+│  - Tiempo: -50% (paralelismo)                                           │
+│  - Calidad: +30% (OPUS donde importa)                                   │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Integración con Comandos
+
+### Comandos que usan Task Dispatcher
+
+| Comando | Fase Exploración | Fase Implementación | Fase Verificación |
+|---------|-----------------|---------------------|-------------------|
+| `/elsabro:execute` | HAIKU x3 | OPUS x2 | OPUS x3 |
+| `/elsabro:plan` | HAIKU x3 | OPUS x1 | - |
+| `/elsabro:verify-work` | - | - | OPUS x3 |
+| `/elsabro:debug` | HAIKU x2 | OPUS x1 | SONNET x1 |
+| `/elsabro:research-phase` | HAIKU x3 | - | - |
+| `/elsabro:map-codebase` | HAIKU x4 | - | - |
+
+### Frontmatter Recomendado
+
+```yaml
+---
+name: execute
+description: Ejecutar planes con dispatcher inteligente
+allowed-tools:
+  - Task
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - TaskGet
+dispatcher:
+  exploration:
+    agents: [Explore, feature-dev:code-explorer, Plan]
+    model: haiku
+    parallel: true
+  implementation:
+    agents: [elsabro-executor, feature-dev:code-architect]
+    model: opus
+    parallel: true
+  verification:
+    agents: [pr-review-toolkit:code-reviewer, pr-review-toolkit:silent-failure-hunter, pr-review-toolkit:pr-test-analyzer]
+    model: opus
+    parallel: true
+---
+```
+
+## Checklist de Uso
+
+Antes de despachar tareas:
+
+- [ ] ¿Clasificaste el tipo de tarea? (exploration/validation/implementation)
+- [ ] ¿Seleccionaste el modelo correcto? (haiku/sonnet/opus)
+- [ ] ¿Las tareas son independientes? → Paralelo
+- [ ] ¿Creaste Tasks API para tracking?
+- [ ] ¿Configuraste dependencias con blockedBy?
+- [ ] ¿Lanzaste agentes paralelos en UN SOLO mensaje?