Tutorial de OpenSpec: un cambio real, de la instalación al archive

OpenSpec no hace más inteligente a tu agente. Lleva la discusión sobre qué construir a un archivo, antes de que haya código sobre el cual discutir.

OpenSpec es una capa de spec open source para agentes de IA para código, hecha por Fission AI bajo licencia MIT. Instalas una CLI chica en Node, corres openspec init, y tu agente (Claude Code, Codex, Cursor, GitHub Copilot, OpenCode y más de cuarenta otros) recibe slash commands que convierten un pedido en una carpeta de cambio: una propuesta, un delta de los requisitos, un diseño y una lista de tareas. Lees el plan, el agente lo construye, y al archivar el delta se integra en specs que describen cómo funciona tu sistema hoy.

Trabajo con spec-driven development todos los días, con mis propios kits con gate: claude-sdd-kit en Claude Code y pi-sdd-kit en Pi. No con OpenSpec. Así que para esta guía hice la parte que la mayoría de los tutoriales se salta: instalé OpenSpec 1.14.1 y pasé un cambio real por él con Claude Code, en un repo chico con un ledger. Propose, un review que cambió el plan, apply, archive, y después una sesión de explore. Cada archivo, cada tiempo y cada cita de abajo salen de esa corrida.

Si estás eligiendo entre herramientas en lugar de aprender esta, puse OpenSpec junto a Spec Kit, Superpowers y pi-sdd-kit en herramientas de SDD comparadas.

Dos carpetas y un delta: todo el modelo mental

OpenSpec mantiene dos carpetas. openspec/specs/ describe cómo se comporta tu sistema hoy, una carpeta por capability. openspec/changes/<name>/ guarda un cambio propuesto: el porqué, qué cambia en los requisitos, el cómo y los pasos.

El truco es el delta. Dentro de un cambio no reescribes la spec. Escribes solo lo que se mueve, bajo requisitos ADDED, MODIFIED, REMOVED o RENAMED. Cuando archivas, el delta se aplica a la spec principal y la carpeta del cambio se mueve a changes/archive/ con una fecha adelante. Las specs nunca se escriben por adelantado. Se acumulan, un cambio archivado a la vez.

Imagina la spec principal como el mapa oficial de una ciudad, y un cambio como una hoja de papel calco encima, con solo la cuadra que estás reconstruyendo dibujada en rojo. Archivar pasa el rojo a tinta en el mapa y guarda el papel calco en un cajón con fecha. La analogía esconde un detalle que importa más adelante: dentro de /opsx:archive, el que entinta es el agente, a mano, siguiendo las instrucciones de la skill. Solo openspec archive, corrido en la terminal, integra el delta en código.

Este es mi repo de prueba justo después del primer /opsx:propose:

El repo del ledger después de un /opsx:propose

• openspec/
  • config.yaml// schema: spec-driven, más tu contexto y tus reglas
  • specs/// vacía hasta el primer archive
  • changes/
    • add-idempotent-transfers/cambio
      • .openspec.yaml// schema y fecha de creación
      • proposal.md// el porqué, qué cambia, el impacto
      • specs/ledger-transfers/spec.md// el delta: cinco requisitos ADDED
      • design.md// decisiones, y las alternativas que descartó
      • tasks.md// tareas con checkbox, la mayoría con sus propios tests
    • archive/// cambios terminados, con fecha
• .claude/
  • skills/// seis skills openspec-*
  • commands/opsx/// propose, explore, apply, update, sync, archive

Después de archivar ese cambio, specs/ tenía una capability, ledger-transfers, con cinco requisitos. Nada más. Es la cantidad correcta. La spec cubre lo que toqué, y el próximo cambio va a sumar lo que toque él.

La mitad de los tutoriales de OpenSpec enseña comandos que ya no existen

Las primeras versiones de OpenSpec, en septiembre de 2025, funcionaban con tres comandos: /openspec:proposal, /openspec:apply y /openspec:archive. Muchos de los tutoriales que todavía aparecen primeros en las búsquedas se escribieron en esa época. El 26 de enero de 2026, la versión 1.0 borró los tres.

La reescritura se llama OPSX. Los comandos viejos empujaban un cambio por fases fijas. OPSX le da acciones al agente, y la CLI lleva la cuenta de qué artefactos existen y cuál es el siguiente que está listo. Los archivos del proyecto también cambiaron: OpenSpec dejó de generar archivos de instrucciones como openspec/project.md, AGENTS.md y CLAUDE.md. Ahora tu agente recibe skills, y el contexto de tu proyecto se mudó a openspec/config.yaml.

Cómo llegó OpenSpec a la 1.14

1. 6 sep 20250.1.0

   Primer release en npm. La primera línea corría tres comandos atados a fases y guardaba el contexto del proyecto en openspec/project.md.

2. 26 ene 20261.0: el release OPSX

   Se eliminan los comandos viejos. Las skills reemplazan los archivos de prompt dispersos, y la CLI arma cada instrucción a partir de la config, las reglas y las plantillas.

3. 23 feb 20261.2: /opsx:propose y perfiles

   Un solo comando redacta el plan completo. El perfil core pasa a ser la instalación por defecto.

4. 28 jun 20261.5: Stores, en beta

   Specs y cambios en un repo de planificación propio, para trabajo que abarca varios repos.

5. 10 jul 20261.6: /opsx:update

   Revisa el plan de un cambio después de empezarlo, en lugar de editar cuatro archivos a mano.

6. 29 jul 20261.7: Codex pasa a solo skills

   Codex invoca $openspec-propose. Los cambios pueden declarar skip_specs para trabajo sin cambio de comportamiento.

7. 30 sep 20261.14: más agentes y navegación del archive

   Warp, Grok Build y DeepSeek Harness entre los destinos nuevos. list --archived muestra los cambios terminados. La 1.14.1 llegó el 5 de octubre.

Si una guía te dice que hagas lo de la izquierda, haz lo de la derecha.

Consejos viejos de OpenSpec vs. OpenSpec 1.14

El workflow de la derecha está estable desde febrero. La lista de herramientas crece cada pocas semanas.

Las guías viejas dicen	Haz esto en la 1.14
/openspec:proposal, :apply, :archive	/opsx:propose, /opsx:apply, /opsx:archive
Describe tu proyecto en openspec/project.md	Pon las restricciones bajo context: en openspec/config.yaml
/opsx:new, después /opsx:ff	/opsx:propose hace las dos cosas. new y ff están en el perfil expanded
OpenSpec edita tu AGENTS.md o CLAUDE.md	Escribe skills y comandos, y no toca esos archivos
/opsx:propose en Codex	$openspec-propose. Codex solo lee skills
Instala el MCP server de OpenSpec	No existe. Es una CLI más archivos generados

Instálalo y después vive en el chat

OpenSpec necesita Node 20.19 o más nuevo.

Instalar OpenSpec e inicializar un proyecto

1. npm

   $ npm install -g @fission-ai/openspec@latest

2. Homebrew

   $ brew install openspec

3. Init, elige tus agentes

   $ openspec init

4. Init para Claude Code, sin preguntas

   $ openspec init --tools claude

5. Init para varios agentes

   $ openspec init --tools claude,codex,cursor

Esto es lo que openspec init --tools claude escribió en mi repo: openspec/config.yaml, las carpetas specs/ y changes/archive/ vacías, seis skills en .claude/skills/ y seis comandos en .claude/commands/opsx/. Son 2.620 líneas de instrucciones para el agente. No tocó ni una línea de mi código, y no tocó CLAUDE.md.

OpenSpec recolecta estadísticas de uso anónimas por defecto: nombres de comandos y versión, nada más, y nunca en CI. export OPENSPEC_TELEMETRY=0 las apaga.

Después del setup repartes tu tiempo entre dos lugares, y confundirlos es la forma más común de trabarse. El binario openspec corre en tu terminal. Los comandos /opsx: corren en el chat de tu agente, la misma caja donde le pides que escriba código.

$

Terminal: openspec …

1. 01openspec init: prepara un proyecto para tus agentes
2. 02openspec update: actualiza los archivos generados después de un upgrade o de un cambio de perfil
3. 03openspec list, show, view: muestran cambios y specs
4. 04openspec validate --strict: revisa un cambio antes de que salga
5. 05openspec config profile: elige qué comandos se instalan

/

Chat del agente: /opsx:…

1. 01/opsx:explore: piensa un cambio a fondo, no escribe nada
2. 02/opsx:propose: redacta el plan completo y se detiene
3. 03/opsx:update: revisa un cambio que ya empezaste
4. 04/opsx:apply: lo construye, tarea por tarea
5. 05/opsx:archive: integra el delta y archiva el cambio

El mismo comando se escribe de cinco formas

/opsx:propose es el nombre que usa la documentación. Tu agente puede querer otra cosa, porque cada herramienta carga a su manera el archivo que escribió OpenSpec. Una carpeta llamada opsx/ te da los dos puntos. Un archivo llamado opsx-propose te da el guion. Las herramientas que solo leen skills toman el nombre de la skill.

Cómo escribir /opsx:propose en cada agente

De la referencia de herramientas soportadas de OpenSpec para la 1.14. Los prompt files de Copilot funcionan en las extensiones del IDE, no en Copilot CLI. openspec init imprime la forma correcta para las herramientas que elegiste, así que lee la indicación al final del setup.

Agente	Escribes	Dónde lo escribe OpenSpec
Claude Code	/opsx:propose	.claude/commands/opsx/
Gemini CLI	/opsx:propose	.gemini/commands/opsx/
Cursor	/opsx-propose	.cursor/commands/
GitHub Copilot	/opsx-propose	.github/prompts/
OpenCode	/opsx-propose	.opencode/commands/
Pi	/opsx-propose	.pi/prompts/
Codex	$openspec-propose	.agents/skills/
Amazon Q Developer	@opsx-propose	.amazonq/prompts/
La mayoría de las herramientas solo skills (Hermes, Zed)	/openspec-propose	la carpeta de skills de la herramienta

Las skills y los comandos son dos formatos de entrega para los mismos workflows, y el default instala los dos. openspec config profile puede cambiar la entrega a solo skills o solo comandos. Un detalle que me gustó de las skills generadas: están escritas para el caso en que el agente las elige solo. Si tu agente selecciona por su cuenta una skill de OpenSpec en un repo que nunca corrió openspec init, la skill le dice que deje OpenSpec de lado y responda normalmente, en lugar de crear carpetas a tus espaldas.

Un cambio real, de principio a fin

El repo de prueba es un ledger en memoria: transfer(from, to, cents), centavos enteros, dos tests. El pedido es el bug que más me importa desde que construí una fintech cripto de 13 apps: un retry nunca debe mover dinero dos veces. Pedí claves de idempotencia. Un retry con la misma clave y el mismo payload devuelve el resultado original. La misma clave con un payload distinto se rechaza.

Un cambio por OpenSpec con Claude Code

Entrada

Un ledger de 24 líneas y un pedido: un retry nunca debe mover dinero dos veces

↓

1. 01/opsx:propose (1 min 14 s)

   Creó la carpeta del cambio con los cuatro artefactos, corrió openspec validate --strict y se detuvo. No tocó código. Terminó con las cuatro decisiones que yo no había especificado, para que las revisara.

   ↓
2. 02Review (yo)

   Leí la propuesta y el delta. El plan era bueno. Una decisión estaba mal para un sistema de dinero: la clave era opcional.

   ↓
3. 03/opsx:update (32 s)

   Propuso ediciones en los cuatro archivos y esperó a que yo respondiera apply all antes de escribir nada. Agregó una tarea para arreglar primero los tests viejos, así la suite sigue en verde.

   ↓
4. 04/opsx:apply (1 min 18 s)

   Avanzó por siete tareas en orden, la mayoría con sus propios tests, y las fue marcando en tasks.md. Pasan diez tests.

   ↓
5. 05/opsx:archive (19 s)

   Preguntó si sincronizaba antes el delta con las specs principales. Le dije que sí. Creó specs/ledger-transfers/spec.md y movió el cambio a changes/archive/2026-10-13-add-idempotent-transfers/.

↓

Salida

Una spec de cómo se comportan hoy las transferencias, un registro con fecha del porqué y un diff que coincide con los dos

Lo que produjo la corrida

136

líneas de planpropuesta, delta, diseño, tareas

84

líneas agregadas17 en el ledger, 67 en tests

10/10

tests pasandodos viejos, ocho nuevos

203 s

tiempo del agentecuatro comandos cronometrados; sin contar dos turnos de confirmación

El delta es la parte que vale la pena leer despacio. Este es uno de sus cinco requisitos, tal como quedó en la spec principal después del archive:

### Requirement: Reusing a key with a different payload is rejected

When a transfer is made with a key that a previous successful transfer used,
and the source, destination, or amount differs from that transfer's, the
system SHALL throw an error identifying the key conflict and SHALL NOT change
any balance.

#### Scenario: Same key, different amount

- **WHEN** a transfer of 2500 cents from `alice` to `bob` with key `k1` has
  succeeded, and a transfer of 3000 cents from `alice` to `bob` with key `k1`
  is made
- **THEN** the call throws an error matching `idempotency key reused` and
  `alice` still has 7500 cents and `bob` still has 2500 cents

Cada requisito es una declaración SHALL con un escenario que un test puede verificar línea por línea. La propia guía de OpenSpec pide un SHALL por requisito, y el agente metió cuatro en el primero, lo que ya vale un comentario en el review. También escribió el escenario que yo habría tenido que recordar por mi cuenta: un retry tiene que salir bien incluso cuando una transferencia nueva ya fallaría por falta de fondos. Eso solo funciona si la búsqueda de la clave corre antes de la verificación del saldo, y el diseño lo decía en una oración.

El plan era bueno. Falló en el único lugar que importaba.

El agente hizo la clave opcional. Su diseño daba una razón: exigirla “breaks every existing caller for no gain in a demo ledger” (rompe todas las llamadas existentes sin ganar nada en un ledger de demo). Razonable, para una demo. Pero el agente había decidido en silencio que este código iba a seguir siendo una demo, y ese es justo el tipo de suposición que un plan deja a la vista. El día que este ledger mueva dinero real, una clave de idempotencia opcional significa que basta con que una sola llamada la omita para cobrar dos veces, y nada se queja.

Respondí con una oración: la clave es obligatoria, y una transferencia sin ella lanza un error. /opsx:update llevó esa oración a los cuatro archivos, 21 líneas que entran y 19 que salen, incluida una tarea nueva para arreglar primero los tests viejos. En código, la misma corrección es un breaking change en una API de pagos, publicado cuando todos ya la llamaban a la manera vieja. Ese es todo el trato que ofrece OpenSpec: el desacuerdo pasa en una propuesta de 29 líneas en lugar de en un pull request.

Lee la lista de decisiones al final de cada propose antes de leer cualquier otra cosa. En mi corrida nombró cuatro: la clave opcional, las transferencias fallidas que no consumen su clave, un replay que devuelve el resultado original aunque el saldo haya cambiado, claves que nunca vencen. Esa lista es el agente diciéndote dónde adivinó.

Después haz que esa suposición sea improbable la próxima vez. Volví al repo recién inicializado, agregué dos líneas a openspec/config.yaml (una de ellas: “Every operation that moves money takes an idempotency key. No exceptions.”) y corrí de nuevo el mismo /opsx:propose. La clave volvió obligatoria, y el agente citó la config del proyecto como la razón. Una corrida no es prueba, y context: sigue siendo texto en un prompt, pero ahora la suposición tiene que discutir contra una regla escrita. Si corriges la misma regla dos veces en review, va en context:.

La CLI es la máquina de estados. El agente es el mecanógrafo.

Lee las skills generadas y el diseño queda claro. El agente nunca decide por su cuenta qué sigue. Le pregunta a la CLI. openspec new change arma la carpeta. openspec status --change <name> --json reporta qué artefactos existen, cuál está listo y cuáles están bloqueados. openspec instructions <artifact> --change <name> --json le devuelve todo lo que el agente necesita para escribir un archivo:

Lo que openspec instructions le entrega al agente para cada artefacto

1. 1

   Contexto

   El campo context: de openspec/config.yaml, hasta 50 KB. Entra en cada pedido de planificación.

   context: | Every operation that moves money takes an idempotency key.

   +
2. 2

   Reglas

   Reglas por artefacto del mismo archivo, aplicadas solo a ese artefacto.

   rules: { proposal: [State what is out of scope] }

   +
3. 3

   Plantilla e instrucción

   Del schema, spec-driven por defecto: la estructura del archivo y cómo llenarlo. Al agente se le indica que nunca copie el contexto ni las reglas dentro del artefacto.

   +
4. 4

   Dependencias

   Los artefactos ya escritos sobre los que se apoya este. Al agente se le indica que los vuelva a leer del disco, aunque los haya visto hace un minuto. Por eso el diseño lee la propuesta, las tareas leen las specs y el diseño, y los cuatro archivos coinciden entre sí.

Así que el workflow vive en una CLI que puedes versionar, automatizar y correr en CI, y el agente se encarga de escribir. Por eso OpenSpec funciona en más de cuarenta agentes sin cuarenta implementaciones.

También explica la línea de la skill de propose que más me importa: status “is file-existence only” (solo verifica que los archivos existan). Lo tomé al pie de la letra y creé un cambio con cuatro archivos vacíos. openspec status respondió 4/4 artifacts complete. Los archivos existen, así que el plan está completo. Nadie los leyó, porque no había nada que leer.

El gate vive en el prompt, no en el disco

OpenSpec se detiene en los lugares correctos. En mi corrida, propose cerró su propio turno después del plan, porque la skill dice que el pedido “authorizes planning only” (autoriza solo la planificación). Update me mostró sus ediciones y esperó. Archive preguntó antes de tocar las specs principales. En una sesión interactiva, con una persona escribiendo, esas paradas funcionan.

Igual son instrucciones a un modelo. Nada en openspec/ registra que una persona aprobó el plan, y la prueba de los archivos vacíos muestra cuánto vale el chequeo de progreso. Lo único que atrapó esos archivos vacíos fue openspec validate --strict, que parsea el delta y falló. Esa es la diferencia que vale la pena aprender: algunas garantías las sostiene el código, otras un prompt y otras nadie.

Quién sostiene cada garantía en un workflow de OpenSpec

OpenSpec es fluido a propósito: su documentación llama a los artefactos habilitadores, no gates. Un agente en un loop, o tú cansado a las 11 de la noche, cruza directo la fila del medio.

La sostiene	Qué	Se cumple cuando
El código	validate --strict: un delta que se puede parsear, requisitos de menos de 500 caracteres desde la 1.14.1. openspec archive en la terminal: integra en código y rechaza un delta que no puede leer	Cada vez que lo corres. Pon validate en CI
El prompt	Propose se detiene después del plan. Update y archive muestran la edición y esperan. context: orienta cada propuesta	El modelo sigue sus instrucciones y una persona está leyendo
Nadie	Que alguien leyó el plan. Que apply lo espere. Que las specs sigan coincidiendo con el código después de ediciones a mano: /opsx:verify reporta huecos, nunca bloquea	Solo si tú lo construyes

Es una decisión de diseño, no un bug. Si quieres que el gate lo sostenga el código, pon la aprobación en el disco, donde un chequeo pueda leerla: un archivo de estado por cambio, sin el cual un job de CI o un hook se niega a pasar. No dentro de .openspec.yaml: OpenSpec ignora ahí las claves que no conoce, y validate --strict las marca.

Mis kits están construidos alrededor de ese hueco. En Claude Code, claude-sdd-kit registra la aprobación como un token en un archivo .status, y su agente implementador se detiene cuando no lee tasks:approved. Esa parada sigue siendo una instrucción. La diferencia es que la aprobación se vuelve un hecho en disco, una línea que un hook o un job de CI puede hacer cumplir, en lugar de una impresión en un chat. pi-sdd-kit hace lo mismo en Pi. La página de comparación explica cómo combinar OpenSpec con otras herramientas sin perder el gate.

Explora primero. De verdad no escribe nada.

/opsx:explore es un compañero para pensar. Lee tu código y tus specs, plantea opciones y no escribe nada a menos que se lo pidas. Lo comprobé: después de una sesión de 45 segundos sobre agregar reversiones al ledger, git status estaba limpio.

La respuesta fue lo mejor de toda la corrida. Explore leyó el cambio archivado y encontró un acoplamiento que yo no había visto. El diseño dejaba el vencimiento de las claves fuera del alcance. Explore notó que si las reversiones encuentran una transferencia por su clave, el almacén de claves se convierte, sin que nadie lo decida, en el log de transacciones, y hacer que las claves venzan borraría esa historia: la transferencia ya no se podría revertir nunca. Terminó con una pregunta que decide el resto: ¿solo reversiones completas, o también reembolsos parciales?

Eso es el archive haciendo su trabajo. La siguiente sesión arrancó desde la decisión en lugar de arrancar de cero, que es lo que un historial de chat nunca te puede dar. Usa explore cuando el cambio es difuso. Ve directo a propose cuando no lo es.

Core te da seis comandos. Activa verify.

Un perfil decide qué slash commands instala openspec init. El default, core, tiene seis. El perfil expanded suma seis más para un control más fino.

Slash commands de OpenSpec en la 1.14

Propose es new más ff en un solo paso. Usa el par de expanded solo cuando quieras aprobar un artefacto a la vez.

Comando	Perfil	Qué hace
/opsx:explore	core	Piensa un cambio contigo. Lee código, no escribe nada
/opsx:propose	core	Crea el cambio y redacta todos los artefactos de planificación, después se detiene
/opsx:apply	core	Avanza por tasks.md en orden y marca las tareas
/opsx:update	core	Revisa los artefactos de un cambio, muestra las ediciones y espera tu OK
/opsx:sync	core	Integra el delta de un cambio en las specs principales sin archivar
/opsx:archive	core	Ofrece sincronizar y después mueve el cambio a changes/archive/
/opsx:new	expanded	Arma un cambio vacío
/opsx:continue	expanded	Escribe el siguiente artefacto listo, uno a la vez
/opsx:ff	expanded	Escribe todos los artefactos de planificación de una vez
/opsx:verify	expanded	Compara el código con el cambio: completitud, corrección, coherencia
/opsx:bulk-archive	expanded	Archiva varios cambios terminados, con detección de conflictos
/opsx:onboard	expanded	Te guía por un primer cambio en tu propia codebase

A core le falta el único paso que yo no me saltaría: /opsx:verify, el review después del código. Lee el cambio, busca en el código evidencia de cada requisito y reporta lo que no coincide, clasificado como critical, warning o suggestion. Nunca bloquea el archive. Solo hace visible el hueco, que es la mayor parte de la pelea.

Activar los comandos del perfil expanded

1. Elige los workflows

   $ openspec config profile

2. Aplícalos a este proyecto

   $ openspec update

La CLI tiene su propia lista corta que vale la pena conocer:

Comandos de la CLI de OpenSpec que de verdad vas a correr

Comando	Para qué sirve
openspec init --tools <ids>	Prepara un proyecto para uno o más agentes
openspec update	Actualiza los archivos generados después de un upgrade o de un cambio de perfil
openspec list	Cambios activos con el progreso de las tareas. También --specs y --archived
openspec show <change>	Imprime un cambio o una spec
openspec status --change <name>	Qué artefactos existen y qué sigue
openspec validate <change> --strict	Revisa el formato del delta. Ponlo en CI
openspec view	Dashboard interactivo de cambios y specs
openspec archive <change>	Archiva desde la terminal en lugar del chat
openspec schema fork spec-driven <name>	Arranca un workflow propio para tu equipo

config.yaml es donde dejas de repetirte

openspec/config.yaml reemplazó a project.md, y hace un solo trabajo: guardar las restricciones que el agente no puede inferir leyendo tu código. El archivo generado lo dice en sus propios comentarios. Tu stack y la estructura de carpetas se pueden descubrir, así que déjalos afuera. Tus reglas sobre el dinero, no.

schema: spec-driven

context: |
  Money is integer cents. No floats in any money path.
  Every operation that moves money takes an idempotency key. No exceptions.

rules:
  proposal:
    - State what is out of scope
  specs:
    - Every requirement gets a scenario for its failure path
  tasks:
    - Each task lands its own tests

El bloque context: entró en mi segundo propose y cambió su decisión. El bloque rules: funciona por artefacto, así que una regla para las tareas nunca ensucia la propuesta. Para escribir las specs en otro idioma, corre openspec init --language <language> en un proyecto nuevo, o agrega la instrucción a context:.

En una codebase existente, deja que las specs crezcan con el trabajo

OpenSpec se construyó primero para brownfield, y se nota. No documentas una app de 80.000 líneas antes de tu primer cambio. Propones el cambio que ibas a hacer esta semana, y el delta documenta la porción que toca. Mi ledger pasó de no tener specs a una capability con cinco requisitos, nacida de un cambio que igual necesitaba.

No documentes hacia atrás. Las specs escritas para código que nadie está cambiando se desactualizan, porque nada las obliga a seguir la realidad. Si ya tienes un PRD, pega la sección relevante en explore y deja que se convierta en un delta. Un solo openspec/ en la raíz cubre un monorepo. El trabajo que de verdad abarca varios repos es para lo que existen los Stores, todavía en beta.

El costo honesto: más plan que diff

Peso cada herramienta de spec en una balanza de dos platos. En uno, las líneas que alguien tiene que revisar. En el otro, lo que costaría el error que esa revisión puede atrapar. Mi corrida puso 136 líneas de plan contra 84 líneas de diff, y 67 de esas 84 son tests: el código de producción se movió 17 líneas. Solo por cantidad de líneas, este cambio quedó sobreespecificado.

El otro plato decidió. El review atrapó una clave de idempotencia opcional en un camino de dinero, y ese error cuesta más que cualquier cantidad de Markdown. OpenSpec paga cuando una decisión equivocada sale cara, y te cuesta cuando no.

→

Usa OpenSpec cuando

1. 01Una decisión equivocada cuesta más que leer un plan: dinero, auth, datos que no puedes recuperar
2. 02El cambio abarca más de una sesión, así que el plan tiene que sobrevivir al chat
3. 03Otra persona revisa o hereda el trabajo
4. 04Quieres que la razón detrás de un comportamiento siga en el repo dentro de seis meses

×

Sáltalo cuando

1. 01Un typo, un bump de versión, un timeout de una línea
2. 02Un refactor sin cambio de comportamiento. O declara skip_specs: true en el cambio
3. 03Estás haciendo un spike para aprender, no para quedártelo
4. 04El plan sería más largo que el diff y no hay nada riesgoso en él

Esa queja es real. En el hilo de Hacker News sobre el sitio nuevo de OpenSpec, en septiembre, devs cuyas empresas lo adoptaron describieron justo eso: cada cambio, mediano o más grande, se vuelve varios documentos que nadie escribió a mano, y cada uno necesita review. Otros dijeron que las specs guardadas se desfasan del código, y que el valor está en el proceso del cambio, no en el archive. En el mismo hilo hay gente que lo llama la dosis de ceremonia más sensata que probó. Los dos bandos tienen razón en algo. Mantén las propuestas cortas con una línea en rules:, revisa la propuesta y el delta en lugar de los cuatro archivos, y corre /opsx:verify antes de archivar, así las specs que guardas son las que llegaron a producción.

OpenSpec junto a Spec Kit, Superpowers y plan mode

La comparación que más me piden está en herramientas de SDD comparadas. La versión corta:

Dónde vive el plan, por herramienta

OpenSpec y Superpowers hacen trabajos distintos y se combinan bien. OpenSpec y Spec Kit hacen la misma apuesta con distinto peso.

Herramienta	Dónde vive el plan	Peso por cambio	Elígela cuando
OpenSpec	Una carpeta de cambio, integrada en las specs al archivar	Cuatro archivos, fluido	Quieres specs que sigan al sistema, con cualquier agente
Spec Kit	Una carpeta de feature bajo specs/, más una constitution	Hasta nueve pasos, siete archivos por defecto	Cada feature tiene que responder a los mismos principios
Superpowers	Un design doc y un plan para la feature en curso	Una metodología entera: TDD, subagents, review	Tu problema es la ejecución, no la intención
Claude Code plan mode	La sesión, fuera de tu repo	Ninguno	La tarea cabe en una sesión y nadie revisa el plan

El plan mode merece una línea más, porque nadie responde bien esa pregunta. El plan mode planea una sesión. OpenSpec planea un cambio y lo guarda en el repo, donde lo lee la siguiente sesión, como mi sesión de explore leyó el diseño archivado. Si la decisión tiene que sobrevivir al chat, el plan mode no es su lugar. Para el extremo más pesado, escribí una guía completa de Spec Kit.

En equipo, la spec se revisa en el pull request

Haz commit de openspec/. El archive se vuelve la historia de por qué tu sistema funciona como funciona, y la carpeta del cambio va en el mismo pull request que el código. Quienes revisan leen primero la propuesta y el delta. Si la intención está mal, se detienen antes del diff.

Ese es el momento en que una spec deja de ser el hábito de un dev y se vuelve el contrato del equipo, que es un problema aparte con sus propias formas de fallar. Escribí sobre eso en spec-driven development en equipo. Y una vez que cada cambio pasa por una spec revisada, estás a un paso de los gates de aprobación de AI-DLC, donde el review se vuelve el proceso.

Cuando el slash command no hace nada

Siete chequeos, en el orden que lo arregla más rápido

• ✓Obligatorio:
  Lo escribiste en el chat del agente, no en la terminal
• ✓Obligatorio:
  Usaste la forma que espera tu agenteCursor y OpenCode quieren /opsx-propose. Codex quiere $openspec-propose. Mira la tabla de arriba.
• ✓Obligatorio:
  Los archivos existen para ese agenteopenspec init prepara un agente nuevo. openspec update solo actualiza archivos que ya están ahí.
• ✓Obligatorio:
  Reiniciaste el agente si estaba abierto durante el init
• ✓Obligatorio:
  Corriste openspec update en cada proyecto después de actualizar el paquete
• •Opcional:
  El comando está en tu perfilverify, new, ff y onboard solo existen en el perfil expanded.
• •Opcional:
  Node es 20.19 o más nuevoRevisa con node --version y openspec --version.

Preguntas frecuentes

¿Qué es OpenSpec?+

OpenSpec es un framework de spec open source para agentes de IA para código, publicado por Fission AI bajo licencia MIT. Agrega a tu repo una capa delgada de archivos Markdown: specs que describen cómo se comporta tu sistema, y una carpeta por cada cambio propuesto con una propuesta, un delta de los requisitos, un diseño y tareas.

Instalas la CLI openspec, corres openspec init y lo manejas desde el chat de tu agente con comandos como /opsx:propose, /opsx:apply y /opsx:archive. Funciona con Claude Code, Codex, Cursor, GitHub Copilot, OpenCode, Gemini CLI y más de cuarenta agentes más.

¿OpenSpec es gratis?+

Sí. La CLI es open source bajo licencia MIT y se instala desde npm o Homebrew. Tu agente se encarga de escribir, con el modelo y el plan que ya pagas.

¿OpenSpec es un MCP server? ¿Necesita una API key?+

No a las dos. OpenSpec es una CLI más los archivos que genera para tu agente: skills y slash commands. La CLI nunca llama a un modelo. Tu agente lee las instrucciones, escribe los artefactos y le pregunta el estado a la CLI.

¿Cómo instalo OpenSpec?+

Necesitas Node 20.19 o más nuevo. Corre npm install -g @fission-ai/openspec@latest, o brew install openspec. Después, dentro de tu proyecto, corre openspec init y elige tus agentes, u openspec init --tools claude para saltarte las preguntas.

Para actualizar más adelante, actualiza el paquete y corre openspec update en cada proyecto, así las skills y los comandos generados coinciden con la versión nueva.

¿Cómo uso OpenSpec con Claude Code?+

Corre openspec init --tools claude. Escribe seis skills en .claude/skills y seis comandos en .claude/commands/opsx. En Claude Code, escribe /opsx:propose seguido de lo que quieres, lee el plan y después corre /opsx:apply y /opsx:archive.

¿Por qué /opsx:propose no funciona en Codex u OpenCode?+

Cada agente escribe el comando a su manera. Codex solo lee skills, así que escribes $openspec-propose. OpenCode, Cursor, GitHub Copilot y Pi leen archivos de comando llamados opsx-propose, así que escribes /opsx-propose. openspec init imprime la forma correcta para los agentes que elegiste.

¿Cuál es la diferencia entre /opsx:propose y /opsx:new?+

/opsx:propose crea el cambio y redacta todos los artefactos de planificación en un solo paso. /opsx:new, en el perfil expanded, solo arma un cambio vacío, y creas los artefactos uno a la vez con /opsx:continue o todos juntos con /opsx:ff. Usa propose, salvo que quieras aprobar cada artefacto por separado.

¿Tengo que correr /opsx:sync?+

Normalmente no. /opsx:archive ofrece sincronizar el delta del cambio con las specs principales antes de archivar. Corre sync por separado solo cuando quieras las specs actualizadas antes de que el cambio termine, por ejemplo en un cambio largo.

¿Tengo que hacer commit de la carpeta openspec en git?+

Sí. Las specs, los cambios activos y el archive son parte de la historia de tu proyecto. El archive es el registro de por qué existe cada comportamiento, y una carpeta de cambio va en el mismo pull request que el código que describe.

¿Cómo desinstalo OpenSpec?+

No hay comando de desinstalación. Quita el paquete con npm uninstall -g @fission-ai/openspec, y después borra el directorio openspec y los archivos generados para tus agentes, como .claude/skills/openspec-* y .claude/commands/opsx, si ya no los quieres.

OpenSpec vs Spec Kit: ¿cuál uso?+

Los dos mantienen la spec como fuente de verdad. OpenSpec es más liviano y fluido: cuatro archivos por cambio, sin fases fijas, hecho para codebases existentes. Spec Kit es más pesado y estructurado: una constitution a la que responde cada feature, hasta nueve pasos y un paso converge que compara el código con los artefactos. Los cambios chicos y frecuentes quedan más cerca de OpenSpec. Un equipo que necesita que cada feature cumpla los mismos principios queda más cerca de Spec Kit.

¿OpenSpec o el plan mode de Claude Code?+

El plan mode planea una sesión. OpenSpec planea un cambio y lo guarda en tu repo, donde alguien puede revisarlo en un pull request y la siguiente sesión puede construir sobre él. Usa plan mode para una tarea que cabe en una sentada. Usa OpenSpec cuando la decisión tiene que sobrevivir a la conversación.