sdd-es 2.0.0 → 2.6.0

package/docs/SEGURIDAD-PARA-NOTECNICOS.md

@@ -0,0 +1,280 @@
+# 🔐 Seguridad para No-Técnicos
+
+> SDD-ES maneja tokens de GitHub y Vercel. Esta guía te explica qué son, cómo protegerlos, y qué hacer si cometes un error.
+
+---
+
+## ¿Qué es un "token"?
+
+Un **token** es como una **contraseña especial** que funciona solo para una cosa.
+
+### Comparación
+
+```
+Contraseña normal:
+├─ Acceso a: email, redes sociales, archivos, TODO
+└─ Riesgo: si alguien la roba, controla tu cuenta
+
+Token:
+├─ Acceso a: SOLO GitHub (o SOLO Vercel)
+├─ Duración: puedes ponerle límite de tiempo
+└─ Riesgo: si alguien lo roba, SOLO puede hacer lo que le diste permiso
+```
+
+**Ejemplo real:**
+```
+Token de GitHub para SDD-ES:
+├─ ✅ PUEDE: crear repositorio, hacer commits, pushear código
+├─ ✅ PUEDE: leer público el repositorio
+└─ ❌ NO PUEDE: ver tus emails privados, cambiar contraseña, acceder a otros proyectos
+```
+
+---
+
+## ¿Por qué SDD-ES pide tokens?
+
+SDD-ES necesita tokens para:
+
+1. **GitHub:** Crear tu repositorio automáticamente (sin que escribas `git init`)
+2. **Vercel:** Publicar tu app en internet (sin que escribas `vercel deploy`)
+
+Sin tokens, tendrías que hacer todo manualmente (comandos, CLI, etc.).
+
+**Con tokens:** SDD-ES lo hace automáticamente por ti.
+
+---
+
+## 🚨 NUNCA hagas ESTO con tokens
+
+### ❌ NO 1: No compartas tu token
+
+```
+❌ MALO:
+- Enviar token por Whatsapp a un amigo
+- Pegar token en Slack o Discord
+- Guardar token en Notas o Google Docs
+- Decirle a alguien tu token
+```
+
+**¿Por qué?** Si alguien tiene tu token, puede:
+- Acceder a tu GitHub/Vercel
+- Hacer commits en tu nombre
+- Borrar repositorios
+- Cambiar configuración de apps
+
+---
+
+### ❌ NO 2: No guardes token en archivos
+
+```
+❌ MALO (SDD-ES NO hace esto):
+- No guardes token en .env
+- No lo guardes en un archivo de texto
+- No lo commitess a GitHub
+
+✅ BIEN (SDD-ES SÍ hace esto):
+- Token se usa en memoria mientras se necesita
+- Cuando termina, se borra automáticamente
+- Nunca se escribe en archivos persistentes
+```
+
+---
+
+### ❌ NO 3: No commitess archivos sensibles
+
+```
+❌ MALO:
+git add .
+git commit -m "Mi proyecto"
+[Si accidentalmente commiteas .env o credenciales]
+
+✅ BIEN:
+SDD-ES usa .gitignore para proteger:
+- .sdd/.vercel-deploy.json (metadata de deploy)
+- .env (variables de entorno)
+- Cualquier archivo con secretos
+
+[Git automáticamente ignora estos archivos]
+```
+
+---
+
+## 📋 ¿Cómo generar un token SEGURO?
+
+### Token de GitHub (para SDD-ES)
+
+**Paso 1:** Abre https://github.com/settings/tokens?type=pat
+
+**Paso 2:** Click "Generate new token" → "Fine-grained tokens"
+
+**Paso 3:** Configura permisos **MÍNIMOS**:
+```
+Repository access:
+  ✅ All repositories (SDD-ES creará uno nuevo)
+  
+Permissions:
+  ✅ Repository: READ + WRITE (crear repo, hacer commits)
+  ✅ Administration: NONE (no cambiar settings)
+  ✅ Secrets: NONE (no leer otros secrets)
+  ❌ User: NONE (no acceder emails)
+```
+
+**Paso 4:** Expiration:
+```
+⚠️ IMPORTANTE: Pon un límite de 90 días
+(No "No expiration" — riesgo si token se roba)
+```
+
+**Paso 5:** Click "Generate token", copia y **úsalo INMEDIATAMENTE**
+
+**Paso 6:** En SDD-ES, pega el token cuando pida
+
+---
+
+### Token de Vercel (para SDD-ES)
+
+**Paso 1:** Abre https://vercel.com/account/tokens
+
+**Paso 2:** Click "Create Token"
+
+**Paso 3:** Configura:
+```
+Token Name: "SDD-ES [nombre-proyecto]" (ej: SDD-ES Mi Tienda)
+Scope: Todos los equipos (o tu equipo)
+Expiration: 90 días (NO "No expiration")
+```
+
+**Paso 4:** Click "Create", copia y **úsalo INMEDIATAMENTE**
+
+---
+
+## ✅ Si generaste token correctamente
+
+```
+Después de pegar el token en SDD-ES:
+
+Sistema: "✅ Token válido"
+Sistema: "[invoca skill de GitHub/Vercel]"
+Sistema: "✅ Tu proyecto está en GitHub/Vercel"
+
+El token se BORRA de la memoria automáticamente.
+Ya NO lo necesitas más.
+```
+
+---
+
+## 🚨 Si cometiste un error (compartiste token accidentalmente)
+
+### Escenario 1: Compartiste token por Whatsapp/Slack
+
+**¿Qué hacer?**
+
+1. **IMMEDIATO — Revoca el token:**
+   - GitHub: https://github.com/settings/tokens
+   - Busca el token
+   - Click "Delete"
+
+2. **Genera uno NUEVO:**
+   - Sigue los pasos de arriba
+   - USA el nuevo en SDD-ES
+
+3. **Chequea que no pasó nada malo:**
+   - GitHub: Mira el repositorio, ¿alguien cambió código?
+   - Vercel: ¿Apps raras desplegadas?
+
+4. **Si sospechas actividad extraña:**
+   - Cambia contraseña de GitHub/Vercel
+   - Activa 2FA (autenticación de dos factores)
+
+---
+
+### Escenario 2: Accidentalmente commitease token a GitHub
+
+```
+(SDD-ES NO hace esto, pero si ocurre por error)
+
+❌ MALO: El token está en GitHub público
+         Cualquiera puede verlo en git log
+
+✅ RECUPERACIÓN:
+1. Revoca el token INMEDIATAMENTE (arriba)
+2. Borra el archivo de histórico de git:
+   git filter-branch --tree-filter 'rm -f .env' HEAD
+3. Force push: git push --force
+4. Avisa a GitHub (https://github.com/security/advisories)
+```
+
+---
+
+## 🔒 SDD-ES protege tu seguridad
+
+### Cómo SDD-ES cuida los tokens
+
+```
+✅ TOKENS EN VARIABLES DE ENTORNO (memoria)
+   └─ No se escriben en archivos
+   └─ Se borran cuando termina el script
+
+✅ VALIDACIÓN INMEDIATA
+   └─ Si token es inválido, sale rápido
+   └─ No continúa si hay problema
+
+✅ .gitignore AUTOMÁTICO
+   └─ Protege archivos sensibles
+   └─ Aunque hagas "git add .", no se commitean
+
+✅ SIN GUARDAR CREDENTIALS
+   └─ sdd.config.yaml SOLO guarda URLs, no tokens
+   └─ Tokens se usan ONCE y desaparecen
+```
+
+---
+
+## 📋 Checklist de Seguridad
+
+Antes de usar SDD-ES, asegúrate de:
+
+```
+[ ] Generé un token NUEVO (no uno viejo)
+[ ] Token tiene expiración 90 días (no "No expiration")
+[ ] Token tiene permisos MÍNIMOS (solo repo, no everything)
+[ ] Guardé el token en un lugar SEGURO temporalmente (1Password, Bitwarden)
+[ ] Voy a pegar el token INMEDIATAMENTE en SDD-ES
+[ ] NO voy a guardar el token en archivos
+[ ] NO voy a compartir el token en mensajes
+```
+
+---
+
+## 🆘 Emergencia: Creo que mi token fue robado
+
+```
+ACCIÓN: REVOCA INMEDIATAMENTE
+
+1. GitHub: https://github.com/settings/tokens
+   → Busca token → Click "Delete"
+
+2. Vercel: https://vercel.com/account/tokens
+   → Click "Delete"
+
+3. Genera NUEVOS tokens
+
+4. IMPORTANTE: Cambia contraseña GitHub/Vercel
+   (por si alguien también robó contraseña)
+```
+
+---
+
+## 📚 Más información
+
+- **GitHub Security:** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure
+- **Vercel Security:** https://vercel.com/docs/security
+- **OWASP (Seguridad general):** https://owasp.org/
+
+---
+
+## 💬 ¿Preguntas?
+
+Si no estás seguro sobre algo de seguridad, **mejor pregunta que arreglar después.**
+
+Abre un issue en GitHub: https://github.com/carlos060798/sdd-lite/issues

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sdd-es",
-  "version": "2.0.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,28 +9,33 @@
   "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/",
+    "craft/",
+    "design-systems/",
     "plantillas/",
     "presets/",
     "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",
@@ -42,9 +47,9 @@
     "plugin"
   ],
   "license": "MIT",
-  "homepage": "https://github.com/carlos060798/sdd-lite",
+  "homepage": "https://github.com/carlos060798/FORGE",
   "repository": {
     "type": "git",
-    "url": "https://github.com/carlos060798/sdd-lite.git"
+    "url": "https://github.com/carlos060798/FORGE.git"
   }
 }

package/plantillas/job-story-mejorar-prompt.md

@@ -0,0 +1,107 @@
+---
+id: JS-PROMPT-001
+tipo: job-story
+estado: aprobada
+fecha: 2026-06-14
+versión: 1.0.0
+autor: SDD-ES
+---
+
+# Job Story — Mejorar Prompts con Claude Code
+
+## Historia principal
+
+**Cuando** estoy a punto de pedirle algo a Claude Code y no sé cómo formularlo con precisión,
+**quiero** una guía que transforme mi intención vaga en un prompt profesional paso a paso,
+**para** obtener resultados predecibles, manteniendo el trabajo dentro del plan de la spec activa.
+
+---
+
+## Contexto del problema
+
+Un prompt vago produce resultados impredecibles porque Claude toma decisiones discrecionales
+sobre el alcance, el enfoque y las dependencias. El mismo prompt puede generar desde un
+try-catch de 3 líneas hasta un sistema de logging con Winston, rotación de archivos y niveles
+de severidad — dependiendo del momento y el contexto de la sesión.
+
+La diferencia entre un resultado útil y uno que hay que descartar no está en Claude Code,
+está en la calidad de las instrucciones. Esta job story captura la necesidad de cerrar esa
+brecha de forma sistemática, sin depender de la experiencia del usuario.
+
+---
+
+## Criterios de Aceptación
+
+- **CA-001:** dado un prompt vago de 1-2 frases, la skill produce una versión profesional
+  con los 5 componentes (Contexto, Tarea, Restricciones, Formato, Verificación) cuando aplican
+- **CA-002:** la versión mejorada incluye siempre una restricción explícita sobre el alcance
+  de la spec activa (`No salgas de lo definido en .sdd/especificaciones/`)
+- **CA-003:** si el prompt solicita algo fuera de la fase o feature actual (según
+  `.sdd/estado.json`), la skill lo detecta y advierte antes de reescribir
+- **CA-004:** el output muestra la justificación de cada componente añadido, no solo el
+  prompt mejorado
+- **CA-005:** la skill se puede invocar con `/mejorar-prompt "texto del prompt vago"`
+- **CA-006:** si el prompt ya es profesional (tiene ≥4 de los 5 componentes), la skill lo
+  confirma y no reescribe innecesariamente
+
+---
+
+## Escenarios BDD
+
+### Escenario 1 — Prompt de implementación vago
+
+```
+Dado:  el usuario escribe "añade autenticación"
+Cuando: invoca /mejorar-prompt "añade autenticación"
+Entonces: obtiene una versión profesional con:
+  - Contexto del stack actual (Express + TypeScript, endpoints existentes)
+  - Tarea acotada (qué tipo de autenticación, qué endpoints proteger)
+  - Restricciones (no romper endpoints existentes, no instalar dependencias no aprobadas)
+  - Verificación con tests que cubran el happy path y el rechazo de tokens inválidos
+Y: cada componente va acompañado de una línea explicando por qué se añadió
+```
+
+### Escenario 2 — Prompt fuera de spec
+
+```
+Dado:  la spec activa en .sdd/estado.json es "login con email"
+  Y:   el usuario escribe "añade un sistema de pagos con Stripe"
+Cuando: invoca /mejorar-prompt
+Entonces: la skill emite una advertencia:
+  "⚠️ 'pagos con Stripe' parece estar fuera de la spec activa (login con email).
+   Para continuar tienes dos opciones:
+   1. Escribe /sdd.especificar para abrir una nueva spec de pagos
+   2. Confirma que este cambio sí forma parte de la feature actual"
+Y: no reescribe el prompt hasta recibir confirmación
+```
+
+### Escenario 3 — Prompt de debug vago
+
+```
+Dado:  el usuario escribe "no funciona el login"
+Cuando: invoca /mejorar-prompt
+Entonces: la skill detecta el patrón "depurar problema" y produce:
+  - Contexto: qué estaba haciendo cuando falló
+  - Tarea: el error exacto (pegar stack trace) y el archivo/línea
+  - Formato: "antes de corregir: (1) causa raíz (2) por qué ocurre (3) fix propuesto"
+  - Verificación: test que reproduce el bug antes del fix y pasa después
+```
+
+### Escenario 4 — Prompt ya profesional
+
+```
+Dado:  el usuario escribe un prompt con contexto, tarea, restricciones y verificación
+Cuando: invoca /mejorar-prompt
+Entonces: la skill responde "Este prompt ya tiene 4/5 componentes. Está bien estructurado."
+  Y opcionalmente sugiere el único componente que falta (si hay alguno)
+  Y no reescribe el prompt
+```
+
+---
+
+## Notas de implementación
+
+- La skill vive en `skills/mejorar-prompt/SKILL.md`
+- El agente que la ejecuta es `sonnet` (balance razonamiento / coste)
+- Lee `.sdd/estado.json` antes de reescribir para detectar el scope de la spec activa
+- Los 7 patrones de referencia están documentados en `docs-site/` bajo la sección Prompts

package/presets/enterprise.yaml

@@ -50,6 +50,12 @@ agentes:
   investigador:
     activo: true
     modelo: sonnet
+  product-designer:
+    activo: true
+    modelo: opus          # diseño de producto riguroso
+  architecture-designer:
+    activo: true
+    modelo: opus          # arquitectura crítica → opus siempre
 
 comportamiento:
   deteccion_tamano_automatica: true

package/presets/lean.yaml

@@ -46,6 +46,10 @@ agentes:
     activo: false
   investigador:
     activo: false         # no hay equipo que necesite el contexto documentado
+  product-designer:
+    activo: false         # sin diseño formal de producto
+  architecture-designer:
+    activo: false         # tú diseñas la arquitectura
 
 comportamiento:
   deteccion_tamano_automatica: true

package/presets/startup.yaml

@@ -50,6 +50,12 @@ agentes:
   investigador:
     activo: true
     modelo: sonnet
+  product-designer:
+    activo: true
+    modelo: sonnet
+  architecture-designer:
+    activo: true
+    modelo: opus          # decisiones de arquitectura → opus
 
 comportamiento:
   deteccion_tamano_automatica: true

package/skills/adr-indexer/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: adr-indexer
+model: claude-haiku-4-5
+description: Indexa decisiones arquitectónicas (ADR) desde comentarios en código
+allowed-tools: Read, Write, Bash
+---
+
+# Skill: ADR Indexer
+
+**Propósito:** Capturar automáticamente decisiones arquitectónicas de comentarios en código y mantener un índice buscable.
+
+---
+
+## Cómo Funciona
+
+### Patrón ADR en Comentarios
+
+El desarrollador (agente) deja una nota en el código:
+
+```python
+# ADR: {"decision": "Use PostgreSQL", "context": "ACID needed", "status": "accepted"}
+class Database:
+    pass
+```
+
+### Hook Captura Automáticamente
+
+Hook `agent-memory.js` detecta comentarios con patrón `ADR: {...}` y:
+1. Extrae JSON
+2. Valida estructura
+3. Guarda en `.sdd/arquitectura/ADRs.jsonl`
+
+### Usuario Consulta
+
+```bash
+/sdd.adr list
+→ Tabla de decisiones
+
+/sdd.adr search "database"
+→ Solo ADRs que mencionan "database"
+
+/sdd.adr new
+→ Captura interactiva de nueva decisión
+```
+
+---
+
+## Estructura de ADR
+
+```json
+{
+  "ts": "2026-06-14T10:30:00Z",
+  "decision": "Use PostgreSQL for relational data",
+  "context": "ACID transactions required, multi-tenant",
+  "alternatives": ["MongoDB", "Firebase"],
+  "status": "accepted",
+  "archivo": "src/database.ts",
+  "linea": 42
+}
+```
+
+**Campos:**
+- `ts` — timestamp (automático)
+- `decision` — qué se decidió
+- `context` — por qué
+- `alternatives` — opciones consideradas
+- `status` — accepted | rejected | deprecated | superseded
+- `archivo` — dónde está el código
+- `linea` — número de línea
+
+---
+
+## Ledger: `.sdd/arquitectura/ADRs.jsonl`
+
+Append-only JSONL:
+```
+{"ts":"2026-06-14T10:30:00Z","decision":"Use PostgreSQL","status":"accepted",...}
+{"ts":"2026-06-14T10:31:00Z","decision":"Use Redis for cache","status":"accepted",...}
+{"ts":"2026-06-14T10:32:00Z","decision":"JWT for auth","status":"accepted",...}
+```
+
+**Ventajas:**
+- Histórico completo
+- Búsqueda rápida (grep)
+- Estadísticas fáciles (contar, agrupar por status)
+- Reversible (append-only, nunca sobrescrito)
+
+---
+
+## Uso Interactivo
+
+### `/sdd.adr list`
+
+```
+ID | DECISION                  | CONTEXT              | STATUS
+───┼───────────────────────────┼──────────────────────┼──────────
+1  | Use PostgreSQL            | ACID needed          | accepted
+2  | Cache with Redis          | Performance req      | accepted
+3  | JWT instead of sessions   | Stateless API        | accepted
+```
+
+### `/sdd.adr search "security"`
+
+```
+ID | DECISION                | STATUS
+───┼───────────────────────────┼──────────
+1  | HTTPS only              | accepted
+2  | Validate all user input | accepted
+3  | Encrypt passwords       | accepted
+```
+
+### `/sdd.adr new`
+
+```
+Nuevo ADR — responde las preguntas:
+1. Decisión: "Use DynamoDB para analytics"
+2. Contexto: "Scale infinitamente, baja latencia"
+3. Alternativas: "PostgreSQL partitioning, BigQuery"
+4. Status: "accepted" (o "rejected", "deprecated")
+
+✅ Guardado en ADRs.jsonl
+```
+
+---
+
+## Implementación Técnica
+
+### En Hook: `agent-memory.js`
+
+```javascript
+function extraerADRsDelContenido(contenido) {
+  // Regex multilenguaje: //, /*, #, --, etc.
+  const regex = /(?:\/\/|\/\*|#|--|<!--|REM)\s*ADR:\s*({[^}]*})/g;
+  const adrs = [];
+  let match;
+  while ((match = regex.exec(contenido)) !== null) {
+    try {
+      const json = JSON.parse(match[1]);
+      adrs.push(json);
+    } catch {
+      // Ignorar JSON inválido
+    }
+  }
+  return adrs;
+}
+
+function registrarADR(cwd, agente, archivo, adrs) {
+  const ledgerFile = join(cwd, ".sdd/arquitectura/ADRs.jsonl");
+  for (const adr of adrs) {
+    const linea = JSON.stringify({
+      ts: new Date().toISOString(),
+      ...adr,
+      archivo: archivo,
+      agente: agente
+    });
+    appendFileSync(ledgerFile, linea + "\n", "utf8");
+  }
+}
+```
+
+---
+
+## CLI: `adr-parser.js`
+
+Batch scan del codebase:
+
+```bash
+node utils/adr-parser.js . src/**/*.ts --update-ledger
+```
+
+Encuentra todos los ADRs en archivos existentes y los añade al ledger.
+
+---
+
+## Notas
+
+- **Multilenguaje:** Soporta comentarios en Python, JS, Go, Java, Rust, etc.
+- **Idempotente:** Escanear 2 veces = mismos resultados (sin duplicados)
+- **Seguro:** JSON validado antes de guardar, error silencioso si es inválido
+- **Performante:** Regex simple, <100ms para archivo de 100KB
+