OpenSpec

Stores (beta) ​

Planifica cambios que abarcan repositorios: un store, muchos repos.

OpenSpec normalmente vive dentro de un repo: una carpeta openspec/ junto al código que planifica. Un store mueve esa carpeta a un repositorio propio, y varios repos de código pueden compartirlo.

Después de una configuración inicial en cada máquina, comandos como status, new change y archive pueden funcionar en el store desde cualquier directorio.

         team-plans  (un store: OpenSpec en su propio repo)
         ├── .openspec-store/store.yaml   el nombre del store
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ se configura una vez en cada máquina,
                   │ se comparte con push y clone como cualquier repo
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(repo de código) (repo de código) (repo de código)

Compartes un store con git, de la misma manera que compartes código: commit, push, pull y revísalo tú mismo. Las specs y los changes obtienen branches y pull requests de la misma manera que el código.

Cuándo necesitas uno ​

Dos razones comunes para usar un store:

  • Frontend y backend en repos separados: una funcionalidad afecta a ambos, y el plan necesita un solo hogar en lugar de dos mitades.

          shop-plans  (store)
      └── openspec/changes/add-discounts/    un plan para la funcionalidad
                ▲
      ┌─────────┴─────────┐
      │                   │
  storefront             api
(repo frontend)     (repo backend)

  • Un producto, varios repos de cliente: Android, iOS y web se despliegan desde sus propios repos pero comparten un comportamiento esperado. Una spec describe comportamiento, no implementación, por lo que una spec sirve para los tres.

            product-specs  (store)
        └── openspec/specs/checkout/spec.md    el comportamiento esperado
                  ▲
    ┌─────────────┼─────────────┐
    │             │             │
android-app    ios-app       web-app
(repo de código) (repo de código) (repo de código)

Puedes tener más de un store, aunque recomendamos mantener la cantidad baja.

Configurar un almacén ​

Una persona crea el almacén, luego todos los demás se unen a él.

  1. Crear el almacén (una persona, una vez por equipo). Ejecuta openspec store setup y responde las preguntas:

    bash
    # ejecutar desde cualquier lugar; pregunta qué crear y dónde
openspec store setup

    Pregunta tres cosas:

    • Nombre del almacén: team-plans
    • ¿Dónde debe vivir este almacén?: pre-rellenado con ~/openspec/<name>, presiona Enter para aceptarlo o escribe otra ruta
    • ¿Crear este almacén?: muestra lo que está a punto de crear, responde Sí

    Luego informa lo que creó:

    yaml
    Store ready: team-plans
Location: ~/openspec/team-plans
OpenSpec root: ready
Registry: registered

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

  2. Publícalo en tu hosting de git. Crea primero un repositorio team-plans vacío en tu hosting. La configuración no añade un remoto git, así que conecta el almacén a ese repositorio, luego publica:

    bash
    # conectar el almacén al repositorio vacío en tu hosting de git
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# publicarlo
git push -u origin main

  3. Unirse al almacén (cada compañero de equipo, una vez por máquina):

    bash
    # obtener el almacén en tu máquina
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# indicar a OpenSpec dónde vive
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    Registrar le indica a tu máquina dónde vive este almacén. El nombre del almacén ya está confirmado dentro de él, en .openspec-store/store.yaml. La configuración registró la copia del creador, así que solo las copias clonadas necesitan este paso.

  4. Confirmar que funcionó, desde cualquier directorio:

    bash
    # cualquier comando de OpenSpec llega al almacén por su nombre
openspec status --store team-plans
    yaml
    Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans

Tipos de configuraciones ​

OpenSpec tiene tres configuraciones. El resto de esta página usa estos nombres:

  • repo-local: OpenSpec dentro de tu repositorio, sin almacén. El predeterminado.
  • store-only: tu repositorio no guarda specs ni cambios propios. Todo vive en el almacén.
  • store-optional: tu proyecto tiene su propia carpeta openspec/ y también accede a un almacén cuando lo solicitas.

El predeterminado: OpenSpec dentro de tu repositorio (repo-local) ​

openspec init coloca una carpeta openspec/ junto a tu código, y las specs y cambios de ese repositorio viven allí. No hay almacén involucrado. Esta es la configuración que enseña Configurar tu proyecto, y la mayoría de los proyectos nunca necesitan otra.

web-app  (repositorio de código)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec fuera de tu repositorio, en un almacén (store-only) ​

El repositorio no guarda specs ni cambios propios. Todo lo que planifica vive en el almacén, y una línea en la configuración del repositorio conecta ambos.

Común cuando un equipo construye todos los repositorios y planea en un solo lugar. Los ejemplos anteriores tienen esta forma.

team-plans  (almacén)
└── openspec/
    ├── specs/       las specs del repositorio viven aquí
    └── changes/     sus cambios también
          ▲
          │ store: team-plans   (la línea de conexión)
web-app  (repositorio de código)
└── openspec/
    └── config.yaml    nada más

OpenSpec en tu repositorio y en un almacén (store-optional) ​

El repositorio permanece repo-local para su propio trabajo, mientras el almacén guarda las specs y cambios compartidos. Dentro del repositorio, OpenSpec usa la carpeta openspec/ de tu proyecto, y accede al almacén solo cuando pasas --store.

Común cuando un repositorio usaba OpenSpec antes de que existiera el almacén, o cuando un repositorio mayormente independiente solo ocasionalmente toca trabajo compartido.

team-plans  (almacén)
└── openspec/          las specs y cambios compartidos
          ▲
          │ solo cuando pasas --store team-plans
web-app  (repositorio de código)
└── openspec/          lo propio de este repositorio
    ├── config.yaml
    ├── specs/
    └── changes/

Un repositorio puede empezar repo-local y mover sus specs y cambios al almacén después. Mover las specs y cambios de un repositorio al almacén muestra cómo.

Dónde se crean los artefactos al usar almacenes ​

Cuando usas un almacén, OpenSpec también tiene que decidir dónde se crean los artefactos. Depende de tu configuración:

  • store-only (tu proyecto solo escribe en el almacén): cada artefacto se crea en el almacén. La línea store: de abajo registra eso.
  • store-optional (tu proyecto tiene su propia carpeta openspec/ y también usa un almacén): los artefactos se crean en tu proyecto, a menos que nombres el almacén en tu solicitud o pases --store para ese cambio. Tu agente entonces lleva el flag a través del resto del flujo de trabajo.

OpenSpec escribe los artefactos en uno de dos lugares: la carpeta openspec/ de tu proyecto, o la del almacén. Elige en este orden, y la primera opción que aplica gana:

  1. --store <id> en un comando. Siempre gana, desde cualquier directorio.
  2. La carpeta openspec/ de tu proyecto. Si tu proyecto tiene sus propias carpetas specs/ o changes/, OpenSpec las usa.
  3. La línea store: en tu proyecto. Cómo un proyecto store-only registra su almacén.
  4. defaultStore en tu máquina. El respaldo cuando ninguna de las anteriores aplica.

Si ninguna de estas aplica y tienes almacenes registrados, el comando falla y los lista. Cuando el id de un almacén coincide con el nombre de tu repositorio en su remoto origin, el error nombra ese almacén y la línea store: que lo selecciona. OpenSpec nunca elige un almacén por nombre por su cuenta, porque repositorios en diferentes organizaciones pueden compartir un nombre.

Cuando OpenSpec selecciona un almacén, imprime Using OpenSpec root: ... antes de la salida del comando.

La línea store: (proyectos store-only) ​

Añade una línea a openspec/config.yaml de tu proyecto:

yaml
# web-app/openspec/config.yaml
store: team-plans

Todo lo que tú o tu agente ejecuten dentro de tu proyecto ahora usa el almacén, sin flag que escribir:

bash
# dentro de web-app, conectado
openspec status
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans
  • Sin la línea: ejecuta un comando simple en un proyecto store-only y OpenSpec se detiene con un error listando tus almacenes registrados.
  • Confírmalo: los compañeros de equipo que clonan tu proyecto obtienen la línea también. Todavía necesitan el almacén registrado en su máquina (paso 3 de Configurar un almacén), o OpenSpec arroja error y les dice que lo registren.
  • Junto a carpetas reales: si tu proyecto también tiene carpetas specs/ o changes/, OpenSpec las usa e ignora la línea, con una advertencia.

Instalar integraciones en un repositorio store-only ​

Ejecuta init desde la raíz del repositorio de código para instalar archivos de integración de herramientas de IA sin devolver la planificación a ese repositorio:

bash
# dentro de web-app, en la raíz del repositorio
openspec init --tools claude
  • Archivos de integración: escritos en el repositorio de código.
  • openspec/config.yaml: preservado byte a byte, incluyendo la línea store:.
  • openspec/specs/ y openspec/changes/: no se crean en el repositorio de código.

OpenSpec rechaza este comando desde un subdirectorio del repositorio de código. Ejecútalo desde la raíz del repositorio.

OpenSpec también rechaza --language aquí 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.

defaultStore en tu máquina ​

Configúralo una vez si cada proyecto en el que trabajas usa el mismo almacén. OpenSpec recurre a él cuando no encuentra flag, ni carpeta openspec/ local, ni línea store::

bash
# usar team-plans cuando nada más nombra un almacén
openspec config set defaultStore team-plans

# deshacerlo
openspec config unset defaultStore

Comandos que permanecen locales. init, update, templates, schemas, y los subcomandos de openspec schema actúan solo en el directorio actual y no toman --store.

Mover las specs y cambios de un repositorio al almacén ​

Para llevar un repositorio de repo-local a store-only:

  1. Mueve todo lo que está en openspec/specs/ y openspec/changes/ del repositorio a las mismas carpetas en el almacén.
  2. Elimina las carpetas ahora vacías, para que la carpeta openspec/ del repositorio contenga solo config.yaml.
  3. Añade la línea store: a ese config.yaml.

openspec status dentro del repositorio ahora comienza con Using OpenSpec root: team-plans.

Trabajar en el almacén ​

Los flujos de trabajo no cambian, ni para ti ni para tu agente. Proponer, aplicar y archivar funcionan como siempre. La única diferencia es dónde se crean los artefactos, y la sección anterior lo cubre.

Crea un cambio desde dentro de un repositorio store-only y cae en el almacén:

bash
# dentro de web-app; la línea store: enruta esto a team-plans
openspec new change add-login
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
Schema: spec-driven
Next: openspec status --change add-login --store team-plans
  • Dónde fue: al repositorio del almacén, no junto a tu código.
  • Compartirlo: el cambio existe solo en tu copia de trabajo hasta que confirmas y publicas el repositorio del almacén. Los compañeros de equipo lo ven cuando descargan. Lo mismo aplica para cada artefacto que los flujos de trabajo escriben.
  • Rutas en los documentos: donde sea que los documentos muestren una ruta openspec/, en una configuración de almacén esa carpeta es la del almacén.

Cuando los artefactos se crean en un lugar que no esperabas, openspec doctor verifica tu configuración sin cambiar nada e imprime una corrección para cada hallazgo:

bash
# verificar la raíz actual y sus almacenes
openspec doctor
yaml
Doctor

Root
  Location: /Users/you/openspec/team-plans
  OpenSpec root: ok
  Store: team-plans (metadata ok)

References
  (none declared)

openspec context lista la raíz y los almacenes con los que trabaja tu directorio actual, cuando quieres la misma imagen sin las verificaciones.

Para abrir el almacén y un repositorio en una ventana del editor, para que tu agente pueda leer ambos, consulta Worksets (beta).

Leer especificaciones de otro almacén ​

Tu repositorio puede mantener su propia carpeta openspec/ y aun así permitir que tu agente lea las especificaciones de otro almacén. Declara ese almacén en references: dentro del openspec/config.yaml del repositorio:

yaml
# api-server/openspec/config.yaml
references:
  - team-plans

Las referencias son de solo lectura. Tu trabajo permanece en tu repositorio, y la referencia solo cambia lo que se le indica a tu agente.

Cuando un flujo de trabajo crea un artefacto, sus instrucciones obtienen un índice de las especificaciones del almacén referenciado, cada una con un resumen de una línea y el comando exacto para obtenerla:

xml
<referenced_stores>
<!-- Contexto upstream de solo lectura. Obtén lo que necesites; cita lo que uses. -->
Almacén team-plans (/Users/you/openspec/team-plans):
  - payments: Reglas para cobrar y reembolsar a los clientes.
  Obtener: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Una referencia también puede incluir la URL de clonación del almacén, para máquinas que todavía no tienen ese almacén:

yaml
references:
  - team-plans
  - { id: design-system, remote: "git@github.com:acme/design-system.git" }

Con la URL declarada, openspec doctor convierte un almacén ausente en una solución lista para pegar:

yaml
# salida ajustada para que quepa
Referencias
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: El almacén referenciado 'design-system' no está registrado en esta máquina.
    Solución: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' &&
         openspec store register '/Users/you/openspec/design-system' --id design-system

Límites de la versión beta ​

  • La estructura puede cambiar: los nombres de los comandos, las opciones y los formatos de archivo pueden cambiar entre versiones. Vuelve a leer esta página después de actualizar.
  • Sin sincronización, por diseño: OpenSpec nunca clona, ni hace pull, ni hace push. Una copia de trabajo desactualizada muestra especificaciones desactualizadas hasta que hagas pull, y las referencias se leen de lo que haya en el disco.
  • Una copia de trabajo por nombre de almacén: registrar una segunda carpeta con un nombre que ya está registrado produce un error, con una indicación de ejecutar openspec store unregister primero.