SDD Harness Kit

Idioma: Español · English

Versión en VERSION, cambios en CHANGELOG.md. Arranque guiado: GUIA-PASO-A-PASO.md. Guía de colaboración: CONTRIBUTING.md. Origen y créditos: CREDITS.md. Normas de este repositorio (mantenedores del kit, no del proyecto instalado): AGENTS.md / CLAUDE.md.

Artefactos portátiles de IA —subagentes, skills, hooks, standards y plantillas— para aplicar Spec-Driven Development con un harness determinista en cualquier proyecto.

Fuente canónica en ai-specs/, doctrina en docs/base-standards.md, y los ficheros de memoria (CLAUDE.md, AGENTS.md) apuntando a ella. Incluye hooks deterministas, adaptadores por stack, soporte real en Windows, doctor de salud y gates de secretos en profundidad.

# Linux / macOS
./install.sh --dest /ruta/a/mi-proyecto --dry-run   # mira qué haría
./install.sh --dest /ruta/a/mi-proyecto             # instala
./install.sh --dest /ruta/a/mi-proyecto --no-frontend
./install.sh --dest /ruta/a/mi-proyecto --frontend livewire
bash ./doctor.sh --dest /ruta/a/mi-proyecto

# Windows
.\install.ps1 -Dest C:\proyectos\mi-proyecto -DryRun
.\install.ps1 -Dest C:\proyectos\mi-proyecto
.\install.ps1 -Dest C:\proyectos\mi-proyecto -NoFrontend
.\install.ps1 -Dest C:\proyectos\mi-proyecto -Frontend livewire
.\doctor.ps1 -Dest C:\proyectos\mi-proyecto

Después: openspec init + cablear config.yaml con la plantilla del kit. Y no ejecutes /init — ver GUIA-PASO-A-PASO.md / USO.md.

Funciona igual si trabajas con los comandos nativos de OpenSpec (/opsx:explore, /opsx:propose, /opsx:apply, /opsx:sync, /opsx:archive), con los del kit, o con ambos a la vez: los 9 hooks y la doctrina actúan sobre la ruta del fichero, no sobre qué comando lo escribió. Tabla de correspondencia en MANUAL.md.

---

Qué instala

---

Las tres ideas del diseño

1. Fuente canónica única

Las skills viven una sola vez, en ai-specs/. .claude/ y .cursor/ la referencian. Editas un fichero y las dos herramientas lo ven.

Donde el sistema operativo permite symlinks, son symlinks. Donde no —Windows sin modo desarrollador— son copias, y sync-artifacts las refresca. Si los symlinks se materializan como stubs de texto, las skills no cargan: el kit lo detecta y lo arregla con copias + sync.

2. Doctrina separada del contexto

Así una actualización del kit trae correcciones del harness sin borrar el cableado del proyecto. Un hook te avisa si intentas editar doctrina por proyecto.

3. Núcleo agnóstico, adaptador por stack

Todo lo dependiente del stack está en .claude/sdd-harness.env. Los hooks lo cargan de forma segura (allowlist, sin eval); las skills lo leen como contexto dinámico. Ninguno de los dos tiene un comando escrito dentro.

Para soportar un stack nuevo no tocas ni una skill ni un hook: copias _template.env, rellenas las 24 variables del contrato, escribes .backend-standards.md, y ya está. La lista de sitios que hay que tocar para que quede completo está en CONTRIBUTING.md.

---

Los 9 hooks

Es la diferencia entre una convención escrita y una convención que se cumple.

---

Requisitos

En Windows: winget install jqlang.jq.

---

Documentación

Por dónde leer (orden recomendado)

1. GUIA-PASO-A-PASO.md — arrancar: prerrequisitos, instalar, OpenSpec, doctor, troubleshooting (Windows/Unix).
2. USO.md — qué ejecutar el día 1, qué en cada ticket y problemas frecuentes.
3. Cuando ya estés trabajando: MANUAL.md (flujo F0–F8, matriz de artefactos, reglas) + PROMPTS.md (prompts P0–P15 listos para copiar).
4. Solo si quieres el procedimiento fino de una herramienta: el SKILL.md de esa skill en core/ai-specs/skills/ (o, tras instalar, ai-specs/skills//SKILL.md en tu proyecto). Igual con los agents en core/ai-specs/agents/.

Índice de documentos

---

Idioma

Las skills, los agents, los standards y las plantillas están en inglés, porque base-standards.md §2 exige inglés en todo artefacto técnico y el agente no puede leer una regla en inglés y una instrucción en español sin incoherencia.

La documentación humana —README.md en la raíz y el resto en docs/es/ y docs/en/ (guía de arranque, uso, manual, prompts, config, ejemplo, briefing para Producto, changelog, contribuir y créditos)— está en español y en inglés, emparejada. Elige el idioma en la barra superior de cada documento o en la tabla de arriba. Los prompts en PROMPTS.en.md se pegan en inglés; los artefactos que produzcan (código, specs, commits) siguen en inglés.

---

Qué NO hace este kit

• No sustituye tu criterio. Hay cinco puntos donde se detiene y espera a un humano.
• No garantiza calidad. Garantiza que ciertos errores concretos no pasen desapercibidos: tests modificados a escondidas, specs sobreescritos, secretos en contexto, capas mezcladas, tasks.md sin verificación, suites en rojo al cerrar el turno.
• No conoce tu dominio. Todo lo que sabe está en docs/project-context.md y en sdd-harness.env. Lo que no escribas ahí, el agente se lo inventará.
• No instala OpenSpec. Es un paso aparte, y deliberadamente: openspec/ lo gobierna esa herramienta, y el kit no escribe dentro salvo sus plantillas.
• No instala Context7 ni Playwright como dependencias del repo. Deja la config MCP (npx); el primer uso descarga. Playwright MCP demuestra UI, no sustituye la suite E2E.

---

Origen

Este kit nace de los apuntes de las clases del Máster AI4Devs de LIDR Academy y toma como punto de partida ideas y convenciones de LIDR-academy/lidr-specboot (MIT), el repositorio de referencia del máster: la disposición de ai-specs/ con skills y subagentes como fuente canónica, los estándares en docs/, y los ficheros de memoria por copiloto —CLAUDE.md, AGENTS.md— apuntando a una doctrina única.

Lo que este kit añade sobre ese punto de partida:

El diseño, el afinado y todo lo anterior son trabajo propio. La deuda con lidr-specboot es de arquitectura y convenciones, y queda declarada aquí y en CREDITS.md.

Licencia

MIT.