Bèta. Stores, verwijzingen, werkcontext en worksets zijn nieuw. Opdrachtnamen, vlaggen, bestandsformaten en JSON-uitvoer kunnen nog van vorm veranderen tussen releases. Elke walkthrough hieronder is uitgevoerd tegen de huidige build, maar lees deze gids opnieuw na een upgrade.

Het probleem dat dit oplost

OpenSpec leeft normaal gesproken in één code-repo: een openspec/ map naast je code, met daarin specificaties en wijzigingen voor die repo.

Dat past niet meer zodra je planning groter is dan één repo:

• Je werk beslaat meerdere repo's — één feature raakt de API-server, de web-app en een gedeelde bibliotheek. In wiens openspec/ map komt het plan te staan?
• Je team plant voordat er code is, of plant dingen die nooit code worden in deze repo.
• Vereisten zijn eigendom van één team en worden door anderen gebruikt. De wiki-versie loopt uit de pas, en je coding agent kan die toch niet lezen.

Een store is de oplossing: een op zichzelf staande repo waarvan de hele taak plannen is. Het heeft dezelfde openspec/ opzet die je al kent — specificaties en wijzigingen — plus een klein identiteitsbestand. Je registreert het eenmalig op je machine, op naam, en dan kan elk normaal OpenSpec commando erin werken, waar je ook bent.

De structuur

            team-plans  (een store: planning in een eigen repo)
            ├── .openspec-store/store.yaml     identiteit: "I am team-plans"
            └── openspec/
                ├── specs/      wat waar is
                └── changes/    wat in beweging is
                      ▲
                      │ geregistreerd op elke machine met naam;
                      │ gedeeld door pushen/clonen zoals elke repo
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (code repo)   (code repo)    (code repo)

Twee regels houden dit eenvoudig:

1. Een store is gewoon een git-repo. Je commit, push, pull en reviewt het zelf. OpenSpec clone, sync of push nooit iets zelfstandig.
2. Declaraties, geen mechanismen. Repos kunnen declareren hoe ze zich verhouden tot stores (zie hieronder). Declaraties veranderen wat OpenSpec je kan vertellen — nooit waar je commando's werken.

Vijf minuten naar je eerste store

Twee commando's brengen je van niets naar een werkende, store-gerelateerde wijziging:

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

Store ready: team-plans
Location: /Users/you/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.

openspec new change add-login --store team-plans

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

Dat is het hele model. Vanaf hier is de levenscyclus precies wat je kent — status, instructions, validate, archive — met --store team-plans bij elk commando, en elke weergegeven hint draagt de vlag voor je mee. De Using OpenSpec root: regel vertelt je altijd waar een commando werkt.

Verhaal: één team, één planning-repo

Een team bewaart zijn specificaties en wijzigingen in team-plans in plaats van ze te verspreiden over code-repos.

Dag één (wie het ook opzet):

openspec store setup team-plans --path ~/openspec/team-plans \
  --remote git@github.com:acme/team-plans.git
git -C ~/openspec/team-plans push -u origin main

Het doorgeven van --remote registreert de clone-URL in het eigen identiteitsbestand van de store (.openspec-store/store.yaml), in de initiële commit. Elke toekomstige clone komt ter wereld met kennis van waar hij vandaan komt, zodat gezondheidscontroles en foutmeldingen een volledige, plakbare oplossing kunnen tonen voor teamleden die het nog niet hebben.

Elke teammaat (een keer per machine):

git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
openspec store register ~/openspec/team-plans

Vanaf dan werkt iedereen in dezelfde planning-repo met naam:

openspec status --store team-plans --change add-login
openspec show add-login --store team-plans

Werk delen is git, bewust. Een wijziging die je aanmaakt bestaat alleen in je checkout totdat je hem commit en push — net als code. Plannen krijgen gratis branches, pull requests en review, omdat een store een gewone repo is.

De code-repos van het team verbinden. Een code-repo waarvan de planning volledig geëxternaliseerd is, heeft precies één regel nodig, in openspec/config.yaml:

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

Nu werkt elk OpenSpec-commando dat binnen web-app wordt uitgevoerd op team-plans zonder enige vlag:

cd ~/src/web-app
openspec status --change add-login

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
...

De pointer is een terugval, nooit een override: een expliciete --store wint altijd, en als de repo eigen echte planning-mappen krijgt, winnen die (met een waarschuwing om de verouderde pointer te verwijderen).

Eén standaard voor elke repo op je machine. Als je werkt met veel code-repos die allemaal plannen in dezelfde store, stel het dan één keer globaal in, in plaats van de store: regel aan elke repo toe te voegen:

openspec config set defaultStore team-plans

Nu lost elk commando dat buiten een planning-root wordt uitgevoerd — en zonder --store en zonder project-pointer — op naar team-plans. Het staat onderaan de prioriteitslijst, dus --store, een lokale root en een project store: pointer winnen allemaal nog steeds. De root-banner en het JSON root blok rapporteren source: "global_default" met de store-id, dus je kunt altijd een machinebrede standaard onderscheiden van een eigen pointer van een repo. Wis het met openspec config unset defaultStore. Als de id niet geregistreerd is, geven commando's een foutmelding en zeggen ze je om hem te registreren of de verouderde standaard te wissen.

Voorbeeld: één functie, twee component-repos

Stel dat add-checkout-promo zowel checkout-api als checkout-web wijzigt. Het team wil één gedeeld productcontract, terwijl elke code-repo nog steeds zijn eigen implementatie-taken, branch en review nodig heeft.

Gebruik twee lagen:

1. Bewaar het gedeelde gedrag in team-plans.
2. Bewaar implementatieplannen in elk component-repo en verwijz naar de store als alleen-lezen upstream-context.

Plan eerst het gedeelde contract in de store:

openspec new change add-checkout-promo --store team-plans
openspec status --change add-checkout-promo --store team-plans

Het voorstel en de specificaties moeten het gedrag beschrijven aan de grens tussen de componenten — bijvoorbeeld de promotievelden die door de service worden teruggegeven en hoe de frontend een ongeschikte checkout verwerkt. Review deze wijziging in de store-repo zoals elke andere branch en pull request.

Welke context ziet planning?

Het selecteren van een store verandert de OpenSpec-root; het ontdekt of leest niet elke code-repo die die store gebruikt. Store-instructies zien de artefacten en geconfigureerde context in de store. Ze zien componentcode alleen wanneer die mappen ook beschikbaar zijn voor de agent of editor en de agent ze leest.

Een workset is een handige manier om de planning-store en beide code-repos samen te openen:

openspec workset create checkout-promo \
  --member ~/openspec/team-plans \
  --member ~/src/checkout-api \
  --member ~/src/checkout-web \
  --tool code
openspec workset open checkout-promo

Dit maakt de mappen zichtbaar in één IDE-workspace. Het kopieert geen broncode-context naar de store, selecteert niet de getroffen repos en verleent een agent geen machtiging om ze te bewerken. Plaats duurzame cross-component feiten in de gedeelde specificaties; vertrouw niet op een planner die toevallig geïnspecteerde broncode onthoudt.

Hoe begint implementatie in elk repo?

Wanneer geen expliciete --store of dichterbij liggende openspec/ root van toepassing is, routeert een store: team-plans pointer commando's naar die store. Het splitst niet één store-taaklijst op basis van de map waaruit apply werd aangeroepen. OpenSpec routeert momenteel geen taken naar repos.

Wanneer elk component een onafhankelijk scope-gerelateerde apply/review cyclus nodig heeft, geef het een lokale OpenSpec-root en verwijz naar de centrale store in plaats van er naar te wijzen:

# checkout-api/openspec/config.yaml (en zo ook in checkout-web)
schema: spec-driven
references:
  - team-plans

Na het goedkeuren van het gedeelde contract en beschikbaar zijn in de hoofdspecificaties van de store, maak een kleine lokale wijziging voor het deel van het component:

cd ~/src/checkout-api
openspec new change implement-checkout-promo-api

cd ~/src/checkout-web
openspec new change implement-checkout-promo-ui

De referentie-index in de instructies van elk repo levert de samenvatting van de store-specificatie en het exacte openspec show ... --store team-plans ophaalcommando. Elk lokaal voorstel citeert dat gedeelde contract en zijn taken beschrijven alleen werk in dat component. Voer daarna /opsx:apply in elk repo afzonderlijk uit; root-resolutie houdt de artefacten en implementatiebewerkingen binnen die repo. De service- en frontend-wijzigingen kunnen nu onafhankelijk worden getest, gereviewd, samengevoegd en gearcheiveerd.

Als implementatie moet beginnen terwijl de gedeelde store-wijziging nog actief is, haal het expliciet op met openspec show add-checkout-promo --store team-plans; referentie-indexen lijsten canonieke store-specificaties, niet actieve store-wijzigingen. Houd de store-branch en component-branches gekoppeld in hun pull-request-beschrijvingen zodat reviewers kunnen zien welke versie van het contract elke implementatie volgt.

Verhaal: vereisten die teamgrenzen overschrijden

Een platformteam bezit de vereisten. Productteams bouwen erop, in hun eigen repos, met hun eigen ontwerpen. Een referentie beschrijft die relatie zonder iemand's werk te verplaatsen.

   platform-reqs (store)                 api-server (code repo)
   bezeten door het platformteam         bezeten door een productteam
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ leest    │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (hun eigen ontwerpen)  │
   │   platform werk          │          │ openspec/changes/        │
   │                          │          │   (hun eigen werk)       │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

Het productteam declareert waar het gebruik van maakt in het openspec/config.yaml van zijn repo:

references:
  - platform-reqs

Referenties zijn alleen-lezen context. De repo behoudt zijn eigen openspec/ root; werk blijft daar. Wat verandert: openspec instructions in die repo bevat nu een index van de specificaties van de gerefereerde store — elk met een regel samenvatting en het exacte ophaalcommando (openspec show <spec-id> --type spec --store platform-reqs). Een agent die werkt in api-server kan de upstream-betalingvereisten vinden, ze citeren en zijn laag-niveau ontwerp schrijven in de eigen root van de repo — zonder dat iemand context hoeft te plakken.

Een referentie kan zijn clone-bron dragen, zodat teamleden die de store nog niet hebben een volledige oplossing krijgen in plaats van een dood uiteinde:

references:
  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }

Wanneer je plan en code samen wilt openen, maak dan een workset. Dit is persoonlijk en expliciet: elke persoon kiest de mappen waarmee hij daadwerkelijk werkt op zijn machine. Niets over die lokale checkout-paden wordt ge-commit naar de gedeelde planning-repo.

openspec workset create platform \
  --member ~/openspec/platform-reqs \
  --member ~/src/api-server \
  --member ~/src/web-app

Twee vragen die je altijd kunt stellen

"Is mijn opstelling gezond?" — openspec doctor controleert de huidige root en zijn gerefereerde stores, alleen-lezen, met een plakbare oplossing per bevinding:

Doctor

Root
  Location: /Users/you/src/api-server
  OpenSpec root: ok

References
  - platform-reqs: ok (/Users/you/openspec/platform-reqs)
  - 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

"Waarmee werk ik?" — openspec context assembleert de werkset uit OpenSpec-declaraties: de root en de stores die hij refereert.

Working context for api-server (/Users/you/src/api-server)

OpenSpec root
  api-server  /Users/you/src/api-server

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

Beide ondersteunen --json voor agents. openspec context --code-workspace <path> schrijft additioneel een VS Code workspace-bestand dat de hele set bevat — de enige schrijfactie die dit commando uitvoert.

Worksets: heropen de mappen die je samen gebruikt

Los van al het bovenstaande: de meeste mensen openen elke sessie dezelfde paar mappen samen — de planning-repo plus twee of drie code-repo's. Een workset is een persoonlijk, benoemd overzicht daarvan, dat met één commando in je favoriete tool opnieuw wordt geopend.

  workset "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       alle drie geopend in je tool

openspec workset create platform \
  --member ~/openspec/team-plans --member ~/src/api-server \
  --tool code
openspec workset list

platform  (opent in VS Code)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

openspec workset open platform start dan de opgeslagen tool: editors (VS Code, Cursor) openen één venster met alle leden en keren terug. Het eerste lid is de primaire. Overschrijf de tool op elk moment met --tool <id>.

Worksets zijn bewust geen gedeelde toestand. Ze bevinden zich op je machine, worden nooit gecommit en doen geen uitspraken over het werk — ze leggen alleen vast wat je graag samen geopend wilt hebben. Het verwijderen van een workset raakt de mappen van de leden nooit. Nieuwe tools zijn configuratie, geen code: alles wat via een workspace-bestand of per-map hechtvlaggen wordt gestart, kan worden toegevoegd onder de openers-sleutel in de globale configuratie (openspec config edit).

Hoe commando's bepalen waar ze handelen

Elke normale opdracht bepaalt zijn root op dezelfde manier, in deze volgorde:

1. --store <id>          je hebt het expliciet gezegd       → die store
2. nearest openspec/     een echte planning-root hier       → deze repo
   (omhoog lopen vanaf de huidige werkmap)
3. store: pointer        config.yaml declareert een store   → die store
4. defaultStore          globale configuratie stelt een     → die store
                         machine-standaard in
5. geen van bovenstaande zijn stores geregistreerd op deze  → fout met een
                         machine?                            selectiehint
                         zijn geen stores geregistreerd?    → de huidige
                                                               map
                                                               (klassiek gedrag)

De regel Using OpenSpec root: (en het root-blok in de --json-uitvoer) vertelt je in welk geval je zit.

Bekende beperkingen

• Beta-vorm. Alles op deze pagina kan tussen releases veranderen — namen, vlaggen, bestandsformaten, JSON-sleutels.
• Eén checkout per store-id per machine. Het registreren van een tweede checkout onder dezelfde id mislukt met een hint om eerst store unregister uit te voeren.
• Geen synchronisatie, nooit — per ontwerp. OpenSpec kloont, pullt of pusht nooit. Een verouderde checkout toont verouderde specificaties totdat jij pullt; verwijzingen worden live geïndexeerd van wat er op schijf staat.
• Lege planningsmappen kunnen ontbreken. Een nieuwe store heeft mogelijk nog geen openspec/changes/, openspec/specs/ of openspec/changes/archive/ in Git. Dat wordt tijdens de bèta geaccepteerd; die mappen verschijnen zodra normale commando's er bestanden voor aanmaken.
• Pointer-repo's blijven pointers. Een configuratie-alleen repo waarvan openspec/config.yaml store: <id> declareert, wordt behandeld als externe planning, niet als een store-checkout om te registreren. Verwijder eerst de store:-regel als je die repo opzettelijk in een lokale store-root wilt omzetten.
• Sommige commando's blijven waar ze zijn. templates en de verouderde zelfstandig-naamwoorden-vormen (openspec change show, ...) werken alleen op de huidige map — geen --store. schemas volgt de canonieke root-selectieprioriteit en accepteert --store <id> terwijl de succesvolle JSON-arrayvorm ongewijzigd blijft.
• Per-machine toestand is per-machine. De store-registry en worksets zijn lokale instellingen. Niets van de indeling van jouw machine wordt ooit gecommit naar gedeelde planning.
• Twee startstijlen voor worksets. Een tool die niet kan worden gestart met een workspace-bestand of per-map hechtvlaggen, kan niet als opener worden toegevoegd.
• Agent JSON heeft een bekende hoofdletter-splitsing (store-familiesleutels zijn snake_case, workflow-familie camelCase). Gedocumenteerd in het agent contract; het uniformeren ervan is uitgesteld tot een versie-release.

Waar dingen leven

Wat	Waar	Gedeeld?
De planning van een store	<store>/openspec/ (specs, changes)	Ja — commit en push het
De identiteit van een store	<store>/.openspec-store/store.yaml	Ja — gecommit met de store
De store-registry	<data dir>/openspec/stores/registry.yaml	Nee — alleen deze machine
Worksets	<data dir>/openspec/worksets/	Nee — alleen deze machine

<data dir> is ~/.local/share/openspec op macOS en Linux (of $XDG_DATA_HOME/openspec indien ingesteld), en %LOCALAPPDATA%\openspec op Windows.

Referentie

Exacte vlaggen en JSON-vormen voor elk commando op deze pagina: CLI-referentie (Stores, Doctor, Working context, Personal worksets) en het agent contract.