swl-ses 3.3.2

package/CLAUDE.md

@@ -0,0 +1,425 @@
+# CLAUDE.md — swl-software-engineering-system v3.0
+
+Este archivo guía a Claude Code cuando trabaja en este repositorio.
+
+## Qué es este repositorio
+
+Es un **sistema de ingeniería de software auto-evolutivo** que cubre el SDLC completo — no un proyecto de software tradicional. Contiene definiciones de agentes, módulos de conocimiento (habilidades/skills), comandos, reglas y hooks que extienden las capacidades de Claude Code. Integra lo mejor de Everything Claude Code (aprendizaje continuo, validación CI, hooks inteligentes) y GSD (thin orchestrator, fases explícitas, estado persistido, anti-context-rot).
+
+**Idioma**: 100% español (México) para componentes SWL. Los componentes GSD y skills de Anthropic se mantienen en inglés.
+
+## Estructura del repositorio
+
+```
+agentes/            # 37 agentes SWL (markdown con frontmatter YAML)
+habilidades/        # 62 habilidades en español (directorios con SKILL.md)
+comandos/swl/       # 17 comandos del sistema (/swl:*)
+reglas/             # 11 reglas obligatorias
+hooks/              # 6 hooks JavaScript (pre/post ejecución)
+manifiestos/        # modulos.json, perfiles.json, hooks-config.json
+plantillas/         # Templates para PROJECT.md, ROADMAP.md, etc.
+scripts/            # CLI (swl-ses) y librerías de instalación
+bin/                # Entrypoint CLI (swl-ses.js)
+_userland/          # Extensiones del usuario (agentes y habilidades custom)
+.claude/            # Settings locales de Claude Code
+.planning/          # Estado del sistema (STATE.md)
+```
+
+## Sistema de Agentes SWL (37 agentes)
+
+### Agentes por dominio
+
+**Orquestación y Proceso** (4):
+- `orquestador-swl` — Coordinador central, thin orchestrator
+- `producto-prd-swl` — Product Requirements Documents
+- `consolidador-swl` — Actualiza CLAUDE.md y memoria al cerrar sesión
+- `auto-evolucion-swl` — Mejora agentes y skills, versionado SemVer
+
+**Discovery e Investigación** (2):
+- `investigador-swl` — Investigación técnica y de dominio
+- `investigador-ux-swl` — Investigación de usuarios, personas, journeys
+
+**Arquitectura y Diseño** (2):
+- `arquitecto-swl` — ADRs, módulos profundos, tradeoffs
+- `planificador-swl` — PLAN.md con vertical slices
+
+**UX / UI / Diseño** (3):
+- `ux-disenador-swl` — UX + UI general
+- `disenador-ui-swl` — Capa visual: tokens, tipografía, color, componentes
+- `accesibilidad-wcag-swl` — Auditoría WCAG 2.1 AA / 2.2
+
+**Frontend** (5):
+- `frontend-swl` — Implementador frontend generalista
+- `frontend-react-swl` — React + Next.js especialista
+- `frontend-angular-swl` — Angular v20+ con signals
+- `frontend-css-swl` — CSS moderno (Container Queries, Layers, Nesting)
+- `frontend-tailwind-swl` — Tailwind CSS v4 y design systems
+
+**Backend** (4):
+- `backend-python-swl` — Python backend avanzado (FastAPI, Django, SQLAlchemy)
+- `backend-node-swl` — Node.js/TypeScript (Express, Fastify, NestJS)
+- `backend-api-swl` — Diseño de APIs (REST, GraphQL, gRPC, WebSocket)
+- `backend-workers-swl` — Background jobs, queues, event processing
+
+**Mobile** (3):
+- `mobile-android-swl` — Android nativo (Kotlin, Jetpack Compose)
+- `mobile-ios-swl` — iOS nativo (Swift, SwiftUI)
+- `mobile-cross-swl` — React Native + Flutter
+
+**Datos** (2):
+- `datos-swl` — Ingeniería de datos, ETL, data quality
+- `migrador-swl` — Migraciones de BD y datos
+
+**Implementación General** (1):
+- `implementador-swl` — Implementador full-stack generalista
+
+**Calidad** (3):
+- `tdd-qa-swl` — TDD y cobertura de tests
+- `revisor-codigo-swl` — Code review
+- `revisor-seguridad-swl` — Auditoría OWASP, CVSSv3
+
+**Infraestructura y Operaciones** (3):
+- `devops-ci-swl` — CI/CD pipelines
+- `cloud-infra-swl` — Arquitectura cloud (AWS, Azure, GCP)
+- `observabilidad-swl` — Monitoring, alertas, SLOs
+
+**Rendimiento y Releases** (2):
+- `rendimiento-swl` — Profiling, caching, load testing
+- `release-manager-swl` — SemVer, changelog, rollbacks
+
+**Documentación y Comunicación** (2):
+- `documentador-swl` — Documentación viva
+- `notificador-swl` — Notificaciones multicanal (Telegram, WhatsApp, email, webhooks)
+
+**Debugging** (1):
+- `depurador-swl` — Debugging sistemático
+
+### Formato de archivo de agente (v3.0)
+
+```yaml
+---
+name: nombre-agente-swl
+description: Cuándo invocar y cuándo NO (activación proactiva)
+tools: Read, Write, Edit, Bash, Grep, Glob, Skill, Agent
+model: claude-sonnet-4-6
+modeloAlterno: claude-haiku-4-5-20251001
+ventanaContexto: 200k
+permissionMode: plan | acceptEdits | bypassPermissions
+color: green
+version: 1.0.0
+nivelRiesgo: BAJO | MEDIO | ALTO
+skillsInvocables: skill-1, skill-2
+skillsRestringidos: skill-x
+permisosRed: true | false
+permisosEscritura: true | false
+permisosComandos: true | false
+---
+```
+
+### Flujos de trabajo principales
+
+**Feature completa con PRD (orquestado)**:
+```
+orquestador-swl
+  → investigador-swl + investigador-ux-swl (discovery)
+  → producto-prd-swl (PRD.md)
+  → arquitecto-swl (ADR)
+  → disenador-ui-swl (UI-SPEC.md, si hay frontend)
+  → planificador-swl (PLAN.md)
+  → [paralelo] backend-python-swl + frontend-react-swl (o angular/mobile)
+  → [paralelo] tdd-qa-swl + revisor-codigo-swl + revisor-seguridad-swl + accesibilidad-wcag-swl
+  → [paralelo] documentador-swl + release-manager-swl
+  → consolidador-swl (actualiza CLAUDE.md + memoria)
+  → notificador-swl (notifica finalización)
+```
+
+**Pipeline frontend especializado**:
+```
+investigador-ux-swl (research)
+  → disenador-ui-swl (design tokens, UI-SPEC.md)
+  → accesibilidad-wcag-swl (validación pre-implementación)
+  → frontend-react-swl / frontend-angular-swl (implementación)
+  → frontend-css-swl / frontend-tailwind-swl (estilos)
+  → rendimiento-swl (Core Web Vitals)
+```
+
+**Pipeline mobile**:
+```
+producto-prd-swl (PRD.md)
+  → mobile-cross-swl (decisión: RN vs Flutter vs nativo)
+  → mobile-android-swl + mobile-ios-swl (implementación paralela)
+  → tdd-qa-swl (testing)
+```
+
+**Pipeline backend**:
+```
+backend-api-swl (diseño de API)
+  → backend-python-swl / backend-node-swl (implementación)
+  → backend-workers-swl (jobs asíncronos)
+  → datos-swl (pipelines de datos)
+```
+
+### Equipos de agentes (paralelización real)
+
+| Equipo | Líder | Miembros paralelos | Cuándo |
+|--------|-------|-------------------|--------|
+| Discovery | investigador-swl | investigador-ux-swl, producto-prd-swl | Proyecto nuevo |
+| Arquitectura | arquitecto-swl | rendimiento-swl, revisor-seguridad-swl | Decisión de diseño |
+| Frontend | frontend-swl | frontend-react-swl, frontend-css-swl, frontend-tailwind-swl | Feature UI compleja |
+| Backend | backend-python-swl | backend-api-swl, backend-workers-swl | Feature backend compleja |
+| Mobile | mobile-cross-swl | mobile-android-swl, mobile-ios-swl | Feature mobile |
+| Calidad | tdd-qa-swl | revisor-codigo-swl, revisor-seguridad-swl, accesibilidad-wcag-swl, rendimiento-swl | Pre-release |
+| Operaciones | devops-ci-swl | cloud-infra-swl, observabilidad-swl | Deploy, infra |
+| Cierre | consolidador-swl | documentador-swl, release-manager-swl, notificador-swl | Fase completada |
+
+Los miembros se lanzan en **paralelo real** (múltiples `Agent()` en un solo mensaje).
+
+## Sistema de habilidades (61 en español + 40 en inglés)
+
+### Estándar oficial de skills (regla: `skills-estandar.md`)
+
+Toda skill sigue el estándar oficial de Claude Agent Skills con 3 niveles de carga:
+
+```
+nombre-skill/
+├── SKILL.md              # OBLIGATORIO — Nivel 2 (instrucciones, ≤300 líneas)
+├── scripts/              # OPCIONAL — Nivel 3 (lógica ejecutable)
+└── recursos/             # OPCIONAL — Nivel 3 (plantillas, ejemplos, docs)
+```
+
+**Frontmatter obligatorio**: `name` (≤64 chars, kebab-case) + `description` (≤1024 chars, QUÉ + CUÁNDO)
+**Paths relativos**: Toda referencia dentro de SKILL.md usa paths relativos al directorio de la skill
+
+### Habilidades con scripts/ o recursos/
+
+| Habilidad | scripts/ | recursos/ |
+|-----------|----------|-----------|
+| validacion-ci-sistema | `validar-sistema.sh` | — |
+| release-semver | `generar-changelog.sh` | — |
+| checklist-calidad | — | `quality-report-template.md` |
+| checkpoints-verificacion | — | `checkpoint-templates.md` |
+| notificaciones-multicanal | — | `config-template.json` |
+| api-rest-diseno | — | `openapi-template.yaml` |
+| contenedores-docker | — | `dockerfile-template.dockerfile` |
+| ci-cd-pipelines | — | `github-actions-template.yaml` |
+| estructura-proyecto-claude | — | `claude-md-template.md`, `mcp-json-template.json`, `variantes-por-stack.md`, `frontmatter-y-hooks-referencia.md` |
+| autoresearch | `calcular-score.js` | `checklist-template.md` |
+
+### Cobertura por dominio
+
+| Dominio | Habilidades |
+|---------|------------|
+| **Backend Python** | fastapi-experto, django-experto, patrones-python, async-python, auth-patrones, manejo-errores |
+| **Backend Node** | node-experto |
+| **Frontend Core** | angular-moderno, angular-avanzado, frontend-avanzado, typescript-avanzado |
+| **Frontend Styling** | css-moderno, tailwind-experto, diseno-responsivo |
+| **Frontend React** | react-experto, react-optimizacion |
+| **Mobile** | mobile-react-native, mobile-flutter |
+| **UX/Diseño** | ux-diseno, accesibilidad-a11y, design-tokens, wireframes-flujos |
+| **Datos** | postgresql-experto, sql-optimizacion, datos-etl |
+| **Infraestructura** | cloud-aws, contenedores-docker, kubernetes-orquestacion, ci-cd-pipelines |
+| **Seguridad** | checklist-seguridad, threat-model-lite, iam-secretos |
+| **Observabilidad** | monitoring-alertas, performance-baseline |
+| **Arquitectura** | api-rest-diseno, microservicios, event-driven, deprecacion-migracion |
+| **Calidad** | checklist-calidad, tdd-workflow, testing-python, validacion-ci-sistema |
+| **Notificaciones** | notificaciones-multicanal, checkpoints-verificacion |
+| **Aprendizaje** | aprendizaje-continuo, extractor-de-aprendizajes, auto-evolucion-protocolo, autoresearch |
+| **Estructura** | estructura-proyecto-claude, workflow-claude-code |
+| **Proceso** | nuevo-proyecto, instalar-sistema, planear-fase, ejecutar-fase, discutir-fase, verificar-trabajo, mapear-codebase, compactacion-contexto, git-worktrees-paralelo, release-semver, doc-sync, dependencias-auditoria |
+
+## Comandos del sistema (/swl:*)
+
+| Comando | Propósito |
+|---------|-----------|
+| `/swl:instalar` | Instalar SWL desde dentro de Claude Code (interactivo) |
+| `/swl:actualizar` | Actualizar SWL a la última versión sin desinstalar |
+| `/swl:nuevo-proyecto` | Iniciar proyecto con PROJECT.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 información clave |
+| `/swl:aprender` | Extraer aprendizajes de la sesión |
+| `/swl:evolucionar` | Auto-evolución de agentes/skills |
+| `/swl:salud` | Diagnóstico de integridad del sistema |
+| `/swl:release` | Ciclo de release SemVer |
+| `/swl:auditar-deps` | Auditoría de dependencias (CVEs, outdated) |
+| `/swl:crear-skill` | Crear nuevo skill con guía interactiva |
+| `/swl:autoresearch` | Loop de auto-mejora iterativa de skills (Karpathy) |
+
+## Sistema de notificaciones
+
+El `notificador-swl` envía notificaciones multicanal cuando eventos importantes ocurren:
+
+| Evento | Prioridad | Canal por defecto |
+|--------|-----------|------------------|
+| Intervención humana requerida | CRITICA | Todos los canales activos |
+| Verificación fallida (score < 9.0) | ALTA | Telegram + Desktop |
+| Fase completada | MEDIA | Desktop |
+| Riesgo alto detectado | ALTA | Telegram + Email |
+| Tarea larga completada | MEDIA | Desktop |
+| Error de API | ALTA | Webhook |
+
+Canales soportados: Desktop nativo, Telegram, WhatsApp, Email, Webhooks genéricos (Slack, Discord, ntfy.sh, Teams).
+
+Integración con `claude-notifications-go` (en `respositorios-git/`).
+
+## Skills bundled de Claude Code (disponibles sin instalación)
+
+Claude Code incluye 17 skills predefinidos que TODOS los agentes pueden usar:
+
+| Skill | Propósito | Agentes que deben usarlo |
+|-------|-----------|-------------------------|
+| `/pdf` | Leer, crear, combinar, dividir PDFs | documentador-swl, producto-prd-swl, release-manager-swl |
+| `/pptx` | Crear presentaciones PowerPoint | producto-prd-swl, documentador-swl |
+| `/docx` | Crear documentos Word | documentador-swl, producto-prd-swl |
+| `/xlsx` | Analizar hojas de cálculo Excel | datos-swl, documentador-swl |
+| `/frontend-design` | Interfaces frontend de alta calidad | disenador-ui-swl, frontend-swl, frontend-react-swl, frontend-angular-swl |
+| `/web-artifacts-builder` | Componentes web complejos (React+shadcn) | frontend-react-swl, disenador-ui-swl |
+| `/claude-api` | Desarrollar con la API de Claude/Anthropic SDK | backend-python-swl, backend-node-swl, backend-api-swl |
+| `/brand-guidelines` | Aplicar guías de marca Anthropic | disenador-ui-swl, frontend-css-swl |
+| `/skill-creator` | Crear nuevos skills para Claude Code | auto-evolucion-swl |
+| `/mcp-builder` | Construir servidores MCP | backend-node-swl, backend-python-swl |
+| `/webapp-testing` | Testing de aplicaciones web | tdd-qa-swl, frontend-swl |
+| `/internal-comms` | Comunicaciones internas | documentador-swl, notificador-swl |
+| `/doc-coauthoring` | Co-escribir documentos | documentador-swl |
+| `/canvas-design` | Diseño en canvas HTML | disenador-ui-swl |
+| `/algorithmic-art` | Arte algorítmico/generativo | disenador-ui-swl |
+| `/theme-factory` | Crear temas y design systems | frontend-tailwind-swl, frontend-css-swl |
+| `/slack-gif-creator` | Crear GIFs para Slack | notificador-swl |
+
+**Regla**: Los agentes listados en la columna "Agentes que deben usarlo" DEBEN considerar estos skills cuando sean relevantes para la tarea. No son opcionales — son herramientas disponibles que deben aprovecharse.
+
+## Patrones integrados de ECC y GSD
+
+### De Everything Claude Code (integrados)
+- **Aprendizaje continuo v2**: Instintos con confianza, scope proyecto/global (`aprendizaje-continuo` skill)
+- **Validación CI**: 7 capas de validación de integridad (`validacion-ci-sistema` skill)
+- **Checkpoints**: human-verify, decision, human-action (`checkpoints-verificacion` skill)
+- **Activación proactiva**: Cada agente declara cuándo activarse sin prompt del usuario
+- **Anti-context-rot**: Contextos frescos por subagente, presupuesto de contexto
+
+### De GSD (integrados)
+- **Thin orchestrator**: `orquestador-swl` coordina sin implementar
+- **Fases explícitas**: discutir → planear → ejecutar → verificar
+- **Estado persistido**: `.planning/STATE.md` como fuente de verdad
+- **Commits atómicos**: Por tarea, bisectables, independientemente revertibles
+- **Trazabilidad**: CONTEXT.md → PLAN.md → SUMMARY.md → VERIFICATION.md
+
+## Reglas obligatorias (11)
+
+| Regla | Aplica a |
+|-------|---------|
+| `seguridad.md` | Código que toque datos o autenticación |
+| `estilo-codigo.md` | Todo código Python y TypeScript |
+| `pruebas.md` | Todo código nuevo o modificado |
+| `arquitectura.md` | Cambios estructurales o nuevos módulos |
+| `git-workflow.md` | Todos los commits y branches |
+| `performance.md` | Código en rutas críticas |
+| `docs.md` | APIs públicas y componentes compartidos |
+| `accesibilidad.md` | Todo frontend y mobile |
+| `cloud-infra.md` | Infraestructura y deployment |
+| `api-diseno.md` | Diseño de APIs REST/GraphQL/gRPC |
+| `skills-estandar.md` | Creación y estructura de skills (estándar oficial) |
+
+## Hooks activos (6)
+
+| Hook | Tipo | Propósito |
+|------|------|-----------|
+| `escaneo-secretos.js` | PreToolUse | Bloquea commits con secretos |
+| `linea-estado.js` | PostToolUse | Estado del sistema en terminal |
+| `monitor-contexto.js` | PostToolUse | Alerta contexto saturado |
+| `proteccion-rutas.js` | PreToolUse | Protege archivos críticos |
+| `calidad-pre-commit.js` | PreToolUse | Calidad mínima pre-commit |
+| `extraccion-aprendizajes.js` | PostToolUse | Captura aprendizajes automáticamente |
+
+## Protocolo de auto-evolución
+
+1. **Observación**: Hooks capturan 100% de actividad de sesión (patrón ECC v2)
+2. **Extracción**: `extraccion-aprendizajes.js` detecta insights automáticamente
+3. **Clasificación**: anti-patrón, patrón positivo, gotcha, decisión
+4. **Instintos**: Creación con confianza 0.3-0.9, scope proyecto/global (patrón ECC)
+5. **Incorporación**: `auto-evolucion-swl` propone cambios a agentes/skills
+6. **Autoresearch**: Loop medible de mutación atómica contra checklists por skill
+7. **Consolidación**: `consolidador-swl` actualiza CLAUDE.md del proyecto
+7. **Versionado**: SemVer (MAJOR.MINOR.PATCH) con CHANGELOG
+8. **Governance**: Cambios de alto riesgo requieren aprobación humana
+
+## Artefactos del sistema
+
+| Artefacto | Productor | Ubicación |
+|-----------|-----------|-----------|
+| PROJECT.md | orquestador / nuevo-proyecto | `.planning/PROJECT.md` |
+| PRD.md | producto-prd-swl | `.planning/PRD.md` |
+| PLAN.md | planificador-swl | `.planning/PLAN.md` |
+| STATE.md | orquestador-swl | `.planning/STATE.md` |
+| CONTEXT.md | discutir-fase | `.planning/phases/NN-nombre/CONTEXT.md` |
+| UI-SPEC.md | disenador-ui-swl | `.planning/UI-SPEC.md` |
+| QUALITY-REPORT.md | checklist-calidad | `.planning/QUALITY-REPORT.md` |
+| APRENDIZAJES.md | extraccion-aprendizajes | `.planning/APRENDIZAJES.md` |
+| DECISIONS.md | consolidador-swl | `.planning/DECISIONS.md` |
+| ADR-NNN.md | arquitecto-swl | `.planning/adrs/` |
+| CHANGELOG.md | auto-evolucion / release-manager | raíz del proyecto |
+
+## Generación de estructura de proyecto Claude-ready
+
+Fuentes oficiales: `referencias/Claude Code Project Structure.jpg`, `referencias/Claude Code WorkFlow Cheatsheet.jpg`
+
+El sistema genera proyectos con soporte nativo para Claude Code usando `Skill("estructura-proyecto-claude")`:
+
+```
+mi_proyecto/
+├── CLAUDE.md                    # Fuente de verdad — L1 (7 secciones obligatorias)
+├── .claude/
+│   ├── settings.json            # Permisos (allow/deny) + hooks + context rules
+│   ├── settings.local.json      # Config local (NUNCA commitear)
+│   ├── commands/                # Slash commands del proyecto
+│   ├── skills/                  # Skills con SKILL.md + scripts/ + references/ + assets/ (L2)
+│   ├── agents/                  # Subagentes especializados del proyecto (L4)
+│   ├── hooks/                   # Automatizaciones event-driven (L3)
+│   ├── rules/                   # Reglas path-scoped (.md con frontmatter paths:)
+│   └── plugins/                 # Plugins distribuibles (plugin.json)
+├── .planning/                   # Estado SWL persistido
+│   ├── PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
+│   └── research/ (STACK.md, ARCHITECTURE.md, FEATURES.md, PITFALLS.md)
+├── .mcp.json                    # Servidores MCP (GitHub, context7, Slack, Playwright, etc.)
+└── [código según stack]
+```
+
+**Arquitectura de 4 capas**: L1-CLAUDE.md (contexto persistente) → L2-Skills (conocimiento versionado) → L3-Hooks (seguridad y automatización) → L4-Agents (subagentes aislados).
+
+**6 tipos de extensiones**: Skills (auto-activación), Commands (slash/legacy), Subagents (paralelo), Hooks (event-driven), MCP Servers (integraciones), Plugins (distribuibles).
+
+**25 eventos de hook oficiales** (clave: PreToolUse, PostToolUse, SessionStart, Stop, PreCompact, PostCompact, Notification, SubagentStart/Stop, ConfigChange, FileChanged).
+
+**Jerarquía de memoria CLAUDE.md**: Managed Policy → User (`~/.claude/CLAUDE.md`) → Project (`./CLAUDE.md`) → Subdirectory. Cada archivo < 200 líneas.
+
+**Gestión de contexto**: 0-40% normal → 40-70% monitorear → 70-90% compactar → 90%+ nueva sesión.
+
+Variantes por stack y templates en `habilidades/estructura-proyecto-claude/recursos/`.
+
+## 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
+- Todos los agentes declaran: version, modelo, permisos, skills, nivel de riesgo
+- `respositorios-git/` es material de referencia — no modificar
+
+## Métricas del sistema
+
+| Componente | Cantidad | Líneas |
+|-----------|----------|--------|
+| Agentes SWL | 37 | ~17,400 |
+| Habilidades ES | 62 (9 con recursos/, 3 con scripts/) | ~24,000 |
+| Recursos y scripts | 15 archivos en 10 habilidades | ~3,300 |
+| Comandos | 17 | ~5,900 |
+| Reglas | 11 | ~2,700 |
+| Hooks | 6 | ~2,200 |
+| **Total SWL** | **172 componentes** | **~54,900 líneas** |
+| + Agentes GSD | 23 | (heredados) |
+| + Skills EN | 40 | (heredados) |
+| **Total sistema** | **235 componentes** | **~54,900 líneas propias** |