@saulwade/swl-ses 1.5.1 → 1.5.2

package/README.md

@@ -1,562 +1,562 @@
-# swl-ses v1.5.1
-
-> El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
-
-Sistema de ingeniería de software auto-evolutivo **multi-runtime** con agentes especializados, habilidades modulares, hooks de seguridad y orquestación ligera. 100% en español (México). Soporta 11 lenguajes: Python, TypeScript, Java, Go, Rust, C#, Kotlin, Swift, PHP, Next.js y C++.
-
-Soporta 7 runtimes de IA: Claude Code, OpenClaude, OpenCode y Gemini CLI (soporte completo); Cursor, Codex CLI y GitHub Copilot (soporte parcial — reglas + MCP server o consolidación en archivo de instrucciones según el runtime). Incluye sistema de transformadores que adapta el formato canónico SWL al formato nativo de cada runtime, **multi-target install** (`--target=claude,cursor,codex` en una sola invocación), y **`swl-mcp-server` v1.0.0** con auth opt-in para que Cursor, Codex y otros clientes MCP consulten la memoria SWL (aprendizajes, instintos, sesiones).
-
-Cubre el SDLC completo: discovery, requisitos, arquitectura, UX/UI, frontend, backend, mobile, datos, testing, seguridad, CI/CD, observabilidad, releases, documentación, notificaciones y auto-evolución. Incluye sistema de notificaciones Telegram opt-in (hook saliente, bot bidireccional con 15 comandos, autostart cross-platform) y **auditoría profunda Nemesis** (loop iterativo Feynman + State Inconsistency hasta convergencia) con 8 tools ejecutables JSON-output para code-profiler, pentest-scanner, dep-doctor, bundle-tracker y más (ADR-0018, v1.4.1).
-
-## Inventario
-
-| Componente | Cantidad |
-|-----------|----------|
-| Agentes SWL | 60 |
-| Habilidades | 160 (todas <=300 líneas, con divulgación progresiva a recursos/) |
-| Comandos (/swl:*) | 44 (todos <=300 líneas, delegan a skills) |
-| Reglas | 25 base + 40 por lenguaje (8 lenguajes x 5) |
-| Hooks | 41 + 66 librerías en hooks/lib/ |
-| Tools ejecutables (audit-tools) | 8 (code-profiler, pentest-scanner, dep-doctor, bundle-tracker, env-validator, migration-checker, canary-monitor, audit-history) |
-| Schemas | 15 |
-| Perfiles de instalación | 17 |
-| Contextos | 3 (dev, review, research) |
-| Gateway multi-plataforma | Telegram, Discord, WhatsApp, Slack, Email, Webhook (salida bidireccional opt-in) |
-
-## Lenguajes soportados (11)
-
-| Lenguaje | Reglas | Skills | Agente Revisor | Agente Implementador | Build Errors |
-|----------|--------|--------|----------------|---------------------|-------------|
-| Python | base | 7 | revisor-codigo-swl | backend-python-swl | build-errors-python |
-| TypeScript | base | 2 | revisor-codigo-swl | backend-node-swl | build-errors-typescript |
-| Java | 5 | 4 | revisor-java-swl | backend-java-swl | build-errors-java |
-| Go | 5 | 4 | revisor-go-swl | backend-go-swl | build-errors-go |
-| Rust | 5 | 4 | revisor-rust-swl | backend-rust-swl | build-errors-rust |
-| C#/.NET | 5 | 4 | revisor-csharp-swl | backend-csharp-swl | build-errors-csharp |
-| Kotlin | 5 | 4 | revisor-kotlin-swl | mobile-android-swl | build-errors-kotlin |
-| Swift | 5 | 4 | revisor-swift-swl | mobile-ios-swl | build-errors-swift |
-| PHP | 5 | 4 | revisor-php-swl | implementador-swl | build-errors-php |
-| Next.js | 5 | 4 | revisor-nextjs-swl | frontend-react-swl | build-errors-nextjs |
-| C++ | - | 1 | - | - | build-errors-cpp |
-
-## Instalación
-
-### Entender `init` vs `install`
-
-El setup requiere **dos comandos en orden**, con propósitos distintos:
-
-| Comando | Qué crea | Dónde | Instala agentes/skills |
-|---------|----------|-------|------------------------|
-| `npx @saulwade/swl-ses@latest init` | `.planning/` y `_userland/` (plantillas vacías) | En el proyecto actual | ❌ No |
-| `npx @saulwade/swl-ses@latest install` | Agentes, skills, reglas, hooks, comandos `/swl:*` | En `.claude/` del proyecto o en `~/.claude/` global | ✅ Sí |
-
-**`init` siempre es local al proyecto.** `install` puede ser local (`--local`, default) o global (`--global`).
-
-> Instalar globalmente (`--global` o `npm install -g swl-ses`) pone los componentes en `~/.claude/`
-> y los hace disponibles en todos tus proyectos. Aun así, cada proyecto necesita su propio `init`
-> para obtener `.planning/` y `_userland/`.
-
-### Opción 1: CLI vía npmjs (recomendada)
-
-```bash
-cd /ruta/a/tu/proyecto
-npx @saulwade/swl-ses@latest init                                       # Crea .planning/ y _userland/
-npx @saulwade/swl-ses@latest install --target claude --profile core     # Instala agentes, skills, hooks y reglas
-npx @saulwade/swl-ses@latest doctor                                     # Verifica que todo quedó correcto
-```
-
-No requiere autenticación. El paquete `swl-ses` está publicado en npmjs.
-
-#### Instalación global (una vez, disponible en todos los proyectos)
-
-```bash
-# Instalar swl-ses globalmente
-npm install -g swl-ses
-
-# En cada proyecto nuevo:
-cd /ruta/a/mi-proyecto
-swl-ses install --global --target claude --profile core  # Componentes en ~/.claude/ (una sola vez)
-swl-ses init                                             # Estructura .planning/ en este proyecto
-swl-ses doctor
-```
-
-### Opción 2: CLI vía GitHub Packages (mirror)
-
-```bash
-# Requiere autenticación con GitHub (ver INSTALACION.md)
-npx @saul-wade/swl-ses@latest init
-npx @saul-wade/swl-ses@latest install --target claude --profile core
-```
-
-Nota: la opción canónica es **npmjs.org** (`@saulwade/swl-ses`), GitHub Packages
-es un mirror para usuarios que prefieran ese registry. El binario y el contenido
-son idénticos.
-
-#### Por qué los scopes difieren
-
-La organización en npmjs.org se llama `saulwade` (sin guion) porque
-**npm no permite guiones en nombres de organización** — el registro
-los rechaza desde el formulario de creación. La organización en GitHub
-sí acepta guiones y se llama `saul-wade`. Como cada registry deriva el
-scope del paquete del nombre de la org propietaria, terminamos con
-`@saulwade/swl-ses` en npmjs y `@saul-wade/swl-ses` en GitHub Packages.
-El contenido publicado es idéntico; el comando CLI `swl-ses` no cambia.
-
-### Opción 3: Clonar y usar directamente
-
-```bash
-git clone https://github.com/saul-wade/swl-ses.git
-cd swl-ses
-claude
-# Claude lee CLAUDE.md y tiene acceso a todo el sistema
-```
-
-### Opción 4: Plugin de Claude Code
-
-```bash
-# Dentro de una sesion de Claude Code:
-/plugin marketplace add https://github.com/saul-wade/swl-ses
-/plugin install swl-ses@saul-wade
-```
-
-> Para forzar siempre la última versión:
-> `npx @saulwade/swl-ses@latest <comando>`
-
-## Comandos del CLI
-
-> Las tablas siguientes usan el alias corto `swl-ses@latest` (sin scope) por
-> compatibilidad con instalación global (`npm install -g swl-ses` enlaza el
-> bin con ese nombre). Para forzar el paquete canónico desde npmjs sin
-> tocar la instalación global, sustituir por `@saulwade/swl-ses@latest`
-> (npmjs canónico) o `@saul-wade/swl-ses@latest` (mirror GitHub Packages).
-
-| Comando | Descripción |
-|---------|-------------|
-| `npx @saulwade/swl-ses@latest init` | Crea `.planning/` (plantillas de planificación) y `_userland/` (tus personalizaciones) en el proyecto actual. **No instala agentes ni skills.** |
-| `npx @saulwade/swl-ses@latest install` | Instala agentes, skills, reglas, hooks y comandos `/swl:*` en el runtime destino (`.claude/` local o `~/.claude/` global). |
-| `npx @saulwade/swl-ses@latest doctor` | Diagnostica problemas de la instalación |
-| `npx @saulwade/swl-ses@latest update` | Actualiza componentes instalados |
-| `npx @saulwade/swl-ses@latest uninstall` | Desinstala componentes del runtime |
-| `npx @saulwade/swl-ses@latest info` | Muestra información del sistema instalado |
-| `npx @saulwade/swl-ses@latest skills list` | Lista skills instalados |
-| `npx @saulwade/swl-ses@latest skills add <fuente>` | Agrega skill desde repo Git, owner/repo, o path local |
-| `npx @saulwade/swl-ses@latest skills remove <nombre>` | Remueve un skill individual |
-| `npx @saulwade/swl-ses@latest agents list` | Lista agentes instalados |
-| `npx @saulwade/swl-ses@latest agents add <fuente>` | Agrega agente desde repo Git o path local |
-| `npx @saulwade/swl-ses@latest agents remove <nombre>` | Remueve un agente individual |
-
-### Opciones de install
-
-| Opción | Valores | Descripción |
-|--------|---------|-------------|
-| `--target <runtime>` | `claude`, `openclaude`, `copilot`, `opencode`, `codex`, `gemini` | Runtime destino (default: `claude`) |
-| `--profile <perfil>` | Ver perfiles abajo | Perfil de instalación (default: `core`) |
-| `--global` | — | Instala en directorio global (`~/.claude/`) |
-| `--local` | — | Instala en directorio local del proyecto (`.claude/`) |
-| `--with <componentes>` | Separados por coma | Incluir módulos adicionales |
-| `--without <componentes>` | Separados por coma | Excluir módulos |
-| `--dry-run` | — | Muestra plan sin aplicar cambios |
-| `--force` | — | Sobrescribe archivos existentes |
-
-### Perfiles de instalación
-
-| Perfil | Descripción |
-|--------|-------------|
-| `core` | Mínimo viable: orquestador + agentes base + reglas + comandos |
-| `backend-python` | FastAPI/Django + patrones + testing + async + API + datos |
-| `backend-node` | Express/Fastify/NestJS + TypeScript + API + datos |
-| `backend-java` | Spring Boot + Maven/Gradle + patrones Java + testing + API |
-| `backend-go` | Go + Gin/Echo + patrones Go + testing + API |
-| `backend-rust` | Rust + Axum/Actix + patrones Rust + testing + API |
-| `backend-csharp` | .NET + ASP.NET Core + patrones C# + testing + API |
-| `frontend-react` | React/Next.js + UX + estilos + accesibilidad |
-| `frontend-angular` | Angular v20+ + signals + UX + estilos |
-| `fullstack-python-angular` | Python backend + Angular frontend + datos + seguridad |
-| `fullstack-node-react` | Node.js backend + React frontend + datos + seguridad |
-| `fullstack-java-angular` | Java backend + Angular frontend + datos + seguridad |
-| `fullstack-go-react` | Go backend + React frontend + datos + seguridad |
-| `mobile` | Android + iOS + React Native/Flutter + UX |
-| `devops` | CI/CD + cloud + observabilidad + releases + seguridad |
-| `polyglot` | Todos los lenguajes: 11 lenguajes + revisores + build resolvers |
-| `completo` | Todo: 60 agentes + 160 habilidades + 44 comandos + 65 reglas + 41 hooks |
-
-### Targets soportados
-
-| Target | Runtime | Soporte | Componentes |
-|--------|---------|---------|-------------|
-| `claude` | Claude Code | Completo | Agentes, skills, comandos, reglas, hooks |
-| `openclaude` | OpenClaude | Completo | Agentes, skills, comandos, reglas, hooks |
-| `opencode` | OpenCode | Completo | Agentes, skills, comandos, reglas, hooks |
-| `gemini` | Gemini CLI | Completo | Agentes, skills, comandos, reglas, hooks |
-| `copilot` | GitHub Copilot | Parcial | Solo agentes y reglas (limitación de plataforma) |
-| `codex` | Codex CLI | Completo | Agentes en `~/.codex/agents/<name>.toml` (Sub-fase 11) + AGENTS.md con marcadores como índice + skills en `~/.agents/skills/<name>/SKILL.md` (path oficial OpenAI) + hooks en `~/.codex/hooks.json` (6 eventos) + MCP en `~/.codex/config.toml` con `--with-mcp` |
-| `cursor` | Cursor | Completo | Agentes en `.cursor/agents/<name>.md` (Subagents) + skills en `.cursor/skills/<name>/SKILL.md` + reglas en `.cursor/rules/*.mdc` + hooks en `.cursor/hooks.json` (17 eventos) + MCP en `.cursor/mcp.json` con `--with-mcp` |
-
-> **OpenClaude** usa los mismos directorios de proyecto que Claude Code (`.claude/`). Instalar `--target openclaude` en un proyecto con Claude Code aplica a ambos simultáneamente.
-
-### Ejemplos
-
-```bash
-# Perfil básico en Claude Code
-npx @saulwade/swl-ses@latest install --target claude --profile core
-
-# Backend Python en Gemini CLI
-npx @saulwade/swl-ses@latest install --target gemini --profile backend-python
-
-# Frontend React en GitHub Copilot
-npx @saulwade/swl-ses@latest install --target copilot --profile frontend-react
-
-# Full-stack en OpenClaude (multi-proveedor, usa .claude/ igual que Claude Code)
-npx @saulwade/swl-ses@latest install --target openclaude --profile fullstack-python-angular
-
-# Full-stack en OpenCode
-npx @saulwade/swl-ses@latest install --target opencode --profile fullstack-python-angular
-
-# Perfil completo en directorio global
-npx @saulwade/swl-ses@latest install --target claude --profile completo --global
-
-# Agregar skills desde GitHub con selector interactivo
-npx @saulwade/swl-ses@latest skills add anthropics/skills
-
-# Agregar un skill específico por nombre
-npx @saulwade/swl-ses@latest skills add anthropics/skills --skill docx
-
-# Agregar todos los skills de un repo sin selector
-npx @saulwade/swl-ses@latest skills add anthropics/skills --all
-
-# Agregar skill desde URL completa
-npx @saulwade/swl-ses@latest skills add https://github.com/user/repo --skill mi-skill
-
-# Agregar agente desde path local
-npx @saulwade/swl-ses@latest agents add ./mis-agentes --agent mi-agente
-
-# Ver que se instalaria sin hacer cambios
-npx @saulwade/swl-ses@latest install --target codex --profile core --dry-run
-
-# Ver información del sistema
-npx @saulwade/swl-ses@latest info --target claude
-```
-
-## Agentes (59)
-
-### Orquestación y Proceso
-`orquestador-swl`, `producto-prd-swl`, `consolidador-swl`, `auto-evolución-swl`
-
-### Discovery e Investigación
-`investigador-swl`, `investigador-ux-swl`
-
-### Arquitectura
-`arquitecto-swl`, `planificador-swl`
-
-### UX / UI / Diseño
-`ux-disenador-swl`, `disenador-ui-swl`, `accesibilidad-wcag-swl`
-
-### Frontend
-`frontend-swl`, `frontend-react-swl`, `frontend-angular-swl`, `frontend-css-swl`, `frontend-tailwind-swl`
-
-### Backend
-`implementador-swl`, `backend-python-swl`, `backend-node-swl`, `backend-api-swl`, `backend-workers-swl`
-
-### Backend Multi-Lenguaje (nuevo)
-`backend-java-swl`, `backend-go-swl`, `backend-csharp-swl`, `backend-rust-swl`
-
-### Mobile
-`mobile-android-swl`, `mobile-ios-swl`, `mobile-cross-swl`
-
-### Datos
-`datos-swl`, `migrador-swl`
-
-### Calidad
-`tdd-qa-swl`, `revisor-codigo-swl`, `revisor-seguridad-swl`
-
-### Revisores por Lenguaje (nuevo)
-`revisor-java-swl`, `revisor-go-swl`, `revisor-rust-swl`, `revisor-csharp-swl`, `revisor-kotlin-swl`, `revisor-swift-swl`, `revisor-php-swl`, `revisor-nextjs-swl`
-
-### Infraestructura
-`devops-ci-swl`, `cloud-infra-swl`, `observabilidad-swl`
-
-### Rendimiento y Releases
-`rendimiento-swl`, `release-manager-swl`
-
-### Documentación, Notificaciones, Debugging
-`documentador-swl`, `notificador-swl`, `depurador-swl`
-
-### Build Resolution
-`resolutor-build-swl`
-
-### LLM, Pagos y SRE
-`llm-apps-swl`, `pagos-swl`, `sre-swl`
-
-### Revisores adicionales
-`revisor-typescript-swl`, `revisor-react-swl`, `revisor-angular-swl`
-
-## Comandos (/swl:*)
-
-| Comando | Función |
-|---------|---------|
-| `/swl:instalar` | Instalación interactiva dentro de Claude Code |
-| `/swl:actualizar` | Actualizar sin desinstalar |
-| `/swl:nuevo-proyecto` | Inicializar proyecto con PROYECTO.md y roadmap |
-| `/swl:discutir-fase` | Recopilar contexto antes de planificar |
-| `/swl:planear-fase` | Crear PLAN.md con vertical slices |
-| `/swl:ejecutar-fase` | Ejecutar plan con commits atómicos |
-| `/swl:verificar` | Verificar implementación contra spec |
-| `/swl:mapear-codebase` | Analizar codebase existente |
-| `/swl:checkpoint` | Guardar estado para continuar después |
-| `/swl:compactar` | Reducir contexto preservando info clave |
-| `/swl:aprender` | Extraer aprendizajes de la sesión |
-| `/swl:evolucionar` | Auto-evolución de agentes/skills |
-| `/swl:autoresearch` | Loop de auto-mejora iterativa contra checklist |
-| `/swl:crear-skill` | Crear nuevo skill con guía interactiva |
-| `/swl:salud` | Diagnóstico de integridad del sistema |
-| `/swl:release` | Ciclo de release SemVer |
-| `/swl:auditar-deps` | Auditoría de dependencias (CVEs) |
-| `/swl:contexto` | Cambiar modo de desarrollo activo (dev/review/research) |
-| `/swl:sesiones` | Gestionar persistencia de sesiones de trabajo |
-| `/swl:instintos` | Inspeccionar y gestionar instintos del sistema |
-| `/swl:modelo` | Configurar modelo de IA por agente o globalmente |
-| `/swl:metricas` | Ver métricas de sesión y productividad |
-| `/swl:dashboard` | Dashboard histórico de uso multi-sesión (gráficas interactivas) |
-| `/swl:revisar-impacto` | Análisis de impacto estructural: blast radius, risk score, comunidades |
-| `/swl:evaluar-skill` | Evaluación formal de skills: 2 capas (estática + semántica), badges de calidad |
-| `/swl:wiki` | Gestionar wiki de conocimiento del proyecto (init/ingest/query/lint) |
-| `/swl:plugins` | Gestionar plugins y extensiones del sistema |
-| `/swl:revisar` | Revisión de código por tecnología |
-| `/swl:brainstorm` | Brainstorming estructurado |
-| `/swl:ayuda` | Ayuda interactiva: catálogo, detalle de comando, búsqueda por keyword |
-| `/swl:skill-search` | Buscar skills por keyword o dominio |
-| `/swl:mcp-status` | Estado de servidores MCP conectados |
-| `/swl:cron` | Gestionar tareas programadas |
-| `/swl:gateway` | Configurar gateway multi-plataforma + modo relay bidireccional Telegram → Claude |
-| `/swl:inbox` | Consumir comandos entrantes del gateway (enviados desde Telegram/Discord/webhook) |
-| `/swl:reflect-skills` | Analizar historial JSONL para detectar patrones candidatos a skill/comando emergente |
-| `/swl:contribuir` | Contribuir evoluciones al core (filtro dominio + PluginEval ≥80) |
-| `/swl:exportar-vault` | Exportar resumen de sesión al vault personal (Obsidian u otro) |
-
-Ver [COMANDOS.md](COMANDOS.md) para flags y opciones detalladas de cada comando.
-Ver [MANUAL_USO.md](MANUAL_USO.md) para explicaciones prácticas de cada comando y guías de cuándo usarlos.
-
-## Arquitectura
-
-### Thin Orchestrator
-
-```
-Comando (/swl:planear-fase)
-  +-> Cargar habilidad (planear-fase/SKILL.md)
-  +-> Spawn agente (planificador-swl) con contexto fresco
-  +-> Verificar resultado (revisor-codigo-swl)
-  +-> Actualizar estado (.planning/ESTADO.md)
-```
-
-### Estado en archivos (.planning/)
-
-```
-.planning/
-  PROYECTO.md          # Vision, contexto, objetivos
-  REQUISITOS.md     # Requisitos con IDs (REQ-001...)
-  HOJA-RUTA.md          # Fases con entregables y verificación
-  ESTADO.md            # Estado actual, decisiones, riesgos
-  CONTEXTO.md         # Modo de desarrollo activo
-  METRICAS.md         # Métricas de sesión
-  research/           # Investigación del dominio
-  fases/              # Documentos por fase (CONTEXTO, PLAN, RESUMEN, VERIFICACION)
-  sessions/           # Persistencia de sesiones JSON
-  comms/              # Comunicación entre agentes
-```
-
-### Arquitectura de 4 capas
-
-| Capa | Componente | Propósito |
-|------|-----------|-----------|
-| L1 | CLAUDE.md | Contexto persistente y reglas |
-| L2 | Skills | Paquetes de conocimiento versionados |
-| L3 | Hooks | Seguridad y automatización |
-| L4 | Agents | Subagentes con contexto aislado |
-
-## Gateway bidireccional con Telegram (opt-in)
-
-El sistema incluye un gateway que permite **enviar comandos a Claude desde Telegram** (u otro adaptador) y recibir respuestas sin necesidad de estar frente al teclado. Todo el flujo es opt-in y queda en audit trail.
-
-### Flujo
-
-```
-Telegram (móvil)  →  CommandRelay (valida)  →  .planning/inbox/cmd-*.json  →  /swl:inbox en Claude
-                                                                              o claude -p headless (auto)
-```
-
-### Protecciones del CommandRelay
-
-- Whitelist de usuarios por plataforma (`relay.platforms.<nombre>.allowedUsers`)
-- Rechazo de payload injection: `<script>`, `.env`, `id_rsa`, `.ssh/`, etc.
-- Límite de 4000 chars por mensaje
-- Rate limit: 10 msg/min por usuario (configurable)
-- Dedup por hash SHA-1 en ventana de 30s
-- Audit trail append-only en `.planning/inbox/audit.jsonl`
-
-### Modos de consumo
-
-| Modo | Qué hace | Compatible |
-|---|---|---|
-| Portable (default) | Los mensajes se encolan; al ejecutar `/swl:inbox` en tu sesión Claude los procesas con juicio humano | Windows / Linux / macOS |
-| Auto-exec headless | El bot invoca `claude -p --model haiku-4-5 --max-budget-usd 0.50 --allowedTools <solo-lectura>` en el cwd del proyecto y responde con el output | Windows / Linux / macOS |
-| tmux inject (opt-in) | Daemon `scripts/inbox-tmux-inject.js` inyecta a una sesión tmux con `tmux send-keys` | Linux / macOS |
-
-Configuración en `manifiestos/gateway-config.json`. Ver [MANUAL_USO.md](MANUAL_USO.md) sección `/swl:gateway` para setup completo.
-
-## Skills bundled de Claude Code
-
-Los agentes SWL pueden usar estos 17 skills que vienen con Claude Code:
-
-`/pdf`, `/pptx`, `/docx`, `/xlsx`, `/frontend-design`, `/web-artifacts-builder`,
-`/claude-api`, `/brand-guidelines`, `/skill-creator`, `/mcp-builder`,
-`/webapp-testing`, `/internal-comms`, `/doc-coauthoring`, `/canvas-design`,
-`/algorithmic-art`, `/theme-factory`, `/slack-gif-creator`
-
-## Modo _userland/
-
-Coloca tus agentes y habilidades personalizados en `_userland/`:
-
-```
-_userland/
-  agentes/
-    mi-agente-custom.md
-  habilidades/
-    mi-habilidad/
-      SKILL.md
-```
-
-El instalador detecta `_userland/`, hace merge con los componentes core y da prioridad a tus archivos.
-
-## Publicación
-
-El paquete se publica en dos registros (dual-publish):
-
-| Registro | Paquete | Requiere auth |
-|----------|---------|---------------|
-| npmjs.org (canónico) | `@saulwade/swl-ses` | Solo para publicar |
-| GitHub Packages (mirror) | `@saul-wade/swl-ses` | Para instalar y publicar |
-
-```bash
-# Publicar a ambos registros
-npm run publish:all
-
-# Solo GitHub Packages
-npm run publish:github
-
-# Solo npmjs
-npm run publish:npmjs
-
-# Simular sin publicar
-npm run publish:dry
-```
-
-Ver [INSTALACION.md](INSTALACION.md) para configuración detallada de autenticación y publicación.
-
-## Verificación (doctor)
-
-```bash
-npx @saulwade/swl-ses@latest doctor
-```
-
-Verifica: Node.js >= 22, runtimes detectados, `.planning/` completo, `_userland/` presente, estado íntegro, permisos, `.env` en `.gitignore`. Repara automáticamente hooks sin `"type": "command"` en settings.json.
-
-## Estructura del repositorio
-
-```
-swl-ses/
-  package.json              # Paquete npm con bin swl-ses
-  plugin.json               # Manifest para Claude Code plugin system
-  bin/swl-ses.js            # CLI principal
-  scripts/                  # Lógica del CLI
-    comandos/               # Handlers de subcomandos (skills, agents, info)
-    lib/                    # Librerías compartidas
-      transformadores/      # Transformadores por target (claude, copilot, opencode, codex, gemini)
-      detectar-runtime.js   # Detección de runtimes de IA
-      gestor-componentes.js # Gestión de skills y agentes individuales
-      resolver-externo.js   # Resolución de repos Git y paths locales
-      hooks-settings.js     # Registro de hooks en settings.json
-      estado.js             # Estado de instalación (v3)
-      manifiestos.js        # Resolución de perfiles/módulos
-      seguridad.js          # Validaciones de seguridad
-  manifiestos/              # Perfiles y módulos de instalación
-  agentes/                  # 60 agentes especializados
-  habilidades/              # 160 habilidades modulares
-  comandos/swl/             # 44 comandos slash
-  reglas/                   # 25 reglas base + 40 por lenguaje
-  hooks/                    # 41 hooks + 66 librerías en hooks/lib/
-  schemas/                  # 15 JSON Schemas
-  contextos/                # 3 modos de desarrollo
-  instintos/                # Instintos YAML con confianza
-  plantillas/               # Templates para .planning/
-  gateway/                  # Gateway multi-plataforma (adapters + CommandRelay)
-    adapters/               # Telegram, Discord, Slack, WhatsApp, Email, Webhook
-    command-relay.js        # Receptor bidireccional con whitelist + validaciones
-  _userland/                # Personalización del usuario
-  CLAUDE.md                 # Fuente de verdad del sistema
-  COMANDOS.md               # Referencia completa de comandos
-  MANUAL_USO.md             # Guía práctica de uso por comando
-  INSTALACION.md            # Guía de configuración y publicación
-```
-
-## ¿Por qué usar SWL? (Análisis y Ejemplo Práctico)
-
-El Sistema SWL transforma la manera tradicional de interactuar con la IA (prompts aislados y pérdida de contexto) en un flujo de **Ingeniería de Software Estructurada**. 
-
-### Beneficios Principales
-
-1. **Estado Persistente y Cero Pérdida de Contexto:** El directorio `.planning/` mantiene documentado el producto (`PROYECTO.md`), los requerimientos (`REQUISITOS.md`) y el roadmap de desarrollo. La IA siempre sabrá en qué fase está el proyecto.
-2. **Especialización (Agentes expertizados):** Delega las tareas a agentes especializados integrados (ej. `arquitecto-swl`, `frontend-react-swl`, `revisor-seguridad-swl`) en lugar de usar comandos genéricos.
-3. **Desarrollo Metódico:** Fuerza un flujo de trabajo estructurado de *Planificar -> Ejecutar -> Verificar*.
-4. **Comandos Simplificados (`/swl:*`):** Automatiza flujos de trabajo masivos de desarrollo (ej. `/swl:planear-fase` o `/swl:auditar-deps`).
-5. **Personalización Absoluta:** El directorio `_userland/` permite inyectar plantillas, redefinir instintos de la IA y crear Habilidades (Skills) específicas para la lógica de negocio.
-
-### Ejemplo de Flujo de Trabajo Real
-
-Un proyecto típico (ej. construir una App Fullstack) usando SWL sigue estos pasos:
-
-1. **Instalación y Setup inicial**
-   ```bash
-   npx @saulwade/swl-ses@latest init
-   npx @saulwade/swl-ses@latest install --target claude --profile fullstack-node-react
-   ```
-
-2. **Definición del Proyecto (Discovery)**
-   Usa el comando `/swl:nuevo-proyecto` para estructurar la idea. El agente `producto-prd-swl` genera, tras hacerte un par de preguntas clave, los archivos `PROYECTO.md`, `REQUISITOS.md` y un `HOJA-RUTA.md` dividido en fases lógicas (Ej. Fase 1: Setup, Fase 2: Auth).
-
-3. **Planeación de la Arquitectura**
-   Usa `/swl:planear-fase Fase 2`. El agente `planificador-swl` investigará tu código y creará un `PLAN.md` que detalla los archivos a crear, dependencias a instalar y plan de pruebas. Todo documentado para tu revisión antes de escribir código.
-
-4. **Ejecución de la Fase**
-   Apruebas el plan y ejecutas `/swl:ejecutar-fase`. Los agentes de programación (ej. `backend-node-swl` y `frontend-react-swl`) implementan el código según el plan mediante commits "atómicos" que garantizan un desarrollo seguro.
-
-5. **Revisión y Verificación**
-   Finalizas con `/swl:verificar`. El agente `revisor-codigo-swl` audita el nuevo código bajo reglas estrictas (Seguridad, Clean Code, patrones específicos) y comprueba que cumpla con los requisitos iniciales.
-
-Con SWL, pasas de ser un "programador asistido por IA" a convertirte en el **Gerente de Ingeniería** de un equipo de IA altamente coordinado.
-
-## Desarrollo
-
-### Tests
-
-```bash
-npm test              # tests unitarios con node:test nativo
-npm run test:validate # Validación estructural del paquete
-npm run test:all      # Ambos
-```
-
-### CI/CD
-
-El repositorio incluye GitHub Actions (`.github/workflows/ci.yml`) que ejecuta automáticamente en push/PR a main: sintaxis de hooks, validación estructural, tests unitarios y consistencia de versiones.
-
-Los mismos workflows son distribuibles a cualquier proyecto usuario vía `/swl:configurar-ci init`: revisión de seguridad con Claude en cada PR (`swl-security.yml`), CI genérico Node 22+24 (`swl-ci.yml`) y releases automáticos desde conventional commits (`release-please.yml`). Instalación opt-in, no afecta al repo destino sin consentimiento explícito.
-
-### Herramientas de mantenimiento
-
-```bash
-npm run generate:docs  # Regenera INVENTARIO.md y SALUD.md desde el disco
-npm run field-report   # Reporte de uso real de skills y agentes
-```
-
-## Licencia
-
+# swl-ses v1.5.2
+
+> El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
+
+Sistema de ingeniería de software auto-evolutivo **multi-runtime** con agentes especializados, habilidades modulares, hooks de seguridad y orquestación ligera. 100% en español (México). Soporta 11 lenguajes: Python, TypeScript, Java, Go, Rust, C#, Kotlin, Swift, PHP, Next.js y C++.
+
+Soporta 7 runtimes de IA: Claude Code, OpenClaude, OpenCode y Gemini CLI (soporte completo); Cursor, Codex CLI y GitHub Copilot (soporte parcial — reglas + MCP server o consolidación en archivo de instrucciones según el runtime). Incluye sistema de transformadores que adapta el formato canónico SWL al formato nativo de cada runtime, **multi-target install** (`--target=claude,cursor,codex` en una sola invocación), y **`swl-mcp-server` v1.0.0** con auth opt-in para que Cursor, Codex y otros clientes MCP consulten la memoria SWL (aprendizajes, instintos, sesiones).
+
+Cubre el SDLC completo: discovery, requisitos, arquitectura, UX/UI, frontend, backend, mobile, datos, testing, seguridad, CI/CD, observabilidad, releases, documentación, notificaciones y auto-evolución. Incluye sistema de notificaciones Telegram opt-in (hook saliente, bot bidireccional con 15 comandos, autostart cross-platform) y **auditoría profunda Nemesis** (loop iterativo Feynman + State Inconsistency hasta convergencia) con 8 tools ejecutables JSON-output para code-profiler, pentest-scanner, dep-doctor, bundle-tracker y más (ADR-0018, v1.4.1).
+
+## Inventario
+
+| Componente | Cantidad |
+|-----------|----------|
+| Agentes SWL | 60 |
+| Habilidades | 160 (todas <=300 líneas, con divulgación progresiva a recursos/) |
+| Comandos (/swl:*) | 44 (todos <=300 líneas, delegan a skills) |
+| Reglas | 25 base + 40 por lenguaje (8 lenguajes x 5) |
+| Hooks | 41 + 66 librerías en hooks/lib/ |
+| Tools ejecutables (audit-tools) | 8 (code-profiler, pentest-scanner, dep-doctor, bundle-tracker, env-validator, migration-checker, canary-monitor, audit-history) |
+| Schemas | 15 |
+| Perfiles de instalación | 17 |
+| Contextos | 3 (dev, review, research) |
+| Gateway multi-plataforma | Telegram, Discord, WhatsApp, Slack, Email, Webhook (salida bidireccional opt-in) |
+
+## Lenguajes soportados (11)
+
+| Lenguaje | Reglas | Skills | Agente Revisor | Agente Implementador | Build Errors |
+|----------|--------|--------|----------------|---------------------|-------------|
+| Python | base | 7 | revisor-codigo-swl | backend-python-swl | build-errors-python |
+| TypeScript | base | 2 | revisor-codigo-swl | backend-node-swl | build-errors-typescript |
+| Java | 5 | 4 | revisor-java-swl | backend-java-swl | build-errors-java |
+| Go | 5 | 4 | revisor-go-swl | backend-go-swl | build-errors-go |
+| Rust | 5 | 4 | revisor-rust-swl | backend-rust-swl | build-errors-rust |
+| C#/.NET | 5 | 4 | revisor-csharp-swl | backend-csharp-swl | build-errors-csharp |
+| Kotlin | 5 | 4 | revisor-kotlin-swl | mobile-android-swl | build-errors-kotlin |
+| Swift | 5 | 4 | revisor-swift-swl | mobile-ios-swl | build-errors-swift |
+| PHP | 5 | 4 | revisor-php-swl | implementador-swl | build-errors-php |
+| Next.js | 5 | 4 | revisor-nextjs-swl | frontend-react-swl | build-errors-nextjs |
+| C++ | - | 1 | - | - | build-errors-cpp |
+
+## Instalación
+
+### Entender `init` vs `install`
+
+El setup requiere **dos comandos en orden**, con propósitos distintos:
+
+| Comando | Qué crea | Dónde | Instala agentes/skills |
+|---------|----------|-------|------------------------|
+| `npx @saulwade/swl-ses@latest init` | `.planning/` y `_userland/` (plantillas vacías) | En el proyecto actual | ❌ No |
+| `npx @saulwade/swl-ses@latest install` | Agentes, skills, reglas, hooks, comandos `/swl:*` | En `.claude/` del proyecto o en `~/.claude/` global | ✅ Sí |
+
+**`init` siempre es local al proyecto.** `install` puede ser local (`--local`, default) o global (`--global`).
+
+> Instalar globalmente (`--global` o `npm install -g swl-ses`) pone los componentes en `~/.claude/`
+> y los hace disponibles en todos tus proyectos. Aun así, cada proyecto necesita su propio `init`
+> para obtener `.planning/` y `_userland/`.
+
+### Opción 1: CLI vía npmjs (recomendada)
+
+```bash
+cd /ruta/a/tu/proyecto
+npx @saulwade/swl-ses@latest init                                       # Crea .planning/ y _userland/
+npx @saulwade/swl-ses@latest install --target claude --profile core     # Instala agentes, skills, hooks y reglas
+npx @saulwade/swl-ses@latest doctor                                     # Verifica que todo quedó correcto
+```
+
+No requiere autenticación. El paquete `swl-ses` está publicado en npmjs.
+
+#### Instalación global (una vez, disponible en todos los proyectos)
+
+```bash
+# Instalar swl-ses globalmente
+npm install -g swl-ses
+
+# En cada proyecto nuevo:
+cd /ruta/a/mi-proyecto
+swl-ses install --global --target claude --profile core  # Componentes en ~/.claude/ (una sola vez)
+swl-ses init                                             # Estructura .planning/ en este proyecto
+swl-ses doctor
+```
+
+### Opción 2: CLI vía GitHub Packages (mirror)
+
+```bash
+# Requiere autenticación con GitHub (ver INSTALACION.md)
+npx @saul-wade/swl-ses@latest init
+npx @saul-wade/swl-ses@latest install --target claude --profile core
+```
+
+Nota: la opción canónica es **npmjs.org** (`@saulwade/swl-ses`), GitHub Packages
+es un mirror para usuarios que prefieran ese registry. El binario y el contenido
+son idénticos.
+
+#### Por qué los scopes difieren
+
+La organización en npmjs.org se llama `saulwade` (sin guion) porque
+**npm no permite guiones en nombres de organización** — el registro
+los rechaza desde el formulario de creación. La organización en GitHub
+sí acepta guiones y se llama `saul-wade`. Como cada registry deriva el
+scope del paquete del nombre de la org propietaria, terminamos con
+`@saulwade/swl-ses` en npmjs y `@saul-wade/swl-ses` en GitHub Packages.
+El contenido publicado es idéntico; el comando CLI `swl-ses` no cambia.
+
+### Opción 3: Clonar y usar directamente
+
+```bash
+git clone https://github.com/saul-wade/swl-ses.git
+cd swl-ses
+claude
+# Claude lee CLAUDE.md y tiene acceso a todo el sistema
+```
+
+### Opción 4: Plugin de Claude Code
+
+```bash
+# Dentro de una sesion de Claude Code:
+/plugin marketplace add https://github.com/saul-wade/swl-ses
+/plugin install swl-ses@saul-wade
+```
+
+> Para forzar siempre la última versión:
+> `npx @saulwade/swl-ses@latest <comando>`
+
+## Comandos del CLI
+
+> Las tablas siguientes usan el alias corto `swl-ses@latest` (sin scope) por
+> compatibilidad con instalación global (`npm install -g swl-ses` enlaza el
+> bin con ese nombre). Para forzar el paquete canónico desde npmjs sin
+> tocar la instalación global, sustituir por `@saulwade/swl-ses@latest`
+> (npmjs canónico) o `@saul-wade/swl-ses@latest` (mirror GitHub Packages).
+
+| Comando | Descripción |
+|---------|-------------|
+| `npx @saulwade/swl-ses@latest init` | Crea `.planning/` (plantillas de planificación) y `_userland/` (tus personalizaciones) en el proyecto actual. **No instala agentes ni skills.** |
+| `npx @saulwade/swl-ses@latest install` | Instala agentes, skills, reglas, hooks y comandos `/swl:*` en el runtime destino (`.claude/` local o `~/.claude/` global). |
+| `npx @saulwade/swl-ses@latest doctor` | Diagnostica problemas de la instalación |
+| `npx @saulwade/swl-ses@latest update` | Actualiza componentes instalados |
+| `npx @saulwade/swl-ses@latest uninstall` | Desinstala componentes del runtime |
+| `npx @saulwade/swl-ses@latest info` | Muestra información del sistema instalado |
+| `npx @saulwade/swl-ses@latest skills list` | Lista skills instalados |
+| `npx @saulwade/swl-ses@latest skills add <fuente>` | Agrega skill desde repo Git, owner/repo, o path local |
+| `npx @saulwade/swl-ses@latest skills remove <nombre>` | Remueve un skill individual |
+| `npx @saulwade/swl-ses@latest agents list` | Lista agentes instalados |
+| `npx @saulwade/swl-ses@latest agents add <fuente>` | Agrega agente desde repo Git o path local |
+| `npx @saulwade/swl-ses@latest agents remove <nombre>` | Remueve un agente individual |
+
+### Opciones de install
+
+| Opción | Valores | Descripción |
+|--------|---------|-------------|
+| `--target <runtime>` | `claude`, `openclaude`, `copilot`, `opencode`, `codex`, `gemini` | Runtime destino (default: `claude`) |
+| `--profile <perfil>` | Ver perfiles abajo | Perfil de instalación (default: `core`) |
+| `--global` | — | Instala en directorio global (`~/.claude/`) |
+| `--local` | — | Instala en directorio local del proyecto (`.claude/`) |
+| `--with <componentes>` | Separados por coma | Incluir módulos adicionales |
+| `--without <componentes>` | Separados por coma | Excluir módulos |
+| `--dry-run` | — | Muestra plan sin aplicar cambios |
+| `--force` | — | Sobrescribe archivos existentes |
+
+### Perfiles de instalación
+
+| Perfil | Descripción |
+|--------|-------------|
+| `core` | Mínimo viable: orquestador + agentes base + reglas + comandos |
+| `backend-python` | FastAPI/Django + patrones + testing + async + API + datos |
+| `backend-node` | Express/Fastify/NestJS + TypeScript + API + datos |
+| `backend-java` | Spring Boot + Maven/Gradle + patrones Java + testing + API |
+| `backend-go` | Go + Gin/Echo + patrones Go + testing + API |
+| `backend-rust` | Rust + Axum/Actix + patrones Rust + testing + API |
+| `backend-csharp` | .NET + ASP.NET Core + patrones C# + testing + API |
+| `frontend-react` | React/Next.js + UX + estilos + accesibilidad |
+| `frontend-angular` | Angular v20+ + signals + UX + estilos |
+| `fullstack-python-angular` | Python backend + Angular frontend + datos + seguridad |
+| `fullstack-node-react` | Node.js backend + React frontend + datos + seguridad |
+| `fullstack-java-angular` | Java backend + Angular frontend + datos + seguridad |
+| `fullstack-go-react` | Go backend + React frontend + datos + seguridad |
+| `mobile` | Android + iOS + React Native/Flutter + UX |
+| `devops` | CI/CD + cloud + observabilidad + releases + seguridad |
+| `polyglot` | Todos los lenguajes: 11 lenguajes + revisores + build resolvers |
+| `completo` | Todo: 60 agentes + 162 habilidades + 44 comandos + 66 reglas + 41 hooks |
+
+### Targets soportados
+
+| Target | Runtime | Soporte | Componentes |
+|--------|---------|---------|-------------|
+| `claude` | Claude Code | Completo | Agentes, skills, comandos, reglas, hooks |
+| `openclaude` | OpenClaude | Completo | Agentes, skills, comandos, reglas, hooks |
+| `opencode` | OpenCode | Completo | Agentes, skills, comandos, reglas, hooks |
+| `gemini` | Gemini CLI | Completo | Agentes, skills, comandos, reglas, hooks |
+| `copilot` | GitHub Copilot | Parcial | Solo agentes y reglas (limitación de plataforma) |
+| `codex` | Codex CLI | Completo | Agentes en `~/.codex/agents/<name>.toml` (Sub-fase 11) + AGENTS.md con marcadores como índice + skills en `~/.agents/skills/<name>/SKILL.md` (path oficial OpenAI) + hooks en `~/.codex/hooks.json` (6 eventos) + MCP en `~/.codex/config.toml` con `--with-mcp` |
+| `cursor` | Cursor | Completo | Agentes en `.cursor/agents/<name>.md` (Subagents) + skills en `.cursor/skills/<name>/SKILL.md` + reglas en `.cursor/rules/*.mdc` + hooks en `.cursor/hooks.json` (17 eventos) + MCP en `.cursor/mcp.json` con `--with-mcp` |
+
+> **OpenClaude** usa los mismos directorios de proyecto que Claude Code (`.claude/`). Instalar `--target openclaude` en un proyecto con Claude Code aplica a ambos simultáneamente.
+
+### Ejemplos
+
+```bash
+# Perfil básico en Claude Code
+npx @saulwade/swl-ses@latest install --target claude --profile core
+
+# Backend Python en Gemini CLI
+npx @saulwade/swl-ses@latest install --target gemini --profile backend-python
+
+# Frontend React en GitHub Copilot
+npx @saulwade/swl-ses@latest install --target copilot --profile frontend-react
+
+# Full-stack en OpenClaude (multi-proveedor, usa .claude/ igual que Claude Code)
+npx @saulwade/swl-ses@latest install --target openclaude --profile fullstack-python-angular
+
+# Full-stack en OpenCode
+npx @saulwade/swl-ses@latest install --target opencode --profile fullstack-python-angular
+
+# Perfil completo en directorio global
+npx @saulwade/swl-ses@latest install --target claude --profile completo --global
+
+# Agregar skills desde GitHub con selector interactivo
+npx @saulwade/swl-ses@latest skills add anthropics/skills
+
+# Agregar un skill específico por nombre
+npx @saulwade/swl-ses@latest skills add anthropics/skills --skill docx
+
+# Agregar todos los skills de un repo sin selector
+npx @saulwade/swl-ses@latest skills add anthropics/skills --all
+
+# Agregar skill desde URL completa
+npx @saulwade/swl-ses@latest skills add https://github.com/user/repo --skill mi-skill
+
+# Agregar agente desde path local
+npx @saulwade/swl-ses@latest agents add ./mis-agentes --agent mi-agente
+
+# Ver que se instalaria sin hacer cambios
+npx @saulwade/swl-ses@latest install --target codex --profile core --dry-run
+
+# Ver información del sistema
+npx @saulwade/swl-ses@latest info --target claude
+```
+
+## Agentes (59)
+
+### Orquestación y Proceso
+`orquestador-swl`, `producto-prd-swl`, `consolidador-swl`, `auto-evolución-swl`
+
+### Discovery e Investigación
+`investigador-swl`, `investigador-ux-swl`
+
+### Arquitectura
+`arquitecto-swl`, `planificador-swl`
+
+### UX / UI / Diseño
+`ux-disenador-swl`, `disenador-ui-swl`, `accesibilidad-wcag-swl`
+
+### Frontend
+`frontend-swl`, `frontend-react-swl`, `frontend-angular-swl`, `frontend-css-swl`, `frontend-tailwind-swl`
+
+### Backend
+`implementador-swl`, `backend-python-swl`, `backend-node-swl`, `backend-api-swl`, `backend-workers-swl`
+
+### Backend Multi-Lenguaje (nuevo)
+`backend-java-swl`, `backend-go-swl`, `backend-csharp-swl`, `backend-rust-swl`
+
+### Mobile
+`mobile-android-swl`, `mobile-ios-swl`, `mobile-cross-swl`
+
+### Datos
+`datos-swl`, `migrador-swl`
+
+### Calidad
+`tdd-qa-swl`, `revisor-codigo-swl`, `revisor-seguridad-swl`
+
+### Revisores por Lenguaje (nuevo)
+`revisor-java-swl`, `revisor-go-swl`, `revisor-rust-swl`, `revisor-csharp-swl`, `revisor-kotlin-swl`, `revisor-swift-swl`, `revisor-php-swl`, `revisor-nextjs-swl`
+
+### Infraestructura
+`devops-ci-swl`, `cloud-infra-swl`, `observabilidad-swl`
+
+### Rendimiento y Releases
+`rendimiento-swl`, `release-manager-swl`
+
+### Documentación, Notificaciones, Debugging
+`documentador-swl`, `notificador-swl`, `depurador-swl`
+
+### Build Resolution
+`resolutor-build-swl`
+
+### LLM, Pagos y SRE
+`llm-apps-swl`, `pagos-swl`, `sre-swl`
+
+### Revisores adicionales
+`revisor-typescript-swl`, `revisor-react-swl`, `revisor-angular-swl`
+
+## Comandos (/swl:*)
+
+| Comando | Función |
+|---------|---------|
+| `/swl:instalar` | Instalación interactiva dentro de Claude Code |
+| `/swl:actualizar` | Actualizar sin desinstalar |
+| `/swl:nuevo-proyecto` | Inicializar proyecto con PROYECTO.md y roadmap |
+| `/swl:discutir-fase` | Recopilar contexto antes de planificar |
+| `/swl:planear-fase` | Crear PLAN.md con vertical slices |
+| `/swl:ejecutar-fase` | Ejecutar plan con commits atómicos |
+| `/swl:verificar` | Verificar implementación contra spec |
+| `/swl:mapear-codebase` | Analizar codebase existente |
+| `/swl:checkpoint` | Guardar estado para continuar después |
+| `/swl:compactar` | Reducir contexto preservando info clave |
+| `/swl:aprender` | Extraer aprendizajes de la sesión |
+| `/swl:evolucionar` | Auto-evolución de agentes/skills |
+| `/swl:autoresearch` | Loop de auto-mejora iterativa contra checklist |
+| `/swl:crear-skill` | Crear nuevo skill con guía interactiva |
+| `/swl:salud` | Diagnóstico de integridad del sistema |
+| `/swl:release` | Ciclo de release SemVer |
+| `/swl:auditar-deps` | Auditoría de dependencias (CVEs) |
+| `/swl:contexto` | Cambiar modo de desarrollo activo (dev/review/research) |
+| `/swl:sesiones` | Gestionar persistencia de sesiones de trabajo |
+| `/swl:instintos` | Inspeccionar y gestionar instintos del sistema |
+| `/swl:modelo` | Configurar modelo de IA por agente o globalmente |
+| `/swl:metricas` | Ver métricas de sesión y productividad |
+| `/swl:dashboard` | Dashboard histórico de uso multi-sesión (gráficas interactivas) |
+| `/swl:revisar-impacto` | Análisis de impacto estructural: blast radius, risk score, comunidades |
+| `/swl:evaluar-skill` | Evaluación formal de skills: 2 capas (estática + semántica), badges de calidad |
+| `/swl:wiki` | Gestionar wiki de conocimiento del proyecto (init/ingest/query/lint) |
+| `/swl:plugins` | Gestionar plugins y extensiones del sistema |
+| `/swl:revisar` | Revisión de código por tecnología |
+| `/swl:brainstorm` | Brainstorming estructurado |
+| `/swl:ayuda` | Ayuda interactiva: catálogo, detalle de comando, búsqueda por keyword |
+| `/swl:skill-search` | Buscar skills por keyword o dominio |
+| `/swl:mcp-status` | Estado de servidores MCP conectados |
+| `/swl:cron` | Gestionar tareas programadas |
+| `/swl:gateway` | Configurar gateway multi-plataforma + modo relay bidireccional Telegram → Claude |
+| `/swl:inbox` | Consumir comandos entrantes del gateway (enviados desde Telegram/Discord/webhook) |
+| `/swl:reflect-skills` | Analizar historial JSONL para detectar patrones candidatos a skill/comando emergente |
+| `/swl:contribuir` | Contribuir evoluciones al core (filtro dominio + PluginEval ≥80) |
+| `/swl:exportar-vault` | Exportar resumen de sesión al vault personal (Obsidian u otro) |
+
+Ver [COMANDOS.md](COMANDOS.md) para flags y opciones detalladas de cada comando.
+Ver [MANUAL_USO.md](MANUAL_USO.md) para explicaciones prácticas de cada comando y guías de cuándo usarlos.
+
+## Arquitectura
+
+### Thin Orchestrator
+
+```
+Comando (/swl:planear-fase)
+  +-> Cargar habilidad (planear-fase/SKILL.md)
+  +-> Spawn agente (planificador-swl) con contexto fresco
+  +-> Verificar resultado (revisor-codigo-swl)
+  +-> Actualizar estado (.planning/ESTADO.md)
+```
+
+### Estado en archivos (.planning/)
+
+```
+.planning/
+  PROYECTO.md          # Vision, contexto, objetivos
+  REQUISITOS.md     # Requisitos con IDs (REQ-001...)
+  HOJA-RUTA.md          # Fases con entregables y verificación
+  ESTADO.md            # Estado actual, decisiones, riesgos
+  CONTEXTO.md         # Modo de desarrollo activo
+  METRICAS.md         # Métricas de sesión
+  research/           # Investigación del dominio
+  fases/              # Documentos por fase (CONTEXTO, PLAN, RESUMEN, VERIFICACION)
+  sessions/           # Persistencia de sesiones JSON
+  comms/              # Comunicación entre agentes
+```
+
+### Arquitectura de 4 capas
+
+| Capa | Componente | Propósito |
+|------|-----------|-----------|
+| L1 | CLAUDE.md | Contexto persistente y reglas |
+| L2 | Skills | Paquetes de conocimiento versionados |
+| L3 | Hooks | Seguridad y automatización |
+| L4 | Agents | Subagentes con contexto aislado |
+
+## Gateway bidireccional con Telegram (opt-in)
+
+El sistema incluye un gateway que permite **enviar comandos a Claude desde Telegram** (u otro adaptador) y recibir respuestas sin necesidad de estar frente al teclado. Todo el flujo es opt-in y queda en audit trail.
+
+### Flujo
+
+```
+Telegram (móvil)  →  CommandRelay (valida)  →  .planning/inbox/cmd-*.json  →  /swl:inbox en Claude
+                                                                              o claude -p headless (auto)
+```
+
+### Protecciones del CommandRelay
+
+- Whitelist de usuarios por plataforma (`relay.platforms.<nombre>.allowedUsers`)
+- Rechazo de payload injection: `<script>`, `.env`, `id_rsa`, `.ssh/`, etc.
+- Límite de 4000 chars por mensaje
+- Rate limit: 10 msg/min por usuario (configurable)
+- Dedup por hash SHA-1 en ventana de 30s
+- Audit trail append-only en `.planning/inbox/audit.jsonl`
+
+### Modos de consumo
+
+| Modo | Qué hace | Compatible |
+|---|---|---|
+| Portable (default) | Los mensajes se encolan; al ejecutar `/swl:inbox` en tu sesión Claude los procesas con juicio humano | Windows / Linux / macOS |
+| Auto-exec headless | El bot invoca `claude -p --model haiku-4-5 --max-budget-usd 0.50 --allowedTools <solo-lectura>` en el cwd del proyecto y responde con el output | Windows / Linux / macOS |
+| tmux inject (opt-in) | Daemon `scripts/inbox-tmux-inject.js` inyecta a una sesión tmux con `tmux send-keys` | Linux / macOS |
+
+Configuración en `manifiestos/gateway-config.json`. Ver [MANUAL_USO.md](MANUAL_USO.md) sección `/swl:gateway` para setup completo.
+
+## Skills bundled de Claude Code
+
+Los agentes SWL pueden usar estos 17 skills que vienen con Claude Code:
+
+`/pdf`, `/pptx`, `/docx`, `/xlsx`, `/frontend-design`, `/web-artifacts-builder`,
+`/claude-api`, `/brand-guidelines`, `/skill-creator`, `/mcp-builder`,
+`/webapp-testing`, `/internal-comms`, `/doc-coauthoring`, `/canvas-design`,
+`/algorithmic-art`, `/theme-factory`, `/slack-gif-creator`
+
+## Modo _userland/
+
+Coloca tus agentes y habilidades personalizados en `_userland/`:
+
+```
+_userland/
+  agentes/
+    mi-agente-custom.md
+  habilidades/
+    mi-habilidad/
+      SKILL.md
+```
+
+El instalador detecta `_userland/`, hace merge con los componentes core y da prioridad a tus archivos.
+
+## Publicación
+
+El paquete se publica en dos registros (dual-publish):
+
+| Registro | Paquete | Requiere auth |
+|----------|---------|---------------|
+| npmjs.org (canónico) | `@saulwade/swl-ses` | Solo para publicar |
+| GitHub Packages (mirror) | `@saul-wade/swl-ses` | Para instalar y publicar |
+
+```bash
+# Publicar a ambos registros
+npm run publish:all
+
+# Solo GitHub Packages
+npm run publish:github
+
+# Solo npmjs
+npm run publish:npmjs
+
+# Simular sin publicar
+npm run publish:dry
+```
+
+Ver [INSTALACION.md](INSTALACION.md) para configuración detallada de autenticación y publicación.
+
+## Verificación (doctor)
+
+```bash
+npx @saulwade/swl-ses@latest doctor
+```
+
+Verifica: Node.js >= 22, runtimes detectados, `.planning/` completo, `_userland/` presente, estado íntegro, permisos, `.env` en `.gitignore`. Repara automáticamente hooks sin `"type": "command"` en settings.json.
+
+## Estructura del repositorio
+
+```
+swl-ses/
+  package.json              # Paquete npm con bin swl-ses
+  plugin.json               # Manifest para Claude Code plugin system
+  bin/swl-ses.js            # CLI principal
+  scripts/                  # Lógica del CLI
+    comandos/               # Handlers de subcomandos (skills, agents, info)
+    lib/                    # Librerías compartidas
+      transformadores/      # Transformadores por target (claude, copilot, opencode, codex, gemini)
+      detectar-runtime.js   # Detección de runtimes de IA
+      gestor-componentes.js # Gestión de skills y agentes individuales
+      resolver-externo.js   # Resolución de repos Git y paths locales
+      hooks-settings.js     # Registro de hooks en settings.json
+      estado.js             # Estado de instalación (v3)
+      manifiestos.js        # Resolución de perfiles/módulos
+      seguridad.js          # Validaciones de seguridad
+  manifiestos/              # Perfiles y módulos de instalación
+  agentes/                  # 60 agentes especializados
+  habilidades/              # 160 habilidades modulares
+  comandos/swl/             # 44 comandos slash
+  reglas/                   # 25 reglas base + 40 por lenguaje
+  hooks/                    # 41 hooks + 66 librerías en hooks/lib/
+  schemas/                  # 15 JSON Schemas
+  contextos/                # 3 modos de desarrollo
+  instintos/                # Instintos YAML con confianza
+  plantillas/               # Templates para .planning/
+  gateway/                  # Gateway multi-plataforma (adapters + CommandRelay)
+    adapters/               # Telegram, Discord, Slack, WhatsApp, Email, Webhook
+    command-relay.js        # Receptor bidireccional con whitelist + validaciones
+  _userland/                # Personalización del usuario
+  CLAUDE.md                 # Fuente de verdad del sistema
+  COMANDOS.md               # Referencia completa de comandos
+  MANUAL_USO.md             # Guía práctica de uso por comando
+  INSTALACION.md            # Guía de configuración y publicación
+```
+
+## ¿Por qué usar SWL? (Análisis y Ejemplo Práctico)
+
+El Sistema SWL transforma la manera tradicional de interactuar con la IA (prompts aislados y pérdida de contexto) en un flujo de **Ingeniería de Software Estructurada**. 
+
+### Beneficios Principales
+
+1. **Estado Persistente y Cero Pérdida de Contexto:** El directorio `.planning/` mantiene documentado el producto (`PROYECTO.md`), los requerimientos (`REQUISITOS.md`) y el roadmap de desarrollo. La IA siempre sabrá en qué fase está el proyecto.
+2. **Especialización (Agentes expertizados):** Delega las tareas a agentes especializados integrados (ej. `arquitecto-swl`, `frontend-react-swl`, `revisor-seguridad-swl`) en lugar de usar comandos genéricos.
+3. **Desarrollo Metódico:** Fuerza un flujo de trabajo estructurado de *Planificar -> Ejecutar -> Verificar*.
+4. **Comandos Simplificados (`/swl:*`):** Automatiza flujos de trabajo masivos de desarrollo (ej. `/swl:planear-fase` o `/swl:auditar-deps`).
+5. **Personalización Absoluta:** El directorio `_userland/` permite inyectar plantillas, redefinir instintos de la IA y crear Habilidades (Skills) específicas para la lógica de negocio.
+
+### Ejemplo de Flujo de Trabajo Real
+
+Un proyecto típico (ej. construir una App Fullstack) usando SWL sigue estos pasos:
+
+1. **Instalación y Setup inicial**
+   ```bash
+   npx @saulwade/swl-ses@latest init
+   npx @saulwade/swl-ses@latest install --target claude --profile fullstack-node-react
+   ```
+
+2. **Definición del Proyecto (Discovery)**
+   Usa el comando `/swl:nuevo-proyecto` para estructurar la idea. El agente `producto-prd-swl` genera, tras hacerte un par de preguntas clave, los archivos `PROYECTO.md`, `REQUISITOS.md` y un `HOJA-RUTA.md` dividido en fases lógicas (Ej. Fase 1: Setup, Fase 2: Auth).
+
+3. **Planeación de la Arquitectura**
+   Usa `/swl:planear-fase Fase 2`. El agente `planificador-swl` investigará tu código y creará un `PLAN.md` que detalla los archivos a crear, dependencias a instalar y plan de pruebas. Todo documentado para tu revisión antes de escribir código.
+
+4. **Ejecución de la Fase**
+   Apruebas el plan y ejecutas `/swl:ejecutar-fase`. Los agentes de programación (ej. `backend-node-swl` y `frontend-react-swl`) implementan el código según el plan mediante commits "atómicos" que garantizan un desarrollo seguro.
+
+5. **Revisión y Verificación**
+   Finalizas con `/swl:verificar`. El agente `revisor-codigo-swl` audita el nuevo código bajo reglas estrictas (Seguridad, Clean Code, patrones específicos) y comprueba que cumpla con los requisitos iniciales.
+
+Con SWL, pasas de ser un "programador asistido por IA" a convertirte en el **Gerente de Ingeniería** de un equipo de IA altamente coordinado.
+
+## Desarrollo
+
+### Tests
+
+```bash
+npm test              # tests unitarios con node:test nativo
+npm run test:validate # Validación estructural del paquete
+npm run test:all      # Ambos
+```
+
+### CI/CD
+
+El repositorio incluye GitHub Actions (`.github/workflows/ci.yml`) que ejecuta automáticamente en push/PR a main: sintaxis de hooks, validación estructural, tests unitarios y consistencia de versiones.
+
+Los mismos workflows son distribuibles a cualquier proyecto usuario vía `/swl:configurar-ci init`: revisión de seguridad con Claude en cada PR (`swl-security.yml`), CI genérico Node 22+24 (`swl-ci.yml`) y releases automáticos desde conventional commits (`release-please.yml`). Instalación opt-in, no afecta al repo destino sin consentimiento explícito.
+
+### Herramientas de mantenimiento
+
+```bash
+npm run generate:docs  # Regenera INVENTARIO.md y SALUD.md desde el disco
+npm run field-report   # Reporte de uso real de skills y agentes
+```
+
+## Licencia
+
 MIT