# CLAUDE.md — swl-software-engineering-system v5.13.1

## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)

### Idioma obligatorio: español de México
Todo contenido generado DEBE ser en español de México: respuestas, código comentado, mensajes de commit, descripciones de PR, documentación y comunicación con el usuario. Usar ortografía correcta con acentos, signos de puntuación y gramática normativa. Evitar anglicismos innecesarios y traducciones literales del inglés. Esta regla tiene prioridad sobre cualquier otra instrucción de idioma.

### Uso obligatorio del sistema SWL
Toda tarea DEBE usar el sistema SWL completo: agentes especializados, habilidades, hooks y comandos `/swl:*`. NO hacer trabajo directo que un agente SWL especializado haría mejor. Para tareas complejas: `orquestador-swl`. Para implementación: `implementador-swl` o el agente de stack. Para debugging: `depurador-swl`. Para revisión: `revisor-codigo-swl`. Para planificación: `planificador-swl`. Cargar skills con `Skill("nombre")` antes de implementar.

### Investigar antes de editar
Investigar el codebase ANTES de editar. NUNCA modificar código que no se ha leído primero. Leer el archivo completo, entender el contexto, y solo entonces hacer cambios.

### Lectura de documentos Office y Jupyter
Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls`, `.pptx` o `.ipynb`, NUNCA uses el Read tool directamente (no soporta esos formatos). Usa:
```bash
python scripts/vendor/markitdown/cli.py <ruta-al-archivo>
```
El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.md`, `.txt` y código fuente. Para más opciones y casos de uso consultar `Skill("swl-markitdown")`.

---

## Qué es este repositorio

Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
11 lenguajes, 5 runtimes, 59 agentes, 150 skills, 41 comandos, 60 reglas, 37 hooks.
**Idioma**: 100% español (México) para componentes SWL y skills Anthropic en inglés.

## Estructura del repositorio

```
agentes/       habilidades/    comandos/swl/   contextos/      instintos/
reglas/        hooks/          schemas/        manifiestos/    plantillas/
scripts/       bin/            _userland/      .claude/        .planning/
```

## Flujos de trabajo

**Feature completa**: orquestador → discovery → PRD → arquitectura → plan → implementación (paralelo) → calidad (paralelo) → cierre
**Fases GSD**: discutir → planear → ejecutar → verificar
**Frontend**: investigador-ux → disenador-ui → accesibilidad → frontend-* → rendimiento
**Backend**: backend-api → backend-python/node → backend-workers → datos
**Mobile**: producto-prd → mobile-cross (decisión) → mobile-android/ios → tdd-qa

## Comandos del sistema (/swl:*)

| Comando | Propósito |
|---------|-----------|
| `/swl:nuevo-proyecto` | Iniciar proyecto nuevo desde cero con entrevista |
| `/swl:adoptar-proyecto` | Incorporar proyecto existente: análisis automático + entrevista corta → 9 archivos |
| `/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:checkpoint` | Guardar estado para continuar después |
| `/swl:compactar` | Reducir contexto preservando información clave |
| `/swl:aprender` | Extraer aprendizajes de la sesión |
| `/swl:evolucionar` | Auto-evolución de agentes/skills |
| `/swl:autoresearch` | Loop de auto-mejora iterativa de skills |
| `/swl:salud` | Diagnóstico de integridad del sistema |
| `/swl:release` | Ciclo de release SemVer |
| `/swl:revisar` | Revisión de código por tecnología |
| `/swl:brainstorm` | Brainstorming estructurado |
| `/swl:metricas` | Ver métricas de sesión (tokens, costo) |
| `/swl:modelo` | Consultar/forzar modelo (haiku/sonnet/opus) |
| `/swl:contexto` | Cambiar modo: dev/review/research |
| `/swl:sesiones` | Historial y retoma de sesiones |
| `/swl:instintos` | Gestionar instintos YAML |
| `/swl:plugins` | Gestionar plugins de _userland/ |
| `/swl:instalar` | Instalar SWL desde Claude Code |
| `/swl:actualizar` | Actualizar SWL a última versión |
| `/swl:auditar-deps` | Auditoría de dependencias (CVEs) |
| `/swl:mapear-codebase` | Analizar codebase existente → ARQUITECTURA.md + STACK.md + TRAMPAS.md |
| `/swl:crear-skill` | Crear nuevo skill con guía interactiva |
| `/swl:gateway` | Configurar gateway multi-plataforma |
| `/swl:cron` | Gestionar tareas programadas |
| `/swl:revisar-impacto` | Análisis de impacto estructural con code-review-graph (blast radius, risk score, comunidades) |
| `/swl:wiki` | Gestionar wiki de conocimiento del proyecto (init/ingest/query/lint) — patrón Karpathy |
| `/swl:inbox` | Consumir comandos entrantes del gateway (Telegram/Discord/webhook) encolados por CommandRelay |
| `/swl:reflect-skills` | Analizar historial JSONL para detectar intenciones repetidas candidatas a skill/comando emergente |
| `/swl:evaluar-skill` | Evaluar calidad de un skill con PluginEval (2 capas, badge) |
| `/swl:dashboard` | Dashboard interactivo del sistema |
| `/swl:mcp-status` | Estado de servidores MCP conectados |
| `/swl:notificaciones` | Gestionar notificaciones Telegram opt-in: init, status, disable, bot daemon |
| `/swl:skill-search` | Buscar skills por keyword o dominio |
| `/swl:contribuir` | Contribuir evoluciones de _userland/ al core vía PR (filtro dominio + PluginEval ≥80) |
| `/swl:ayuda` | Ayuda interactiva: catálogo, detalle de comando, búsqueda por keyword |

## Reglas obligatorias (20 base + 40 por lenguaje)

| Regla | Carga cuando |
|-------|-------------|
| `brevedad-output.md` | Siempre — idioma español, uso obligatorio de SWL y eficiencia de tokens |
| `seguridad.md` | *.py, *.ts, auth/, Dockerfile |
| `estilo-codigo.md` | *.py, *.ts, *.js, *.css |
| `pruebas.md` | *.py, *.ts, test*/, *.spec.* |
| `arquitectura.md` | Cambios estructurales |
| `git-workflow.md` | Siempre |
| `performance.md` | *.py, *.ts, *.sql |
| `docs.md` | *.md, docs/, README |
| `accesibilidad.md` | *.html, *.tsx, *.component.* |
| `cloud-infra.md` | *.tf, terraform/, k8s/, docker* |
| `api-diseno.md` | api/, routes/, endpoints/ |
| `skills-estandar.md` | habilidades/, skills/, SKILL.md |
| `seguridad-agentes.md` | Agentes autónomos, MCP, delegación, permisos |
| `gobernanza.md` | Proyectos con múltiples contribuidores |
| `hooks.md` | hooks/, *.hook.js |
| `markitdown.md` | Lectura de archivos Office/Jupyter |
| `patrones.md` | Patrones de diseño y arquitectura |
| `testing.md` | test*/, *.test.*, *.spec.* |

Reglas por lenguaje (5 por lenguaje × 8 lenguajes): Java, Go, Rust, C#, Kotlin, Swift, PHP, Next.js — en `reglas/` con subdirectorios.

## Estrategia de modelos por nivel de criticidad (Model-Tier)

Asignar el modelo correcto a cada agente según la criticidad e irreversibilidad de la tarea.
Esta tabla es **obligatoria** al crear o actualizar agentes. El objetivo es reducir costos
un 40–60% sin comprometer calidad en tareas que no lo requieren.

| Nivel | Modelo | Campo en frontmatter | Agentes SWL | Criterio de asignación |
|-------|--------|---------------------|-------------|------------------------|
| **Crítico** | `claude-opus-4-7` | `model: claude-opus-4-7` | orquestador-swl, arquitecto-swl, revisor-seguridad-swl, producto-prd-swl | Decisiones irreversibles: arquitectura, seguridad, PRD. El error tiene alto costo de corrección |
| **Estándar** | `claude-sonnet-4-6` | `model: claude-sonnet-4-6` | backend-*-swl, frontend-*-swl, mobile-*-swl, tdd-qa-swl, revisores de lenguaje | Implementación y revisión. Balance óptimo costo/calidad para la mayoría de tareas |
| **Ligero** | `claude-haiku-4-5-20251001` | `model: claude-haiku-4-5-20251001` | notificador-swl, resolutor-build-swl (búsquedas simples) | Operaciones deterministas rápidas: notificaciones, búsquedas, formateo, transformaciones |
| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El agente padre decide el modelo según el contexto |

### Reglas de asignación

- Si la tarea toca **decisiones de diseño no reversibles** → Opus obligatorio
- Si la tarea es **implementación o revisión de código** → Sonnet por defecto
- Si la tarea es **búsqueda, formateo o notificación** → Haiku
- Si un agente Sonnet necesita análisis crítico eventual → definir `modeloAlterno: claude-opus-4-7`
- **NUNCA** usar Opus para tareas que Sonnet puede resolver igual de bien (búsquedas, lecturas, notificaciones)

### Justificación

Opus 4.7 supera a 4.6 en ~3× en resolución de tareas de producción de coding
y 98.5% vs 54.5% en agudeza visual. Mismo precio por token que 4.6 ($5/$25 por M tokens).
El tokenizer de 4.7 produce 1.0–1.35× más tokens para el mismo contenido, por lo que
los umbrales de compactación y los presupuestos de contexto se han recalibrado en `compactacion-contexto` y `context-builder`.

Opus 4.7 cuesta ~5× más que Sonnet por token. Usar Opus en tareas que no lo requieren
desperdicia entre 300–500% de presupuesto sin mejora observable en el resultado final.

### Workflow de delegación (Opus 4.7)

Opus 4.7 rinde mejor tratado como **ingeniero al que se delega** que como pair programmer
al que se guía línea por línea. Implicaciones para agentes SWL:

- **Orquestadores y planificadores**: entregar spec completa al delegar (intent +
  constraints + acceptance criteria + file locations). Evitar microgestión turn-by-turn.
- **Sub-agentes en paralelo**: Opus 4.7 usa menos sub-agentes por defecto. Si una
  tarea requiere paralelismo, especificarlo en el prompt de forma explícita.
- **Instrucciones literales**: 4.7 sigue instrucciones con menos inferencia que 4.6.
  Los prompts ambiguos se ejecutan al pie de la letra — eliminar ambigüedades.
- **Effort levels nativos** (`high | xhigh | max`): el skill `control-profundidad`
  queda deprecated en favor del control de esfuerzo nativo de Claude Code.

---

## Convenciones

- Nombres en **kebab-case**. Agentes SWL en español, GSD en inglés.
- Skills se cargan vía `Skill("nombre")`, nunca leyendo AGENTS.md directamente.
- Score mínimo de calidad: **9.0/10** para aprobar trabajo.
- Modos de desarrollo: `dev`, `review`, `research` (vía `/swl:contexto`).
- `respositorios-git/` y `temp/` son material de referencia — no modificar ni commitear.
- Inventario completo de agentes, skills, hooks y métricas: ver `INVENTARIO.md` o `.planning/ESTADO.md`.
- Los mensajes de commit generados automáticamente siempre deben estar en español.
- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas.
- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()`/`atomicWriteJSON()` de `hooks/lib/atomic-write.js`.
- **Preservación de datos en actualización**: `.planning/sessions/`, `.planning/comms/`, `_userland/`, `instintos/proyecto.yaml`, `APRENDIZAJES.md` NUNCA se sobreescriben.
- **Documentación obligatoria**: toda funcionalidad nueva DEBE documentarse en MANUAL_USO.md, COMANDOS.md, CLAUDE.md y README.md ANTES del commit.
- **Limpieza de registros resueltos**: no dejar items completados en listas de pendientes.
- **Directorios excluidos de verificación de console.log**: `scripts/`, `bin/`, `hooks/`, `gateway/`.
- **Variables de entorno opt-in para integraciones enterprise**: hooks con exportación externa (OTLP, webhooks) usan el patrón `if (!process.env.VAR) return` — zero-config por defecto, activos solo cuando la variable está configurada. Nunca requerir configuración para funcionamiento básico. Variables opt-in conocidas: `SWL_GUARDRAIL_MODELO=1` (activa `hooks/guardrail-modelo.js` para observación de degradación de modelo), `SWL_AUDIT_SKILLS=1` (activa `scripts/audit-skills.sh` para auditoría de skills vía snyk-agent-scan), `SWL_AUDIT_FRAMEWORKS=1` (activa `scripts/auditar-cobertura-frameworks.js` en `/swl:salud` paso 5c para reportar cobertura de NIST CSF/AI RMF/MITRE ATLAS/ATT&CK/D3FEND), `SWL_AUDIT_AGENTES=1` (activa `scripts/auditar-agentes-gaps.js` en `/swl:salud` paso 5d para reportar gaps SAP-Agents en los 59 agentes), `SWL_MC_URL` (URL base de Mission Control, ej. `http://localhost:3000` — activa integración opt-in con el dashboard externo, ver `/swl:dashboard`), `SWL_MC_TOKEN` (API key de Mission Control cuando `SWL_MC_URL` está definida), `SWL_AIISMS_GATE=1` (activa gate en `scripts/verificar-release.js` que corre detector Python de AI-isms contra CHANGELOG.md y RELEASE_NOTES.md, bloquea el release si p0_count > 0), `SWL_AIISMS_HOOK=0` (desactiva `hooks/aiisms-detector.js` que se dispara en PostToolUse sobre Write/Edit/MultiEdit de archivos .md y emite nudge si hay AI-ism P0; activo por defecto cuando Python 3.10+ está disponible), `SWL_REPAIR_LOOP_THRESHOLD` (default `3`; umbral de nudges drift-detectado no accionados del mismo par `(metrica, agente)` en ventana de 14 días tras el cual `scripts/lib/drift-detector.js` marca el nudge como `banned: true` para prevenir saturación de `nudges.jsonl`; patrón adaptado de evolver GEP), `SWL_SUGERIR_REGEN_INVENTARIO=0` (silencia `hooks/sugerir-regenerar-inventario.js` que en PostToolUse Write/Edit/MultiEdit sugiere regenerar `INVENTARIO.md` cuando el agente toca `agentes/`, `habilidades/`, `comandos/swl/`, `hooks/` o `reglas/`; activo por defecto con cooldown de 30 min por carpeta).
- **Criterio de dominio para incorporar skills de proyectos usuario**: una habilidad generada en un proyecto swl-ses solo se incorpora al core si su dominio es **ingeniería de software general** (SDLC, backend, frontend, QA, DevOps, seguridad). Skills de dominios externos (ML Ops, Data Science, finanzas, bio-informática, etc.) se descartan aunque estén bien escritas. Pregunta de filtro: *¿le sirve esto a un ingeniero de software en cualquier proyecto de software?*
- **Filtro primario al analizar repos en `temp/`**: antes de evaluar arquitectura o patrones, verificar **compatibilidad de dominio** con ingeniería de software general. Si el dominio es incompatible (ML productivo, ciencia de datos, dominio vertical específico), veredicto NINGUNA aplicabilidad sin análisis adicional.
- **JSONL para eventos de alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe el archivo completo. Reservar `atomicWriteJSON` para archivos de estado mutable.
- **`skillsInvocables` en formato CSV estricto**: el campo `skillsInvocables` en frontmatter de agentes DEBE ser CSV puro en una sola línea (ej: `skillsInvocables: skill-a, skill-b, skill-c`). NUNCA mezclar formato lista YAML (`- item`) con CSV. Cada valor debe ser un nombre de skill existente en `habilidades/` — nunca nombres de agentes ni skills inexistentes. Verificar con `ls habilidades/ | grep nombre` antes de agregar.
- **Precedencia de capas del sistema**: Reglas base (`reglas/`) → Reglas por lenguaje (`reglas/{lang}/`) → Skills (`habilidades/`) → Instintos (`instintos/`). Cada capa puede especializar pero NUNCA contradecir las capas superiores. Si hay conflicto, la capa más general (regla base) prevalece. Los instintos solo aplican dentro de su scope (proyecto/dominio/global) y nunca sobreescriben reglas ni skills.
- **Privilegio mínimo de agentes**: un agente delegado NUNCA excede los permisos declarados en su propio frontmatter (`permisosRed`, `permisosEscritura`, `permisosComandos`, `tools`). La cadena de delegación no escala privilegios: si el agente padre tiene `nivelRiesgo: ALTO` y delega a un agente `BAJO`, el hijo opera con sus restricciones propias. Ver `reglas/seguridad-agentes.md`.
- **Dependencias externas educativas se marcan como opt-in NO-dependencia**: cuando se documenta un recurso externo de tipo educativo/formativo (guías, MCPs de documentación, plantillas comunitarias como `cc.bruniaux.com`, indexadores externos como GitNexus) en MANUAL_USO.md sección Dependencias externas, marcar explícitamente **"NO es dependencia técnica de swl-ses"** y advertir si sus componentes (slash commands, agentes, hooks) no están coordinados con los del sistema SWL. El sistema debe seguir funcionando sin ese recurso — si un recurso se vuelve necesario para un flujo, deja de ser educativo y requiere ADR. Aplica también a MCPs opcionales, librerías opt-in y herramientas de terceros referenciadas en docs.
- **Patrón obligatorio "validar antes de invocar" para dependencias externas opt-in**: cualquier invocación desde un comando, skill o hook de swl-ses a una herramienta externa opt-in (markitdown, MinerU, gh, gitnexus, mineru-open-api, etc.) **DEBE** verificar primero si está disponible (`command -v <bin>` en Bash, `execSync('<bin> --version', { stdio: 'ignore' })` en Node) y, si no lo está, **continuar con el flujo nativo de SWL sin emitir error al usuario**. Una falla en la dependencia externa nunca debe romper el flujo principal. Para verificación silenciosa, usar `2>/dev/null` o `try/catch`. Este patrón aplica a todos los wrappers en `scripts/vendor/` y a cualquier invocación cross-tool en hooks. Sin este check, el sistema deja de cumplir con su contrato "opt-in NO-dependencia".
- **Siempre usar `@latest` en invocaciones `npx`**: todo mensaje impreso por installer, hook de check-update, scripts de inicialización y documentación que sugiera ejecutar el CLI debe usar `npx swl-ses@latest <comando>`, nunca `npx swl-ses <comando>` desnudo. Sin `@latest`, npx cachea la primera versión encontrada por máquina y la reutiliza indefinidamente; tras publicar una nueva versión, los usuarios existentes siguen corriendo la vieja sin saberlo. Regla cubre: `scripts/instalador.js`, `hooks/check-update.js`, `scripts/check-update.js`, `scripts/inicializar.js`, README, MANUAL_USO, COMANDOS, INSTALACION.

## Mapa de propagación de cambios

Al modificar un componente del sistema, verificar TODOS los archivos afectados. Un cambio incompleto causa desincronización.

| Tipo de cambio | Archivos a verificar |
|----------------|---------------------|
| **Agente nuevo o modificado** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `AGENTS.md`, `SALUD.md`, `.planning/REPORTE-GRAFO.md` |
| **Skill nuevo o modificado** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `CLAUDE.md` (tabla de skills por dominio) |
| **Hook nuevo o modificado** | `plugin.json`, `.claude/settings.json`, `manifiestos/hooks-config.json` (event+matcher), `manifiestos/modulos.json` (ruta archivo), `INVENTARIO.md`, `SALUD.md`. **AMBOS manifiestos son obligatorios**: sin `hooks-config.json` el hook no se registra en settings.json del destino, sin `modulos.json` el instalador no lo copia. `scripts/validar-manifest.js` bloquea el CI si falta cualquiera. |
| **Comando nuevo o modificado** | `COMANDOS.md`, `CLAUDE.md` (tabla de comandos), `INVENTARIO.md` |
| **Regla nueva o modificada** | `CLAUDE.md` (tabla de reglas), `INVENTARIO.md`, `SALUD.md` |
| **Schema nuevo o modificado** | `INVENTARIO.md`, `SALUD.md` |
| **Bump de versión** | 15+ ubicaciones en 14 archivos — ver checklist en `/swl:release` paso 6 |
| **Frontmatter de agente (`skillsInvocables`)** | `manifiestos/modulos.json`, `.planning/REPORTE-GRAFO.md` (re-generar grafo) |

Esta tabla es obligatoria. Omitir un archivo causa fallos en `/swl:salud` y desincronización del grafo de dependencias.

### Regla obligatoria: regenerar inventario, nunca contar a mano

Antes de modificar contadores de agentes, skills, comandos, reglas o hooks en CLAUDE.md, README.md, SALUD.md, AGENTS.md, package.json o plugin.json, ejecutar SIEMPRE:

```bash
node scripts/generar-inventario.js
```

Motivo: en v5.11.1 estimé "28 hooks" visualmente y propagué el error a 5 archivos; el conteo real (regenerado) era 30. Contar manualmente no es fuente de verdad — el script que recorre los directorios sí lo es. Aplica a cualquier proyecto SWL, no solo al sistema.

### Regla: modelo por defecto para auto-ejecución headless

Cuando un script o bot externo invoca `claude -p` sin intervención humana, usar por defecto:

```bash
claude -p \
  --model claude-haiku-4-5-20251001 \
  --effort low \
  --max-budget-usd 0.50 \
  --dangerously-skip-permissions \
  --allowedTools "Read Grep Glob Bash(git status:*) ..." \
  "<mensaje>"
```

Haiku 4.5 cuesta 5× menos que Sonnet/Opus y cubre consultas headless típicas (status, log, lecturas, resúmenes). El primer invoke por cwd cuesta ~$0.15 por cache warmup del CLAUDE.md + reglas; invocaciones subsiguientes dentro de 5min son $0.001-0.05. Con Opus el warmup sube a ~$0.90 por invocación — reservar Opus solo para auto-exec que requiera razonamiento profundo.

### Decisión de arquitectura: file-based queue sobre PTY injection

Para control remoto de Claude desde canales externos (Telegram, Discord), el patrón adoptado en v5.11.1 es **file-based inbox** (`gateway/command-relay.js` escribe a `.planning/inbox/cmd-*.json`, consumidor `/swl:inbox` o `claude -p` headless) en lugar de PTY injection (AppleScript macOS / tmux send-keys Linux). Razones:

- Portable Windows/Linux/macOS con un solo mecanismo
- Auditable por archivo con audit trail en `.planning/inbox/audit.jsonl`
- Compatible con HITL (humano decide si ejecutar), ortogonal a la validación del CommandRelay
- Tmux queda como modo opt-in avanzado vía `scripts/inbox-tmux-inject.js` solo Linux/macOS