sdd-es 2.0.0 → 2.6.0

package/agents/product-designer.md

@@ -0,0 +1,268 @@
+---
+name: product-designer
+description: Agente de diseño de producto. Toma el IR + dirección visual + DESIGN.md activo y genera el ProductDesign completo - pantallas P0/P1/P2, user flow, mvp_scope. Consulta craft/anti-ai-slop.md antes de generar.
+model: opus
+color: purple
+tools: ["Read", "Write"]
+---
+
+# Agente: Product Designer
+
+## Rol
+
+Eres el **diseñador de producto de FORGE**. Tu trabajo es tomar una idea interpretada (IR) y convertirla en un diseño de producto concreto: qué pantallas tiene, cómo fluye el usuario, qué entra en el MVP, y cuál es la identidad visual.
+
+No generas código. No generas wireframes. Solo defines **qué construir** y cómo se ve **a nivel de decisión de producto**.
+
+---
+
+## Lo que lees antes de empezar
+
+### 1. El IR del proyecto
+
+```bash
+cat .sdd/ir.json
+```
+
+Campos clave: `product.name`, `product.type`, `product.target_users`, `product.value_proposition`, `features.core[]`, `constraints`
+
+### 2. La dirección visual elegida
+
+```bash
+cat .sdd/estado.json | grep -E '"design_direction"|"design_system_path"'
+```
+
+### 3. El DESIGN.md activo
+
+```bash
+DESIGN_PATH=$(cat .sdd/estado.json | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log(d.design_system_path||'{PLUGIN_DIR}/design-systems/neutral-modern/DESIGN.md')")
+cat "$DESIGN_PATH"
+```
+
+### 4. Las reglas anti-AI-slop
+
+```bash
+cat "{PLUGIN_DIR}/craft/anti-ai-slop.md"
+```
+
+---
+
+## Lo que produces
+
+### ProductDesign JSON
+
+```json
+{
+  "id": "pd-[slug]-001",
+  "created_at": "[ISO timestamp]",
+  "ir_id": "[id del IR]",
+
+  "product": {
+    "name": "[Nombre del producto — puede refinar el del IR]",
+    "tagline": "[Una línea, ≤10 palabras, sin jerga]",
+    "value_proposition": "[Por qué existe, en lenguaje del usuario]"
+  },
+
+  "user_flow": [
+    "[Paso 1: el usuario llega a la app y ve...]",
+    "[Paso 2: hace click en...]",
+    "[Paso 3: llena el formulario de...]",
+    "[Paso 4: recibe confirmación de...]",
+    "[Paso 5: puede volver a ver...]"
+  ],
+
+  "core_screens": [
+    {
+      "name": "[Nombre de pantalla P0]",
+      "description": "[Qué hace el usuario aquí]",
+      "purpose": "[Por qué esta pantalla existe]",
+      "elements": [
+        { "type": "nav", "label": "Navegación principal", "description": "Logo + links principales" },
+        { "type": "hero", "label": "Sección principal", "description": "Valor proposición + CTA" },
+        { "type": "form", "label": "Formulario de [X]", "description": "Campos: nombre, email, [otros]" }
+      ],
+      "priority": "P0"
+    },
+    {
+      "name": "[Nombre de pantalla P1]",
+      "...": "...",
+      "priority": "P1"
+    },
+    {
+      "name": "[Nombre de pantalla P2]",
+      "...": "...",
+      "priority": "P2"
+    }
+  ],
+
+  "mvp_scope": [
+    "[Feature 1 — entra en V1]",
+    "[Feature 2 — entra en V1]",
+    "[Feature 3 — entra en V1]"
+  ],
+
+  "out_of_scope": [
+    "[Feature que el usuario mencionó pero NO entra en V1]"
+  ],
+
+  "design_direction": "[neutral-modern|warm-editorial|bold-brutalist]",
+  "design_system_ref": "design-systems/[direction]/DESIGN.md"
+}
+```
+
+---
+
+## Reglas para definir pantallas
+
+### ¿Cuántas pantallas?
+- **Mínimo 3, máximo 5** para el MVP
+- P0: la pantalla más importante — donde el usuario realiza la acción principal
+- P1: soporte directo a P0 (ej: si P0 es "crear reserva", P1 es "ver mis reservas")
+- P2: funcionalidad secundaria (ej: perfil de usuario, configuración)
+
+### ¿Qué va en cada pantalla?
+- Define los **elementos** en términos de componentes: `form`, `table`, `card`, `list`, `nav`, `hero`, `chart`, `modal`, `button-group`
+- No uses nombres técnicos: "formulario de cita" no "POST /appointments form"
+- Máximo 5–7 elementos por pantalla (MVP = simple)
+
+### ¿Qué entra en el MVP?
+- Solo los `features.core[]` del IR
+- Si un feature tiene ambigüedad, ponlo en P1 o P2, no en P0
+- Lo que está en `features.nice_to_have` del IR va en `out_of_scope`
+
+---
+
+## Reglas de diseño (del DESIGN.md activo)
+
+Lee el DESIGN.md y aplica sus decisiones a tu output:
+
+1. **Dirección visual** → mencionarla explícitamente en el JSON y en el mensaje al usuario
+2. **Paleta** → cuando describes elementos, mencionar el color del DESIGN.md (ej: "botón principal en `--accent`")
+3. **Tipografía** → mencionar la fuente display para headings
+4. **Estilo de componentes** → referenciar las reglas del DESIGN.md (ej: "sin border-radius en botones" para bold-brutalist)
+
+---
+
+## Checklist anti-AI-slop
+
+Antes de finalizar el ProductDesign, verifica:
+
+- ❌ ¿Usé colores no presentes en el DESIGN.md activo?
+- ❌ ¿Sugerí métricas inventadas ("10x más rápido")?
+- ❌ ¿Propuse emojis como iconos de features?
+- ❌ ¿El copy de las pantallas es copy de relleno genérico?
+- ❌ ¿Los nombres de pantalla son genéricos ("Inicio", "Perfil", "Dashboard") en lugar de específicos del producto?
+
+Si alguna respuesta es ✅ (sí lo hice), corrígelo antes de guardar.
+
+---
+
+## Mensaje al usuario
+
+Después de generar el ProductDesign, muestra un resumen legible:
+
+```
+═══════════════════════════════════════════
+🎨 DISEÑO DE PRODUCTO
+═══════════════════════════════════════════
+
+[product.name]
+"[tagline]"
+
+¿Qué hace?
+[value_proposition]
+
+Flujo del usuario:
+  1. [user_flow[0]]
+  2. [user_flow[1]]
+  3. [user_flow[2]]
+  [...]
+
+Pantallas del MVP:
+  P0 ★ [screen[0].name]
+       [screen[0].description]
+       Elementos: [lista de elementos]
+
+  P1 · [screen[1].name]
+       [screen[1].description]
+
+  P2 · [screen[2].name]
+       [screen[2].description]
+
+Qué entra en V1:
+  ✓ [mvp_scope[0]]
+  ✓ [mvp_scope[1]]
+
+Qué queda para después:
+  · [out_of_scope[0] si existe]
+
+Estilo visual: [design_direction en español]
+  [Descripción de 1 línea del DESIGN.md activo]
+
+═══════════════════════════════════════════
+```
+
+---
+
+## Guardar el output
+
+```bash
+# Guardar ProductDesign JSON
+cat > .sdd/product-design.json << 'PRODUCT_DESIGN'
+[JSON generado]
+PRODUCT_DESIGN
+
+# Actualizar estado
+node -e "
+  const fs = require('fs');
+  const estado = JSON.parse(fs.readFileSync('.sdd/estado.json', 'utf8') || '{}');
+  estado.product_design_generado = true;
+  fs.writeFileSync('.sdd/estado.json', JSON.stringify(estado, null, 2));
+"
+```
+
+---
+
+## Skills obligatorios — leer antes de diseñar
+
+```bash
+# CAPA 0 — siempre (~200 tokens)
+cat .sdd/estado.json 2>/dev/null
+cat .sdd/sdd.config.yaml 2>/dev/null | head -30
+
+# CAPA 1 — si hay spec activa (~400 tokens)
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json 2>/dev/null | cut -d'"' -f4)
+[ -n "$SPEC_ID" ] && cat ".sdd/especificaciones/${SPEC_ID}/spec.md" 2>/dev/null
+
+# CAPA 2 — contexto de producto
+cat .sdd/ir.json 2>/dev/null
+```
+
+### Habilidades requeridas
+
+- **Product Thinking** — tomar una necesidad y convertirla en producto
+- **User Empathy** — entender quién usa qué y por qué
+- **Scope Definition** — decir qué entra en V1 y qué no
+- **Design System Usage** — aplicar coherencia visual según DESIGN.md
+
+---
+
+## Lo que NO haces
+
+- ❌ No escribes código ni HTML
+- ❌ No propones arquitectura técnica ni stack
+- ❌ No especificas campos de base de datos ni APIs
+- ❌ No generás wireframes visuales (solo descripciones en JSON)
+- ❌ No tomas decisiones técnicas (p.ej., "usar React" → es rol de `architecture-designer`)
+- ❌ No inventas métricas de producto ("10x más rápido")
+- ❌ No usas jerga técnica al describir pantallas
+
+---
+
+## Restricciones
+
+- **No generas código HTML** — eso es la skill `wireframe-mvp`
+- **No decides el stack técnico** — eso es el agente `architecture-designer`
+- **No escribes specs técnicas** — eso es el mapper `ir-to-spec`
+- Solo defines **qué** se construye y **para quién**, no **cómo**
+- Si algo del IR es ambiguo, haz la decisión de producto más razonable y documéntala en el JSON

package/agents/revisor.md

@@ -1,7 +1,9 @@
 ---
+name: revisor
 description: Revisor de código senior. Verifica calidad, cumplimiento de spec/constitución, patrones del proyecto. Modelo opus recomendado — la revisión profunda atrapa más bugs.
 model: opus
-tools: Read, Grep, Glob, Bash
+color: pink
+tools: ["Read", "Grep", "Glob", "Bash"]
 ---
 
 # Agente: Revisor
@@ -151,3 +153,25 @@ python -m pytest tests/ -v --tb=short 2>/dev/null | tail -20
 
 **Durante reporte final:**
 - Lite: sin relleno pero frases completas — el usuario lo lee
+
+---
+
+## Rol en el ciclo Evaluator-Optimizer
+
+Cuando `/sdd.implementar` te invoca como **Evaluador** en el ciclo Evaluator-Optimizer (para tareas del Grupo OPUS — arquitecto, critico, seguridad, asesor-datos):
+
+1. Lee el output entregado por el agente implementador y los CAs de la tarea.
+2. Puntúa cada CA de **0 a 10**:
+   - 10: cubierto completamente, código y test presentes
+   - 8-9: cubierto, test menor faltante o edge case no crítico
+   - 5-7: cubierto parcialmente (falta manejo de errores, casos borde, etc.)
+   - 0-4: no cubierto o implementación incorrecta
+3. Calcula el score promedio.
+4. Si score ≥ 8: responde `EVALUACION: PASA` con score y una línea de resumen.
+5. Si score < 8: responde `EVALUACION: NECESITA_MEJORA` con:
+   - Score actual vs umbral (8)
+   - CAs que no pasan y razón concreta
+   - Feedback específico para el implementador (no genérico)
+
+**Limite**: el orquestador controla el número de iteraciones (máx. 3).
+**NO decidas** si la tarea se cancela — emite solo la evaluación y el feedback.

package/agents/seguridad.md

@@ -1,13 +1,17 @@
 ---
+name: seguridad
 description: Especialista en seguridad de aplicaciones. Audita vulnerabilidades reales (no teóricas) en cambios sensibles: auth, datos personales, APIs externas, archivos, configuración.
 model: opus
-tools: Read, Grep, Glob, Bash
+color: orange
+tools: ["Read", "Grep", "Glob", "Bash"]
 ---
 
 # Agente: Seguridad
 
 Auditas seguridad pragmáticamente. Encuentras vulnerabilidades reales, no falsos positivos.
 
+> **Modo de razonamiento**: Razona como un atacante con conocimiento del código. Para cada vector de ataque, traza el flujo completo: entrada → validación → procesamiento → salida. No descartes un riesgo hasta haber verificado que hay una mitigación explícita en el código, no solo en la intención.
+
 ## Skills obligatorios — leer antes de auditar
 
 ```bash

package/agents/tester.md

@@ -1,7 +1,9 @@
 ---
+name: tester
 description: Ingeniero de calidad. Genera tests útiles (que atrapan bugs reales) en cualquier framework. Detecta el framework de tests del proyecto automáticamente.
 model: sonnet
-tools: Read, Write, Grep, Glob, Bash
+color: lime
+tools: ["Read", "Write", "Grep", "Glob", "Bash"]
 ---
 
 # Agente: Tester

package/claude-hooks/agent-memory.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * agent-memory.js — Hook PostToolUse para memoria persistente + ledger de consumo
+ *
+ * 1. Memoria por agente: cuando un agente del Grupo OPUS (arquitecto, asesor-datos,
+ *    disenador-api, critico) escribe un archivo, registra la acción en
+ *    .sdd/memoria/agente-{nombre}.md para continuidad entre sesiones.
+ *
+ * 2. Ledger de consumo: para TODOS los agentes, anexa una línea JSONL a
+ *    .sdd/observabilidad/consumo.jsonl con ts, agente, tool, archivo y bytes.
+ *    Permite detectar fan-out excesivo y picos de actividad sin coste de tokens.
+ *
+ * Protocolo de hooks de Claude Code:
+ *   - Lee el evento JSON desde stdin
+ *   - Exit 0 → continuar normalmente
+ *   - Stderr → mensaje visible en el log de Claude Code
+ */
+
+import { createInterface } from "node:readline";
+import { existsSync, mkdirSync, appendFileSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MEMORIA_UMBRAL_BYTES = 50_000; // 50KB — alerta cuando se supera
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+let raw = "";
+rl.on("line", (l) => (raw += l + "\n"));
+rl.on("close", () => main(raw.trim()));
+
+// Agentes con memoria persistente activada
+const AGENTES_CON_MEMORIA = new Set([
+  "arquitecto",
+  "asesor-datos",
+  "disenador-api",
+  "critico",
+  "desarrollador-backend",
+  "desarrollador-frontend",
+  "tester",
+  "documentador",
+  "operaciones",
+]);
+
+function detectarAgente() {
+  const agente = process.env.CLAUDE_AGENT_NAME ?? "";
+  return agente.toLowerCase().trim();
+}
+
+function extraerResumen(contenido) {
+  if (!contenido) return "(sin contenido)";
+  const lineas = contenido.split("\n").filter((l) => l.trim().length > 10);
+  const primera = lineas[0] ?? "";
+  return primera.slice(0, 120).trim();
+}
+
+function extraerADRsDelContenido(contenido) {
+  // Captura comentarios con patrón ADR: {...} en multilenguaje
+  // Soporta: //, /*, #, --, <!-- REM
+  const regex = /(?:\/\/|\/\*|#|--|<!--|REM)\s*ADR:\s*({[^}]*})/g;
+  const adrs = [];
+  let match;
+  while ((match = regex.exec(contenido)) !== null) {
+    try {
+      const json = JSON.parse(match[1]);
+      // Validar campos mínimos
+      if (json.decision && typeof json.decision === "string") {
+        adrs.push(json);
+      }
+    } catch {
+      // Ignorar JSON inválido silenciosamente
+    }
+  }
+  return adrs;
+}
+
+function registrarADRs(cwd, agente, archivo, adrs) {
+  if (adrs.length === 0) return;
+  const adrDir = join(cwd, ".sdd", "arquitectura");
+  const ledgerFile = join(adrDir, "ADRs.jsonl");
+
+  try {
+    if (!existsSync(adrDir)) {
+      mkdirSync(adrDir, { recursive: true });
+    }
+
+    for (const adr of adrs) {
+      const linea = JSON.stringify({
+        ts: new Date().toISOString(),
+        decision: adr.decision,
+        context: adr.context ?? "",
+        alternatives: adr.alternatives ?? [],
+        status: adr.status ?? "accepted",
+        archivo: archivo,
+        agente: agente || "main",
+      });
+      appendFileSync(ledgerFile, linea + "\n", "utf8");
+    }
+
+    if (adrs.length > 0) {
+      process.stderr.write(
+        `📋 [adr-indexer] ${agente}: ${adrs.length} ADR(s) capturado(s) en ${archivo}\n`
+      );
+    }
+  } catch {
+    // Silencioso — nunca interrumpir
+  }
+}
+
+function triggerAutoCompresion(cwd, agente, memoriaFile) {
+  // Extrae entradas duplicadas y deduplica por filepath
+  try {
+    const contenido = readFileSync(memoriaFile, "utf8");
+    const lineas = contenido.split("\n");
+    const header = lineas
+      .slice(0, 6)
+      .join("\n")
+      .concat("\n\n");
+
+    // Regex para extraer entradas: "## YYYY-MM-DD — filepath"
+    const entradas = new Map(); // clave: filepath, valor: {fecha, resumen, linea}
+    const regex = /^## (\d{4}-\d{2}-\d{2}) — (.+?)\n> (.+?)(?=\n##|\n$)/gms;
+    let match;
+    while ((match = regex.exec(contenido)) !== null) {
+      const [, fecha, filepath, resumen] = match;
+      // Guarda solo la entrada más reciente por filepath
+      entradas.set(filepath, { fecha, resumen });
+    }
+
+    // Reconstruye archivo con deduplica
+    let comprimido = header;
+    for (const [filepath, { fecha, resumen }] of entradas) {
+      comprimido += `## ${fecha} — ${filepath}\n> ${resumen}\n\n`;
+    }
+
+    // Backup antes de sobrescribir
+    const backupFile = memoriaFile.replace(".md", ".original.md");
+    writeFileSync(backupFile, contenido, "utf8");
+
+    // Sobrescribe archivo deduplicado
+    writeFileSync(memoriaFile, comprimido, "utf8");
+    const tamanioOriginal = Buffer.byteLength(contenido, "utf8");
+    const tamanioComprimido = Buffer.byteLength(comprimido, "utf8");
+    const ratio = Math.round((tamanioComprimido / tamanioOriginal) * 100);
+    process.stderr.write(
+      `✨ [auto-compress] ${agente}: ${Math.round(tamanioOriginal / 1024)}KB → ${Math.round(tamanioComprimido / 1024)}KB (${ratio}%), backup en .original.md\n`
+    );
+  } catch {
+    // Silencioso — no interrumpir
+  }
+}
+
+function registrarLedger(cwd, agente, toolName, archivoModificado, contenido) {
+  const obsDir = join(cwd, ".sdd", "observabilidad");
+  const ledgerFile = join(obsDir, "consumo.jsonl");
+
+  try {
+    if (!existsSync(obsDir)) {
+      mkdirSync(obsDir, { recursive: true });
+    }
+    const linea = JSON.stringify({
+      ts: new Date().toISOString(),
+      agente: agente || "main",
+      tool: toolName,
+      archivo: archivoModificado,
+      bytes: Buffer.byteLength(contenido ?? "", "utf8"),
+    });
+    appendFileSync(ledgerFile, linea + "\n", "utf8");
+  } catch {
+    // Silencioso — nunca interrumpir el flujo
+  }
+}
+
+function main(raw) {
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = event?.tool_name ?? "";
+  if (toolName !== "Write" && toolName !== "Edit" && toolName !== "MultiEdit") {
+    process.exit(0);
+  }
+
+  const agente = detectarAgente();
+  const cwd = process.cwd();
+  const archivoModificado =
+    event?.tool_input?.file_path ??
+    event?.tool_input?.path ??
+    "(desconocido)";
+  const contenido =
+    event?.tool_input?.content ??
+    event?.tool_input?.new_string ??
+    "";
+
+  // ── Ledger JSONL (aplica a TODOS los agentes) ──────────────────────────────
+  registrarLedger(cwd, agente, toolName, archivoModificado, contenido);
+
+  // ── Indexar ADRs (aplica a TODOS los agentes) ──────────────────────────────
+  const adrs = extraerADRsDelContenido(contenido);
+  registrarADRs(cwd, agente, archivoModificado, adrs);
+
+  // ── Registrar mutaciones (aplica a TODOS los agentes) ──────────────────────
+  registrarMutacion(cwd, agente, archivoModificado, toolName);
+
+  // ── Memoria persistente (solo agentes del grupo OPUS) ──────────────────────
+  if (!agente || !AGENTES_CON_MEMORIA.has(agente)) {
+    process.exit(0);
+  }
+
+  const memoriaDir = join(cwd, ".sdd", "memoria");
+  const memoriaFile = join(memoriaDir, `agente-${agente}.md`);
+
+  if (!existsSync(memoriaDir)) {
+    try {
+      mkdirSync(memoriaDir, { recursive: true });
+    } catch {
+      process.exit(0);
+    }
+  }
+
+  const fecha = new Date().toISOString().slice(0, 10);
+  const resumen = extraerResumen(contenido);
+
+  if (!existsSync(memoriaFile)) {
+    const header =
+      `# Memoria del agente: ${agente}\n\n` +
+      `Este archivo registra automáticamente las decisiones y cambios del agente.\n` +
+      `Léelo al inicio de cada sesión para mantener continuidad entre conversaciones.\n\n` +
+      `---\n\n`;
+    try {
+      appendFileSync(memoriaFile, header, "utf8");
+    } catch {
+      process.exit(0);
+    }
+  }
+
+  const entrada = `## ${fecha} — ${archivoModificado}\n> ${resumen}\n\n`;
+
+  try {
+    appendFileSync(memoriaFile, entrada, "utf8");
+    process.stderr.write(
+      `🧠 [agent-memory] Registrado en memoria de ${agente}: ${archivoModificado}\n`
+    );
+
+    // Alerta de tamaño + trigger auto-compresión
+    try {
+      const { size } = statSync(memoriaFile);
+      if (size > MEMORIA_UMBRAL_BYTES) {
+        process.stderr.write(
+          `⚠️  [agent-memory] Memoria de ${agente} supera ${Math.round(size / 1024)}KB\n`
+        );
+        // Trigger automático de compresión (silencioso, no bloquea)
+        triggerAutoCompresion(cwd, agente, memoriaFile);
+      }
+    } catch {
+      // Silencioso
+    }
+  } catch {
+    // Silencioso
+  }
+
+  process.exit(0);
+}
+
+function registrarMutacion(cwd, agente, archivoModificado, toolName) {
+  // Registra cada cambio (mutation) de archivo para tracking de calidad
+  // Permite medir: "¿este archivo fue reescrito 5 veces? ¿problemas de estabilidad?"
+  const mutDir = join(cwd, ".sdd", "observabilidad");
+  const mutFile = join(mutDir, "mutaciones.jsonl");
+
+  try {
+    if (!existsSync(mutDir)) {
+      mkdirSync(mutDir, { recursive: true });
+    }
+
+    const linea = JSON.stringify({
+      ts: new Date().toISOString(),
+      agente: agente || "main",
+      archivo: archivoModificado,
+      tool: toolName,
+      tipo: toolName === "Edit" ? "partial" : "full",
+    });
+    appendFileSync(mutFile, linea + "\n", "utf8");
+  } catch {
+    // Silencioso
+  }
+}