elsabro 2.1.0 → 2.3.0

package/references/command-flow.md

@@ -0,0 +1,352 @@
+# ELSABRO Command Flow & Synchronization
+
+## ESTADO COMPARTIDO
+
+Los comandos ELSABRO se sincronizan a través de un sistema de estado compartido. Esto permite que cada comando sepa dónde está el usuario en el flujo y qué contexto necesita.
+
+---
+
+## FLUJO PRINCIPAL
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          /elsabro:start                              │
+│                    (Entry Point - Orquestador)                       │
+└─────────────────────────┬───────────────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┬───────────────┐
+          ▼               ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │  :new    │    │  :plan   │    │  :debug  │    │  :quick  │
+    │ Proyecto │    │ Feature  │    │  Bugs    │    │  Rápido  │
+    │  nuevo   │    │  nueva   │    │          │    │          │
+    └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
+         │               │               │               │
+         ▼               ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐         │
+    │ :execute │◄───│ :execute │◄───│ :execute │         │
+    │          │    │          │    │          │         │
+    └────┬─────┘    └────┬─────┘    └────┬─────┘         │
+         │               │               │               │
+         └───────────────┴───────────────┴───────────────┘
+                                │
+                                ▼
+                         ┌──────────────┐
+                         │ :verify-work │
+                         │  (Siempre)   │
+                         └──────────────┘
+```
+
+---
+
+## ARCHIVO DE ESTADO: .elsabro/state.json
+
+Cada proyecto ELSABRO mantiene un archivo de estado en `.elsabro/state.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T14:45:00Z",
+
+  "current_flow": {
+    "command": "execute",
+    "phase": "implementation",
+    "started_at": "2024-01-15T14:30:00Z"
+  },
+
+  "context": {
+    "project_type": "fullstack",
+    "tech_stack": ["nextjs", "prisma", "postgresql"],
+    "current_feature": "auth-system"
+  },
+
+  "history": [
+    {
+      "command": "start",
+      "completed_at": "2024-01-15T10:30:00Z",
+      "result": "redirected_to_new"
+    },
+    {
+      "command": "new",
+      "completed_at": "2024-01-15T11:00:00Z",
+      "result": "project_created"
+    },
+    {
+      "command": "plan",
+      "completed_at": "2024-01-15T12:30:00Z",
+      "result": "plan_approved",
+      "artifact": ".planning/auth-plan.md"
+    }
+  ],
+
+  "pending_tasks": [],
+  "blocked_on": null
+}
+```
+
+---
+
+## SINCRONIZACIÓN ENTRE COMANDOS
+
+### Regla 1: Leer Estado Antes de Actuar
+
+**OBLIGATORIO**: Todo comando debe leer `.elsabro/state.json` al iniciar.
+
+```typescript
+// Pseudo-código - cada comando hace esto primero
+const state = readState(".elsabro/state.json");
+
+if (!state) {
+  // Primera vez - inicializar
+  createState();
+}
+
+// Verificar si hay flujo en progreso
+if (state.current_flow && state.current_flow.command !== thisCommand) {
+  // Advertir al usuario
+  warn(`Hay un flujo de ${state.current_flow.command} en progreso`);
+  askUser("¿Continuar con ese flujo o iniciar uno nuevo?");
+}
+```
+
+### Regla 2: Actualizar Estado al Cambiar de Fase
+
+**OBLIGATORIO**: Actualizar `current_flow` al cambiar de fase o comando.
+
+```typescript
+// Al iniciar una fase
+updateState({
+  current_flow: {
+    command: "execute",
+    phase: "exploration",
+    started_at: new Date().toISOString()
+  }
+});
+
+// Al completar
+updateState({
+  current_flow: null,
+  history: [...state.history, {
+    command: "execute",
+    completed_at: new Date().toISOString(),
+    result: "success"
+  }]
+});
+```
+
+### Regla 3: Pasar Contexto Entre Comandos
+
+**OBLIGATORIO**: Los comandos deben preservar y extender el contexto.
+
+| De | A | Contexto Pasado |
+|----|---|-----------------|
+| start | new | project_type, user_level |
+| start | plan | existing_codebase_info |
+| new | plan | tech_stack, project_structure |
+| plan | execute | plan_file_path, acceptance_criteria |
+| execute | verify-work | changed_files, test_locations |
+| debug | execute | root_cause, fix_approach |
+
+---
+
+## PUNTOS DE SINCRONIZACIÓN
+
+### Checkpoint 1: Después de start
+
+```json
+{
+  "checkpoint": "post_start",
+  "data": {
+    "user_intent": "create_new_app | add_feature | fix_bug | understand",
+    "detected_context": "greenfield | brownfield | continuation",
+    "next_command": "new | plan | debug | analyst"
+  }
+}
+```
+
+### Checkpoint 2: Después de plan
+
+```json
+{
+  "checkpoint": "post_plan",
+  "data": {
+    "plan_file": ".planning/feature-xyz.md",
+    "phases": ["setup", "core", "integration", "tests"],
+    "estimated_complexity": "low | medium | high",
+    "ready_for_execution": true
+  }
+}
+```
+
+### Checkpoint 3: Después de execute
+
+```json
+{
+  "checkpoint": "post_execute",
+  "data": {
+    "changed_files": ["src/auth.ts", "src/api/login.ts"],
+    "tests_added": ["tests/auth.test.ts"],
+    "commits": ["abc123", "def456"],
+    "verification_pending": true
+  }
+}
+```
+
+---
+
+## TRANSICIONES VÁLIDAS
+
+```
+start → new         ✓ (proyecto nuevo)
+start → plan        ✓ (feature en proyecto existente)
+start → debug       ✓ (resolver problema)
+start → quick       ✓ (tarea simple)
+
+new → plan          ✓ (siguiente paso natural)
+new → execute       ✗ (necesita plan primero)
+
+plan → execute      ✓ (ejecutar el plan)
+plan → plan         ✓ (refinar plan)
+
+execute → verify    ✓ (verificar trabajo)
+execute → execute   ✓ (continuar implementación)
+
+verify → execute    ✓ (corregir problemas encontrados)
+verify → [done]     ✓ (trabajo completado)
+
+debug → execute     ✓ (aplicar fix)
+debug → plan        ✓ (fix complejo necesita plan)
+
+quick → verify      ✓ (verificar tarea rápida)
+quick → [done]      ✓ (tarea completada)
+```
+
+---
+
+## RECUPERACIÓN DE CONTEXTO
+
+### Cuando el Usuario Vuelve
+
+Si el usuario vuelve después de una pausa:
+
+1. **Leer estado**: `.elsabro/state.json`
+2. **Detectar flujo incompleto**: `current_flow !== null`
+3. **Ofrecer opciones**:
+   ```
+   Veo que estabas en medio de [comando] fase [fase].
+
+   ¿Qué quieres hacer?
+   1) Continuar donde lo dejaste
+   2) Empezar algo nuevo (esto descartará el progreso)
+   3) Ver resumen de lo que falta
+   ```
+
+### Resume Automático
+
+Si `current_flow.phase === "implementation"` y hay archivos modificados sin commit:
+
+```
+Detecté cambios sin guardar de tu última sesión:
+- src/auth.ts (modificado)
+- src/api/login.ts (nuevo)
+
+¿Quieres que continúe la implementación o prefieres revisar primero?
+```
+
+---
+
+## INTEGRACIÓN CON ENFORCEMENT RULES
+
+Cada punto de sincronización debe respetar las reglas de `/references/enforcement-rules.md`:
+
+1. **TaskCreate** antes de cada transición de comando
+2. **TaskUpdate(in_progress)** antes de ejecutar la lógica
+3. **Parallelism** cuando la transición involucra múltiples operaciones
+4. **TaskUpdate(completed)** y actualizar `state.json` al finalizar
+
+---
+
+## COMANDOS QUE MODIFICAN ESTADO
+
+| Comando | Lee Estado | Escribe Estado | Crea Artefactos |
+|---------|-----------|----------------|-----------------|
+| start | SÍ | SÍ | NO |
+| new | SÍ | SÍ | SÍ (.elsabro/, estructura) |
+| plan | SÍ | SÍ | SÍ (.planning/*.md) |
+| execute | SÍ | SÍ | SÍ (código, tests) |
+| verify-work | SÍ | SÍ | SÍ (reportes) |
+| debug | SÍ | SÍ | OPCIONAL |
+| quick | SÍ | SÍ | VARIABLE |
+| help | NO | NO | NO |
+| settings | SÍ | SÍ | NO |
+
+---
+
+## EJEMPLO COMPLETO: Flujo de Nueva Feature
+
+```
+Usuario: "Quiero agregar sistema de pagos"
+
+1. /elsabro:start
+   - Lee state.json → proyecto existente
+   - Detecta: brownfield
+   - Usuario elige: "Agregar algo"
+   - Actualiza state: { user_intent: "add_feature", next: "plan" }
+   - Redirige a /elsabro:plan
+
+2. /elsabro:plan
+   - Lee state.json → sabe que viene de start, es feature nueva
+   - TaskCreate("Explorar codebase para payments")
+   - Task(haiku) x3 [paralelo] → exploración
+   - TaskCreate("Generar plan de payments")
+   - Task(opus) x2 → genera plan
+   - Guarda .planning/payments-plan.md
+   - Actualiza state: { plan_file: "...", ready_for_execution: true }
+   - Usuario aprueba → sugiere /elsabro:execute
+
+3. /elsabro:execute
+   - Lee state.json → sabe el plan, los archivos
+   - TaskCreate("Implementar fase 1: setup Stripe")
+   - Task(haiku) x3 [paralelo] → exploración
+   - Task(opus) x2 [paralelo] → implementación
+   - Task(opus) x3 [paralelo] → verificación
+   - Actualiza state: { changed_files: [...], commits: [...] }
+   - Sugiere /elsabro:verify-work
+
+4. /elsabro:verify-work
+   - Lee state.json → sabe qué archivos verificar
+   - Task(opus) x3 [paralelo] → verificación exhaustiva
+   - Actualiza state: { verification: "passed" }
+   - DONE
+```
+
+---
+
+## ANTI-PATRONES
+
+### NO hacer:
+
+1. **Ignorar estado existente**
+   ```
+   ✗ Empezar fresh sin leer state.json
+   ✓ Siempre leer y ofrecer continuar si hay flujo
+   ```
+
+2. **Saltar comandos**
+   ```
+   ✗ start → execute (sin plan)
+   ✓ start → plan → execute
+   ```
+
+3. **No actualizar estado**
+   ```
+   ✗ Completar comando sin escribir state.json
+   ✓ Actualizar estado al inicio y fin de cada fase
+   ```
+
+4. **Perder contexto entre comandos**
+   ```
+   ✗ Cada comando empieza de cero
+   ✓ Pasar contexto relevante entre comandos
+   ```

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.