sdd-es 2.0.0 → 2.5.0

package/docs/EJEMPLO-PRACTICA.md

@@ -1,383 +0,0 @@
-# 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

package/docs/EJEMPLOS.md

@@ -1,212 +0,0 @@
-# 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.