sdd-es 2.0.0

package/docs/AGENTES.md

@@ -0,0 +1,74 @@
+# Guía de Agentes Especializados
+
+SDD-ES incluye 11 agentes con roles bien definidos. Esta guía explica cuándo se activa cada uno.
+
+## Tabla rápida
+
+| Agente | Modelo recomendado | Cuándo se activa | Para qué |
+|--------|--------------------|------------------|----------|
+| arquitecto | opus | `/sdd.planificar`, fase A | Decisiones técnicas de alto nivel |
+| disenador-api | sonnet | `/sdd.planificar` (si hay contratos) | OpenAPI, GraphQL, gRPC, eventos |
+| asesor-datos | opus | `/sdd.planificar` (si toca BD) | Schemas, queries, índices, migraciones |
+| desarrollador-backend | sonnet | `/sdd.implementar` (servidor) | Servicios, controllers, lógica |
+| desarrollador-frontend | sonnet | `/sdd.implementar` (UI) | Componentes, vistas, estado cliente |
+| operaciones | sonnet | `/sdd.implementar` (infra) | CI/CD, Docker, IaC, deploy |
+| tester | sonnet | `/sdd.implementar` (tests) | Unitarios, integración, E2E |
+| revisor | opus | Al final de `/sdd.implementar` | Revisión cruzada de calidad |
+| critico | opus | `/sdd.planificar`, `/sdd.analizar` | Riesgos y puntos ciegos |
+| seguridad | opus | Cambios sensibles automáticamente | Auditoría de vulnerabilidades |
+| documentador | sonnet | Bajo demanda (desactivado por defecto) | Docs útiles (no obvias) |
+
+## Cuándo activar/desactivar agentes
+
+### Proyectos típicos
+
+**API REST sin frontend:**
+```yaml
+disenador-api: activo
+desarrollador-backend: activo
+desarrollador-frontend: desactivado  ← no necesario
+asesor-datos: activo
+operaciones: activo
+```
+
+**SPA sin backend propio (consume APIs externas):**
+```yaml
+desarrollador-frontend: activo
+desarrollador-backend: desactivado
+asesor-datos: desactivado
+disenador-api: desactivado
+```
+
+**MVP / Side project / Prototipo:**
+```yaml
+critico: desactivado          ← acelera el flujo
+seguridad: desactivado        ← no es producto público aún
+documentador: desactivado
+# todos los modelos a sonnet o haiku
+```
+
+**Producto enterprise / Crítico:**
+```yaml
+# Todos activos
+# Modelos opus en: arquitecto, asesor-datos, revisor, critico, seguridad
+```
+
+## Cómo se invocan los agentes
+
+Los agentes NO se invocan manualmente por el usuario. El plugin los orquesta:
+
+- **Durante `/sdd.planificar`**: el orquestador llama a `arquitecto`, `disenador-api`, `asesor-datos`, `critico` (y `seguridad` si es sensible). Cada uno aporta su sección al plan.
+
+- **Durante `/sdd.implementar`**: por cada tarea, el skill `enrutador-agentes` decide qué agente la ejecuta según el tipo de tarea.
+
+- **Al final de `/sdd.implementar`**: el `revisor` cruza el código contra la spec; el `tester` ejecuta la suite; el `seguridad` audita si tocó algo sensible.
+
+## Personalizar un agente
+
+Los agentes son archivos Markdown plano. Edita `.claude/agents/[nombre].md` para:
+- Cambiar la personalidad/tono
+- Añadir restricciones específicas de tu proyecto
+- Cambiar el formato de salida
+- Agregar conocimiento de domain específico
+
+Cambios al frontmatter `model:` se sobreescriben con la config en `.sdd/sdd.config.yaml`.

package/docs/COMPRESION.md

@@ -0,0 +1,155 @@
+# Compresión de Tokens — Caveman-Lite adaptado al español
+
+## El problema
+
+Tus archivos de memoria (CLAUDE.md, notas, preferencias) se cargan cada sesión:
+
+```
+CLAUDE.md normal:  5000 palabras = 5000 tokens
+CLAUDE.md comprimido:  1500 palabras = 1500 tokens
+Ahorro por sesión: 3500 tokens
+Ahorro mensual (20 sesiones): 70k tokens (~USD 0.30)
+```
+
+Pequeño, pero suma. Especialmente si mantienes memoria grande.
+
+## Cómo funciona
+
+Aplica transformaciones lingüísticas simples que preservan sustancia técnica:
+
+| Cambio | Ejemplo |
+|--------|---------|
+| Quita artículos | "el BD" → "BD" |
+| Simplifica conectores | "sin embargo" → "pero" |
+| Quita hedging | "creo que falla" → "falla" |
+| Quita cortesía | "por favor" → [quitar] |
+| Abreviar | "base de datos" → "BD" |
+
+Result: 64-75% de ahorro en palabras, 0% pérdida de sustancia.
+
+## Niveles
+
+### Lite
+- Solo quita: hedging + cortesía
+- Mantiene: frases completas, estructura
+- Ahorro: 20-30%
+- **Cuándo**: documentación editada frecuentemente
+
+### Full (default)
+- Quita: artículos, conectores, hedging, cortesía
+- Mantiene: sustancia técnica, estructura
+- Ahorro: 40-50%
+- **Cuándo**: memoria de proyecto, notas internas
+
+### Ultra
+- Quita: TODO lo anterior + términos técnicos se abrevian
+- Fragmentos OK
+- Ahorro: 60-75%
+- **Cuándo**: archivos internos, nunca editarás manualmente
+
+## Uso
+
+```bash
+# Comprimir CLAUDE.md con nivel full
+/sdd.comprimir aplicar CLAUDE.md full
+
+# Comprimir archivo.md con nivel lite
+/sdd.comprimir aplicar archivo.md lite
+
+# Ver antes/después sin guardar
+/sdd.comprimir validar archivo.md
+
+# Restaurar desde backup
+/sdd.comprimir revertir archivo.md
+```
+
+## Seguridad automática
+
+NUNCA comprime:
+- ❌ Código (`.py`, `.ts`, `.js`, `.json`, etc.)
+- ❌ Líneas con "PELIGRO", "CUIDADO", "NO USAR EN PRODUCCIÓN"
+- ❌ Instrucciones de acciones irreversibles ("ELIMINAR", "BORRAR")
+- ❌ Secuencias multi-paso donde fragmentación causa confusión
+
+Si detecta estos patrones: deja el texto como estaba.
+
+## Ejemplo completo
+
+**CLAUDE.md original** (456 palabras):
+
+```markdown
+# Estado del proyecto: Auth v2.0
+
+Estamos trabajando en migrar la autenticación hacia un sistema 
+basado en magic links por email. Es importante notar que, sin embargo,
+esto requiere que el usuario sea validado correctamente en la base de datos.
+
+Por favor, asegúrate de que todos los commits incluyan tests. 
+Creo que es fundamental que sigamos estas prácticas de calidad.
+
+La razón por la cual sugiero este enfoque es porque reduce la fricción 
+de los usuarios nuevos al no tener que recordar contraseñas.
+```
+
+**Comprimido (Full)** (147 palabras, 68% ahorro):
+
+```markdown
+# Estado del proyecto: Auth v2.0
+
+Migración: auth → magic links por email.
+Requiere validación correcta BD.
+
+Debe incluir tests en commits.
+Prácticas de calidad obligatorias.
+
+Approach: reduce fricción usuarios. No recordar pwd.
+```
+
+## Backup automático
+
+Cuando comprimes:
+```
+archivo.md          ← comprimido (nuevo)
+archivo.md.original ← backup (automático)
+```
+
+Para revertir:
+```bash
+/sdd.comprimir revertir archivo.md
+```
+
+## Tips
+
+1. **Empieza con Lite**: menos agresivo, más reversible
+2. **Valida antes**: `/sdd.comprimir validar` sin guardar
+3. **Equipo**: Si trabajas en equipo, comunica que comprimiste
+4. **Git**: Committea el `.original.md` también (es el "canonical")
+
+## Diccionario completo
+
+```
+/sdd.comprimir reglas
+```
+
+Muestra todas las 80+ parejas español-caveman-lite.
+
+## Limitaciones
+
+- ⚠️ Pierde matices tonales (formal → casual)
+- ⚠️ Manual review recomendado para docs importantes
+- ❌ No entiende contexto profundo (un "tal vez" crítico podría comprimirse)
+
+## Configuración global
+
+En `.sdd/sdd.config.yaml`:
+
+```yaml
+compresion:
+  enabled: true
+  modo_salida_usuario: lite        # user-facing: contenido/agentes
+  modo_agentes_internos: ultra     # comunicación IA-IA (usuario no ve)
+  preservar_terminos:
+    - autenticación
+    - verificación
+    - algoritmo
+```

package/docs/EJEMPLO-PRACTICA.md

@@ -0,0 +1,383 @@
+# Ejemplo Práctico — API de Lista de Tareas desde Cero
+
+Este ejemplo recorre el flujo completo de SDD-ES construyendo una API REST de lista de tareas con Node.js + Express + SQLite. No asume ningún código previo.
+
+---
+
+## Contexto del proyecto
+
+Tienes una carpeta vacía. Quieres construir una API que permita crear, listar, completar y eliminar tareas.
+
+```bash
+mkdir mi-api-tareas
+cd mi-api-tareas
+git init
+bash /ruta/a/sdd-es/instalar.sh
+```
+
+Abre Claude Code en `mi-api-tareas`.
+
+---
+
+## Paso 1 — Constitución
+
+```
+/sdd.constitucion
+```
+
+Claude detecta que el proyecto está vacío y te pregunta por el stack. Respondes:
+
+```
+Stack: Node.js con Express
+Base de datos: SQLite (sin ORM, queries directas)
+Tests: Jest
+Calidad: cobertura mínima 80%, funciones ≤40 líneas, sin any en TypeScript
+Sin TypeScript por ahora — JavaScript puro
+```
+
+Claude genera `.sdd/memoria/constitucion.md` con tus principios.
+
+---
+
+## Paso 2 — Primera especificación
+
+```
+/sdd.especificar API de lista de tareas — CRUD completo con SQLite
+```
+
+Claude detecta que es un cambio **mediano** (varios endpoints, BD, tests) y genera la spec:
+
+```
+✅ Spec creada: .sdd/especificaciones/2026-06-09-api-lista-tareas/spec.md
+
+⚠️  2 puntos requieren aclaración.
+
+PRÓXIMO PASO RECOMENDADO:
+   /sdd.aclarar    — resolver los [NECESITA_ACLARACION]
+```
+
+La spec generada contiene secciones como:
+
+```markdown
+## 4. Historias de Usuario
+
+### HU-001: Gestión de tareas
+Como usuario de la API
+Quiero crear, listar, completar y eliminar tareas
+Para organizar mi trabajo
+
+Criterios de aceptación:
+- [ ] CA-001-01: POST /tareas crea una tarea con título obligatorio (P1)
+- [ ] CA-001-02: GET /tareas devuelve todas las tareas ordenadas por fecha (P1)
+- [ ] CA-001-03: PATCH /tareas/:id/completar marca la tarea como completa (P1)
+- [ ] CA-001-04: DELETE /tareas/:id elimina la tarea (P1)
+- [ ] CA-001-05: POST /tareas sin título devuelve 400 con mensaje de error (P1)
+- [ ] CA-001-06: PATCH /tareas/:id con ID inexistente devuelve 404 (P2)
+
+## 8. Fuera de Alcance
+
+❌ Autenticación de usuarios
+❌ Múltiples listas por usuario
+❌ Prioridades o etiquetas
+```
+
+---
+
+## Paso 3 — Aclarar ambigüedades
+
+```
+/sdd.aclarar
+```
+
+Claude encuentra 2 puntos sin definir y pregunta:
+
+```
+🔴 ACLARACIONES CRÍTICAS
+
+1. [Datos] — ¿Las tareas tienen fecha de vencimiento?
+   a) Sí, campo opcional `vence_en` (ISO 8601)
+   b) No, solo título y estado
+
+2. [Formato] — ¿Qué devuelve DELETE /tareas/:id?
+   a) 204 sin body
+   b) 200 con la tarea eliminada
+```
+
+Respondes: `1.b, 2.a`
+
+Claude actualiza la spec y elimina los marcadores `[NECESITA_ACLARACION]`.
+
+---
+
+## Paso 4 — Plan técnico
+
+```
+/sdd.planificar
+```
+
+El arquitecto, el asesor de datos y el crítico trabajan en paralelo. Claude genera `.sdd/especificaciones/{ID}/plan.md`:
+
+```
+── Constitutional AI Check ─────────────────────────────
+✅ Stack: Express + SQLite — alineado con constitución
+✅ Patrones: módulos ES, funciones ≤40 líneas
+✅ Sin dependencias nuevas más allá de express y better-sqlite3
+─────────────────────────────────────────────────────────
+
+📋 Plan técnico generado
+   • 6 archivos afectados
+   • 2 dependencias nuevas (express, better-sqlite3)
+   • 4 decisiones técnicas
+   • 1 riesgo identificado
+
+⚠️  PUNTOS DESTACADOS:
+   • Riesgo medio: SQLite no soporta concurrencia alta — documentado, aceptado
+     para el scope actual (API local/dev)
+
+POR FAVOR REVISA EL PLAN:
+   /sdd.planificar aprobar    — continuar al desglose
+   /sdd.planificar revisar    — discutir cambios
+```
+
+Revisas el plan en `.sdd/especificaciones/{ID}/plan.md`. Ves que el arquitecto propuso esta estructura:
+
+```
+src/
+  db.js          ← inicialización de SQLite
+  tareas.js      ← lógica de negocio
+  rutas.js       ← endpoints Express
+  app.js         ← setup de Express
+  server.js      ← punto de entrada
+tests/
+  tareas.test.js
+```
+
+```
+/sdd.planificar aprobar
+```
+
+---
+
+## Paso 5 — Desglose en tareas
+
+```
+/sdd.tareas
+```
+
+```
+✅ 8 tareas generadas
+
+DISTRIBUCIÓN POR AGENTE:
+   • arquitecto:           1 (estructura base)
+   • desarrollador-backend: 5 (BD, lógica, rutas)
+   • tester:              2 (tests unitarios + integración)
+
+COBERTURA:
+   • 6/6 CAs cubiertos
+```
+
+Las tareas generadas en `.sdd/especificaciones/{ID}/tareas.md`:
+
+```
+T001 — Inicializar proyecto e instalar dependencias         [arquitecto]
+T002 — Crear módulo de BD (db.js + migración inicial)       [backend]
+T003 — Tests unitarios de la capa de datos                  [tester]
+T004 — Implementar lógica de tareas (tareas.js)             [backend]
+T005 — Tests unitarios de lógica                            [tester]
+T006 — Implementar rutas Express (rutas.js)                 [backend]
+T007 — Setup de app.js y server.js                          [backend]
+T008 — Tests de integración (API completa)                  [tester]
+```
+
+---
+
+## Paso 6 — Implementación
+
+```
+/sdd.implementar
+```
+
+Claude muestra el progreso en tiempo real:
+
+```
+🔧 T001 — Inicializar proyecto e instalar dependencias
+   Agente: arquitecto (modelo: opus)
+   Tiempo estimado: S
+
+✅ T001 completada — Verificación: PASADA
+
+🔧 T002 — Crear módulo de BD
+   Agente: desarrollador-backend (modelo: sonnet)
+
+── Validación de convenciones: src/db.js (fuentes: constitución, inferido) ──
+✅ Sin violaciones
+────────────────────────────────────────────────────────────────────────────
+
+✅ T002 completada — Verificación: PASADA
+
+🔧 T003 — Tests unitarios de la capa de datos
+   Agente: tester (modelo: sonnet)
+✅ T003 completada
+
+[...continúa para T004–T008...]
+
+✅ T008 completada
+```
+
+El código generado en `src/db.js`:
+
+```javascript
+import Database from 'better-sqlite3'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const DB_PATH = join(__dirname, '..', 'tareas.db')
+
+let db
+
+export function getDb() {
+  if (!db) {
+    db = new Database(DB_PATH)
+    db.pragma('journal_mode = WAL')
+    inicializar(db)
+  }
+  return db
+}
+
+function inicializar(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS tareas (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      titulo    TEXT NOT NULL,
+      completa  INTEGER NOT NULL DEFAULT 0,
+      creada_en TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `)
+}
+```
+
+Y en `src/tareas.js`:
+
+```javascript
+import { getDb } from './db.js'
+
+export function listarTareas() {
+  return getDb()
+    .prepare('SELECT * FROM tareas ORDER BY creada_en DESC')
+    .all()
+}
+
+export function crearTarea(titulo) {
+  if (!titulo || titulo.trim().length === 0) {
+    throw new Error('El título es obligatorio')
+  }
+  const stmt = getDb().prepare('INSERT INTO tareas (titulo) VALUES (?)')
+  const result = stmt.run(titulo.trim())
+  return getDb().prepare('SELECT * FROM tareas WHERE id = ?').get(result.lastInsertRowid)
+}
+
+export function completarTarea(id) {
+  const tarea = getDb().prepare('SELECT * FROM tareas WHERE id = ?').get(id)
+  if (!tarea) return null
+  getDb().prepare('UPDATE tareas SET completa = 1 WHERE id = ?').run(id)
+  return { ...tarea, completa: 1 }
+}
+
+export function eliminarTarea(id) {
+  const result = getDb().prepare('DELETE FROM tareas WHERE id = ?').run(id)
+  return result.changes > 0
+}
+```
+
+---
+
+## Paso 7 — Verificación final
+
+Al terminar todas las tareas, Claude invoca automáticamente al revisor y corre los tests:
+
+```
+📊 Implementación Completada: 2026-06-09-api-lista-tareas
+
+Tareas:      8/8 ✅
+Tests:       Jest — 14 pasados, 0 fallidos
+Cobertura:   87% (umbral: 80%) ✅
+Constitución: ✅
+
+Revisión del agente revisor:
+  ✅ Todos los CAs cubiertos por tests
+  ✅ Funciones ≤40 líneas (máx. encontrada: 18 líneas)
+  🟡 Sugerencia: añadir middleware de manejo de errores global (no bloqueante)
+
+SIGUIENTES PASOS:
+   /sdd.verificar      — verificación final contra spec original
+   /sdd.snapshot       — actualizar SNAPSHOT del producto
+```
+
+```
+/sdd.verificar
+```
+
+```
+✅ Verificación completada
+
+CA-001-01: POST /tareas crea tarea         ✅ test: "debería crear tarea con título"
+CA-001-02: GET /tareas devuelve ordenadas  ✅ test: "debería listar en orden descendente"
+CA-001-03: PATCH completa la tarea         ✅ test: "debería marcar como completa"
+CA-001-04: DELETE elimina la tarea         ✅ test: "debería eliminar y devolver 204"
+CA-001-05: POST sin título → 400           ✅ test: "debería devolver 400 sin título"
+CA-001-06: PATCH ID inexistente → 404      ✅ test: "debería devolver 404 si no existe"
+
+6/6 criterios de aceptación verificados ✅
+```
+
+---
+
+## Resultado final
+
+```
+mi-api-tareas/
+├── src/
+│   ├── db.js          ← BD SQLite
+│   ├── tareas.js      ← lógica de negocio
+│   ├── rutas.js       ← endpoints Express
+│   ├── app.js         ← setup Express
+│   └── server.js      ← punto de entrada
+├── tests/
+│   └── tareas.test.js ← 14 tests, 87% cobertura
+├── package.json
+├── tareas.db          ← BD generada en primera ejecución
+└── .sdd/
+    ├── memoria/constitucion.md
+    ├── especificaciones/2026-06-09-api-lista-tareas/
+    │   ├── spec.md
+    │   ├── plan.md
+    │   ├── tareas.md
+    │   └── checklist-spec.md
+    └── SNAPSHOT.md
+```
+
+**Lo que SDD-ES garantizó:**
+- Cada línea de código está trazada a un criterio de aceptación
+- El revisor verificó independientemente del implementador
+- La constitución se cumplió en cada decisión técnica
+- Los tests no son decorativos — cada CA tiene su test
+
+---
+
+## Próxima feature
+
+```
+/sdd.especificar añadir prioridad a las tareas (alta/media/baja)
+```
+
+El sistema detecta que hay una spec anterior completada, carga el contexto del proyecto (constitución + snapshot) y empieza desde cero — sin repetir preguntas ya respondidas.
+
+---
+
+## Ver también
+
+- [FLUJO.md](FLUJO.md) — diagrama completo del flujo
+- [AGENTES.md](AGENTES.md) — qué hace cada agente
+- [PERSONALIZACION.md](PERSONALIZACION.md) — ajustar modelos, activar/desactivar agentes
+- [FILOSOFIA.md](FILOSOFIA.md) — por qué SDD con IA