elsabro 2.0.1 → 2.2.0

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

package/references/state-sync.md

@@ -0,0 +1,381 @@
+# ELSABRO State Synchronization
+
+## PROTOCOLO DE SINCRONIZACIÓN DE ESTADO
+
+Este documento define cómo todos los comandos ELSABRO deben sincronizarse con el estado compartido en `.elsabro/state.json`.
+
+---
+
+## REGLA FUNDAMENTAL
+
+**Todo comando DEBE:**
+1. LEER `.elsabro/state.json` al iniciar
+2. VERIFICAR si hay flujo en progreso
+3. ACTUALIZAR estado al cambiar de fase
+4. ESCRIBIR estado al completar
+
+**NO HAY EXCEPCIONES.**
+
+---
+
+## CÓDIGO DE SINCRONIZACIÓN (Copiar a cada comando)
+
+### Al Iniciar (OBLIGATORIO)
+
+```javascript
+// SYNC: Leer estado existente
+const stateFile = ".elsabro/state.json";
+let state = null;
+
+try {
+  state = Read(stateFile);
+  state = JSON.parse(state);
+} catch {
+  // Primera vez - crear estado inicial
+  state = {
+    version: "1.0.0",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    current_flow: null,
+    context: {},
+    history: [],
+    pending_tasks: [],
+    blocked_on: null
+  };
+}
+
+// SYNC: Verificar flujo en progreso
+if (state.current_flow && state.current_flow.command !== "[ESTE_COMANDO]") {
+  // Advertir al usuario
+  AskUserQuestion({
+    questions: [{
+      question: `Hay un flujo de "${state.current_flow.command}" en progreso. ¿Qué quieres hacer?`,
+      header: "Flujo",
+      options: [
+        { label: "Continuar ese flujo", description: "Retomar donde lo dejaste" },
+        { label: "Empezar este comando", description: "Pausar el anterior y empezar este" }
+      ],
+      multiSelect: false
+    }]
+  });
+}
+
+// SYNC: Marcar inicio de este comando
+state.current_flow = {
+  command: "[ESTE_COMANDO]",
+  phase: "initializing",
+  started_at: new Date().toISOString()
+};
+state.updated_at = new Date().toISOString();
+Write(stateFile, JSON.stringify(state, null, 2));
+```
+
+### Al Cambiar de Fase (OBLIGATORIO)
+
+```javascript
+// SYNC: Actualizar fase
+state.current_flow.phase = "[NUEVA_FASE]";
+state.updated_at = new Date().toISOString();
+Write(stateFile, JSON.stringify(state, null, 2));
+```
+
+### Al Completar (OBLIGATORIO)
+
+```javascript
+// SYNC: Registrar en historial
+state.history.push({
+  command: "[ESTE_COMANDO]",
+  completed_at: new Date().toISOString(),
+  result: "[resultado]",
+  artifact: "[path a archivo generado o null]"
+});
+
+// SYNC: Limpiar flujo actual
+state.current_flow = null;
+state.updated_at = new Date().toISOString();
+
+// SYNC: Sugerir siguiente comando
+state.suggested_next = "[siguiente_comando_sugerido]";
+
+Write(stateFile, JSON.stringify(state, null, 2));
+```
+
+---
+
+## FASES POR COMANDO
+
+### /elsabro:start
+```
+Fases: initializing → detecting_context → greeting → transitioning → done
+```
+
+### /elsabro:plan
+```
+Fases: initializing → exploring → researching → planning → validating → done
+```
+
+### /elsabro:execute
+```
+Fases: initializing → exploring → executing_wave_N → verifying → done
+```
+
+### /elsabro:verify-work
+```
+Fases: initializing → verifying → aggregating → done
+```
+
+### /elsabro:debug
+```
+Fases: initializing → diagnosing → fixing → verifying → done
+```
+
+### /elsabro:quick
+```
+Fases: initializing → executing → done
+```
+
+---
+
+## CONTEXTO QUE CADA COMANDO DEBE PASAR
+
+### start → plan
+```json
+{
+  "project_type": "greenfield | brownfield | continuation",
+  "tech_stack": ["detectado"],
+  "user_intent": "add_feature | fix_bug | refactor | understand"
+}
+```
+
+### start → new
+```json
+{
+  "project_type": "greenfield",
+  "selected_skill": "full-stack-app | mobile-app | etc",
+  "user_level": "beginner | intermediate | advanced"
+}
+```
+
+### plan → execute
+```json
+{
+  "plan_file": ".planning/01-PLAN.md",
+  "phases": [1, 2, 3],
+  "tech_stack": ["verificado con Context7"],
+  "ready_for_execution": true
+}
+```
+
+### execute → verify-work
+```json
+{
+  "changed_files": ["src/auth.ts", "src/api/login.ts"],
+  "commits": ["abc123", "def456"],
+  "tests_added": ["tests/auth.test.ts"],
+  "phase_completed": 1
+}
+```
+
+### verify-work → (complete)
+```json
+{
+  "verification_result": "PASS | FAIL | PARTIAL",
+  "ready_for_merge": true,
+  "report_path": ".planning/VERIFICATION-REPORT.md"
+}
+```
+
+### debug → execute
+```json
+{
+  "root_cause": "descripción del problema",
+  "fix_approach": "plan de corrección",
+  "affected_files": ["archivos a modificar"]
+}
+```
+
+---
+
+## TRANSICIONES VÁLIDAS
+
+```
+start → new        ✓
+start → plan       ✓
+start → debug      ✓
+start → quick      ✓
+
+new → plan         ✓
+new → execute      ✗ (necesita plan)
+
+plan → execute     ✓
+plan → plan        ✓ (refinar)
+
+execute → verify   ✓
+execute → execute  ✓ (continuar)
+
+verify → execute   ✓ (fix gaps)
+verify → done      ✓
+
+debug → execute    ✓
+debug → plan       ✓ (fix complejo)
+
+quick → verify     ✓
+quick → done       ✓
+```
+
+---
+
+## ACTUALIZACIÓN DE context.md
+
+Después de cada comando, actualizar `.elsabro/context.md` para humanos:
+
+```markdown
+# Estado Actual del Proyecto
+
+**Última actualización**: [timestamp]
+**Comando actual**: [current_flow.command o "ninguno"]
+**Fase**: [current_flow.phase o "completado"]
+
+## Contexto del Proyecto
+- **Tipo**: [context.project_type]
+- **Stack**: [context.tech_stack]
+- **Feature actual**: [context.current_feature]
+
+## Historial Reciente
+1. [history[-1].command] - [history[-1].result] ([timestamp])
+2. [history[-2].command] - [history[-2].result] ([timestamp])
+3. [history[-3].command] - [history[-3].result] ([timestamp])
+
+## Siguiente Paso Sugerido
+[suggested_next o inferir de context]
+
+## Para Continuar
+```bash
+# Si hay flujo en progreso
+/elsabro:start  # Te preguntará si continuar
+
+# Si empezar algo nuevo
+/elsabro:[comando]  # Empezar directamente
+```
+```
+
+---
+
+## RECUPERACIÓN DE ESTADO
+
+### Si el usuario vuelve después de pausa
+
+1. Leer `.elsabro/state.json`
+2. Si `current_flow !== null`:
+   - Mostrar qué estaba haciendo
+   - Ofrecer continuar o empezar nuevo
+3. Si `current_flow === null`:
+   - Mostrar historial reciente
+   - Sugerir siguiente paso basado en `suggested_next`
+
+### Si `.elsabro/state.json` está corrupto
+
+1. Intentar leer `.elsabro/context.md` para contexto
+2. Si falla, empezar fresh pero advertir al usuario
+3. Crear backup del archivo corrupto
+
+### Si hay cambios sin commit
+
+1. Detectar con `git status`
+2. Advertir al usuario
+3. Ofrecer:
+   - Continuar donde lo dejó
+   - Guardar cambios (commit)
+   - Descartar cambios
+
+---
+
+## CHECKLIST DE SINCRONIZACIÓN
+
+Cada comando debe verificar antes de completar:
+
+- [ ] `state.json` leído al inicio
+- [ ] Flujo en progreso verificado
+- [ ] `current_flow` actualizado al iniciar
+- [ ] `current_flow.phase` actualizado en cada cambio
+- [ ] `history` actualizado al completar
+- [ ] `current_flow` limpiado al completar
+- [ ] `suggested_next` establecido
+- [ ] `context.md` actualizado
+- [ ] Contexto relevante pasado al siguiente comando
+
+---
+
+## EJEMPLO COMPLETO: Flow de Feature Nueva
+
+```
+# Usuario ejecuta /elsabro:start
+
+1. start lee state.json (vacío o existente)
+2. start detecta: brownfield
+3. Usuario elige: "Agregar funcionalidad"
+4. start actualiza state.json:
+   {
+     current_flow: { command: "start", phase: "transitioning" },
+     context: { user_intent: "add_feature", project_type: "brownfield" }
+   }
+5. start invoca /elsabro:plan con contexto
+
+# /elsabro:plan toma control
+
+6. plan lee state.json → ve que viene de start
+7. plan actualiza: current_flow: { command: "plan", phase: "exploring" }
+8. plan ejecuta exploración (HAIKU x3)
+9. plan actualiza: current_flow.phase: "researching"
+10. plan crea RESEARCH.md y PLAN.md
+11. plan actualiza: current_flow.phase: "validating"
+12. plan valida el plan
+13. plan actualiza state.json:
+    {
+      current_flow: null,
+      context: { ...existing, plan_file: ".planning/01-PLAN.md", ready_for_execution: true },
+      history: [..., { command: "plan", result: "created", artifact: ".planning/01-PLAN.md" }],
+      suggested_next: "execute"
+    }
+14. plan sugiere al usuario: "¿Ejecutar? → /elsabro:execute 1"
+
+# /elsabro:execute toma control
+
+15. execute lee state.json → ve plan_file y ready_for_execution
+16. execute actualiza: current_flow: { command: "execute", phase: "exploring" }
+17. execute explora (HAIKU x3)
+18. execute actualiza: current_flow.phase: "executing_wave_1"
+19. execute implementa (OPUS x2)
+20. execute actualiza: current_flow.phase: "verifying"
+21. execute verifica (OPUS x3)
+22. execute actualiza state.json:
+    {
+      current_flow: null,
+      context: { ...existing, changed_files: [...], commits: [...] },
+      history: [..., { command: "execute", result: "completed", artifact: null }],
+      suggested_next: "verify-work"
+    }
+
+# /elsabro:verify-work finaliza
+
+23. verify lee state.json → ve changed_files y commits
+24. verify ejecuta verificación (OPUS x3)
+25. verify actualiza state.json:
+    {
+      current_flow: null,
+      context: { ...existing, verification_result: "PASS" },
+      history: [..., { command: "verify-work", result: "PASS" }],
+      suggested_next: null  // Feature completa
+    }
+26. verify muestra: "¡Listo para merge!"
+```
+
+---
+
+## NOTAS DE IMPLEMENTACIÓN
+
+1. **Atomic Writes**: Usar Write con JSON completo, no edits parciales
+2. **Timestamps ISO**: Siempre usar `new Date().toISOString()`
+3. **Contexto Acumulativo**: Cada comando agrega contexto, nunca reemplaza
+4. **History Limitado**: Mantener últimos 20 entries, archivar resto
+5. **Backup Diario**: Crear `.elsabro/history/YYYY-MM-DD.json` con estado del día