elsabro 2.1.0 → 2.2.0

package/references/enforcement-rules.md

@@ -0,0 +1,331 @@
+# ELSABRO Enforcement Rules
+
+## REGLAS NO NEGOCIABLES
+
+Estas reglas son **OBLIGATORIAS**. No hay excepciones. No hay "casos especiales". Si no las sigues, estás violando el protocolo ELSABRO.
+
+---
+
+### 1. TaskCreate ANTES de Acción
+
+**PROHIBIDO**: Ejecutar código, modificar archivos, o hacer operaciones sin crear Task primero.
+
+**OBLIGATORIO**: Seguir la secuencia completa:
+```
+TaskCreate → TaskUpdate(in_progress) → Task() → TaskUpdate(completed)
+```
+
+**Ejemplo correcto:**
+```
+1. TaskCreate("Implementar endpoint de autenticación")
+2. TaskUpdate(id, status: "in_progress")
+3. Task("Implementa el endpoint POST /api/auth/login...")
+4. TaskUpdate(id, status: "completed", result: "...")
+```
+
+**Ejemplo INCORRECTO:**
+```
+# VIOLACIÓN: Ejecutar sin Task
+Edit(file_path: "src/api/auth.ts", ...)
+```
+
+---
+
+### 2. TaskUpdate(in_progress) ANTES de Task()
+
+**PROHIBIDO**: Lanzar `Task()` sin primero marcar la tarea como `in_progress`.
+
+**OBLIGATORIO**: Actualizar estado ANTES de ejecutar.
+
+**Razón**: El sistema necesita saber qué está en ejecución para coordinación, recuperación de errores, y visibilidad.
+
+```
+# CORRECTO
+TaskUpdate(id: "task-001", status: "in_progress")
+Task("prompt...")
+
+# INCORRECTO - VIOLACIÓN
+Task("prompt...")  # Sin TaskUpdate previo
+```
+
+---
+
+### 3. Mínimo de Agentes por Fase
+
+**PROHIBIDO**: Lanzar menos agentes del mínimo requerido.
+
+**OBLIGATORIO**: Respetar los mínimos según la fase:
+
+| Fase | Mínimo Agentes | Modelo | Paralelo |
+|------|----------------|--------|----------|
+| Exploración | 3+ | HAIKU | OBLIGATORIO |
+| Implementación | 2+ | OPUS | OBLIGATORIO |
+| Verificación | 3+ | OPUS | OBLIGATORIO |
+
+**Ejemplo exploración:**
+```
+# CORRECTO: 3 agentes haiku en paralelo
+Task("Explora estructura de archivos...")  # haiku
+Task("Busca patrones existentes...")       # haiku
+Task("Identifica dependencias...")         # haiku
+
+# INCORRECTO - VIOLACIÓN: Solo 1 agente
+Task("Explora todo el proyecto...")
+```
+
+---
+
+### 4. Paralelismo OBLIGATORIO
+
+**PROHIBIDO**: Ejecutar secuencialmente cuando se puede paralelizar.
+
+**OBLIGATORIO**: Lanzar agentes en paralelo cuando las tareas son independientes.
+
+**Regla**: Si las tareas NO dependen del resultado de otra, DEBEN ejecutarse en paralelo.
+
+```
+# CORRECTO: Paralelo
+[Task("Analiza módulo A"), Task("Analiza módulo B"), Task("Analiza módulo C")]
+
+# INCORRECTO: Secuencial innecesario
+Task("Analiza módulo A")
+# esperar...
+Task("Analiza módulo B")
+# esperar...
+Task("Analiza módulo C")
+```
+
+---
+
+### 5. Tasks API como Backend Único
+
+**PROHIBIDO**: Usar sistemas de storage duplicados (`.planning/TODOS.md`, archivos custom).
+
+**OBLIGATORIO**: Usar Claude Code Tasks API para todo el tracking.
+
+**Metadata Schema Estándar:**
+```json
+{
+  "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",
+  "source_command": "add-todo|plan|execute|etc"
+}
+```
+
+**Ejemplo correcto:**
+```javascript
+// Crear TODO
+TaskCreate({
+  subject: "Fix validation bug",
+  metadata: { type: "todo", priority: "high", category: "bug" }
+});
+
+// Consultar TODOs
+TaskList().filter(t => t.metadata?.type === "todo");
+```
+
+**Ejemplo INCORRECTO:**
+```javascript
+// VIOLACIÓN: Sistema duplicado
+fs.appendFile('.planning/TODOS.md', '- [ ] Fix validation bug');
+```
+
+---
+
+### 6. Modelo Correcto por Fase
+
+**PROHIBIDO**: Usar modelos incorrectos para cada fase.
+
+**OBLIGATORIO**: Seguir la asignación de modelos:
+
+| Fase | Modelo | Razón |
+|------|--------|-------|
+| Exploración rápida | HAIKU | Velocidad, bajo costo |
+| Análisis profundo | SONNET | Balance velocidad/calidad |
+| Implementación | OPUS | Máxima calidad |
+| Verificación crítica | OPUS | Máxima precisión |
+
+---
+
+## MATRIZ DE COMANDOS
+
+### Comandos Core (Workflow Principal)
+
+| Comando | TaskCreate | Min Agents | Paralelo | Modelo | State Sync | Notas |
+|---------|-----------|-----------|----------|--------|------------|-------|
+| `start` | **OBLIGATORIO** | 2 | **SÍ** | haiku | **SÍ** | Orquestador - detectar contexto |
+| `plan` | **OBLIGATORIO** | 3+ | **SÍ** | haiku→opus | **SÍ** | Exploración→Planificación |
+| `execute` | **OBLIGATORIO** | 3+ | **SÍ** | haiku→opus→opus | **SÍ** | Exploración→Impl→Verificación |
+| `verify-work` | **OBLIGATORIO** | 3 | **SÍ** | opus | **SÍ** | Verificación exhaustiva |
+| `debug` | **OBLIGATORIO** | 1+ | OPCIONAL | opus | **SÍ** | Diagnóstico profundo |
+| `quick` | **OBLIGATORIO** | 1 | NO | sonnet | **SÍ** | Tarea simple y rápida |
+| `new` | **OBLIGATORIO** | 2 | **SÍ** | haiku | **SÍ** | Setup inicial |
+
+### Comandos de Session Management
+
+| Comando | TaskCreate | Min Agents | Paralelo | Modelo | State Sync | Notas |
+|---------|-----------|-----------|----------|--------|------------|-------|
+| `pause-work` | **OBLIGATORIO** | 0 | NO | - | **SÍ** | Guardar contexto para retomar |
+| `resume-work` | **OBLIGATORIO** | 1 | NO | haiku | **SÍ** | Retomar contexto guardado |
+| `progress` | NO | 0 | NO | - | **SÍ** (read) | Ver estado actual |
+
+### Comandos de Milestone Management
+
+| Comando | TaskCreate | Min Agents | Paralelo | Modelo | State Sync | Notas |
+|---------|-----------|-----------|----------|--------|------------|-------|
+| `new-milestone` | **OBLIGATORIO** | 1 | NO | sonnet | **SÍ** | Crear nuevo milestone |
+| `complete-milestone` | **OBLIGATORIO** | 1 | NO | sonnet | **SÍ** | Cerrar milestone |
+| `audit-milestone` | **OBLIGATORIO** | 2 | **SÍ** | haiku→sonnet | **SÍ** | Auditar estado |
+| `plan-milestone-gaps` | **OBLIGATORIO** | 2 | **SÍ** | haiku→opus | **SÍ** | Identificar gaps |
+
+### Comandos de Phase Management
+
+| Comando | TaskCreate | Min Agents | Paralelo | Modelo | State Sync | Notas |
+|---------|-----------|-----------|----------|--------|------------|-------|
+| `add-phase` | OPCIONAL | 0 | NO | - | **SÍ** | Agregar fase al final |
+| `insert-phase` | OPCIONAL | 0 | NO | - | **SÍ** | Insertar fase en posición |
+| `remove-phase` | OPCIONAL | 0 | NO | - | **SÍ** | Eliminar fase |
+| `discuss-phase` | **OBLIGATORIO** | 1 | NO | sonnet | NO | Discusión interactiva |
+| `research-phase` | **OBLIGATORIO** | 2 | **SÍ** | haiku | **SÍ** | Investigar tecnologías |
+| `list-phase-assumptions` | NO | 0 | NO | - | NO | Listar supuestos |
+
+### Comandos de Todo Management
+
+| Comando | TaskCreate | Min Agents | Paralelo | Modelo | State Sync | Notas |
+|---------|-----------|-----------|----------|--------|------------|-------|
+| `add-todo` | OPCIONAL | 0 | NO | - | NO | Agregar item |
+| `check-todos` | NO | 0 | NO | - | NO | Ver lista |
+
+### Comandos de Utilidad
+
+| Comando | TaskCreate | Min Agents | Paralelo | Modelo | State Sync | Notas |
+|---------|-----------|-----------|----------|--------|------------|-------|
+| `help` | NO | 0 | NO | - | NO | Solo información |
+| `settings` | NO | 0 | NO | - | NO | Solo configuración |
+| `set-profile` | NO | 0 | NO | - | NO | Cambiar perfil |
+| `update` | NO | 0 | NO | - | NO | Actualizar ELSABRO |
+| `map-codebase` | **OBLIGATORIO** | 2 | **SÍ** | haiku | NO | Mapear proyecto |
+| `verify` | **OBLIGATORIO** | 1 | NO | sonnet | NO | Verificar feature |
+
+---
+
+## SECUENCIA OBLIGATORIA POR COMANDO
+
+### /elsabro:execute
+```
+1. TaskCreate("Fase exploración")
+2. TaskUpdate(in_progress)
+3. Task(haiku) x3 [paralelo] - Explorar contexto
+4. TaskUpdate(completed)
+
+5. TaskCreate("Fase implementación")
+6. TaskUpdate(in_progress)
+7. Task(opus) x2 [paralelo] - Implementar
+8. TaskUpdate(completed)
+
+9. TaskCreate("Fase verificación")
+10. TaskUpdate(in_progress)
+11. Task(opus) x3 [paralelo] - Verificar
+12. TaskUpdate(completed)
+```
+
+### /elsabro:plan
+```
+1. TaskCreate("Explorar requerimientos")
+2. TaskUpdate(in_progress)
+3. Task(haiku) x3 [paralelo] - Explorar codebase
+4. TaskUpdate(completed)
+
+5. TaskCreate("Generar plan")
+6. TaskUpdate(in_progress)
+7. Task(opus) x2 [paralelo] - Crear plan detallado
+8. TaskUpdate(completed)
+```
+
+### /elsabro:verify-work
+```
+1. TaskCreate("Verificación exhaustiva")
+2. TaskUpdate(in_progress)
+3. Task(opus) x3 [paralelo]:
+   - Verificar funcionalidad
+   - Verificar tests
+   - Verificar integración
+4. TaskUpdate(completed)
+```
+
+### /elsabro:debug
+```
+1. TaskCreate("Diagnóstico")
+2. TaskUpdate(in_progress)
+3. Task(opus) x1+ - Investigar problema
+4. TaskUpdate(completed)
+```
+
+### /elsabro:quick
+```
+1. TaskCreate("Tarea rápida")
+2. TaskUpdate(in_progress)
+3. Task(sonnet) x1 - Ejecutar tarea simple
+4. TaskUpdate(completed)
+```
+
+### /elsabro:new
+```
+1. TaskCreate("Setup proyecto")
+2. TaskUpdate(in_progress)
+3. Task(haiku) x2 [paralelo] - Analizar y crear estructura
+4. TaskUpdate(completed)
+```
+
+---
+
+## VIOLACIONES Y CONSECUENCIAS
+
+### Violación Crítica
+- Ejecutar sin TaskCreate
+- Lanzar Task sin TaskUpdate(in_progress)
+- Menos agentes del mínimo
+
+**Consecuencia**: Abortar operación. No continuar.
+
+### Violación Mayor
+- No paralelizar cuando es posible
+- Modelo incorrecto para la fase
+
+**Consecuencia**: Warning. Corregir antes de continuar.
+
+### Violación Menor
+- TaskUpdate(completed) sin resultado claro
+
+**Consecuencia**: Registrar. Continuar con precaución.
+
+---
+
+## CHECKLIST DE AUTO-VERIFICACIÓN
+
+Antes de cada operación, verifica:
+
+- [ ] TaskCreate ejecutado
+- [ ] TaskUpdate(in_progress) ejecutado
+- [ ] Cantidad de agentes >= mínimo requerido
+- [ ] Agentes lanzados en paralelo (si aplica)
+- [ ] Modelo correcto para la fase
+- [ ] TaskUpdate(completed) al finalizar
+
+---
+
+## NOTAS FINALES
+
+1. **No hay atajos**: Estas reglas existen por razones de rendimiento, coordinación y calidad.
+
+2. **Paralelismo = Velocidad**: 3 agentes en paralelo terminan antes que 3 secuenciales.
+
+3. **Tasks = Visibilidad**: Sin Tasks, no hay tracking, no hay recuperación de errores.
+
+4. **Modelos = Costo/Beneficio**: Haiku para explorar, Opus para implementar. No al revés.
+
+5. **Mínimos son mínimos**: Puedes usar MÁS agentes, nunca MENOS.

package/references/error-handling-instructions.md

@@ -19,7 +19,7 @@ Cuando encuentres un error, clasifícalo usando esta escala:
 ```
 
 **Ejemplos:**
-- SESSION.md corrupto o faltante
+- `.elsabro/state.json` corrupto o faltante
 - Archivos de configuración críticos inválidos
 - Dependencias con versiones incompatibles
 - Estado de git inconsistente (detached HEAD, conflictos)
@@ -102,18 +102,18 @@ Usa este formato visual para errores:
 ### Error CRITICAL
 ```
 ╔══════════════════════════════════════════════════╗
-║  🔴 ERROR: SESSION_MISSING                       ║
+║  🔴 ERROR: STATE_MISSING                         ║
 ║  Severity: CRITICAL                              ║
 ╠══════════════════════════════════════════════════╣
 ║                                                  ║
-║  No se encontró el archivo de sesión             ║
+║  No se encontró el archivo de estado             ║
 ║                                                  ║
-║  El archivo .planning/SESSION.md no existe       ║
+║  El archivo .elsabro/state.json no existe        ║
 ║  o está corrupto.                                ║
 ║                                                  ║
 ╠══════════════════════════════════════════════════╣
 ║  ACCIÓN REQUERIDA:                               ║
-║  → /elsabro:start para iniciar nueva sesión      ║
+║  → /elsabro:start para inicializar proyecto      ║
 ╚══════════════════════════════════════════════════╝
 ```
 
@@ -276,17 +276,31 @@ Attempt 3: Esperar 2s, reintentar
 
 ## Actualización de Estado
 
-Después de cada operación significativa, actualiza `.planning/SESSION-STATE.json`:
+**IMPORTANTE**: El archivo de estado unificado es `.elsabro/state.json` (ver `/references/state-sync.md`).
+
+Después de cada operación significativa, actualiza `.elsabro/state.json`:
 
 ```json
 {
-  "lastUpdated": "2024-01-20T15:30:00Z",
+  "version": "1.0.0",
+  "updated_at": "2024-01-20T15:30:00Z",
+  "current_flow": {
+    "command": "execute",
+    "phase": "executing_wave_2",
+    "started_at": "2024-01-20T15:00:00Z"
+  },
   "context": {
-    "milestone": "M001",
-    "phase": "P3",
-    "progress": 65,
-    "currentTask": "Implement user profile"
+    "project_type": "brownfield",
+    "tech_stack": ["nextjs", "prisma"],
+    "current_feature": "user-profile"
   },
+  "history": [
+    {
+      "command": "plan",
+      "completed_at": "2024-01-20T14:50:00Z",
+      "result": "created"
+    }
+  ],
   "errors": {
     "count": 1,
     "lastError": {
@@ -307,6 +321,6 @@ Antes de reportar "completado":
 
 - [ ] ¿Hubo errores? → Clasificados y reportados
 - [ ] ¿Hubo warnings? → Listados al final
-- [ ] ¿Estado actualizado? → SESSION-STATE.json actualizado
+- [ ] ¿Estado actualizado? → .elsabro/state.json actualizado (ver /references/state-sync.md)
 - [ ] ¿Retry necesario? → Intentado con backoff
 - [ ] ¿Ejecución paralela? → Política aplicada, resultados agregados