SDD Devkit

imageversion imagelicense

SDD Devkit es un framework de SDD (Spec-Driven Development), distribuido como Agent Plugin, cuyo objetivo es ayudarte en la preparación, planificación e implementación de proyectos de desarrollo. Su flujo:

1. Prepara el harness del proyecto: los archivos base, el stack tecnológico, las decisiones de arquitectura (ADRs), los estándares y una compuerta de calidad para que los agentes trabajen con contexto.
2. Refina el requerimiento y lo descompone hasta el detalle que pide una implementación sin ambigüedades: modelos, diagramas, flujos, wireframes y planes de implementación (historias de usuario o tareas de mantenimiento).
3. Orquesta la implementación con worktrees, de modo que cada plan se implementa de forma independiente.
4. Cierra con puertas de calidad: revisión de código, pruebas, cobertura de los criterios de aceptación e integración o Pull Request.

Instalación

Instala el plugin completo, no skills sueltos. Es compatible con cualquier agente que soporte el estándar abierto Agent Plugins, entre ellos:

Cursor:

/add-plugin https://github.com/juanca202/sdd-devkit

VS Code:

Paleta de comandos (Ctrl/Cmd+Shift+P) → Chat: Install Plugin From Source → pega https://github.com/juanca202/sdd-devkit

Kiro:

Panel de Powers → Add Custom Power → Import power from GitHub → pega https://github.com/juanca202/sdd-devkit

Claude Code (tiene su propio sistema de plugins, no usa el estándar Agent Plugins):

/plugin marketplace add juanca202/sdd-devkit
/plugin install sdd-devkit@juanca202

Configuración del proyecto

La primera vez que uses el plugin en un proyecto, /arch-init crea .sdd-devkit/settings.json en la raíz principal (en una solución multi-repo, la del repo de especificaciones: es un único archivo para toda la solución, nunca uno por submódulo). Ahí eliges el idioma de los documentos, dónde viven tus especificaciones, cuánto te pregunta el agente antes de commitear, implementar o corregir algo, y cuántos intentos hace sobre un problema que no logra resolver antes de devolvértelo. Puedes dejarlo todo en sus valores por defecto y ajustarlo cuando quieras.

Detalle de cada opción en SETTINGS.md.

Empezar desde un repositorio

/arch-init puede recibir las URLs (o rutas) de los repositorios con los que arranca el proyecto, cada una con un indicador que dice qué es:

/arch-init base https://github.com/mi-org/plantilla-api.git        # proyecto base: se clona y queda como remote upstream
/arch-init existing https://github.com/mi-org/pedidos-api.git      # repo existente: se clona tal cual, origin intacto
/arch-init existing <url-backend> base <url-plantilla-frontend>    # varios repos → multirepo

• base: una plantilla, starter o semilla corporativa. No es el repo del proyecto, solo su punto de partida; queda como remote upstream y origin se agrega cuando exista el remoto propio.
• existing: el repositorio del proyecto ya existe; se usa sin reconfigurar remotos.
• Una URL → monorepo. Dos o más → multirepo: se crea un repositorio de especificaciones y cada URL se agrega como submódulo.
• Sin indicador, el skill pregunta si la URL es un proyecto base o el repo existente. Sin URLs, pregunta la topología (monorepo / multirepo) y trabaja sobre el directorio actual.

Más detalle en SKILLS.md.

Skills incluidos

Detalle de uso, opciones y ejemplos de cada skill: SKILLS.md.

Harness

Skills que preparan y mantienen la base del proyecto — arquitectura y control de versiones — independientes del requerimiento en el que estés trabajando.

Flujo del harness

arch-init es el punto de entrada: detecta en qué estado está el proyecto, prepara la base y te lleva a la compuerta de calidad. Desde ahí se pasa al flujo de implementación de requerimientos.

flowchart TD
    INIT["Inicialización<br/>**/arch-init**"]
    subgraph BF["Proyecto con código existente"]
        BA["Descubrimiento de arquitectura<br/>**/arch-discover**"]
        BA -.-> WR["Descubrimiento de funcionalidades<br/>**/work-research**"]
        WR -.-> TD["Casos de prueba<br/>**/test-define**"]
    end
    INIT --> BA
    INIT --> T["Compuerta de calidad<br/>(vía **/arch-init**)"]
    BA --> T
    WR -.-> T
    TD -.-> T
    T --> S["Arquitectura: ADRs y estándares<br/>**/arch-manage**"]
    S -.-> AUD["Auditoría<br/>**/arch-audit**"]
    subgraph NESTED["Implementación de requerimientos"]
        IMPL["ver diagrama siguiente"]
    end
    S --> IMPL
    IMPL --> DONE(["Entregable"])

    classDef nestedFlow fill:#fff7ed,stroke:#ea580c,stroke-width:2px,stroke-dasharray:5 5,color:#9a3412
    classDef entryPoint fill:#dcfce7,stroke:#15803d,stroke-width:3px,color:#14532d
    classDef exitPoint fill:#fee2e2,stroke:#b91c1c,stroke-width:3px,color:#7f1d1d
    class IMPL nestedFlow
    class INIT entryPoint
    class DONE exitPoint

1. Todo empieza con arch-init: prepara la base y el stack, partiendo del directorio actual o de los repositorios que le pases (base / existing; si hay varios, uno de especificaciones agrupa a los demás como submódulos).
2. Si el proyecto ya tiene código, arch-init te lleva a descubrir su arquitectura (arch-discover) y, si quieres, sus funcionalidades (work-research) y casos de prueba (test-define).
3. Se configura la compuerta de calidad.
4. Se documentan o actualizan los ADRs/estándares (arch-manage); opcionalmente se audita el cumplimiento (arch-audit).
5. Con la base lista, entras al flujo de implementación de requerimientos (siguiente sección).

Specs

Skills del ciclo de vida de un requerimiento: de la idea al Pull Request mergeado.

Flujo de implementación

Seguir este flujo te da trazabilidad de punta a punta (cada línea de código rastreable hasta su historia y su criterio de aceptación), calidad consistente en cada entrega, y la posibilidad de pausar y retomar el trabajo sin perder contexto. Los pasos con línea punteada son opcionales.

flowchart TD
    A[Requerimiento] --> B["Historias de usuario<br/>**/work-define**"]
    A -.-> Z["Refinar el requerimiento<br/>**/requirement-refine**"]
    Z -.-> B
    B -.-> C["Casos de prueba<br/>**/test-define**"]
    B -.-> D["Diseño técnico<br/>**/design-define**"]
    B --> E["Planificación de tareas<br/>**/work-plan**"]
    A -.->|tareas de mantenimiento| E
    E -.-> F["Investigación<br/>**/work-research**"]
    E -.-> D
    E --> G["Implementación<br/>**/work-implement**"]
    C -.->|automatizar pruebas| G
    G --> H["Integración directa<br/>**/work-integrate**"]
    G --> I["Creación de PR<br/>**/pr-create**"]
    H --> J(["Entregable"])
    I --> J

    classDef main fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef entryPoint fill:#dcfce7,stroke:#15803d,stroke-width:3px,color:#14532d
    classDef exitPoint fill:#fee2e2,stroke:#b91c1c,stroke-width:3px,color:#7f1d1d
    class B,E,G,I main
    class A entryPoint
    class J exitPoint

1. Un requerimiento se convierte en historias de usuario (work-define). Si llega ambiguo, puedes refinarlo primero con requirement-refine. Si es una tarea de mantenimiento sin historia, pasa directo a planificación.
2. Opcionalmente, desde la historia se definen casos de prueba (test-define) y/o diseño técnico (design-define).
3. Se planifican las tareas técnicas de la historia, o la tarea de mantenimiento (work-plan).
4. Las tareas se implementan (work-implement); los casos de prueba también pueden automatizarse ahí.
5. El trabajo se cierra integrándolo directo a tu rama de desarrollo (work-integrate) o mediante un Pull Request (pr-create) — ambos verifican calidad, revisan el código y validan la cobertura de pruebas antes de dar por cerrado el trabajo.

Integración con otros frameworks de implementación

¿Ya usas Speckit, OpenSpec, AgentOS u otro framework de specs para implementar? SDD Devkit puede cubrir solo hasta las historias de usuario (y, si quieres, investigación, casos de prueba y diseño técnico) y dejarte el resto a tu framework — el cierre sigue siendo el mismo.

flowchart TD
    A[Requerimiento] --> B["Historias de usuario<br/>**/work-define**"]
    A -.-> Z["Refinar el requerimiento<br/>**/requirement-refine**"]
    Z -.-> B
    B -.-> R["Investigación<br/>**/work-research**"]
    B -.-> C["Casos de prueba<br/>**/test-define**"]
    B -.-> D["Diseño técnico<br/>**/design-define**"]
    subgraph NESTED["Tu framework · Speckit / OpenSpec / AgentOS…"]
        S["Specs e implementación"]
    end
    B --> S
    S --> H["Integración directa<br/>**/work-integrate**"]
    S --> I["Creación de PR<br/>**/pr-create**"]
    H --> J(["Entregable"])
    I --> J

    classDef main fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef nestedFlow fill:#fff7ed,stroke:#ea580c,stroke-width:2px,stroke-dasharray:5 5,color:#9a3412
    classDef entryPoint fill:#dcfce7,stroke:#15803d,stroke-width:3px,color:#14532d
    classDef exitPoint fill:#fee2e2,stroke:#b91c1c,stroke-width:3px,color:#7f1d1d
    class B,H,I main
    class S nestedFlow
    class A entryPoint
    class J exitPoint

Las historias alimentan tu framework de terceros; al cerrar, work-integrate/pr-create corren igual las puertas de calidad sobre el entregable. Lo que genere tu framework (sus propias specs, planes o tareas) no lo toca SDD Devkit — solo archiva sus propios artefactos (requisitos, historias, tareas de mantenimiento e investigaciones), y solo cuando tú lo pides al skill que los produjo con el modificador archive.

Nivel de responsabilidades

Tú defines la intención, las restricciones y las decisiones importantes; el agente resuelve los detalles dentro de esos límites.

Casos de uso

Recorridos completos que combinan varios skills para una situación concreta.

Contribuir

Las contribuciones son bienvenidas. Antes de abrir un issue o un Pull Request, lee la guía de contribución.

Licencia

Este proyecto es de código abierto y se distribuye bajo la licencia MIT.