swl-ses 3.3.2

package/habilidades/estructura-proyecto-claude/recursos/claude-md-template.md

@@ -0,0 +1,261 @@
+# CLAUDE.md — [Nombre del Proyecto]
+
+> Fuente de verdad del proyecto para Claude Code.
+> Claude lee este archivo al inicio de cada sesion.
+> Actualizar cuando cambien convenciones, stack o arquitectura.
+> Mantener bajo 200 lineas — usar .claude/rules/ para instrucciones extensas.
+> Ultima actualizacion: [YYYY-MM-DD]
+
+---
+
+## Que es este proyecto
+
+[2-3 oraciones describiendo el proposito del proyecto, el problema que resuelve
+y a quien va dirigido. Ser especifico — evitar frases genericas como "sistema
+de gestion empresarial".]
+
+**Ejemplo**:
+> API REST para el sistema de facturacion electronica de PyMEs en Mexico.
+> Genera CFDIs 4.0 certificados por el SAT e integra con los PACs Finkok y Diverza.
+> Expone una interfaz REST consumida por el frontend Angular y la app movil React Native.
+
+---
+
+## 1. Stack tecnologico
+
+| Capa | Tecnologia | Version |
+|------|-----------|---------|
+| Lenguaje backend | Python | 3.12 |
+| Framework backend | FastAPI | 0.115+ |
+| ORM | SQLAlchemy | 2.0 (async) |
+| Base de datos | PostgreSQL | 16 |
+| Migraciones | Alembic | 1.13+ |
+| Gestor de paquetes | uv | 0.5+ |
+| Lenguaje frontend | TypeScript | 5.4+ |
+| Framework frontend | Angular | 20+ |
+| Estilos | Tailwind CSS | 4.0 |
+| Tests backend | pytest + httpx | - |
+| Tests frontend | Jasmine + Karma | - |
+| CI/CD | GitHub Actions | - |
+| Contenedores | Docker + Compose | - |
+
+> Ajustar esta tabla al stack real del proyecto. Eliminar filas que no aplican.
+
+---
+
+## 2. Convenciones de codigo
+
+### Python / Backend
+
+- **Estilo**: PEP 8 + Ruff para lint y formato. Maximo 88 caracteres por linea.
+- **Type hints**: Obligatorios en toda funcion publica. Sin `Any` sin justificacion.
+- **Docstrings**: Solo en funciones publicas de modulos, clases y endpoints complejos.
+  Formato Google Style.
+- **Imports**: Agrupados — stdlib, terceros, locales. Separados por linea en blanco.
+- **Nombres**: `snake_case` para variables y funciones, `PascalCase` para clases.
+
+### TypeScript / Frontend
+
+- **Framework**: Angular 20+ con signals. Sin NgModules para componentes nuevos.
+- **Directivas de control**: `@if`, `@for`, `@switch`. NUNCA `*ngIf`, `*ngFor`.
+- **Estado**: `signal()` y `computed()` para estado reactivo.
+- **Estilos**: Tailwind CSS. Angular Material SOLO para componentes funcionales.
+- **HTTP**: Siempre tipado. Sin `any` en responses de API.
+
+### Naming conventions
+
+- Archivos: `kebab-case` para todos los archivos
+- Componentes Angular: `nombre.component.ts`, `nombre.component.html`
+- Services: `nombre.service.ts`
+- Models: `nombre.model.ts`
+- Tests: `nombre.spec.ts` (frontend), `test_nombre.py` (backend)
+
+---
+
+## 3. Arquitectura
+
+```
+src/
++-- [capa-1]/          # [Descripcion: ej. "Componentes React compartidos"]
++-- [capa-2]/          # [Descripcion: ej. "Handlers / logica de negocio"]
++-- [capa-3]/          # [Descripcion: ej. "Utilidades compartidas"]
++-- [capa-4]/          # [Descripcion: ej. "Modelos de datos y schemas"]
+```
+
+### Reglas de arquitectura
+- Services no importan directamente modelos de otros dominios
+- Endpoints no tienen logica de negocio — delegan a services
+- Componentes no hacen llamadas HTTP directamente — usan services
+
+---
+
+## 4. Seguridad
+
+- No secretos en codigo ni logs — usar variables de entorno
+- Validar todos los inputs del usuario en el boundary del sistema
+- Usar queries parametrizadas — NUNCA concatenacion de strings SQL
+- RBAC en todos los endpoints que modifican datos
+- CORS configurado explicitamente — no wildcard `*` en produccion
+- Rate limiting en endpoints publicos
+- Headers de seguridad: HSTS, X-Content-Type-Options, X-Frame-Options
+
+---
+
+## 5. Testing
+
+### Estrategia de tests
+
+| Tipo | Framework | Cobertura minima |
+|------|-----------|-----------------|
+| Unit tests backend | pytest | 80% lineas |
+| Integration tests | pytest + httpx | Todos los endpoints |
+| Unit tests frontend | Jasmine + Karma | 70% lineas |
+| E2E tests | Playwright / Cypress | Flujos criticos |
+
+### Como correr tests
+
+```bash
+# Backend — tests completos con cobertura
+pytest tests/ --cov=app --cov-report=html -v
+
+# Backend — solo un modulo
+pytest tests/test_facturacion.py -v
+
+# Frontend — tests unitarios
+ng test
+
+# Frontend — E2E
+ng e2e
+
+# Lint y tipo-checking
+ruff check app/ tests/
+mypy app/
+```
+
+### Reglas de testing
+- Todo PR debe incluir tests para codigo nuevo/modificado
+- Tests deben tener assertions reales (no solo verificar que no lanza excepcion)
+- Fixtures compartidas en `conftest.py` / `test-utils.ts`
+- Mock solo para dependencias externas (APIs, email). NUNCA mockear la BD en integration tests.
+
+---
+
+## 6. Git Workflow
+
+### Ramas
+- `main` — produccion, protegida
+- `develop` — integracion (si aplica)
+- `feature/descripcion-corta` — features nuevas
+- `fix/descripcion-corta` — bug fixes
+- `chore/descripcion` — mantenimiento
+
+### Commits
+Formato Conventional Commits en ingles:
+```
+feat: add CFDI billing endpoint
+fix: correct RFC validation in schema
+chore: update security dependencies
+refactor: extract billing logic to service
+test: add integration tests for auth flow
+```
+
+### Pull Requests
+- Al menos 1 revisor
+- Tests pasando en CI
+- Sin TODO sin ticket asociado
+- Squash merge a main
+
+---
+
+## 7. Comandos comunes (Workflows)
+
+```bash
+# --- Setup inicial ---
+uv sync                                    # Instalar dependencias Python
+npm install                                # Instalar dependencias frontend
+
+# --- Desarrollo ---
+uvicorn app.main:app --reload --port 8000  # Backend dev server
+ng serve --open                            # Frontend dev server
+
+# --- Base de datos ---
+alembic revision --autogenerate -m "desc"  # Crear migracion
+alembic upgrade head                       # Aplicar migraciones
+alembic downgrade -1                       # Revertir ultima
+
+# --- Testing ---
+pytest tests/ -v                           # Tests backend
+ng test                                    # Tests frontend
+
+# --- Calidad ---
+ruff check app/ tests/                     # Lint Python
+ruff format app/ tests/                    # Format Python
+mypy app/                                  # Type checking
+
+# --- Docker ---
+docker compose up -d postgres redis        # Solo infra
+docker compose up --build                  # Todo
+docker compose down                        # Detener
+```
+
+---
+
+## Reglas anti-error del proyecto
+
+> Estas reglas documentan errores que ya ocurrieron en este proyecto.
+> Son la segunda defensa despues de los tests.
+
+### Backend
+
+- **selectinload OBLIGATORIO**: Toda relacion accedida en serializacion Pydantic
+  DEBE tener `selectinload()` en el query. Sin esto -> `MissingGreenlet` en runtime.
+- **Services NO hacen commit**: Solo `db.add()`, `db.flush()`, `db.refresh()`.
+  El commit SIEMPRE en el endpoint.
+- **Literal[] en schemas**: Campos con dominio cerrado (`estatus`, `tipo`) DEBEN
+  usar `Literal["valor1", "valor2"]`. NUNCA `str` sin restriccion.
+- **RBAC en escritura**: Todos los endpoints POST/PUT/DELETE deben tener
+  `_=Depends(require_role([...]))`.
+
+### Frontend
+
+- **PaginatedResponse**: Todo endpoint paginado parsear con `.pipe(map(r => r.items))`.
+- **track obligatorio en @for**: `@for (item of items; track item.id)`.
+- **takeUntilDestroyed()**: En toda suscripcion larga o polling.
+
+---
+
+## Estructura de archivos
+
+```
+[Pegar aqui la estructura de arbol del proyecto, generada con:
+  tree -I "node_modules|__pycache__|.git|*.pyc|dist|build" --max-depth=3
+]
+```
+
+---
+
+## Variables de entorno requeridas
+
+Copiar `.env.example` a `.env` y completar antes de ejecutar:
+
+```bash
+cp .env.example .env
+```
+
+Descripcion de cada variable en `.env.example`. Las variables marcadas con `*`
+son obligatorias para correr en desarrollo.
+
+---
+
+## Agentes y skills activos en este proyecto
+
+| Tipo | Nombre | Proposito |
+|------|--------|-----------|
+| Skill | [nombre] | [que cubre] |
+| Agente | [nombre] | [cuando se usa] |
+| Comando | `/proyecto:nombre` | [que hace] |
+
+---
+
+*Template generado con `Skill("estructura-proyecto-claude")` el [YYYY-MM-DD].*
+*Mantener actualizado al cierre de cada fase con `consolidador-swl`.*

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

@@ -0,0 +1,213 @@
+# 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 | Descripcion |
+|-------|-----------|------|-------------|
+| `name` | No* | string | Nombre kebab-case, max 64 chars. Se convierte en `/nombre` para invocacion. *Si se omite, usa el nombre del directorio |
+| `description` | Recomendado | string | Max 1024 chars. QUE hace + CUANDO usar. Guia la auto-activacion 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 esta 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 conversacion |
+| `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 menu `/` |
+
+### 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 sesion
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `SessionStart` | Al iniciar o resumir sesion | `startup`, `resume`, `clear`, `compact` | Cargar contexto, setup env |
+| `SessionEnd` | Al terminar sesion | `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 |
+
+### Ejecucion de herramientas
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `PreToolUse` | Antes de ejecutar herramienta | Nombre de tool (Bash, Edit, Read, mcp__*) | Bloquear ops inseguras, validar |
+| `PostToolUse` | Despues de ejecutar herramienta (exito) | Nombre de tool | Auto-lint, format, log |
+| `PostToolUseFailure` | Cuando falla herramienta | Nombre de tool | Notificar, reintentar |
+| `PermissionRequest` | Se muestra dialogo de permiso | Nombre de tool | Auto-aprobar acciones seguras |
+
+### Respuesta y control
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `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 envia prompt | Ninguno | Interceptar/enriquecer input |
+
+### Compactacion de contexto
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `PreCompact` | Antes de compactar | `manual`, `auto` | Salvar estado critico |
+| `PostCompact` | Despues de compactar | `manual`, `auto` | Re-inyectar contexto |
+
+### Subagentes
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `SubagentStart` | Al spawnar subagente | `Explore`, `Plan`, `general-purpose`, nombres custom | Log creacion |
+| `SubagentStop` | Al terminar subagente | Mismos que SubagentStart | Cleanup worktrees |
+| `TeammateIdle` | Miembro de equipo idle | Ninguno | Keep alive, escalar |
+
+### Tasks
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `TaskCreated` | Al crear tarea | Ninguno | Log, validar tasks |
+| `TaskCompleted` | Al completar tarea | Ninguno | Notificar, log |
+
+### Configuracion y archivos
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `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 | Patron de nombre (`.envrc`, `.env`) | Recargar config, re-lint |
+
+### Git worktrees
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `WorktreeCreate` | Git worktree creado | Ninguno | Setup custom |
+| `WorktreeRemove` | Git worktree removido | Ninguno | Cleanup recursos |
+
+### MCP
+
+| Evento | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `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 | Cuando se dispara | Matchers | Uso tipico |
+|--------|-------------------|----------|-----------|
+| `Notification` | Claude espera input | `permission_prompt`, `idle_prompt`, `auth_success` | Alertas desktop, sonidos |
+
+---
+
+## Tipos de handler para hooks
+
+| Tipo | Descripcion | Ejemplo |
+|------|-------------|---------|
+| `command` | Ejecuta comando shell | `"command": "node .claude/hooks/lint.js"` |
+| `prompt` | Claude decide que 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"` |
+
+### Codigos de retorno para hooks command
+
+| Codigo | Significado |
+|--------|-------------|
+| `0` | Permitir (allow) |
+| `2` | Bloquear (block) — la operacion no se ejecuta |
+| Otro | Error — Claude decide que hacer |
+
+---
+
+## 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": "Descripcion 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"]
+    }
+  }
+}