elsabro 2.1.0 → 2.3.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

package/scripts/setup-parallel-worktrees.sh

@@ -0,0 +1,319 @@
+#!/bin/bash
+# ELSABRO Parallel Worktrees Setup
+# Crea worktrees automaticos para ejecucion paralela de agentes
+#
+# Basado en: claude-productivity-plugin/scripts/setup-worktrees.sh
+# Adaptado para el sistema de agentes de ELSABRO
+
+set -e
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+WORKTREE_BASE="${REPO_ROOT}/../elsabro-worktrees"
+
+# Colores
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Agentes disponibles en ELSABRO
+ELSABRO_AGENTS=("analyst" "executor" "verifier" "planner" "orchestrator")
+
+# Limite maximo de worktrees simultaneos
+MAX_WORKTREES=5
+
+print_header() {
+    echo ""
+    echo -e "${BLUE}========================================${NC}"
+    echo -e "${BLUE}   ELSABRO Parallel Worktrees Setup    ${NC}"
+    echo -e "${BLUE}========================================${NC}"
+    echo ""
+}
+
+check_git_repo() {
+    if ! git rev-parse --git-dir > /dev/null 2>&1; then
+        echo -e "${RED}Error: No estas en un repositorio git${NC}"
+        exit 1
+    fi
+}
+
+check_git_version() {
+    local git_version=$(git --version | grep -oE '[0-9]+\.[0-9]+' | head -1)
+    local major=$(echo "$git_version" | cut -d. -f1)
+    local minor=$(echo "$git_version" | cut -d. -f2)
+
+    if [ "$major" -lt 2 ] || ([ "$major" -eq 2 ] && [ "$minor" -lt 15 ]); then
+        echo -e "${RED}Error: Se requiere git >= 2.15 (tienes $git_version)${NC}"
+        exit 1
+    fi
+}
+
+# Crear directorio base si no existe
+ensure_worktree_base() {
+    if [ ! -d "$WORKTREE_BASE" ]; then
+        mkdir -p "$WORKTREE_BASE"
+        echo -e "${GREEN}Directorio base creado: ${WORKTREE_BASE}${NC}"
+    fi
+}
+
+# Contar worktrees activos
+count_active_worktrees() {
+    local count=$(git worktree list | grep -c "elsabro-worktrees" || echo "0")
+    echo "$count"
+}
+
+# Funcion para crear worktree para un agente
+create_agent_worktree() {
+    local agent_name="$1"
+    local worktree_path="${WORKTREE_BASE}/${agent_name}-wt"
+    local branch_name="elsabro/${agent_name}"
+
+    # Verificar limite de worktrees
+    local active=$(count_active_worktrees)
+    if [ "$active" -ge "$MAX_WORKTREES" ]; then
+        echo -e "${RED}Error: Limite de worktrees alcanzado (${MAX_WORKTREES})${NC}"
+        echo -e "${YELLOW}Usa 'cleanup' para liberar worktrees${NC}"
+        return 1
+    fi
+
+    # Si ya existe, limpiar
+    if [ -d "$worktree_path" ]; then
+        echo -e "${YELLOW}Limpiando worktree existente: ${agent_name}${NC}"
+        git worktree remove "$worktree_path" --force 2>/dev/null || true
+        git branch -D "$branch_name" 2>/dev/null || true
+    fi
+
+    # Crear branch desde HEAD actual
+    echo -e "${GREEN}Creando worktree: ${agent_name}${NC}"
+    git branch "$branch_name" HEAD 2>/dev/null || git branch -D "$branch_name" && git branch "$branch_name" HEAD
+    git worktree add "$worktree_path" "$branch_name"
+
+    echo -e "${GREEN}  Path: ${worktree_path}${NC}"
+    echo -e "${GREEN}  Branch: ${branch_name}${NC}"
+    echo "$worktree_path"
+}
+
+# Funcion para merge de worktree
+merge_agent_worktree() {
+    local agent_name="$1"
+    local branch_name="elsabro/${agent_name}"
+    local current_branch=$(git rev-parse --abbrev-ref HEAD)
+
+    # Verificar que la branch existe
+    if ! git show-ref --verify --quiet "refs/heads/${branch_name}"; then
+        echo -e "${RED}Error: Branch ${branch_name} no existe${NC}"
+        return 1
+    fi
+
+    # Verificar si hay cambios para mergear
+    local changes=$(git log "${current_branch}..${branch_name}" --oneline 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$changes" -eq 0 ]; then
+        echo -e "${YELLOW}No hay cambios en ${branch_name} para mergear${NC}"
+        return 0
+    fi
+
+    echo -e "${GREEN}Merging ${agent_name} into ${current_branch}${NC}"
+    echo -e "${BLUE}  Commits a mergear: ${changes}${NC}"
+
+    # Intentar merge
+    if git merge "$branch_name" --no-edit -m "Merge: ELSABRO ${agent_name} parallel work"; then
+        echo -e "${GREEN}  Merge exitoso${NC}"
+    else
+        echo -e "${RED}  Conflictos detectados. Resuelve manualmente.${NC}"
+        echo -e "${YELLOW}  Usa 'git merge --abort' para cancelar${NC}"
+        return 1
+    fi
+}
+
+# Funcion para cleanup de un agente especifico
+cleanup_agent_worktree() {
+    local agent_name="$1"
+    local worktree_path="${WORKTREE_BASE}/${agent_name}-wt"
+    local branch_name="elsabro/${agent_name}"
+
+    if [ -d "$worktree_path" ]; then
+        echo -e "${YELLOW}Eliminando worktree: ${agent_name}${NC}"
+        git worktree remove "$worktree_path" --force 2>/dev/null || true
+    fi
+
+    if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
+        git branch -D "$branch_name" 2>/dev/null || true
+        echo -e "${GREEN}  Branch ${branch_name} eliminada${NC}"
+    fi
+}
+
+# Funcion para cleanup de todos los worktrees
+cleanup_worktrees() {
+    echo -e "${YELLOW}Limpiando worktrees de ELSABRO...${NC}"
+
+    # Limpiar por directorio
+    if [ -d "$WORKTREE_BASE" ]; then
+        for wt in "$WORKTREE_BASE"/*-wt; do
+            if [ -d "$wt" ]; then
+                local name=$(basename "$wt" | sed 's/-wt$//')
+                echo -e "${YELLOW}  Eliminando: ${name}${NC}"
+                git worktree remove "$wt" --force 2>/dev/null || true
+                git branch -D "elsabro/${name}" 2>/dev/null || true
+            fi
+        done
+
+        # Eliminar directorio base si esta vacio
+        rmdir "$WORKTREE_BASE" 2>/dev/null || true
+    fi
+
+    # Limpiar worktrees huerfanos
+    git worktree prune
+
+    echo -e "${GREEN}Worktrees limpiados${NC}"
+}
+
+# Funcion para mostrar status
+show_status() {
+    echo -e "${BLUE}Worktrees activos:${NC}"
+    git worktree list
+    echo ""
+
+    echo -e "${BLUE}Branches de ELSABRO:${NC}"
+    git branch --list "elsabro/*" 2>/dev/null || echo "  (ninguna)"
+    echo ""
+
+    local active=$(count_active_worktrees)
+    echo -e "${BLUE}Worktrees ELSABRO: ${active}/${MAX_WORKTREES}${NC}"
+}
+
+# Crear worktrees para todos los agentes de una wave
+create_wave_worktrees() {
+    local agents=("$@")
+
+    if [ ${#agents[@]} -eq 0 ]; then
+        echo -e "${RED}Error: Especifica los agentes para la wave${NC}"
+        return 1
+    fi
+
+    echo -e "${BLUE}Creando worktrees para wave: ${agents[*]}${NC}"
+
+    for agent in "${agents[@]}"; do
+        create_agent_worktree "$agent"
+    done
+
+    echo ""
+    show_status
+}
+
+# Merge y cleanup de una wave completa
+complete_wave() {
+    local agents=("$@")
+
+    if [ ${#agents[@]} -eq 0 ]; then
+        echo -e "${RED}Error: Especifica los agentes de la wave${NC}"
+        return 1
+    fi
+
+    echo -e "${BLUE}Completando wave: ${agents[*]}${NC}"
+
+    # Merge todos los agentes
+    for agent in "${agents[@]}"; do
+        merge_agent_worktree "$agent"
+    done
+
+    # Cleanup
+    for agent in "${agents[@]}"; do
+        cleanup_agent_worktree "$agent"
+    done
+
+    echo ""
+    echo -e "${GREEN}Wave completada${NC}"
+}
+
+# Mostrar ayuda
+show_help() {
+    echo "ELSABRO Parallel Worktrees"
+    echo ""
+    echo "Uso: $0 <comando> [argumentos]"
+    echo ""
+    echo "Comandos:"
+    echo "  create <agentes...>    Crear worktrees para agentes especificos"
+    echo "  merge <agentes...>     Merge branches de agentes al branch actual"
+    echo "  cleanup [agentes...]   Limpiar worktrees (todos si no se especifica)"
+    echo "  complete <agentes...>  Merge y cleanup de una wave"
+    echo "  status                 Mostrar estado de worktrees"
+    echo "  list                   Listar todos los worktrees (git worktree list)"
+    echo ""
+    echo "Agentes disponibles: ${ELSABRO_AGENTS[*]}"
+    echo ""
+    echo "Ejemplos:"
+    echo "  $0 create analyst executor verifier"
+    echo "  $0 merge analyst executor"
+    echo "  $0 complete analyst executor verifier"
+    echo "  $0 cleanup"
+    echo "  $0 status"
+    echo ""
+    echo "Limites:"
+    echo "  - Maximo ${MAX_WORKTREES} worktrees simultaneos"
+    echo "  - Requiere git >= 2.15"
+    echo "  - Worktrees en: ${WORKTREE_BASE}"
+}
+
+# Main
+main() {
+    check_git_repo
+    check_git_version
+    ensure_worktree_base
+
+    case "$1" in
+        create)
+            shift
+            if [ $# -eq 0 ]; then
+                echo -e "${RED}Error: Especifica al menos un agente${NC}"
+                echo "Agentes disponibles: ${ELSABRO_AGENTS[*]}"
+                exit 1
+            fi
+            for agent in "$@"; do
+                create_agent_worktree "$agent"
+            done
+            ;;
+        merge)
+            shift
+            if [ $# -eq 0 ]; then
+                echo -e "${RED}Error: Especifica al menos un agente${NC}"
+                exit 1
+            fi
+            for agent in "$@"; do
+                merge_agent_worktree "$agent"
+            done
+            ;;
+        cleanup)
+            shift
+            if [ $# -eq 0 ]; then
+                cleanup_worktrees
+            else
+                for agent in "$@"; do
+                    cleanup_agent_worktree "$agent"
+                done
+            fi
+            ;;
+        complete)
+            shift
+            complete_wave "$@"
+            ;;
+        status)
+            print_header
+            show_status
+            ;;
+        list)
+            git worktree list
+            ;;
+        help|--help|-h)
+            print_header
+            show_help
+            ;;
+        *)
+            print_header
+            show_help
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"