sdd-es 2.0.0

package/commands/sdd.implementar.md

@@ -0,0 +1,377 @@
+---
+description: Ejecuta las tareas con los agentes especializados configurados. Modos: todas en secuencia (sin args), tarea específica (T003), continuar (continuar). Cada tarea se verifica antes de la siguiente.
+allowed-tools: Read, Write, Edit, Bash, Task, TodoWrite, mcp__sdd-figma__analizar_sistema_diseño, mcp__sdd-figma__evaluar_ui_existente, mcp__sdd-figma__conectar_figma, mcp__sdd-figma__listar_componentes, mcp__sdd-figma__traer_componente, mcp__sdd-figma__mapear_estilos, mcp__sdd-figma__generar_componente, mcp__sdd-figma__sugerir_mejoras
+handoffs:
+  - etiqueta: "Verificar contra spec"
+    comando: sdd.verificar
+  - etiqueta: "Actualizar SNAPSHOT"
+    comando: sdd.snapshot
+---
+
+# /sdd.implementar — Ejecutar Tareas
+
+Eres el **Orquestador de Implementación**. Coordinas a los agentes especializados para ejecutar las tareas con calidad verificada.
+
+## PASO 1 — Hook pre-ejecución y validación
+
+```bash
+[ -f ".sdd/hooks/antes_implementar.sh" ] && bash .sdd/hooks/antes_implementar.sh
+
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json | cut -d'"' -f4)
+SPEC_DIR=".sdd/especificaciones/${SPEC_ID}"
+
+# Verificar precondiciones
+[ ! -f "${SPEC_DIR}/tareas.md" ] && echo "ERROR: ejecuta /sdd.tareas primero" && exit 1
+[ ! -f "${SPEC_DIR}/.estado-tareas.json" ] && echo "ERROR: estado de tareas no encontrado" && exit 1
+
+cat .sdd/sdd.config.yaml
+cat "${SPEC_DIR}/spec.md"
+cat "${SPEC_DIR}/plan.md"
+cat "${SPEC_DIR}/tareas.md"
+cat "${SPEC_DIR}/.estado-tareas.json"
+cat .sdd/memoria/constitucion.md
+```
+
+## PASO 2 — Determinar modo de ejecución
+
+| Argumento | Modo |
+|-----------|------|
+| (vacío) | **Secuencial**: ejecutar todas las tareas pendientes en orden |
+| `T003` | **Específica**: solo la tarea T003 |
+| `continuar` | **Reanudar**: desde la última tarea no completada |
+| `fase A` | **Por fase**: solo las tareas de la Fase A |
+| `revisar` | **Revisión**: invocar revisor sobre tareas completadas |
+
+## PASO 3 — Crear TODO list para visualización
+
+Usa `TodoWrite` para mostrar el progreso en tiempo real al usuario. Crea un TODO por tarea pendiente.
+
+## PASO 3.5 — Planificación PTC (Programmatic Tool Calling)
+
+Antes de ejecutar, clasifica las tareas seleccionadas según la skill `orquestacion-ptc`:
+
+```bash
+# Leer dependencias del estado de tareas para construir el grafo
+cat "${SPEC_DIR}/.estado-tareas.json" | grep -E '"dependencias"|"agente"|"id"'
+```
+
+**Algoritmo de clasificación:**
+
+1. Construye el grafo de dependencias de las tareas seleccionadas.
+2. Identifica **grupos independientes** (tareas sin arco entre sí que pueden correr en paralelo).
+3. Aplica PTC si hay ≥3 tareas independientes en el mismo grupo; si hay <3, ejecuta secuencial.
+
+**Si PTC aplica** (≥3 tareas independientes):
+
+```javascript
+// Bloque PTC — despacha el grupo independiente en paralelo
+const grupo = [
+  { id: "T001", agente: "desarrollador-backend", spec: especSec, plan: planSec },
+  { id: "T003", agente: "tester",                spec: especSec, plan: planSec },
+  { id: "T005", agente: "documentador",           spec: especSec, plan: planSec }
+];
+
+const resultados = await Promise.all(
+  grupo.map(t => Task(t.agente, construirPrompt(t)))
+);
+
+// Agrega SOLO lo mínimo — NO devuelve el output completo de cada agente
+return resultados.map((r, i) => ({
+  id:       grupo[i].id,
+  estado:   r.verificacion_ok ? "PASA" : "FALLA",
+  archivos: r.archivos_modificados,   // lista de rutas, sin contenido
+  resumen:  r.resumen_una_linea,      // una frase
+  error:    r.verificacion_ok ? null : r.mensaje_error  // solo si falla
+}));
+```
+
+Tras el bloque PTC, **procesa las tareas del siguiente nivel del grafo** de forma análoga. Las tareas dependientes del primer grupo se procesan una vez que ese grupo termina.
+
+**Fallback secuencial** — Si el sandbox no soporta ejecución programática:
+```
+→ notificar: "Ejecutando en modo secuencial (PTC no disponible)"
+→ continuar con el PASO 4 estándar
+```
+
+---
+
+## PASO 4 — Ciclo por tarea
+
+Para CADA tarea seleccionada, ejecuta este ciclo:
+
+### 4.1 — Verificar precondiciones
+
+```bash
+# La tarea no debe estar completada/bloqueada
+# Sus dependencias deben estar completadas
+```
+
+Si una dependencia no está completa:
+> ⏸️ T00X depende de T00Y (no completada). Cambio el orden y ejecuto T00Y primero.
+
+### 4.2 — Anunciar inicio
+
+```
+🔧 T00X — [Nombre]
+   Agente: [agente] (modelo: [modelo])
+   Archivos: [lista]
+   Cubre: [CAs]
+   Tiempo estimado: [S/M/L]
+```
+
+Marca la tarea como `en_progreso` en `.estado-tareas.json` y actualiza el TodoWrite.
+
+### 4.3 — Hook por tarea (opcional)
+
+```bash
+[ -f ".sdd/hooks/antes_cada_tarea.sh" ] && bash .sdd/hooks/antes_cada_tarea.sh "$TAREA_ID"
+```
+
+### 4.4 — Activar MCP de Figma si la tarea es de UI/frontend
+
+**Antes de delegar al agente frontend**, verifica si la tarea es de tipo UI:
+
+```
+SI el agente asignado es "desarrollador-frontend"
+O el tipo/área de la tarea contiene: ui, componente, interfaz, diseño, vista, pantalla, layout, figma:
+
+  1. Ejecuta: mcp__sdd-figma__analizar_sistema_diseño({ project_root: "." })
+     → Guarda el perfil en contexto para el agente
+
+  2. SI la constitución o config del proyecto tiene figma_file_key definido:
+     a. Ejecuta: mcp__sdd-figma__conectar_figma({ file_key: "<key>" })
+     b. Si la tarea menciona un componente específico de Figma:
+        - mcp__sdd-figma__traer_componente({ file_key, node_id })
+        - mcp__sdd-figma__mapear_estilos({ file_key, node_id, project_root: "." })
+     c. Inyecta el resultado del mapeo en el contexto del agente
+
+  3. Si hay tokens sin mapear (matchType: "new"), avisa al usuario:
+     > ⚠️ Figma tiene [N] colores sin equivalente en el proyecto.
+     > El agente usará el valor hex directo. ¿Continuar?
+
+SI el agente NO es frontend → salta este paso
+```
+
+> **Sin PAT / sin Figma:** Si `FIGMA_PAT` no está definido o la conexión falla, continúa sin el MCP — no bloquea la implementación.
+
+### 4.5 — Constitutional AI pre-check
+
+Antes de delegar al agente, extrae las restricciones de constitución relevantes para la tarea:
+
+```bash
+# Carga selectiva según tipo de tarea (NO cargar la constitución completa)
+TIPO_TAREA="[arquitectura|backend|frontend|bd|api|infra|test|docs]"
+
+case "$TIPO_TAREA" in
+  arquitectura) cat .sdd/memoria/constitucion.md | grep -A3 -i "stack\|framework\|prohibido\|DEBE\|NUNCA" ;;
+  backend)      cat .sdd/memoria/constitucion.md | grep -A3 -i "calidad\|test\|lint\|patron\|longitud" ;;
+  bd)           cat .sdd/memoria/constitucion.md | grep -A3 -i "base de datos\|migracion\|bd\|database" ;;
+  seguridad)    cat .sdd/memoria/constitucion.md | grep -A3 -i "seguridad\|auth\|pii\|secreto\|token" ;;
+  *)            cat .sdd/memoria/constitucion.md | grep -A2 -i "DEBE\|NUNCA\|prohibido" ;;
+esac
+```
+
+Inyecta el resultado en el contexto del agente como **restricciones explícitas**, no como contexto de fondo.
+
+### 4.6 — Delegar al agente
+
+Usa la herramienta `Task` para invocar al agente asignado. El agente recibe:
+
+- Contenido de la tarea específica
+- Spec completa
+- Plan completo
+- Constitución
+- Tareas ya completadas en este ciclo (contexto)
+- Lista de archivos modificados hasta ahora
+- **[Si es UI]** Perfil del sistema de diseño + mapeo de estilos Figma (del paso 4.4)
+
+El agente debe:
+1. Leer el código existente relacionado antes de escribir
+2. Seguir patrones del codebase actual
+3. Implementar SOLO lo que la tarea pide
+4. Respetar la constitución
+5. **[Si es UI]** Usar `mcp__sdd-figma__generar_componente` como punto de partida si hay node_id disponible
+6. Devolver lista de archivos modificados
+7. **NUNCA modificar `package.json` ni instalar paquetes** salvo que la spec lo indique de forma explícita — usar exclusivamente las dependencias ya presentes en el proyecto
+
+### 4.6 — Checkpoint de salida por tarea
+
+Antes de marcar la tarea como completada, verifica en dos niveles:
+
+**Nivel 1 — Verificación del criterio de la tarea:**
+```bash
+# Comando definido en la sección "Criterio de verificación" de la tarea
+[comando]
+```
+
+**Nivel 2 — Verificación de artefactos esperados:**
+```bash
+# Los archivos que el plan indicó como CREAR/MODIFICAR para esta tarea deben existir
+# Ejemplo para una tarea de backend:
+#   [ -f "src/services/nombre.service.ts" ] || echo "FALTA: archivo esperado no creado"
+#   grep -q "export" src/services/nombre.service.ts || echo "FALTA: ningún export — módulo vacío"
+```
+
+**Nivel 3 — No regresión:**
+```bash
+# Correr solo los tests que tocaron archivos modificados (fast feedback)
+# TS/JS: npx jest --findRelatedTests [archivos_modificados]
+# Python: python -m pytest [directorio_afectado] -q
+```
+
+Si cualquier nivel falla:
+1. Marca como `bloqueada` con descripción del fallo
+2. **NO continúa con tareas dependientes**
+3. Reporta al usuario:
+   > ❌ T00X falló la verificación: [razón]
+   > 
+   > ¿Qué hacemos?
+   > a) Reintentar (con corrección automática)
+   > b) Saltar y continuar (no recomendado)
+   > c) Detener y revisar manualmente
+
+### 4.7 — Actualizar estado
+
+```bash
+# .estado-tareas.json: T00X → completada
+# tareas.md: ✅ T00X, actualizar barra de progreso
+# .sdd/estado.json: ultima_actualizacion
+```
+
+### 4.8 — Hook post-tarea (opcional)
+
+```bash
+[ -f ".sdd/hooks/despues_cada_tarea.sh" ] && bash .sdd/hooks/despues_cada_tarea.sh "$TAREA_ID"
+```
+
+### 4.9 — Reportar
+
+```
+✅ T00X completada
+   Verificación: PASADA
+   Archivos modificados: [lista]
+   [N]/[M] tareas completadas ([X]%)
+```
+
+## VALIDACIÓN DE SALIDA
+
+El checkpoint de salida se aplica por tarea (ver paso 4.6 — tres niveles: criterio de tarea, artefactos esperados, no regresión). Al final de todas las tareas, la validación global se ejecuta en el PASO 5 mediante el revisor y la suite de tests completa.
+
+**Condición de bloqueo**: si cualquier checkpoint individual falla y el usuario no elige continuar explícitamente, la implementación se detiene y no avanza a `/sdd.verificar`.
+
+## PASO 5 — Al terminar todas las tareas
+
+### 5.1 — Invocar revisor
+
+```bash
+# Usar el agente revisor con modelo de su config (recomendado: opus)
+```
+
+El revisor cruza el código generado contra:
+- Los CAs de la spec
+- Las decisiones del plan
+- Los principios de la constitución
+
+### 5.2 — Invocar tester para correr toda la suite
+
+```bash
+# Detectar framework de tests automáticamente y correr
+npm test 2>/dev/null || pnpm test 2>/dev/null || yarn test 2>/dev/null || \
+  pytest 2>/dev/null || python -m pytest 2>/dev/null || \
+  cargo test 2>/dev/null || go test ./... 2>/dev/null || \
+  mvn test 2>/dev/null || gradle test 2>/dev/null || \
+  bundle exec rspec 2>/dev/null || \
+  echo "NO_FRAMEWORK_DETECTADO"
+```
+
+### 5.3 — Invocar seguridad (si la tarea tocaba área sensible)
+
+Auditoría automática si la implementación tocó: autenticación, manejo de datos personales, queries dinámicas, APIs externas, manejo de archivos.
+
+## PASO 6 — Reporte final exhaustivo
+
+```markdown
+## 📊 Implementación Completada: {ID}
+
+### Resumen
+- Tareas totales: [N]
+- Completadas: [N] ✅
+- Bloqueadas: [N] ❌
+- Omitidas: [N] ⏭️
+- Tiempo total: [duración]
+
+### Detalle por tarea
+
+| Tarea | Estado | Agente | Verificación |
+|-------|--------|--------|--------------|
+| T001  | ✅     | arquitecto | PASADA |
+| T002  | ✅     | desarrollador-backend | PASADA |
+| T003  | ❌     | tester | FALLIDA: [razón] |
+
+### Cumplimiento de Criterios de Aceptación
+
+| CA | Tarea | Cubierto | Verificado por tests |
+|----|-------|---------|---------------------|
+| CA-001-01 | T001 | ✅ | ✅ |
+| CA-001-02 | T002 | ✅ | ✅ |
+| CA-002-01 | T005 | ✅ | ⚠️ Test pendiente |
+
+### Tests
+- Suite ejecutada: [framework]
+- Tests pasados: [N]
+- Tests fallidos: [N]
+- Cobertura: [%]  (umbral mínimo: [Y]%)
+
+### Revisión final del agente revisor
+[Resumen de hallazgos]
+
+### Auditoría de seguridad (si aplicó)
+[Resumen]
+
+### Archivos modificados
+[Lista completa]
+
+### Sugerencia de commit
+```
+feat({ID}): [TÍTULO]
+
+[Resumen de cambios]
+
+Implementa: {SPEC_ID}
+Cubre: {Lista de CAs}
+```
+```
+
+## PASO 7 — Actualizar estado global
+
+```json
+{
+  "fase_actual": "implementacion_completa",
+  "historial": [..., {
+    "fase": "implementacion",
+    "id": "{ID}",
+    "fecha": "{FECHA}",
+    "resultado": "exitoso | parcial | fallido"
+  }]
+}
+```
+
+## PASO 8 — Hook post-ejecución
+
+```bash
+[ -f ".sdd/hooks/despues_implementar.sh" ] && bash .sdd/hooks/despues_implementar.sh
+```
+
+## PASO 9 — Siguientes pasos
+
+```
+🎉 Implementación terminada
+
+SIGUIENTES PASOS RECOMENDADOS:
+   /sdd.verificar       — verificación final contra spec original
+   /sdd.snapshot        — actualizar SNAPSHOT.md del producto
+   (commit a tu sistema de control de versiones manualmente)
+
+¿Quieres empezar otra feature?
+   /sdd.especificar [descripción]
+```

package/commands/sdd.importar.md

@@ -0,0 +1,91 @@
+---
+description: Importa una especificación externa (Markdown, issue de GitHub/GitLab, doc compartido) y la convierte al formato SDD-ES.
+allowed-tools: Read, Write, Bash, WebFetch
+---
+
+# /sdd.importar — Importar Spec Externa
+
+Eres el **Importador de Especificaciones**. Tomas un documento externo y lo reformulas al formato SDD-ES sin perder información.
+
+## PASO 1 — Identificar la fuente
+
+El usuario pasa la fuente como argumento:
+- URL (web, GitHub issue, GitLab issue, doc compartido)
+- Ruta a archivo local (`./mi-spec.md`, `docs/feature.txt`)
+- Texto pegado directamente
+
+```bash
+[ -f ".sdd/hooks/antes_importar.sh" ] && bash .sdd/hooks/antes_importar.sh
+
+# Si es URL, fetcheamos. Si es archivo, leemos. Si es texto, parseamos directo.
+```
+
+## PASO 2 — Extraer información
+
+Independientemente del formato origen, intenta extraer:
+
+- **Título / objetivo** del cambio
+- **Contexto / motivación**
+- **Requisitos funcionales explícitos**
+- **Criterios de aceptación** (si están)
+- **Restricciones técnicas mencionadas**
+- **Diagramas / mockups** (referencias)
+- **Personas involucradas / actores**
+
+## PASO 3 — Mapear al formato SDD-ES
+
+Convierte la información al formato estándar de spec SDD-ES (igual que `/sdd.especificar`).
+
+Donde el documento original tenga información ambigua o falte:
+- Inserta `[NECESITA_ACLARACION]: [lo que se intentó deducir]`
+- NO inventes información para completar huecos
+
+## PASO 4 — Generar ID y crear estructura
+
+```bash
+FECHA=$(date +%Y-%m-%d)
+SLUG=$(echo "$TITULO" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
+ID="${FECHA}-${SLUG}"
+
+mkdir -p ".sdd/especificaciones/${ID}"
+```
+
+## PASO 5 — Generar spec.md con marca de origen
+
+En el frontmatter de la spec:
+
+```yaml
+---
+id: {ID}
+titulo: "[TÍTULO]"
+estado: borrador
+creada: {FECHA}
+autor: importado
+origen: "[URL o ruta]"
+origen_resumen: "[breve descripción de la fuente]"
+---
+```
+
+Incluye una sección al final:
+
+```markdown
+## 99. Importación
+
+- **Fuente original:** [URL/ruta]
+- **Fecha de importación:** {FECHA}
+- **Información perdida en conversión:** [si hubo algo no mapeable]
+- **Aclaraciones requeridas:** [N puntos marcados con [NECESITA_ACLARACION]]
+```
+
+## PASO 6 — Reportar
+
+```
+✅ Spec importada
+📁 .sdd/especificaciones/{ID}/spec.md
+📥 Origen: [URL/archivo]
+⚠️  [N] puntos marcados como [NECESITA_ACLARACION]
+
+SIGUIENTES PASOS:
+   /sdd.aclarar       — resolver puntos ambiguos
+   /sdd.checklist     — validar calidad
+```

package/commands/sdd.mapear.md

@@ -0,0 +1,120 @@
+---
+description: Indexa la estructura del proyecto, símbolos públicos y dependencias. Genera mapas estáticos en .sdd/mapa/ para que Claude consulte en vez de escanear archivos.
+aliases: mapear, indexar, map, idx
+allowed-tools: Read, Write, Bash
+---
+
+# /sdd.mapear — Indexar proyecto
+
+Genera 3 archivos de mapa estático que Claude puede consultar rápidamente, ahorrando miles de tokens en lectura de código.
+
+## Uso
+
+```
+/sdd.mapear                    ← indexación inteligente (completa si es 1ª vez, incremental si existe)
+/sdd.mapear regenerar          ← fuerza re-indexación completa (tira todo, empieza de cero)
+/sdd.mapear validar            ← muestra si está obsoleto sin actualizar
+/sdd.mapear actualizar         ← fuerza actualización incremental
+```
+
+## Qué genera
+
+El comando crea `.sdd/mapa/` con:
+
+1. **estructura.md** — árbol de directorios + 1 línea por archivo (qué contiene)
+2. **simbolos.md** — funciones, clases, tipos exportados con su firma
+3. **dependencias.md** — quién depende de quién (grafo de imports)
+
+## Cómo funciona
+
+### Primera ejecución
+```bash
+/sdd.mapear
+```
+→ Indexación completa del proyecto → genera los 3 mapas
+
+**Costo**: ~5-15k tokens dependiendo del tamaño del proyecto (una sola vez).
+
+### Ejecuciones posteriores
+```bash
+/sdd.mapear
+```
+→ Detección automática de archivos modificados (con `find -newer`) → re-indexa solo lo nuevo
+
+**Costo**: ~500 tokens por archivo modificado (imperceptible).
+
+### Si quieres forzar regeneración completa
+```bash
+/sdd.mapear regenerar
+```
+→ Borra los mapas viejos y empieza de cero.
+
+**Cuándo**: Casi nunca. Solo si sospechas que el mapa está corrupto.
+
+### Para validar sin actualizar
+```bash
+/sdd.mapear validar
+```
+Salida:
+```
+📊 Estado del mapa
+├─ estructura.md       ✅ fresco (hace 2h)
+├─ simbolos.md         ✅ fresco (hace 2h)
+├─ dependencias.md     ⚠️ desactualizado (12 archivos nuevos)
+└─ Recomendación: /sdd.mapear actualizar
+```
+
+## Beneficios
+
+- **Ahorro de tokens**: En lugar de que Claude lea 50-100 archivos (50k tokens), lee 3 archivos de mapa (10k tokens)
+- **Actualización automática**: Hooks SDD actualizan el mapa después de implementar
+- **Validación perezosa**: Al inicio de cualquier comando, verifica si hay archivos nuevos y actualiza silenciosamente
+- **Control total**: Los mapas son Markdown plano, editable manualmente si necesitas
+
+## Archivos generados
+
+```
+.sdd/mapa/
+├── estructura.md            — árbol + descripción por archivo
+├── simbolos.md              — funciones, clases, tipos, exports
+├── dependencias.md          — grafo de imports + acoplamientos
+├── .estado-mapeo            — metadata: última indexación, checksums
+└── .pendientes              — lista de archivos para próxima actualización (auto-gestionado)
+```
+
+## Cómo consulta Claude estos mapas
+
+Durante comandos como `/sdd.planificar` o `/sdd.implementar`:
+
+1. Al inicio, Claude busca si existen los mapas
+2. Si existen, los lee primero (son pequeños, ~10k tokens)
+3. En lugar de correr `find . -type f`, Claude consulta mentalmente el mapa
+4. Si necesita más detalle, entonces corre `/Read archivo.ts` — pero normalmente el mapa le alcanza
+
+## Integración con otros comandos
+
+- `/sdd.planificar` — Lee mapas al inicio para entender la estructura
+- `/sdd.implementar` — Consulta grafo de dependencias antes de modificar archivos
+- `/sdd.verificar` — Mapea CAs a símbolos encontrados en `simbolos.md`
+- Hook `despues_implementar` — Marca archivos modificados para próxima actualización
+
+## Lenguajes soportados
+
+Detección automática de: TypeScript, Python, Rust, Go, Java, C#, Ruby, PHP, C/C++.
+
+Si tu proyecto usa otro lenguaje, puedes editar `.sdd/mapa/estructura.md` manualmente.
+
+## Regeneración automática
+
+El plugin NO regenera automáticamente (para no gastar tokens). Pero:
+
+- Hooks de SDD-ES actualizan después de `implementar`
+- Validación perezosa (al inicio de otros comandos) detecta cambios
+- Usuario puede forzar con `/sdd.mapear actualizar` cuando quiera
+
+## Tips
+
+- **Ignorar directorios**: Edita `.sdd/.mapeoignore` (sintaxis como `.gitignore`)
+- **Debugging**: `/sdd.mapear validar` te muestra exactamente qué está desactualizado
+- **Backup**: Los mapas anteriores se guardan como `.estructura.md.backup`, etc.
+- **Espacio**: Los mapas son pequeños (~50KB típicamente), no hay problema de disk