elsabro 4.0.0 → 4.2.0

package/commands/elsabro/verify-work.md

@@ -12,6 +12,9 @@ allowed-tools:
   - TaskUpdate
   - TaskList
   - TaskGet
+  - TeamCreate
+  - TeamDelete
+  - SendMessage
   - AskUserQuestion
 sync:
   reads: [".elsabro/state.json"]
@@ -24,6 +27,9 @@ dispatcher:
     model: opus
     parallel: true
     min_agents: 3
+    method: "agent-team"
+    blocking: true
+    max_review_iterations: 5
 ---
 
 # /elsabro:verify-work
@@ -50,6 +56,7 @@ TaskUpdate(id, status: "in_progress")
 const state = Read(".elsabro/state.json") || createInitialState();
 
 // 3. Verificar contexto de execute (archivos a verificar)
+state.context = state.context || {};
 if (state.context.changed_files && state.context.changed_files.length > 0) {
   console.log("Archivos a verificar:", state.context.changed_files);
   console.log("Commits a revisar:", state.context.commits);
@@ -60,6 +67,7 @@ if (state.context.changed_files && state.context.changed_files.length > 0) {
 
 // 4. Actualizar estado
 state.current_flow = { command: "verify-work", phase: "initializing", started_at: new Date().toISOString() };
+state.elsabro_mode = true;
 Write(".elsabro/state.json", JSON.stringify(state, null, 2));
 
 // 5. Completar task de inicialización
@@ -90,12 +98,13 @@ state.history.push({
 });
 
 // Actualizar contexto
+state.context = state.context || {};
 state.context.verification_result = verificationResult;
 state.context.ready_for_merge = verificationResult === "PASS";
 
 // Limpiar flujo y sugerir siguiente
 state.current_flow = null;
-state.suggested_next = verificationResult === "PASS" ? null : "execute"; // null = done
+state.suggested_next = verificationResult === "PASS" ? "plan" : "execute"; // plan = next phase
 
 Write(".elsabro/state.json", JSON.stringify(state, null, 2));
 
@@ -133,6 +142,26 @@ Además de los checks estándar, verificar contra:
 - `.planning/CLAUDE.md` - ¿Se respetaron las reglas del proyecto?
 </review_integration>
 
+<agent_teams_gate>
+## Agent Teams Gate (OBLIGATORIO)
+
+verify-work usa 3 agentes OPUS en paralelo → Agent Teams es OBLIGATORIO.
+
+```
+¿3 agentes de verificación necesarios?
+│
+└─ SÍ → TeamCreate("elsabro-verify")
+        Task(team_name: "elsabro-verify", name: "reviewer-1")
+        Task(team_name: "elsabro-verify", name: "reviewer-2")
+        Task(team_name: "elsabro-verify", name: "reviewer-3")
+        ... verificación ...
+        SendMessage(shutdown_request) x3
+        TeamDelete()
+```
+
+**VIOLACIÓN CRÍTICA**: Lanzar 3 verificadores sin Agent Teams = ABORTAR
+</agent_teams_gate>
+
 ## Propósito
 
 Verificar que el trabajo completado cumple con los requirements, pasa todos los tests, y está listo para merge/deploy.
@@ -322,27 +351,50 @@ TaskUpdate({ taskId: "functional-id", status: "in_progress" })
 TaskUpdate({ taskId: "quality-id", status: "in_progress" })
 TaskUpdate({ taskId: "security-id", status: "in_progress" })
 
-// 2. Lanzar 3 agentes OPUS EN UN SOLO MENSAJE (paralelo real)
+// 2. OBLIGATORIO: Crear Agent Team para verificación paralela (Rule 8)
+TeamCreate({
+  team_name: "elsabro-verify",
+  description: "Verification team for phase " + phaseNumber
+})
+
+// MARCAR: Agent Teams fue usado correctamente (para GATE CHECK en siguiente_paso)
+state.current_flow.parallel_agents_used = 3;
+state.current_flow.agent_teams_used = true;
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+
+// 3. Spawn 3 teammates OPUS EN PARALELO (un solo mensaje)
 Task({
   subagent_type: "pr-review-toolkit:code-reviewer",
-  model: "opus",  // ← OPUS para análisis profundo
+  model: "opus",
+  team_name: "elsabro-verify",
+  name: "reviewer-1",
   description: "Code review completo",
   prompt: "Revisa los cambios buscando bugs, code smells, mejores prácticas, seguridad..."
 }) |
 Task({
   subagent_type: "pr-review-toolkit:silent-failure-hunter",
-  model: "opus",  // ← OPUS para edge cases
+  model: "opus",
+  team_name: "elsabro-verify",
+  name: "reviewer-2",
   description: "Buscar errores ocultos",
   prompt: "Busca errores silenciosos, try/catch que ocultan errores, fallbacks problemáticos..."
 }) |
 Task({
   subagent_type: "pr-review-toolkit:pr-test-analyzer",
-  model: "opus",  // ← OPUS para análisis de tests
+  model: "opus",
+  team_name: "elsabro-verify",
+  name: "reviewer-3",
   description: "Analizar cobertura de tests",
   prompt: "Verifica que los tests cubren los cambios, busca casos críticos sin test..."
 })
 
-// 3. Al completar cada uno, marcar completed
+// 4. Al completar verificación, shutdown teammates y cleanup
+SendMessage({ type: "shutdown_request", recipient: "reviewer-1", content: "Verification complete" })
+SendMessage({ type: "shutdown_request", recipient: "reviewer-2", content: "Verification complete" })
+SendMessage({ type: "shutdown_request", recipient: "reviewer-3", content: "Verification complete" })
+TeamDelete()
+
+// 5. Al completar cada uno, marcar completed
 TaskUpdate({
   taskId: "functional-id",
   status: "completed",
@@ -434,8 +486,9 @@ Si cualquier verificador falla:
 ║  Opciones:                                       ║
 ║  [d] /elsabro:debug - Investigar fallos         ║
 ║  [f] Fix y re-verificar                          ║
-║  [s] Saltar verificación (no recomendado)       ║
 ║  [a] Abortar                                     ║
+║                                                  ║
+║  (NO hay opción "saltar" — v4.0.0 policy)       ║
 ╚══════════════════════════════════════════════════╝
 ```
 
@@ -555,3 +608,37 @@ TaskCreate({
 }
 ```
 </parallel_coordination>
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al completar, establecer en state.json:
+```javascript
+// GATE CHECK: No proceder sin Agent Teams para fases con 2+ agentes
+if (state.current_flow?.parallel_agents_used >= 2 && !state.current_flow?.agent_teams_used) {
+  throw new Error("AGENT_TEAMS_GATE: Cannot proceed without Agent Teams for 2+ agents");
+}
+if (verificationResult === "PASS") {
+  state.suggested_next = "plan";  // next phase
+} else {
+  state.suggested_next = "execute";  // re-execute to fix
+}
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Si PASS:
+```
+## Siguiente Paso
+
+→ /elsabro:plan [N+1] — planificar la siguiente fase
+→ /elsabro:progress — ver el estado general
+```
+
+Si FAIL/PARTIAL:
+```
+## Siguiente Paso
+
+→ /elsabro:execute — re-ejecutar para corregir los gaps
+→ /elsabro:debug — investigar problemas encontrados
+```
+</siguiente_paso>

package/commands/elsabro/verify.md

@@ -14,6 +14,18 @@ argument-hint: "[número de fase o 'manual']"
 
 # ELSABRO: Verify
 
+<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 = "progress"`
+</state_sync>
+
 <objective>
 Verificar que una fase o feature cumple con sus objetivos usando:
 - Tests automáticos
@@ -205,3 +217,21 @@ gaps:
 | medium | Documentar para después |
 | low | Opcional arreglar |
 </gap_handling>
+
+<siguiente_paso>
+## Siguiente Paso
+
+Al completar la verificación, establecer en state.json:
+```javascript
+state.suggested_next = "progress";
+Write(".elsabro/state.json", JSON.stringify(state, null, 2));
+```
+
+Mostrar al usuario:
+```
+## Siguiente Paso
+
+→ /elsabro:progress — ver el estado general del proyecto
+→ /elsabro:plan [N+1] — planificar la siguiente fase
+```
+</siguiente_paso>

package/hooks/elsabro-mode.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# ELSABRO Persistent Mode Hook - UserPromptSubmit
+# Runs on every user message. Fast path: 2 checks then exit 0.
+# When active: outputs routing instructions for Claude to classify intent.
+
+set -euo pipefail
+
+STATE_FILE=".elsabro/state.json"
+
+# ─── Dependency Check ─────────────────────────────────────────────────
+
+if ! command -v jq &>/dev/null; then
+  echo "[ELSABRO] 'jq' no instalado. Persistent mode requiere jq. Instalar: brew install jq (macOS) o apt install jq (Linux)" >&2
+  exit 0
+fi
+
+# ─── Consume stdin (required - hook protocol sends JSON on stdin) ─────
+
+INPUT_JSON=$(cat)
+
+# ─── Fast Path (< 5ms) ───────────────────────────────────────────────
+
+# 1. No state file? Not in ELSABRO → pass through
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+# 2. Check elsabro_mode (with validation for empty/corrupt files)
+ELSABRO_MODE=$(jq -r '.elsabro_mode // false' "$STATE_FILE" 2>/dev/null || echo "false")
+if [ -z "$ELSABRO_MODE" ]; then
+  echo "[ELSABRO] state.json existe pero no se pudo leer elsabro_mode. Archivo corrupto?" >&2
+  exit 0
+fi
+if [ "$ELSABRO_MODE" != "true" ]; then
+  exit 0
+fi
+
+# 3. Parse user message from stdin JSON (only when active - avoids jq on fast path)
+USER_MESSAGE=$(echo "$INPUT_JSON" | jq -r '.prompt // ""' 2>/dev/null || echo "")
+
+# 4. Slash command? Match /command or /command:sub pattern, not file paths like /api/users
+#    Slash commands: /commit, /elsabro:plan, /help (single token, no embedded /)
+#    NOT slash commands: /api/users is broken, /usr/bin/node
+if [[ "$USER_MESSAGE" =~ ^/[a-zA-Z][a-zA-Z0-9_:-]*($|[[:space:]]) ]]; then
+  exit 0
+fi
+
+# ─── Active Path: ELSABRO is ON ──────────────────────────────────────
+
+# Read session context for routing
+# Use single jq call to extract all fields at once (performance + atomic read)
+CONTEXT_JSON=$(jq -r '{
+  cmd: (.current_flow.command // "none"),
+  ptype: (.context.project_type // "unknown"),
+  stack: ((.context.tech_stack // []) | if type == "array" then join(", ") elif type == "string" then . else "" end)
+}' "$STATE_FILE" 2>/dev/null || echo '{"cmd":"none","ptype":"unknown","stack":""}')
+
+CURRENT_COMMAND=$(echo "$CONTEXT_JSON" | jq -r '.cmd // "none"' 2>/dev/null || echo "none")
+PROJECT_TYPE=$(echo "$CONTEXT_JSON" | jq -r '.ptype // "unknown"' 2>/dev/null || echo "unknown")
+TECH_STACK=$(echo "$CONTEXT_JSON" | jq -r '.stack // ""' 2>/dev/null || echo "")
+
+# Output routing instructions (quoted heredoc prevents shell expansion for security)
+cat <<'ROUTING_HEADER'
+ELSABRO PERSISTENT MODE ACTIVE
+
+You are in ELSABRO persistent mode. The user's message should be routed to the appropriate ELSABRO command based on intent classification.
+
+## Current Session
+ROUTING_HEADER
+# Variable lines use printf to avoid shell expansion attacks from state.json content
+printf -- '- Active command: %s\n' "$CURRENT_COMMAND"
+printf -- '- Project type: %s\n' "$PROJECT_TYPE"
+printf -- '- Tech stack: %s\n' "$TECH_STACK"
+cat <<'ROUTING_BODY'
+
+## Intent Routing Table
+
+Classify the user's message and invoke the matching ELSABRO skill using the Skill tool:
+
+| If the user wants to...                          | Invoke                                |
+|--------------------------------------------------|---------------------------------------|
+| Fix a bug, error, crash, or investigate a problem | Skill("elsabro:debug")               |
+| Create a new feature, add something, build        | Skill("elsabro:plan")                |
+| Understand, explain, or explore the codebase       | Skill("elsabro:map-codebase")        |
+| Make a quick/small/simple change                   | Skill("elsabro:quick")               |
+| Refactor, improve, or clean up code               | Skill("elsabro:plan")                |
+| Verify, test, check, or validate work              | Skill("elsabro:verify-work")         |
+| Resume, continue, or pick up where they left off   | Skill("elsabro:resume-work")         |
+| Design UI, create mockup, wireframe, or screen     | Skill("elsabro:design-ui")           |
+| Exit, leave, stop, or deactivate ELSABRO           | Skill("elsabro:exit")                |
+| See progress, status, or what's next               | Skill("elsabro:progress")            |
+| Pause work or take a break                         | Skill("elsabro:pause-work")          |
+
+## Rules
+
+1. ALWAYS route through a Skill() call - never answer directly without invoking the appropriate ELSABRO command
+2. If the intent is ambiguous, ask the user to clarify with 2-3 options
+3. If the user is clearly having a casual conversation (greeting, thanks, etc.), respond naturally but remind them ELSABRO mode is active
+4. Pass the user's original message as the argument to the skill when relevant
+ROUTING_BODY
+
+exit 0

package/hooks/hooks-config-updated.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "description": "ELSABRO Hooks Configuration v3.1 - Agent Teams + Blocking Review + Skill Discovery (npx skills)",
-  "version": "3.1.0",
+  "description": "ELSABRO Hooks Configuration v3.2 (hook config version) for ELSABRO v4.0.0 - Agent Teams + Blocking Review + Skill Discovery + Persistent Mode",
+  "version": "3.2.0",
 
   "hooks": {
     "PreFlow": [
@@ -14,10 +14,8 @@
         "command": "bash ./hooks/skill-discovery.sh \"{{inputs.task}}\" \"{{inputs.complexity}}\"",
         "timeout": 30000,
         "enabled": true,
-        "output": {
-          "type": "json",
-          "inject_into": ["state.discoveredSkills", "state.skillContext"]
-        },
+        "outputFormat": "json",
+        "outputNote": "stdout JSON is consumed by flow engine to populate state.discoveredSkills and state.skillContext",
         "errorPolicy": "continue",
         "cacheable": true,
         "cache_ttl": 3600
@@ -58,6 +56,23 @@
       }
     ],
 
+    "UserPromptSubmit": [
+      {
+        "id": "elsabro-persistent-mode",
+        "name": "elsabro-persistent-mode",
+        "description": "Ruteo automático de mensajes a comandos ELSABRO cuando persistent mode está activo",
+        "command": "bash \"$CLAUDE_PROJECT_DIR\"/hooks/elsabro-mode.sh",
+        "timeout": 5000,
+        "enabled": true,
+        "errorPolicy": "continue",
+        "errorPolicyRationale": "Hook debe fallar silenciosamente para no bloquear input del usuario. Errores se reportan via stderr.",
+        "fastPath": {
+          "description": "< 5ms cuando inactivo: no state.json, elsabro_mode=false, o mensaje empieza con /",
+          "checks": ["state_file_exists", "elsabro_mode_true", "not_slash_command"]
+        }
+      }
+    ],
+
     "Notification": [
       {
         "id": "task-complete-notify",
@@ -112,11 +127,32 @@
     },
 
     "teams": {
-      "description": "Perfil para Agent Teams - coordinación peer-to-peer con Teammate/SendMessage",
+      "description": "Perfil para Agent Teams - coordinacion peer-to-peer con TeamCreate/TeamDelete/SendMessage",
+      "auto-test-on-edit": true,
+      "lint-on-save": true,
+      "confirm-destructive": true,
+      "skill-discovery": true,
+      "agent-teams": true,
+      "blocking-review": true,
+      "max-review-iterations": 5
+    },
+
+    "persistent-mode": {
+      "description": "Perfil con persistent mode habilitado - ELSABRO siempre activo, ruteo automático de mensajes",
+      "auto-test-on-edit": true,
+      "lint-on-save": true,
+      "confirm-destructive": true,
+      "skill-discovery": true,
+      "elsabro-persistent-mode": true
+    },
+
+    "persistent-teams": {
+      "description": "Perfil completo - persistent mode + Agent Teams + blocking review",
       "auto-test-on-edit": true,
       "lint-on-save": true,
       "confirm-destructive": true,
       "skill-discovery": true,
+      "elsabro-persistent-mode": true,
       "agent-teams": true,
       "blocking-review": true,
       "max-review-iterations": 5

package/hooks/skill-discovery.sh

@@ -13,6 +13,10 @@
 # 3. npx skills find <query> (vercel-labs/skills registry)
 #
 # Requiere: bash 4+, jq, node/npm (para npx)
+#
+# NOTA: Este script NO es safe para ejecución paralela del mismo archivo.
+# Si se ejecuta concurrentemente, las escrituras a CACHE_FILE pueden colisionar.
+# El flow engine debe serializar llamadas a este script.
 
 set -euo pipefail
 
@@ -53,8 +57,12 @@ log_error()   { echo -e "${RED}${PREFIX}${NC} ✗ $1" >&2; }
 # ============================================================================
 
 ensure_dirs() {
-    mkdir -p "$CACHE_DIR" 2>/dev/null || true
-    mkdir -p "$GLOBAL_SKILLS_DIR" 2>/dev/null || true
+    if ! mkdir -p "$CACHE_DIR" 2>/dev/null; then
+        log_warn "Could not create cache directory: $CACHE_DIR"
+    fi
+    if ! mkdir -p "$GLOBAL_SKILLS_DIR" 2>/dev/null; then
+        log_warn "Could not create skills directory: $GLOBAL_SKILLS_DIR"
+    fi
 }
 
 has_command() {
@@ -80,7 +88,13 @@ is_cache_valid() {
 
 get_from_cache() {
     local cache_key="$1"
-    jq --arg key "$cache_key" '.[$key].data' "$CACHE_FILE" 2>/dev/null
+    local data
+    data=$(jq --arg key "$cache_key" '.[$key].data' "$CACHE_FILE" 2>/dev/null)
+    # Guard against null/empty data from corrupt cache
+    if [ -z "$data" ] || [ "$data" = "null" ]; then
+        return 1
+    fi
+    echo "$data"
 }
 
 save_to_cache() {
@@ -89,6 +103,9 @@ save_to_cache() {
     ensure_dirs
     local now
     now=$(date +%s)
+    # NOTE: PID-unique tmp file mitigates but doesn't eliminate the read-modify-write
+    # race condition on concurrent writes. This is acceptable because skill discovery
+    # runs sequentially in the flow engine. Worst case: one cache entry is lost.
     local tmp_file="${CACHE_FILE}.tmp.$$"
     if [ -f "$CACHE_FILE" ] && jq empty "$CACHE_FILE" 2>/dev/null; then
         jq --arg key "$cache_key" --argjson data "$data" --argjson ts "$now" \
@@ -208,7 +225,7 @@ scan_elsabro_skills() {
 
         # Extraer metadata básica
         local description=""
-        description=$(sed -n '/^description:/s/^description: *//p' "$skill_file" | head -1 | sed 's/"/\\"/g')
+        description=$(sed -n '/^description:/s/^description: *//p' "$skill_file" | head -1)
         description="${description:0:100}"
 
         local tags=""
@@ -319,6 +336,7 @@ check_skill_updates() {
 
     local check_output=""
     check_output=$(timeout "$NPX_TIMEOUT" npx -y skills check 2>/dev/null) || {
+        log_warn "npx skills check failed or timed out"
         echo "[]"
         return
     }
@@ -341,7 +359,11 @@ check_skill_updates() {
         local name
         name=$(echo "$line" | grep -oE '[a-z][a-z0-9_-]+' | head -1)
         [ -z "$name" ] && continue
-        updates+=("{\"id\":\"$name\",\"update_available\":true,\"update_cmd\":\"npx skills update $name\"}")
+        # Use jq for safe JSON construction (avoids injection from special chars)
+        local update_obj
+        update_obj=$(jq -n --arg id "$name" --arg cmd "npx skills update $name" \
+            '{id: $id, update_available: true, update_cmd: $cmd}')
+        updates+=("$update_obj")
     done <<< "$check_output"
 
     if [ ${#updates[@]} -eq 0 ]; then
@@ -484,6 +506,12 @@ main() {
     local task="${1:-}"
     local complexity="${2:-medium}"
 
+    # Check required dependencies
+    if ! has_command jq; then
+        echo '{"status":"error","message":"jq is required but not installed. Install with: brew install jq (macOS) or apt-get install jq (Linux)","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
+        exit 1
+    fi
+
     # Validate complexity
     case "$complexity" in
         low|medium|high) ;;
@@ -506,7 +534,7 @@ main() {
 
     # --- Fase 2: Cache check ---
     local cache_key
-    cache_key=$(echo -n "${task}|${complexity}" | md5 2>/dev/null || echo -n "${task}|${complexity}" | md5sum 2>/dev/null | awk '{print $1}' || echo "nocache")
+    cache_key=$(echo -n "${task}|${complexity}" | md5 2>/dev/null || echo -n "${task}|${complexity}" | md5sum 2>/dev/null | awk '{print $1}' || echo -n "${task}|${complexity}" | cksum | awk '{print $1}')
 
     if is_cache_valid "$cache_key"; then
         log_success "Cache hit"
@@ -550,8 +578,10 @@ main() {
     local output
     output=$(generate_output "$keywords" "$installed" "$elsabro" "$external" "$recommended" "$updates")
 
-    # Guardar en cache
-    save_to_cache "$cache_key" "$output" 2>/dev/null || true
+    # Guardar en cache (log warning on failure, don't mask exit code)
+    if ! save_to_cache "$cache_key" "$output"; then
+        log_warn "Failed to save results to cache"
+    fi
 
     # Output final a STDOUT (esto captura el Flow Engine)
     echo "$output"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elsabro",
-  "version": "4.0.0",
-  "description": "Sistema de desarrollo AI-powered para Claude Code - Agent Teams, blocking code review, orquestación avanzada con checkpointing, memoria multi-nivel y flows declarativos",
+  "version": "4.2.0",
+  "description": "Sistema de desarrollo AI-powered para Claude Code - Next Step Suggestions, Stitch UI Design, Agent Teams, blocking code review, orquestación avanzada con checkpointing, memoria multi-nivel y flows declarativos",
   "bin": {
     "elsabro": "bin/install.js"
   },
@@ -32,11 +32,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/goat1990/elsabro.git"
+    "url": "git+https://github.com/goat1990/elsabro-gsd.git"
   },
-  "homepage": "https://github.com/goat1990/elsabro",
+  "homepage": "https://github.com/goat1990/elsabro-gsd",
   "bugs": {
-    "url": "https://github.com/goat1990/elsabro/issues"
+    "url": "https://github.com/goat1990/elsabro-gsd/issues"
   },
   "engines": {
     "node": ">=18.0.0"

package/references/SYSTEM_INDEX.md

@@ -425,6 +425,15 @@
 - API endpoint: `https://add-skill.vercel.sh/check-updates`
 - Comandos: /elsabro:skills search|install|update|list|config
 
+### 41. `next-step-engine.md` (v4.2)
+**Propósito**: Decision matrix para sugerencias de siguiente paso
+**Contiene**:
+- Decision Matrix (28 commands mapped to suggested_next)
+- Contextual overrides (blocked tasks, TODOs, verification results)
+- Output template for "Siguiente Paso" blocks
+- Fallback rule (progress as safe default)
+- Integration with persistent mode routing
+
 ---
 
 ## ESTADO UNIFICADO