OpenSpec

Store (beta) ​

Pianifica modifiche che attraversano più repository: uno store, molti repo.

OpenSpec normalmente vive all'interno di un singolo repo: una cartella openspec/ accanto al codice che pianifica. Uno store sposta quella cartella in un repository dedicato, e più repo di codice possono condividerlo.

Dopo una configurazione iniziale su ogni macchina, comandi come status, new change e archive possono operare nello store da qualsiasi directory.

         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)

Condividi uno store con git, allo stesso modo in cui condividi il codice: commit, push, pull e revisione da parte tua. Spec e modifiche ricevono branch e pull request nello stesso modo del codice.

Quando ti serve ​

Due ragioni comuni per usare uno store:

  • Frontend e backend in repo separati: una funzionalità tocca entrambi, e il piano ha bisogno di un'unica sede invece di due metà.

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

  • Un prodotto, più repo client: Android, iOS e web vengono rilasciati dai propri repo ma condividono un comportamento atteso. Una spec descrive il comportamento, non l'implementazione, quindi una singola spec serve tutti e tre.

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

Puoi avere più di uno store, anche se consigliamo di mantenerne un numero basso.

Configurare uno store ​

Una persona crea lo store, poi tutti gli altri vi si uniscono.

  1. Crea lo store (una persona, una volta per team). Esegui openspec store setup e rispondi ai prompt:

    bash
    # eseguilo da qualsiasi posizione; chiede cosa creare e dove
openspec store setup

    Chiede tre domande:

    • Nome dello store: team-plans
    • Dove deve risiedere questo store?: precompilato con ~/openspec/<name>, premi Invio per accettarlo o digita un altro percorso
    • Creare questo store?: mostra cosa sta per creare, rispondi Yes

    Poi riporta ciò che ha creato:

    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. Esegui il push verso il tuo host Git. Crea prima un repository team-plans vuoto sul tuo host. Il setup non aggiunge un remote Git, quindi collega lo store a quel repository, poi esegui il push:

    bash
    # collega lo store al repository vuoto sul tuo host Git
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# pubblicalo
git push -u origin main

  3. Unisciti allo store (ogni membro del team, una volta per macchina):

    bash
    # porta lo store sulla tua macchina
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# indica a OpenSpec dove risiede
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    La registrazione indica alla tua macchina dove risiede questo store. Il nome dello store è già incluso nel repository, in .openspec-store/store.yaml. Il setup ha registrato la copia del creatore, quindi solo le copie clonate necessitano di questo passaggio.

  4. Verifica che abbia funzionato, da qualsiasi directory:

    bash
    # qualsiasi comando OpenSpec raggiunge lo store tramite il nome
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

Tipi di configurazione ​

OpenSpec prevede tre configurazioni. Il resto di questa pagina usa questi nomi:

  • repo-local: OpenSpec all'interno del tuo repository, senza store. La configurazione predefinita.
  • store-only: il tuo repository non mantiene specifiche né modifiche proprie. Tutto risiede nello store.
  • store-optional: il tuo progetto ha una propria cartella openspec/ e raggiunge anche uno store quando lo richiedi.

La configurazione predefinita: OpenSpec all'interno del tuo repository (repo-local) ​

openspec init inserisce una cartella openspec/ accanto al tuo codice, e le specifiche e le modifiche di quel repository risiedono lì. Nessuno store è coinvolto. È la configurazione illustrata in Configura il tuo progetto, e la maggior parte dei progetti non ne richiede mai un'altra.

web-app  (repository del codice)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec all'esterno del tuo repository, in uno store (store-only) ​

Il repository non mantiene specifiche né modifiche proprie. Tutto ciò che pianifica risiede nello store, e una riga nella configurazione del repository collega i due.

Comune quando un team sviluppa tutti i repository e pianifica in un unico posto. Gli esempi sopra hanno tutti questa struttura.

team-plans  (store)
└── openspec/
    ├── specs/       le specifiche del repository risiedono qui
    └── changes/     anche le sue modifiche
          ▲
          │ store: team-plans   (la riga di collegamento)
web-app  (repository del codice)
└── openspec/
    └── config.yaml    nient'altro

OpenSpec nel tuo repository e in uno store (store-optional) ​

Il repository resta repo-local per il proprio lavoro, mentre lo store contiene le specifiche e le modifiche condivise. All'interno del repository, OpenSpec usa la cartella openspec/ del tuo progetto e raggiunge lo store solo quando passi --store.

Comune quando un repository usava OpenSpec prima che lo store esistesse, o quando un repository in gran parte indipendente tocca solo occasionalmente il lavoro condiviso.

team-plans  (store)
└── openspec/          le specifiche e le modifiche condivise
          ▲
          │ solo quando passi --store team-plans
web-app  (repository del codice)
└── openspec/          quella del repository stesso
    ├── config.yaml
    ├── specs/
    └── changes/

Un repository può iniziare come repo-local e spostare in seguito le proprie specifiche e modifiche nello store. Spostare le specifiche e le modifiche di un repository nello store mostra come fare.

Dove vengono creati gli artefatti quando si usano gli store ​

Quando usi uno store, OpenSpec deve anche decidere dove vengono creati gli artefatti. Dipende dalla tua configurazione:

  • store-only (il tuo progetto scrive solo nello store): ogni artefatto viene creato nello store. La riga store: qui sotto lo registra.
  • store-optional (il tuo progetto ha una propria cartella openspec/ e usa anche uno store): gli artefatti vengono creati nel tuo progetto, a meno che tu non nomini lo store nella tua richiesta o non passi --store per quella modifica. Il tuo agente poi mantiene il flag per il resto del flusso di lavoro.

OpenSpec scrive gli artefatti in uno di due posti: nella cartella openspec/ del tuo progetto o in quella dello store. Sceglie in questo ordine, e prevale la prima opzione applicabile:

  1. --store <id> in un comando. Prevale sempre, da qualsiasi directory.
  2. La cartella openspec/ del tuo progetto. Se il tuo progetto ha cartelle specs/ o changes/ proprie, OpenSpec le usa.
  3. La riga store: nel tuo progetto. È così che un progetto store-only registra il proprio store.
  4. defaultStore sulla tua macchina. Il fallback quando nessuna delle opzioni precedenti si applica.

Se nessuna di queste si applica e hai store registrati, il comando fallisce e li elenca. Quando l'id di uno store corrisponde al nome del tuo repository nel suo remote origin, l'errore nomina quello store e la riga store: che lo seleziona. OpenSpec non sceglie mai uno store per nome da solo, perché repository in organizzazioni diverse possono condividere un nome.

Quando OpenSpec seleziona uno store, stampa Using OpenSpec root: ... prima dell'output del comando.

La riga store: (progetti store-only) ​

Aggiungi una riga al file openspec/config.yaml del tuo progetto:

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

Tutto ciò che tu o il tuo agente eseguite all'interno del tuo progetto ora usa lo store, senza digitare alcun flag:

bash
# all'interno di web-app, connesso
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
  • Senza la riga: esegui un comando semplice in un progetto store-only e OpenSpec si ferma con un errore che elenca i tuoi store registrati.
  • Fai il commit: i membri del team che clonano il tuo progetto ricevono anche la riga. Devono comunque registrare lo store sulla loro macchina (passaggio 3 di Configurare uno store), altrimenti OpenSpec restituisce un errore e dice loro di registrarlo.
  • Accanto a cartelle reali: se il tuo progetto ha anche cartelle specs/ o changes/, OpenSpec usa quelle e ignora la riga, con un avviso.

Installare le integrazioni in un repository store-only ​

Esegui init dalla radice del repository del codice per installare i file di integrazione per gli strumenti AI senza riportare la pianificazione in quel repository:

bash
# all'interno di web-app, alla radice del repository
openspec init --tools claude
  • File di integrazione: scritti nel repository del codice.
  • openspec/config.yaml: conservato byte per byte, inclusa la riga store:.
  • openspec/specs/ e openspec/changes/: non creati nel repository del codice.

OpenSpec rifiuta questo comando da una sottodirectory del repository del codice. Eseguilo dalla radice del repository.

OpenSpec rifiuta anche --language qui perché la lingua appartiene alla configurazione dello store esterno. Esegui init nella radice dello store o modifica direttamente quella configurazione.

defaultStore sulla tua macchina ​

Impostalo una volta se ogni progetto in cui lavori usa lo stesso store. OpenSpec vi ricorre quando non trova alcun flag, nessuna cartella openspec/ locale e nessuna riga store::

bash
# usa team-plans quando nient'altro indica uno store
openspec config set defaultStore team-plans

# annullalo
openspec config unset defaultStore

Comandi che restano locali. init, update, templates, schemas e i sottocomandi di openspec schema agiscono solo sulla directory corrente e non accettano --store.

Spostare le specifiche e le modifiche di un repository nello store ​

Per portare un repository da repo-local a store-only:

  1. Sposta tutto il contenuto di openspec/specs/ e openspec/changes/ del repository nelle stesse cartelle nello store.
  2. Elimina le cartelle ormai vuote, in modo che la cartella openspec/ del repository contenga solo config.yaml.
  3. Aggiungi la riga store: a quel config.yaml.

openspec status all'interno del repository ora inizia con Using OpenSpec root: team-plans.

Lavorare nello store ​

I flussi di lavoro non cambiano, né per te né per il tuo agente. Proponi, applica e archivia funzionano come hanno sempre fatto. L'unica differenza è dove vengono creati gli artefatti, e la sezione sopra tratta questo aspetto.

Crea una modifica dall'interno di un repository store-only e questa finisce nello store:

bash
# all'interno di web-app; la riga store: indirizza questo comando 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
  • Dove è stata creata: nel repository dello store, non accanto al tuo codice.
  • Condividerla: la modifica esiste solo nel tuo checkout finché non esegui il commit e il push del repository dello store. I membri del team la vedono quando eseguono pull. Lo stesso vale per ogni artefatto scritto dai flussi di lavoro.
  • Percorsi nella documentazione: ovunque la documentazione mostri un percorso openspec/, in una configurazione con store quella cartella è quella dello store.

Quando gli artefatti vengono creati in un posto che non ti aspettavi, openspec doctor controlla la tua configurazione senza modificare nulla e stampa una correzione per ogni problema rilevato:

bash
# controlla la root corrente e i suoi store
openspec doctor
yaml
Doctor

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

References
  (none declared)

openspec context elenca la root e gli store con cui lavora la tua directory corrente, quando vuoi lo stesso quadro senza i controlli.

Per aprire lo store e un repository in un'unica finestra dell'editor, in modo che il tuo agente possa leggere entrambi, vedi Worksets (beta).

Leggere le specifiche da un altro store ​

Il tuo repository può mantenere la propria cartella openspec/ e comunque consentire al tuo agent di leggere le specifiche di un altro store. Dichiara tale store sotto references: nel file openspec/config.yaml del repository:

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

I riferimenti sono di sola lettura. Il tuo lavoro rimane nel tuo repository e il riferimento cambia solo ciò che viene comunicato al tuo agent.

Quando un workflow crea un artefatto, le sue istruzioni ottengono un indice delle specifiche dello store di riferimento, ciascuna con un riassunto di una riga e il comando esatto per recuperarla:

xml
<referenced_stores>
<!-- Contesto upstream di sola lettura. Recupera ciò di cui hai bisogno; cita ciò che usi. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Regole per l'addebito e il rimborso dei clienti.
  Recupera: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Un riferimento può anche contenere l'URL di clone dello store, per le macchine che non hanno ancora tale store:

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

Con l'URL dichiarato, openspec doctor trasforma uno store mancante in una correzione che puoi incollare:

yaml
# output a capo per adattarsi
Riferimenti
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Lo store di riferimento 'design-system' non è registrato su questa macchina.
    Correzione: 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

Limiti della beta ​

  • La forma può cambiare: i nomi dei comandi, i flag e i formati dei file possono cambiare tra le release. Rileggi questa pagina dopo l'aggiornamento.
  • Nessuna sincronizzazione, per scelta progettuale: OpenSpec non clona, non esegue pull né push. Un checkout non aggiornato mostra specifiche non aggiornate finché non esegui il pull, e i riferimenti vengono letti da ciò che si trova su disco.
  • Un checkout per nome di store: registrare una seconda cartella con un nome già registrato fallisce, con un suggerimento per eseguire prima openspec store unregister.