CLI

Los comandos de terminal de openspec.

Comandos

Configuración

Comando	Qué hace
`openspec init`	Inicializa OpenSpec en un proyecto.
`openspec update`	Actualiza los archivos de instrucciones instalados de OpenSpec.
`openspec config`	Ver y modificar la configuración global.

Cambios y especificaciones

Comando	Qué hace
`openspec list`	Lista los cambios, o las especificaciones con `--specs`.
`openspec show`	Imprime un cambio o especificación, como markdown o JSON.
`openspec view`	Panel de un solo vistazo con especificaciones y cambios.
`openspec validate`	Verifica los cambios y especificaciones en busca de problemas estructurales.
`openspec archive`	Mueve un cambio completado al archivo y actualiza las especificaciones principales.

Flujos de trabajo y esquemas

Tu agente ejecuta la mayoría de estos comandos durante el flujo de trabajo.

Comando	Qué hace
`openspec new`	Crea un nuevo directorio de cambio.
`openspec status`	Estado de finalización de artefactos para uno o cada cambio activo.
`openspec instructions`	Instrucciones para crear, aplicar o archivar un artefacto.
`openspec templates`	Rutas de plantilla resueltas para los artefactos de un esquema.
`openspec schemas`	Lista los esquemas de flujo de trabajo disponibles.
`openspec schema`	Inspeccionar, bifurcar o crear un esquema (experimental).

Multirrepositorio (beta)

Comando	Qué hace
`openspec store`	Crear y gestionar stores: repositorios OpenSpec independientes registrados en tu máquina.
`openspec doctor`	Informa sobre el estado de las relaciones para la raíz de OpenSpec resuelta.
`openspec context`	Imprime el contexto de trabajo para la raíz de OpenSpec resuelta.
`openspec workset`	Componer, mantener y abrir vistas de trabajo personales.

Utilidades

Comando	Qué hace
`openspec version`	Informa la versión instalada y opcionalmente verifica si hay una actualización.
`openspec install`	Instala la versión independiente de `openspec`, que funciona sin Node.js.
`openspec feedback`	Enviar comentarios sobre OpenSpec.
`openspec completion`	Instalar o generar autocompletado de shell.

Obsoletos

Comando	Qué hace
`openspec change`	Forma sustantiva de show, list y validate para cambios. La CLI muestra una advertencia y redirige a los comandos con el verbo primero.
`openspec spec`	Forma sustantiva de show, list y validate para especificaciones, con la misma advertencia.

Cada comando acepta -h, --help. El comando openspec sin argumentos también acepta:

-V, --version: imprime la versión de la CLI.
--no-color: desactiva la salida con colores.

openspec init

Inicializa OpenSpec en un proyecto.

bash

openspec init                        # directorio actual, selector de herramientas interactivo
openspec init --tools claude,cursor  # configura herramientas específicas, sin preguntas
openspec init --tools none           # solo la estructura openspec/, sin archivos de herramientas

Sin --tools, init te pide seleccionar herramientas en una terminal interactiva. Fuera de una, configura las herramientas que detecta en el proyecto. Si no detecta ninguna, termina con el código 1 y enumera los ids válidos.

Repositorios de solo almacén

Cuando openspec/config.yaml contiene una línea store: y el repositorio no tiene specs ni cambios locales, ejecuta init desde la raíz del repositorio:

bash

# instala los archivos de integración de Claude Code en el repositorio de código
openspec init --tools claude

Archivos de integración: se escriben en el repositorio de código.
openspec/config.yaml: se conserva byte a byte.
openspec/specs/ y openspec/changes/: no se crean en el repositorio de código.

Ejecutar init desde un subdirectorio termina con el código 1 e indica que lo ejecutes desde la raíz del repositorio. --language también termina con el código 1 porque el idioma pertenece a la configuración del almacén externo. Ejecuta init en la raíz del almacén o edita esa configuración directamente.

Argumentos

Argumento	Qué es
`path`	El directorio del proyecto que se inicializará. Por defecto: el directorio actual. Se crea si no existe.

Opciones

Flag	Efecto
`--tools <tools>`	Ids de herramientas separados por comas, `all` o `none`. Omite el selector. Los ids se enumeran en Herramientas compatibles.
`--language <language>`	Añade una instrucción de idioma a una configuración de proyecto nueva. Se rechaza cuando la línea `store:` del repositorio apunta a un almacén externo.
`--force`	Elimina archivos de estructuras de OpenSpec anteriores sin preguntar. De lo contrario, las ejecuciones interactivas confirman primero la limpieza.
`--profile <profile>`	Sustituye el perfil de la configuración global para esta ejecución: `core` (el conjunto de flujos de trabajo estándar) o `custom` (los flujos de trabajo guardados en la configuración global).
`--no-animation`	Muestra una pantalla de bienvenida estática en lugar de la animada.

Salida

Cada herramienta seleccionada recibe las skills y los comandos de OpenSpec en su propio directorio:

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Restart your IDE for the new commands to take effect.

--tools none crea únicamente openspec/config.yaml. En un proyecto ya inicializado, init reescribe los archivos instalados in situ y el resumen muestra Refreshed: Claude Code con Config: openspec/config.yaml (exists).

Códigos de salida

0: la configuración se completó.
1: un valor de --tools o --profile no válido, una ejecución no interactiva sin herramientas detectadas y sin --tools, o una invocación de solo almacén no válida.

openspec update

Actualiza los archivos de instrucciones instalados de OpenSpec.

bash

openspec update             # actualiza las herramientas cuyos archivos son más antiguos que la CLI
openspec update --force     # reescribe los archivos aunque estén actualizados
openspec update --dry-run   # lista lo que cambiaría una actualización, sin cambiar nada

update busca las herramientas que init configuró y compara sus archivos generados con la versión de la CLI. Cuando existe una versión más reciente de OpenSpec, primero ofrece actualizar la CLI y luego vuelve a ejecutarse con la versión actualizada. Establece OPENSPEC_NO_UPDATE_CHECK=1 para omitir la comprobación.

Argumentos

Argumento	Qué es
`path`	El directorio del proyecto que se actualizará. Por defecto: el directorio actual.

Opciones

Flag	Efecto
`--force`	Reescribe los archivos de todas las herramientas configuradas incluso cuando están actualizados.
`--dry-run`	Informa de cada archivo que la actualización añadiría, cambiaría o eliminaría, sin escribir nada. Sin comprobación de actualización de la CLI, sin preguntas. Combínalo con `--force` para previsualizar una actualización forzada.
`--json`	Con `--dry-run`, imprime el plan como JSON. Sin `--dry-run` termina con el código 1.

Vista previa de una actualización

--dry-run planifica la actualización que haría una ejecución no interactiva: la misma ruta de código, con cada escritura y cada borrado registrados en lugar de realizados. Se listan todos los archivos que la actualización real afectaría, incluidos:

mover los archivos de OpenSpec fuera del directorio anterior de una herramienta (.kimi/ a .kimi-code/, .windsurf/ a .devin/, .codex/ y .agent/ a .agents/);
guardar la configuración global cuando una instalación anterior a los perfiles obtiene uno;
sincronizar los archivos del agente en la nube de GitHub Copilot;
con --force, configurar herramientas que solo se encuentran en artefactos heredados y limpiar dichos artefactos, incluidos los prompts globales de Codex retirados.

bash

openspec update --dry-run

2 file(s) would change:
  update  .claude/skills/openspec-propose/SKILL.md  (claude)
  add     ~/.config/openspec/config.json  (openspec)

--dry-run --json imprime el mismo plan como un único documento JSON:

json

{
  "changes": [
    { "path": ".claude/skills/openspec-propose/SKILL.md", "action": "update", "tool": "claude" },
    { "path": "~/.config/openspec/config.json", "action": "add", "tool": "openspec" }
  ],
  "notes": [],
  "failures": []
}

Campo	Qué contiene
`changes[].path`	Ruta relativa al proyecto. Un archivo fuera del proyecto, como una skill global o la configuración global, se muestra respecto a tu directorio personal como `~/...`, o como una ruta absoluta cuando también está fuera del directorio personal.
`changes[].action`	`add`, `update` o `delete`. Un archivo cuyos bytes nuevos coinciden con los antiguos no se lista.
`changes[].tool`	La herramienta configurada a la que pertenece el archivo, como `claude`. Los archivos que pertenecen al propio OpenSpec en lugar de a una herramienta (la configuración global y la limpieza de artefactos heredados) son `openspec`.
`notes[]`	`{ code, message }` para un paso sobre el que se preguntaría a un usuario en terminal. `legacy-tool-directories`: un movimiento que una ejecución interactiva pregunta antes de hacer; `changes` lo lista como realizado. `legacy-artifacts`: se encontraron archivos de la estructura anterior de OpenSpec, como comandos slash `openspec-proposal.md` o bloques de marcador de OpenSpec en `AGENTS.md`. Sin `--force`, una actualización no interactiva los deja intactos, y `changes` también; `--dry-run --force` lista su limpieza. Vacío para una actualización ordinaria.
`failures[]`	`{ tool, error }` para cada herramienta en la que la actualización real fallaría, incluida una escritura que no puede realizar: un directorio en el lugar de un archivo, un archivo en el lugar de un directorio, o un archivo o carpeta sin permiso de escritura. Para esa herramienta, `changes` se detiene donde se detiene la actualización real; las demás herramientas siguen planificadas. Los fallos que el disco solo informa al escribir, como quedarse sin espacio, no se pueden prever.

Un fallo antes de la planificación, como que no exista el directorio de OpenSpec, sigue imprimiendo exactamente un documento JSON: el plan vacío más un array status con severity, code (update_error) y message. El código de salida es 1.

Salida

Cuando los archivos de todas las herramientas coinciden con la versión de la CLI:

✓ All 1 tool(s) up to date (v1.7.0)
  Tools: claude

Use --force to refresh files anyway.

Cuando los archivos de una herramienta provienen de una CLI más antigua (o con --force, que imprime Force updating 1 tool(s): claude en su lugar):

Updating 1 tool(s): claude (1.6.0 → 1.7.0)

✔ Updated Claude Code

✓ Updated: Claude Code (v1.7.0)
Tools: Claude Code

Restart your IDE for changes to take effect.

En un directorio sin OpenSpec, update se niega:

✖ Error: No OpenSpec directory found. Run 'openspec init' first.

Códigos de salida

0: archivos actualizados, o todo ya estaba actualizado.
1: no hay un directorio de OpenSpec en la ruta, o la actualización falló.

openspec config

Muestra y modifica la configuración global.

bash

openspec config list                  # ver los ajustes actuales
openspec config set delivery skills   # cambiar un valor
openspec config profile               # selector de flujos de trabajo interactivo

Subcomando	Qué hace
`path`	Imprime la ubicación del archivo de configuración.
`list`	Muestra todos los ajustes actuales.
`get <key>`	Imprime un valor, en bruto y apto para scripts.
`set <key> <value>`	Establece un valor, aplicando coerción de tipos.
`unset <key>`	Elimina una clave para que se aplique su valor por defecto.
`reset`	Restablece toda la configuración a los valores por defecto.
`edit`	Abre el archivo de configuración en `$EDITOR`.
`profile [preset]`	Configura el modo de entrega y los flujos de trabajo.

La configuración es global a tu máquina y se almacena como JSON donde apunta config path: $XDG_CONFIG_HOME/openspec/config.json si está definida; en caso contrario, ~/.config/openspec/config.json (macOS, Linux) o %APPDATA%\openspec\config.json (Windows). Cada subcomando acepta --scope <scope>, pero hoy en día solo funciona global. Cualquier otro ámbito termina con el código 1 y muestra Error: Project-local config is not yet implemented.

openspec config path

bash

openspec config path

/Users/you/.config/openspec/config.json

openspec config list

bash

openspec config list          # ajustes legibles más resumen del perfil
openspec config list --json   # configuración en bruto como JSON

Opciones

Flag	Efecto
`--json`	Imprime el objeto de configuración como JSON.

Salida

Cada ajuste y, a continuación, un resumen del perfil que marca los valores como explícitos o por defecto:

featureFlags: {}
profile: core
delivery: both

Profile settings:
  profile: core (default)
  delivery: both (default)
  workflows: propose, explore, apply, update, sync, archive (from core profile)

openspec config get

bash

openspec config get delivery

Argumentos

Argumento	Qué es
`key`	La clave a leer. Los puntos acceden a valores anidados (`featureFlags.workspaces`).

Salida

El valor puro, listo para scripts. Los objetos se imprimen como JSON compacto:

both

Códigos de salida

0: valor impreso.
1: la clave no tiene valor y no se imprime nada.

openspec config set

bash

openspec config set delivery skills
openspec config set featureFlags.workspaces true

Argumentos

Argumento	Qué es
`key`	La clave a escribir, con puntos para los valores anidados.
`value`	El nuevo valor. `true`/`false` se convierten en booleanos, las cadenas numéricas se convierten en números.

Opciones

Flag	Efecto
`--string`	Almacena el valor como cadena, omitiendo la coerción de tipos.
`--allow-unknown`	Permite claves que el esquema no conoce.

Salida

Set featureFlags.workspaces = true

Las claves desconocidas y los valores no válidos fallan con el código de salida 1 antes de que se guarde nada:

Error: Invalid configuration key "bogus.key". Unknown top-level key "bogus".
Use "openspec config list" to see available keys.
Pass --allow-unknown to bypass this check.

Error: Invalid configuration - delivery: Invalid option: expected one of "both"|"skills"|"commands"

Si el archivo de configuración existe pero no contiene un objeto JSON, ya sea porque no es JSON válido en absoluto o porque su raíz es otra cosa como null o un array, config set, config unset y config profile terminan con el código 1 y dejan el archivo sin cambios. Arréglalo con openspec config edit, o reemplázalo con openspec config reset --all:

Error: /home/you/.config/openspec/config.json could not be parsed, so it was left unchanged.
Fix it with "openspec config edit", or reset it with "openspec config reset --all".

Hasta que se arregle, la telemetría y la comprobación de actualizaciones permanecen desactivadas.

openspec config unset

bash

openspec config unset delivery

Elimina la clave para que vuelva a aplicarse el valor por defecto. Las claves con valores por defecto integrados siempre cuentan como establecidas, por lo que esto informa de éxito aunque nunca las hayas establecido:

Unset delivery (reverted to default)

Una clave sin ningún valor imprime Key "featureFlags.nothere" was not set. Ambos casos terminan con el código 0. Un archivo de configuración que no puede analizarse termina con el código 1 en su lugar, igual que en config set.

openspec config reset

bash

openspec config reset --all      # pide confirmación
openspec config reset --all -y   # sin pregunta

Opciones

Flag	Efecto
`--all`	Obligatorio. Restablece todo.
`-y, --yes`	Omite la pregunta de confirmación.

Salida

Configuration reset to defaults

Sin --all termina con el código 1 e imprime la línea de uso.

Códigos de salida

0: restablecimiento completado, o respondiste que no en la pregunta.
1: falta --all.
130: pregunta cancelada con Ctrl-C.

openspec config edit

bash

openspec config edit

Abre el archivo de configuración en $EDITOR (con $VISUAL como alternativa), creándolo primero con los valores por defecto si no existe. Cuando se cierra el editor, el archivo se valida. Un JSON no válido o una configuración no válida termina con el código 1.

El valor del editor puede incluir argumentos y rutas entre comillas, por ejemplo code --wait o "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Se divide en palabras sin usar un shell, de modo que $VAR, ~ y ; se pasan literalmente. Un editor que no puede iniciarse, o que termina con un código distinto de cero, imprime un error de una línea y termina con el código 1.

Sin editor configurado termina con el código 1:

Error: No editor configured
Set the EDITOR or VISUAL environment variable to your preferred editor
Example: export EDITOR=vim

openspec config profile

bash

openspec config profile        # selector interactivo (necesita una terminal)
openspec config profile core   # aplica el preset core directamente

Argumentos

Argumento	Qué es
`preset`	Nombre de preset opcional. Solo existe `core`. Selecciona los flujos de trabajo core y conserva tu ajuste de entrega.

Sin preset, un selector interactivo muestra tu modo de entrega y flujos de trabajo actuales, permite cambiar uno, otro o ambos (entrega: ambos, solo skills o solo comandos; flujos de trabajo: una lista de casillas), imprime el diff y, dentro de un proyecto OpenSpec, ofrece ejecutar openspec update por ti. Fuera de una terminal termina con el código 1:

Interactive mode required. Use `openspec config profile core` or set config via environment/flags.

Salida

La configuración cambiada no llega a los proyectos hasta que estos se actualicen:

Config updated. Run `openspec update` in your projects to apply.

Códigos de salida

0: perfil guardado, o mantuviste los ajustes actuales.
1: preset desconocido, sin terminal, o el openspec update ofrecido falló.
130: selector cancelado con Ctrl-C.

openspec list

Lista cambios, o especificaciones con --specs.

bash

openspec list                    # cambios activos, los modificados más recientemente primero
openspec list --archived         # cambios archivados
openspec list --all              # cambios activos y archivados
openspec list --specs            # especificaciones con recuentos de requisitos
openspec list --json             # legible por máquina, incluye la raíz resuelta

Las filas provienen de openspec/changes/ y openspec/specs/ bajo la raíz resuelta. El listado de cambios predeterminado omite openspec/changes/archive/.

Opciones

Opción	Efecto
`--specs`	Lista especificaciones en lugar de cambios.
`--changes`	Lista cambios. Esta es la opción predeterminada.
`--archived`	Lista solo cambios archivados. No se puede combinar con `--specs`.
`--all`	Lista cambios activos y archivados. No se puede combinar con `--specs`. Tiene prioridad sobre `--archived`.
`--sort <order>`	`recent` (los modificados más recientemente primero) o `name`. Predeterminado: `recent`. Las especificaciones siempre se ordenan por nombre.
`--json`	Imprime JSON en lugar de la tabla.
`--store <id>`	Usa un almacén registrado como raíz de OpenSpec en lugar del proyecto actual.

Salida

Una fila por cambio: nombre, estado de las tareas y última modificación. La columna de estado muestra No tasks, 2/5 tasks o ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all agrupa los cambios activos y archivados bajo encabezados separados. Cada grupo usa el orden de clasificación seleccionado:

Changes:
  add-rate-limit     No tasks      just now

Archived Changes:
  2026-08-10-add-login     ✓ Complete    2d ago

Specs:
  api     requirements 1

--json añade recuentos de tareas y un status de no-tasks, in-progress o complete:

json

{
  "changes": [
    {
      "name": "add-rate-limit",
      "completedTasks": 0,
      "totalTasks": 0,
      "lastModified": "2026-08-11T13:44:40.171Z",
      "status": "no-tasks"
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Con --archived o --all, cada objeto de cambio incluye un booleano archived. El array combinado usa el orden de clasificación seleccionado. Un cambio archivado todavía puede tener un estado in-progress cuando su archivo de tareas asociado tiene tareas sin marcar. Sin ninguna de las dos opciones, la forma del JSON permanece sin cambios.

Un listado vacío imprime No active changes found., No archived changes found., No changes found. o No specs found. y aun así termina con código 0.

Un cambio es un directorio directamente bajo openspec/changes/. A diferencia de las especificaciones, los cambios no pueden anidarse en una carpeta de espacio de nombres. Una carpeta como changes/mobile/ que solo envuelve un cambio (changes/mobile/refresh-token/) se lista con el estado not a change, seguida de una advertencia que nombra los directorios anidados. --json marca esa entrada con un array nested y añade un array warnings de nivel superior. show, status, validate y archive rechazan la carpeta con el mismo mensaje. Para solucionarlo, mueve el cambio un nivel hacia arriba e incorpora el espacio de nombres en su nombre:

bash

mv openspec/changes/mobile/refresh-token openspec/changes/mobile-refresh-token
rmdir openspec/changes/mobile

Códigos de salida

0: se imprime el listado, incluso cuando está vacío.
1: no se encontró ninguna raíz de OpenSpec (fuera de un proyecto, sin --store).

openspec show

Imprime un cambio o una especificación, como Markdown o JSON.

bash

openspec show add-rate-limit              # cambio: imprime proposal.md
openspec show add-rate-limit --diff       # cambio: añade los diffs de requisitos
openspec show api                         # especificación: imprime spec.md
openspec show api --json --no-scenarios   # JSON de especificación sin el texto de los escenarios

Sin un nombre, show pregunta si es un cambio o una especificación y luego lista elementos para elegir. Fuera de una terminal interactiva, termina con código 1 e imprime las formas directas en su lugar.

Argumentos

Argumento	Qué es
`item-name`	El cambio o la especificación que se va a mostrar, por nombre de carpeta (`add-rate-limit`, `api`).

Opciones

Opción	Efecto
`--json`	Imprime JSON estructurado en lugar de Markdown sin procesar.
`--type <change\|spec>`	Elige el tipo cuando un cambio y una especificación comparten un nombre.
`--no-interactive`	Nunca pregunta: si falta un nombre, se convierte en un error.
`--deltas-only`	JSON, cambio: restringe la salida a los deltas. El JSON de cambio ya contiene solo deltas, así que la salida coincide con la de `--json` sin más.
`--requirements-only`	Alias obsoleto de `--deltas-only`. Muestra una advertencia en stderr.
`--diff`	Cambio: añade los diffs delta de cada requisito. Se ignora con una advertencia para las especificaciones.
`--requirements`	JSON, especificación: conserva el texto de los requisitos y vacía los arrays `scenarios`.
`--no-scenarios`	JSON, especificación: la misma salida que `--requirements`.
`-r, --requirement <id>`	JSON, especificación: muestra un solo requisito por su posición (empezando en 1). No se puede combinar con `--requirements`.
`--store <id>`	Usa un almacén registrado como raíz de OpenSpec en lugar del proyecto actual.

Las opciones que no se aplican al tipo resuelto se ignoran con una advertencia en stderr.

Salida

El modo de texto es una salida directa sin procesar: un cambio imprime su proposal.md; una especificación imprime su spec.md.

# Add rate limiting

Por qué

Los clientes no autenticados pueden agotar la API.

Qué cambia

Añadir límite de tasa por cliente a la API pública.

Para un cambio, `--diff` imprime primero la propuesta, luego una sección `Specifications Changed (diffs)`. Los requisitos ADDED incluyen su texto completo. Los requisitos REMOVED conservan la Razón y Migración originales. Los requisitos RENAMED muestran FROM y TO. Los requisitos MODIFIED muestran un diff unificado contra el requisito principal coincidente.

Si un encabezado MODIFIED coincide solo después de plegar mayúsculas o espacios en blanco, la salida incluye tanto el diff como una advertencia de que la coincidencia del archivo es exacta. Si falta el spec o requisito principal, la salida advierte e imprime el bloque delta completo. Un bloque MODIFIED sin diferencias textuales imprime (no textual changes).

Un cambio con --json tiene forma de delta:

json

{
  "id": "add-rate-limit",
  "title": "Add rate limiting",
  "deltaCount": 1,
  "deltas": [
    {
      "spec": "api",
      "operation": "ADDED",
      "description": "Add requirement: The API SHALL limit each client to 100 requests per minute.",
      "requirement": {
        "name": "Rate limit",
        "text": "The API SHALL limit each client to 100 requests per minute.",
        "scenarios": [
          {
            "name": "Client exceeds the limit",
            "rawText": "- **WHEN** a client sends its 101st request within a minute\n- **THEN** the API responds 429"
          }
        ]
      },
      ...
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Cada requisito lleva su name, el texto del encabezado después de Requirement:. Este es el nombre con el que el archivo compara las entradas MODIFIED, REMOVED y RENAMED. Cada escenario lleva su name, el texto del encabezado después de Scenario:. Una secuencia de # de cierre en cualquiera de los encabezados no forma parte del nombre.

--json --diff mantiene esta forma de nivel superior. Un delta MODIFIED gana una cadena diff, una cadena warning, o ambas. Las demás operaciones no cambian. Una cadena diff vacía significa que los bloques principal y delta son textualmente idénticos.

Un spec con --json lista sus requisitos con escenarios. Los requisitos y escenarios llevan los mismos campos name que el JSON de cambio:

json

{
  "id": "api",
  "title": "api",
  "overview": "Public HTTP API behavior.",
  "requirementCount": 1,
  "requirements": [
    {
      "name": "Health endpoint",
      "text": "The API SHALL expose a health endpoint.",
      "scenarios": [
        {
          "name": "Health check succeeds",
          "rawText": "- **WHEN** a client requests GET /health\n- **THEN** the API responds 200"
        }
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "format": "openspec"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Un nombre desconocido sugiere coincidencias cercanas: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Un nombre que coincide tanto con un cambio como con un spec produce un error y pide --type.

Códigos de salida

0: elemento impreso.
1: nombre desconocido o ambiguo, sin nombre fuera de una terminal, un índice -r fuera de rango, --requirements combinado con -r, o un delta o spec principal que no se puede leer para --diff.

openspec view

Imprime un panel de una pantalla con specs y cambios.

bash

openspec view   # project summary in one screen

view imprime el panel una vez y sale. No lee pulsaciones de teclado. Los cambios se agrupan por progreso de tareas: Draft (sin tareas aún), Active (tareas en curso, con barra de progreso y porcentaje), Completed (todas las tareas marcadas). Los specs se listan con conteos de requisitos, primero los más grandes.

Opciones

Bandera	Efecto
`--store <id>`	Usar un almacén registrado como raíz de OpenSpec en lugar del proyecto actual.

Salida

OpenSpec Dashboard

════════════════════════════════════════════════════════════
Summary:
  ● Specifications: 1 specs, 1 requirements
  ● Draft Changes: 1
  ● Active Changes: 0 in progress
  ● Completed Changes: 0

Draft Changes
────────────────────────────────────────────────────────────
  ○ add-rate-limit

Specifications
────────────────────────────────────────────────────────────
  ▪ api                            1 requirement

════════════════════════════════════════════════════════════

Use openspec list --changes or openspec list --specs for detailed views

Una línea de resumen Task Progress aparece cuando algún cambio tiene tareas en curso.

Cada cambio activo también muestra sus estados de esquema y artefactos debajo de su barra de progreso de tareas:

text

    └─ [spec-driven] proposal✓ specs→ design→ tasks✓

Marcador	Estado del artefacto
`✓`	Su salida existe. Un artefacto de tareas existente está hecho incluso si su lista de verificación no está terminada.
`→`	Está listo para crearse.
Sin marcador	Está bloqueado por una dependencia faltante.
`(skipped)`	El cambio lo omite.

Si no se puede cargar un flujo de trabajo, view imprime una advertencia y mantiene visible el progreso de tareas de ese cambio. Ejecuta openspec status --change <name> para inspeccionar el flujo de trabajo por separado. Después de openspec view --store <id>, pasa el mismo --store <id> a status.

Códigos de salida

0: panel impreso.
1: no se encontró raíz de OpenSpec (fuera de un proyecto, sin --store).

openspec validate

Comprueba cambios y specs en busca de problemas estructurales.

bash

openspec validate add-rate-limit   # one change or spec, by name
openspec validate --all            # every change and spec

Sin nombre y sin bandera masiva, validate te pide que elijas elementos. Fuera de una terminal interactiva, sale con 1 e imprime las banderas masivas en su lugar.

Argumentos

Argumento	Qué es
`item-name`	El cambio o spec a validar, por nombre de carpeta (`add-rate-limit`, `api`).

Opciones

Bandera	Efecto
`--all`	Validar todos los cambios y specs.
`--changes`	Validar todos los cambios.
`--specs`	Validar todos los specs.
`--archived`	Comprobar la finalización de tareas en cambios archivados, sin validar sus deltas de spec aplicados.
`--strict`	Tratar las advertencias como fallos.
`--type <change\|spec>`	Elegir el tipo cuando un cambio y un spec comparten nombre.
`--json`	Imprimir un informe estructurado en lugar de texto.
`--report <mode>`	Salida masiva: `full` (predeterminado) o `findings`. Requiere un ámbito masivo explícito.
`--concurrency <n>`	Máximo de validaciones paralelas en ejecuciones masivas. Predeterminado: `OPENSPEC_CONCURRENCY`, si no, 6.
`--no-interactive`	Nunca preguntar: un nombre faltante o ambiguo se convierte en error.
`--store <id>`	Usar un almacén registrado como raíz de OpenSpec en lugar del proyecto actual.

Salida

Las ejecuciones masivas imprimen una línea de estado por elemento, seguida de cualquier hallazgo, y terminan con totales:

✓ change/add-rate-limit
✓ spec/api
Totals: 2 passed, 0 failed (2 items)

Hallazgos de casillas de tareas

El progreso cuenta casillas y nada más, por lo que un archivo de tareas escrito como viñetas simples se lee como cero tareas: openspec list y openspec status no reportan trabajo, y openspec archive no tiene nada que marcar como incompleto. Validate reporta un WARNING en cada archivo de tareas rastreado que liste trabajo sin casilla:

text

⚠ [WARNING] tasks.md: This change counts as 0 tasks: no line in its tracked task files is a checkbox, so "openspec list" and "openspec status" report no work and "openspec archive" has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".

La advertencia se dispara solo cuando todo el conjunto rastreado del cambio no contiene ninguna casilla. Un archivo de prosa junto a una lista de verificación real no se reporta, y un cambio en plena redacción mantiene su progreso en el momento en que existe una sola casilla. --strict convierte la advertencia en un fallo. El número de línea está en el informe --json.

Los bloques cercados, los comentarios HTML, el front matter YAML y el código indentado no se escanean, por lo que una muestra de terminal pegada nunca se confunde con una lista de tareas.

Hallazgos de fusión de archivo

Para cambios, validate ejecuta el constructor de fusión del archivo contra los specs principales actuales sin escribir archivos. Reporta conflictos de fusión, como un objetivo MODIFIED faltante o un requisito ADDED conflictivo, como INFO:

text

ℹ [INFO] api/spec.md: Archive would refuse this delta: api MODIFIED failed for header "### Requirement: Rate limiting" - not found

Estos hallazgos aparecen incluso cuando la validación pasa, tanto en salida de texto como JSON. INFO nunca cambia el código de salida, incluso bajo --strict: un objetivo faltante puede pertenecer a un cambio hermano que aún no se ha archivado. Los deltas ya sincronizados en los specs principales siguen las reglas de fusión existentes del archivo.

Esta comprobación no ejecuta la validación posterior de specs fusionados del archivo ni las comprobaciones de retiro. Un informe limpio no garantiza que el archivo tenga éxito.

Si el preflight de fusión no puede iniciarse, un hallazgo INFO explica por qué. Los hallazgos de validación existentes y el código de salida permanecen sin cambios.

Un elemento que falla lista cada problema y la solución:

Change 'add-rate-limit' has issues
✗ [ERROR] api/spec.md: ADDED "Rate limiting" must include at least one scenario
Next steps:
  - Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements
  - Each requirement MUST include at least one #### Scenario: block
  - Debug parsed deltas: openspec show add-rate-limit --json --deltas-only

--json imprime un informe para la ejecución:

json

{
  "items": [
    {
      "id": "add-rate-limit",
      "type": "change",
      "valid": true,
      "issues": [],
      "durationMs": 2
    }
  ],
  "summary": {
    "totals": {
      "items": 1,
      "passed": 1,
      "failed": 0
    },
    "byType": {
      "change": {
        "items": 1,
        "passed": 1,
        "failed": 0
      }
    }
  },
  "version": "1.0",
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Las entradas issues llevan un level de ERROR, WARNING o INFO.

Códigos de salida

0: todos los elementos validados pasaron, incluido un ámbito masivo vacío.
1: un elemento falló, la solicitud de informe no es válida, openspec/config.yaml no se puede leer o no es YAML válido, o la ejecución falló (por ejemplo, un nombre desconocido o sin raíz de OpenSpec). Una configuración que no se puede leer o analizar detiene la ejecución antes de que se compruebe cualquier elemento; con --json se reporta como una sola entrada status con el código unreadable_config o unparseable_config.

--report full|findings

Selecciona la salida para un ámbito de validación masiva explícito:

full: todos los elementos. Este es el predeterminado. --report full explícito mantiene la forma de salida existente sin añadir metadatos de informe.
findings: solo elementos con problemas, incluidos los que pasan con advertencias o información. Todos los elementos se siguen validando. Los totales, el comportamiento de modo estricto y los códigos de salida no cambian.

bash

openspec validate --all --report findings
openspec validate --archived --report findings --json

Ámbitos

Banderas	`report.scope` de Findings
`--all`	`all`
`--changes`	`changes`
`--specs`	`specs`
`--changes --specs`, o `--all` con cualquiera de las banderas	`all`
`--archived`	`archived`

Ambos modos de informe explícitos rechazan un nombre de elemento posicional, un ámbito masivo faltante o ámbitos de archivo y activos combinados.

Salida de texto de Findings

Salida humana: stdout imprime Scope: <scope> (<count> items), luego totales. Sin elementos con problemas:

text

Scope: all (2 items)
No item findings.
Totals: 2 passed, 0 failed (2 items)

Las etiquetas de elementos con problemas, etiquetas de severidad, rutas y mensajes se imprimen en stderr. Los fallos de ámbito activo mantienen la pista de reintento Details: después de los totales. El banner de raíz existente y la salida de progreso pueden preceder al informe.

Salida JSON de Findings

--report findings --json imprime un documento. Este ejemplo tiene dos elementos limpios:

json

{
  "report": {
    "kind": "validation-findings",
    "version": "1.0",
    "scope": "all",
    "returnedItems": 0,
    "totalItems": 2
  },
  "itemFindings": [],
  "summary": {
    "totals": { "items": 2, "passed": 2, "failed": 0 },
    "byType": {
      "change": { "items": 1, "passed": 1, "failed": 0 },
      "spec": { "items": 1, "passed": 1, "failed": 0 }
    }
  },
  "root": { "path": "/Users/you/projects/my-app", "source": "nearest" }
}

report.kind y report.version: identifican la forma validation-findings, versión 1.0. No hay version ni items de nivel superior.
report.returnedItems y report.totalItems: cuentan los registros devueltos y todos los elementos validados, respectivamente.
itemFindings: registros de elementos completos cuyo array issues no está vacío. Incluye problemas ERROR, WARNING e INFO. Cada registro conserva id, type, valid, issues y durationMs. Los elementos archivados usan type: "change".
summary: totales de toda la ejecución y conteos por tipo, no conteos del subconjunto devuelto. Un ámbito vacío tiene totales cero y sale con 0.
root: los mismos metadatos de raíz seleccionada que el informe completo.

Preservación de registros: los elementos devueltos mantienen su orden del informe completo y cualquier campo aditivo en elementos o problemas. El filtrado no reescribe mensajes ni ubicaciones, incluidos los campos opcionales line y column.

Fallos de comando: los fallos de selección de raíz o descubrimiento de elementos conservan el diagnóstico status existente y salen con 1. No devuelven un informe de hallazgos completado ni un informe vacío exitoso.

Solicitudes de informe no válidas

Ambos modos de informe explícitos rechazan estas solicitudes antes de la selección de raíz o el descubrimiento de elementos:

Un valor de informe no compatible, incluida una cadena vacía.
Un nombre de elemento posicional, incluso con una bandera masiva.
Sin ámbito masivo explícito.
--archived combinado con --all, --changes o --specs.

En modo JSON, una solicitud rechazada sale con 1 y solo un array status de un elemento. No tiene root ni payload de informe:

bash

openspec validate --all --report bogus --json

json

{
  "status": [
    {
      "severity": "error",
      "code": "invalid_validation_report_request",
      "message": "Unknown validation report 'bogus'.",
      "fix": "Use --report full|findings with --all, --changes, --specs, or --archived, without an item name. Do not combine archived and active scopes."
    }
  ]
}

El modo humano imprime el error en stderr. Un --report desnudo sin valor es un error de sintaxis de Commander en stderr, incluso con --json; no usa este sobre de diagnóstico.

Filtrar un informe completo externamente

Para una vista JSON personalizada, filtra el informe completo con jq o PowerShell. Estos ejemplos de script preservan el código de salida de validación y dejan intactos los documentos de error de comando.

En Bash con jq:

bash

if validation_json=$(openspec validate --all --json); then
  validation_exit=0
else
  validation_exit=$?
fi
printf '%s\n' "$validation_json" |
  jq 'if has("items") then .items |= map(select(.issues | length > 0)) else . end'
exit "$validation_exit"

En PowerShell:

powershell

$validationJson = openspec validate --all --json
$validationExit = $LASTEXITCODE
$validationReport = $validationJson | ConvertFrom-Json
if ($validationReport.PSObject.Properties.Name -contains 'items') {
  $validationReport.items = @($validationReport.items | Where-Object { $_.issues.Count -gt 0 })
}
$validationReport | ConvertTo-Json -Depth 100
exit $validationExit

Estas vistas personalizadas mantienen las claves del informe completo pero omiten los elementos limpios. No son ni informes completos full-v1 ni la forma versionada --report findings.

openspec archive

Mueve un cambio completado al archivo y actualiza las especificaciones principales.

bash

openspec archive add-rate-limit -y                # archiva un cambio, fusiona sus deltas
openspec archive add-rate-limit -y --skip-specs   # archiva sin tocar las especificaciones

Sin un nombre, archive te solicita que elijas un cambio. Fuera de una terminal interactiva, termina con el código 1 e imprime en su lugar el comando para volver a ejecutarlo.

Argumentos

Argumento	Qué es
`change-name`	El cambio que se va a archivar, por nombre de carpeta (`add-rate-limit`).

Opciones

Opción	Efecto
`-y, --yes`	Responde afirmativamente a todas las confirmaciones: actualizaciones de especificaciones, tareas incompletas y validación omitida.
`--skip-specs`	Archiva sin tocar las especificaciones principales (infraestructura, herramientas o cambios solo de documentación).
`--no-validate`	Omite la validación. Archive te pide que confirmes primero, y `-y` responde afirmativamente.
`--json`	Imprime un resultado estructurado en lugar de texto. Requiere `--yes` para confirmar las actualizaciones de especificaciones.
`--store <id>`	Usa un almacén registrado como raíz de OpenSpec en lugar del proyecto actual.

Salida

Una ejecución correcta informa el estado de las tareas, muestra una vista previa de las actualizaciones de las especificaciones, las aplica e indica el nombre de la carpeta de archivado:

Task status: ✓ Complete

Specs to update:
  api: update
Applying changes to openspec/specs/api/spec.md:
  + 1 added
Totals: + 1, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-rate-limit' archived as '2026-08-11-add-rate-limit'.

La carpeta del cambio se mueve completa a openspec/changes/archive/2026-08-11-add-rate-limit/, con la fecha de hoy antepuesta a su nombre. Cada delta se fusiona en su especificación principal: el requisito ADDED anterior se añadió al final de openspec/specs/api/spec.md. Sin -y, archive muestra la vista previa y pregunta antes de actualizar. Rechazar la confirmación archiva el cambio de todos modos y deja las especificaciones intactas.

Con --json --yes:

json

{
  "archive": {
    "change": "add-rate-limit",
    "archivedAs": "2026-08-11-add-rate-limit",
    "path": "/Users/you/projects/my-app/openspec/changes/archive/2026-08-11-add-rate-limit",
    "specsUpdated": true,
    "totals": {
      "added": 1,
      "modified": 0,
      "removed": 0,
      "renamed": 0
    }
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Archive valida primero el cambio y rechaza el cambio si falla la validación:

Validation errors in change delta specs:
  ✗ ADDED "Rate limiting" must include at least one scenario

Validation failed. Please fix the errors before archiving.
To skip validation (not recommended), use --no-validate flag.

Las tareas incompletas generan una advertencia, pero no bloquean. En modo interactivo, archive pregunta si se debe continuar, y -y continúa por su cuenta:

Task status: 1/2 tasks
Warning: 1 incomplete task(s) found. Continuing due to --yes flag.

Códigos de salida

0: el cambio se archivó, con o sin actualizaciones de especificaciones.
1: la validación falló, el nombre del cambio es desconocido, o se necesitaba una confirmación y no se pudo leer ninguna respuesta.

openspec new

Crea un nuevo directorio de cambio.

bash

openspec new change add-caching                                # solo metadatos
openspec new change add-search --goal "Users can search docs"  # registra un objetivo

new tiene un solo subcomando, new change <name>. Crea openspec/changes/<name>/ con un único archivo de metadatos .openspec.yaml:

yaml

schema: spec-driven
created: 2026-08-11

Los artefactos (propuesta, especificaciones, diseño, tareas) no se generan como plantilla aquí. Los escribes más adelante, y openspec status te indica cuál es el siguiente.

Argumentos

Argumento	Qué es
`name`	Nombre de la carpeta para el cambio (`add-caching`).

Opciones

Opción	Efecto
`--description <text>`	También crea un `README.md` en el directorio del cambio con este texto.
`--goal <text>`	Guarda una línea `goal:` en `.openspec.yaml`.
`--schema <name>`	Esquema de flujo de trabajo para el cambio. Predeterminado: `spec-driven`, el único esquema incluido.
`--json`	Imprime el cambio creado como JSON en lugar de texto.
`--store <id>`	Usa un almacén registrado como raíz de OpenSpec en lugar del proyecto actual.

Salida

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Cuando no se encuentra ningún directorio openspec/, new change crea uno en el directorio actual y lo indica:

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Note: no OpenSpec root was found here, so one was created at openspec/.
Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.

El aviso se envía a stdout junto con el resto de la salida legible para personas, y nunca aparece con --json.

Con --json, en un proyecto que ya tiene openspec/:

json

{
  "change": {
    "id": "add-caching",
    "path": "/Users/you/projects/my-app/openspec/changes/add-caching",
    "metadataPath": "/Users/you/projects/my-app/openspec/changes/add-caching/.openspec.yaml",
    "schema": "spec-driven"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Cuando no se encontró ningún directorio openspec/ y new change creó uno, el JSON tiene la misma estructura. root.path es el directorio desde el que lo ejecutaste, y root.source muestra implicit:

json

"root": {
  "path": "/Users/you/projects/my-app",
  "source": "implicit"
}

Códigos de salida

0: el cambio se creó.
1: el cambio ya existe, o el esquema es desconocido.

openspec status

Informa del estado de finalización de artefactos para un cambio o para todos los cambios activos.

bash

openspec status --change add-rate-limit          # vista de lista de verificación
openspec status --change add-rate-limit --json   # informe estructurado
openspec status --all                            # todos los cambios activos
openspec status --all --json                     # un informe por lotes

Cuando existen cambios activos, usa exactamente una de --change o --all. Sin ninguna de las dos, status sale con código 1 y lista los cambios disponibles, incluso cuando solo existe uno:

text

✖ Error: Missing required option --change (or --all for every active change). Available changes:
  add-rate-limit

Cuando el proyecto no tiene cambios activos, status imprime No active changes. Create one with: openspec new change <name> y sale con código 0 incluso sin ninguno de los dos flags. Con --all --json, el mismo estado vacío es { "changes": [], "message": "No active changes.", "root": ... }.

Opciones

Flag	Efecto
`--change <id>`	El cambio sobre el que informar, por nombre de carpeta.
`--all`	Informar de todos los cambios activos, ordenados por nombre. No se puede combinar con `--change`.
`--schema <name>`	Anular el esquema autodetectado desde `openspec/config.yaml`. Un nombre desconocido es un error.
`--json`	Imprimir un informe estructurado en lugar de texto.
`--store <id>`	Usar un store registrado como raíz de OpenSpec en lugar del proyecto actual.

Salida

Una lista de verificación de los artefactos del esquema: [x] completado, [ ] listo para escribir, [-] bloqueado hasta que existan los artefactos de los que depende.

Change: add-rate-limit
Schema: spec-driven
Change root: /Users/you/projects/my-app/openspec/changes/add-rate-limit
Progress: 2/4 artifacts complete

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)

Next: openspec instructions design --change "add-rate-limit" --json

La línea Next: nombra el único comando que hace avanzar el cambio, por lo que openspec status es suficiente para retomar un cambio en una sesión nueva. Nombra el siguiente artefacto listo mientras la planificación no ha terminado, y openspec instructions apply una vez que existen todos los artefactos de planificación:

[x] proposal
[x] specs
[x] design
[x] tasks

All planning artifacts complete!
Next: openspec instructions apply --change "add-rate-limit" --json

Incluye --store <id> cuando la raíz resuelta es un store, y nombra el mismo comando que la oración nextSteps del JSON.

--json añade dependencias por artefacto, rutas de archivo resueltas y un siguiente paso sugerido. Recortado:

json

{
  "changeName": "add-rate-limit",
  "schemaName": "spec-driven",
  "isComplete": false,
  "nextSteps": [
    "Run openspec instructions design --change \"add-rate-limit\" --json before writing that artifact."
  ],
  "artifacts": [
    {
      "id": "proposal",
      "outputPath": "proposal.md",
      "status": "done",
      "requires": []
    },
    {
      "id": "design",
      "outputPath": "design.md",
      "status": "ready",
      "requires": [
        "proposal"
      ]
    },
    {
      "id": "tasks",
      "outputPath": "tasks.md",
      "status": "blocked",
      "requires": [
        "specs",
        "design"
      ],
      "missingDeps": [
        "design"
      ]
    }
  ]
}

Con --all --json, changes contiene el mismo objeto de estado para cada cambio, sin un root por cambio. La raíz seleccionada aparece una vez en el sobre. Este ejemplo recorta los campos de estado por cambio mostrados anteriormente:

json

{
  "changes": [
    {
      "changeName": "add-rate-limit",
      "schemaName": "spec-driven",
      "artifacts": []
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Si un cambio no se puede cargar, el lote continúa. Su entrada contiene changeName y un diagnóstico de status mientras las demás entradas permanecen disponibles. El comando sale con código 1, incluyendo en modo JSON, para que CI no acepte un informe incompleto como exitoso. La salida JSON sigue siendo un documento parseable.

Códigos de salida

0: todos los estados solicitados impresos; un informe --all vacío también sale con 0.
1: un cambio solicitado no se pudo cargar, falta --change o --all, se combinaron los dos flags, el cambio no existe o la anulación de esquema es desconocida.

openspec instructions

Imprime instrucciones para crear un artefacto, aplicar o archivar. Tu agente ejecuta esto durante el flujo de trabajo para obtener el texto de instrucción para su siguiente paso.

bash

openspec instructions proposal --change add-rate-limit   # cómo escribir un artefacto
openspec instructions apply --change add-rate-limit      # cómo implementar el cambio
openspec instructions archive --change add-rate-limit    # entradas para archivar

Argumentos

Argumento	Qué es
`artifact`	Un id de artefacto del esquema (`proposal`, `specs`, `design`, `tasks` en `spec-driven`), o las palabras reservadas `apply` y `archive`.

Opciones

Flag	Efecto
`--change <id>`	El cambio para el que generar instrucciones. Obligatorio.
`--schema <name>`	Anular el esquema. Autodetectado desde `config.yaml` en caso contrario.
`--json`	Imprimir un objeto estructurado en lugar de texto.
`--store <id>`	Usar un store registrado como raíz de OpenSpec en lugar del proyecto actual.

Salida

La forma de artefacto imprime un bloque de instrucción: la tarea, el archivo a escribir, cómo escribirlo, la plantilla del artefacto y lo que se desbloquea al completarlo.

<artifact id="proposal" change="add-rate-limit" schema="spec-driven">

<task>
Create the proposal artifact for change "add-rate-limit".
Initial proposal document outlining the change
</task>

<output>
Write to: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
</output>

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

apply imprime archivos de contexto, progreso de tareas y la instrucción de trabajo:

## Apply: add-rate-limit
Schema: spec-driven

### Context Files
- proposal: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
- specs: /Users/you/projects/my-app/openspec/changes/add-rate-limit/specs/api/spec.md
- tasks: /Users/you/projects/my-app/openspec/changes/add-rate-limit/tasks.md

### Progress
1/3 complete

### Tasks
- [x] 1.1 Add rate limit middleware
- [ ] 1.2 Return 429 with Retry-After header
- [ ] 1.3 Add tests for burst traffic

### Instruction
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.

No project context or operation guidance configured.

Cuando faltan artefactos obligatorios, apply informa ### ⚠️ Blocked y los nombra. archive imprime el nombre del cambio más cualquier contexto del proyecto y orientación de operación de la configuración. Si no hay ninguno configurado, lo indica y nada más.

Con --json, cada forma devuelve un objeto. La forma de artefacto comienza:

json

{
  "changeName": "add-rate-limit",
  "artifactId": "proposal",
  "schemaName": "spec-driven",
  "changeDir": "/Users/you/projects/my-app/openspec/changes/add-rate-limit",
  ...

y continúa con outputPath, existingOutputPaths, las cadenas completas de instruction y template, dependencies, unlocks y root. La forma apply incluye contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done) e instruction.

Cada entrada de tasks incluye id, description, done, sourcePath y line. sourcePath es la ruta absoluta al archivo rastreado que proporcionó la tarea. line es el número de línea basado en uno del checkbox de la tarea en ese archivo.

taskTrackingConfigured es siempre un booleano: true cuando el esquema establece un apply.tracks no nulo, incluso si ningún archivo coincide, y false en caso contrario. Si un archivo de rastreo coincidente no se puede leer, unavailableTrackingFiles contiene su path absoluto y la reason del error. Este campo se omite cuando todos los archivos coincidentes son legibles. Los archivos legibles siguen contribuyendo a tasks y progress, pero state no puede ser all_done hasta que se lean todos los archivos coincidentes.

Códigos de salida

0: instrucciones impresas.
1: artefacto desconocido, cambio desconocido, esquema desconocido o falta --change. Cada error lista los valores válidos.

openspec templates

Imprime las rutas de plantilla resueltas para los artefactos de un esquema.

bash

openspec templates          # esquema predeterminado: spec-driven
openspec templates --json   # mapa de ids de artefactos a rutas

Opciones

Flag	Efecto
`--schema <name>`	Esquema a resolver. Predeterminado: `spec-driven`.
`--json`	Imprime un mapa JSON de ids de artefactos a rutas de plantilla.

Salida

Schema: spec-driven
Source: package

proposal:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md
specs:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md
design:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md
tasks:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md

Source indica desde dónde se resolvió el esquema: project (openspec/schemas/ en tu proyecto), user (una anulación global) o package (integrado en la CLI). Project tiene prioridad sobre user, y user sobre package.

json

{
  "proposal": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md",
    "source": "package"
  },
  "specs": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md",
    "source": "package"
  },
  "design": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md",
    "source": "package"
  },
  "tasks": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md",
    "source": "package"
  }
}

Códigos de salida

0: se imprimieron las rutas.
1: esquema desconocido. El error lista los esquemas disponibles.

openspec schemas

Lista los esquemas de flujo de trabajo disponibles.

bash

openspec schemas          # nombres, descripciones, orden de artefactos
openspec schemas --json   # legible por máquinas, para uso de agentes

Opciones

Flag	Efecto
`--json`	Salida como JSON (para uso de agentes).

Salida

Available schemas:

  spec-driven
    Default OpenSpec workflow - proposal → specs → design → tasks
    Artifacts: proposal → specs → design → tasks

Los esquemas de tu proyecto se etiquetan como (project), y las anulaciones globales se etiquetan como (user override).

json

[
  {
    "name": "spec-driven",
    "description": "Default OpenSpec workflow - proposal → specs → design → tasks",
    "artifacts": [
      "proposal",
      "specs",
      "design",
      "tasks"
    ],
    "source": "package"
  }
]

Códigos de salida

0: se listaron los esquemas.
1: no se pudo leer la lista de esquemas.

openspec schema

Inspecciona, bifurca (fork) o crea un esquema (experimental). Cada subcomando primero imprime Note: Schema commands are experimental and may change. en stderr.

bash

openspec schema which spec-driven          # de dónde se resuelve un esquema
openspec schema fork spec-driven my-flow   # copia un esquema al proyecto
openspec schema init my-schema             # crea un esquema desde cero

Subcomando	Qué hace
`which`	Muestra de dónde se resuelve un esquema.
`validate`	Comprueba la estructura y las plantillas de un esquema.
`fork`	Copia un esquema existente al proyecto para personalizarlo.
`init`	Crea un nuevo esquema local al proyecto.

Los esquemas se resuelven desde tres ubicaciones. Gana la primera coincidencia:

Fuente	Ubicación
`project`	`openspec/schemas/` en el proyecto actual.
`user`	`~/.local/share/openspec/schemas/` (se respetan `XDG_DATA_HOME` y `%LOCALAPPDATA%` de Windows).
`package`	Los esquemas incluidos con la CLI. `spec-driven` vive aquí.

openspec schema which

Muestra qué copia de un esquema usará la CLI.

bash

openspec schema which spec-driven
openspec schema which --all        # todos los esquemas, agrupados por fuente

Argumentos

Argumento	Qué es
`name`	El esquema a buscar. Obligatorio a menos que se establezca `--all`. Sin ninguno de los dos, which sale con código 1.

Opciones

Flag	Efecto
`--all`	Lista todos los esquemas con su fuente de resolución.
`--json`	Imprime la resolución como JSON.

Salida

Schema: spec-driven
Source: package
Path: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven

Cuando una copia de mayor prioridad oculta a otra, una sección Shadows: lista las copias ocultas. Con --json:

json

{
  "name": "my-flow",
  "source": "project",
  "path": "/Users/you/projects/my-app/openspec/schemas/my-flow",
  "shadows": []
}

Un nombre desconocido sale con código 1 y lista los esquemas disponibles.

openspec schema validate

Comprueba la estructura y las plantillas de un esquema.

bash

openspec schema validate spec-driven   # un esquema, desde cualquier fuente
openspec schema validate               # todos los esquemas locales al proyecto

Verifica que schema.yaml existe y se analiza correctamente, que la estructura coincide con el formato de esquema, que el archivo de plantilla de cada artefacto existe dentro del directorio templates/ del esquema, y que el grafo de dependencias no tiene ciclos ni referencias desconocidas, incluido en apply.requires. Un valor de apply.tracks que no sea exactamente igual al valor generates de algún artefacto imprime una línea warning: pero no hace fallar la validación, porque entonces OpenSpec no puede saber a qué artefacto pertenece el progreso de ese archivo.

Opciones

Flag	Efecto
`--json`	Imprime un informe estructurado en lugar de texto.
`--verbose`	Imprime cada paso de la validación.

Salida

✓ Schema 'spec-driven' is valid

Sin nombre, cada esquema del proyecto recibe una línea bajo un encabezado Validation Results:. Un esquema que falla lista sus problemas y la ejecución sale con código 1:

✗ Schema 'my-schema' has errors:
  error: Template file 'tasks.md' not found for artifact 'tasks'

openspec schema fork

Copia un esquema existente al proyecto para que puedas personalizarlo.

bash

openspec schema fork spec-driven my-flow

Argumentos

Argumento	Qué es
`source`	El esquema a copiar, desde cualquier ubicación de origen.
`name`	Nombre para la copia. Kebab-case (`my-workflow`). Predeterminado: `<source>-custom`.

Opciones

Flag	Efecto
`--force`	Sobrescribe un esquema de destino existente.
`--json`	Imprime el resultado como JSON.

Salida

✔ Forked 'spec-driven' to 'my-flow'

Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven (package)
Destination: /Users/you/projects/my-app/openspec/schemas/my-flow

El fork se coloca en openspec/schemas/, y el campo name: de su schema.yaml se reescribe con el nuevo nombre:

openspec/schemas/my-flow/
├── schema.yaml
└── templates/
    ├── design.md
    ├── proposal.md
    ├── spec.md
    └── tasks.md

Un destino existente es un error a menos que pases --force. Un fork que conserva el nombre del origen oculta al original.

openspec schema init

Crea un nuevo esquema local al proyecto con plantillas iniciales.

bash

openspec schema init my-schema --description "Lightweight flow" --artifacts proposal,tasks

Sin --description ni --artifacts en una terminal interactiva, init solicita una descripción, una lista de verificación de artefactos, y si se debe hacer que el esquema sea el predeterminado del proyecto. Fuera de una terminal, usa los valores predeterminados a continuación.

Argumentos

Argumento	Qué es
`name`	Nombre para el nuevo esquema. Kebab-case (`my-workflow`).

Opciones

Flag	Efecto
`--description <text>`	Descripción del esquema. Predeterminado: `Custom workflow schema for <name>`.
`--artifacts <list>`	IDs de artefacto separados por comas de `proposal`, `specs`, `design`, `tasks`. Predeterminado: los cuatro.
`--default`	Escribe `schema: <name>` en el `openspec/config.yaml` o `openspec/config.yml` existente. Crea `openspec/config.yaml` si no existe ninguno. Los nuevos cambios usan este esquema.
`--no-default`	Omite la pregunta sobre el valor predeterminado.
`--force`	Sobrescribe un esquema existente con el mismo nombre.
`--json`	Imprime el resultado como JSON.

La creación del esquema y la actualización de la configuración con --default son una sola operación. Si OpenSpec no puede validar o escribir la configuración, deja tanto la configuración como cualquier esquema existente sin cambios.

Salida

✔ Created schema 'my-schema'

Schema created at: /Users/you/projects/my-app/openspec/schemas/my-schema

Artifacts: proposal, tasks

La disposición en disco:

openspec/schemas/my-schema/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

schema.yaml conecta los artefactos seleccionados con sus dependencias. Cuando se incluye tasks, también obtiene una fase apply que rastrea tasks.md. Usa el esquema con openspec new --schema my-schema.

openspec store

Crea y gestiona stores: repositorios OpenSpec independientes registrados en tu máquina.

bash

openspec store setup team-context --path ~/openspec/team-context   # crear y registrar
openspec store register ~/stores/design-system                     # registrar una copia de trabajo existente
openspec store list                                                # ver qué está registrado

Los registros viven en un registro por máquina: ~/.local/share/openspec/stores/registry.yaml, o $XDG_DATA_HOME/openspec/stores/registry.yaml cuando XDG_DATA_HOME está establecido. Cada subcomando acepta --json para imprimir un informe estructurado en lugar de texto. Ejecutar openspec store con un subcomando faltante o desconocido sale con código 1 y lista los subcomandos.

Subcomando	Qué hace
`setup [id]`	Crea una carpeta de store y la registra.
`register [path]`	Registra una carpeta de store existente.
`unregister <id>`	Olvida el registro. La carpeta permanece en el disco.
`remove <id>`	Olvida el registro y elimina la carpeta.
`list` (alias `ls`)	Lista los stores registrados.
`doctor [id]`	Comprueba el registro, los metadatos y el estado de Git de los stores registrados.

openspec store setup

Crea una carpeta de store y la registra.

bash

openspec store setup team-context --path ~/openspec/team-context

En una terminal interactiva, setup solicita un nombre y una ubicación faltantes y confirma antes de crear nada. Fuera de una, un nombre o --path faltante sale con código 1 junto con el flag que hay que pasar. Volver a ejecutar setup para un store registrado informa Registry: already registered.

Setup sale con código 1 con store_setup_inside_git_repo cuando --path está dentro de otro repositorio Git, porque inicializar el store allí anidaría un repositorio dentro de otro. --no-init-git no crea ningún repositorio, por lo que omite esa comprobación. Úsalo para mantener un store en ~/openspec/<id> cuando tu directorio home es en sí mismo un repositorio Git, como un repositorio de dotfiles.

Argumentos

Argumento	Qué es
`id`	El nombre del store. Se convierte en el id que pasas a `--store`.

Opciones

Flag	Efecto
`--path <path>`	Carpeta donde debe vivir el store (se expande `~`).
`--init-git`	Inicializa un repositorio Git con un commit inicial. Predeterminado.
`--no-init-git`	Omite toda acción de Git: sin init, sin commit inicial.
`--remote <url>`	Fuente de clonación canónica registrada en `store.yaml`.

Salida

Store ready: team-context
Location: /Users/you/stores/team-context
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-context
Share this store by committing and pushing it like any Git repo.

--json informa qué se creó y dónde se registró:

json

{
  "store": {
    "id": "design-system",
    "root": "/Users/you/stores/design-system",
    "metadata_path": "/Users/you/stores/design-system/.openspec-store/store.yaml"
  },
  "registry": {
    "path": "/Users/you/.local/share/openspec/stores/registry.yaml",
    "registered": true,
    "already_registered": false
  },
  "git": {
    "is_repository": true,
    "initialized": true,
    "committed": true
  },
  "created_files": [
    "openspec/",
    "openspec/specs/",
    "openspec/changes/",
    "openspec/changes/archive/",
    "openspec/config.yaml",
    "openspec/specs/.gitkeep",
    "openspec/changes/archive/.gitkeep",
    ".openspec-store/store.yaml"
  ],
  "status": []
}

openspec store register

Registra una carpeta de store existente, por ejemplo el store de un compañero de equipo que clonaste.

bash

openspec store register ~/stores/design-system

La carpeta debe contener una raíz openspec/ en buen estado. Si .openspec-store/store.yaml está presente, register reutiliza el id registrado. Sin él, register pregunta antes de crear esos metadatos. Fuera de una terminal interactiva, pasa --yes en su lugar. Una máquina puede registrar una copia de trabajo por id de store. Una segunda ruta bajo el mismo id, o la misma ruta bajo un segundo id, sale con código 1.

Argumentos

Argumento	Qué es
`path`	La carpeta de store a registrar (se expande `~`). Obligatorio.

Opciones

Flag	Efecto
`--id <id>`	Id del store. Predeterminado: los metadatos o el nombre de la carpeta.
`--yes`	Confirma la creación de los metadatos de identidad del store para una raíz OpenSpec en buen estado.

Salida

Store registered: design-system
Location: /Users/you/stores/design-system
OpenSpec root: ready
Registry: registered

--json imprime la misma forma de documento que store setup --json.

openspec store unregister

Olvida el registro. La carpeta permanece en el disco.

bash

openspec store unregister design-system

Unregistered store: design-system
Files kept at: /Users/you/stores/design-system

openspec store remove

Olvida el registro y elimina la carpeta.

bash

openspec store remove design-system --yes

De forma interactiva, remove pregunta antes de eliminar. Con --json o fuera de una terminal interactiva, la eliminación requiere --yes:

Error: Pass --yes to delete store files non-interactively.
Fix: openspec store remove design-system --yes

Remove sale con código 1 y no elimina nada cuando a la carpeta le faltan los metadatos de store correspondientes, o cuando contiene otro store registrado (por ejemplo, un store incluido como submódulo de Git). En ese caso el error es store_remove_contains_registered_store: ejecuta openspec store unregister <nested-id> primero, o openspec store unregister <id> para olvidar el store sin eliminar archivos.

Opciones

Flag	Efecto
`--yes`	Confirma la eliminación de la carpeta local del store.

Salida

Removed store: design-system
Deleted: /Users/you/stores/design-system

openspec store list

Lista los stores registrados. ls es un alias.

bash

openspec store list

OpenSpec stores (2)

ID              Location
design-system   /Users/you/stores/design-system
team-context    /Users/you/stores/team-context

Sin nada registrado, list imprime No stores registered. y los comandos setup y register que hay que ejecutar a continuación.

openspec store doctor

Comprueba el registro, los metadatos y el estado de Git de los stores registrados.

bash

openspec store doctor                # todos los stores registrados
openspec store doctor team-context  # un store

Salida

Store doctor

team-context
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Metadata: ok
  Git: repository detected (commits: yes, uncommitted changes: no, remote: none)
  Issues: none

Códigos de salida

0: el informe se imprimió, incluso cuando un store informa problemas.
1: el informe no pudo ejecutarse (por ejemplo, un id de store desconocido).

openspec doctor

Informa el estado de salud de las relaciones para la raíz de OpenSpec resuelta.

bash

openspec doctor                       # raíz openspec/ más cercana por encima de tu cwd
openspec doctor --store team-context  # un store registrado como raíz

Doctor es de solo lectura: nunca clona, sincroniza ni repara. Informa si la raíz está en buen estado y si cada referencia declarada en openspec/config.yaml se resuelve en esta máquina. Sin una raíz por encima de tu cwd y sin --store, sale con código 1 y nombra tus stores registrados.

Opciones

Flag	Efecto
`--store <id>`	Usar un store registrado como raíz de OpenSpec en lugar del proyecto actual.
`--json`	Imprimir el informe de salud como JSON.

Salida

Doctor

Root
  Location: /Users/you/projects/my-app
  OpenSpec root: ok

References
  - team-context: ok (/Users/you/stores/team-context)

Con --store, la raíz es el store y el informe añade una línea de store:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Doctor

Root
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Store: team-context (metadata ok)

References
  (none declared)

json

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "healthy": true,
    "status": []
  },
  "store": null,
  "references": [
    {
      "store_id": "team-context",
      "root": "/Users/you/stores/team-context",
      "status": []
    }
  ],
  "status": []
}

Códigos de salida

0: el informe se imprimió, incluyendo cuando enumera problemas.
1: no se resolvió ninguna raíz (no hay openspec/ por encima de tu cwd y no se indicó --store), o un id de --store desconocido.

openspec context

Imprime el contexto de trabajo para la raíz de OpenSpec resuelta: la raíz más cada store referenciado declarado en openspec/config.yaml, cada uno con un comando de obtención.

bash

openspec context                       # raíz openspec/ más cercana por encima de tu cwd
openspec context --store team-context  # un store registrado como raíz
openspec context --json                # resumen para agentes

Las referencias que no se resuelven en esta máquina aparecen en una sección Not available on this machine, cada una con una solución.

Opciones

Flag	Efecto
`--store <id>`	Usar un store registrado como raíz de OpenSpec en lugar del proyecto actual.
`--json`	Imprimir el resumen para agentes como JSON.
`--code-workspace <path>`	Escribir también un archivo de workspace de VS Code para el conjunto.
`--force`	Sobrescribir un archivo `--code-workspace` existente.

Salida

Working context for my-app (/Users/you/projects/my-app)

OpenSpec root
  my-app  /Users/you/projects/my-app

Referenced stores
  team-context  /Users/you/stores/team-context
    Fetch: openspec show <spec-id> --type spec --store team-context

Con --store, el store es todo el conjunto:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Working context for team-context (/Users/you/stores/team-context)

OpenSpec root
  team-context  /Users/you/stores/team-context

No references declared; the working set is this root alone.

json

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "role": "openspec_root"
  },
  "members": [
    {
      "role": "referenced_store",
      "id": "team-context",
      "path": "/Users/you/stores/team-context",
      "fetch": "openspec show <spec-id> --type spec --store team-context",
      "status": []
    }
  ],
  "status": []
}

Escritura de un archivo de workspace

--code-workspace escribe un archivo de workspace de VS Code en la ruta indicada: una carpeta para la raíz, una carpeta ref:<id> por cada store referenciado disponible. Las referencias no disponibles se omiten y se nombran en la línea de resumen, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). El resumen se imprime en stderr, de modo que la salida --json en stdout permanece como un solo documento JSON. Un archivo existente hace que se salga con código 1 a menos que se pase --force.

json

{
  "folders": [
    {
      "name": "my-app",
      "path": "/Users/you/projects/my-app"
    },
    {
      "name": "ref:team-context",
      "path": "/Users/you/stores/team-context"
    }
  ]
}

Códigos de salida

0: el informe se imprimió.
1: no se resolvió ninguna raíz (no hay openspec/ por encima de tu cwd y no se indicó --store), o la escritura de --code-workspace fue rechazada.

openspec workset

Compone, conserva y abre vistas de trabajo personales. Un workset es una lista guardada y con nombre de carpetas con las que trabajas de forma conjunta.

bash

openspec workset create checkout --member ~/projects/checkout-api --member web=~/projects/checkout-web
openspec workset list
openspec workset remove checkout --yes

Subcomando	Qué hace
`create [name]`	Compone y guarda una vista de trabajo con nombre de las carpetas que elijas.
`list`, `ls`	Muestra los worksets guardados con sus miembros.
`open <name>`	Abre un workset guardado en tu herramienta (ventana de editor o sesión de agente).
`remove <name>`	Elimina un workset guardado (las carpetas de los miembros nunca se modifican).

Un workset es puramente local:

Su estado reside en una sola carpeta: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ cuando está definida; %LOCALAPPDATA%\openspec\worksets\ en Windows).
No se escribe nada en las carpetas de los miembros, y no se confirma ni se comparte nada.
Eliminar esa única carpeta borra todo rastro.

openspec workset create

Guarda una vista de trabajo con nombre de carpetas.

bash

openspec workset create checkout \
  --member ~/projects/checkout-api \
  --member web=~/projects/checkout-web

En una terminal interactiva, create solicita todo lo que las banderas no proporcionaron: el nombre, las carpetas de una en una, una herramienta y, a continuación, una oferta para abrir el workset ahora. Fuera de una terminal interactiva, la falta de un nombre o miembro es un error. Un nombre que ya esté guardado siempre es un error. Elimínalo primero.

Argumentos

Argumento	Qué es
`name`	El nombre del workset. En kebab-case: letras minúsculas, números y guiones simples. Obligatorio fuera de una terminal interactiva.

Opciones

Bandea	Efecto
`--member <member>`	Carpeta miembro como `<path>` o `<name>=<path>`, repetible. La primera es la principal. La ruta debe ser una carpeta existente y la etiqueta se establece por defecto con el nombre de la propia carpeta.
`--tool <id>`	Herramienta preferida para abrir este workset. IDs integrados: `code` (VS Code), `cursor` (Cursor). `claude` y `codex` están temporalmente deshabilitados.
`--json`	Imprime el workset guardado como JSON.

Salida

Saved workset 'checkout' (2 members) to your machine.
Open it any time with: openspec workset open checkout

openspec workset list

Muestra los worksets guardados con sus miembros, ordenados por nombre.

bash

openspec workset list   # alias: ls

Opciones

Bandea	Efecto
`--json`	Imprime los worksets como JSON.

Salida

Un bloque por workset: el nombre, su herramienta si la tiene y, a continuación, una fila name path por miembro. Si no hay nada guardado, list imprime No worksets saved. Create one with: openspec workset create.

checkout
  checkout-api  /Users/you/projects/checkout-api
  web           /Users/you/projects/checkout-web
checkout-tool  (opens in VS Code)
  checkout-api  /Users/you/projects/checkout-api

Con --json:

json

{
  "worksets": [
    {
      "name": "checkout",
      "members": [
        {
          "name": "checkout-api",
          "path": "/Users/you/projects/checkout-api"
        },
        {
          "name": "web",
          "path": "/Users/you/projects/checkout-web"
        }
      ]
    }
  ],
  "status": []
}

openspec workset open

Abre un workset guardado en tu herramienta. Las herramientas de editor (code, cursor) reciben un archivo .code-workspace generado. Se abre una ventana y el comando regresa. Las herramientas de agente CLI (claude, codex) tomarían el control de esta terminal con todos los miembros adjuntos. Están temporalmente deshabilitadas mientras se rediseña ese flujo, por lo que los worksets se abren en un IDE por ahora.

bash

openspec workset open checkout                # saved tool, or a prompt
openspec workset open checkout --tool cursor  # this tool just this once

Argumentos

Argumento	Qué es
`name`	El workset que se va a abrir.

Opciones

Bandea	Efecto
`--tool <id>`	Abrir con esta herramienta solo esta vez.

Sin --tool y sin herramienta guardada, open te solicita que elijas una herramienta instalada. Fuera de una terminal interactiva, sale con el código 1.

Una carpeta miembro que ya no existe se omite con una advertencia. Cuando falta la principal, el siguiente miembro superviviente se convierte en el principal para esta apertura. Cuando no existe ninguna carpeta miembro, la apertura falla.
--json se rechaza: open cede la terminal a la herramienta y no tiene modo JSON.
Cuando el lanzamiento falla, el error termina con la ruta manual: la ruta del archivo de workspace y la lista de miembros.

Códigos de salida

Refleja la herramienta: el comando sale con el código de salida de la propia herramienta, y una señal se convierte en 128+n (130 después de Ctrl-C).
1: workset desconocido, ninguna carpeta miembro disponible o ninguna herramienta utilizable.

openspec workset remove

Elimina un workset guardado y su archivo .code-workspace generado. Las carpetas de los miembros nunca se modifican.

bash

openspec workset remove checkout --yes

En una terminal interactiva, remove muestra el workset y te pide confirmación. Con --json, o fuera de una terminal, requiere --yes y sale con el código 1 si no se proporciona.

Opciones

Bandea	Efecto
`--yes`	Confirmar la eliminación de forma no interactiva.
`--json`	Imprime la eliminación como JSON.

Salida

Removed workset 'checkout'. Member folders were not touched.

openspec version

Informa de la versión de OpenSpec en ejecución y de cómo se instaló esta copia.

bash

openspec version                 # local version and install details
openspec version --json          # structured local report
openspec version --check         # also check the registry for an update
openspec version --check --json  # structured local and update report

Sin --check, este comando es local y no se comunica con un registro. Funciona fuera de un proyecto OpenSpec. La bandera existente openspec --version sigue siendo la forma más corta e imprime solo el número de versión simple.

Opciones

Bandea	Efecto
`--json`	Imprime un documento JSON versionado en lugar de texto.
`--check`	Comprueba en el registro configurado si hay una versión más reciente.

Salida

Para una instalación global de npm:

text

OpenSpec 1.13.2 (npm, global)

El ámbito de instalación es global, project, temporary para un ejecutor efímero como npx, source para un checkout, o standalone para la instalación independiente. OpenSpec omite los detalles que no puede identificar en lugar de adivinarlos.

--json mantiene los detalles desconocidos como valores null explícitos:

json

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  }
}

Con --check, una actualización disponible añade la última versión y un comando cuando OpenSpec puede identificar un comando seguro para esa instalación:

text

OpenSpec 1.13.2 (npm, global)
Update available: 1.14.0
  npm install -g @fission-ai/openspec@latest

json

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  },
  "update": {
    "status": "available",
    "latest": "1.14.0",
    "command": "npm install -g @fission-ai/openspec@latest",
    "canSelfUpgrade": true
  }
}

Valores de estado de actualización:

Estado	Significado
`available`	El registro devolvió una versión segura más reciente que la versión en ejecución.
`current`	La comprobación finalizó y no encontró una versión más reciente.
`disabled`	Una configuración existente de privacidad o de comprobación de actualizaciones bloqueó el acceso al registro. `latest` es `null`.
`offline`	El registro no estaba disponible o devolvió una respuesta inutilizable. `latest` es `null`.

Para la instalación independiente, el comando de actualización es openspec install.

DO_NOT_TRACK, las exclusiones de telemetría, OPENSPEC_NO_UPDATE_CHECK, la detección de CI y las anulaciones de registro no HTTPS rechazadas deshabilitan la comprobación. Las comprobaciones deshabilitadas y sin conexión siguen saliendo con el código 0 porque la disponibilidad de actualizaciones es informativa. Este comando nunca actualiza OpenSpec; canSelfUpgrade solo informa de si la ruta existente openspec update podría actualizar esta copia de forma segura.

Códigos de salida

0: el informe local se imprimió, incluidas las comprobaciones de actualización deshabilitadas o sin conexión.
1: la sintaxis del comando no era válida, como la opción no admitida --upgrade.

openspec install

Instala el openspec independiente. Ejecútalo desde una instalación de npm o Homebrew para cambiar a la versión independiente, o desde la instalación independiente para actualizarla en el mismo lugar.

bash

openspec install          # versión más reciente
openspec install 1.15.0   # una versión específica

Ejecuta el script de instalación, que selecciona la versión más reciente cuyos archivos estén todos adjuntos, así como el archivo para tu máquina, y lo verifica con el SHA256SUMS de esa versión:

Desde un gestor de paquetes: instala en ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) e imprime el comando que elimina la copia anterior, como npm uninstall -g @fission-ai/openspec. Nunca elimina esa copia por sí mismo.
Desde la instalación independiente: reemplaza el archivo en ejecución donde está, con su propio nombre.

Después indica qué copia de openspec se ejecuta ahora, ya que una copia instalada por un gestor de paquetes que aparezca antes en tu PATH seguirá ejecutándose hasta que la elimines.

Argumentos

Argumento	Qué es
`version`	Versión a instalar, como `1.15.0`. Opcional; por defecto, la más reciente.

OPENSPEC_INSTALL_DIR y OPENSPEC_INSTALL_NAME eligen otra carpeta o nombre de archivo.

Códigos de salida

0: instalado.
1: la versión no es una versión de lanzamiento, o la descarga o instalación falló. Tu copia actual queda como estaba.

openspec feedback

Envía comentarios sobre OpenSpec.

bash

openspec feedback "Validate output is hard to scan"
openspec feedback "Archive fails on Windows" --body "Steps: init, propose, archive. Error: EPERM."

La CLI registra tu mensaje como un issue de GitHub en el repositorio Fission-AI/OpenSpec mediante tu CLI gh. El título pasa a ser Feedback: <message>. El cuerpo usa los encabezados del formulario de errores: tu mensaje bajo What happened, el texto de tu --body bajo Details, y una sección Minimal steps to reproduce que te pide que añadas los pasos, ya que la CLI no puede rellenarlos. Un pie de página añade la versión de la CLI, la plataforma y la marca temporal. El issue recibe la etiqueta feedback. Si el repositorio no define esa etiqueta, la CLI lo reintenta sin ella y lo indica.

Argumentos

Argumento	Qué es
`message`	Resumen de una línea. Pasa a ser el título del issue. Obligatorio.

Opciones

Opción	Efecto
`--body <text>`	Descripción más larga añadida al cuerpo del issue.

Salida

Si se ejecuta correctamente:

✓ Feedback submitted successfully!
Issue URL: https://github.com/Fission-AI/OpenSpec/issues/1234

Si gh no está instalado, o si gh no ha iniciado sesión, no se envía nada. La CLI imprime tus comentarios formateados entre los marcadores --- FORMATTED FEEDBACK --- y, después, un enlace que abre el formulario de informe de errores con el título, lo que ocurrió (tu mensaje y el texto de --body), la versión de la CLI y el entorno (plataforma y versión de Node) ya completados. Tú completas el resto del formulario en el navegador. La ruta sin sesión iniciada añade To auto-submit in the future: gh auth login.

Códigos de salida

0: issue creado, o se ejecutó la alternativa de envío manual (sin gh, o gh sin sesión iniciada).
1: no se proporcionó ningún mensaje.
El código propio de gh: gh falló después de la autenticación (red, límite de peticiones, issues deshabilitados). La CLI vuelve a imprimir tus comentarios y la URL de envío manual primero.

openspec completion

Instala o genera autocompletados de shell.

bash

openspec completion install        # detecta tu shell, instala y configura
openspec completion generate zsh   # imprime el script en stdout

Shells compatibles: zsh, bash, fish, powershell. Todos los subcomandos aceptan un argumento de shell opcional. Si lo omites, la CLI detecta tu shell a partir del entorno.

Subcomando	Qué hace
`generate [shell]`	Imprime el script de autocompletado en stdout.
`install [shell]`	Escribe el script y configura tu archivo de inicio del shell.
`uninstall [shell]`	Elimina el script y el bloque de configuración.

Si se instala con Nix, los autocompletados ya están en su sitio: el paquete flake incluye los scripts para Bash, Fish y Zsh en las ubicaciones estándar, por lo que no hace falta install (Instalación).

openspec completion generate

Imprime el script y no escribe nada.

#compdef openspec

# Script de autocompletado de Zsh para OpenSpec CLI
# Generado automáticamente: no editar manualmente

_openspec() {
  local context state line
  typeset -A opt_args
...

openspec completion install

Escribe el script y edita la configuración de tu shell. Los cambios de configuración se colocan entre los marcadores # OPENSPEC:START y # OPENSPEC:END. Si ya existe un script, se hace una copia de seguridad primero (copia .backup-<timestamp>).

Shell	Ubicación del script	Configuración editada
zsh	`~/.zsh/completions/_openspec`	`$ZDOTDIR/.zshrc` cuando `ZDOTDIR` es una ruta absoluta; en caso contrario, `~/.zshrc`
bash	`~/.local/share/bash-completion/completions/openspec`	`~/.bashrc`
fish	`~/.config/fish/completions/openspec.fish`	Ninguna: fish lo carga automáticamente.
powershell	`OpenSpecCompletion.ps1` junto a tu perfil	`$PROFILE`

Si Oh My Zsh está instalado, el script se coloca en $ZSH_CUSTOM/completions/_openspec en su lugar (por defecto, ~/.oh-my-zsh/custom/completions/_openspec).

Un ZDOTDIR relativo o que empiece por ~ se ignora, y en su lugar se edita ~/.zshrc. Si ejecutas install de nuevo cuando el script ya está actualizado, el bloque se sigue añadiendo al .zshrc que lee zsh.

Opciones

Opción	Efecto
`--verbose`	También imprime la ruta instalada, cualquier ruta de copia de seguridad y qué archivo de configuración se editó.

Salida

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Elimina el script y el bloque de configuración marcado. Pregunta antes de tocar tu configuración (por defecto: No).

Para zsh, limpia el .zshrc que edita install, y también ~/.zshrc cuando una instalación anterior dejó un bloque allí bajo ZDOTDIR. Si no se puede eliminar un bloque, uninstall indica el nombre del archivo y sale con el código 1.

Opciones

Opción	Efecto
`-y, --yes`	Omite las solicitudes de confirmación.

Salida

✓ Completion script removed from /Users/you/.zsh/completions/_openspec. Removed OpenSpec configuration from ~/.zshrc

Códigos de salida

0: script generado, instalado o eliminado. Una desinstalación cancelada también sale con 0.
1: shell no compatible o no detectado, o falló algún paso de instalación o desinstalación.

openspec change

Forma nominal obsoleta de show, list y validate. Cada ejecución muestra una advertencia y remite a los comandos con el verbo primero, pero se ejecuta igualmente:

Warning: The "openspec change ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec list", "openspec validate --changes").
Warning: "openspec change list" is deprecated. Use "openspec list".
add-rate-limit

Obsoleto	Usa en su lugar
`openspec change show <name>`	`openspec show <name>`
`openspec change list`	`openspec list`
`openspec change validate <name>`	`openspec validate <name>` (todos los cambios: `openspec validate --changes`)

Las secciones de los comandos con el verbo primero documentan las opciones.

openspec spec

Forma nominal obsoleta de show, list y validate. Cada ejecución muestra una advertencia y remite a los comandos con el verbo primero, pero se ejecuta igualmente:

Warning: The "openspec spec ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec show", "openspec validate --specs").
api

Obsoleto	Usa en su lugar
`openspec spec show <id>`	`openspec show <id>`
`openspec spec list`	`openspec list --specs`
`openspec spec validate <id>`	`openspec validate <id>` (todas las specs: `openspec validate --specs`)

Las secciones de los comandos con el verbo primero documentan las opciones.

CLI ​

Comandos ​

openspec init ​

openspec update ​

openspec config ​

openspec config path ​

openspec config list ​

openspec config get ​

openspec config set ​

openspec config unset ​

openspec config reset ​

openspec config edit ​

openspec config profile ​

openspec list ​

openspec show ​

Por qué ​

Qué cambia ​

openspec view ​

openspec validate ​

--report full|findings ​

Salida de texto de Findings ​

Salida JSON de Findings ​

Solicitudes de informe no válidas ​

Filtrar un informe completo externamente ​

openspec archive ​

openspec new ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

openspec schema ​

openspec schema which ​

openspec schema validate ​

openspec schema fork ​

openspec schema init ​

openspec store ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

openspec doctor ​

openspec context ​

openspec workset ​

openspec workset create ​

openspec workset list ​

openspec workset open ​

openspec workset remove ​

openspec version ​

openspec install ​

openspec feedback ​

openspec completion ​

openspec completion generate ​

openspec completion install ​

openspec completion uninstall ​

openspec change ​

openspec spec ​

CLI

Comandos

openspec init

openspec update

openspec config

openspec config path

openspec config list

openspec config get

openspec config set

openspec config unset

openspec config reset

openspec config edit

openspec config profile

openspec list

openspec show

Por qué

Qué cambia

openspec view

openspec validate

--report full|findings

Salida de texto de Findings

Salida JSON de Findings

Solicitudes de informe no válidas

Filtrar un informe completo externamente

openspec archive

openspec new

openspec status

openspec instructions

openspec templates

openspec schemas

openspec schema

openspec schema which

openspec schema validate

openspec schema fork

openspec schema init

openspec store

openspec store setup

openspec store register

openspec store unregister

openspec store remove

openspec store list

openspec store doctor

openspec doctor

openspec context

openspec workset

openspec workset create

openspec workset list

openspec workset open

openspec workset remove

openspec version

openspec install

openspec feedback

openspec completion

openspec completion generate

openspec completion install

openspec completion uninstall

openspec change

openspec spec