@saulwade/swl-ses 1.9.0 → 2.0.0

package/habilidades/ejecutar-fase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ejecutar-fase
-description: Ejecuta el PLAN.md de una fase con commits atómicos por tarea. Aplica reglas de desviación, maneja checkpoints HITL, soporta TDD opcional, y mantiene ESTADO.md y HOJA-RUTA.md actualizados tras cada tarea completada.
-version: "1.1.0"
+description: Ejecuta el PLAN.md de una fase con commits atómicos por tarea. Aplica reglas de desviación, maneja checkpoints HITL, ejecuta TDD por default con evidencia RED en telemetría (opt-out declarado), y mantiene ESTADO.md y HOJA-RUTA.md actualizados tras cada tarea completada.
+version: "1.2.0"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar si no existe PLAN.md con `estado: aprobado` — ejecutar `planear-fase` primero."
@@ -31,7 +31,7 @@ antipatrón de acumular cambios sin verificar y commitear "todo de golpe".
 
 ## Cuándo NO cargar
 
-- No hay PLAN.md o el plan tiene `estado: propuesto` (no aprobado) — ejecutar `planear-fase` y obtener aprobación primero.
+- No hay PLAN.md o el plan no tiene `estado: aprobado` — ejecutar `planear-fase` y aprobar con `/swl:aprobar-plan N` (firma el lock G1) antes de ejecutar.
 - El objetivo es solo verificar calidad del trabajo ya implementado; usar `verificar-trabajo`.
 - Hay un checkpoint `decision` o `human-action` sin resolver en ESTADO.md — resolver el checkpoint antes de continuar la ejecución.
 - Se quiere ejecutar solo una sub-tarea fuera de la secuencia de oleadas del plan; hacerlo rompe el grafo de dependencias y el estado en ESTADO.md.
@@ -41,6 +41,26 @@ antipatrón de acumular cambios sin verificar y commitear "todo de golpe".
 Leer `.planning/fases/0N-PLAN.md` y `.planning/ESTADO.md` (si existe) antes de
 ejecutar la primera tarea.
 
+### Gate G1 — integridad del plan firmado
+
+Antes de la primera tarea Y al inicio de cada slice, verificar que el PLAN no
+fue mutado tras su aprobación:
+
+```bash
+node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
+```
+
+- `modo: "firmado"` → continuar.
+- `modo: "legacy"` (plan aprobado sin lock, cláusula de gracia D-05 para planes
+  pre-Fase09) → advertencia visible al usuario y continuar sin verificación de
+  integridad. Para activar el gate: `/swl:aprobar-plan N`.
+- `modo: "mutado"` → DETENER. El plan cambió tras la firma; reportar
+  `hashEsperado`/`hashActual` y remitir a `/swl:aprobar-plan N`.
+- cualquier otro `ok: false` → DETENER y reportar el `motivo`.
+
+La firma se escribe en `.planning/locks/0N-PLAN.md.lock` (versionado en git).
+La única vía válida de aprobar+firmar es `/swl:aprobar-plan`.
+
 ---
 
 ## Protocolo de ejecución por tarea
@@ -146,11 +166,16 @@ Reglas:
 - Detalle adicional si es necesario
 - Referencia a la tarea del plan
 
-Co-Authored-By: SWL Agent <noreply@swl.dev>
+Refs: REQ-NN[, REQ-MM]
 ```
 
 Tipos de commit válidos: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`, `migration`
 
+El footer `Refs: REQ-NN` cierra la cadena de trazabilidad REQ→T→commit (G4):
+lleva los REQ que la tarea declara en su campo `**Verifica REQ**` del PLAN.
+Omitirlo solo en fases legacy sin REQ-IDs. SIN co-autores ni atribuciones a IA
+(regla global `git-coauthor.md` — el único autor es el usuario).
+
 ---
 
 ## Modo Pipeline: acumulación de resultados entre tareas
@@ -267,23 +292,44 @@ B) [opción B]
 
 ---
 
-## TDD opcional (activar si el CONTEXTO.md lo requiere)
+## TDD por default con evidencia RED (gate G2 — opt-out declarado)
+
+TDD es **default ON** desde la Fase 10 (vNext H2). Solo se omite cuando el
+CONTEXTO.md declara `**TDD**: off — razón: [...]` (excepción registrada en
+AUDITORIA.md por `discutir-fase`). Sin esa declaración, toda tarea de código
+sigue el ciclo con evidencia.
 
-Cuando el CONTEXTO.md indica que la fase requiere TDD:
+### Ciclo RED → GREEN → REFACTOR por tarea (con telemetría)
 
-### Ciclo RED → GREEN → REFACTOR por tarea
+Al iniciar la primera tarea de código de la fase, abrir la corrida de evidencia:
+
+```bash
+node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'tdd',direccion:'lower_is_better',config:{fase:'0N',tarea:'T-NN'}});console.log(r.dir)"
+```
 
 **RED**: Escribir el test que describe el comportamiento esperado.
 El test DEBE fallar. Verificar que falla por la razón correcta, no por error
-de sintaxis o configuración.
+de sintaxis o configuración. **Registrar la evidencia** (métrica = tests fallando,
+descripción = fallo exacto):
+
+```bash
+node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:0,metrica:<N_fallan>,delta:0,estado:'baseline',descripcion:'RED T-NN: <fallo exacto del runner>'})"
+```
 
 **GREEN**: Escribir la implementación mínima que hace pasar el test.
-"Mínima" significa: no implementar más de lo que el test exige. Resistir la
-tentación de añadir casos no cubiertos por tests.
+"Mínima" significa: no implementar más de lo que el test exige. Registrar:
+
+```bash
+node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:1,metrica:0,delta:-<N>,estado:'keep',descripcion:'GREEN T-NN: suite verde'})"
+```
 
 **REFACTOR**: Limpiar el código sin cambiar el comportamiento.
 El test DEBE seguir pasando después del refactor. Hacer commit solo en este paso.
 
+La fila RED en `.planning/loops/tdd-*/iteraciones.tsv` es la evidencia que
+`hooks/tdd-gate.js` busca al commitear (warn-only, ADR-0035) — cierra F-TDD-6
+("el RED no deja evidencia"). Sin registro, el gate emite nudge `tdd-red-evidence`.
+
 ### Cobertura mínima en modo TDD
 
 - Toda función pública tiene al menos 1 test de camino feliz
@@ -344,10 +390,10 @@ Actualizar ESTADO.md después de cada tarea (no al final de la oleada):
 - Pendientes: N-M-K
 
 ## Estado por tarea
-| ID   | Nombre | Estado | Commit | Notas |
-|------|--------|--------|--------|-------|
-| T-01 | [nombre] | COMPLETADA | abc1234 | |
-| T-02 | [nombre] | COMPLETADA | def5678 | |
+| ID   | Nombre | Estado | Commit | REQ | Notas |
+|------|--------|--------|--------|-----|-------|
+| T-01 | [nombre] | COMPLETADA | abc1234 | REQ-01 | |
+| T-02 | [nombre] | COMPLETADA | def5678 | REQ-01, REQ-02 | |
 | T-03 | [nombre] | EN_PROGRESO | — | |
 | T-04 | [nombre] | PENDIENTE | — | depende T-03 |
 | T-05 | [nombre] | BLOQUEADA | — | [descripción del bloqueo] |
@@ -466,3 +512,7 @@ NO proceder con el deploy hasta aprobar este gate.
 - [ ] Decisiones HITL registradas con respuesta del usuario
 - [ ] Tests pasan en el estado final del código
 - [ ] No hay `console.log`, `print()` de debug ni pendientes sin ticket en el código nuevo
+- [ ] `.planning/locks/fase-activa.json` eliminado (libera el gate G0 — el `.lock`
+      del plan NO se toca: es evidencia versionada)
+- [ ] `/swl:verificar --until-converge` invocado automáticamente (gate G4) — o
+      desviación `--sin-verify` registrada en RESUMEN.md con razón

package/habilidades/estructura-proyecto-claude/SKILL.md

@@ -6,9 +6,9 @@ description: >
   Cargar al inicializar proyecto nuevo, migrar proyecto existente al sistema SWL,
   auditar estructura Claude-ready, agregar extensiones (commands, skills, agents,
   hooks, plugins), o configurar MCP. Cubre arquitectura de 4 capas, jerarquía
-  de memoria, 6 tipos de extensión, 27 hook events, frontmatter de skills/agents/commands
+  de memoria, 6 tipos de extensión, 30 hook events, frontmatter de skills/agents/commands
   y settings avanzados.
-version: "1.0.0"
+version: "1.1.0"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar para iniciar un proyecto desde cero — ese flujo usa `/swl:nuevo-proyecto` que incluye entrevista de contexto antes de generar la estructura; este skill genera estructura pero no recoge requisitos de negocio."
@@ -53,7 +53,7 @@ mi_proyecto/
 |   +-- plugins/                           # Plugins distribuibles
 +-- .planning/                             # Estado de planificación SWL
 |   +-- PROYECTO.md, REQUISITOS.md, HOJA-RUTA.md, ESTADO.md
-|   +-- research/
+|   +-- fases/, adrs/, research/
 +-- .mcp.json                              # Configuracion de servidores MCP
 ```
 
@@ -74,17 +74,19 @@ mi_proyecto/
 
 | Scope | Path | Aplica a |
 |-------|------|----------|
-| **Managed Policy** | Sistema | Todos los usuarios org |
+| **Managed Policy** | Sistema (ej. Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`) | Todos los usuarios org |
 | **User** | `~/.claude/CLAUDE.md` | Todos tus proyectos |
-| **Project** | `./CLAUDE.md` | Proyecto (repo) |
+| **Project** | `./CLAUDE.md` o `./.claude/CLAUDE.md` | Proyecto (repo) |
+| **Local** | `./CLAUDE.local.md` (en `.gitignore`) | Solo tú, este proyecto |
 | **Subdirectory** | `packages/frontend/CLAUDE.md` | Paquete del monorepo |
 
 ### Comportamiento de carga
 
-- **Ancestor (ARRIBA)**: al inicio, carga TODOS los CLAUDE.md desde cwd hasta la raíz del sistema de archivos — siempre se cargan
-- **Descendant (ABAJO)**: lazy — solo carga cuando Claude navega a un subdirectorio
+- **Ancestor (ARRIBA)**: al inicio, carga TODOS los CLAUDE.md y CLAUDE.local.md desde cwd hasta la raíz del sistema de archivos — siempre se cargan, concatenados (raíz primero, cwd al final)
+- **Descendant (ABAJO)**: lazy — solo carga cuando Claude lee archivos en ese subdirectorio
 - **Siblings**: NUNCA se cargan entre sí
-- Solo las **primeras 200 líneas** de cada CLAUDE.md se inyectan al prompt del sistema
+- Cada CLAUDE.md se carga **completo** sin importar su longitud — el límite de 200 líneas es recomendación de adherencia, no truncado. (El truncado de 200 líneas / 25KB aplica al `MEMORY.md` de auto memory, no a CLAUDE.md.)
+- **Auto memory** (complementario): Claude escribe notas propias en `~/.claude/projects/<proyecto>/memory/` — activado por defecto, gestionable con `/memory` o `autoMemoryEnabled`
 
 **Reglas clave**: Menos de 200 líneas por CLAUDE.md. Subdirectorios agregan, NUNCA sobreescriben.
 
@@ -94,8 +96,8 @@ mi_proyecto/
 
 | Tipo | Activación | Ubicación |
 |------|-----------|-----------|
-| **Skills** | Auto-activación | `.claude/skills/` |
-| **Commands** | Manual (`/comando`) | `.claude/commands/` |
+| **Skills** | Auto-activación o `/nombre` | `.claude/skills/` |
+| **Commands** | Manual (`/comando`) — fusionados con skills, mismo frontmatter | `.claude/commands/` |
 | **Subagents** | Spawn por orquestador | `.claude/agents/` |
 | **Hooks** | Event-driven | `settings.json` hooks |
 | **MCP Servers** | Siempre disponibles | `.mcp.json` |
@@ -116,7 +118,7 @@ mi_proyecto/
 ```yaml
 ---
 name: nombre-skill              # kebab-case, max 64 chars
-description: >                  # max 1024 chars — QUÉ + CUÁNDO
+description: >                  # QUÉ + CUÁNDO (description + when_to_use truncados a 1,536 chars combinados)
   Describe qué hace y cuándo Claude debe auto-activarla.
 allowed-tools: ["Read", "Grep", "Glob"]
 paths:
@@ -129,7 +131,7 @@ Ver referencia completa en [recursos/frontmatter-y-hooks-referencia.md](recursos
 
 ---
 
-## Hook Events (14 críticos de 27 oficiales)
+## Hook Events (7 críticos de 30 oficiales)
 
 | Evento | Cuándo se dispara | Uso típico |
 |--------|-------------------|-----------|
@@ -141,8 +143,9 @@ Ver referencia completa en [recursos/frontmatter-y-hooks-referencia.md](recursos
 | **PostCompact** | Después de compactar | Re-inyectar contexto |
 | **Notification** | Claude espera input | Alertas desktop |
 
-Los 20 eventos restantes, frontmatter de agents (16 campos) y commands (13 campos),
-opciones avanzadas de hooks y orden de resolución en
+Los 23 eventos restantes, frontmatter de agents (16 campos) y de skills/commands
+(unificados — los commands se fusionaron con skills), opciones avanzadas de hooks
+y orden de resolución en
 [recursos/frontmatter-y-hooks-referencia.md](recursos/frontmatter-y-hooks-referencia.md).
 
 ---

package/habilidades/estructura-proyecto-claude/recursos/configuracion-y-extensiones.md

@@ -28,41 +28,42 @@ completos de settings.json, .mcp.json, plugins y checklists detallados.
     "PreToolUse": [
       {
         "matcher": "Bash",
-        "type": "command",
-        "command": "node .claude/hooks/lint-check.js"
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/lint-check.js" }
+        ]
       }
     ],
     "PostToolUse": [
       {
         "matcher": "Write",
-        "type": "command",
-        "command": "node .claude/hooks/format-on-save.js"
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/format-on-save.js" }
+        ]
       }
     ],
     "SessionStart": [
       {
         "matcher": "startup",
-        "type": "command",
-        "command": "node .claude/hooks/load-context.js"
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/load-context.js" }
+        ]
       }
     ]
-  },
-  "context": {
-    "rules": [
-      "CLAUDE.md"
-    ]
   }
 }
 ```
 
 ### Jerarquía de settings (mayor a menor prioridad)
 
-1. **Managed** (MDM plist / Registry / Server-managed / `managed-settings.d/`)
+1. **Managed** (MDM plist / Registry / Server-managed / `managed-settings.json`)
 2. **CLI arguments** (solo sesión actual)
 3. **`.claude/settings.local.json`** (personal, git-ignored)
 4. **`.claude/settings.json`** (equipo, commiteado)
 5. **`~/.claude/settings.json`** (global personal)
 
+**Excepción**: los `permissions` (allow/deny) se **fusionan** entre scopes, no se
+sobreescriben por precedencia simple.
+
 ---
 
 ## Settings avanzados y variables de entorno
@@ -90,13 +91,20 @@ Settings poco documentados pero de alto impacto:
 
 | Flag | Efecto |
 |------|--------|
-| `--bare` | Arranque hasta 10x más rápido — omite carga de CLAUDE.md y skills. Útil para scripts |
-| `--add-dir <path>` | Agregar directorio adicional a la sesión — sesiones multi-repo sin copiar archivos |
-| `-w` / `--worktree` | Git worktree aislado — cada sesión en su propia rama |
-| `--agent=<nombre>` | Usar agente custom como agente principal de la sesión |
-| `--effort high` | Nivel de esfuerzo alto para todas las respuestas |
-| `/sandbox` | Reduce 84% los diálogos de permisos — sandbox seguro para exploración |
-```
+| `--bare` | Modo mínimo: omite auto-discovery de hooks, skills, plugins, MCP servers, auto memory y CLAUDE.md — arranque más rápido para scripts |
+| `--add-dir <path>` | Agregar directorio adicional a la sesión — sesiones multi-repo sin copiar archivos. Los CLAUDE.md de esos directorios NO se cargan por defecto (`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` para cargarlos) |
+| `-w` / `--worktree` | Git worktree aislado en `<repo>/.claude/worktrees/<nombre>` |
+| `--agent <nombre>` | Usar agente custom como agente principal de la sesión |
+| `--effort <nivel>` | Nivel de esfuerzo de la sesión: `low`, `medium`, `high`, `xhigh`, `max` |
+| `--max-budget-usd <n>` | Tope de gasto en API antes de detenerse (solo print mode) |
+
+### Comando `/sandbox` (Bash sandbox)
+
+Abre el panel del sandbox de Bash: aislamiento de filesystem y red **a nivel de SO**
+(Seatbelt en macOS, bubblewrap en Linux/WSL2 — no soportado en Windows nativo). En modo
+auto-allow, los comandos sandboxeados corren sin diálogos de permiso; los que requieren
+acceso fuera del boundary caen al flujo regular de permisos. Configuración persistente
+vía `sandbox.enabled` y `sandbox.filesystem.*` en settings.json.
 
 ---
 
@@ -110,18 +118,21 @@ Settings poco documentados pero de alto impacto:
       "args": ["-y", "@upstash/context7-mcp@latest"]
     },
     "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" }
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/"
     },
     "playwright": {
       "command": "npx",
-      "args": ["-y", "@anthropic/mcp-playwright"]
+      "args": ["-y", "@playwright/mcp@latest"]
     }
   }
 }
 ```
 
+> El GitHub MCP server oficial es remoto (`api.githubcopilot.com/mcp/`) — el paquete
+> npm `@modelcontextprotocol/server-github` fue archivado. El de Playwright oficial
+> es `@playwright/mcp` (Microsoft).
+
 Ver catalogo completo en [mcp-json-template.json](mcp-json-template.json).
 
 ---

package/habilidades/estructura-proyecto-claude/recursos/frontmatter-y-hooks-referencia.md

@@ -4,19 +4,23 @@ Fuente: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overvi
 
 ---
 
-## Frontmatter completo de SKILL.md (12 campos)
+## Frontmatter completo de SKILL.md (16 campos — aplica también a commands, que se fusionaron con skills)
 
 | Campo | Requerido | Tipo | Descripción |
 |-------|-----------|------|-------------|
-| `name` | No* | string | Nombre kebab-case, max 64 chars. Se convierte en `/nombre` para invocación. *Si se omite, usa el nombre del directorio |
-| `description` | Recomendado | string | Max 1024 chars. QUÉ hace + CUÁNDO usar. Guía la auto-activación de Claude |
+| `name` | No* | string | Nombre mostrado en listados. *Si se omite, usa el nombre del directorio |
+| `description` | Recomendado | string | QUÉ hace + CUÁNDO usar. Guía la auto-activación. `description` + `when_to_use` se truncan a 1,536 chars combinados en el listado |
+| `when_to_use` | Opcional | string | Contexto adicional de activación (frases trigger, ejemplos). Se anexa a `description` y cuenta para el tope de 1,536 chars |
 | `argument-hint` | Opcional | string | Hint de autocompletado: `[archivo]`, `[issue-num]`, `[file] [format]` |
-| `allowed-tools` | Opcional | array | Tools que Claude puede usar sin pedir permiso cuando la skill está activa |
+| `arguments` | Opcional | array/string | Argumentos posicionales con nombre para sustitución `$nombre` en el contenido |
+| `allowed-tools` | Opcional | array/string | Tools que Claude puede usar sin pedir permiso cuando la skill está activa |
+| `disallowed-tools` | Opcional | array/string | Tools removidas del pool de Claude mientras la skill está activa |
 | `paths` | Opcional | array/string | Patrones glob: cargar skill SOLO al trabajar con archivos que coinciden |
 | `context` | Opcional | string | `fork` = ejecutar en subagente aislado con su propia conversación |
 | `agent` | Opcional | string | Tipo de subagente si `context: fork` (Explore, Plan, general-purpose) |
-| `model` | Opcional | string | Override de modelo para esta skill |
-| `effort` | Opcional | string | Nivel de esfuerzo: `low`, `medium`, `high`, `max` (Opus only) |
+| `model` | Opcional | string | Override de modelo mientras la skill está activa (mismos valores que `/model`, o `inherit`) |
+| `effort` | Opcional | string | Nivel de esfuerzo: `low`, `medium`, `high`, `xhigh`, `max` (los niveles disponibles dependen del modelo) |
+| `hooks` | Opcional | object | Hooks acotados al ciclo de vida de esta skill |
 | `shell` | Opcional | string | `bash` o `powershell`. Controla bloques `!comando` embebidos |
 | `disable-model-invocation` | Opcional | boolean | `true` = solo el usuario puede invocar (no auto-trigger). Usar para skills con side-effects como `/deploy` |
 | `user-invocable` | Opcional | boolean | `false` = solo Claude la ve (conocimiento de background). No aparece en menú `/` |
@@ -46,21 +50,24 @@ user-invocable: true
 
 | Variable | Valor |
 |----------|-------|
-| `$ARGUMENTS` | Argumentos pasados al invocar la skill |
-| `$0`, `$1`, `$2`... | Argumentos posicionales |
+| `$ARGUMENTS` | Todos los argumentos pasados al invocar la skill (si no aparece, se anexan como `ARGUMENTS: <valor>`) |
+| `$ARGUMENTS[N]` | Argumento específico por índice 0-based |
+| `$0`, `$1`, `$2`... | Shorthand de `$ARGUMENTS[N]` |
+| `$nombre` | Argumento con nombre declarado en `arguments:` del frontmatter |
 | `${CLAUDE_SESSION_ID}` | ID unico de la sesion actual |
+| `${CLAUDE_EFFORT}` | Nivel de esfuerzo activo (`low`...`max`) |
 | `${CLAUDE_SKILL_DIR}` | Path absoluto al directorio de la skill |
-| `${env:VAR_NAME}` | Variable de entorno del sistema |
 
 ---
 
-## 25 Hook Events oficiales
+## 30 Hook Events oficiales
 
 ### Ciclo de vida de sesión
 
 | Evento | Cuándo se dispara | Matchers | Uso típico |
 |--------|-------------------|----------|-----------|
 | `SessionStart` | Al iniciar o resumir sesión | `startup`, `resume`, `clear`, `compact` | Cargar contexto, setup env |
+| `Setup` | Inicialización one-time (`--init-only`, `--maintenance`) | `init`, `maintenance` | Bootstrap de repo, mantenimiento |
 | `SessionEnd` | Al terminar sesión | `clear`, `resume`, `logout`, `other` | Cleanup, archivado |
 | `InstructionsLoaded` | CLAUDE.md o rules/ cargados | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` | Log que instrucciones se cargaron |
 
@@ -71,7 +78,9 @@ user-invocable: true
 | `PreToolUse` | Antes de ejecutar herramienta | Nombre de tool (Bash, Edit, Read, mcp__*) | Bloquear ops inseguras, validar |
 | `PostToolUse` | Después de ejecutar herramienta (éxito) | Nombre de tool | Auto-lint, format, log |
 | `PostToolUseFailure` | Cuando falla herramienta | Nombre de tool | Notificar, reintentar |
+| `PostToolBatch` | Al resolver un batch completo de tool calls paralelos | Ninguno | Métricas de batch |
 | `PermissionRequest` | Se muestra diálogo de permiso | Nombre de tool | Auto-aprobar acciones seguras |
+| `PermissionDenied` | El clasificador de auto mode niega un tool call | Nombre de tool | Log, escalar |
 
 ### Respuesta y control
 
@@ -80,6 +89,8 @@ user-invocable: true
 | `Stop` | Claude termina de responder | Ninguno (siempre se dispara) | Verificar tarea completa |
 | `StopFailure` | Error de API en Stop | `rate_limit`, `authentication_failed`, `billing_error`, `server_error` | Notificar fallos |
 | `UserPromptSubmit` | Usuario envía prompt | Ninguno | Interceptar/enriquecer input |
+| `UserPromptExpansion` | Un comando del usuario se expande a prompt | Ninguno | Transformar input |
+| `MessageDisplay` | Mientras se muestra texto del asistente | Ninguno | Modificar texto en pantalla |
 
 ### Compactación de contexto
 
@@ -135,44 +146,40 @@ user-invocable: true
 
 ## Frontmatter completo de agents (.claude/agents/*.md) — 16 campos
 
-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| `name` | string | Nombre kebab-case del agente |
-| `description` | string | Cuándo invocarlo — usar `"PROACTIVELY"` para invocación eager |
-| `model` | string | Override de modelo (`sonnet`, `haiku`, `opus`) |
-| `color` | string | Color del agente en terminal (green, blue, red, etc.) |
-| `maxTurns` | number | Máximo de turnos antes de terminar |
-| `permissionMode` | string | `acceptEdits`, `dontAsk`, `plan`, `default` |
-| `memory` | string | `project`, `user`, `local`, `none` |
-| `skills` | array | Skills precargados como conocimiento de background |
-| `isolation` | string | `worktree` = rama git aislada por ejecución |
-| `allowed-tools` | array | Herramientas permitidas sin pedir permiso |
-| `hooks` | object | Hooks específicos del agente (SubagentStop, PreToolUse, etc.) |
-| `stop` | string | Instrucción de cuándo detenerse |
-| `shell` | string | `bash` o `powershell` |
-| `effort` | string | `low`, `medium`, `high`, `max` |
-| `disable-model-invocation` | boolean | Solo invocación manual |
-| `user-invocable` | boolean | Visible en menú o solo invocable por Claude |
-
-**Gotcha**: El evento `Stop` en frontmatter de agente se dispara como `SubagentStop`, no como `Stop`.
+| Campo | Requerido | Tipo | Descripción |
+|-------|-----------|------|-------------|
+| `name` | Sí | string | Identificador único en minúsculas con guiones. Los hooks lo reciben como `agent_type` |
+| `description` | Sí | string | Cuándo Claude debe delegar a este subagente |
+| `tools` | No | array | Tools que el subagente puede usar. Hereda todas si se omite. Para precargar skills usar `skills`, no listar `Skill` aquí |
+| `disallowedTools` | No | array | Tools negadas — se remueven de la lista heredada o especificada |
+| `model` | No | string | `sonnet`, `opus`, `haiku`, `fable`, un model ID completo, o `inherit` (default) |
+| `permissionMode` | No | string | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` |
+| `maxTurns` | No | number | Máximo de turnos agénticos antes de detenerse |
+| `skills` | No | array | Skills precargadas al contexto al inicio (se inyecta el contenido completo) |
+| `mcpServers` | No | array/object | MCP servers disponibles para este subagente (nombre de server ya configurado o definición inline) |
+| `hooks` | No | object | Hooks acotados al ciclo de vida del subagente (`Stop` se convierte en `SubagentStop` en runtime) |
+| `memory` | No | string | Memoria persistente cross-sesión: `user`, `project`, `local` |
+| `background` | No | boolean | `true` = siempre corre como background task |
+| `effort` | No | string | `low`, `medium`, `high`, `xhigh`, `max` — override del nivel de sesión |
+| `isolation` | No | string | `worktree` = git worktree temporal aislado (auto-limpiado si no hay cambios) |
+| `color` | No | string | Color en task list/transcript: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` |
+| `initialPrompt` | No | string | Primer turno auto-enviado cuando el agente corre como agente principal (`--agent`) |
+
+**Gotcha**: El evento `Stop` declarado en `hooks:` de un agente se dispara como `SubagentStop`, no como `Stop`.
 
 ---
 
-## Frontmatter de commands (.claude/commands/*.md) — 13 campos
+## Frontmatter de commands (.claude/commands/*.md)
 
-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| `name` | string | Se convierte en `/nombre` (o subcarpeta: `/dir:nombre`) |
-| `description` | string | Descripción mostrada en autocompletado |
-| `argument-hint` | string | Hint visual: `[archivo]`, `[issue-num]` |
-| `allowed-tools` | array | Tools permitidos sin pedir permiso |
-| `model` | string | Override de modelo |
-| `effort` | string | Nivel de esfuerzo |
-| `shell` | string | `bash` o `powershell` |
-| `user-invocable` | boolean | Default `true` — commands siempre son user-invocable |
-| `disable-model-invocation` | boolean | `true` = Claude no puede auto-invocar |
+**Los commands se fusionaron con las skills**: un archivo en `.claude/commands/deploy.md`
+y una skill en `.claude/skills/deploy/SKILL.md` crean ambos `/deploy` y funcionan igual.
+Los archivos existentes en `.claude/commands/` siguen funcionando y aceptan el **mismo
+frontmatter de 16 campos de SKILL.md** (ver tabla arriba).
 
-**Diferencia clave**: commands NUNCA se auto-invocan — siempre requieren `/nombre` del usuario.
+Las skills agregan sobre los commands legacy: directorio de archivos de apoyo,
+control de invocación (`disable-model-invocation`, `user-invocable`) y auto-activación
+por relevancia. Para forzar que un comando NUNCA se auto-invoque (comportamiento
+del command clásico), declarar `disable-model-invocation: true`.
 
 ---
 
@@ -195,6 +202,7 @@ porque se ejecuta inline sin el overhead de un subagente.
 | `prompt` | Claude decide qué hacer | `"prompt": "Verifica que el archivo..."` |
 | `agent` | Claude con herramientas propias | `"agent": "Analiza y corrige..."` |
 | `http` | POST a endpoint HTTP | `"url": "https://webhook.example.com/hook"` |
+| `mcp_tool` | Llama una tool de un MCP server configurado | `"server": "slack", "tool": "send_message"` |
 
 ### Códigos de retorno para hooks command
 
@@ -209,22 +217,31 @@ porque se ejecuta inline sin el overhead de un subagente.
 | Opción | Tipo | Descripción |
 |--------|------|-------------|
 | `async` | boolean | Ejecutar en background sin bloquear — fire-and-forget |
-| `timeout` | number | Timeout en ms (default varía por evento) |
-| `once` | boolean | Ejecutar solo la primera vez que el evento ocurre |
-| `asyncRewake` | boolean | Re-despertar al agente cuando el hook async termina |
-| `statusMessage` | string | Mensaje mostrado mientras el hook ejecuta |
-| `if` | string | Condicional (v2.1.85+) — solo ejecutar si la condición se cumple |
+| `timeout` | number | Timeout en **segundos** (defaults: 600 command/http/mcp_tool, 30 prompt, 60 agent) |
+| `once` | boolean | Ejecutar una sola vez por sesión y removerse (solo en hooks de frontmatter de skill) |
+| `asyncRewake` | boolean | Background + re-despertar a Claude si el hook sale con exit code 2 (implica `async`) |
+| `statusMessage` | string | Mensaje del spinner mientras el hook ejecuta |
+| `if` | string | Filtro con sintaxis de regla de permisos: `"Bash(git *)"`, `"Edit(*.ts)"` |
 
 ### Campos JSON de retorno del hook
 
+Campos universales (nivel superior):
+
+| Campo | Tipo | Efecto |
+|-------|------|--------|
+| `continue` | boolean | `false` = detener el procesamiento por completo |
+| `stopReason` | string | Mensaje mostrado cuando `continue: false` |
+| `suppressOutput` | boolean | Ocultar el stdout del hook del transcript |
+| `systemMessage` | string | Mensaje de advertencia mostrado al usuario |
+
+Campos dentro de `hookSpecificOutput` (con `hookEventName` obligatorio):
+
 | Campo | Tipo | Efecto |
 |-------|------|--------|
-| `continue` | boolean | `false` = detener la cadena de hooks |
-| `stopReason` | string | Razón de detención (si `continue: false`) |
-| `suppressOutput` | boolean | No mostrar output del hook al usuario |
-| `systemMessage` | string | Inyectar mensaje al contexto del sistema |
 | `additionalContext` | string | Agregar contexto adicional a la conversación |
-| `updatedInput` | object | Solo PreToolUse — modificar el input de la herramienta antes de ejecución |
+| `updatedInput` | object | Reescribir el input de la herramienta (PreToolUse, PostToolUse) |
+| `updatedToolOutput` | object | Reescribir el output de la herramienta (PostToolUse) |
+| `permissionDecision` | string | Solo PreToolUse: `allow`, `deny`, `ask`, `defer` |
 
 ---