Catálogo reutilizable de reglas, workflows y skills para agentes de desarrollo. Su propósito es que Windsurf, Cascade y los plugins de JetBrains trabajen con un proceso consistente, trazable y orientado primero al dominio.
Spec-Driven Development (SDD) significa que una especificación verificable dirige el cambio de software. Antes de modificar código se define qué problema se resuelve, qué comportamiento espera el usuario, qué reglas de negocio deben preservarse y qué evidencia demostrará que el resultado es correcto.
La spec no es un documento decorativo creado después de programar. Es el registro vivo que conecta:
necesidad del usuario
-> reglas y lenguaje del dominio
-> escenarios de aceptación
-> plan y tareas pequeñas
-> tests y cambios de código
-> evidencia de verificación
-> documentación y cierre
Este repositorio combina cuatro prácticas complementarias:
- SDD conserva intención, decisiones, trazabilidad y evidencia.
- BDD descubre el valor, los ejemplos y el comportamiento en lenguaje de negocio.
- TDD conduce el diseño interno mediante ciclos RED, GREEN y BLUE; BLUE es el refactor obligatorio, con tests verdes, para production code y test code.
- ATDD demuestra el resultado observable desde el límite ejecutable del sistema.
El diseño comienza en el negocio, no en controladores, tablas, SDKs, colas ni frameworks. Antes de elegir detalles técnicos, la spec identifica:
- la capacidad de negocio y su bounded context;
- el lenguaje ubicuo y el significado preciso de sus términos;
- quién posee cada política: agregado, entidad, value object o servicio de dominio;
- invariantes, transiciones válidas e inválidas y eventos de dominio;
- ejemplos exitosos, contraejemplos y casos límite.
De ese modelo se derivan las capas y puertos técnicos. Si el dominio no cambia, la spec debe declarar domain: not_affected y justificarlo con evidencia; no se inventan objetos de dominio para cambios que sólo afectan orquestación o entrega.
Los tres tipos de artefacto tienen responsabilidades distintas:
| Artefacto | Función | Ejemplo |
|---|---|---|
| Regla | Restricción permanente que el agente debe respetar | Orden inside-out, aislamiento de tests o límites de arquitectura |
| Workflow | Procedimiento con fases, decisiones, gates y evidencia | Crear una spec, implementar un cambio o corregir un bug |
| Skill | Criterio especializado que mejora cómo se ejecuta el trabajo | Modelado DDD/CQRS o ingeniería backend senior |
Los nombres y workflow_id son parte de la interfaz del agente. El ID del frontmatter es la identidad canónica y el nombre estable del archivo debe reflejar ese ID; ninguno se renombra salvo que cambie materialmente la intención del artefacto.
always_on: baseline breve de una regla o skill; se carga cuando también coincide su scope oglobs.model_decision: regla, skill o workflow especializado; el agente lo carga sólo cuando el alcance lo requiere.manual: workflow principal que el usuario o el agente invoca explícitamente.automatic: workflow disparado por una condición objetiva, por ejemplo validación de PR o checkpoint de contexto.
No se permiten otros valores de trigger. always_on se reserva para constituciones y perfiles compactos; una guía extensa o especializada debe usar model_decision para no consumir contexto en tareas ajenas.
La memoria global es el bootstrap compacto. Para cada tarea, el agente carga un solo workflow principal, las reglas comunes requeridas por esa fase, un solo perfil de lenguaje y únicamente las reglas de boundary afectadas. No carga el catálogo completo ni varias skills que repitan el mismo baseline.
Las reglas comunes obligatorias fijan el mínimo de seguridad, gates y dirección de dependencias. Las reglas locales del proyecto prevalecen cuando son más específicas o estrictas y no relajan ese mínimo; las reglas de lenguaje y boundary sólo lo especializan. Si dos instrucciones del mismo nivel son incompatibles, el agente debe señalar los archivos y la contradicción durante la planificación, sin inventar una tercera política.
En Cascade puede pedirse un workflow por su ID exacto. Por ejemplo:
Usa WORKFLOW-CSHARP_SDD_IMPLEMENT_CHANGE_WORKFLOW para implementar este cambio.
Usa WORKFLOW-COMMON_SDD_FIX_BUG_WORKFLOW para diagnosticar y corregir este defecto.
El agente debe abrir el archivo correspondiente, seguir sus gates y registrar el routing en la spec. No debe improvisar un workflow a partir del nombre ni sustituirlo por una lista genérica de pasos.
Una tarea tiene un solo workflow principal y puede invocar workflows de apoyo. Los workflows comunes gobiernan el ciclo SDD; los de lenguaje adaptan la ejecución; los de REST, Lambda, SNS o SQS añaden detalles del límite sin reemplazar el ciclo principal.
Ejemplo para una funcionalidad REST en C#:
WORKFLOW-COMMON_SDD_SPEC_WORKFLOW
-> WORKFLOW-COMMON_BDD_SPECIFICATION_WORKFLOW
-> WORKFLOW-CSHARP_SDD_IMPLEMENT_CHANGE_WORKFLOW # principal
-> WORKFLOW-COMMON_REST_API_DESIGN_WORKFLOW # apoyo
-> WORKFLOW-CSHARP_REST_API_WORKFLOW # adaptador
-> gates de limpieza, seguridad, cobertura y documentación
-> WORKFLOW-COMMON_SDD_VERIFY_SPEC_WORKFLOW
Un cambio vertical puede contener varios work_type, pero sigue perteneciendo a una sola spec y a un solo workflow de implementación:
domain-rule
application-command
application-query
rest-endpoint
lambda-rest-endpoint
persistence-adapter
message-consumer
domain-event
sns-publisher
sqs-consumer
composition-root
boundary-integration-test
ci-pipeline
documentation
No se crea un workflow nuevo por endpoint, use case, repositorio, evento o registro de DI. Esas unidades se expresan como tareas pequeñas dentro del lifecycle.
La taxonomía completa y las equivalencias heredadas están en common-workflow-taxonomy.md.
Todo cambio de comportamiento sigue este orden:
descubrimiento read-only: capacidad canónica + riesgo + perfil
-> Gate 1: autorizar el cambio activo y sus targets canónicos
-> descubrir valor, ejemplos, BDD y modelo de dominio
-> crear sólo el perfil L1, L2 o L3 requerido
-> Gate 2: autorizar el inicio de RED
-> Domain RED -> Gate 3-DOMAIN -> GREEN mínimo -> BLUE -> layer gate
-> Application RED -> Gate 3-APPLICATION -> GREEN mínimo -> BLUE -> core gate
-> si cambia producción externa: Boundary RED -> Gate 3-BOUNDARY
-> Infrastructure -> Interface -> Composition/IaC
-> Boundary GREEN a través del composition root real -> BLUE de capas externas
-> gates de limpieza, seguridad, cobertura y documentación según el riesgo
-> convergencia entre delta, código, tests y documentación
-> revisión final del delta y evidencia
-> consolidar en la spec canónica y archivar el cambio
-> si aplica: actualizar AI context + snapshot + índice
Los gates humanos de implementación son:
- Gate 1 autoriza escribir los artefactos de la spec.
- Gate 2 autoriza crear y ejecutar el primer RED.
- Gate 3 revisa evidencia RED real antes del GREEN de cada capa afectada. La aprobación de Domain no autoriza Application ni Boundary.
La revisión final aprueba el delta y su evidencia. Después, el workflow de consolidación actualiza la spec canónica en una ruta estable y mueve el expediente activo al archivo fechado; el estado nunca forma parte del nombre de la carpeta.
La producción de una capa no se modifica hasta que exista un test de esa capa fallando por la razón esperada, se apruebe su Gate 3 y haya pasado el gate de la capa interior. Boundary RED sólo se crea cuando cambia producción externa; si no cambia, se conserva evidencia GREEN y se registra not_affected.
Antes de editar código productivo, cada partición de comportamiento declara su TEST-*, tipo de test, capa/scope, comando standalone, fallo RED esperado y archivos productivos que desbloquea. El agente ejecuta un microciclo por partición:
clasificar el test correcto
-> escribir y ejecutar RED con producción intacta
-> aprobar Gate 3 del scope
-> implementar el GREEN mínimo sólo en archivos mapeados
-> verificar GREEN
-> ejecutar BLUE: refactorizar producción y tests manteniendo GREEN
-> verificar < 150 líneas físicas, Value Objects con semántica real y Clean Architecture
BLUE no es una revisión opcional al final. Después de cada GREEN revisa y mejora el production code y su test code: nombres, responsabilidades, duplicación, fixtures/doubles, Value Objects cuando poseen validación o invariantes, SOLID, CQRS y dependencias de Clean Architecture. Cada archivo mantenido de source, tests, configuración, CI o scripts debe quedar en menos de 150 líneas físicas; exactamente 150 falla. Si el refactor requiere comportamiento nuevo, BLUE se detiene y comienza otro RED aprobado.
La selección base es:
unit: Domain, Application y lógica frontend pura;component: componentes, hooks, páginas, rutas, accesibilidad e interacción frontend;integration/http: entrada pública REST, mensaje, worker o CLI y composición real;integration/infrastructure: use case con adapter y recurso local real;contract: validación ejecutable de CI, IaC, schemas o configuración;e2e: evidencia adicional para journeys críticos, nunca reemplazo del RED propietario.
QA manual/visual, build, lint, typecheck, cobertura o un test agregado después de implementar son evidencia complementaria; nunca desbloquean producción. Si falta el harness, sólo se puede crear el mínimo setup de test sin comportamiento productivo y después demostrar RED.
SDD separa la verdad vigente del expediente temporal del cambio:
specs/
index.md
capabilities/ # qué es verdad hoy
party-lifecycle/
spec.md
changes/
active/ # qué se propone o implementa ahora
CHG-0123-add-visibility/
change.md
delta.md
design.md
tasks.md
archive/2026/ # evidencia terminada
CHG-0122-fix-invite/
decisions/ # sólo decisiones duraderas
Al finalizar, el delta ADDED/MODIFIED/REMOVED se fusiona en la spec canónica y el cambio se archiva. Una corrección o evolución de una capacidad existente no crea otra spec permanente.
Los artefactos escalan por riesgo:
| Riesgo | Perfil |
|---|---|
| L0 | Sin carpeta SDD; diff/PR y validación nativa |
| L1 | Un change.md compacto |
| L2 | change.md, delta.md, design.md, tasks.md |
| L3 | L2 más traceability.yaml, verification.md, security-review.md, rollout.md |
parallel-tracks.md, workflow-routing.md, handoffs, checkpoints y snapshots sólo existen cuando se activa su condición. L1 usa trazabilidad directa requisito → test; L2 la mantiene compacta en tasks.md; sólo L3 exige trazabilidad exhaustiva.
Cuando se consume el 60% del contexto, WORKFLOW-COMMON_SDD_CONTEXT_CHECKPOINT_WORKFLOW crea un handoff dentro del cambio activo. El snapshot final es condicional y apunta a la spec canónica estable y al cambio archivado.
Los backends usan exactamente dos suites de runtime:
unit: comportamiento de Domain y Application sin infraestructura externa.integration: suite bajotests/integration/con dos scopes:http/como ruta canónica de compatibilidad para la entrada pública real einfrastructure/para adapters contra bases de datos, colas, caches y storage locales reales. En sistemas no HTTP, el primer scope usa la entrada real de mensaje, worker o CLI y se denomina boundary integration test, no HTTP test.
Domain, Application, HTTP integration e Infrastructure integration deben poder ejecutarse por separado, desde estado limpio y sin consumir fixtures o estado mutable de otra capa. HTTP e Infrastructure siguen siendo scopes de la misma suite integration. Las APIs de terceros se simulan con WireMock u otra herramienta equivalente; la infraestructura local se levanta con Docker, Testcontainers o emuladores fieles.
Los gates obligatorios incluyen limpieza, seguridad, documentación y cobertura de producción del proyecto de al menos 90%. Mutation testing y E2E crítico se activan según el riesgo.
Cada módulo de negocio es dueño de su composición. El ejecutable conoce la entrada pública del módulo, pero no registra manualmente sus repositorios, handlers o servicios internos.
En C#, cada módulo expone un extension method por capa:
Add<Module>Domain(...)
Add<Module>Application(...)
Add<Module>Infrastructure(...)
Add<Module>Interface(...)
Add<Module>Module(...) # fachada que compone las capas
El composition root llama únicamente a Add<Module>Module(...). Las reglas detalladas están en csharp-dependency-injection.md.
En Go, cada módulo posee internal/<module>/di, donde construye sus dependencias y expone una entrada de módulo. cmd o el composition root importa esa entrada y no cablea los detalles internos de otros módulos. Véase go-dependency-injection.md.
common/
rules/ # constitución SDD, arquitectura, testing y guardrails
workflows/ # lifecycle común y procedimientos de apoyo
skills/ # capacidades reutilizables entre lenguajes
templates/ # plantillas de evidencia y handoff
languages/
csharp/ # reglas, workflows y skills de .NET
go/ # reglas, workflows y skills de Go
react/ # React + TypeScript + Vite
web/ # frontend web ligero
tools/
validate-sdd-change.sh
validate-bdd-spec.sh
create-sdd-context-checkpoint.sh
windsurf/
common/ contiene el comportamiento canónico compartido. Los directorios de lenguaje sólo agregan detalles de ejecución y no pueden relajar los gates comunes.
El repositorio es la fuente de verdad. No deben copiarse reglas administradas dentro de cada proyecto HBK.
bash tools/windsurf/install-global.sh
bash tools/windsurf/verify-global.shLa instalación publica el catálogo de usuario en:
~/.codeium/windsurf/common/
~/.codeium/windsurf/global_workflows/
~/.codeium/windsurf/skills/
~/.codeium/windsurf/memories/global_rules.md
En macOS también se publica el fallback de sistema en /Library/Application Support/Windsurf/. Si se requieren privilegios administrativos:
sudo bash tools/windsurf/install-system.shEl instalador sincroniza el MCP compartido usado por Rider, GoLand y WebStorm. Sus roots incluyen ~/Projects/HBK y este repositorio. Después de instalar o cambiar roots se deben reiniciar completamente los IDEs.
La resolución de un workflow sigue este orden:
- catálogo canónico común o del lenguaje;
- catálogo global de usuario;
- fallback de sistema para JetBrains.
Los detalles de resolución y mantenimiento están en tools/windsurf/README.md.
El propio catálogo valida metadata, IDs, triggers, referencias, links, presupuesto always_on y thresholds compartidos mediante:
bash tools/validate-agent-catalog.shLos proyectos consumidores ejecutan la política SDD en CI mediante:
bash tools/validate-sdd-change.shLa validación comprueba estructura, IDs, routing, riesgo, orden de capas y evidencia requerida. No reemplaza los tests, la revisión de seguridad, la cobertura ni los demás gates; sólo confirma que sus artefactos son coherentes.
Para verificar el catálogo instalado localmente:
bash tools/windsurf/verify-global.sh- Las reglas reutilizables viven en
common/ylanguages/. - Las specs pertenecen al proyecto consumidor y viven en
specs/. - No se mantienen copias administradas en
.windsurf/,.agents/,.devin/,AGENTS.mdo.windsurfrulesde cada proyecto. - Los cambios al catálogo se realizan aquí, se validan y después se vuelven a publicar globalmente.
Este proyecto se publica bajo CC0 1.0 Universal. Véase LICENSE.md.