elsabro 4.0.0 → 4.2.0

package/README.md

@@ -1,10 +1,63 @@
-# ELSABRO v3.8
-
-**Tu asistente AI para crear apps increíbles** - Orquestación de agentes de nivel enterprise.
-
-ELSABRO es un sistema de desarrollo AI-powered para Claude Code que te guía paso a paso en la creación de aplicaciones, desde la idea inicial hasta el producto funcionando.
-
-## 🚀 Novedades v3.8 (Skill Marketplace Integration)
+# ELSABRO v4.2.0
+
+**Tu asistente AI para crear apps increibles** - Orquestacion de agentes de nivel enterprise.
+
+ELSABRO es un sistema de desarrollo AI-powered para Claude Code que te guia paso a paso en la creacion de aplicaciones, desde la idea inicial hasta el producto funcionando.
+
+## Novedades v4.2.0 (Next Step Suggestions + Stitch UI Design)
+
+### Next Step Suggestions
+- **Guided workflow**: Every command now suggests what to do next with "Siguiente Paso" blocks
+- **`suggested_next` in state.json**: Programmatic field for smart routing in persistent mode
+- **Context-aware**: Suggestions adapt based on pending tasks, TODOs, verification results
+- **28 commands enhanced**: All state-writing commands guide you to the next logical step
+- **New reference**: `references/next-step-engine.md` — Complete decision matrix and override rules
+
+### Stitch AI UI Design
+- **`/elsabro:design-ui`**: New command to generate professional UI screens from text descriptions
+- **Stitch MCP integration**: Create projects, generate screens, review and refine designs
+- **Sally enhanced**: UX Designer agent now uses both Stitch (full screens) and 21st.dev (components)
+- **Auto-documentation**: Designs saved to `.planning/ui-designs/` with screen specs
+- **Persistent mode routing**: Say "design", "mockup", "wireframe" and ELSABRO routes to design-ui
+
+## Novedades v4.1.0 (Persistent Mode + Code Review Enforcement)
+
+### Persistent Mode
+- **ELSABRO stays ON**: Once activated, all subsequent messages are automatically routed through ELSABRO workflows
+- **Intent classification**: Your messages are classified and routed to the right command (debug, plan, quick, etc.)
+- **`/elsabro:exit`**: Deactivate persistent mode when you want to return to normal Claude Code
+- **Zero overhead when inactive**: <5ms fast path when persistent mode is off
+- **Slash command bypass**: `/commit`, `/help`, etc. still work normally
+
+### Mandatory Code Review
+- **Rule 7 enforcement**: Code review is now mandatory after every code modification
+- **Integrated into commands**: `quick` and `debug` commands include automatic code review steps
+- **No escape hatches**: Cannot complete a code-writing command without running `pr-review-toolkit:code-reviewer`
+
+## Novedades v4.0.0 (Agent Teams + Blocking Review)
+
+### Agent Teams
+- **Coordinacion peer-to-peer** entre agentes usando Claude Code Agent Teams nativo
+- **Auto-routing** entre subagents y Agent Teams segun complejidad y perfil
+- **7 agentes migrados** a Team mode (orchestrator, executor, planner, analyst, qa, verifier, debugger)
+- **5 agentes mantienen** modo subagent (quick-dev, yolo-dev, scrum-master, tech-writer, ux-designer)
+- **Nuevo nodo `team`** en el flow engine para spawn y coordinacion de equipos
+- **Nuevo perfil `teams`** en hooks y flow engine
+
+### Blocking Code Review (Sin Escape)
+- **CERO opciones de skip** - no "aceptar con errores", no "continuar sin fix"
+- **5 iteraciones max** de fix antes de bloqueo (antes eran 2)
+- **3 reviewers paralelos** (code quality, silent failures, staff review)
+- **Quality gate completo** - tests + TypeScript + lint (antes faltaba lint)
+- **Exit codes reales** - `captureExitCode: true` en vez de `|| true`
+- **Nuevo nodo `interrupt_blocked`** para bloqueo duro en review failures
+
+### Nuevos Nodos de Flujo
+- `interrupt_blocked` - Bloqueo sin escape en review failures
+- `wait_manual_review_fix` - Espera fix manual del usuario
+- `interrupt_teams_failed` - Fallback de Agent Teams a subagents
+
+## Novedades v3.8 (Skill Marketplace Integration)
 
 ### Integración Automática de Skills (skills.sh)
 - **SkillDiscoveryEngine** - Descubrimiento automático de skills necesarias por keywords y categorías
@@ -278,6 +331,7 @@ Después de instalar, abre Claude Code y escribe:
 | `/elsabro:resume-work` | Retomar trabajo guardado |
 | `/elsabro:pause-work` | Pausar y guardar contexto |
 | `/elsabro:progress` | Ver progreso actual |
+| `/elsabro:exit` | Desactivar persistent mode |
 
 ### Todo Management
 | Comando | Descripción |

package/agents/elsabro-orchestrator.md

@@ -7,7 +7,8 @@ tools:
   - TaskUpdate
   - TaskList
   - TaskGet
-  - Teammate
+  - TeamCreate
+  - TeamDelete
   - SendMessage
   - Read
   - Glob
@@ -345,31 +346,32 @@ Archivos modificados:
 </integration_with_elsabro>
 
 <agent_teams>
-## Agent Teams Integration (v4.0.0)
+## Agent Teams Integration (v4.2.0 — Mandatory)
 
 ### Cuándo Usar Agent Teams
 
-Como orquestador, decido automáticamente cuándo usar Agent Teams vs Task subagents:
+Como orquestador, Agent Teams es **OBLIGATORIO** para todo trabajo paralelo con 2+ agentes (Rule 8):
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  DECISIÓN: ¿Agent Teams o Subagents?                        │
+│  AGENT TEAMS — OBLIGATORIO (v4.2.0)                         │
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
-│  Si profile == "teams":                                     │
-│    → AGENT TEAMS (siempre)                                  │
+│  agent_count < 2:                                           │
+│    → SUBAGENT (agente único, no necesita coordinación)      │
 │                                                             │
-│  Si complexity == "high" Y implementation:                  │
-│    → AGENT TEAMS (peer-to-peer coordination)                │
+│  phase == "exploration" (HAIKU read-only):                  │
+│    → SUBAGENTS (excepción: read-only, no modifica código)   │
 │                                                             │
-│  Si exploration o verification:                              │
-│    → SUBAGENTS (read-only, no necesita coordinación)        │
+│  agent_count >= 2 + ANY otra fase:                          │
+│    → AGENT TEAMS (OBLIGATORIO)                              │
+│    ├── implementación → TeamCreate + executor/qa teammates  │
+│    ├── review/verificación → TeamCreate + reviewer teammates│
+│    ├── planning (2+ opus) → TeamCreate + planner teammates  │
+│    └── debugging (2+ agents) → TeamCreate + debugger mates  │
 │                                                             │
-│  Si complexity == "low" o profile == "yolo":                │
-│    → SUBAGENTS (velocidad > coordinación)                   │
-│                                                             │
-│  Default:                                                   │
-│    → SUBAGENTS (menor overhead)                             │
+│  VIOLACIÓN CRÍTICA: 2+ agentes sin TeamCreate = ABORTAR    │
+│  Ver /references/enforcement-rules.md Regla 8              │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -377,9 +379,8 @@ Como orquestador, decido automáticamente cuándo usar Agent Teams vs Task subag
 ### Spawn Team Pattern
 
 ```javascript
-// 1. Crear equipo
-Teammate({
-  operation: "spawnTeam",
+// 1. Crear equipo (API oficial Claude Code)
+TeamCreate({
   team_name: "elsabro-wave-N",
   description: "Wave N implementation"
 })
@@ -402,14 +403,63 @@ Task({
   prompt: "Write tests for feature A..."
 })
 
-// 4. Teammates se comunican entre sí con SendMessage
+// 4. Teammates se comunican entre si con SendMessage
 // executor → qa: "Feature A implementada, estos son los archivos..."
 // qa → executor: "Test falla en edge case X, necesito fix..."
 
 // 5. Shutdown y cleanup
 SendMessage({ type: "shutdown_request", recipient: "executor" })
 SendMessage({ type: "shutdown_request", recipient: "qa" })
-Teammate({ operation: "cleanup" })
+TeamDelete()
+```
+
+### Limitations (de la documentacion oficial)
+
+- **No session resumption**: `/resume` no restaura teammates in-process
+- **No nested teams**: Teammates NO pueden crear sus propios teams
+- **Lead es fijo**: La sesion que crea el team es el lead para siempre
+- **Un team por sesion**: Limpiar el actual antes de crear uno nuevo
+- **Task status can lag**: Teammates a veces no marcan tasks como completed
+
+### Display Modes
+
+```javascript
+// In-process (default): todos en el mismo terminal
+// Shift+Up/Down para seleccionar teammate, Shift+Tab para delegate mode
+
+// Split panes: cada teammate en su propio panel (requiere tmux o iTerm2)
+// En settings.json:
+// { "teammateMode": "in-process" | "tmux" | "auto" }
+
+// CLI flag para forzar modo:
+// claude --teammate-mode in-process
+```
+
+### Plan Approval para Teammates
+
+```javascript
+// Para tareas complejas, requerir que teammates planifiquen antes de implementar
+// El teammate trabaja en plan mode hasta que el lead apruebe
+
+// Cuando teammate llama ExitPlanMode, envia plan_approval_request al lead
+// Lead responde con:
+SendMessage({
+  type: "plan_approval_response",
+  request_id: "abc-123",
+  recipient: "executor",
+  approve: true  // o false con content: "feedback..."
+})
+```
+
+### Delegate Mode
+
+```
+// Shift+Tab para activar delegate mode
+// En delegate mode, el lead SOLO puede coordinar:
+// - Spawn/shutdown teammates
+// - Enviar mensajes
+// - Gestionar tasks
+// NO puede editar archivos ni ejecutar codigo directamente
 ```
 
 ### Blocking Review con Agent Teams

package/agents/elsabro-ux-designer.md

@@ -8,6 +8,7 @@ tools:
   - WebSearch
   - mcp__plugin_context7_context7__*
   - mcp__magic__*
+  - mcp__stitch__*
 color: pink
 icon: "🎨"
 ---
@@ -97,6 +98,42 @@ Crear wireframes en ASCII/descripción.
 ```
 </workflows>
 
+<stitch_workflows>
+## Stitch AI Design Workflows
+
+### [ST] Stitch Design
+Generar screens visuales profesionales usando Stitch AI.
+
+```
+1. Entender requerimientos de UI
+2. Crear/reutilizar proyecto Stitch
+3. Generar screens desde texto
+4. Revisar con el usuario
+5. Refinar según feedback
+6. Documentar en .planning/ui-designs/
+```
+
+**Herramientas Stitch:**
+- `mcp__stitch__list_projects` — Ver proyectos existentes
+- `mcp__stitch__create_project` — Crear proyecto nuevo
+- `mcp__stitch__generate_screen_from_text` — Generar screen desde texto
+- `mcp__stitch__list_screens` — Listar screens de un proyecto
+- `mcp__stitch__get_screen` — Ver detalle de un screen
+- `mcp__stitch__get_project` — Ver detalle de un proyecto
+
+**Cuándo usar Stitch vs 21st.dev:**
+| Necesidad | Herramienta |
+|-----------|-------------|
+| Diseño visual completo de pantalla | **Stitch** |
+| Componente React individual | **21st.dev** |
+| Mockup rápido de una idea | **Stitch** |
+| Implementación de componente | **21st.dev** |
+| Flujo multi-pantalla | **Stitch** |
+| Botón/Card/Form específico | **21st.dev** |
+
+Output: `.planning/ui-designs/`
+</stitch_workflows>
+
 <ux_patterns>
 ## Patrones UX Comunes
 
@@ -276,3 +313,36 @@ User: "Necesito un card para mostrar productos"
 Sally: [usa 21st magic para encontrar/generar el componente]
 ```
 </integration_with_21st>
+
+<integration_with_stitch>
+## Integración con Stitch AI
+
+Cuando necesites diseñar pantallas completas, puedo usar Stitch AI para:
+
+1. Generar screens profesionales desde descripción de texto
+2. Crear flujos multi-pantalla completos
+3. Iterar diseños con feedback del usuario
+4. Documentar diseños para los developers
+
+### Flujo combinado Stitch + 21st.dev
+```
+1. Stitch: Generar screen completo (layout, estructura)
+2. 21st.dev: Generar componentes específicos (buttons, cards)
+3. Combinar: Screen de Stitch como guía + componentes de 21st.dev como código
+```
+
+### Ejemplo
+```
+User: "Necesito un dashboard con gráficos y filtros"
+Sally:
+  1. [Stitch] Genera screen completo del dashboard
+  2. [21st.dev] Genera componentes: FilterBar, StatCard, ChartContainer
+  3. Documenta todo en .planning/ui-designs/
+```
+
+### Comando Asociado
+El usuario puede invocar directamente:
+```
+/elsabro:design-ui "descripción de la pantalla"
+```
+</integration_with_stitch>

package/commands/elsabro/add-phase.md

@@ -16,10 +16,12 @@ sync:
 ### Al Iniciar
 - Leer `.elsabro/state.json`
 - Verificar contexto actual del milestone/phase
+- Activar persistent mode: `state.elsabro_mode = true`
 
 ### Al Completar
 - Registrar cambio en `history`
 - Actualizar `context` si corresponde
+- Establecer `state.suggested_next = "plan"`
 </state_sync>
 
 <command-name>add-phase</command-name>
@@ -129,3 +131,21 @@ Actualiza `PHASES.md` y `MILESTONE.md`:
 
 View phases: /elsabro:progress --phases
 ```
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al agregar la fase, establecer en state.json:
+```javascript
+state.suggested_next = "plan";
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Mostrar al usuario:
+```
+## Siguiente Paso
+
+→ /elsabro:plan [N] — planificar la nueva fase agregada
+→ /elsabro:progress — ver el estado actualizado del milestone
+```
+</siguiente_paso>

package/commands/elsabro/add-todo.md

@@ -12,6 +12,18 @@ allowed-tools:
 
 <command-name>add-todo</command-name>
 
+<state_sync>
+## SINCRONIZACIÓN DE ESTADO
+
+### Al Iniciar
+- Leer `.elsabro/state.json` (si existe)
+- Activar persistent mode: `state.elsabro_mode = true`
+
+### Al Completar
+- Registrar en `history`
+- Establecer `state.suggested_next = "check-todos"`
+</state_sync>
+
 ## Propósito
 
 Agregar tareas rápidas al todo list del proyecto usando **Claude Code Tasks API** como backend. Para items que no merecen ser una fase o story completa.
@@ -214,3 +226,21 @@ TaskCreate({ subject: "Update user docs", metadata: {...} })
 - Can be promoted to phase task with `/elsabro:add-phase`
 - Persists across sessions via Tasks API
 - Supports dependencies with `blocks/blockedBy`
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al completar, establecer en state.json:
+```javascript
+state.suggested_next = "check-todos";
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Mostrar al usuario:
+```
+## Siguiente Paso
+
+→ /elsabro:check-todos — ver la lista completa de TODOs
+→ /elsabro:quick — resolver este TODO ahora mismo
+```
+</siguiente_paso>

package/commands/elsabro/audit-milestone.md

@@ -17,11 +17,13 @@ sync:
 - Leer `.elsabro/state.json`
 - Verificar si hay flujo en progreso
 - Actualizar `current_flow.command` con este comando
+- Activar persistent mode: `state.elsabro_mode = true`
 
 ### Al Completar
 - Registrar en `history`
 - Actualizar `context` con informacion del milestone
 - Limpiar `current_flow`
+- Establecer `state.suggested_next = "plan-milestone-gaps"`
 </state_sync>
 
 <command-name>audit-milestone</command-name>
@@ -164,3 +166,21 @@ Genera `.planning/milestones/M001-xxx/AUDIT-2024-01-20.md`:
 - Puede ser parte de weekly review
 - Alimenta `/elsabro:progress`
 - Dispara alertas si status es crítico
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al completar la auditoría, establecer en state.json:
+```javascript
+state.suggested_next = "plan-milestone-gaps";
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Mostrar al usuario:
+```
+## Siguiente Paso
+
+→ /elsabro:plan-milestone-gaps — planificar cómo cerrar los gaps encontrados
+→ /elsabro:discuss-phase — discutir los hallazgos de la auditoría
+```
+</siguiente_paso>

package/commands/elsabro/check-todos.md

@@ -13,6 +13,17 @@ allowed-tools:
 
 <command-name>check-todos</command-name>
 
+<state_sync>
+## SINCRONIZACIÓN DE ESTADO
+
+### Al Iniciar
+- Leer `.elsabro/state.json` (si existe)
+- Activar persistent mode: `state.elsabro_mode = true`
+
+### Al Completar
+- Establecer `state.suggested_next = "quick"`
+</state_sync>
+
 ## Propósito
 
 Revisar, filtrar y gestionar los TODOs del proyecto usando **Claude Code Tasks API**. Vista completa de tareas pendientes con capacidad de gestión directa.
@@ -369,3 +380,21 @@ Output:
 - Soporta dependencias (`blocks/blockedBy`)
 - Visible en `/elsabro:progress`
 - Promovible a fase con `/elsabro:add-phase`
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al completar, establecer en state.json:
+```javascript
+state.suggested_next = "quick";
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Mostrar al usuario:
+```
+## Siguiente Paso
+
+→ /elsabro:quick — resolver un TODO rápidamente
+→ /elsabro:execute — trabajar en tareas más grandes
+```
+</siguiente_paso>

package/commands/elsabro/complete-milestone.md

@@ -17,11 +17,13 @@ sync:
 - Leer `.elsabro/state.json`
 - Verificar si hay flujo en progreso
 - Actualizar `current_flow.command` con este comando
+- Activar persistent mode: `state.elsabro_mode = true`
 
 ### Al Completar
 - Registrar en `history`
 - Actualizar `context` con informacion del milestone
 - Limpiar `current_flow`
+- Establecer `state.suggested_next = "new-milestone"`
 </state_sync>
 
 <command-name>complete-milestone</command-name>
@@ -155,3 +157,21 @@ Options:
 - Dispara notificación de milestone completado
 - Actualiza `/elsabro:progress` automáticamente
 - Linked con próximo milestone si existe
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al completar el milestone, establecer en state.json:
+```javascript
+state.suggested_next = "new-milestone";
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Mostrar al usuario:
+```
+## Siguiente Paso
+
+→ /elsabro:new-milestone — crear el siguiente milestone
+→ /elsabro:progress — ver el estado general del proyecto
+```
+</siguiente_paso>

package/commands/elsabro/debug.md

@@ -29,11 +29,13 @@ sync:
 - Leer `.elsabro/state.json`
 - Verificar si hay flujo en progreso
 - Actualizar `current_flow.command` con este comando
+- Activar persistent mode: `state.elsabro_mode = true`
 
 ### Al Completar
 - Registrar en `history`
 - Actualizar `context` con informacion relevante
 - Limpiar `current_flow`
+- Establecer `state.suggested_next = "verify-work"`
 </state_sync>
 
 <objective>
@@ -97,6 +99,14 @@ Task(elsabro-debugger):
   Modo: find_and_fix
 ```
 
+```javascript
+// MARCAR: código fue modificado (para code_review_gate)
+if (mode === "find_and_fix") {
+  state.current_flow.code_written = true;
+  Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+}
+```
+
 ## Paso 4: Seguimiento
 
 El debugger actualizará el archivo de sesión con:
@@ -105,7 +115,26 @@ El debugger actualizará el archivo de sesión con:
 - Fix implementado
 - Verificación realizada
 
-## Paso 5: Verificar con Usuario
+## Paso 5: Code Review (OBLIGATORIO)
+
+**REGLA:** Después de implementar cualquier fix, SIEMPRE ejecutar code review antes de reportar al usuario.
+
+```
+Task(pr-review-toolkit:code-reviewer):
+  Revisa los cambios del fix aplicado.
+  Busca bugs, code smells, seguridad.
+  Archivos modificados: [lista de archivos cambiados]
+```
+
+Si el review encuentra issues, corregir ANTES de reportar al usuario.
+
+```javascript
+// MARCAR: code review pasó (para code_review_gate en siguiente_paso)
+state.current_flow.code_review_passed = true;
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+## Paso 6: Verificar con Usuario
 
 Una vez el debugger reporta fix:
 
@@ -122,6 +151,29 @@ Para verificar:
 ```
 </process>
 
+<code_review_gate>
+## Code Review Gate (OBLIGATORIO - NO NEGOCIABLE)
+
+**ANTES de reportar resultado al usuario o ofrecer commit, VERIFICAR:**
+
+```
+¿Se implementó un fix (modo find_and_fix)?
+│
+├─ SÍ → ¿Se ejecutó code review (Paso 5)?
+│    │
+│    ├─ NO → EJECUTAR AHORA:
+│    │   Task(pr-review-toolkit:code-reviewer)
+│    │   Si issues > 0: fix y re-review
+│    │   Solo cuando issues == 0: continuar
+│    │
+│    └─ SÍ, issues == 0 → Continuar
+│
+└─ NO (solo find_root_cause_only) → Continuar (no aplica)
+```
+
+**VIOLACIÓN CRÍTICA**: Reportar fix sin code review = ABORTAR OPERACIÓN
+</code_review_gate>
+
 <modes>
 ## Modos de Debug
 
@@ -170,3 +222,26 @@ Opciones:
 ¿Qué prefieres?
 ```
 </escalation>
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al completar el debug, establecer en state.json:
+```javascript
+// GATE CHECK: No escribir suggested_next sin code review (aplica en modo find_and_fix)
+if (state.current_flow?.code_written && !state.current_flow?.code_review_passed) {
+  // VIOLACIÓN CRÍTICA — ABORTAR. Volver a code_review_gate.
+  throw new Error("CODE_REVIEW_GATE: Cannot proceed without code review");
+}
+state.suggested_next = "verify-work";
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Mostrar al usuario:
+```
+## Siguiente Paso
+
+→ /elsabro:verify-work — verificar que el fix funciona correctamente
+→ /elsabro:progress — ver el estado general del proyecto
+```
+</siguiente_paso>