sdd-es 2.5.0 → 2.6.0

package/docs/CASO-COMPLETO.md

@@ -0,0 +1,206 @@
+# Caso completo: app de lista de tareas desde cero
+
+Este documento muestra un recorrido real de FORGE para un proyecto pequeño.
+Cada bloque muestra qué escribe el usuario y qué hace FORGE en respuesta.
+
+El caso usa el flujo FORGE (idea → deploy) con perfil `guiado` para un usuario no-técnico.
+
+---
+
+## Fase 1 — Descubrir la idea
+
+**Usuario:**
+```
+/sdd "quiero una app de lista de tareas para mí solo"
+```
+
+**FORGE** (hub `/sdd`):
+1. Lee `.sdd/estado.json` — no existe, proyecto sin inicializar.
+2. Detecta intención FORGE ("quiero una app").
+3. Llama a `/sdd.interpretar` con el texto de la idea.
+
+---
+
+## Fase 2 — Interpretar (`/sdd.interpretar`)
+
+**FORGE** ejecuta internamente:
+1. Activa el agente `investigador` para leer el contexto del directorio actual.
+2. Hace 3 preguntas mínimas al usuario (sí/no o una palabra):
+   - ¿Web en el navegador o app de escritorio? → `web`
+   - ¿Con cuenta de usuario o sin login? → `sin login`
+   - ¿Solo tú o quieres compartir listas? → `solo yo`
+3. Genera `.sdd/ir.json`:
+
+```json
+{
+  "id": "ir-todo-app-001",
+  "product": {
+    "name": "Mi Lista de Tareas",
+    "type": "web",
+    "target_users": "usuario único sin cuenta",
+    "value_proposition": "Lista de tareas personal, sin registro, datos en el navegador"
+  },
+  "features": {
+    "core": ["agregar tarea", "marcar como hecha", "eliminar tarea"],
+    "nice_to_have": ["filtrar por estado", "persistencia en localStorage"]
+  },
+  "constraints": {
+    "tech_preference": null,
+    "budget": "bajo",
+    "team_size": "1"
+  }
+}
+```
+
+**Usuario ve:**
+```
+Entendido. Tu app es una lista de tareas personal para el navegador, sin login.
+
+Características principales:
+  ✓ Agregar tarea
+  ✓ Marcar como hecha
+  ✓ Eliminar tarea
+  ✓ Persistencia en localStorage (los datos quedan aunque cierres el navegador)
+
+¿Arrancamos con el diseño? (responde sí)
+```
+
+---
+
+## Fase 3 — Diseñar (`/sdd.diseñar`)
+
+**Usuario:** `sí`
+
+**FORGE** orquesta internamente:
+1. Agente `product-designer` lee `ir.json` y genera `product-design.json`:
+   - Pantallas P0: lista de tareas + input de nueva tarea
+   - User flow: usuario abre → ve lista → agrega → marca → cierra
+   - MVPscope: solo las 3 features core, sin filtros en V1
+2. Agente `architecture-designer` lee `ir.json` y propone stack:
+   - Frontend: HTML + CSS vanilla + JS puro (sin frameworks — proyecto de 1 persona, bajo presupuesto)
+   - Backend: ninguno (datos en localStorage)
+   - Deploy: GitHub Pages o Vercel (gratis)
+3. Skill `critica-diseno` revisa y aprueba: no hay over-engineering.
+
+**Usuario ve:**
+```
+Diseño listo:
+
+Stack: HTML/CSS/JS vanilla — sin framework, sin backend, datos en tu navegador.
+Deploy: Vercel gratis.
+
+Una pantalla: input + lista de tareas. Simple y directo.
+
+¿Construimos el código? (responde sí)
+```
+
+---
+
+## Fase 4 — Especificar y Planificar
+
+**Usuario:** `sí`
+
+**FORGE** ejecuta `/sdd.especificar` automáticamente desde el IR + ProductDesign:
+1. Genera `.sdd/especificaciones/2026-06-14-todo-app/spec.md` con criterios de aceptación:
+   - CA-001: Al cargar la página, se muestran las tareas guardadas en localStorage
+   - CA-002: El usuario puede agregar una tarea escribiendo en el input y presionando Enter
+   - CA-003: Al hacer click en una tarea se marca como completada (tachada)
+   - CA-004: El botón "×" elimina una tarea permanentemente
+   - CA-005: Los cambios persisten tras recargar la página
+
+Luego ejecuta `/sdd.planificar`:
+1. Plan técnico: 1 archivo `index.html`, 1 `style.css`, 1 `app.js`
+2. Agente `critico` revisa — sin riesgos identificados para este alcance
+3. Presenta plan al usuario para aprobación.
+
+**Usuario ve:**
+```
+Plan aprobado. 3 archivos: index.html, style.css, app.js.
+Estimado: 15 minutos de implementación.
+
+¿Implementamos? (responde sí)
+```
+
+---
+
+## Fase 5 — Implementar (`/sdd.implementar`)
+
+**Usuario:** `sí`
+
+**FORGE** ejecuta `/sdd.tareas` y luego `/sdd.implementar`:
+1. Genera tareas atómicas:
+   - T001: Crear `index.html` con estructura base (input + ul#tasks)
+   - T002: Crear `style.css` con estilos minimalistas
+   - T003: Crear `app.js` con lógica CRUD + localStorage
+   - T004: Conectar los tres archivos y verificar criterios de aceptación
+
+2. Agente `desarrollador-frontend` ejecuta cada tarea en secuencia.
+3. Al terminar T004, agente `tester` genera y corre tests básicos (sin navegador — valida lógica pura de `app.js`).
+4. Agente `revisor` verifica que cada CA del spec esté cubierto.
+
+**Usuario ve:**
+```
+Implementación completa.
+
+✓ T001 index.html
+✓ T002 style.css
+✓ T003 app.js
+✓ T004 integración verificada
+
+Tests: 5/5 pasando
+Spec: CA-001 ✓  CA-002 ✓  CA-003 ✓  CA-004 ✓  CA-005 ✓
+
+¿Desplegamos? (responde sí)
+```
+
+---
+
+## Fase 6 — Verificar y Desplegar
+
+**Usuario:** `sí`
+
+**FORGE** ejecuta `/sdd.verificar` y luego `/sdd.desplegar`:
+
+1. `/sdd.verificar` hace la verificación final:
+   - Lee `spec.md` y el código generado
+   - Confirma que cada criterio de aceptación tiene cobertura en el código
+   - Gate pasa: 0 violaciones de constitución (no hay constitución configurada en este proyecto)
+
+2. `/sdd.desplegar` con gate duro:
+   - Tests verdes ✓
+   - Spec verificada ✓
+   - Sin secretos en el código ✓
+   - Pide confirmación explícita: **el usuario escribe "desplegar"**
+
+3. Agente `operaciones` ejecuta:
+   ```bash
+   npx vercel --prod
+   ```
+4. Health check post-deploy: GET a la URL devuelta por Vercel, verifica HTTP 200.
+5. Registra URL en `.sdd/estado.json`.
+
+**Usuario ve:**
+```
+✓ Desplegado en: https://mi-lista-tareas-abc123.vercel.app
+
+Health check: OK (142ms)
+
+Tu app está en línea. Puedes compartir ese enlace o abrirlo en cualquier navegador.
+```
+
+---
+
+## Resumen del flujo
+
+| Fase | Comando FORGE | Qué produce |
+|------|--------------|-------------|
+| Interpretar idea | `/sdd.interpretar` | `.sdd/ir.json` |
+| Diseñar producto | `/sdd.diseñar` | `product-design.json`, stack definido |
+| Especificar | `/sdd.especificar` | `spec.md` con 5 criterios de aceptación |
+| Planificar | `/sdd.planificar` | `plan.md`, tareas aprobadas |
+| Implementar | `/sdd.implementar` | `index.html`, `style.css`, `app.js` |
+| Verificar | `/sdd.verificar` | Confirmación de CAs cubiertos |
+| Desplegar | `/sdd.desplegar` | URL pública + health check |
+
+Interacciones del usuario: 5 respuestas (`sí` / `sí` / `sí` / `sí` / `desplegar`).
+Todo lo técnico lo maneja FORGE.

package/docs/EJEMPLOS.md

@@ -0,0 +1,88 @@
+# Ejemplos prácticos de FORGE
+
+## Flujo básico: de idea a MVP
+
+Este documento muestra cómo usar FORGE en un proyecto real.
+
+### Ejemplo 1: App de tareas simple
+
+**Idea:** "Necesito una aplicación web para gestionar mis tareas pendientes"
+
+```bash
+/sdd.descubrir App para gestionar tareas
+# → FORGE hace preguntas rápidas:
+#   • ¿Cuántas personas usan esto? (1 → tú)
+#   • ¿Dónde viven los datos? (en el navegador)
+#   • ¿Cuándo necesitas esto? (semana que viene)
+
+/sdd.especificar
+# → Genera una spec automáticamente
+
+/sdd.planificar
+/sdd.tareas
+/sdd.implementar
+# → 2-3 horas: app funcional
+```
+
+**Resultado:** App web con React + SQLite, desplegada en Vercel.
+
+---
+
+### Ejemplo 2: CLI para procesar datos
+
+**Idea:** "Script que convierta CSV a JSON, filtrando filas por criterio"
+
+```bash
+/sdd crear-app "CLI para procesar CSV a JSON"
+# → Genera proyecto Node.js con TypeScript
+
+npm run dev
+# → Funciona inmediatamente
+```
+
+---
+
+## Cómo interpretar la Spec
+
+Una spec FORGE tiene esta estructura:
+
+```yaml
+---
+id: spec-001
+titulo: "Autenticación de usuarios"
+---
+
+# Criterios de aceptación
+
+## CA-001: Login con email/password
+Dado un usuario registrado
+Cuando introduce email + password correctos
+Entonces puede acceder a su panel
+
+## CA-002: Mensaje de error
+Dado credenciales inválidas
+Cuando intenta login
+Entonces ve mensaje "Email o contraseña incorrectos"
+```
+
+---
+
+## Usar el indexador
+
+Para mapear tu proyecto:
+
+```bash
+/sdd.mapear
+# Genera .sdd/mapa/simbolos.md
+
+# Ver símbolos de un archivo
+cat .sdd/mapa/simbolos.md | grep "auth"
+```
+
+---
+
+## Más información
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Flujo completo de FORGE
+- [../commands/](../commands/) — Referencia de todos los comandos
+- [../agents/](../agents/) — Roles de cada agente

package/docs/FABRICA.md

@@ -31,7 +31,7 @@ SDD-ES leyó esa descripción y creó un plan detallado:
 Martina revisó el plan, preguntó: "¿Puedo agregar una opción de pago en el mismo sitio?" El sistema actualizó el plan en 30 segundos.
 
 **Las 14:45 — Se construye sola (en paralelo)**
-Aquí es donde la magia ocurre. En lugar de un desarrollador escribiendo código línea por línea durante horas, 12 agentes especializados trabajaron en paralelo:
+Aquí es donde la magia ocurre. En lugar de un desarrollador escribiendo código línea por línea durante horas, 14 agentes especializados trabajaron en paralelo:
 - Uno diseñó la base de datos
 - Otro construyó el formulario interactivo
 - Un tercero implementó la lógica de cálculo de presupuestos
@@ -79,9 +79,9 @@ SDD-ES lee tu descripción y traduce tu idea a un **plan detallado**, pero en le
 
 Tú revisas el plan. ¿No te gusta una decisión? La cambias. ¿Se te ocurrió algo nuevo? Lo agregas. El sistema actualiza el plan al instante. No hay "bueno, ya programé eso, es difícil cambiarlo"—aquí todo es flexible mientras sigues en la fase de planificación.
 
-### Fase 3: Se Construye Sola (12 Agentes Trabajando en Paralelo)
+### Fase 3: Se Construye Sola (14 Agentes Trabajando en Paralelo)
 
-Una vez que el plan es definitivo, SDD-ES activa 12 agentes especializados que trabajan al mismo tiempo, como obreros en una fábrica real:
+Una vez que el plan es definitivo, SDD-ES activa 14 agentes especializados que trabajan al mismo tiempo, como obreros en una fábrica real:
 
 - **Agente de Arquitectura**: diseña cómo se comunicarán todas las partes
 - **Agente de Base de Datos**: crea dónde se guardarán los datos de forma segura
@@ -96,7 +96,7 @@ Una vez que el plan es definitivo, SDD-ES activa 12 agentes especializados que t
 - **Agente de DevOps**: configura los servidores
 - **Agente de Auditoría**: revisa cada decisión antes de continuar
 
-Mientras estos 12 trabajan (en paralelo, no uno después de otro), tú esperas. No necesitas hacer nada. Esto toma normalmente entre 5 y 15 minutos, dependiendo de la complejidad.
+Mientras estos 14 trabajan (en paralelo, no uno después de otro), tú esperas. No necesitas hacer nada. Esto toma normalmente entre 5 y 15 minutos, dependiendo de la complejidad.
 
 ### Fase 4: Verificación Automática (Antes de Publicar)
 
@@ -189,10 +189,9 @@ Para alguien sin conocimiento técnico, eso es todo. No necesitas ser ingeniero
 
 | Documento | Para quién | Propósito |
 |-----------|-----------|-----------|
-| [EJEMPLO-E2E-REAL.md](EJEMPLO-E2E-REAL.md) | Todos | Diálogos exactos: qué escribes, qué responde Claude (paso a paso) |
 | [QUE-PASA-SI-FALLA.md](QUE-PASA-SI-FALLA.md) | No-técnicos | Respuestas: "¿y si cambio de idea?", "¿y si falla?", etc. |
-| [RESUMEN-EJECUTIVO-NO-TECNICOS.md](RESUMEN-EJECUTIVO-NO-TECNICOS.md) | Ejecutivos, managers | Qué cambió en v2.2, sin jerga |
 | [FLUJO.md](FLUJO.md) | Programadores | Comandos técnicos, workflows, pipes |
+| [MEMORIA-Y-OBSERVABILIDAD.md](MEMORIA-Y-OBSERVABILIDAD.md) | Arquitectos/developers | Sistema de memoria persistente y observabilidad de tokens |
 
 ---
 

package/docs/INICIO-RAPIDO.md

@@ -1,116 +1,64 @@
-# Inicio Rápido — SDD-ES
+# Inicio Rápido
 
-SDD-ES es un plugin para Claude Code que añade un flujo estructurado para convertir ideas en código verificado. En lugar de pedirle a Claude "implementa X", defines primero qué quieres y por qué, y el sistema coordina agentes especializados para construirlo con trazabilidad completa.
+## La idea central
 
----
-
-## Instalación
-
-Requiere **Node.js >= 18**. El instalador funciona igual en Windows, macOS y Linux.
-
-```bash
-# 1. Ve a tu proyecto
-cd mi-proyecto
-
-# 2. Instala (camino recomendado, multiplataforma)
-npx sdd-es init
-```
+Escribe `/sdd [tu idea]` y FORGE hace el resto.
 
-**Windows (PowerShell)** — atajo equivalente:
-
-```powershell
-.\instalar.ps1
-```
-
-**macOS / Linux / Git Bash** — atajo equivalente:
-
-```bash
-bash /ruta/a/sdd-es/instalar.sh
-```
-
-El instalador crea la carpeta `.sdd/` en tu proyecto y copia los comandos, agentes, skills y hooks de seguridad al `.claude/` local. Comprueba que todo quedó bien con:
-
-```bash
-npx sdd-es doctor
-```
+No necesitas saber programar. No necesitas configurar nada primero. Solo describe lo que quieres construir.
 
 ---
 
-## Primera vez en un proyecto
+## ¿Cómo empiezo?
 
-Abre Claude Code en tu proyecto y ejecuta:
+Abre Claude Code en tu proyecto y escribe:
 
 ```
-/sdd.constitucion
+/sdd quiero una app para gestionar mis tareas
 ```
 
-Claude te hace preguntas sobre tu proyecto (stack, principios, estándares de calidad) y genera `.sdd/memoria/constitucion.md` — la ley del proyecto que todos los agentes respetan.
-
-Solo se hace una vez por proyecto.
-
----
-
-## Flujo diario
+O simplemente:
 
 ```
-/sdd.especificar [descripción de lo que quieres]
+/sdd
 ```
 
-Desde ahí el sistema te guía paso a paso. No necesitas memorizar el resto de comandos — `/sdd` solo te pregunta qué quieres y enruta automáticamente.
+FORGE te preguntará qué quieres construir y te irá guiando paso a paso.
 
 ---
 
-## Los 4 comandos que más usarás
+## ¿Qué hace FORGE por mí?
 
-| Comando | Para qué |
-|---|---|
-| `/sdd` | Punto de entrada — di lo que quieres en lenguaje natural |
-| `/sdd.especificar [idea]` | Convertir una idea en spec con criterios de aceptación |
-| `/sdd.implementar` | Ejecutar las tareas con los agentes especializados |
-| `/sdd.estado` | Ver dashboard del proyecto |
+1. **Entiende tu idea** — te hace solo las preguntas necesarias para aclarar qué quieres.
+2. **Hace el plan** — decide cómo construirlo sin que tengas que saber de tecnología.
+3. **Lo construye** — escribe el código, lo prueba y lo verifica.
+4. **Te informa en tu idioma** — te dice "tu login está listo" en vez de "pipeline_step=verify".
 
----
-
-## ¿Eres nuevo en programación?
+Tú solo confirmas con "sí" entre pasos. FORGE hace el trabajo.
 
-SDD-ES tiene un **perfil guiado** para personas con poca o ninguna experiencia. Durante `/sdd.constitucion` puedes elegirlo (o el sistema lo detecta automáticamente por la forma en que hablas).
+---
 
-En perfil guiado:
-- No ves comandos ni tecnicismos — solo preguntas en lenguaje normal
-- El sistema elige el stack por ti
-- Confirmas con "sí" entre cada paso
-- Al final, Claude publica tu app en internet
+## Instalación
 
-**Atajo directo para no-programadores:**
+Necesitas tener **Node.js** instalado. Luego, en tu proyecto:
 
-```
-/sdd.crear-app [describe tu idea]
+```bash
+npx sdd-es init
 ```
 
-Ver el recorrido completo en [FABRICA.md](FABRICA.md).
+Eso es todo. FORGE queda listo para usarse con Claude Code.
 
 ---
 
-## Crear una herramienta para Claude
+## Si algo no funciona
 
-Si quieres que Claude pueda hacer algo nuevo (consultar una API, acceder a tus archivos, etc.):
+Escribe:
 
 ```
-/sdd.crear-mcp [describe qué hace la herramienta]
+/sdd ayuda
 ```
 
-Genera un servidor MCP funcional empaquetado como `.mcpb` instalable con una línea.
-
----
-
-## Si algo sale mal o quieres retomar
-
-```
-/sdd.estado                    # ¿dónde estoy?
-/sdd.implementar continuar     # retomar desde la última tarea
-/sdd.ayuda                     # lista completa de comandos
-```
+FORGE te explicará qué está pasando y qué hacer.
 
 ---
 
-## Ejemplo completo → ver [EJEMPLO-PRACTICA.md](EJEMPLO-PRACTICA.md)
+Para usuarios avanzados que quieren ver todos los comandos disponibles: [FLUJO.md](FLUJO.md)

package/docs/MEMORIA-Y-OBSERVABILIDAD.md

@@ -1,6 +1,6 @@
 # Memoria, Observabilidad y Optimización de Tokens en SDD-ES
 
-Este documento explica cómo SDD-ES mantiene continuidad entre sesiones (memoria por agente), cómo monitorizar el consumo de agentes sin depender del conteo de tokens del modelo, y cómo usar las nuevas técnicas de optimización de tokens (v2.5.0).
+Este documento explica cómo SDD-ES mantiene continuidad entre sesiones (memoria por agente), cómo monitorizar el consumo de agentes sin depender del conteo de tokens del modelo, y cómo usar las nuevas técnicas de optimización de tokens (v2.6.0).
 
 ---
 
@@ -8,7 +8,9 @@ Este documento explica cómo SDD-ES mantiene continuidad entre sesiones (memoria
 
 ### Qué es
 
-Cada agente del Grupo OPUS (arquitecto, asesor-datos, disenador-api, critico) tiene un archivo de memoria persistente en:
+> **Desde v2.6.0, todos los agentes activos tienen memoria persistente.** Además del Grupo OPUS, los agentes `desarrollador-backend`, `desarrollador-frontend`, `tester`, `documentador` y `operaciones` registran sus cambios en su propio archivo de memoria, lo que garantiza continuidad entre sesiones para todo el pipeline SDD.
+
+Cada agente activo (Grupo OPUS — arquitecto, asesor-datos, disenador-api, critico — más desarrollador-backend, desarrollador-frontend, tester, documentador y operaciones) tiene un archivo de memoria persistente en:
 
 ```
 .sdd/memoria/agente-{nombre}.md
@@ -24,7 +26,7 @@ Claude Code no mantiene contexto entre sesiones. El archivo de memoria resuelve
 
 El hook `claude-hooks/agent-memory.js` se ejecuta como `PostToolUse` tras cada `Write` o `Edit`. Lee la variable de entorno `CLAUDE_AGENT_NAME` que Claude Code inyecta cuando hay un subagente activo, y si el agente es uno de los cuatro del Grupo OPUS, añade una entrada al archivo de memoria correspondiente.
 
-Desde v2.5.0, el hook también emite una alerta por stderr cuando la memoria de un agente supera 50KB:
+Desde v2.6.0, el hook también emite una alerta por stderr cuando la memoria de un agente supera 50KB:
 
 ```
 ⚠️  [agent-memory] Memoria de arquitecto supera 52KB — considera ejecutar /sdd.optimizar memoria
@@ -100,7 +102,7 @@ echo "" > .sdd/observabilidad/consumo.jsonl
 
 ---
 
-## 3. Técnicas de optimización de tokens (v2.5.0)
+## 3. Técnicas de optimización de tokens (v2.6.0)
 
 ### El comando unificado
 
@@ -198,7 +200,7 @@ La alerta del hook (`⚠️ Memoria supera 50KB`) es la señal principal. Tambi
 
 ---
 
-## 5. Arquitectura del sistema (v2.5.0)
+## 5. Arquitectura del sistema (v2.6.0)
 
 ```
 claude-hooks/
@@ -209,16 +211,16 @@ claude-hooks/
 
 skills/
   observabilidad-consumo/  ← Lee consumo.jsonl, produce reporte, detecta fan-out
-  effort-router/           ← Routing Haiku/Sonnet/Opus por fase (v2.5.0)
-  memory-compactor/        ← Deduplicación + compresión de .sdd/memoria/ (v2.5.0)
-  cache-audit/             ← Detecta invalidadores silenciosos de caché (v2.5.0)
-  token-budget/            ← Proyecta costo por fase + recomendación PTC (v2.5.0)
+  effort-router/           ← Routing Haiku/Sonnet/Opus por fase (v2.6.0)
+  memory-compactor/        ← Deduplicación + compresión de .sdd/memoria/ (v2.6.0)
+  cache-audit/             ← Detecta invalidadores silenciosos de caché (v2.6.0)
+  token-budget/            ← Proyecta costo por fase + recomendación PTC (v2.6.0)
   compresion-tokens/       ← Diccionario caveman — reutilizado por memory-compactor
   orquestacion-ptc/        ← Criterios PTC — reutilizados por token-budget
 
 commands/
   sdd.estado.md            ← /sdd.estado consumo
-  sdd.optimizar.md         ← Ciclo completo de optimización (v2.5.0)
+  sdd.optimizar.md         ← Ciclo completo de optimización (v2.6.0)
   sdd.comprimir.md         ← /sdd.comprimir memoria → memory-compactor
 ```
 

package/docs/README.md

@@ -0,0 +1,43 @@
+# Documentación de FORGE
+
+> **Sitio web de documentación**: hay una versión navegable, bilingüe (ES/EN) y con buscador en [`docs-site/`](../docs-site/) — ábrela en el navegador o visita la versión publicada en GitHub Pages.
+
+Esta carpeta contiene la documentación de referencia en Markdown. Está organizada en dos rutas según para quién es.
+
+---
+
+## 🟢 Para construir (no necesitas saber programar)
+
+| Documento | De qué trata |
+|-----------|--------------|
+| [INICIO-RAPIDO.md](INICIO-RAPIDO.md) | Los primeros pasos: instalar y escribir tu primera idea |
+| [FABRICA.md](FABRICA.md) | Cómo una idea se convierte en producto, en vivo y sin código |
+| [QUE-PASA-SI-FALLA.md](QUE-PASA-SI-FALLA.md) | Qué hacer cuando algo sale mal, en lenguaje simple |
+| [SEGURIDAD-PARA-NOTECNICOS.md](SEGURIDAD-PARA-NOTECNICOS.md) | Tokens y seguridad explicados sin miedo |
+
+## 🔵 Para entender el motor (desarrolladores)
+
+| Documento | De qué trata |
+|-----------|--------------|
+| [FLUJO.md](FLUJO.md) | El flujo de ingeniería SDD completo, con diagrama |
+| [FILOSOFIA.md](FILOSOFIA.md) | Qué es SDD y los principios que lo guían |
+| [AGENTES.md](AGENTES.md) | Los 14 agentes: roles, cuándo se activan |
+| [MODELOS.md](MODELOS.md) | Qué modelo de Claude usa cada agente y por qué |
+| [MEMORIA-Y-OBSERVABILIDAD.md](MEMORIA-Y-OBSERVABILIDAD.md) | Persistencia, ledger y compresión de tokens |
+| [MAPAS.md](MAPAS.md) | Indexación de estructura, símbolos y dependencias |
+| [RELACION-CON-CLAUDE-CODE.md](RELACION-CON-CLAUDE-CODE.md) | FORGE como capa sobre las primitivas oficiales |
+| [PERSONALIZACION.md](PERSONALIZACION.md) | Los 5 niveles de personalización |
+| [COMPRESION.md](COMPRESION.md) | La técnica de compresión de contexto |
+
+## 📖 Ejemplos y casos
+
+| Documento | De qué trata |
+|-----------|--------------|
+| [CASO-COMPLETO.md](CASO-COMPLETO.md) | Un proyecto real de principio a fin |
+| [EJEMPLOS.md](EJEMPLOS.md) | Ejemplos por stack (TypeScript, Python, Go…) |
+
+---
+
+## Ingeniería de prompts
+
+La guía de ingeniería de prompts con Claude — principios oficiales, ejemplos buenos vs malos y cómo FORGE los aplica — está en el **sitio de documentación** ([`docs-site/`](../docs-site/)), sección *Ingeniería de prompts*.

package/docs/RELACION-CON-CLAUDE-CODE.md

@@ -0,0 +1,38 @@
+# FORGE / SDD-ES — Relación con las primitivas oficiales de Claude Code
+
+FORGE no es un reemplazo de Claude Code. Es una **capa de opinión en español** que organiza y conecta las primitivas nativas de Claude Code en un flujo de trabajo estructurado (idea → deploy).
+
+Toda la funcionalidad de FORGE descansa sobre primitivas que Claude Code ya provee.
+
+---
+
+## Tabla de correspondencias
+
+| Pieza de FORGE | Primitiva oficial de Claude Code | Notas |
+|----------------|----------------------------------|-------|
+| `commands/*.md` (ej. `/sdd.especificar`) | **Slash commands** (`.claude/commands/*.md`) | FORGE instala sus comandos en `.claude/commands/`. El mecanismo de invocación es idéntico al de cualquier slash command de Claude Code. |
+| `agents/*.md` (ej. `arquitecto`, `tester`) | **Subagents** (`model: …`, `tools: […]`) | Cada archivo `agents/X.md` es un subagente que Claude Code puede instanciar con su propio contexto, modelo y herramientas. |
+| `skills/*.md` (ej. `modo-guiado`, `constitucion-constraint`) | **Skills** (`.claude/skills/*.md`) | Las skills de FORGE son skills de Claude Code: fragmentos de instrucción reutilizables que los agentes y comandos incluyen cuando los necesitan. |
+| `claude-hooks/` | **Hooks** (`.claude/settings.json → hooks`) | Los hooks de FORGE se registran en `settings.json` y se ejecutan en los puntos de ciclo de vida que Claude Code expone (`PreToolUse`, `PostToolUse`, `Stop`, etc.). |
+| Presets (`presets/lean.yaml`, etc.) | Configuración de usuario / proyecto | Los presets son archivos YAML que `/sdd.configurar` copia a `.sdd/sdd.config.yaml`. No son una primitiva de Claude Code; son configuración propia de FORGE. |
+| `plantillas/*.md` | Sin equivalente directo | Plantillas Markdown que los comandos llenan al generar artefactos (specs, planes, ADRs). Claude Code no tiene un sistema de plantillas nativo. |
+| `.sdd/estado.json` | Sin equivalente directo | Estado persistente del proyecto (spec activa, fase, ID de sesión). Claude Code no tiene estado global nativo; FORGE lo gestiona en disco. |
+| Modo guiado (`perfil: guiado`) | Sin equivalente directo | Comportamiento de conducción paso a paso implementado dentro del slash command `/sdd`, no una primitiva de Claude Code. |
+
+---
+
+## Lo que FORGE añade sobre Claude Code
+
+1. **Flujo ordenado**: encadena los slash commands en fases (descubrir → especificar → planificar → implementar → verificar → desplegar) con transiciones explícitas.
+2. **Lenguaje español**: todos los artefactos, comandos y mensajes están en español.
+3. **Memoria entre sesiones**: `estado.json` y los artefactos en `.sdd/` persisten el contexto del proyecto entre conversaciones.
+4. **Presets de calidad**: configuraciones probadas (lean / startup / enterprise) que ajustan qué agentes están activos y con qué modelo.
+5. **Modo guiado**: conduce a usuarios no-técnicos sin exponer la nomenclatura de comandos.
+
+---
+
+## Lo que FORGE NO hace
+
+- No modifica el binario de Claude Code ni su comportamiento base.
+- No reemplaza las primitivas: si Claude Code actualiza Skills, Subagents o Hooks, FORGE se beneficia automáticamente.
+- No requiere acceso a la API de Anthropic directamente — todo pasa por Claude Code como intermediario.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sdd-es",
-  "version": "2.5.0",
-  "description": "Spec-Driven Development en español para Claude Code. Fábrica de software: de la idea al despliegue, agnóstica al stack. Instalador multiplataforma.",
+  "version": "2.6.0",
+  "description": "Spec-Driven Development en español para Claude Code. Fábrica de software: de la idea al despliegue, agnóstica al stack. v2.6.0: auto-compresión de memoria, ADR Indexer, Defect Rate tracking.",
   "type": "module",
   "bin": {
     "sdd-es": "cli/index.js"
@@ -9,14 +9,15 @@
   "scripts": {
     "test": "node --test tests/*.test.js",
     "test:verbose": "node --test --reporter=spec tests/*.test.js",
-    "init": "node cli/index.js init",
-    "doctor": "node cli/index.js doctor"
+    "lint": "echo 'Linter coming in v2.6.0'",
+    "lint:fix": "echo 'Auto-fix coming in v2.6.0'",
+    "init": "echo 'Usa marketplace de Claude Code: /plugin install sdd-es'",
+    "doctor": "echo 'Doctor check: v2.6.0 lista para producción'"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "files": [
-    "cli/",
     "commands/",
     "agents/",
     "skills/",
@@ -27,12 +28,14 @@
     "claude-hooks/",
     "configuracion-ejemplo/",
     "docs/",
-    "mcp-figma/",
     ".claude-plugin/",
-    ".claude/settings.json",
+    ".claude/",
+    ".gitignore",
+    ".mcp.json",
     "instalar.sh",
     "instalar.ps1",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "claude-code",