AI-SDLC hybrid workflow

Spec Kit vs OpenSpec, commands, and human gates (DOC-013).

Source: docs/development/DOC-013-ai-sdlc-hybrid-workflow.md

DOC-013: AI-SDLC Hybrid Workflow (Spec Kit + OpenSpec)

Estado

Approved (seed)

Contexto

Modelo híbrido de Specification-Driven Development:

  • GitHub Spec Kit — iniciativas estratégicas (multi-módulo, >1 semana, impacto arquitectónico).
  • OpenSpec — desarrollo operativo (bugs, endpoints, refactors, DX/CI).

Guía operativa para elegir herramienta, comandos y gates humanos.

Documentos relacionados:


Las cuatro capas de especificación

┌─────────────────────────────────────────────────────────────┐
│  Capa 1 — Fundación                                         │
│  DOC-001 · dominio · ADRs · DOC-009 · contratos             │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  Capa 2 — sd-discover (producto)                            │
│  brief.md · spikes · use-cases · gates humanos              │
└──────────────────────────────┬──────────────────────────────┘
                               │
              ┌────────────────┴────────────────┐
              ▼                                 ▼
┌──────────────────────────┐    ┌──────────────────────────────┐
│  Capa 3a — ESTRATÉGICO   │    │  Capa 3b — OPERATIVO         │
│  GitHub Spec Kit         │    │  OpenSpec                    │
│  specs/<NNN-feature>/    │    │  openspec/changes/<name>/    │
└──────────────┬───────────┘    └──────────────┬───────────────┘
               │                               │
               └───────────────┬───────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  Capa 4 — Implementación                                    │
│  código · tests · PR · CI · deploy                          │
└─────────────────────────────────────────────────────────────┘
CapaHerramientaPregunta que responde
Fundacióndocs/ + ADRs¿Qué producto es?
sd-discover/sd-*¿Qué significa esta feature?
EstratégicoSpec Kit¿Cómo planificamos una iniciativa grande?
OperativoOpenSpec¿Cómo implementamos un cambio acotado?

Matriz de selección

Tipo de cambioSpec KitOpenSpec
Nueva línea de negocio✓
Nuevo módulo principal✓
Nueva app / plataforma✓
Integración estratégica✓
Cambio arquitectónico✓
Corrección de bug✓
Nuevo endpoint acotado✓
Ajuste UI✓
Refactorización local✓
Optimización✓
Infra / DX / CI✓ (sin brief)

Regla práctica (cualquiera de estas → Spec Kit):

  • Introduce o expande un módulo / bounded context.
  • Toca ≥ 2 capas (Backend + Frontend, etc.).
  • Requiere ADR nuevo o cambio arquitectónico.
  • Agrupa varias stories / pantallas o dura > 1 semana.

Algoritmo de decisión (obligatorio antes de /opsx:propose o /speckit.specify)

1. ¿Es infra / DX / CI / bugfix / refactor SIN tocar dominio?
   → OpenSpec directo (sin brief). FIN.

2. ¿Tiene brief de dominio (FEAT-xxx) en docs/product/features/?
   → NO  → /sd-feature-brief primero. FIN.
   → SÍ  → continuar.

3. ¿Coincide con CUALQUIER fila estratégica de la matriz?
   → SÍ  → Spec Kit OBLIGATORIO: /speckit.specify → plan → tasks,
           y descomponer en slices OpenSpec (tabla en plan.md). FIN.
   → NO  → continuar.

4. ¿Es un cambio acotado DENTRO de un módulo YA especificado en specs/?
   → SÍ  → OpenSpec directo, citando Strategic spec padre. FIN.
   → NO  → por defecto Spec Kit (ante la duda, especificar).

Consecuencia: una feature de dominio que estrena un módulo no entra por OpenSpec directo. Entra por Spec Kit y luego se parte en changes OpenSpec.


Comandos por herramienta

PrefijoCursorCopilotClaude CodeGemini CLI
/sd-*.cursor/commands/sd-*.md.github/prompts/sd-*.prompt.md.claude/commands/sd-*.md.gemini/commands/sd-*.toml
/speckit.*.cursor/commands/speckit.*.github/prompts/speckit.*.claude/skills/speckit-*/ (hyphen).gemini/commands/speckit.*.toml
/opsx:*.cursor/commands/opsx-*.md.github/prompts/opsx-*.prompt.md.claude/commands/opsx-*.md.gemini/commands/opsx-*.toml

OpenCode: mismos stems en .opencode/commands/ (markdown). Hub: .cursor/; sync con ./scripts/sync-agents.sh o make sync-agents FROM=<superficie> si editaste otra herramienta.

Nota Claude: Spec Kit instala skills como /speckit-specify (guión), no /speckit.specify.

Codex (desktop / CLI / IDE): AGENTS.md carga el protocolo de agents/codex.md y el índice agents/codex-rules.md. Skills del repo en .agents/skills/, generadas con make sync-agents. Invocar por selector o nombre en lenguaje natural; en CLI/extensión también $init-session, $sd-feature-brief, $openspec-propose, $speckit-plan. Los procedimientos y gates son los mismos; el menú slash y los hooks de Cursor no se trasladan automáticamente. Guía y tabla completa de equivalencias Codex.

Codex edita skills mediante symlinks al hub; después ejecutar make sync-agents FROM=codex. Los adaptadores Spec Kit leen .cursor/commands/speckit.*.md; los comandos fuente siguen administrados por Spec Kit. El sync también regenera el índice de reglas MDC. Verificación: make test-agent-sync.

Sesión (siempre)

ComandoCuándo
/init-sessionAl abrir
/cierre-sessionAl cerrar

sd-discover (producto)

ComandoUso
/sd-exploreIdea vaga, trade-offs
/sd-spikeDecisión técnica GO/NO-GO
/sd-feature-briefbrief.md para dominio
/sd-use-caseCaso de uso detallado
/sd-screen-specSpec de pantalla S-xxx
/sd-wireframeWireframe HTML

Spec Kit

/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement

OpenSpec

/opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive

CLI:

openspec new change "<nombre-kebab>"
openspec status --change "<nombre>"
openspec validate
openspec list

Vinculación Spec Kit ↔ OpenSpec

  1. En plan.md del Spec Kit: tabla OpenSpec implementation slices (plantilla en docs/development/templates/).
  2. Cada slice → /opsx:propose con sección Trazabilidad citando parent + Slice ID.
  3. Al archivar → actualizar fila del plan padre a archived.

Strategic spec: N/A solo permitido en changes sin dominio (infra/DX/CI/bugfix localizado).


Git

ComandoUso
/sd-branchCrear rama feature/, bugfix/, etc.
/sd-prAbrir PR sin merge automático
/cierre-sessionCierre + ship (scripts/sd-ship.sh)

Convención de ramas:

TipoFormato
OpenSpecfeature/<change-name>
Spec Kitfeature/spec-<NNN>-<short-name>
Bugfixbugfix/<short-name>
Chorechore/<short-name>

Base branch: master (ADR-017; override con SD_BASE_BRANCH solo si un ADR lo redefine).


Gates humanos

  • Brief Status: approved antes de specify/propose de dominio.
  • Plan/design revisado antes de implement/apply.
  • PR + CI verdes antes de merge.
  • Archive OpenSpec explícito cuando el change está hecho.

Referencias

  • Constitution: .specify/memory/constitution.md
  • Sesión: docs/README-METODOLOGIA-SESION.md
  • Templates: docs/development/templates/