sdd-es 2.0.0 → 2.5.0

package/skills/descubrir-idea/SKILL.md

@@ -0,0 +1,133 @@
+---
+description: Discovery form de 5 preguntas para entender la idea del usuario antes de interpretar. Genera contexto estructurado que alimenta el Interpreter.
+model: claude-opus-4-8
+allowed-tools: Write
+---
+
+# Skill: Descubrir Idea
+
+## Propósito
+
+Antes de generar ningún IR, necesitamos entender el contexto de la idea. Esta skill hace **5 preguntas clave** en lenguaje natural — sin jerga técnica — y guarda las respuestas en `.sdd/descubrimiento.md`.
+
+El objetivo no es un interrogatorio. Es una conversación breve (2–3 minutos) que permite al Interpreter generar un IR con confidence ≥ 0.8 en lugar de ≤ 0.6.
+
+---
+
+## Flujo
+
+### Paso 1: Presentación
+
+Antes de las preguntas, muestra esto:
+
+```
+Antes de entender tu idea en detalle, tengo 5 preguntas rápidas.
+No hay respuestas correctas — contesta lo que se te ocurra.
+```
+
+### Paso 2: Las 5 preguntas (una a la vez)
+
+Haz cada pregunta de forma conversacional. Espera la respuesta antes de hacer la siguiente.
+
+**Pregunta 1 — Superficie**
+```
+¿Dónde va a vivir esto?
+Por ejemplo: en un navegador web, en el celular, como programa de escritorio, o es algo más técnico (una API, una herramienta de línea de comandos)?
+```
+Acepta respuestas vagas: "web", "móvil", "app", "no sé" — todas son válidas.
+
+**Pregunta 2 — Audiencia**
+```
+¿Quién lo va a usar?
+Puede ser tú mismo, tus clientes, tu equipo, o el público en general.
+```
+No pidas detalles. Cualquier respuesta sirve.
+
+**Pregunta 3 — Tono**
+```
+¿Qué sensación quieres que tenga?
+Por ejemplo: profesional y sobrio, moderno y tecnológico, cálido y amigable, simple y directo...
+```
+Si el usuario no sabe, anota "no definido".
+
+**Pregunta 4 — Restricciones**
+```
+¿Hay algo importante que debamos tener en cuenta?
+Por ejemplo: presupuesto ajustado, necesita estar listo pronto, solo un desarrollador, no quieres depender de servicios de pago...
+```
+Si no hay restricciones, registra "ninguna mencionada".
+
+**Pregunta 5 — Inspiración**
+```
+¿Hay algún producto o app que te guste y que se parezca a lo que quieres hacer?
+No tiene que ser exactamente igual — solo para entender el estilo o la dirección.
+```
+Si el usuario no tiene referencia, anota "sin referencia".
+
+### Paso 3: Guardar contexto
+
+Después de las 5 respuestas, guarda en `.sdd/descubrimiento.md`:
+
+```markdown
+# Contexto de Descubrimiento
+
+**Fecha**: [fecha actual]
+**Idea original**: [texto que dio el usuario antes de la skill]
+
+## Respuestas
+
+**Superficie**: [respuesta 1]
+**Audiencia**: [respuesta 2]
+**Tono**: [respuesta 3]
+**Restricciones**: [respuesta 4]
+**Inspiración**: [respuesta 5]
+
+## Notas del sistema
+
+[Cualquier observación relevante: contradicciones, pistas, contexto adicional]
+```
+
+### Paso 4: Confirmar y pasar al Interpreter
+
+Muestra un resumen de una línea:
+```
+Entendido. Voy a interpretar tu idea teniendo esto en cuenta.
+```
+
+No pidas confirmación — pasa directo al Interpreter.
+
+---
+
+## Reglas
+
+- **Una pregunta a la vez** — nunca hagas 2 preguntas en el mismo mensaje
+- **Sin jerga técnica** — nunca uses "frontend", "backend", "API REST", "deployment", etc.
+- **Sin juzgar** — cualquier respuesta es válida, incluso "no sé"
+- **Máximo 5 preguntas** — nunca hagas preguntas de seguimiento
+- **Tono conversacional** — no formal, no robótico
+
+---
+
+## Ejemplos de respuestas aceptables
+
+**Pregunta 1 - Superficie:**
+- ✅ "web" → `web`
+- ✅ "en el celular" → `mobile`
+- ✅ "no sé, lo que sea más fácil" → `web` (default)
+- ✅ "quiero que se use desde el navegador" → `web`
+
+**Pregunta 2 - Audiencia:**
+- ✅ "mis clientes" → `clientes del negocio`
+- ✅ "yo solo" → `uso personal`
+- ✅ "cualquier persona" → `público general`
+
+**Pregunta 3 - Tono:**
+- ✅ "profesional" → `profesional`
+- ✅ "no sé, que se vea bien" → `moderno y limpio`
+- ✅ "como Airbnb" → `cálido, accesible`
+
+---
+
+## Output esperado
+
+`.sdd/descubrimiento.md` con las 5 respuestas estructuradas, listo para que `interpretar-idea` lo lea como contexto adicional.

package/skills/effort-router/SKILL.md

@@ -0,0 +1,128 @@
+---
+description: Dado el nombre de la fase SDD actual, recomienda effort (low/medium/high/max) y modelo (Haiku/Sonnet/Opus) para cada agente. Evita pagar Opus cuando Sonnet o Haiku son suficientes — ahorro típico del 60-75% en fases mecánicas.
+model: claude-haiku-4-5-20251001
+allowed-tools: Read
+---
+
+# Skill: Effort Router
+
+## Propósito
+
+Los agentes de FORGE usan modelos fijos declarados en su frontmatter. Pero no toda fase requiere el mismo nivel de razonamiento. Esta skill lee la fase actual del proyecto y produce una tabla de configuración recomendada: qué modelo usar en cada agente y con qué nivel de `effort`, para evitar gastar Opus donde Haiku es suficiente.
+
+**Ahorro estimado por fase:**
+- Fases mecánicas (tests, docs, deploy): 75-80% vs. Opus en todo
+- Fases de verificación: 50-60%
+- Fases de decisión (spec, plan, análisis): 0% — estas SÍ necesitan Opus
+
+---
+
+## Lo que lees primero
+
+```bash
+# Fase actual y spec activa
+cat .sdd/estado.json 2>/dev/null | head -20 || echo "SIN_ESTADO"
+```
+
+---
+
+## Tabla de routing por fase
+
+### GRUPO A — Siempre Opus (decisiones críticas, no degradar)
+
+| Fase SDD | Agente principal | Effort | Modelo | Razón |
+|---|---|---|---|---|
+| `especificacion` | arquitecto | high | claude-opus-4-8 | Define restricciones del sistema entero |
+| `planificacion` | arquitecto, critico | high | claude-opus-4-8 | Decisiones de arquitectura irreversibles |
+| `analisis` (7 dimensiones) | critico, seguridad | high | claude-opus-4-8 | Auditoría de riesgos — falsos negativos son costosos |
+| `aclaracion` (cuando hay `[MARCADOR]`) | arquitecto | high | claude-opus-4-8 | Ambigüedades de spec → decisiones de arquitectura |
+
+### GRUPO B — Sonnet suficiente (trabajo técnico estándar)
+
+| Fase SDD | Agente principal | Effort | Modelo | Razón |
+|---|---|---|---|---|
+| `checklist` | (sin agente dedicado) | medium | claude-sonnet-4-6 | Verificación mecánica contra criterios conocidos |
+| `tareas` | (sin agente dedicado) | medium | claude-sonnet-4-6 | Descomposición mecánica de plan → tareas |
+| `implementacion` (backend/API) | desarrollador-backend, disenador-api | medium | claude-sonnet-4-6 | Implementación con spec clara |
+| `implementacion` (frontend) | desarrollador-frontend | medium | claude-sonnet-4-6 | Implementación con spec clara |
+| `verificacion` | verificador-implementacion | medium | claude-sonnet-4-6 | Cruzar CAs — bien definido |
+| `qa` | tester | medium | claude-sonnet-4-6 | Orquestar Playwright — mecánico pero con estado |
+| `snapshot` | (sin agente dedicado) | low | claude-sonnet-4-6 | Serializar estado actual |
+
+### GRUPO C — Haiku suficiente (operaciones mecánicas puras)
+
+| Fase SDD | Agente principal | Effort | Modelo | Razón |
+|---|---|---|---|---|
+| `aclaracion` (sin marcadores) | (sin agente dedicado) | low | claude-haiku-4-5-20251001 | Solo formatear preguntas conocidas |
+| `implementacion` (tests) | tester | low | claude-haiku-4-5-20251001 | Tests unitarios con spec y código claros |
+| `implementacion` (docs) | documentador | low | claude-haiku-4-5-20251001 | Documentar código ya escrito |
+| `deploy` | operaciones | low | claude-haiku-4-5-20251001 | Ejecutar scripts CI/CD predefinidos |
+| `canary` | operaciones | low | claude-haiku-4-5-20251001 | Igual que deploy |
+| `release` | (sin agente dedicado) | low | claude-haiku-4-5-20251001 | Actualizar versiones y CHANGELOG |
+| `retro` | (sin agente dedicado) | low | claude-haiku-4-5-20251001 | Formato de retrospectiva estructurado |
+
+---
+
+## Output que produces
+
+Dado el JSON de `.sdd/estado.json`, imprime el bloque de configuración recomendada:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║          🎯 EFFORT ROUTER — Configuración recomendada        ║
+╠══════════════════════════════════════════════════════════════╣
+║  Fase detectada: {FASE}                                      ║
+╠══════════════════════════════════════════════════════════════╣
+║  AGENTE               | MODELO          | EFFORT   | GRUPO  ║
+║  ─────────────────────┼─────────────────┼──────────┼─────── ║
+║  {agente}             | {modelo}        | {effort} | {A/B/C}║
+╠══════════════════════════════════════════════════════════════╣
+║  💰 AHORRO ESTIMADO vs. Opus-en-todo                         ║
+║                                                              ║
+║     Agentes en Grupo B:  {N} × ~60% ahorro por token        ║
+║     Agentes en Grupo C:  {N} × ~80% ahorro por token        ║
+║     Ahorro total estimado de la fase: ~{%}%                  ║
+╠══════════════════════════════════════════════════════════════╣
+║  ⚠️  ATENCIÓN                                                ║
+║                                                              ║
+║  Estos son defaults para la fase "{FASE}".                   ║
+║  Si la tarea actual tiene ambigüedad estructural →           ║
+║  sube a Opus para el agente afectado.                        ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+### Cálculo del ahorro estimado
+
+Precios de referencia (por millón de tokens):
+- Opus 4.8: $5 input / $25 output
+- Sonnet 4.6: $3 input / $15 output  ← 40% más barato en input, 40% en output
+- Haiku 4.5: $1 input / $5 output   ← 80% más barato en input, 80% en output
+
+Para la fase actual, suma los agentes activos y calcula el delta respecto a "todos Opus".
+
+**Ejemplo — fase `implementacion`:**
+```
+Grupo A (Opus):    0 agentes
+Grupo B (Sonnet):  3 agentes (backend, frontend, disenador-api) → ~40% ahorro c/u
+Grupo C (Haiku):   2 agentes (tester, documentador) → ~80% ahorro c/u
+
+Ahorro total estimado: ((3×0.40) + (2×0.80)) / 5 = ~56%
+```
+
+---
+
+## Cómo aplicar las recomendaciones
+
+Las recomendaciones son de sesión (no tocan los archivos `.md` de los agentes). Para aplicar en la sesión actual:
+
+1. Cuando Claude Code invoca un agente vía `/sdd.implementar`, puedes prefixar la invocación con el modelo sugerido si el runtime lo permite.
+2. Para cambios permanentes en el frontmatter del agente, edita `{PLUGIN_DIR}/agents/{nombre}.md` y cambia la línea `model:` del frontmatter.
+3. Para registrar que usaste el router en esta sesión, añadir al ledger: `/sdd.estado consumo`.
+
+---
+
+## Notas
+
+- Esta skill se invoca automáticamente desde `/sdd.optimizar` como PASO 2 cuando hay alertas de fan-out.
+- Para proyectos con presupuesto de tokens restringido, usa junto con `token-budget` para ver el impacto económico real.
+- La regla de oro: **si el agente toma una decisión que no se puede deshacer → Opus. Si ejecuta una decisión ya tomada → Sonnet o Haiku.**

package/skills/elegir-direccion/SKILL.md

@@ -0,0 +1,184 @@
+---
+description: Direction picker inspirado en open-design. Selecciona 3 de las 5 direcciones visuales disponibles según el tipo de producto y audiencia del IR, y el usuario elige una antes de generar cualquier diseño.
+model: claude-sonnet-4-6
+allowed-tools: Read, Write
+---
+
+# Skill: Elegir Dirección Visual
+
+## Propósito
+
+Antes de diseñar pantallas, el usuario elige **una dirección visual** que guiará todo el diseño del proyecto. Esta elección activa el DESIGN.md correspondiente y define paleta, tipografía, y estilo de componentes.
+
+---
+
+## Contexto que leer primero
+
+```bash
+cat .sdd/ir.json 2>/dev/null | node -e "
+  const ir = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  console.log('type:', ir.product?.type);
+  console.log('users:', ir.product?.target_users);
+  console.log('name:', ir.product?.name);
+"
+```
+
+---
+
+## Las 5 direcciones disponibles
+
+| Slug | Nombre | Ideal para |
+|------|--------|-----------|
+| `neutral-modern` | Neutral Moderno | SaaS B2B, dashboards, herramientas, apps de productividad |
+| `warm-editorial` | Editorial Cálido | Blogs, marketplaces de nicho, apps culturales, contenido |
+| `bold-brutalist` | Bold Brutalist | Herramientas dev, portfolios, startups técnicas, CLI wrappers |
+| `editorial-minimal` | Editorial Minimal | Firmas profesionales, consultoras, galerías, portfolios premium |
+| `vibrant-consumer` | Vibrant Consumer | Apps B2C, educación, fitness, entretenimiento, onboarding |
+
+---
+
+## Lógica de selección — cuáles 3 mostrar
+
+Basado en `product.type` y `target_users` del IR:
+
+| Tipo | Audiencia | Mostrar (orden de recomendación) |
+|------|-----------|----------------------------------|
+| `saas` | B2B / profesionales | Neutral Modern, Bold Brutalist, Editorial Minimal |
+| `saas` | B2C / consumidores | Neutral Modern, Vibrant Consumer, Warm Editorial |
+| `web` | General | Neutral Modern, Vibrant Consumer, Warm Editorial |
+| `mobile` | Consumidores | Vibrant Consumer, Neutral Modern, Warm Editorial |
+| `mobile` | Profesionales | Neutral Modern, Bold Brutalist, Vibrant Consumer |
+| `api` / `cli` | Desarrolladores | Bold Brutalist, Neutral Modern, Editorial Minimal |
+| `landing` / marketing | Cualquiera | Bold Brutalist, Vibrant Consumer, Neutral Modern |
+| Contenido / editorial | Lectores | Warm Editorial, Editorial Minimal, Neutral Modern |
+| Portfolio / agencia | Clientes premium | Editorial Minimal, Bold Brutalist, Warm Editorial |
+
+Si no hay IR o el tipo no está claro → mostrar: **Neutral Modern, Vibrant Consumer, Bold Brutalist**.
+
+---
+
+## Flujo
+
+### Paso 1: Determinar las 3 opciones a mostrar
+
+Analiza el IR y selecciona las 3 direcciones más adecuadas según la tabla de arriba. Ordénalas de más a menos recomendada.
+
+### Paso 2: Mostrar las 3 opciones al usuario
+
+Presenta las 3 opciones con descripción visual, paleta de colores y tipografía:
+
+```
+Elige la dirección visual para [product.name]:
+
+┌─────────────────────────────────────────────────────────┐
+│  1. [NOMBRE DE LA DIRECCIÓN 1]                          │
+│     [Descripción de 2 líneas: qué sensación transmite   │
+│     y para qué tipo de producto es ideal]               │
+│                                                         │
+│     Paleta: [color bg] [color text] [color accent]      │
+│     Fuente: [nombre de la fuente principal]             │
+│     Estilo: [3–4 palabras del estilo visual]            │
+├─────────────────────────────────────────────────────────┤
+│  2. [NOMBRE DE LA DIRECCIÓN 2]                          │
+│     [Descripción]                                       │
+│                                                         │
+│     Paleta: [...]                                       │
+│     Fuente: [...]                                       │
+│     Estilo: [...]                                       │
+├─────────────────────────────────────────────────────────┤
+│  3. [NOMBRE DE LA DIRECCIÓN 3]                          │
+│     [Descripción]                                       │
+│                                                         │
+│     Paleta: [...]                                       │
+│     Fuente: [...]                                       │
+│     Estilo: [...]                                       │
+└─────────────────────────────────────────────────────────┘
+
+Escribe 1, 2 o 3 (o descríbeme qué buscas):
+```
+
+**Datos de cada dirección para el display:**
+
+| Dirección | Paleta (bg / text / accent) | Fuente | Estilo |
+|-----------|---------------------------|--------|--------|
+| Neutral Modern | ⬜ #FAFAFA / ⬛ #111111 / 🔵 #2563EB | Inter | Limpio, funcional, espacioso |
+| Warm Editorial | 🟫 #FAF8F4 / 🟤 #2C2416 / 🔴 #C0392B | Playfair Display | Editorial, cálido, tipográfico |
+| Bold Brutalist | ⬛ #0A0A0A / ⬜ #F5F5F5 / 🟡 #F0E040 | Space Grotesk 900 | Impactante, UPPERCASE, offset shadow |
+| Editorial Minimal | ⬜ #FFFFFF / ⬛ #0A0A0A / ⬛ #0A0A0A | Cormorant Garamond | Silencioso, espacio vacío, austero |
+| Vibrant Consumer | 💜 #F8F7FF / 🟣 #1A1535 / 🟣 #6C3FF5 | Nunito 900 | Energético, redondeado, colorido |
+
+### Paso 3: Procesar la elección
+
+El usuario escribe `1`, `2`, `3`, o una descripción libre.
+
+**Mapeo de respuestas libres:**
+- "neutral" / "limpio" / "moderno" / "profesional" → `neutral-modern`
+- "cálido" / "editorial" / "revista" / "warm" → `warm-editorial`
+- "bold" / "brutal" / "oscuro" / "impactante" / "técnico" → `bold-brutalist`
+- "minimal" / "minimalista" / "austero" / "elegante" / "premium" → `editorial-minimal`
+- "colorido" / "vibrant" / "energía" / "dinámico" / "consumidor" → `vibrant-consumer`
+
+Si el usuario describe algo ambiguo, elige la más cercana y explica por qué:
+```
+Entendido. Usaré [Dirección] — [razón en 1 frase].
+Si prefieres otra, escribe el número o descríbela.
+```
+
+### Paso 4: Activar el DESIGN.md
+
+Lee el DESIGN.md de la dirección elegida:
+
+```bash
+DIRECTION="[slug elegido]"
+cat "{PLUGIN_DIR}/design-systems/$DIRECTION/DESIGN.md"
+```
+
+Guarda la elección en `.sdd/estado.json`:
+
+```bash
+node -e "
+  const fs = require('fs');
+  const p = '.sdd/estado.json';
+  const estado = fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {};
+  estado.design_direction = '$DIRECTION';
+  estado.design_system_path = '{PLUGIN_DIR}/design-systems/$DIRECTION/DESIGN.md';
+  estado.ultima_actualizacion = new Date().toISOString();
+  fs.mkdirSync('.sdd', { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(estado, null, 2));
+"
+```
+
+### Paso 5: Confirmar
+
+```
+✅ Dirección elegida: [Nombre de la dirección]
+
+El diseño de [product.name] usará:
+  • Paleta: [colores principales del DESIGN.md]
+  • Tipografía: [fuentes del DESIGN.md]
+  • Estilo: [descriptor de 1 línea]
+
+Continuando con el diseño de pantallas...
+```
+
+No pedir confirmación adicional — pasar directo al agente `product-designer`.
+
+---
+
+## Salida guardada
+
+```
+.sdd/estado.json → campos "design_direction" + "design_system_path"
+```
+
+El DESIGN.md activo se referencia en `product-design.json` bajo `design_system_ref`.
+
+---
+
+## Notas
+
+- Esta skill nunca genera código HTML ni diseño — solo selecciona la dirección
+- El DESIGN.md activo es la guía para **todo** lo que viene después (wireframe, UI, crítica)
+- Si el usuario quiere cambiar de dirección: `/sdd.diseñar cambiar-direccion`
+- Las 5 direcciones disponibles son: Neutral Modern, Warm Editorial, Bold Brutalist, Editorial Minimal, Vibrant Consumer
+- Siempre se muestran exactamente 3 opciones — las más adecuadas para el IR — no las 5