elsabro 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elsabro",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Sistema de desarrollo AI-powered para Claude Code - El mejor asistente para crear apps sin experiencia previa",
   "bin": {
     "elsabro": "bin/install.js"

package/references/SYSTEM_INDEX.md

@@ -0,0 +1,241 @@
+# ELSABRO System Index
+
+## ARQUITECTURA DEL SISTEMA
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            ELSABRO SYSTEM                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌──────────────────────────────────────────────────────────────────────┐   │
+│  │                      ENTRY POINT                                      │   │
+│  │                    /elsabro:start                                     │   │
+│  │              (Orquestador Principal)                                  │   │
+│  └────────────────────────────┬─────────────────────────────────────────┘   │
+│                               │                                              │
+│                               ▼                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                    CORE WORKFLOW                                        │ │
+│  │  ┌─────────┐  ┌─────────┐  ┌─────────────┐  ┌───────────────┐         │ │
+│  │  │  :new   │→ │  :plan  │→ │  :execute   │→ │ :verify-work  │         │ │
+│  │  │ (setup) │  │(design) │  │(implement)  │  │   (check)     │         │ │
+│  │  └─────────┘  └─────────┘  └─────────────┘  └───────────────┘         │ │
+│  │                    ↑               │                                    │ │
+│  │                    └───── :debug ──┘                                    │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                    SHARED STATE                                         │ │
+│  │                 .elsabro/state.json                                     │ │
+│  │              (Sincronización entre comandos)                            │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                    TASK DISPATCHER                                      │ │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                     │ │
+│  │  │   HAIKU     │  │   SONNET    │  │    OPUS     │                     │ │
+│  │  │ Exploración │  │  Balance    │  │ Implementar │                     │ │
+│  │  │  (rápido)   │  │ (flexible)  │  │  (calidad)  │                     │ │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘                     │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ARCHIVOS DE REFERENCIA
+
+### 1. `enforcement-rules.md`
+**Propósito**: Reglas NO negociables que todo comando debe seguir
+**Contiene**:
+- Secuencia obligatoria: TaskCreate → TaskUpdate → Task → TaskUpdate
+- Mínimos de agentes por fase
+- Matriz completa de todos los comandos (29 comandos)
+- Políticas de paralelismo
+
+### 2. `state-sync.md`
+**Propósito**: Protocolo de sincronización de estado entre comandos
+**Contiene**:
+- Código de sincronización para copiar a cada comando
+- Fases por comando
+- Contexto que pasa cada comando al siguiente
+- Transiciones válidas entre comandos
+
+### 3. `command-flow.md`
+**Propósito**: Flujo de navegación y estado compartido
+**Contiene**:
+- Diagrama de flujo principal
+- Estructura de `.elsabro/state.json`
+- Checkpoints entre comandos
+- Recuperación de contexto
+
+### 4. `task-dispatcher.md`
+**Propósito**: Selección automática de modelo según tipo de tarea
+**Contiene**:
+- Matriz modelo-tipo de tarea
+- Configuración de agentes por comando
+- Políticas de ejecución paralela
+- Integración con Claude Code Tasks API
+
+### 4.1. `tasks-integration.md` (NUEVO)
+**Propósito**: Integración con Claude Code Tasks API como backend único
+**Contiene**:
+- Arquitectura unificada (ELSABRO commands + Tasks API)
+- Metadata schema para TODOs, phases, milestones
+- Migración de `.planning/TODOS.md` a Tasks API
+- Ejemplos de implementación para cada comando
+
+### 5. `error-handling-instructions.md`
+**Propósito**: Manejo consistente de errores
+**Contiene**:
+- Clasificación (CRITICAL, HIGH, MEDIUM, LOW)
+- Display visual de errores
+- Políticas de retry
+- Actualización de estado después de errores
+
+### 6. `source-hierarchy.md`
+**Propósito**: Prioridad de fuentes de información
+**Contiene**:
+- Context7 > Docs > WebSearch > Training
+- Verificación de versiones
+- Proceso de research
+
+### 7. `token-optimization.md`
+**Propósito**: Uso eficiente del contexto
+**Contiene**:
+- Regla del 50%
+- Lazy loading
+- Wave execution
+
+---
+
+## ESTADO UNIFICADO
+
+**Archivo principal**: `.elsabro/state.json`
+
+```json
+{
+  "version": "1.0.0",
+  "created_at": "ISO timestamp",
+  "updated_at": "ISO timestamp",
+
+  "current_flow": {
+    "command": "string",
+    "phase": "string",
+    "started_at": "ISO timestamp"
+  },
+
+  "context": {
+    "project_type": "greenfield | brownfield | continuation",
+    "tech_stack": ["array"],
+    "current_feature": "string | null"
+  },
+
+  "history": [
+    {
+      "command": "string",
+      "completed_at": "ISO timestamp",
+      "result": "string",
+      "artifact": "path | null"
+    }
+  ],
+
+  "pending_tasks": [],
+  "blocked_on": null,
+  "suggested_next": "string | null",
+
+  "errors": {
+    "count": 0,
+    "lastError": null
+  }
+}
+```
+
+**Archivo legible**: `.elsabro/context.md` (para humanos)
+
+---
+
+## SKILLS PROFESIONALES
+
+| Skill | Stack | Versiones |
+|-------|-------|-----------|
+| `full-stack-app` | Next.js 15 + React 19 + Prisma 6 + PostgreSQL | Específicas |
+| `saas-starter` | Full-stack + Stripe 2024-12-18 | Específicas |
+| `mobile-app` | Expo SDK 52 + React Native | Específicas |
+| `api-microservice` | Fastify + OpenAPI + Docker | Parciales |
+| `chrome-extension` | Manifest V3 + Vite + TypeScript | Parciales |
+
+---
+
+## CHECKLIST DE CONSISTENCIA
+
+Para verificar que el sistema está correctamente configurado:
+
+### Comandos Core
+- [ ] `start.md` tiene sección `<enforcement>` y `<state_sync>`
+- [ ] `plan.md` tiene sección `<state_sync>` y `dispatcher` en frontmatter
+- [ ] `execute.md` tiene sección `<state_sync>` y `dispatcher` en frontmatter
+- [ ] `verify-work.md` tiene sección `<state_sync>` y `dispatcher` en frontmatter
+
+### Referencias
+- [ ] Todos los archivos usan `.elsabro/state.json` (NO `.planning/SESSION.md`)
+- [ ] `enforcement-rules.md` tiene matriz para los 29 comandos
+- [ ] `state-sync.md` tiene código de sincronización completo
+
+### Skills
+- [ ] Cada skill tiene `tags` en frontmatter
+- [ ] Cada skill tiene versiones específicas de tecnologías
+- [ ] Cada skill tiene `<verification>` ejecutable
+
+---
+
+## FLUJO DE EJECUCIÓN TÍPICO
+
+```
+1. Usuario ejecuta /elsabro:start
+   └─ Lee .elsabro/state.json (si existe)
+   └─ Lanza 2 HAIKU en paralelo para detectar contexto
+   └─ Muestra opciones según proyecto (greenfield/brownfield/continuation)
+   └─ Actualiza state.json con current_flow
+   └─ Invoca siguiente comando con Skill tool
+
+2. /elsabro:plan toma control
+   └─ Lee state.json (contexto de start)
+   └─ Lanza 3 HAIKU en paralelo para explorar
+   └─ Lanza 1 OPUS para crear RESEARCH.md y PLAN.md
+   └─ Lanza 1 SONNET para validar plan
+   └─ Actualiza state.json (plan_file, ready_for_execution)
+   └─ Sugiere /elsabro:execute
+
+3. /elsabro:execute toma control
+   └─ Lee state.json (plan_file)
+   └─ Lanza 3 HAIKU en paralelo para explorar
+   └─ Lanza 2+ OPUS en paralelo para implementar (por wave)
+   └─ Lanza 3 OPUS en paralelo para verificar
+   └─ Actualiza state.json (changed_files, commits)
+   └─ Sugiere /elsabro:verify-work
+
+4. /elsabro:verify-work finaliza
+   └─ Lee state.json (changed_files)
+   └─ Lanza 3 OPUS en paralelo para verificación exhaustiva
+   └─ Genera VERIFICATION-REPORT.md
+   └─ Actualiza state.json (verification_result)
+   └─ Si PASS: "Listo para merge"
+   └─ Si FAIL: Sugiere /elsabro:execute para fix
+```
+
+---
+
+## REGLAS DE ORO
+
+1. **TaskCreate ANTES de cualquier acción**
+2. **TaskUpdate(in_progress) ANTES de Task()**
+3. **Tasks API como backend único** (NO duplicar con sistemas custom)
+4. **Metadata schema consistente** para type, priority, category
+5. **TaskList para sincronización** (NO archivos .md separados)
+6. **Mínimo 3 agentes HAIKU para exploración**
+7. **OPUS para implementación y verificación**
+8. **Context7 ANTES de escribir código con librerías**
+9. **Paralelismo OBLIGATORIO cuando las tareas son independientes**
+10. **Pasar contexto via Task metadata** al siguiente comando

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
+   ```