Quickstart

Tu primer cambio, de la idea al archivo, en un proyecto nuevo o existente.

Antes de comenzar, necesitas la CLI en tu máquina (Instalación) y OpenSpec inicializado en tu proyecto (Configura tu proyecto).

Comenzar desde un proyecto vacío

Puedes comenzar sin una pila elegida o una arquitectura completa. Inicializa OpenSpec en tu carpeta de proyecto, luego pide a tu agente que explore las opciones contigo. En tu chat de IA:

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

Decide lo que necesita el primer cambio y deja abiertas las decisiones de arquitectura posteriores. Pide a tu agente que proponga ese único cambio, luego sigue los pasos a continuación. Puedes revisitar la arquitectura a medida que el proyecto crece.

El bucle de un vistazo

Cada cambio avanza por los mismos cinco pasos: piensas la idea con tu agente, este redacta un plan, corriges el plan antes de que exista cualquier código, el agente construye a partir de él, y el archivado actualiza tus specs con lo que se implementó.

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

Cada prompt a continuación va en tu chat de IA, el mismo lugar donde pides código. Los ejemplos usan lenguaje sencillo para que funcionen en todas las herramientas. También puedes invocar una skill directamente; la sintaxis varía según la herramienta (herramientas compatibles).

Paso 1: Explorar

Piensa la idea con tu agente antes de pedir un plan. En tu chat de IA:

Help me explore how rate limiting should work in this app.

Explorar es un modo de pensamiento. El agente investiga tu base de código, hace las preguntas que importan, esboza opciones y cuestiona suposiciones. Nunca escribe código. No escribe nada más a menos que le pidas capturar lo que decidieron, o que digas que sí cuando lo ofrece. El resultado es una idea más clara.

Quédate aquí todo lo que el problema necesite. Cuando la forma se sienta correcta, pásala:

Propose the change we just discussed.

Esa línea inicia proponer por ti, llevando todo lo que acordaste. Omite el primer prompt del paso 2.

Paso 2: Proponer

Proponer convierte la idea en un plan revisable. Viniendo de explorar, ya está en marcha. Comenzando en frío, cuando el cambio está claro en tu cabeza, pídelo directamente. En tu chat de IA:

Propose a change to add rate limiting.

El agente pregunta lo que necesita, luego escribe una carpeta de cambio:

openspec/changes/add-rate-limiting/
├── proposal.md    why, and what changes
├── specs/         what "done" means, as testable requirements
├── design.md      technical decisions (only when the change needs one)
└── tasks.md       the implementation checklist

No hay código todavía. Proponer se detiene en el plan.

Paso 3: Revisar y corregir el plan

Corrige el plan mientras sigue siendo palabras y nada está construido todavía. Lee en este orden:

• proposal.md: ¿es este el problema correcto, del tamaño correcto?
• specs/: la lectura de mayor valor. ¿Aceptarías estos requisitos como terminados?
• tasks.md: ¿las tareas cubren los specs, y nada más?

Para corregir algo, cualquiera de las dos opciones funciona:

• Edita el archivo tú mismo. Los artefactos son markdown simple, y los archivos son el plan.
• Dile a tu agente qué está mal ("al spec le falta el caso no autenticado"). Este revisa los artefactos.

Paso 4: Aplicar

Aplicar convierte el plan en código. Inicia una sesión de chat nueva, ya que la implementación va mejor en una ventana de contexto limpia. En tu chat de IA:

Apply the add-rate-limiting change.

El agente lee la carpeta de cambio, luego trabaja a través de tasks.md, marcando cada tarea a medida que se completa.

• ¿Interrumpido, o sin contexto? Abre una sesión nueva y pídele que aplique de nuevo. Reanuda en la primera tarea sin marcar.
• ¿El plan resultó estar mal? Corrige los artefactos (de cualquiera de las dos formas del paso 3), luego continúa aplicando.
• El progreso vive en las casillas de verificación de tasks.md. No hay estado oculto.

Paso 5: Archivar

Archivar hace dos cosas: actualiza tus specs principales con los requisitos del cambio, y mueve la carpeta de cambio a la carpeta de archivo (en /openspec/changes/archive/*).

Cuando cada casilla de tasks.md esté marcada, en tu chat de IA:

Archive the add-rate-limiting change.

Recorre lo que hace el archivado:

## The finished change
> Implementation is done. The delta spec (what this change adds) still sits inside the change folder; specs/ doesn't know about rate limiting yet.
  openspec/
  ├── specs/                                   (no rate-limiting spec yet)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         every box checked
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta: ADDED requirements

## Requirements land in specs/
> Each requirement in the delta lands in the main spec: added ones append, modified ones replace their old version. A new capability gets a new spec file.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gains "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta, source of the merge

## The folder moves to archive/
> The whole change folder, delta included, moves into the archive under a date prefix. Nothing is deleted.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs describe the system as built
> changes/ is clear for the next change. specs/ is the source of truth for what the system does; archive/ is the history of how it got there.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          the spec as built
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git es un asunto separado. Haz commit de la carpeta de cambio junto con el código, y nada más cambia en tu flujo de trabajo.

Conservar o podar los cambios archivados

openspec/changes/archive/ conserva la propuesta, el diseño, las tareas y el delta de cada cambio terminado. En el flujo de archivo anterior, el delta ya actualizó openspec/specs/.

• Conserva toda la carpeta de cambio cuando quieras un registro autónomo en el checkout actual.
• Elimina la carpeta specs/ de un cambio archivado cuando Git es tu historial de specs. Haz commit del archivo primero, luego elimina openspec/changes/archive/<change>/specs/. La propuesta, el diseño y las tareas permanecen en el checkout. openspec validate --archived sigue funcionando porque verifica la finalización de tareas, no los deltas aplicados.
• Elimina toda la carpeta de cambio solo cuando ya no necesites su propuesta, diseño o historial de tareas en el checkout. Los specs actuales no cambian, pero openspec validate --archived y las búsquedas del checkout ya no incluyen ese cambio.

WARNING

Mantén el commit del archivo en el historial de tu repositorio si quieres que Git conserve los archivos eliminados. Hacer squash del commit de archivo y el de limpieza juntos elimina esa instantánea intermedia.

OpenSpec no poda los cambios archivados automáticamente ni proporciona una configuración de retención.

Ir más allá

• Specs delta: cómo escribir los cambios de comportamiento en un spec delta.
• Perfiles: flujos de trabajo opcionales más allá del conjunto principal (verificación antes de archivar, planificación incremental).

Guías avanzadas

Aún no escritas; guías que planeamos agregar:

• Prototipo primero: haz un spike del código antes de cualquier spec, luego completa la propuesta a partir de lo que te enseñó el prototipo.
• Construyendo iterativamente: una secuencia de cambios pequeños en lugar de una propuesta grande.
• Revisar un cambio implementado: el plan necesita moverse de nuevo después de aplicar, pero el cambio aún no se ha fusionado o archivado.