AI-SDLC hybrid workflow

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:

• DOC-012 — capa sd-discover
• specs/README.md
• ADR-009

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                          │
└─────────────────────────────────────────────────────────────┘

Matriz de selección

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

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)

sd-discover (producto)

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

Convención de ramas:

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/