sdd-es 2.0.0

package/docs/EJEMPLOS.md

@@ -0,0 +1,212 @@
+# Ejemplos Completos de Uso
+
+## Ejemplo 1: Proyecto nuevo en blanco
+
+```bash
+# 1. Instalar plugin
+cd mi-proyecto
+bash sdd-es/instalar.sh
+
+# 2. Inicializar
+claude
+> /sdd.constitucion
+
+# Claude detecta package.json con React+Express+PostgreSQL
+# Hace 4-5 preguntas: propósito, audiencia, no-negociables, restricciones
+# Genera .sdd/memoria/constitucion.md v1.0.0
+
+> /sdd.configurar
+# Revisas agentes y modelos. Confirmas defaults o ajustas.
+
+> /sdd.especificar Quiero agregar autenticación con magic links por email
+# Claude crea .sdd/especificaciones/2026-06-08-auth-magic-links/spec.md
+# Marca 3 puntos con [NECESITA_ACLARACION]
+
+> /sdd.aclarar
+# Claude hace preguntas agrupadas:
+#   1. ¿Magic link expira en cuántos minutos? a)5  b)15  c)60
+#   2. ¿Un solo uso o múltiples? a)único b)múltiples
+#   3. ¿Qué pasa si el usuario solicita 5 links seguidos? a)rate limit b)reemplazar último
+# Respondes: 1.b, 2.a, 3.a
+# Spec actualizada
+
+> /sdd.checklist
+# Resultado: APROBADA (cobertura 95%)
+
+> /sdd.planificar
+# arquitecto: define estructura (auth/, magic-link.service.ts, ...)
+# disenador-api: 2 endpoints: POST /auth/magic-link, GET /auth/verify
+# asesor-datos: tabla magic_links con TTL via cron
+# critico: identifica 3 riesgos (race conditions, email bounce, rate limit bypass)
+# seguridad: recomienda hashear el token antes de guardarlo
+# Plan generado
+
+> /sdd.planificar aprobar
+# ✅ Plan aprobado
+
+> /sdd.tareas
+# 12 tareas generadas, distribuidas en 6 agentes
+
+> /sdd.analizar
+# Verifica que todos los CAs estén cubiertos
+# Resultado: APROBADO
+
+> /sdd.implementar
+# Ejecuta T001 (arquitecto, tipos)
+# T002 (asesor-datos, migración)
+# T003 (desarrollador-backend, service)
+# ... 12 tareas con verificación entre cada una
+# Tests pasan
+# Revisor da APROBADO
+
+> /sdd.verificar
+# Cruza código contra los 8 CAs
+# Resultado: APROBADA (100%)
+
+> /sdd.snapshot
+# Actualiza .sdd/SNAPSHOT.md con la nueva funcionalidad
+```
+
+## Ejemplo 2: Cambio micro
+
+```bash
+> /sdd.especificar Corregir typo en el texto del botón de login
+# Detecta MICRO automáticamente
+# Genera spec mínima + plan mínimo + 1 tarea
+# Pregunta: "¿Ejecutar ahora?" → sí
+# Cambia el texto, marca como completado
+# Total: 30 segundos
+```
+
+## Ejemplo 3: Feature grande con calidad máxima
+
+```bash
+> /sdd.especificar Migrar de REST a GraphQL manteniendo el endpoint REST en deprecación
+
+> /sdd.aclarar
+# 12 puntos de aclaración (gran cambio)
+
+> /sdd.checklist
+# Necesita revisión: faltan métricas de éxito medibles
+
+> /sdd.aclarar
+# Resuelve los puntos faltantes
+
+> /sdd.checklist
+# APROBADA
+
+> /sdd.planificar
+# Todos los agentes participan
+# Plan tiene 17 secciones, 25 archivos, 6 ADRs generados
+
+> /sdd.planificar revisar
+# Discutes 3 ajustes con el arquitecto
+
+> /sdd.planificar aprobar
+
+> /sdd.tareas
+# 47 tareas generadas
+
+> /sdd.analizar
+# OBSERVACIONES: 2 riesgos sin mitigación
+
+# Editar manualmente tareas.md para añadir mitigaciones, o:
+> /sdd.tareas regenerar
+
+> /sdd.analizar
+# APROBADO
+
+> /sdd.implementar
+# 4 horas de implementación. Tareas en orden por fase.
+
+> /sdd.verificar
+> /sdd.snapshot
+```
+
+## Ejemplo 4: Importar spec de Jira/Notion
+
+```bash
+> /sdd.importar https://mi-org.notion.site/Feature-XYZ
+# Claude fetchea, extrae lo que puede
+# Genera spec con secciones rellenadas
+# Marca 5 puntos con [NECESITA_ACLARACION]
+# Sección 99 documenta qué se importó y qué se perdió
+
+> /sdd.aclarar
+# Resuelves los puntos pendientes
+```
+
+## Ejemplo 5: Personalización con hook de Git
+
+`.sdd/hooks/antes_especificar.sh`:
+```bash
+#!/bin/bash
+# Verifica que estés en main antes de empezar una spec nueva
+RAMA=$(git branch --show-current)
+if [ "$RAMA" != "main" ]; then
+  echo "⚠️  No estás en main (estás en $RAMA)"
+  echo "¿Continuar de todos modos? (s/N)"
+  read RESP
+  [ "$RESP" != "s" ] && exit 1
+fi
+```
+
+`.sdd/hooks/despues_implementar.sh`:
+```bash
+#!/bin/bash
+# Lint + commit + push automático
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json | cut -d'"' -f4)
+
+# Lint
+npm run lint --fix
+
+# Commit
+git add -A
+git commit -m "feat: implementa ${SPEC_ID}
+
+Spec: .sdd/especificaciones/${SPEC_ID}/spec.md
+Plan: .sdd/especificaciones/${SPEC_ID}/plan.md
+
+Generado con SDD-ES v2.0.0"
+
+# Push opcional
+read -p "¿Push a remoto? (s/N) " PUSH
+[ "$PUSH" == "s" ] && git push origin HEAD
+```
+
+## Ejemplo 6: Solo frontend
+
+`.sdd/sdd.config.yaml`:
+```yaml
+agentes:
+  arquitecto:
+    activo: true
+    modelo: opus
+  desarrollador-frontend:
+    activo: true
+    modelo: sonnet
+  tester:
+    activo: true
+    modelo: sonnet
+  revisor:
+    activo: true
+    modelo: opus
+  
+  # Desactivar lo que no aplica
+  disenador-api:
+    activo: false
+  desarrollador-backend:
+    activo: false
+  asesor-datos:
+    activo: false
+  operaciones:
+    activo: false
+  critico:
+    activo: false
+  seguridad:
+    activo: false
+  documentador:
+    activo: false
+```
+
+El plugin solo invoca a los activos, ahorrando tokens y tiempo.

package/docs/FABRICA.md

@@ -0,0 +1,185 @@
+# La Fábrica: de la idea al despliegue sin saber programar
+
+Este documento es un recorrido completo para alguien que tiene una idea pero nunca ha escrito código. SDD-ES actúa como fábrica: tú describes, confirmas, y el sistema construye y publica.
+
+---
+
+## Antes de empezar
+
+Solo necesitas:
+- **Claude Code** instalado ([claude.ai/code](https://claude.ai/code))
+- **Node.js 18+** instalado ([nodejs.org](https://nodejs.org))
+- Una **cuenta en Vercel** (gratis) si quieres publicar en internet
+
+Para instalar SDD-ES, abre una terminal y escribe:
+```
+npx sdd-es init
+```
+
+Eso es todo. SDD-ES se instala solo.
+
+---
+
+## Escenario: "Quiero una app para anotar mis ideas diarias"
+
+Usaremos este ejemplo de principio a fin. Tú solo escribes lo que está en **negrita**; el resto lo hace Claude.
+
+---
+
+### Paso 1 — Cuéntale tu idea
+
+Abre Claude Code y escribe:
+
+> **quiero crear una app para anotar mis ideas diarias**
+
+Claude pregunta tres cosas simples para entender bien:
+
+> ¿Quién va a usar la app, solo tú o varias personas?
+
+**Solo yo.**
+
+> ¿Quieres que las notas se guarden para siempre o solo durante la sesión?
+
+**Para siempre.**
+
+> ¿Quieres acceder desde el móvil también, o solo desde tu computadora?
+
+**Desde cualquier lado.**
+
+Claude elige automáticamente el mejor stack para esto (una web app con base de datos) y te lo explica sin tecnicismos:
+
+> "Perfecto. Voy a construirte una web pequeña que guarda tus notas. Funciona en el navegador y las guarda para siempre. ¿Arrancamos? (responde *sí*)"
+
+**sí**
+
+---
+
+### Paso 2 — Claude construye la app
+
+Claude trabaja solo. Ves mensajes como:
+
+```
+🔧 Creando la estructura de la app...
+🔧 Implementando: guardar nota nueva...  ✅
+🔧 Implementando: ver todas las notas... ✅
+🔧 Implementando: borrar una nota...     ✅
+🔧 Probando que todo funciona...         ✅ 3/3 pruebas pasadas
+```
+
+Cuando termina:
+
+> "¡Tu app está lista! Tiene 3 funciones que probé y funcionan. Para publicarla en internet, solo dime 'despliégala' y lo hago yo."
+
+---
+
+### Paso 3 — Publicar en internet
+
+**despliégala**
+
+Claude hace una verificación antes de publicar (para no subir nada roto):
+
+```
+✅ Pruebas: pasadas
+✅ Sin errores de código
+✅ Sin información privada expuesta
+```
+
+Luego pregunta una vez más para confirmar:
+
+> "Voy a publicar tu app en Vercel (gratis). Escribe *desplegar* para confirmar."
+
+**desplegar**
+
+```
+🚀 Publicando...
+✅ App publicada en: https://tu-app.vercel.app
+✅ Comprobando que funciona... responde en 312ms — todo bien.
+```
+
+---
+
+### Paso 4 — Tu app está en internet
+
+Abre `https://tu-app.vercel.app` en cualquier navegador, incluso desde el móvil. Funciona.
+
+---
+
+### Añadir cosas después
+
+En cualquier momento puedes decirle a Claude qué quieres añadir:
+
+> **quiero que también pueda buscar entre mis notas**
+
+Claude toma esa frase, la convierte en especificación, la implementa, la prueba y la publica — siguiendo el mismo ciclo.
+
+---
+
+## Escenario alternativo: "Quiero crear una herramienta para Claude"
+
+Si quieres que Claude pueda hacer algo nuevo (consultar una API, acceder a tus archivos, buscar en tu base de datos), usa `/sdd.crear-mcp`:
+
+> **quiero una herramienta que consulte el precio del dólar en tiempo real**
+
+Claude pregunta:
+> "¿De qué fuente quieres sacar el precio? ¿Tienes alguna API favorita, o buscamos una gratuita?"
+
+**busca una gratuita**
+
+Claude encuentra una API pública, implementa la herramienta, la empaqueta y te da la instrucción de instalación:
+
+```
+claude mcp add precio-dolar -- node "/ruta/mcp-precio-dolar/src/index.js"
+```
+
+Después de eso, puedes decirle a Claude: *"¿A cuánto está el dólar?"* y lo sabrá en tiempo real.
+
+---
+
+## El ciclo completo
+
+```
+Tu idea en palabras
+      │
+      ▼
+/sdd.crear-app  o  /sdd.crear-mcp
+(Claude elige el stack, construye, prueba)
+      │
+      ▼
+/sdd.desplegar
+(gate de calidad → tu confirmación → publicación → health check)
+      │
+      ▼
+🌐 App en internet  /  🔌 Tool instalada en Claude
+      │
+      ▼
+/sdd.especificar [qué quieres añadir]
+(el ciclo se repite para cada mejora)
+```
+
+Cada flecha tiene un control: no se publica sin pruebas verdes, no se publica sin tu confirmación. Eso es lo que convierte esta herramienta en una fábrica con estándares de ingeniería altos, no solo un generador de código.
+
+---
+
+## Si algo sale mal
+
+Claude nunca te deja con una app rota publicada. Si algo falla:
+
+- **Durante la construcción**: Claude te lo dice y lo corrige antes de seguir.
+- **Durante el despliegue**: si la app no responde después de publicarse, Claude te avisa y revierte.
+- **En cualquier momento**: escribe `/sdd.estado` para ver en qué punto estás.
+
+---
+
+## Comandos de esta fábrica
+
+| Lo que quieres hacer | Lo que escribes |
+|----------------------|-----------------|
+| Crear una app desde cero | `/sdd.crear-app [describe tu idea]` |
+| Crear una herramienta para Claude | `/sdd.crear-mcp [describe qué hace]` |
+| Publicar en internet | `/sdd.desplegar` |
+| Comprobar que sigue funcionando | `/sdd.canary` |
+| Añadir una función nueva | `/sdd.especificar [qué quieres añadir]` |
+| Ver el estado de tu proyecto | `/sdd.estado` |
+| Pedir ayuda | `/sdd.ayuda` |
+
+No necesitas memorizar estos comandos. Puedes escribir directamente lo que quieres hacer en español y Claude te enrutará al correcto.

package/docs/FILOSOFIA.md

@@ -0,0 +1,61 @@
+# Filosofía de SDD-ES
+
+## ¿Qué es SDD?
+
+**Spec-Driven Development** (Desarrollo Guiado por Especificaciones) es una metodología donde:
+
+1. **La especificación es la fuente de verdad**, no el código.
+2. El código es un **artefacto derivado** de la spec, no al revés.
+3. Cada cambio empieza definiendo *qué* y *por qué* antes de *cómo*.
+
+## ¿Por qué SDD funciona con IA?
+
+Los modelos de IA son muy creativos — demasiado para nuestro gusto cuando programan. SDD canaliza esa creatividad imponiendo restricciones estructuradas:
+
+- La spec define el espacio de soluciones aceptables
+- La constitución limita las decisiones técnicas
+- Las tareas atómicas reducen la deriva en cada paso
+- Los criterios de verificación atrapan errores antes de que se acumulen
+
+**Resultado**: implementación predecible, auditable, sin "magia" en el medio.
+
+## Inspiración
+
+SDD-ES integra ideas de:
+
+- **[github/spec-kit](https://github.com/github/spec-kit)**: constitution, sync impact reports, hooks de extensión, versionado semántico, checklist como tests de los requisitos.
+- **[LiorCohen/sdd](https://github.com/LiorCohen/sdd)**: agentes especializados por rol con modelo asignado, comandos en lenguaje natural, estructura específica con INDEX/SNAPSHOT/glossary, verificación cruzada.
+- **OpenSpec**, **SpecWeave**, **disciplined-agentic-engineering**: schemas custom, BDD, mecanismos de auditoría.
+
+## Diferencias de SDD-ES
+
+1. **100% español**: comandos, plantillas, agentes, documentación
+2. **Agnóstico al stack**: TypeScript, Python, Rust, Go, Java, C#, Ruby, PHP, etc.
+3. **Sin acoplamiento a Git/GitHub/GitLab**: tú integras tu VCS desde hooks personalizados
+4. **Configurable**: cualquier agente se activa/desactiva, cualquier modelo se reasigna
+5. **Recomendaciones de modelos**: cada agente trae una recomendación justificada
+6. **Personalización exhaustiva**: todo es Markdown plano editable
+
+## Cuándo usar SDD-ES
+
+✅ **Usar cuando:**
+- Tienes una idea de feature pero no sabes cómo descomponerla
+- El proyecto requiere trazabilidad de decisiones
+- Trabajas en equipo y necesitas alineación
+- Quieres que la IA implemente con rigor (no improvisando)
+- El cambio toca múltiples archivos o capas
+
+❌ **No usar (overhead innecesario):**
+- Arreglar un typo
+- Cambiar un literal de string
+- Ajustes de CSS visual sin lógica
+
+> Para esos casos hay flujo "micro" — la IA detecta automáticamente que es trivial y simplifica el proceso.
+
+## Los 5 principios de SDD-ES
+
+1. **Spec antes que código** — siempre
+2. **Constitución es ley** — el plan no puede contradecirla sin justificación documentada
+3. **Cada decisión es trazable** — del CA a la línea de código que lo implementa
+4. **Agentes especializados** — un experto por dominio supera a un generalista
+5. **Verificación independiente** — la IA que verifica no es la misma que implementa

package/docs/FLUJO.md

@@ -0,0 +1,149 @@
+# Flujo Completo de SDD-ES
+
+## Diagrama del flujo
+
+```
+                    ┌──────────────────────┐
+                    │   /sdd.constitucion  │  ← Solo la primera vez
+                    │   (principios del    │
+                    │    proyecto)         │
+                    └──────────┬───────────┘
+                               │
+                    ┌──────────▼───────────┐
+                    │   /sdd.configurar    │  ← Opcional: ajustar agentes/modelos
+                    └──────────┬───────────┘
+                               │
+                ┌──────────────▼───────────┐
+                │   /sdd.especificar       │
+                │   (qué + por qué)        │
+                └──────────────┬───────────┘
+                               │
+                       ┌───────┴───────┐
+                       │   ¿micro?     │
+                       └───┬───────┬───┘
+                  sí ─────┘       └────── no
+                           │              │
+                           │     ┌────────▼────────┐
+                           │     │  /sdd.aclarar    │ ← Resolver [NECESITA_ACLARACION]
+                           │     └────────┬────────┘
+                           │              │
+                           │     ┌────────▼────────┐
+                           │     │  /sdd.checklist  │ ← Validar calidad
+                           │     └────────┬────────┘
+                           │              │
+                           │     ┌────────▼────────┐
+                           │     │  /sdd.planificar │ ← Plan técnico
+                           │     └────────┬────────┘
+                           │              │
+                           │     ┌────────▼─────────┐
+                           │     │  /sdd.planificar │ ← Aprobar plan
+                           │     │      aprobar     │
+                           │     └────────┬─────────┘
+                           │              │
+                           │     ┌────────▼────────┐
+                           │     │  /sdd.tareas     │ ← Desglose atómico
+                           │     └────────┬────────┘
+                           │              │
+                           │     ┌────────▼────────┐
+                           │     │  /sdd.analizar   │ ← Auditoría cruzada
+                           │     └────────┬────────┘
+                           │              │
+                           └──────────────┼──────► (las micro vuelven aquí)
+                                          │
+                              ┌───────────▼──────────┐
+                              │  /sdd.implementar    │ ← Ejecutar con agentes
+                              └───────────┬──────────┘
+                                          │
+                              ┌───────────▼──────────┐
+                              │  /sdd.verificar      │ ← Verificación final
+                              └───────────┬──────────┘
+                                          │
+                              ┌───────────▼──────────┐
+                              │  /sdd.snapshot       │ ← Actualizar estado producto
+                              └───────────┬──────────┘
+                                          │
+                                          ▼
+                                    ✅ COMPLETADO
+                                          │
+                                          └─── /sdd.especificar [siguiente]
+```
+
+## Flujos según tamaño del cambio
+
+### Micro (≤3 archivos, <10 líneas)
+```
+/sdd.especificar [descripción]
+→ Detecta micro → genera spec+plan+tareas automáticamente → implementa
+```
+
+### Pequeño (1 feature simple)
+```
+/sdd.especificar [descripción]
+/sdd.planificar
+/sdd.planificar aprobar
+/sdd.tareas
+/sdd.implementar
+```
+
+### Mediano (múltiples componentes)
+```
+/sdd.especificar [descripción]
+/sdd.aclarar
+/sdd.planificar
+/sdd.planificar aprobar
+/sdd.tareas
+/sdd.implementar
+/sdd.verificar
+```
+
+### Grande (sistema nuevo, calidad máxima)
+```
+/sdd.constitucion          (actualizar si hay nuevos principios)
+/sdd.especificar [descripción]
+/sdd.aclarar
+/sdd.checklist
+/sdd.planificar
+/sdd.planificar aprobar
+/sdd.tareas
+/sdd.analizar              ← clave para grandes
+/sdd.implementar
+/sdd.verificar
+/sdd.snapshot
+```
+
+## Reanudación entre sesiones
+
+Si cierras Claude Code y vuelves después:
+
+```
+/sdd.estado           ← muestra dashboard
+/sdd.implementar continuar  ← retoma desde la última tarea
+```
+
+El estado se guarda en `.sdd/estado.json` y `.sdd/especificaciones/{ID}/.estado-tareas.json`.
+
+## El sprint completo: de la idea al despliegue
+
+SDD-ES implementa un sprint estructurado de extremo a extremo. Cada fase alimenta a la siguiente y nada pasa sin verificación. Mapeo de las fases a los comandos:
+
+| Fase del sprint | Qué ocurre | Comandos SDD-ES |
+|-----------------|-----------|-----------------|
+| **Pensar** | Encuadrar el problema, sacar contexto de una idea vaga | `/sdd.constitucion`, `/sdd.descubrir` |
+| **Planear** | Capturar requisitos, diseñar, auditar el plan | `/sdd.especificar`, `/sdd.aclarar`, `/sdd.planificar`, `/sdd.analizar` |
+| **Construir** | Implementar con agentes especializados | `/sdd.implementar` |
+| **Revisar** | Revisión independiente de calidad y cumplimiento | `/sdd.verificar` (+ agente `revisor`) |
+| **Probar** | QA en navegador real, no solo unitarios | `/sdd.qa` |
+| **Publicar** | Despliegue verificado + monitoreo | `/sdd.desplegar`, `/sdd.canary` |
+| **Reflexionar** | Capturar aprendizajes, actualizar el estado del producto | `/sdd.retro`, `/sdd.snapshot` |
+
+```
+Pensar → Planear → Construir → Revisar → Probar → Publicar → Reflexionar
+  │                                                                │
+  └──────────────── /sdd.especificar [siguiente feature] ◄────────┘
+```
+
+La diferencia con "pídele a la IA que lo haga" es que **cada flecha tiene un control**: no se construye sin spec, no se publica sin tests verdes y QA, no se cierra sin verificación independiente. Esa es la garantía de estándar de ingeniería alto.
+
+### Flujo "fábrica" para no-programadores (perfil guiado)
+
+En perfil `guiado`, el usuario no ve los comandos. Describe lo que quiere, confirma con "sí", y el sistema recorre el sprint completo explicando cada paso en lenguaje natural y publicando al final. Ver [FABRICA.md](FABRICA.md).