@saulwade/swl-ses 1.0.0

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

@@ -0,0 +1,289 @@
+# Referencia Completa: Frontmatter de Skills y Hook Events
+
+Fuente: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+
+---
+
+## Frontmatter completo de SKILL.md (12 campos)
+
+| 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 |
+| `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 |
+| `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) |
+| `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ú `/` |
+
+### Ejemplo completo
+
+```yaml
+---
+name: api-test-generator
+description: >
+  Genera tests de integracion para endpoints REST. Auto-activar cuando el usuario
+  crea o modifica un endpoint en src/api/. Produce tests con httpx y pytest que
+  cubren happy path, validacion de input, auth y error handling.
+argument-hint: "[endpoint-path]"
+allowed-tools: ["Read", "Grep", "Glob", "Write"]
+paths:
+  - "src/api/**/*.py"
+  - "tests/integration/**/*.py"
+model: claude-sonnet-4-6
+effort: high
+disable-model-invocation: false
+user-invocable: true
+---
+```
+
+### Sustituciones de string disponibles
+
+| Variable | Valor |
+|----------|-------|
+| `$ARGUMENTS` | Argumentos pasados al invocar la skill |
+| `$0`, `$1`, `$2`... | Argumentos posicionales |
+| `${CLAUDE_SESSION_ID}` | ID unico de la sesion actual |
+| `${CLAUDE_SKILL_DIR}` | Path absoluto al directorio de la skill |
+| `${env:VAR_NAME}` | Variable de entorno del sistema |
+
+---
+
+## 25 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 |
+| `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 |
+
+### Ejecución de herramientas
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `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 |
+| `PermissionRequest` | Se muestra diálogo de permiso | Nombre de tool | Auto-aprobar acciones seguras |
+
+### Respuesta y control
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `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 |
+
+### Compactación de contexto
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `PreCompact` | Antes de compactar | `manual`, `auto` | Salvar estado crítico |
+| `PostCompact` | Después de compactar | `manual`, `auto` | Re-inyectar contexto |
+
+### Subagentes
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `SubagentStart` | Al spawnar subagente | `Explore`, `Plan`, `general-purpose`, nombres custom | Log creación |
+| `SubagentStop` | Al terminar subagente | Mismos que SubagentStart | Cleanup worktrees |
+| `TeammateIdle` | Miembro de equipo idle | Ninguno | Keep alive, escalar |
+
+### Tasks
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `TaskCreated` | Al crear tarea | Ninguno | Log, validar tasks |
+| `TaskCompleted` | Al completar tarea | Ninguno | Notificar, log |
+
+### Configuración y archivos
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `ConfigChange` | Cambio en settings | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | Auditar, bloquear no autorizado |
+| `CwdChanged` | Cambio de directorio de trabajo | Ninguno | Recargar direnv, actualizar env |
+| `FileChanged` | Archivo observado cambia | Patrón de nombre (`.envrc`, `.env`) | Recargar config, re-lint |
+
+### Git worktrees
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `WorktreeCreate` | Git worktree creado | Ninguno | Setup custom |
+| `WorktreeRemove` | Git worktree removido | Ninguno | Cleanup recursos |
+
+### MCP
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `Elicitation` | Servidor MCP pide input | Nombre del servidor MCP | Gate user input |
+| `ElicitationResult` | Usuario responde a MCP | Nombre del servidor MCP | Validar/transformar respuesta |
+
+### Notificaciones
+
+| Evento | Cuándo se dispara | Matchers | Uso típico |
+|--------|-------------------|----------|-----------|
+| `Notification` | Claude espera input | `permission_prompt`, `idle_prompt`, `auth_success` | Alertas desktop, sonidos |
+
+---
+
+## 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`.
+
+---
+
+## Frontmatter de commands (.claude/commands/*.md) — 13 campos
+
+| 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 |
+
+**Diferencia clave**: commands NUNCA se auto-invocan — siempre requieren `/nombre` del usuario.
+
+---
+
+## Orden de resolución (cuando múltiples coinciden)
+
+```
+Skill (inline, preferido) > Agent (contexto separado) > Command (nunca auto-invocado)
+```
+
+Si un skill y un agent tienen descripciones similares, Claude prefiere el skill
+porque se ejecuta inline sin el overhead de un subagente.
+
+---
+
+## Tipos de handler para hooks
+
+| Tipo | Descripción | Ejemplo |
+|------|-------------|---------|
+| `command` | Ejecuta comando shell | `"command": "node .claude/hooks/lint.js"` |
+| `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"` |
+
+### Códigos de retorno para hooks command
+
+| Código | Significado |
+|--------|-------------|
+| `0` | Permitir (allow) |
+| `2` | Bloquear (block) — la operación no se ejecuta |
+| Otro | Error — Claude decide qué hacer |
+
+### Opciones avanzadas de hooks
+
+| 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 |
+
+### Campos JSON de retorno del hook
+
+| 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 |
+
+---
+
+## Patrones de permisos en settings.json
+
+### Patrones comunes de allow
+
+```json
+"allow": [
+  "Bash(git:*)",
+  "Bash(npm:*)",
+  "Bash(python:*)",
+  "Bash(uv:*)",
+  "Bash(pytest:*)",
+  "Read(**/src/**)",
+  "Write(**/src/**)",
+  "Read(**/tests/**)",
+  "Write(**/tests/**)"
+]
+```
+
+### Patrones comunes de deny
+
+```json
+"deny": [
+  "Bash(rm -rf:*)",
+  "Bash(curl * | bash:*)",
+  "Bash(sudo:*)",
+  "Read(**/env:*)",
+  "Read(**/.env*)",
+  "Write(**/node_modules/**)"
+]
+```
+
+---
+
+## Estructura de plugin.json
+
+```json
+{
+  "name": "mi-plugin",
+  "version": "1.0.0",
+  "description": "Descripción del plugin",
+  "author": "Tu nombre",
+  "skills": ["skills/mi-skill"],
+  "agents": ["agents/mi-agent.md"],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "node hooks/validate.js"
+      }
+    ]
+  },
+  "mcpServers": {
+    "mi-server": {
+      "command": "node",
+      "args": ["mcp-servers/server.js"]
+    }
+  }
+}
+```

package/habilidades/estructura-proyecto-claude/recursos/mcp-json-template.json

@@ -0,0 +1,77 @@
+{
+  "_comentario": "Template de .mcp.json para proyectos Claude-ready. Eliminar los servidores que no se usen. Las variables de entorno con valor vacío deben completarse en .env o exportarse antes de correr claude.",
+  "_instrucciones": [
+    "1. Copiar este archivo a la raíz del proyecto como .mcp.json",
+    "2. Eliminar el bloque _comentario y _instrucciones (no son JSON válido en producción)",
+    "3. Configurar las variables de entorno requeridas por cada servidor activo",
+    "4. Agregar .mcp.json al repositorio (no contiene secretos — los secretos van en env vars)",
+    "5. Agregar a .gitignore cualquier archivo .mcp.local.json con credenciales"
+  ],
+  "mcpServers": {
+    "context7": {
+      "_descripcion": "Documentación actualizada de librerías. Uso: 'use context7' en el prompt.",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "github": {
+      "_descripcion": "Acceso a GitHub: issues, PRs, repos, commits. Requiere token con permisos repo.",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+      }
+    },
+    "filesystem": {
+      "_descripcion": "Acceso a sistema de archivos fuera del directorio de trabajo. Usar con cuidado.",
+      "_activar": "Descomentar solo si se necesita acceso a paths fuera del proyecto",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/ruta/al/directorio/permitido"
+      ]
+    },
+    "postgres": {
+      "_descripcion": "Acceso de solo lectura a PostgreSQL. Útil para explorar esquemas y datos.",
+      "_activar": "Descomentar si el proyecto usa PostgreSQL y se requiere introspección de BD",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "POSTGRES_CONNECTION_STRING": "postgresql://usuario:password@localhost:5432/nombre_bd"
+      }
+    },
+    "sqlite": {
+      "_descripcion": "Acceso a base de datos SQLite. Alternativa ligera a postgres para proyectos pequeños.",
+      "_activar": "Descomentar si el proyecto usa SQLite",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data.db"]
+    },
+    "brave-search": {
+      "_descripcion": "Búsqueda web con Brave Search API. Útil para investigación técnica durante desarrollo.",
+      "_activar": "Requiere API key de Brave Search (plan gratuito disponible)",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": ""
+      }
+    },
+    "memory": {
+      "_descripcion": "Memoria persistente entre sesiones. Almacena entidades y relaciones en grafo.",
+      "_activar": "Útil para proyectos largos donde se quiere persistir contexto entre sesiones",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"]
+    },
+    "puppeteer": {
+      "_descripcion": "Control de navegador. Útil para testing E2E, scraping o automatización web.",
+      "_activar": "Requiere Chrome/Chromium instalado",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    },
+    "sequential-thinking": {
+      "_descripcion": "Herramienta de razonamiento estructurado para problemas complejos.",
+      "_activar": "Útil para arquitectura, debugging complejo, decisiones de diseño",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}

package/habilidades/estructura-proyecto-claude/recursos/variantes-por-stack.md

@@ -0,0 +1,177 @@
+# Variantes de estructura por stack tecnológico
+
+Referencia completa de estructura de proyecto Claude-ready para cada stack.
+Todos los stacks incluyen la estructura base `.claude/`, `.planning/` y `.mcp.json`.
+
+---
+
+## Python backend (FastAPI / Django)
+
+```
+proyecto/
+├── CLAUDE.md
+├── .claude/               # Ver estructura base en SKILL.md
+├── .planning/             # Ver estructura base en SKILL.md
+├── .mcp.json
+├── pyproject.toml         # Dependencias y metadata del paquete
+├── .env.example           # Variables de entorno (sin valores reales)
+├── alembic/               # Migraciones de base de datos
+│   ├── alembic.ini
+│   ├── env.py
+│   └── versions/
+├── app/
+│   ├── main.py
+│   ├── routers/
+│   ├── models/
+│   ├── schemas/
+│   ├── services/
+│   ├── dependencies/
+│   └── core/
+│       ├── config.py
+│       └── security.py
+└── tests/
+    ├── conftest.py
+    ├── unit/
+    └── integration/
+```
+
+**Qué agregar en CLAUDE.md para proyectos Python**:
+- Versión de Python y gestor de paquetes (`uv` o `pip`)
+- Comando para activar entorno virtual
+- Comandos de migración Alembic
+- Comando para correr tests con cobertura (`pytest --cov`)
+
+---
+
+## Node.js backend (Express / Fastify / NestJS)
+
+```
+proyecto/
+├── CLAUDE.md
+├── .claude/
+├── .planning/
+├── .mcp.json
+├── package.json
+├── tsconfig.json
+├── .env.example
+├── src/
+│   ├── index.ts           # Entry point
+│   ├── routes/
+│   ├── controllers/
+│   ├── services/
+│   ├── models/
+│   └── middleware/
+├── prisma/                # Si usa Prisma ORM
+│   └── schema.prisma
+└── tests/
+    ├── unit/
+    └── integration/
+```
+
+**Qué agregar en CLAUDE.md para proyectos Node**:
+- Versión de Node.js y gestor de paquetes (`npm`, `pnpm`, `yarn`)
+- Comando de dev con hot-reload
+- Comando de build de producción
+
+---
+
+## Angular frontend
+
+```
+proyecto/
+├── CLAUDE.md
+├── .claude/
+├── .planning/
+├── .mcp.json
+├── angular.json
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── app/
+    │   ├── core/          # Servicios singleton, guards, interceptors
+    │   ├── shared/        # Componentes, pipes, directivas compartidas
+    │   ├── features/      # Módulos de features (lazy loaded)
+    │   └── app.config.ts
+    ├── assets/
+    └── environments/
+```
+
+**Qué agregar en CLAUDE.md para proyectos Angular**:
+- Versión de Angular y Node
+- Convención de signals vs RxJS
+- Estructura de features (feature-based o type-based)
+
+---
+
+## React / Next.js frontend
+
+```
+proyecto/
+├── CLAUDE.md
+├── .claude/
+├── .planning/
+├── .mcp.json
+├── next.config.js         # Si usa Next.js
+├── package.json
+├── tsconfig.json
+├── tailwind.config.ts     # Si usa Tailwind CSS
+├── app/                   # App Router (Next.js 13+)
+│   ├── layout.tsx
+│   ├── page.tsx
+│   └── [rutas de la app]
+├── components/
+│   ├── ui/                # Componentes genéricos
+│   └── [dominio]/         # Componentes de dominio
+└── lib/
+    ├── utils.ts
+    └── api.ts
+```
+
+---
+
+## Mobile (React Native con Expo)
+
+```
+proyecto/
+├── CLAUDE.md
+├── .claude/
+├── .planning/
+├── .mcp.json
+├── app.json               # Configuración de Expo
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── app/               # Expo Router
+    ├── components/
+    ├── hooks/
+    ├── services/
+    ├── stores/            # Estado global (Zustand, Jotai)
+    └── utils/
+```
+
+---
+
+## Full-stack (monorepo: backend + frontend + mobile)
+
+```
+proyecto/
+├── CLAUDE.md              # Instrucciones del monorepo completo
+├── .claude/
+├── .planning/
+├── .mcp.json
+├── package.json           # Workspace root (si usa monorepo JS)
+│   o pyproject.toml      # Si el backend es Python
+├── apps/
+│   ├── backend/           # Ver estructura Python o Node arriba
+│   ├── web/               # Ver estructura React/Angular arriba
+│   └── mobile/            # Ver estructura Mobile arriba
+└── packages/              # Código compartido entre apps
+    ├── types/             # TypeScript types compartidos
+    └── ui/                # Componentes UI compartidos
+```
+
+**Consideraciones para monorepos**:
+- El CLAUDE.md raíz describe el monorepo completo
+- Cada app puede tener su propio CLAUDE.md con instrucciones específicas
+- Los comandos de desarrollo suelen incluir scripts de workspace (`npm -w apps/backend dev`)
+- Considerar Turborepo o Nx para gestión de builds en monorepos grandes