# swl-ses v1.7.3

> 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), **auditoría profunda Nemesis** (loop iterativo Feynman + State Inconsistency hasta convergencia, ahora con loop evaluator-optimizer opt-in vía `/swl:nemesis --remediar` desde v1.5.2 - ADR-0021) con 8 tools ejecutables JSON-output para code-profiler, pentest-scanner, dep-doctor, bundle-tracker y más (ADR-0018, v1.4.1), e **instalador/actualizador TUI custom** zero-deps con paneles, multi-select y barra de progreso por categoría (v1.6.0).

## 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/`.

### Modo recomendado: TUI visual (v1.6.0+)

Desde v1.6.0, al ejecutar `install` o `update` sin flags desde una terminal
interactiva, swl-ses lanza un **TUI custom** con paneles, selectores con
flechas, multi-select con espacio y barra de progreso por categoría.

```bash
# Lanza el TUI: Welcome → Menú → Wizard → Progreso → Resumen
npx -y @saulwade/swl-ses@latest install
npx -y @saulwade/swl-ses@latest update
```

Opt-out con `--no-tui` para usar el asistido lineal clásico, o pasa cualquier
flag (`--target`, `--profile`, `--force`, etc.) y el CLI usa el flujo directo
sin prompts. Ver [`MANUAL_USO.md`](./MANUAL_USO.md) sección "Opción C — Modo
TUI visual" para capturas ASCII de cada pantalla.

### 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: 61 agentes + 178 habilidades + 44 comandos + 71 reglas + 43 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/                   # 28 reglas base + 40 por lenguaje
  hooks/                    # 43 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