Stores (beta)

Planifiez des changements qui s'étendent sur plusieurs dépôts : un seul store, plusieurs dépôts.

OpenSpec vit normalement à l'intérieur d'un seul dépôt : un dossier openspec/ à côté du code qu'il planifie. Un store déplace ce dossier dans un dépôt qui lui est propre, et plusieurs dépôts de code peuvent le partager.

Après une configuration unique sur chaque machine, des commandes comme status, new change et archive peuvent fonctionner dans le store depuis n'importe quel répertoire.

         team-plans  (a store: OpenSpec in its own repo)
         ├── .openspec-store/store.yaml   the store's name
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ set up once on each machine,
                   │ shared by pushing and cloning like any repo
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(code repo)   (code repo)    (code repo)

Vous partagez un store avec git, de la même manière que vous partagez du code : commitez, poussez, tirez et relisez-le vous-même. Les specs et les changements obtiennent des branches et des pull requests de la même façon que le code.

Quand en utiliser un

Deux raisons courantes d'utiliser un store :

• Frontend et backend dans des dépôts séparés : une fonctionnalité touche les deux, et le plan a besoin d'un lieu unique plutôt que de deux moitiés.

        shop-plans  (store)
        └── openspec/changes/add-discounts/    one plan for the feature
                  ▲
        ┌─────────┴─────────┐
        │                   │
    storefront             api
  (frontend repo)     (backend repo)

• Un produit, plusieurs dépôts clients : Android, iOS et web sont livrés depuis leurs propres dépôts mais partagent un comportement attendu unique. Une spec décrit un comportement, pas une implémentation, donc une seule spec sert les trois.

          product-specs  (store)
          └── openspec/specs/checkout/spec.md    the expected behavior
                    ▲
      ┌─────────────┼─────────────┐
      │             │             │
  android-app    ios-app       web-app
  (code repo)   (code repo)   (code repo)

Vous pouvez avoir plus d'un store, bien que nous recommandions de garder leur nombre faible.

Configurer un store

Une personne crée le store, puis tout le monde le rejoint.

1. Créer le store (une personne, une fois par équipe). Exécutez openspec store setup et répondez aux invites :

   # run from anywhere; it asks what to create and where
   openspec store setup

   Il pose trois questions :

   • Store name : team-plans
   • Where should this store live? : pré-rempli avec ~/openspec/<name>, appuyez sur Entrée pour accepter ou saisissez un autre chemin
   • Create this store? : affiche ce qu'il s'apprête à créer, répondez Yes

   Ensuite, il indique ce qu'il a créé :

   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. Publiez-le sur votre hébergeur Git. Créez d'abord un dépôt team-plans vide sur votre hébergeur. Le setup n'ajoute pas de remote Git, connectez donc le store à ce dépôt, puis poussez :

   # connect the store to the empty repo on your git host
   cd ~/openspec/team-plans
   git remote add origin git@github.com:acme/team-plans.git
   
   # publish it
   git push -u origin main

3. Rejoindre le store (chaque membre de l'équipe, une fois par machine) :

   # get the store onto your machine
   git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
   
   # tell OpenSpec where it lives
   openspec store register ~/openspec/team-plans

   Store registered: team-plans
   Location: /Users/you/openspec/team-plans
   OpenSpec root: ready
   Registry: registered

   L'enregistrement indique à votre machine où se trouve ce store. Le nom du store est déjà committé à l'intérieur, dans .openspec-store/store.yaml. Le setup a enregistré la copie du créateur, donc seules les copies clonées nécessitent cette étape.

4. Confirmez que cela fonctionne, depuis n'importe quel répertoire :

   # any OpenSpec command reaches the store by name
   openspec status --store team-plans

   Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
   No active changes. Create one with: openspec new change <name> --store team-plans

Types de configurations

OpenSpec propose trois configurations. Le reste de cette page utilise ces noms :

• repo-local : OpenSpec dans votre dépôt, sans store. La configuration par défaut.
• store-only : votre dépôt ne conserve aucun specs ni changements propres. Tout se trouve dans le store.
• store-optional : votre projet possède son propre dossier openspec/ et accède également à un store sur demande.

Par défaut : OpenSpec dans votre dépôt (repo-local)

openspec init place un dossier openspec/ à côté de votre code, et les specs et changements de ce dépôt y résident. Aucun store n'est impliqué. C'est la configuration qu'enseigne Configurez votre projet, et la plupart des projets n'en nécessitent pas d'autre.

web-app  (code repo)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec hors de votre dépôt, dans un store (store-only)

Le dépôt ne conserve aucun specs ni changements propres. Tout ce qu'il planifie réside dans le store, et une ligne dans la configuration du dépôt relie les deux.

Fréquent quand une équipe construit tous les dépôts et les planifie au même endroit. Les exemples ci-dessus ont tous cette forme.

team-plans  (store)
└── openspec/
    ├── specs/       the repo's specs live here
    └── changes/     its changes too
          ▲
          │ store: team-plans   (the connecting line)
web-app  (code repo)
└── openspec/
    └── config.yaml    nothing else

OpenSpec dans votre dépôt et dans un store (store-optional)

Le dépôt reste repo-local pour son propre travail, tandis que le store conserve les specs et changements partagés. À l'intérieur du dépôt, OpenSpec utilise le dossier openspec/ de votre projet et n'accède au store que lorsque vous passez --store.

Fréquent quand un dépôt utilisait OpenSpec avant l'existence du store, ou quand un dépôt quasi indépendant ne touche que ponctuellement au travail partagé.

team-plans  (store)
└── openspec/          the shared specs and changes
          ▲
          │ only when you pass --store team-plans
web-app  (code repo)
└── openspec/          this repo's own
    ├── config.yaml
    ├── specs/
    └── changes/

Un dépôt peut démarrer en repo-local et déplacer ses specs et changements vers le store ultérieurement. Déplacer les specs et changements d'un dépôt vers le store explique comment procéder.

Où les artefacts sont créés lors de l'utilisation de stores

Quand vous utilisez un store, OpenSpec doit également décider où les artefacts sont créés. Cela dépend de votre configuration :

• store-only (votre projet n'écrit que dans le store) : chaque artefact est créé dans le store. La ligne store: ci-dessous l'enregistre.
• store-optional (votre projet possède son propre dossier openspec/ et utilise également un store) : les artefacts sont créés dans votre projet, sauf si vous nommez le store dans votre demande ou passez --store pour ce changement. Votre agent propage alors le flag à travers le reste du workflow.

OpenSpec écrit les artefacts dans l'un des deux emplacements : le dossier openspec/ de votre projet ou celui du store. Il choisit dans cet ordre, et la première option applicable l'emporte :

1. --store <id> sur une commande. Toujours prioritaire, depuis n'importe quel répertoire.
2. Le dossier openspec/ de votre projet. Si votre projet possède ses propres dossiers specs/ ou changes/, OpenSpec les utilise.
3. La ligne store: dans votre projet. La façon dont un projet store-only enregistre son store.
4. defaultStore sur votre machine. Le repli quand aucune des options ci-dessus ne s'applique.

Si aucune de ces options ne s'applique et que vous avez des stores enregistrés, la commande échoue et les liste. Lorsqu'un store a un id correspondant au nom de votre dépôt dans son remote origin, l'erreur mentionne ce store et la ligne store: qui le sélectionne. OpenSpec ne choisit jamais un store par nom de lui-même, car des dépôts dans différentes organisations peuvent partager un nom.

Quand OpenSpec sélectionne un store, il affiche Using OpenSpec root: ... avant le résultat de la commande.

La ligne store: (projets store-only)

Ajoutez une ligne à votre openspec/config.yaml de projet :

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

Tout ce que vous ou votre agent exécutez dans votre projet utilise désormais le store, sans flag à saisir :

# inside web-app, connected
openspec status

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans

• Sans la ligne : exécutez une commande simple dans un projet store-only et OpenSpec s'arrête avec une erreur listant vos stores enregistrés.
• Commitez-la : les coéquipiers qui clonent votre projet obtiennent également la ligne. Ils doivent néanmoins avoir le store enregistré sur leur machine (étape 3 de Configurer un store), sinon OpenSpec génère une erreur leur demandant de l'enregistrer.
• À côté de dossiers réels : si votre projet possède également des dossiers specs/ ou changes/, OpenSpec les utilise et ignore la ligne, avec un avertissement.

Installer des intégrations dans un dépôt store-only

Exécutez init depuis la racine du dépôt de code pour installer les fichiers d'intégration d'outils IA sans rapatrier la planification dans ce dépôt :

# inside web-app, at the repository root
openspec init --tools claude

• Fichiers d'intégration : écrits dans le dépôt de code.
• openspec/config.yaml : préservé octet par octet, y compris la ligne store:.
• openspec/specs/ et openspec/changes/ : non créés dans le dépôt de code.

OpenSpec refuse cette commande depuis un sous-répertoire du dépôt de code. Exécutez-la depuis la racine du dépôt.

OpenSpec refuse également --language ici car la langue appartient à la configuration du store externe. Exécutez init à la racine du store ou éditez directement cette configuration.

defaultStore sur votre machine

Définissez-le une fois si chaque projet avec lequel vous travaillez utilise le même store. OpenSpec y recourt quand il ne trouve ni flag, ni dossier openspec/ local, ni ligne store: :

# use team-plans whenever nothing else names a store
openspec config set defaultStore team-plans

# undo it
openspec config unset defaultStore

Commandes qui restent locales. init, update, templates, schemas et les sous-commandes openspec schema agissent uniquement sur le répertoire courant et n'acceptent pas --store.

Déplacer les specs et changements d'un dépôt vers le store

Pour faire passer un dépôt de repo-local à store-only :

1. Déplacez tout le contenu des dossiers openspec/specs/ et openspec/changes/ du dépôt vers les mêmes dossiers dans le store.
2. Supprimez les dossiers désormais vides, de sorte que le dossier openspec/ du dépôt ne contienne plus que config.yaml.
3. Ajoutez la ligne store: à ce config.yaml.

openspec status dans le dépôt commence maintenant par Using OpenSpec root: team-plans.

Travailler dans le store

Les workflows ne changent pas, pour vous ni pour votre agent. Propose, apply et archive fonctionnent comme toujours. La seule différence réside dans l'emplacement de création des artefacts, et la section ci-dessus couvre ce sujet.

Créez un changement depuis un dépôt store-only et il atterrit dans le store :

# inside web-app; the store: line routes this to team-plans
openspec new change add-login

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

• Où il est allé : dans le dépôt du store, pas à côté de votre code.
• Le partager : le changement n'existe que dans votre checkout jusqu'à ce que vous committiez et poussiez le dépôt du store. Les coéquipiers le voient quand ils tirent. Il en va de même pour chaque artefact que les workflows écrivent.
• Chemins dans la documentation : partout où la documentation montre un chemin openspec/, dans une configuration store ce dossier est celui du store.

Quand des artefacts sont créés à un endroit inattendu, openspec doctor vérifie votre configuration sans rien modifier et affiche une correction pour chaque constat :

# check the current root and its stores
openspec doctor

Doctor

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

References
  (none declared)

openspec context liste la racine et les stores avec lesquels votre répertoire courant travaille, quand vous souhaitez la même vue sans les vérifications.

Pour ouvrir le store et un dépôt dans une seule fenêtre d'éditeur, afin que votre agent puisse lire les deux, consultez Worksets (beta).

Lire les specs d'un autre store

Votre repo peut conserver son propre dossier openspec/ et permettre à votre agent de lire les specs d'un autre store. Déclarez ce store sous references: dans le fichier openspec/config.yaml du repo :

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

Les références sont en lecture seule. Votre travail reste dans votre repo, et la référence ne fait que modifier ce qui est communiqué à votre agent.

Lorsqu'un workflow crée un artefact, ses instructions reçoivent un index des specs du store référencé, chacune avec un résumé en une ligne et la commande exacte pour la récupérer :

<referenced_stores>
<!-- Read-only upstream context. Fetch what you need; cite what you use. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Rules for charging and refunding customers.
  Fetch: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Une référence peut également contenir l'URL de clone du store, pour les machines qui ne disposent pas encore de ce store :

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

Avec l'URL déclarée, openspec doctor transforme un store manquant en une solution à copier-coller :

# output wrapped to fit
References
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Referenced store 'design-system' is not registered on this machine.
    Fix: 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

Limites de la bêta

• La forme peut changer : les noms de commandes, les drapeaux et les formats de fichiers peuvent changer entre les versions. Relisez cette page après une mise à niveau.
• Pas de synchronisation, par conception : OpenSpec ne clone jamais, ne tire pas (pull) et ne pousse pas (push). Un checkout obsolète affiche des specs obsolètes jusqu'à ce que vous fassiez un pull, et les références sont lues depuis ce qui se trouve sur le disque.
• Un checkout par nom de store : l'enregistrement d'un deuxième dossier sous un nom déjà enregistré échoue, avec une indication pour exécuter d'abord openspec store unregister.