Spec-First Enforcement

Guia de Enforcement Spec-First

Version: 1.0 | Fase principal: F05-F06 | Track minimo: Solo (warn) Referencia: project-template/.claude/skills/spec_workflow/SKILL.md

1. Por Que Spec-First

Spec-first no es documentacion post-facto. Es la validacion de la logica de negocio ANTES de escribir codigo.

El problema que resuelve

Sin spec-first, el ciclo tipico es:

Usuario describe feature → Agente interpreta → Agente codea → Codigo refleja interpretacion incorrecta → Reescritura

Esto genera:

Desperdicio de tokens y tiempo: codigo que se descarta porque la logica estaba mal
Deuda tecnica invisible: endpoints sin contrato que nadie puede validar
Regresiones silenciosas: cambios de API sin spec que rompen integraciones

Lo que Spec-First garantiza

Usuario describe feature → Validar logica de negocio → Generar spec → Validar spec → Codear con certeza

Beneficios:

La logica de negocio se valida con el usuario ANTES de invertir en codigo
El contrato OpenAPI es la fuente de verdad — no el codigo
Cualquier agente puede implementar el mismo endpoint sin ambiguedad
Los tests de contrato se derivan automaticamente del spec
Los cambios de API son detectables y versionables

Spec-first vs documentacion

Aspecto	Documentacion post-facto	Spec-first
Momento	Despues del codigo	Antes del codigo
Proposito	Describir lo que existe	Definir lo que debe existir
Validacion	Manual, opcional	Automatizada, obligatoria
Fuente de verdad	El codigo	El contrato
Costo de error	Alto (reescritura)	Bajo (editar spec)

2. El Ciclo Completo

El flujo spec-first tiene 5 pasos, de los cuales los primeros 4 ocurren ANTES de escribir codigo:

┌─────────────────────────────────────────────────────────────────┐
│  1. Lenguaje natural: usuario describe que necesita             │
│  2. Validar logica de negocio: confirmar entendimiento          │
│  3. Generar SPEC: crear contrato OpenAPI en .openspec/          │
│  4. Validar SPEC: lint, schema check, review                   │
│  5. Codigo: implementar desde el contrato validado              │
└─────────────────────────────────────────────────────────────────┘

Paso 1: Lenguaje natural

El usuario describe la feature en sus propios terminos. No se requiere formato especifico.

Paso 2: Validar logica de negocio

El agente debe:

Identificar entidades y relaciones del dominio
Documentar reglas de negocio (invariantes, validaciones, flujos)
Confirmar con el usuario: “Entendi que X debe hacer Y cuando Z. Correcto?”
NO proceder sin confirmacion

Paso 3: Generar SPEC

Crear el contrato OpenAPI 3.1 en project/F05_contracts/.openspec/:

Request schema, response schema, error schema
Usar $ref para reutilizar schemas
Registrar entidades en data_dictionary.yaml

Paso 4: Validar SPEC

Lint del YAML (sintaxis, indentacion)
Validacion contra JSON Schema de OpenAPI
Review de consistencia con specs existentes

Paso 5: Codigo

Solo despues de los pasos 1-4:

Implementar endpoint segun contrato
Tests de contrato derivados del spec
Verificar compliance con spec-first-check.py

3. Enforcement en 4 Niveles

El enforcement spec-first opera en 4 capas complementarias, de la mas temprana a la mas tardia:

Nivel 1: Agent Instruction (prevencion)

El archivo project-template/.claude/agents/builder.md tiene un SPEC-FIRST GATE como paso 0:

Before ANY code generation:
0. SPEC-FIRST GATE: Verify .openspec/ contains a contract for what you are about to build.
   - If NO spec exists: STOP IMMEDIATELY. Do NOT write any code.
   - Instead: invoke /spec_workflow to create the spec first.

Este es el primer punto de enforcement. Si el agente sigue sus instrucciones, nunca genera codigo sin spec.

Nivel 2: Pre-commit Hook (bloqueo local)

El hook pre-commit detecta commits que agregan codigo en project/F06_build/ sin archivos correspondientes en project/F05_contracts/.openspec/:

Si el commit incluye archivos de codigo nuevos sin spec → bloqueo
El desarrollador debe crear el spec antes de commitear
Configurable via .claude/settings.json

Nivel 3: Compliance Linter (validacion continua)

El compliance-linter.py incluye checks especificos para spec-first:

Check	Codigo	Descripcion
Spec coverage	SF-01	Todo endpoint en F06 debe tener spec en .openspec/
Data dictionary	SF-02	Todo modelo de datos debe tener entrada en data_dictionary.yaml

Severidad por track:

Solo: WARNING (permite avanzar, reporta gap)
Lean: FAIL (bloquea gate si no hay spec)
Full: FAIL (bloquea gate si no hay spec)

Nivel 4: CI Gate (bloqueo en PR)

El workflow gates.yml verifica spec coverage antes de permitir merge:

PRs que agregan codigo sin spec correspondiente → PR bloqueado
El check se ejecuta como parte del gate de F06
Solo se puede bypasear con flag --skip-spec-check (requiere justificacion)

Cascada de enforcement

Nivel 1 (Agent)     → Previene que el agente genere codigo sin spec
    ↓ (si falla)
Nivel 2 (Pre-commit) → Bloquea el commit local
    ↓ (si falla)
Nivel 3 (Linter)     → Reporta violacion en validacion
    ↓ (si falla)
Nivel 4 (CI)         → Bloquea el PR en GitHub

4. Que Se Bloquea

Endpoint sin spec

Si un archivo en project/F06_build/ define un endpoint HTTP (route, controller, handler) y no existe un contrato correspondiente en project/F05_contracts/.openspec/:

Nivel 1: Agente se detiene, invoca /spec_workflow
Nivel 2: Pre-commit rechaza el commit
Nivel 3: Linter reporta SF-01 como FAIL
Nivel 4: CI bloquea el PR

Modelo sin data_dictionary

Si se crea un modelo de datos (schema, entity, migration) sin entrada correspondiente en data_dictionary.yaml:

Nivel 1: Agente verifica data_dictionary antes de crear modelo
Nivel 3: Linter reporta SF-02 como FAIL

Codigo sin directorio .openspec/

Si el proyecto tiene archivos en F06_build/ pero el directorio project/F05_contracts/.openspec/ no existe o esta vacio:

Nivel 3: Linter reporta SF-01 como CRITICAL
Nivel 4: CI bloquea cualquier PR con codigo

5. Como Generar Specs desde Lenguaje Natural

El skill /spec_workflow es la herramienta principal para generar specs. Su flujo completo es:

Fase 0: Validacion de Logica de Negocio (OBLIGATORIA)

Antes de generar cualquier spec:

Entender el requerimiento en lenguaje natural
Identificar entidades y relaciones del dominio
Documentar reglas de negocio (invariantes, validaciones, flujos)
Confirmar con el usuario
Solo despues de confirmacion: proceder a /specify

Fase 1: /specify — Especificar QUE y POR QUE

Crear spec centrada en el usuario con: feature, problema, usuario_objetivo, user_stories, criterios_aceptacion, no_goals.

Fase 2: /plan — Plan tecnico

Definir stack, arquitectura, data_model, api_contracts, dependencias, riesgos.

Fase 3: /tasks — Descomponer en tareas

Lista de tareas atomicas con orden: contratos → tests → implementacion → docs.

Fase 4: /implement — Ejecutar

Implementar tarea por tarea, verificando contra criterios de aceptacion.

Para detalle completo del flujo, invocar /spec_workflow.

6. Backward Compatibility

El enforcement spec-first respeta el track del proyecto:

Track	Severidad SF-01/SF-02	Comportamiento
Solo	WARNING	Reporta gap, permite avanzar
Lean	FAIL	Bloquea gate, requiere spec
Full	FAIL	Bloquea gate, requiere spec

Flag `--strict`

Para proyectos Solo que quieran enforcement completo:

python3 baseline/scripts/spec-first-check.py --project-dir . --track solo --strict

Con --strict, todos los tracks tratan SF-01/SF-02 como FAIL.

Migracion gradual

Para proyectos brownfield que adoptan spec-first:

Ejecutar spec-first-check.py en modo inventario (sin --strict)
Generar specs para endpoints existentes usando /spec_workflow
Una vez cubiertos todos los endpoints, activar --strict

7. Script de Verificacion

El script spec-first-check.py verifica compliance spec-first:

# Verificacion basica (respeta severidad por track)
python3 baseline/scripts/spec-first-check.py --project-dir . --track lean

# Verificacion estricta (FAIL para todos los tracks)
python3 baseline/scripts/spec-first-check.py --project-dir . --track solo --strict

# Solo inventario (lista gaps sin fallar)
python3 baseline/scripts/spec-first-check.py --project-dir . --track solo --inventory

Que verifica

Check	Codigo	Descripcion
Spec coverage	SF-01	Endpoint en F06 tiene spec en .openspec/
Data dictionary	SF-02	Modelo tiene entrada en data_dictionary.yaml
Spec drift	SF-03	Endpoint en codigo puede haber divergido del spec (method/path)
Dead spec	SF-04	Spec define endpoint que codigo ya no implementa

Output ejemplo

=== Spec-First Compliance Check ===
Track: lean | Mode: enforce

[PASS] SF-01: 12/12 endpoints have specs
[PASS] SF-02: 8/8 models in data_dictionary
[PASS] SF-03: All specs are valid OpenAPI 3.1
[WARN] SF-04: 2 specs older than their implementations

Score: 95/100
Status: PASS (2 warnings)

8. Drift Detection

A partir de v1.1, spec-first-check.py incluye deteccion de drift entre codigo y specs. No solo verifica que exista un spec, sino que el spec este sincronizado con el codigo.

SF-03: SPEC_DRIFT — Endpoint puede haber divergido del spec

Se reporta cuando:

Un endpoint en codigo tiene un method que el spec no define para ese path (ej: codigo tiene POST /api/users pero spec solo define GET /api/users)
Un endpoint en codigo tiene un path similar pero no identico al spec (ej: codigo tiene /api/v2/users pero spec define /api/v1/users)

Severidad: medium (warning, no bloquea)

[MEDIUM] SPEC_DRIFT: Endpoint POST /api/users en src/routes.ts:42 —
         spec define GET para este path pero no POST
         Fix: Actualizar spec en .openspec/ para incluir POST /api/users, o alinear codigo con spec

SF-04: DEAD_SPEC — Spec sin implementacion en codigo

Se reporta cuando:

Un spec define un endpoint (method + path) que no tiene implementacion en el codigo escaneado
Solo se reporta si el proyecto tiene al menos un endpoint de codigo (para evitar falsos positivos en proyectos sin codigo)

Severidad: medium (warning, no bloquea)

[MEDIUM] DEAD_SPEC: Spec define DELETE /api/users/{id} en project/F05_contracts/.openspec/api.yaml
         pero no se encontro implementacion en codigo
         Fix: Implementar DELETE /api/users/{id} segun el contrato, o eliminar del spec si ya no aplica

Cuando actuar

Situacion	Accion recomendada
SPEC_DRIFT por method	Agregar el method al spec o corregir el codigo
SPEC_DRIFT por path	Verificar cual es el path correcto (spec o codigo)
DEAD_SPEC intencional	Endpoint planeado pero no implementado aun — ignorar
DEAD_SPEC accidental	Endpoint eliminado del codigo — limpiar el spec

9. Escape Hatch: .specignore

Para proyectos que necesitan eximir ciertos archivos o directorios del enforcement spec-first, se puede crear un archivo .specignore en la raiz del proyecto.

Formato

El archivo sigue el mismo formato que .gitignore:

Un patron por linea
Lineas en blanco se ignoran
Comentarios con #
Patrones de directorio terminan en /
Patrones de archivo usan wildcards (*, ?)

Ejemplo de .specignore

# Directorios de experimentacion
spike/
sandbox/

# Utilidades internas sin API publica
src/utils/
src/helpers/

# Scripts de migracion
scripts/*.py

# Archivos generados
*.generated.ts

Patrones default

El script siempre aplica los siguientes patrones, incluso sin archivo .specignore:

Patron	Proposito
`test/`, `tests/`, `__tests__/`	Directorios de tests
`.test.`, `.spec.`	Archivos de test
`spike/`, `spikes/`	Spikes de exploracion
`experimental/`, `sandbox/`, `prototype/`	Codigo experimental

Output

Cuando specignore esta activo, el reporte incluye:

Specignore: 12 patterns loaded, 5 files excluded

10. Spikes y Exploracion

El framework reconoce que la exploracion es parte natural del desarrollo. No toda linea de codigo necesita un spec formal — los spikes y prototipos son herramientas validas de aprendizaje.

Tag [spike] en commits

Cuando un commit incluye el tag [spike] en su mensaje, indica que el codigo es exploratorio y no requiere spec:

git commit -m "[spike] Explorar integracion con API de pagos"

El pre-commit hook reconoce este tag y no aplica la validacion spec-first.

Flag —skip-spike-dirs

Para excluir automaticamente los directorios de exploracion:

python3 baseline/scripts/spec-first-check.py --project-dir . --skip-spike-dirs

Esto excluye automaticamente:

spike/ y spikes/
experimental/
sandbox/
prototype/

Reglas para spikes

Regla	Detalle
Duracion maxima	2-4 horas (1 sprint max)
Output esperado	Descubrimiento documentado en DISCOVERIES.md
NO llevar a produccion	El spike se descarta; el codigo final se hace con spec
Ubicacion	Siempre en directorios designados (`spike/`, `experimental/`, etc.)

Flujo recomendado

1. Crear directorio spike/nombre-exploracion/
2. Experimentar libremente (sin spec)
3. Documentar hallazgos en DISCOVERIES.md
4. Descartar el spike
5. Si el spike valida la idea: crear spec → implementar con spec-first

Referencias

Skill: project-template/.claude/skills/spec_workflow/SKILL.md
Agente: project-template/.claude/agents/builder.md (SPEC-FIRST GATE)
Regla: project-template/.claude/rules/contracts.md (Spec-First Enforcement)
Regla: project-template/.claude/rules/code_quality.md (Spec primero)
Linter: scripts/compliance-linter.py (checks SF-01, SF-02)
Acelerador: framework/accelerators/playbooks/ACC_PLAYBOOK_Spec_Kit_Acelerador_Operativo.md