swl-ses v2.9.0

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++.

Autoevolución programada

Una instalación global registra los proyectos durante el uso y programa un worker diario del sistema operativo. Fase A madura instintos y drena feedback; Fase B convierte señales con evidencia y observaciones abiertas de task-observer en propuestas estructuradas mediante Claude CLI sin tools, MCP ni sesión persistente. Un hub personal local lleva propuestas sanitizadas de downstream al repo madre sin copiar código, prompts, respuestas o rutas absolutas.

Las propuestas LOW sobre skills, agentes o comandos existentes se pueden materializar en un worktree detached y validar npm run test:all dentro de Docker sin red, con límites de recursos y canario de instalación fresca. El sistema no hace merge, push, tag, instalación ni publicación: esas fronteras siguen bajo autorización humana. El canario Docker es de preintegración y no se presenta como quórum de campo. Detalles operativos: MANUAL_USO.md § 15.

SWL reconoce siete targets de instalación de IA. La disponibilidad de un transformador no certifica conformidad con el harness; los estados públicos se derivan del manifiesto canónico. Incluye instalación multi-target, el servidor swl-mcp-server (stdio, solo lectura, SDK oficial v2) y el cliente swl-mcp-client para diagnosticar y consultar la configuración registrada en cada runtime.

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 notificaciones Telegram opt-in para Claude Code y Codex (hooks salientes, bot bidireccional con 15 comandos y 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 | 61 | | Habilidades | 182 (todas <=300 líneas, con divulgación progresiva a recursos/) | | Comandos (/swl:*) | 48 (todos <=300 líneas, delegan a skills) | | Reglas | 39 base + 40 por lenguaje (8 lenguajes x 5) | | Hooks | 55 distribuidos + 87 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 | 60 | | Perfiles de instalación | 17 | | Contextos | 3 (dev, review, research) | | Gateway multi-plataforma | Telegram, Discord, WhatsApp, Slack, Email, Webhook (salida bidireccional opt-in) |

Harness IR diagnóstico

Desde v2.7.0, SWL compila sus 429 agentes, comandos, habilidades, reglas y hooks a una vista intermedia neutral. El artefacto manifiestos/harness-ir.json conserva procedencia SHA-256 y diagnósticos bloqueantes; no convierte el contenido legacy en capacidades consumibles ni certifica runtimes.

node scripts/generar-harness-ir.js --check  # Detecta ausencia o drift sin escribir
node scripts/generar-harness-ir.js --write  # Publicación atómica con fsync y CAS

La API productiva expone sólo compilación, serialización y validación del contrato. El CLI rechaza overrides de raíz, fuentes o mappings para mantener el corpus confinado al repositorio Git actual.

Entrega de subagentes y Agent Teams

SWL no trata idle como sinónimo de “reporte entregado”. Los subagentes clásicos de Claude, Codex, Cursor y Copilot usan sus eventos documentados de inicio y cierre; en Claude Code Agent Teams el evento correcto es TeammateIdle, no SubagentStop. Antes de permitir que un teammate quede idle, el hook SWL:

1. captura el reporte sustantivo desde su transcript_path;
2. comprueba un SendMessage exitoso hacia team-lead posterior al reporte;
3. devuelve exit 2 hasta dos veces si falta la entrega;
4. conserva el resultado en .planning/comms/reportes-subagentes.jsonl para que el coordinador pueda contar entregas y recuperar cualquier faltante.

El ledger registra invocado en SubagentStart, terminado en SubagentStop y correlaciona ambos por sesión + agent_id. Si el transcript tiene metadata, también conserva nombre, rol, spawnDepth y el contenedor del workflow para contar subagentes anidados. Un Stop del coordinador sin identidad ni transcript se omite: ya no produce filas agente:null que aparentan terminaciones.

El gate sólo se registra en Claude Code, que expone TeammateIdle. Codex, Cursor y Copilot mantienen sus ciclos nativos; no se les proyecta un evento que sus contratos no ofrecen. Gemini/OpenClaude registran el resultado observable de la herramienta de delegación y OpenCode el idle de cada sesión hija.

Kernel de políticas W2

El paquete 2.8.0 distribuye 13 módulos zero-deps para identidad, contexto, approvals, evidencia, ledger, gates G0-G4, autorización fail-closed y migración legacy. También incluye cuatro schemas cerrados, manifiestos/policy-bundle.json y el corpus público de 500 vectores manifiestos/policy-corpus-w2.json.

Estos artefactos son una API interna para proyectos downstream: viajan en el tarball, pero los perfiles no los copian como hooks ni los presentan como integración de un runtime. W3 conectará operaciones nativas de Claude, Codex y Gemini; W6 ligará cada grant al efecto real mediante sandbox, fencing y rollback. Por ello, W2 no certifica conformidad de ningún runtime y todos conservan estado público unverified.

Frontera oficial de mutation testing

Una campaña de mutación se inicia por una sola puerta: swl-ses mutacion ejecutar --solicitud=<archivo> --stack=<stack>. El coordinador resuelve la policy anclada, reserva presupuesto, consume una approval de un solo uso cuando hay ampliación, aísla el sandbox y hace el único spawn permitido. Ni el skill ni el agente QA lanzan el runner: preparan la solicitud y leen el resultado.

Correr el binario a mano sigue siendo posible para el operador local, pero esa corrida no emite recibo y el gate G4 no tiene qué leer. El contrato fija un target por campaña y un presupuesto agotado se reporta como inconcluso-sin-score, nunca como éxito. Procedimiento completo en docs/runbooks/mutation-testing.md.

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 -y @saulwade/swl-ses@latest init | .planning/ y _userland/ (plantillas vacías) | En el proyecto actual | ❌ No | | npx -y @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 -y @saulwade/swl-ses@latest init                                       # Crea .planning/ y _userland/
npx -y @saulwade/swl-ses@latest install --target claude --profile core     # Instala agentes, skills, hooks y reglas
npx -y @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)

# Converger CLI global y componentes globales en una sola transacción
npx -y @saulwade/swl-ses@latest install --global --target claude --profile core --force

# En cada proyecto nuevo:
cd /ruta/a/mi-proyecto
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 -y @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 -y @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 -y @saulwade/swl-ses@latest install | Instala agentes, skills, reglas, hooks y comandos /swl:* en el runtime destino (.claude/ local o ~/.claude/ global). | | npx -y @saulwade/swl-ses@latest doctor | Diagnostica problemas de la instalación | | npx -y @saulwade/swl-ses@latest update | Actualiza componentes instalados | | npx -y @saulwade/swl-ses@latest uninstall | Desinstala componentes del runtime | | npx -y @saulwade/swl-ses@latest info | Muestra información del sistema instalado | | npx -y @saulwade/swl-ses@latest skills list | Lista skills instalados | | npx -y @saulwade/swl-ses@latest skills add <fuente> | Agrega skill desde repo Git, owner/repo, o path local | | npx -y @saulwade/swl-ses@latest skills remove <nombre> | Remueve un skill individual | | npx -y @saulwade/swl-ses@latest agents list | Lista agentes instalados | | npx -y @saulwade/swl-ses@latest agents add <fuente> | Agrega agente desde repo Git o path local | | npx -y @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: completo) | | --global | — | Instala componentes globales y, si hay efectos, converge la CLI swl-ses con los bytes exactos del paquete invocado en la misma transacción. | | --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 administrados sin evolución local. Para agentes, skills, comandos y reglas evolucionados, usa la base registrada para un merge de tres vías: integra cambios disjuntos; ante solapamiento conserva el original y falla cerrado con backup y recibo de conflicto. Los componentes pre-evolucionados de fábrica que el usuario no tocó sí se actualizan, con backup previo. | | --phase-authority <archivo> | JSON de identidades | En el salto a 2.8.5, inicializa la autoridad explícita necesaria si el proyecto conserva una fase activa legacy. | | --confirm-phase-authority | — | Confirmación HITL para congelar la allowlist exacta del lock legacy durante install/update. |

Instalación global transaccional: CLI y componentes (ADR-0095)

install --global con efectos ya no trata la CLI y los componentes como dos operaciones independientes. Antes de tocar un runtime, empaqueta la fuente exacta que ejecutó el usuario, calcula su integridad, valida el npm bundled de Node, usa configuración neutral, desactiva lifecycle scripts y registra un journal por prefix. Después inicia esa CLI validada para instalar los componentes. Así npx ...@latest, npx github:...#main y un tarball local no se sustituyen entre sí sólo por compartir el mismo SemVer.

# Un solo comando converge la CLI global y los componentes globales
npx -y @saulwade/swl-ses@latest install --global --profile completo --force

--dry-run y install --local no actualizan la CLI ni crean journal. Las combinaciones --local --global y --solo-hooks --global se rechazan antes de consultar npm o escribir archivos. El instalador rechaza una fuente invocada inferior a la CLI global existente, conforme al orden SemVer completo (incluidos los pre-release).

Si una interrupción deja un journal pendiente, vuelve a ejecutar el mismo install --global: primero intentará recuperarlo. Si informa recovery-required, conserva el journal en el almacén de estado del sistema operativo (%LOCALAPPDATA%\\swl-ses\\transacciones\\cli-global\\ en Windows; ${XDG_STATE_HOME:-~/.local/state}/swl-ses/transacciones/cli-global/ en POSIX) para diagnóstico; no borres el journal ni ejecutes una desinstalación concurrente. Corrige la causa de npm/Node y repite el comando. Si un lock conserva un PID aparentemente vivo por más de 15 minutos, la recuperación es manual: no se libera ni revierte automáticamente porque el PID podría haberse reutilizado.

Cada install y update deja además un registro JSONL durable, portable y redactado. doctor muestra la última operación, distingue un fallo de instalación de la ausencia del binario de un runtime y avisa si una ejecución quedó iniciada sin cierre. Las rutas predeterminadas son %LOCALAPPDATA%\swl-ses\logs\installations.jsonl en Windows y ${XDG_STATE_HOME:-~/.local/state}/swl-ses/logs/installations.jsonl en POSIX. Consulta el runbook del registro de instalaciones para inspección, rotación y códigos estables.

Cierre transaccional de fases (2.8.5)

El primer cierre en cada equipo requiere identidades explícitas y distintas para operador, ejecutor y verificador. SWL no las inventa a partir del nombre del rol:

swl-ses autoridad-fase bootstrap \
  --principal-id=operator:saul --subject=usuario:saul --agent-node-id=wisclap \
  --executor-principal-id=agent:executor --executor-subject=agente:executor \
  --executor-agent-node-id=executor-wisclap \
  --verifier-principal-id=agent:verifier --verifier-subject=agente:verifier \
  --verifier-agent-node-id=verifier-wisclap --confirmar

Después de /swl:verificar, el artefacto JSON de G4 debe contener los vínculos exactos REQ × T × commit × test × evidencia. attest-g4 captura y firma el HEAD actual y un manifiesto SHA-256 canónico de todos los archivos tracked y no ignorados del worktree, salvo el ledger criptográfico y el review que la propia firma actualiza. Cualquier commit, edición staged/tracked o archivo nuevo posterior obliga a verificar y atestar de nuevo antes del cierre. Los blobs de sparse checkout se leen desde el índice y los submódulos se aceptan sólo si su HEAD coincide con el gitlink y están limpios. Se firma y se cierra así:

swl-ses autoridad-fase attest-g4 --fase=49 --evidencia=.planning/evidence/g4-f49.json --confirmar
swl-ses cerrar-fase --fase=49 --json

Para actualizar a 2.8.5 un proyecto que ya tenía fase-activa.json, ejecuta la actualización desde la raíz del proyecto. Si aún no existe autoridad, pasa un JSON con principal y rolePrincipals usando la misma forma del bootstrap:

npx -y @saulwade/[email protected] update --force \
  --phase-authority=.planning/phase-authority.json --confirm-phase-authority

La migración es acumulativa: también se ejecuta si un equipo salta directamente de una versión anterior a 2.8.5 hacia una posterior. El instalador congela una sola vez el lock exacto que existía al actualizar; un lock posterior no entra automáticamente en esa allowlist. Las llaves privadas permanecen fuera del repositorio en el almacén de estado del usuario: %LOCALAPPDATA%\\swl-ses\\authority en Windows, ~/Library/Application Support/swl-ses/authority en macOS y ${XDG_STATE_HOME:-~/.local/state}/swl-ses/authority en Linux. SWL_AUTHORITY_HOME puede sustituirlo por una ruta absoluta controlada por el operador.

No borres ~/.swl-ses para reparar la autoridad: una instalación global de algunos runtimes puede usar ese archivo como manifiesto. El bootstrap usa el almacén de estado del sistema precisamente para evitar esa colisión.

El bootstrap público 2.8.5 crea una autoridad standalone reutilizable por todos los workspaces del equipo: un workspace posterior adopta esa misma autoridad local y recibe un stream propio, sin crear otra raíz. La adopción de un kernel ajeno inyectado se rechaza antes de persistir metadata: ese kernel no expone los firmantes delegados de principal y evidencia que necesita el cierre, por lo que declararlo “adoptado” produciría una autoridad imposible de reabrir. Ésta es la distinción normativa de REQ-49-16: adopción local soportada; dependencia externa inoperable, fail-closed.

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 + 182 habilidades + 48 comandos + 79 reglas + 55 hooks |

Conformidad de runtimes

Estado bootstrap: disponibilidad de instalación no equivale a certificación del harness.

| Runtime | Target | Soporte público | Certificación | |---|---|---|---| | claude-code | claude | experimental | unverified | | openclaude | openclaude | experimental | unverified | | opencode | opencode | experimental | unverified | | gemini-cli | gemini | experimental | unverified | | cursor | cursor | experimental | unverified | | codex-cli | codex | experimental | unverified | | github-copilot | copilot | experimental | unverified |

Capacidades de instalación por target

| Target | Runtime | Artefactos emitidos | |---|---|---| | claude | Claude Code | Agentes, skills, comandos, reglas y hooks | | openclaude | OpenClaude | Agentes, skills, comandos, reglas y captura filtrada de delegación en .openclaude/ | | opencode | OpenCode | Agentes, skills, comandos, reglas y plugin de captura de sesiones hijas | | gemini | Gemini CLI | Agentes, skills, comandos, reglas y configuración | | cursor | Cursor | Agentes, skills, comandos nativos, reglas, hooks y configuración MCP | | codex | Codex CLI | Agentes TOML, AGENTS.md, skills, hooks y configuración MCP | | copilot | GitHub Copilot | Agentes, reglas consolidadas y hook subagentStop |

OpenClaude no comparte la configuración de Claude Code: SWL usa ~/.openclaude/settings.json y .openclaude/settings.json, además de un adaptador filtrado de PostToolUse. La certificación conductual permanece pendiente; consulta la auditoría de hooks.

Ejemplos

# Perfil básico en Claude Code
npx -y @saulwade/swl-ses@latest install --target claude --profile core

# Backend Python en Gemini CLI
npx -y @saulwade/swl-ses@latest install --target gemini --profile backend-python

# Frontend React en GitHub Copilot
npx -y @saulwade/swl-ses@latest install --target copilot --profile frontend-react

# OpenClaude: no instalar aún — requiere migrar la adaptación a su configuración propia

# Full-stack en OpenCode
npx -y @saulwade/swl-ses@latest install --target opencode --profile fullstack-python-angular

# Perfil completo en directorio global
npx -y @saulwade/swl-ses@latest install --target claude --profile completo --global

# Agregar skills desde GitHub con selector interactivo
npx -y @saulwade/swl-ses@latest skills add anthropics/skills

# Agregar un skill específico por nombre
npx -y @saulwade/swl-ses@latest skills add anthropics/skills --skill docx

# Agregar todos los skills de un repo sin selector
npx -y @saulwade/swl-ses@latest skills add anthropics/skills --all

# Agregar skill desde URL completa
npx -y @saulwade/swl-ses@latest skills add https://github.com/user/repo --skill mi-skill

# Agregar agente desde path local
npx -y @saulwade/swl-ses@latest agents add ./mis-agentes --agent mi-agente

# Ver que se instalaria sin hacer cambios
npx -y @saulwade/swl-ses@latest install --target codex --profile core --dry-run

# Ver información del sistema
npx -y @saulwade/swl-ses@latest info --target claude

Agentes (61)

Orquestación y Proceso

orquestador-swl, producto-prd-swl, consolidador-swl, auto-evolución-swl, abogado-diablo-swl

Discovery e Investigación

investigador-swl, investigador-ux-swl

Arquitectura

arquitecto-swl, planificador-swl

UX / UI / Diseño

investigador-ux-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 y sellar el paquete factual antes de planificar | | /swl:planear-fase | Crear PLAN.md con vertical slices y validación determinista | | /swl:ejecutar-fase | Ejecutar, verificar y cerrar el plan con recibo transaccional | | /swl:verificar | Verificar implementación contra spec | | /swl:seguridad | Postura de seguridad del proyecto completo (secretos, deps, OWASP, pipeline) | | /swl:fix | Triage y despacho unificado de reparaciones (bug/build/CI/hallazgos) | | /swl:predecir | Panel predictivo pre-implementación; --abogado-diablo critica la decisión | | /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:status 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:status metricas | Ver métricas de sesión y productividad | | /swl:status 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 -y @saulwade/swl-ses@latest doctor

Verifica: Node.js >= 22, runtimes detectados, .planning/ completo, _userland/ presente, estado íntegro, permisos, .env en .gitignore y la última operación registrada de install/update. Repara automáticamente hooks sin "type": "command" en settings.json. Un runtime missing significa que su CLI no está disponible en PATH; no invalida por sí solo una copia de artefactos que el instalador haya escrito correctamente.

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/                  # 61 agentes especializados
  habilidades/              # 182 habilidades modulares
  comandos/swl/             # 48 comandos slash
  reglas/                   # 37 reglas base + 40 por lenguaje
  hooks/                    # 55 hooks distribuidos + 87 librerías en hooks/lib/
  schemas/                  # 60 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 -y @saulwade/swl-ses@latest init
   npx -y @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. Contexto factual y planeación de la arquitectura Usa primero /swl:discutir-fase Fase 2 para verificar y sellar las premisas materiales. Después, /swl:planear-fase Fase 2 crea un PLAN.md con archivos, dependencias y pruebas, y ejecuta sus validaciones deterministas. Si el PLAN cambia, se revisa el delta antes de firmarlo.

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), releases automáticos desde conventional commits (release-please.yml) y gates devsecops opt-in — gitleaks + auditoría de dependencias (swl-devsecops.yml, flag --with-devsecops). 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
swl-ses field-report   # Reporte de campo sobre el outbox local del proyecto

Licencia

MIT