spec-driven

Los artefactos del flujo de trabajo predeterminado: su orden, sus formatos y la carpeta de cambio que producen.

spec-driven es el esquema predeterminado integrado de OpenSpec. schema.yaml define los campos que establece.

Artefactos

El flujo de trabajo redacta cuatro artefactos:

Artefacto	Archivo	Propósito
proposal	proposal.md	Por qué se necesita el cambio
specs	specs/<capability-path>/spec.md, uno por capacidad	Qué comportamiento cambia
design	design.md	Cómo construirlo
tasks	tasks.md	La lista de verificación de implementación

Orden de redacción

             ┌─ specs ──┐
proposal ────┤          ├── tasks ── apply
             └─ design ─┘

La propuesta va primero. Las especificaciones y el diseño siguen en cualquier orden, y las tareas requieren ambas. La implementación (apply) comienza una vez que tasks.md está en su lugar.

Se pueden omitir dos artefactos:

• design: cuando ninguna de sus condiciones aplica, el agente lo deja fuera y de todos modos redacta tasks.
• specs: establece skip_specs: true en el .openspec.yaml del cambio.

Ejemplo de carpeta de cambio

Un cambio llamado add-user-auth, con todos los artefactos redactados:

openspec/changes/add-user-auth/
├── .openspec.yaml      metadatos del cambio, escritos cuando se crea el cambio
├── proposal.md
├── specs/
│   └── user-auth/
│       └── spec.md     un delta de especificación por capacidad
├── design.md
└── tasks.md

proposal.md

Establece por qué se necesita el cambio.

Estructura

La plantilla que recibe el agente como formato de salida (templates/proposal.md):

# Proposal

## Why

<!-- Explain the motivation for this change. What problem does this solve? Why now? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->

## Capabilities

### New Capabilities
<!-- Capabilities being introduced. Name each capability for a cohesive system
     behavior that can own related requirements as the system evolves. Do not name
     implementation tasks or proposal sections. Avoid broad catch-all names. Use
     kebab-case for path segments you introduce (e.g., user-auth or identity/user-auth)
     that follow the project's existing spec organization. Each creates
     specs/<capability-path>/spec.md. -->
- `<capability-path>`: <brief description of what this capability covers>

### Modified Capabilities
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
     Only list here if spec-level behavior changes. Each needs a delta spec file.
     Use the exact existing path under openspec/specs/. Leave empty if no requirement
     changes. A change with no capabilities at all (pure refactor, tooling, docs)
     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
     a zero-delta change without that marker. Do not invent a requirement just to
     satisfy validation. -->
- `<existing-capability-path>`: <what requirement is changing>

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Instrucciones

La instrucción enviada al agente cuando redacta este artefacto (de schema.yaml):

Create the proposal document that establishes WHY this change is needed.

Sections:
- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
- **Capabilities**: Identify which specs will be created or modified:
  - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Name each capability for a durable system behavior (for example, `user-auth`), not the work in this change (for example, `add-login-endpoint`). Choose a cohesive boundary that can own related requirements as the system evolves; avoid broad catch-all capabilities. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
  - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
- **Impact**: Affected code, APIs, dependencies, or systems.

IMPORTANT: The Capabilities section is critical. It creates the contract between
proposal and specs phases. Research existing specs before filling this in:
run `openspec list --specs` for the project's capability inventory, then
`openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
look related - that returns a capability's purpose and requirement texts
without pulling whole spec files into context. Append `--store "<id>"` to
both commands only for a registered standalone store, and keep `--type
spec`: a change and a spec sharing a name is otherwise an ambiguous-item
error. `openspec list` without `--specs` lists in-flight changes, not
specs - it never shows what the project already covers. Reuse an existing
capability's exact path instead of introducing a near-duplicate name.
The filtered read is only an overview. Before deciding what is already
covered or what should change, read each relevant spec in full, including
scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
Each capability listed here will need a corresponding spec file.

Every change must either declare at least one capability (new or
modified) or explicitly opt out of specs: `openspec validate` rejects a
change with zero deltas unless the change's `.openspec.yaml` sets
`skip_specs: true`. Use `skip_specs: true` only when no spec-level
behavior changes (pure refactor, tooling, docs) - specs describe
behavior, so if behavior does not change, no spec should change either.
Do not invent a requirement just to satisfy validation.

Keep it concise (1-2 pages). Focus on the "why" not the "how" -
implementation details belong in design.md.

This is the foundation - specs, design, and tasks all build on this.

Deltas de especificación (spec.md)

Define qué comportamiento cambia, con un delta de especificación por capacidad que la propuesta enumera.

Cada delta de especificación es el spec.md dentro de su carpeta de capacidad. openspec validate y openspec archive rechazan las secciones delta escritas en cualquier otro archivo bajo specs/, como specs/user-auth.md, porque el archivado nunca las fusiona.

Estructura

La plantilla que recibe el agente como formato de salida (templates/spec.md):

# Spec Delta

## Purpose
<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->

## ADDED Requirements

### Requirement: <!-- requirement name -->
<!-- requirement text -->

#### Scenario: <!-- scenario name -->
- **WHEN** <!-- condition -->
- **THEN** <!-- expected outcome -->

Instrucciones

La instrucción enviada al agente cuando redacta este artefacto (de schema.yaml):

Create specification files that define WHAT the system should do.

A spec is a behavior contract, not an implementation plan.

Good spec content:
- Observable behavior users or downstream systems rely on
- Inputs, outputs, and error conditions
- External constraints (security, privacy, reliability, compatibility)
- Scenarios that can be tested or explicitly validated

Avoid in specs:
- Internal class/function names
- Library or framework choices
- Step-by-step implementation details
- Detailed execution plans (those belong in design.md or tasks.md)

Quick test: if the implementation can change without changing externally
visible behavior, it likely does not belong in the spec.

Create one spec file per capability listed in the proposal's Capabilities section.
`<capability-path>` is the spec directory relative to `specs/` (for example,
`user-auth` or `identity/user-auth`). Preserve the full path:
- New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
- Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.

Write the spec files one at a time, so the user sees progress and an
interrupted run keeps the files it already wrote:
- Before writing anything, compare the capabilities the proposal lists
  with the `specs/<capability-path>/spec.md` files that already exist,
  and start with the first capability that has no file. Do not rewrite
  an existing file unless the user asks you to.
- Before each file, say in one line which capability you are writing.
- Write each file as soon as you have drafted it. Do not plan every file
  before writing the first.
- Stop when every capability the proposal lists has its file.

There must be at least one spec file unless the change's `.openspec.yaml`
sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
rejects a zero-delta change without that marker. If the proposal lists no
capabilities and `skip_specs` is not set, revisit the proposal first.

Delta operations (use ## headers):
- **ADDED Requirements**: New capabilities
- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
- **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
- **RENAMED Requirements**: Name changes only - use FROM:/TO: format

Format requirements:
- Each requirement: `### Requirement: <name>` followed by description
- Use SHALL/MUST for normative requirements (avoid should/may)
- Each scenario: `#### Scenario: <name>` with WHEN/THEN format
- **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
- Every requirement MUST have at least one scenario.
- Every scenario MUST have a WHEN/GIVEN step (its trigger) and a THEN step (its outcome). A scenario with only AND lines or plain prose still counts as a scenario, but `openspec validate` flags it as a warning: normal validation still passes, but `openspec validate --strict` fails on it.
- Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.

New capabilities only: the delta spec's first section is `## Purpose` -
one or two sentences (50+ characters, or `openspec validate --strict`
reports it as too brief) describing what the capability is for. Archive
copies it into the main spec it creates; without it the new main spec is
left with a `TBD ... Update Purpose after archive` placeholder to fill in
by hand. Do NOT add `## Purpose` to a delta for an existing capability -
that spec already has one and the delta's is ignored. To change an
existing capability's Purpose - including a leftover `TBD` placeholder -
edit `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
directly. `planningHome.root` comes from the `openspec instructions ...
--json` response. Always use it rather than a repo-relative path: it
resolves to the store whenever the change lives in one - whether that
came from `--store`, a project `store:` pointer, or a global default
store - and to the current repository otherwise. Do not try to work out
which case applies; the field already has.

MODIFIED requirements workflow:
1. Locate the existing requirement in `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (the same store-aware root as above)
2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
4. Ensure header text matches exactly (whitespace-insensitive)

Common pitfall: Using MODIFIED with partial content loses detail at archive time.
If adding new concerns without changing existing behavior, use ADDED instead.

Example (a new capability, so its first section is `## Purpose`):
```
# Spec Delta

## Propósito

Permite a los usuarios extraer sus datos del producto en un formato portátil.

## Requisitos AÑADIDOS

### Requisito: El usuario puede exportar datos
El sistema DEBE permitir a los usuarios exportar sus datos en formato CSV.

#### Escenario: Exportación exitosa
- **CUANDO** el usuario hace clic en el botón "Export"
- **ENTONCES** el sistema descarga un archivo CSV con todos los datos del usuario

## Requisitos ELIMINADOS

### Requisito: Exportación heredada
**Motivo**: Reemplazado por el nuevo sistema de exportación
**Migración**: Utilice el nuevo endpoint de exportación en /api/v2/export
```

Las especificaciones deben poder comprobarse: cada escenario es un posible caso de prueba.

design.md

Explica cómo implementar el cambio. Solo se redacta cuando el cambio lo requiere.

Estructura

La plantilla que recibe el agente como formato de salida (templates/design.md):

# Diseño

## Contexto

<!-- Estado actual y restricciones que dan forma al enfoque. Consulte proposal.md para ver la motivación; no la repita -->

## Objetivos / No objetivos

**Objetivos:**
<!-- Qué pretende lograr este diseño -->

**No objetivos:**
<!-- Qué queda explícitamente fuera del alcance -->

## Decisiones

<!-- Decisiones clave de diseño con su justificación y las alternativas consideradas -->

## Riesgos / Compensaciones

<!-- Riesgos y compensaciones conocidos -->

Instrucciones

La instrucción que se envía al agente cuando redacta este artefacto (desde schema.yaml):

Cree el documento de diseño que explica CÓMO implementar el cambio.

Cuándo incluir design.md (créelo solo si se cumple alguno de estos casos):
- Cambio transversal (varios servicios/módulos) o nuevo patrón arquitectónico
- Nueva dependencia externa o cambios significativos en el modelo de datos
- Complejidad de seguridad, rendimiento o migración
- Ambigüedad que se beneficia de decisiones técnicas antes de codificar

Secciones:
- **Contexto**: Solo el estado actual y las restricciones necesarias para explicar el enfoque. Remítase a la propuesta para la motivación en lugar de repetirla (p. ej., "Consulte proposal.md - Por qué").
- **Objetivos / No objetivos**: Qué logra este diseño y qué excluye explícitamente. No repita el alcance de la propuesta; añada solo los límites a nivel de diseño.
- **Decisiones**: Elecciones técnicas clave con su justificación (¿por qué X en lugar de Y?). Incluya las alternativas consideradas para cada decisión.
- **Riesgos / Compensaciones**: Limitaciones conocidas y cosas que podrían salir mal. Formato: [Riesgo] → Mitigación
- **Plan de migración**: Pasos para desplegar y estrategia de reversión (si corresponde)
- **Preguntas abiertas**: Incógnitas que se pueden responder más adelante de forma segura sin
  cambiar las especificaciones, el enfoque ni el desglose de tareas. Omítalas si no hay ninguna.

Las preguntas abiertas son para incógnitas que realmente puedan aplazarse, no para decisiones que
haya omitido. Si una pregunta cambiara las especificaciones, el enfoque elegido o
el desglose de tareas, resuélvala ahora: pregunte al usuario en lugar de suponer.

Céntrese en la arquitectura y el enfoque, no en la implementación línea por línea.
La propuesta cubre el porqué y el qué; el diseño cubre el cómo. Remítase a la
propuesta para la motivación y, una vez escritas, a las especificaciones para los requisitos;
si una sección solo fuera a repetirlos, remítase a ellos en su lugar.

Los buenos documentos de diseño explican el "porqué" detrás de las decisiones técnicas.

tasks.md

Desglosa la implementación en tareas comprobables. apply realiza el seguimiento del progreso aquí.

Estructura

La plantilla que recibe el agente como formato de salida (templates/tasks.md):

# Tareas

## 1. <!-- Nombre del grupo de tareas -->

- [ ] 1.1 <!-- Descripción de la tarea -->
- [ ] 1.2 <!-- Descripción de la tarea -->

## 2. <!-- Nombre del grupo de tareas -->

- [ ] 2.1 <!-- Descripción de la tarea -->
- [ ] 2.2 <!-- Descripción de la tarea -->

Instrucciones

La instrucción que se envía al agente cuando redacta este artefacto (desde schema.yaml):

Cree la lista de tareas que desglosa el trabajo de implementación.

Antes de escribir las tareas, consulte las Preguntas abiertas en design.md. Si alguna de ellas
cambiara lo que se va a construir, resuélvala primero con el usuario; no
incorpore una suposición no declarada en la lista de tareas.

**IMPORTANTE: Siga la plantilla que aparece a continuación para las tareas con seguimiento.** La fase apply analiza
el formato de las casillas para realizar el seguimiento del progreso. Una casilla que contiene solo `x` cuenta como completada,
en mayúscula o minúscula y con cualquier espaciado, por lo que `- [ x]` también cuenta como completada. Cualquier
otro marcador, incluidos `- [~]`, `- [-]` y una `- []` vacía, se interpreta como
no finalizado. Una línea sin casilla no se rastrea en absoluto.

Directrices:
- Agrupe las tareas con seguimiento relacionadas bajo encabezados numerados con ##
- Cada tarea con seguimiento DEBE ser una casilla: `- [ ] X.Y Descripción de la tarea`
- Las tareas deben ser lo suficientemente pequeñas como para completarse en una sola sesión
- Ordene las tareas por dependencia (¿qué debe hacerse primero?)
- Realice el seguimiento del trabajo de implementación y verificación que pueda completarse antes del
  archivado. Si el flujo de trabajo solicitado incluye el archivado o trabajo que requiera
  que este cambio se archive, conserve esos pasos como viñetas simples en una
  sección opcional `## Seguimiento del flujo de trabajo` al final de tasks.md. Estas
  viñetas son información de referencia ajena al progreso de las tareas con seguimiento.
- Cada tarea DEBE indicar cómo verificar su finalización (una prueba, un comando,
  un comportamiento observable o un artefacto entregado). Incluya la verificación en
  la descripción de la casilla de esa tarea. Use una tarea de verificación independiente solo
  cuando compruebe una integración más amplia o un comportamiento del sistema que abarque
  varias tareas de implementación.
- Cada grupo de tareas DEBE incluir las pruebas y la documentación que su propio trabajo
  requiera. NO acumule las pruebas ni la documentación en un grupo final:
  cuando un grupo tardío ejerce por primera vez el trabajo de uno anterior, los fallos
  se propagan en cascada por todos los grupos intermedios y obligan a rehacer el trabajo. Un grupo
  cuyo trabajo no requiera ninguna de las dos cosas, como el andamiaje o la configuración de dependencias,
  no incluye ninguna. Un grupo final es solo para comprobaciones de integración, no para
  las pruebas y la documentación que debía un grupo anterior.

Ejemplo:
```
# Tareas

## 1. Configuración

- [ ] 1.1 Crear la nueva estructura del módulo y verificar que los archivos esperados estén presentes
- [ ] 1.2 Agregar dependencias a package.json y verificar que la instalación del paquete se realice correctamente

## 2. Implementación principal

- [ ] 2.1 Implementar la función de exportación de datos y verificar que pase la prueba de exportación
- [ ] 2.2 Agregar utilidades de formato CSV y verificar que las pruebas unitarias cubran el entrecomillado y los delimitadores
- [ ] 2.3 Documentar la API de exportación en docs/export.md y verificar que el comando documentado se ejecute tal como está escrito
```

Cuando corresponda, añada el seguimiento del flujo de trabajo como viñetas simples, por ejemplo:
```
## Seguimiento del flujo de trabajo

- Archivar el cambio una vez satisfechos los requisitos de revisión del proyecto.
- Verificar el resultado archivado.
```

Consulte las especificaciones para saber qué debe construirse y el diseño para saber cómo construirlo.

Apply

La transición de la planificación a la implementación. Apply es la fase que recorre tasks.md, no un artefacto.

• Empieza: una vez que tasks.md existe y enumera al menos una tarea.
• Realiza el seguimiento de: las casillas de verificación en tasks.md. Marcarlas es el registro del progreso.
• Termina: cuando todas las casillas están marcadas. OpenSpec entonces sugiere archivar el cambio.

Configuración

La configuración de apply (desde schema.yaml):

apply:
  requires: [tasks]
  tracks: tasks.md
  # instruction: se muestra a continuación

Instrucciones

La instrucción que se envía al agente cuando comienza la implementación (desde schema.yaml):

Lea los archivos de contexto, avance por las tareas pendientes y márquelas como completadas a medida que avanza.
Haga una pausa si encuentra bloqueos o necesita aclaraciones.

schema.yaml

El schema.yaml completo, con los cuerpos de las instrucciones omitidos. Cada uno se muestra en su totalidad en su sección correspondiente más arriba.

name: spec-driven
version: 1
description: Flujo de trabajo predeterminado de OpenSpec: propuesta → especificaciones → diseño → tareas
artifacts:
  - id: proposal
    generates: proposal.md
    description: Documento de propuesta inicial que describe el cambio
    template: proposal.md
    # instruction: se muestra en su totalidad en la sección proposal.md anterior
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    description: Especificaciones detalladas del cambio
    template: spec.md
    # instruction: se muestra en su totalidad en la sección Delta specs anterior
    requires:
      - proposal

  - id: design
    generates: design.md
    description: Documento de diseño técnico con detalles de implementación
    template: design.md
    # instruction: se muestra en su totalidad en la sección design.md anterior
    requires:
      - proposal

  - id: tasks
    generates: tasks.md
    description: Lista de verificación de implementación con tareas con seguimiento
    template: tasks.md
    # instruction: se muestra en su totalidad en la sección tasks.md anterior
    requires:
      - specs
      - design

apply:
  requires: [tasks]
  tracks: tasks.md
  # instruction: se muestra en su totalidad en la sección Apply anterior