sdd-es 2.0.0 → 2.6.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/mcp-figma/README.md

@@ -1,158 +0,0 @@
-# sdd-figma-mcp
-
-MCP server local para integración de Figma con proyectos que usan SDD-ES. Lo usa el agente `desarrollador-frontend` para analizar el sistema de diseño del proyecto, traer componentes de Figma y generar código adaptado — sin romper lo que ya existe.
-
-## Qué hace
-
-| Herramienta | Qué resuelve |
-|---|---|
-| `analizar_sistema_diseño` | Lee tokens, colores, tipografía y componentes del proyecto local |
-| `evaluar_ui_existente` | Score 0-100 + problemas + sugerencias de mejora |
-| `conectar_figma` | Verifica PAT y metadata del archivo |
-| `listar_componentes` | Lista componentes publicados en el archivo Figma |
-| `traer_componente` | Detalle completo de un nodo: estructura, fills, texto, dimensiones |
-| `mapear_estilos` | Cruza colores/tipografía de Figma con tokens del proyecto |
-| `generar_componente` | Código React/Vue adaptado al sistema de diseño local |
-| `sugerir_mejoras` | Lista priorizada de mejoras al design system |
-
-## Instalación
-
-### 1. Sin dependencias — listo para ejecutar
-
-No hay `npm install`. El servidor usa exclusivamente módulos built-in de Node.js (`readline`, `fs`, `path`) y `fetch` nativo (disponible desde Node 18). El `package.json` es solo un descriptor — no instala nada.
-
-### 2. Obtener el Personal Access Token de Figma
-
-1. Abre Figma → Menú de usuario (esquina superior derecha) → **Settings**
-2. Pestaña **Security** → **Personal access tokens** → **Generate new token**
-3. Dale un nombre (ej. `sdd-figma-mcp`) y copia el token
-
-### 3. Definir FIGMA_PAT como variable de entorno del sistema
-
-El MCP lee el token desde `process.env.FIGMA_PAT` — **no está hardcodeado en ningún archivo de configuración** para evitar que quede en el repositorio.
-
-Claude Code hereda las variables de entorno de la sesión donde se lanza, así que basta con definirla una vez en el sistema:
-
-**Windows (PowerShell, permanente para el usuario):**
-```powershell
-[System.Environment]::SetEnvironmentVariable("FIGMA_PAT", "tu-token-aqui", "User")
-# Cierra y vuelve a abrir la terminal para que tome efecto
-```
-
-**Windows (solo sesión actual):**
-```powershell
-$env:FIGMA_PAT = "tu-token-aqui"
-```
-
-**macOS / Linux (permanente):**
-```bash
-echo 'export FIGMA_PAT="tu-token-aqui"' >> ~/.zshrc   # o ~/.bashrc
-source ~/.zshrc
-```
-
-> Si el proyecto tiene un `.env` que Claude Code carga automáticamente, también puedes agregar `FIGMA_PAT=tu-token` ahí — el proceso Node lo hereda igual.
-
-### 4. Registrar el MCP en Claude Code
-
-Agrega esto a tu `.claude/settings.json` (o `~/.claude/settings.json` para uso global):
-
-```json
-{
-  "mcpServers": {
-    "sdd-figma": {
-      "command": "node",
-      "args": ["/ruta/absoluta/al/sdd-lite/mcp-figma/src/index.js"]
-    }
-  }
-}
-```
-
-No hay campo `env` — el servidor hereda `FIGMA_PAT` directamente del entorno del sistema (paso 3). Así el token nunca queda registrado en ningún archivo de configuración del repositorio.
-
-> Reemplaza `/ruta/absoluta/al/sdd-lite` con la ruta real donde instalaste SDD-ES.
-> En Windows usa barras invertidas dobles: `"c:\\\\Users\\\\usuario\\\\sdd-lite\\\\mcp-figma\\\\src\\\\index.js"`
-
-### 5. Verificar
-
-Reinicia Claude Code y ejecuta en cualquier proyecto frontend:
-
-```
-analizar_sistema_diseño({ project_root: "." })
-```
-
-Deberías ver el perfil del sistema de diseño del proyecto.
-
-## Cómo encontrar el file_key de Figma
-
-La URL de Figma tiene este formato:
-
-```
-https://www.figma.com/file/ABCDEF123456/nombre-del-archivo?node-id=0:1
-                           ^^^^^^^^^^^^
-                           este es el file_key
-```
-
-## Cómo encontrar el node_id
-
-1. Selecciona el frame o componente en Figma
-2. La URL cambia a: `?node-id=123:456`
-3. Ese valor (`123:456` o en formato `123-456`) es el `node_id`
-
-## Flujo típico de uso
-
-```
-# 1. Analiza lo que ya tiene el proyecto
-analizar_sistema_diseño({ project_root: "/mi/proyecto" })
-
-# 2. Conecta con el archivo de Figma
-conectar_figma({ file_key: "ABCDEF123456" })
-
-# 3. Lista los componentes disponibles
-listar_componentes({ file_key: "ABCDEF123456", filter: "Button" })
-
-# 4. Trae el componente que quieres implementar
-traer_componente({ file_key: "ABCDEF123456", node_id: "123:456" })
-
-# 5. Verifica que los estilos tienen equivalente en el proyecto
-mapear_estilos({ file_key: "ABCDEF123456", node_id: "123:456", project_root: "/mi/proyecto" })
-
-# 6. Genera el código adaptado
-generar_componente({ file_key: "ABCDEF123456", node_id: "123:456", project_root: "/mi/proyecto" })
-```
-
-## Stacks soportados
-
-| Framework | CSS | Estado |
-|---|---|---|
-| React / Next.js | Tailwind CSS | ✅ Completo |
-| React / Next.js | CSS Modules | ✅ Completo |
-| Vue 3 | Tailwind / Scoped CSS | ✅ Completo |
-| React / Next.js | styled-components | ⚠️ Parcial (genera CSS Module) |
-| Angular | Cualquiera | ⚠️ Genera React, ajusta manualmente |
-| Svelte | Cualquiera | 🔜 En roadmap |
-
-## Variables de entorno
-
-| Variable | Requerida | Descripción |
-|---|---|---|
-| `FIGMA_PAT` | Sí | Personal Access Token de Figma |
-
-## Estructura del proyecto
-
-```
-mcp-figma/
-├── src/
-│   ├── index.js                  ← Servidor MCP + definición de tools
-│   ├── mcp.js                    ← Protocolo JSON-RPC 2.0 sobre stdio (sin deps)
-│   ├── figma-client.js           ← Cliente HTTP de la API de Figma
-│   ├── design-system-analyzer.js ← Análisis del sistema de diseño local
-│   ├── style-mapper.js           ← Mapeo de estilos Figma ↔ tokens locales
-│   └── component-generator.js   ← Generación de código por framework
-└── package.json                  ← Cero dependencias — solo descriptor
-```
-
-## Limitaciones conocidas
-
-- La detección de tokens en Tailwind usa análisis estático de texto (no ejecuta el módulo), por lo que configs muy dinámicas pueden no detectarse completamente
-- La generación de componentes es un punto de partida — siempre revisa accesibilidad, props faltantes y manejo de estado
-- La API de Figma Variables (tokens del sistema de diseño de Figma) requiere plan Professional o superior

package/mcp-figma/package.json

@@ -1,7 +0,0 @@
-{
-  "name": "sdd-figma-mcp",
-  "version": "1.0.0",
-  "description": "MCP server para integración de Figma con SDD-ES — cero dependencias externas",
-  "type": "module",
-  "main": "src/index.js"
-}