elsabro 2.1.0 → 2.2.0

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