specs, changes, artifacts: Los Tres Conceptos Fundamentales de OpenSpec

Puedes usar los comandos de OpenSpec sin entender el modelo subyacente y las cosas funcionarán en su mayor parte — pero en el momento en que te preguntes "¿qué está haciendo realmente este comando?", tendrás que volver aquí de todas formas. Es mejor entender bien los tres conceptos fundamentales ahora, para que cada paso de aquí en adelante tenga más sentido.

Specs: Cómo Se Ve tu Sistema Ahora Mismo

openspec/specs/ es la fuente de verdad — describe cómo funciona tu sistema actualmente.

No lo que quieres en el futuro. Lo que existe ahora.

Organizado en carpetas por dominio:

openspec/specs/
├── auth/
│   └── spec.md       # Cómo funciona el inicio de sesión, autenticación y sesiones
├── payments/
│   └── spec.md       # Flujo de pago
└── ui/
    └── spec.md       # Comportamiento de la interfaz y temas

Dentro de cada spec.md, se ve así:

# Auth Specification
 
## Purpose
Authentication and session management for the application.
 
## Requirements
 
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
 
#### Scenario: Valid credentials
- GIVEN a user enters correct credentials
- WHEN the login form is submitted
- THEN a JWT token is returned
- AND the user is redirected to the dashboard
 
#### Scenario: Invalid credentials
- GIVEN a user enters incorrect credentials
- WHEN the login form is submitted
- THEN an error message is shown
- AND no token is issued

Algunos puntos clave:

Los Requirements describen "qué debería hacer el sistema," no "cómo implementarlo" — usando el lenguaje del RFC 2119:

• SHALL / MUST — Requisito absoluto, sin excepciones
• SHOULD — Recomendado, pero se permiten excepciones
• MAY — Opcional

Los Scenarios describen "ejemplos concretos" usando una estructura Given/When/Then. Cada escenario debería ser verificable — podrías escribir una prueba automatizada a partir de él.

Lo que los specs no incluyen: nombres de clases, qué bibliotecas usar, cómo está estructurada la base de datos — eso es trabajo de design.md. Los specs solo describen "comportamiento visible para usuarios o sistemas externos."

Changes: Cada Modificación Obtiene Su Propia Carpeta

openspec/changes/ contiene modificaciones en progreso — cada funcionalidad que quieres agregar o cambiar vive aquí en su propia carpeta hasta que esté completa y archivada.

openspec/changes/
└── add-dark-mode/
    ├── proposal.md
    ├── design.md
    ├── tasks.md
    └── specs/
        └── ui/
            └── spec.md   ← delta spec para este cambio

Múltiples cambios pueden estar en progreso simultáneamente sin interferencia — porque cada uno vive en su propia carpeta, no entran en conflicto.

Artifacts: Cuatro Documentos Dentro de Cada Change

Una carpeta de cambio típicamente contiene cuatro artifacts, cada uno con un propósito distinto:

Estos cuatro artifacts tienen dependencias entre sí, pero no estás obligado a seguir un orden estricto:

proposal → specs → design → tasks → implementation
   ↑          ↑        ↑                  │
   └──────────┴────────┴──────────────────┘
        Los problemas descubiertos durante la implementación
        siempre pueden ser abordados actualizando los artifacts

proposal.md responde el "por qué" — la motivación para el cambio, su alcance y la dirección general. No necesita ser largo; solo necesita ser claro.

specs/ (delta spec) dice "qué comportamientos están cambiando" — usando tres secciones: ADDED, MODIFIED y REMOVED:

# Delta for UI
 
## ADDED Requirements
 
### Requirement: Theme Selection
The system SHALL allow users to switch between light and dark themes.
 
#### Scenario: Manual toggle
- GIVEN the user is on any page
- WHEN the theme toggle button is clicked
- THEN the theme switches immediately
- AND the preference is saved so it persists after page reload
 
## MODIFIED Requirements
(si aplica)
 
## REMOVED Requirements
(si aplica)

Al archivar, los requisitos ADDED se fusionan en la especificación principal, los requisitos MODIFIED sobrescriben la versión anterior, y los requisitos REMOVED se eliminan.

design.md responde el "cómo" — enfoque técnico, decisiones de arquitectura, elección de bibliotecas, diseño del flujo de datos. Aquí es donde pertenecen los detalles de implementación; la spec no necesita tocarlos.

tasks.md es la lista de verificación — cuando la IA ejecuta /opsx:apply, ejecuta esta lista elemento por elemento:

# Tasks
 
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext to manage light/dark state
- [ ] 1.2 Add custom properties to CSS
- [ ] 1.3 Implement localStorage preference persistence
 
## 2. UI Components
- [ ] 2.1 Build ThemeToggle component
- [ ] 2.2 Add settings page

La Relación Entre los Tres, en Una Oración

specs es el estado actual, changes es lo que está en progreso, y artifacts son los cuatro documentos dentro de cada change que juntos explican "qué construir, cómo construirlo, y las tareas concretas."

Después de archivar, el delta spec del change se fusiona en specs, la carpeta del change se mueve al archivo, y el ciclo continúa.

Con estos tres conceptos claros, el siguiente artículo te guía a través de /opsx:propose → apply → archive — el flujo de trabajo principal. Explica qué hace cada comando, qué necesitas verificar y cuándo avanzar.

Siguiente: /opsx:propose → apply → archive: Ejecutar un Flujo de Trabajo Completo de OpenSpec