elsabro 2.1.0 → 2.2.0

package/references/tasks-integration.md

@@ -0,0 +1,380 @@
+# ELSABRO Tasks Integration
+
+## Propósito
+
+Integración del sistema ELSABRO con Claude Code Tasks API. Este documento define cómo ELSABRO usa Tasks API como backend único para tracking de trabajo, reemplazando sistemas duplicados.
+
+---
+
+## Arquitectura Unificada
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    ELSABRO + TASKS API INTEGRATION                           │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌─────────────────────┐     ┌──────────────────────────────────────────┐   │
+│  │   ELSABRO COMMANDS  │     │          CLAUDE CODE TASKS API           │   │
+│  │   (User Interface)  │────▶│            (Backend Storage)             │   │
+│  └─────────────────────┘     └──────────────────────────────────────────┘   │
+│           │                              │                                   │
+│           │                              │                                   │
+│  ┌────────┴─────────┐        ┌──────────┴─────────────────────────────┐    │
+│  │  High-Level UX   │        │  Native Capabilities                    │    │
+│  │  - /add-todo     │        │  - TaskCreate(subject, description)     │    │
+│  │  - /check-todos  │        │  - TaskUpdate(status, metadata)         │    │
+│  │  - /progress     │        │  - TaskList() with filters              │    │
+│  │  - /pause-work   │        │  - TaskGet(id) for details              │    │
+│  │  - /resume-work  │        │  - blocks/blockedBy dependencies        │    │
+│  └──────────────────┘        │  - owner assignment                     │    │
+│                              │  - metadata (flexible key-value)        │    │
+│                              └──────────────────────────────────────────┘    │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                      METADATA SCHEMA                                    │ │
+│  │                                                                         │ │
+│  │  {                                                                      │ │
+│  │    "type": "todo|phase|milestone|work",                                │ │
+│  │    "priority": "critical|high|medium|low",                             │ │
+│  │    "category": "bug|tech-debt|docs|chore|idea|feature",                │ │
+│  │    "due_date": "ISO-8601 | null",                                      │ │
+│  │    "milestone_id": "M001 | null",                                      │ │
+│  │    "phase_id": "P001 | null",                                          │ │
+│  │    "created_by": "user|system",                                        │ │
+│  │    "source_command": "add-todo|plan|execute|etc"                       │ │
+│  │  }                                                                      │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Migración de TODOs a Tasks
+
+### Antes (Sistema Duplicado)
+
+```markdown
+# .planning/TODOS.md
+
+## Critical
+- [ ] Fix auth token refresh (#123)
+
+## High Priority
+- [ ] Update React to v18.3 (tech-debt)
+```
+
+### Después (Tasks API)
+
+```javascript
+// Crear TODO como Task
+TaskCreate({
+  subject: "Fix auth token refresh",
+  description: "Authentication tokens not refreshing correctly. Issue #123",
+  activeForm: "Fixing auth token refresh",
+  metadata: {
+    type: "todo",
+    priority: "critical",
+    category: "bug",
+    issue_ref: "#123",
+    source_command: "add-todo"
+  }
+});
+
+// Crear TODO tech-debt
+TaskCreate({
+  subject: "Update React to v18.3",
+  description: "Upgrade React version for performance improvements",
+  activeForm: "Updating React",
+  metadata: {
+    type: "todo",
+    priority: "high",
+    category: "tech-debt",
+    source_command: "add-todo"
+  }
+});
+```
+
+---
+
+## Comando: /elsabro:add-todo (Actualizado)
+
+### Implementación con Tasks API
+
+```javascript
+// Usuario ejecuta: /elsabro:add-todo "Fix typo in README" --priority=high --category=docs
+
+// 1. Crear Task
+TaskCreate({
+  subject: "Fix typo in README",
+  description: "User-created TODO item",
+  activeForm: "Fixing typo in README",
+  metadata: {
+    type: "todo",
+    priority: "high",          // Del argumento --priority
+    category: "docs",          // Del argumento --category
+    due_date: null,            // Del argumento --due
+    milestone_id: null,        // Del argumento --milestone
+    created_by: "user",
+    source_command: "add-todo",
+    created_at: new Date().toISOString()
+  }
+});
+
+// 2. Output
+console.log(`
+✓ TODO added (Task #${task.id})
+
+  Subject: Fix typo in README
+  Priority: high
+  Category: docs
+
+  View all: /elsabro:check-todos
+`);
+```
+
+---
+
+## Comando: /elsabro:check-todos (Actualizado)
+
+### Implementación con Tasks API
+
+```javascript
+// Usuario ejecuta: /elsabro:check-todos --priority=high
+
+// 1. Obtener todas las Tasks tipo "todo"
+const tasks = TaskList();
+
+// 2. Filtrar por metadata.type === "todo"
+const todos = tasks.filter(t => t.metadata?.type === "todo");
+
+// 3. Filtrar por prioridad si se especificó
+const filtered = todos.filter(t =>
+  !priority || t.metadata?.priority === priority
+);
+
+// 4. Agrupar por prioridad
+const grouped = {
+  critical: filtered.filter(t => t.metadata?.priority === "critical"),
+  high: filtered.filter(t => t.metadata?.priority === "high"),
+  medium: filtered.filter(t => t.metadata?.priority === "medium"),
+  low: filtered.filter(t => t.metadata?.priority === "low")
+};
+
+// 5. Mostrar vista formateada
+console.log(`
+╔══════════════════════════════════════════════════╗
+║  PROJECT TODOs                                   ║
+╠══════════════════════════════════════════════════╣
+
+🔴 CRITICAL (${grouped.critical.length})
+${grouped.critical.map(t => `#${t.id} ${t.subject} [${t.metadata.category}]`).join('\n')}
+
+🟠 HIGH (${grouped.high.length})
+${grouped.high.map(t => `#${t.id} ${t.subject} [${t.metadata.category}]`).join('\n')}
+
+🟡 MEDIUM (${grouped.medium.length})
+${grouped.medium.map(t => `#${t.id} ${t.subject} [${t.metadata.category}]`).join('\n')}
+
+⬜ LOW (${grouped.low.length})
+${grouped.low.map(t => `#${t.id} ${t.subject} [${t.metadata.category}]`).join('\n')}
+
+╠══════════════════════════════════════════════════╣
+║  Total: ${filtered.length} | Completed: ${completed.length}
+╚══════════════════════════════════════════════════╝
+`);
+```
+
+### Acciones con TaskUpdate
+
+```javascript
+// Marcar como completado
+// /elsabro:check-todos --complete=5
+TaskUpdate({ taskId: "5", status: "completed" });
+
+// Cambiar prioridad
+// /elsabro:check-todos --prioritize=6 --to=high
+TaskUpdate({
+  taskId: "6",
+  metadata: { priority: "high" }
+});
+
+// Eliminar (usando status especial)
+// /elsabro:check-todos --delete=9
+TaskUpdate({ taskId: "9", status: "deleted" });
+```
+
+---
+
+## State Sync Simplificado
+
+### Antes (state-sync.md complejo)
+
+```javascript
+// 20+ líneas de código para sincronizar estado
+function initializeState() {
+  const stateFile = '.elsabro/state.json';
+  let state = { version: "1.0.0", ... };
+  // ... mucho código
+}
+```
+
+### Después (Tasks API como fuente de verdad)
+
+```javascript
+// Sincronización automática via Tasks API
+function getCommandContext() {
+  const tasks = TaskList();
+
+  return {
+    currentCommand: tasks.find(t =>
+      t.status === "in_progress" &&
+      t.metadata?.type === "command"
+    ),
+    pendingWork: tasks.filter(t => t.status === "pending"),
+    blockedWork: tasks.filter(t => t.blockedBy?.length > 0),
+    lastCompleted: tasks
+      .filter(t => t.status === "completed")
+      .sort((a, b) => b.metadata?.completed_at - a.metadata?.completed_at)[0]
+  };
+}
+```
+
+---
+
+## Tipos de Tasks por Comando
+
+### Comando: /elsabro:execute
+
+```javascript
+// Fase exploración
+TaskCreate({
+  subject: "Explore codebase for feature X",
+  metadata: { type: "work", phase: "exploration", model: "haiku" }
+});
+
+// Fase implementación
+TaskCreate({
+  subject: "Implement feature X",
+  metadata: { type: "work", phase: "implementation", model: "opus" }
+});
+
+// Fase verificación
+TaskCreate({
+  subject: "Verify feature X",
+  metadata: { type: "work", phase: "verification", model: "opus" }
+});
+```
+
+### Comando: /elsabro:plan
+
+```javascript
+TaskCreate({
+  subject: "Create plan for feature Y",
+  metadata: {
+    type: "work",
+    phase: "planning",
+    output_file: ".elsabro/plans/feature-y.md"
+  }
+});
+```
+
+### Comando: /elsabro:new-milestone
+
+```javascript
+TaskCreate({
+  subject: "Milestone: MVP Launch",
+  description: "Complete all MVP features for launch",
+  metadata: {
+    type: "milestone",
+    milestone_id: "M001",
+    target_date: "2024-02-15",
+    phases: ["P001", "P002", "P003"]
+  }
+});
+```
+
+---
+
+## Dependencias Automáticas
+
+```javascript
+// Crear tareas con dependencias
+const phase1 = TaskCreate({
+  subject: "Phase 1: Database setup",
+  metadata: { type: "phase", phase_id: "P001" }
+});
+
+const phase2 = TaskCreate({
+  subject: "Phase 2: API endpoints",
+  metadata: { type: "phase", phase_id: "P002" }
+});
+
+// Phase 2 depende de Phase 1
+TaskUpdate({
+  taskId: phase2.id,
+  addBlockedBy: [phase1.id]
+});
+
+// Resultado: Phase 2 no puede empezar hasta que Phase 1 complete
+```
+
+---
+
+## Migración Gradual
+
+### Paso 1: Dual-Write (Compatibilidad)
+
+```javascript
+// Escribir a ambos sistemas durante transición
+function addTodo(todo) {
+  // Nuevo: Tasks API
+  TaskCreate({ subject: todo.description, metadata: {...} });
+
+  // Legacy: .planning/TODOS.md (temporal)
+  appendToFile('.planning/TODOS.md', `- [ ] ${todo.description}`);
+}
+```
+
+### Paso 2: Read from Tasks API
+
+```javascript
+// Leer solo de Tasks API
+function getTodos() {
+  return TaskList().filter(t => t.metadata?.type === "todo");
+}
+```
+
+### Paso 3: Remove Legacy
+
+```javascript
+// Eliminar archivo legacy
+// rm .planning/TODOS.md
+// Actualizar comandos para usar solo Tasks API
+```
+
+---
+
+## Beneficios de la Integración
+
+| Aspecto | Antes | Después |
+|---------|-------|---------|
+| Storage | `.planning/TODOS.md` + `.elsabro/state.json` | Tasks API (único) |
+| Dependencias | Manual | `blocks/blockedBy` nativo |
+| Persistencia | Por sesión | Entre sesiones |
+| Filtros | Código custom | TaskList nativo |
+| Estado | Sincronización manual | Automático |
+| Visualización | Parsing de markdown | Structured data |
+
+---
+
+## Checklist de Implementación
+
+- [ ] Actualizar `/elsabro:add-todo` para usar TaskCreate
+- [ ] Actualizar `/elsabro:check-todos` para usar TaskList/TaskUpdate
+- [ ] Actualizar `/elsabro:progress` para leer de Tasks API
+- [ ] Actualizar `/elsabro:pause-work` para usar TaskUpdate
+- [ ] Actualizar `/elsabro:resume-work` para usar TaskGet
+- [ ] Deprecar `.planning/TODOS.md`
+- [ ] Migrar state-sync a usar Tasks API metadata
+- [ ] Actualizar enforcement-rules.md con nuevos patrones