OpenSpec

La fuente de verdad de cada cambio

OpenSpec es la convención de InnovaFamily para estructurar los cambios de software. Cada feature, bugfix o refactor de magnitud tiene su propia carpeta en /changes/ con documentos estandarizados que sirven como fuente de verdad para el equipo y los agentes de IA.

¿Qué es OpenSpec?

OpenSpec no es un formato de documentación — es una convención de trazabilidad. Cada cambio en el repositorio tiene una carpeta correspondiente en /changes/ que contiene los documentos necesarios para entender por qué se hizo, cómo se diseñó y cómo se ejecutó. Esto permite que los agentes de IA tengan contexto preciso, que las revisiones de código sean eficientes y que el equipo pueda entender cualquier cambio meses después de haberlo implementado.

Estructura de archivos

Cada feature tiene su propia carpeta dentro de /changes/.

/changes/{feature-name}/
├── proposal.md       ← Qué se hace y por qué
├── design.md         ← Cómo se implementa técnicamente
├── tasks.md          ← Plan de tareas ejecutables
└── specs/
    └── {feature}.md  ← Especificaciones detalladas

Los 4 documentos

Cada documento tiene un rol específico y un momento de creación definido en el workflow.

Proposal

proposal.md

Define el problema, la solución propuesta y las alternativas descartadas.

Cuándo usarlo

Al inicio de cualquier feature o cambio significativo.

Contiene

Contexto de negocio
Historia de usuario principal
Criterios de éxito
Decisión tomada

Design

design.md

Documenta las decisiones técnicas: arquitectura, modelo de datos y contratos.

Cuándo usarlo

Antes de comenzar la implementación.

Contiene

Arquitectura del cambio
Modelo de datos
Contrato API
Decisiones técnicas

Tasks

tasks.md

Plan de implementación dividido en tareas atómicas ejecutables por agentes.

Cuándo usarlo

Cuando el design está aprobado y se inicia la ejecución.

Contiene

Lista de tareas ordenadas
Dependencias entre tareas
Criterios de done por tarea

Specs

specs/{feature}.md

Especificaciones detalladas del feature para consulta durante la implementación.

Cuándo usarlo

Como referencia durante la ejecución y la revisión.

Contiene

Reglas de negocio
Flujos detallados
Edge cases
Criterios de aceptación técnicos

Mapping de documentos

Equivalencia entre los documentos del proceso anterior y la estructura OpenSpec. El contenido no se pierde — se reorganiza en menos archivos con mayor coherencia.

Documento actual	OpenSpec	Sección
contexto_negocio.md	proposal.md	Motivation & Context
historia_usuario.md	proposal.md + specs/	User Story
criterios_aceptacion.md	specs/	Acceptance Criteria
arquitectura.md	design.md	Architecture
modelo_datos.md	design.md	Data Model
contrato_api.md	design.md + specs/	API Contract
execution_plan.md	tasks.md	Execution Plan
plan_pruebas.md	specs/ + quality gates	Test Plan