spec-driven-pipeline

Transformá tus archivos .md en código real de forma autónoma, local y con verificación garantizada.

CLI spec-driven para equipos: instala plantillas bajo specs/, descubre el repo y genera specs/project-context.md

Documentación en el repositorio

• docs/guia-equipos.md
• docs/spec-formato-unificado.md
• templates/spec-unified-template.md
• templates/_shared/zero-guesswork-system.md

Quick Start en 3 pasos

1. Instalá el paquete en tu proyecto:

npm install spec-driven-pipeline --save-dev

2. Generá la estructura specs/ y la config del pipeline:

npx spec-driven-pipeline init

Recomendado: después de init, corré npx spec-driven-pipeline run una vez para regenerar specs/project-context.md (contexto del repo sin costo de API).

Los 8 agentes del pipeline

Inicia cada fase invocando al agente correspondiente en el chat de tu IDE:

1. Iniciador de propuesta (Step 1)

• Comando: /step-1-ai-proposal-initiator
• Misión: Crear la carpeta de épica con spec.md, config.yaml de épica y proposal.md.
• Skills: epic-input-validator, ai-path-generator, epic-scope-analyzer, epic-domain-extractor.

2. Analizador de exploración (Step 2)

• Comando: /step-2-ai-exploration-analyzer
• Misión: Código + specs/library/ frente a proposal.md / spec.md → exploration.md (y refinar spec.md si aplica).
• Skills: spec-library-reader, repo-structure-scanner, technical-gap-analyzer, code-area-impact-detector.

3. Constructor de diseño (Step 3)

• Comando: /step-3-ai-design-builder
• Misión: design.md y tasks.md; mantiene coherencia con spec.md.
• Skills: technical-decision-maker, task-list-generator, fsd-architecture-planner.

4. Comportamiento y QA (Step 4)

• Comando: /step-4-ai-qa-manual-generator
• Misión: Completar reglas y escenarios en spec.md, generar testing.md, opcionalmente actualizar specs/library/.
• Skills: qa-test-matrix-builder, usage-manual-builder, qa-edge-case-expander, fsd-structure-validator.

5. Ejecutor de desarrollo (Step 5)

• Comando: /step-5-ai-dev-executor
• Misión: Implementar código según design.md / spec.md / testing.md y marcar tasks.md.
• Skills: repo-code-analyzer, task-progress-updater, code-style-enforcer, minimal-change-implementer.

6. Revisor estricto (Step 6)

• Comando: /step-6-ai-strict-reviewer
• Misión: Auditoría frente a spec.md, design.md, tasks.md, testing.md.
• Skills: diff-change-detector, code-style-reviewer, task-completion-verifier.

7. Organizador de commits (Step 7)

• Comando: /step-7-ai-commit-splitter
• Misión: Plan de Conventional Commits atómicos (cruza con tasks.md en specs/changes/).
• Skills: conventional-commit-generator.

8. Archivador (Step 8)

• Comando: /step-8-ai-archiver
• Misión: Promover a specs/library/; archivar en specs/changes/archive/[épica]/ (raíz: cuatro .md + .openspec.yaml desde config.yaml; carpeta specs/ con spec.md y testing.md); luego rm -rf la carpeta activa en specs/changes/[épica].
• Skills: ai-archiver.

Equivalente por entorno: SPEC_VERIFICATION_PATH con la misma ruta que --spec.

Otras formas de instalar el CLI

Sin instalar dependencia (solo npx)

npx spec-driven-pipeline init
npx spec-driven-pipeline run

Sin dejar paquete en el proyecto (ya cubierto arriba)

npx usa la versión publicada; para fijar versión podés usar npx spec-driven-pipeline@2 ....

Comandos del CLI

init

Copia plantillas, pipeline.config.yaml y el árbol bajo specs/ (flujo interactivo según el entorno). Primer paso para alinear Cursor, Windsurf u otros flujos con el pipeline.

npx spec-driven-pipeline init

run o sync

Alias: run y sync hacen lo mismo. En el directorio actual:

• Crea carpetas necesarias bajo la raíz de documentación del pipeline.
• Mantiene specs/config.yaml, índice de skills y archivos de equipo.
• Ejecuta auto-discovery y regenera specs/project-context.md (stack, scripts, entrypoints heurísticos, árbol acotado respetando .gitignore).

npx spec-driven-pipeline run

Qué incluye el paquete

• 33 skills de arquitectura y flujo: reglas y prompts en templates/skills/ para que la IA respete Clean Architecture, FSD, análisis de repo, QA, riesgo, estilo y buenas prácticas de equipo (alineadas al baseline Zero-Guesswork).
• Plantillas de agentes por pasos del pipeline en templates/agents/.
• Documentación en el repo (enlaces abajo).

Desarrollo y contribución

Instalación global del CLI

npm install -g spec-driven-pipeline
spec-driven-pipeline init

Trabajar con el código fuente (npm link)

Para probar cambios locales del CLI antes de publicar, o usar el clon del repo sin pasar por una versión publicada:

1. Cloná e instalá:

git clone https://github.com/dgiannico19/spec-driven-pipeline.git
cd spec-driven-pipeline
npm install

2. En el clon:

npm link

3. En otro proyecto:

cd /ruta/a/tu-proyecto
npm link spec-driven-pipeline

4. Usá npx spec-driven-pipeline como siempre.

Desenlazar en el proyecto: npm unlink spec-driven-pipeline. En el clon del framework: npm unlink -g desde la carpeta del repo.

Incidencias y PRs: issues en GitHub.

Licencia

MIT. Texto completo: LICENSE.