swl-ses v1.7.4

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.

# 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 sección "Opción C — Modo TUI visual" para capturas ASCII de cada pantalla.

Opción 1: CLI vía npmjs (recomendada)

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)

# 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)

# 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

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

# 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

# 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 para flags y opciones detalladas de cada comando. Ver 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 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 |

# 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 para configuración detallada de autenticación y publicación.

Verificación (doctor)

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

   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

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

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