elsabro 2.1.0 → 2.3.0

package/agents/elsabro-orchestrator.md

@@ -150,6 +150,119 @@ Para cada story sin dependencias:
 ```
 </execution_pattern>
 
+<error_contracts>
+## Contratos de Error en Ejecución Paralela
+
+**IMPORTAR**: Este agente DEBE seguir `/references/error-contracts.md` para manejo de errores.
+
+### Integración Obligatoria
+
+Antes de ejecutar cualquier wave, el orquestador DEBE:
+
+1. **Validar Registry** (ContractRegistryValidator)
+```javascript
+const validator = new ContractRegistryValidator("./agents");
+const batch = await validator.validateBatch(agentsNeeded);
+if (!batch.canProceed) {
+  displayError({
+    severity: "CRITICAL",
+    message: `${batch.invalid} agentes faltantes`,
+    options: ["update", "help", "abort"]
+  });
+  return;
+}
+```
+
+2. **Validar Sesión** (ContractSessionValidator)
+```javascript
+const sessionValidator = new ContractSessionValidator();
+const session = await sessionValidator.load();
+if (!session.success) {
+  // Intentar reparar o escalar a usuario
+}
+```
+
+3. **Iniciar Timeout** (ContractTimeoutHandler)
+```javascript
+const timeoutHandler = new ContractTimeoutHandler();
+timeoutHandler.startTimeout(waveId, 30 * 60 * 1000);
+```
+
+### Durante Ejecución Paralela
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│             ERROR HANDLING EN WAVES PARALELAS                       │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Wave N ejecutando:                                                 │
+│  ├─ Agent 1 ──→ SUCCESS ──┐                                        │
+│  ├─ Agent 2 ──→ FAILED ───┼──→ ErrorAggregator.addResult()         │
+│  └─ Agent 3 ──→ SUCCESS ──┘                                        │
+│                           ↓                                         │
+│                    ErrorAggregator.aggregate()                      │
+│                           ↓                                         │
+│              ┌────────────┴────────────┐                           │
+│              │ Aplicar Policy (quorum) │                           │
+│              └────────────┬────────────┘                           │
+│                           ↓                                         │
+│    ┌──────────────────────┴──────────────────────┐                 │
+│    │ 2/3 = 66% > 50%      │ 1/3 = 33% < 50%      │                 │
+│    │ → CONTINUE           │ → STOP               │                 │
+│    │ → Notificar warning  │ → Escalar a usuario  │                 │
+│    └──────────────────────┴──────────────────────┘                 │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Retry Automático
+
+Para errores transitorios (timeout, network):
+
+```javascript
+const retryPolicy = new ContractRetryPolicy({
+  maxAttempts: 3,
+  baseDelayMs: 1000,
+  backoffMultiplier: 2
+});
+
+const result = await retryPolicy.executeWithRetry(
+  operationId,
+  async () => executeAgent(agent),
+  { wave: waveId }
+);
+```
+
+### Notificación al Usuario
+
+**INMEDIATA para CRITICAL:**
+```
+╔════════════════════════════════════════════════════╗
+║  🔴 CRITICAL: Wave 2 Agent Failed                  ║
+╠════════════════════════════════════════════════════╣
+║  Agent: elsabro-verifier                           ║
+║  Error: Timeout after 30 minutes                   ║
+║                                                    ║
+║  [r] Retry now  [s] Skip  [a] Abort               ║
+╚════════════════════════════════════════════════════╝
+```
+
+**AL FINAL para otros:**
+```
+╔════════════════════════════════════════════════════╗
+║  PARALLEL EXECUTION SUMMARY                        ║
+╠════════════════════════════════════════════════════╣
+║  Waves: 3/3 completed                              ║
+║  Agents: 8/9 succeeded (89%)                       ║
+║                                                    ║
+║  Errors:                                           ║
+║  └─ Wave 2: elsabro-qa timeout (retried 2x)       ║
+║                                                    ║
+║  Status: SUCCESS (quorum met)                      ║
+╚════════════════════════════════════════════════════╝
+```
+</error_contracts>
+
 <conflict_resolution>
 ## Resolución de Conflictos
 

package/commands/elsabro/add-phase.md

@@ -1,10 +1,27 @@
 ---
 name: add-phase
 description: Agregar una nueva fase al final del milestone actual
+sync:
+  reads: [".elsabro/state.json"]
+  writes: [".elsabro/state.json"]
 ---
 
 # /elsabro:add-phase
 
+<state_sync>
+## SINCRONIZACION DE ESTADO
+
+**IMPORTAR**: Ver `/references/state-sync.md` para protocolo completo.
+
+### Al Iniciar
+- Leer `.elsabro/state.json`
+- Verificar contexto actual del milestone/phase
+
+### Al Completar
+- Registrar cambio en `history`
+- Actualizar `context` si corresponde
+</state_sync>
+
 <command-name>add-phase</command-name>
 
 ## Propósito

package/commands/elsabro/add-todo.md

@@ -1,6 +1,11 @@
 ---
 name: add-todo
 description: Agregar un item al todo list del proyecto actual
+allowed-tools:
+  - TaskCreate
+  - TaskList
+  - Read
+  - AskUserQuestion
 ---
 
 # /elsabro:add-todo
@@ -9,7 +14,7 @@ description: Agregar un item al todo list del proyecto actual
 
 ## Propósito
 
-Agregar tareas rápidas al todo list del proyecto. Para items que no merecen ser una fase o story completa.
+Agregar tareas rápidas al todo list del proyecto usando **Claude Code Tasks API** como backend. Para items que no merecen ser una fase o story completa.
 
 ## Cuándo Usar
 
@@ -63,96 +68,149 @@ Agregar tareas rápidas al todo list del proyecto. Para items que no merecen ser
 | `medium` | Normal (default) |
 | `low` | Cuando haya tiempo |
 
-## Almacenamiento
+---
 
-Todos se guardan en `.planning/TODOS.md`:
+## Implementación (Tasks API)
 
-```markdown
-# Project TODOs
+<implementation>
+Cuando el usuario ejecuta `/elsabro:add-todo`:
 
-## Critical 🔴
-- [ ] Fix authentication token refresh (#123)
+### 1. Parse Arguments
 
-## High Priority 🟠
-- [ ] Update React to v18.3 (tech-debt)
-- [ ] Add loading states to dashboard (ux)
+```
+INPUT: /elsabro:add-todo "Fix typo in README" --priority=high --category=docs
+PARSE:
+  - description: "Fix typo in README"
+  - priority: "high" (default: "medium")
+  - category: "docs" (default: "chore")
+  - due: null (opcional)
+  - milestone: null (opcional)
+```
 
-## Medium Priority 🟡
-- [ ] Fix typo in README (docs) - Added 2024-01-20
-- [ ] Add error boundary (tech-debt)
-- [ ] Document API endpoints (docs)
+### 2. Crear Task
+
+```javascript
+TaskCreate({
+  subject: "Fix typo in README",
+  description: "User-created TODO: Fix typo in README\n\nCategory: docs\nPriority: high",
+  activeForm: "Working on: Fix typo in README",
+  metadata: {
+    type: "todo",
+    priority: "high",
+    category: "docs",
+    due_date: null,
+    milestone_id: null,
+    created_by: "user",
+    source_command: "add-todo",
+    created_at: "ISO-8601 timestamp"
+  }
+})
+```
 
-## Low Priority ⬜
-- [ ] Investigate dark mode (idea)
-- [ ] Consider adding PWA support (idea)
+### 3. Output
 
-## Completed ✅
-- [x] Set up CI pipeline (2024-01-18)
-- [x] Add basic tests (2024-01-19)
 ```
+✓ TODO added (Task #<ID>)
 
-## Interactivo
+  Subject: Fix typo in README
+  Priority: high
+  Category: docs
+  Due: -
 
-```bash
-/elsabro:add-todo
+  View all: /elsabro:check-todos
 ```
 
+### 4. Contar TODOs existentes
+
+```javascript
+// Listar todos los tasks tipo "todo"
+TaskList()
+  .filter(t => t.metadata?.type === "todo" && t.status !== "completed")
+
+// Mostrar conteo por prioridad
+  Total TODOs: 8 (2 high, 4 medium, 2 low)
 ```
-Add new TODO:
+</implementation>
 
-Description: Update error messages
-Priority (critical/high/medium/low): high
-Category (bug/tech-debt/docs/chore/idea/question): ux
-Due date (optional):
+---
+
+## Modo Interactivo
 
-Added: "Update error messages" [high/ux]
+```bash
+/elsabro:add-todo
 ```
 
+Si no se proporciona descripción, usar AskUserQuestion:
+
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "What TODO do you want to add?",
+      header: "Description",
+      options: [
+        { label: "Bug fix", description: "Minor bug to fix" },
+        { label: "Tech debt", description: "Code improvement" },
+        { label: "Documentation", description: "Docs to write" },
+        { label: "Other", description: "Custom description" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+---
+
 ## Opciones
 
 ```bash
 --priority, -p     # critical/high/medium/low
 --category, -c     # Category tag
---due, -d          # Due date
---milestone, -m    # Link to milestone
---phase            # Link to phase
+--due, -d          # Due date (ISO-8601)
+--milestone, -m    # Link to milestone ID
+--phase            # Link to phase ID
 ```
 
-## Quick Add
+## Quick Add (Batch)
 
-Para agregar múltiples todos rápidamente:
+Para agregar múltiples todos:
 
 ```bash
 /elsabro:add-todo --batch
 ```
 
+```javascript
+// Crear múltiples Tasks en paralelo
+TaskCreate({ subject: "Fix button alignment", metadata: {...} })
+TaskCreate({ subject: "Add form validation", metadata: {...} })
+TaskCreate({ subject: "Update user docs", metadata: {...} })
 ```
-Enter TODOs (one per line, empty to finish):
-> Fix button alignment
-> Add form validation
-> Update user docs
->
 
-Added 3 TODOs (all medium priority)
-```
-
-## Output
+---
 
+## Metadata Schema
+
+```json
+{
+  "type": "todo",
+  "priority": "critical|high|medium|low",
+  "category": "bug|tech-debt|docs|chore|idea|question",
+  "due_date": "ISO-8601 | null",
+  "milestone_id": "M001 | null",
+  "phase_id": "P001 | null",
+  "created_by": "user|system",
+  "source_command": "add-todo",
+  "created_at": "ISO-8601"
+}
 ```
-✓ TODO added
 
-  Description: Fix typo in README
-  Priority: medium
-  Category: docs
-  Due: -
-
-  Total TODOs: 8 (2 high, 4 medium, 2 low)
-
-  View all: /elsabro:check-todos
-```
+---
 
 ## Integración
 
 - View with `/elsabro:check-todos`
 - Referenced in `/elsabro:progress`
 - Can be promoted to phase task with `/elsabro:add-phase`
+- Persists across sessions via Tasks API
+- Supports dependencies with `blocks/blockedBy`

package/commands/elsabro/audit-milestone.md

@@ -1,10 +1,29 @@
 ---
 name: audit-milestone
 description: Auditar el estado actual de un milestone - progreso, riesgos y recomendaciones
+sync:
+  reads: [".elsabro/state.json"]
+  writes: [".elsabro/state.json", ".elsabro/context.md"]
 ---
 
 # /elsabro:audit-milestone
 
+<state_sync>
+## SINCRONIZACION DE ESTADO
+
+**IMPORTAR**: Ver `/references/state-sync.md` para protocolo completo.
+
+### Al Iniciar
+- Leer `.elsabro/state.json`
+- Verificar si hay flujo en progreso
+- Actualizar `current_flow.command` con este comando
+
+### Al Completar
+- Registrar en `history`
+- Actualizar `context` con informacion del milestone
+- Limpiar `current_flow`
+</state_sync>
+
 <command-name>audit-milestone</command-name>
 
 ## Propósito