OpenSpec

Winkels (beta) ​

Planwijzigingen die zich over repositories uitstrekken: één winkel, vele repos.

OpenSpec bevindt zich normaal gesproken binnen één repo: een openspec/-map naast de code die het plant. Een winkel verplaatst deze map naar een eigen repository, waardoor meerdere code-repos deze kunnen delen.

Na eenmalige installatie op elke machine kunnen commando's zoals status, new change en archive vanuit elke directory in de winkel worden uitgevoerd.

         team-plans  (een winkel: OpenSpec in zijn eigen repo)
         ├── .openspec-store/store.yaml   de naam van de winkel
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ eenmalig instellen op elke machine,
                   │ gedeeld door te pushen en clonen zoals bij elke repo
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(code repo)   (code repo)    (code repo)

Je deelt een winkel via git, op dezelfde manier als je code deelt: commit, push, pull en review jezelf. Specs en wijzigingen krijgen takken en pull requests op exact dezelfde manier als code.

Wanneer je er één nodig hebt ​

Twee veelvoorkomende redenen om een winkel te gebruiken:

  • Frontend en backend in aparte repos: één functie raakt beide, en het plan heeft één centrale locatie nodig in plaats van twee losse helften.

          shop-plans  (winkel)
      └── openspec/changes/add-discounts/    één plan voor de functie
                ▲
      ┌─────────┴─────────┐
      │                   │
  storefront             api
(frontend repo)     (backend repo)

  • Één product, meerdere client-repos: Android, iOS en web worden vanuit hun eigen repos uitgebracht, maar delen hetzelfde verwachte gedrag. Een spec beschrijft gedrag, niet implementatie, dus één spec is voldoende voor alle drie.

            product-specs  (winkel)
        └── openspec/specs/checkout/spec.md    het verwachte gedrag
                  ▲
    ┌─────────────┼─────────────┐
    │             │             │
android-app    ios-app       web-app
(code repo)   (code repo)   (code repo)

Het is mogelijk om meer dan één winkel te hebben, hoewel we aanraden het aantal laag te houden.

Een winkel instellen ​

Eén persoon maakt de winkel aan, waarna iedereen anders zich aansluit.

  1. De winkel aanmaken (één persoon, één keer per team). Voer openspec store setup uit en beantwoord de vragen:

    bash
    # uitvoeren vanaf elke locatie; het vraagt wat er aangemaakt moet worden en waar
openspec store setup

    Het stelt drie vragen:

    • Winkelnaam: team-plans
    • Waar moet deze winkel komen?: vooraf ingevuld met ~/openspec/<name>, druk op Enter om dit te accepteren of typ een ander pad
    • Deze winkel aanmaken?: toont wat er gemaakt gaat worden, antwoord Yes

    Daarna wordt gerapporteerd wat er is aangemaakt:

    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. Pushen naar je git-host. Maak eerst een lege team-plans-repo aan op je host. Setup voegt geen git-remote toe, dus koppel de winkel aan die repo en push vervolgens:

    bash
    # koppel de winkel aan de lege repo op je git-host
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# publiceer het
git push -u origin main

  3. De winkel betreden (elke teamlid, één keer per machine):

    bash
    # haal de winkel naar je machine
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# vertel OpenSpec waar hij zit
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    Registreren vertelt je machine waar deze winkel zich bevindt. De naam van de winkel staat al vastgelegd in .openspec-store/store.yaml. Setup registreerde de kopie van de maker, dus alleen gekloonde kopieën hebben deze stap nodig.

  4. Bevestig dat het werkt, vanaf elke directory:

    bash
    # elke OpenSpec-opdracht bereikt de winkel op naam
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

Soorten setups ​

OpenSpec heeft drie setups. De rest van deze pagina gebruikt deze namen:

  • repo-local: OpenSpec binnen je repo, zonder winkel. De standaardinstelling.
  • store-only: je repo houdt geen eigen specificaties of wijzigingen bij. Alles leeft in de winkel.
  • store-optional: je project heeft zijn eigen openspec/-map en raadpleegt ook een winkel wanneer je daarom vraagt.

De standaard: OpenSpec binnen je repo (repo-local) ​

openspec init plaatst een openspec/-map naast je code, en de specificaties en wijzigingen van die repo leven daar. Er is geen winkel bij betrokken. Dit is de setup die Je project instellen leert, en de meeste projecten hebben nooit iets anders nodig.

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

OpenSpec buiten je repo, in een winkel (store-only) ​

De repo houdt geen eigen specificaties of wijzigingen bij. Alles wat het plant, leeft in de winkel, en één regel in de configuratie van de repo verbindt de twee.

Veelvoorkomend wanneer één team alle repos en plannen op één plek bouwt. De voorbeelden hierboven hebben allemaal deze vorm.

team-plans  (store)
└── openspec/
    ├── specs/       de specificaties van de repo leven hier
    └── changes/     ook zijn wijzigingen
          ▲
          │ store: team-plans   (de verbindingsregel)
web-app  (code repo)
└── openspec/
    └── config.yaml    niets anders

OpenSpec in je repo en in een winkel (store-optional) ​

De repo blijft repo-lokaal voor zijn eigen werk, terwijl de winkel de gedeelde specificaties en wijzigingen bevat. Binnen de repo gebruikt OpenSpec de openspec/-map van je project en raakt de winkel alleen aan wanneer je --store doorgeeft.

Veelvoorkomend wanneer een repo OpenSpec gebruikte voordat de winkel bestond, of wanneer een grotendeels onafhankelijke repo slechts af en toe shared work aanraakt.

team-plans  (store)
└── openspec/          de gedeelde specificaties en wijzigingen
          ▲
          │ alleen wanneer je --store team-plans doorgeeft
web-app  (code repo)
└── openspec/          dit eigen van de repo
    ├── config.yaml
    ├── specs/
    └── changes/

Een repo kan beginnen als repo-lokaal en later zijn specificaties en wijzigingen naar de winkel verplaatsen. Specificaties en wijzigingen van een repo naar de winkel verplaatsen laat zien hoe.

Waar artefacten worden aangemaakt bij het gebruik van winkels ​

Wanneer je een winkel gebruikt, moet OpenSpec ook beslissen waar de artefacten worden aangemaakt. Dit hangt af van je setup:

  • store-only (je project schrijft alleen naar de winkel): elk artefact wordt in de winkel aangemaakt. De store:-regel hieronder registreert dat.
  • store-optional (je project heeft zijn eigen openspec/-map en gebruikt ook een winkel): artefacten worden in je project aangemaakt, tenzij je de winkel noemt in je verzoek of --store doorgeeft voor die wijziging. Je agent draagt vervolgens het vlaggetje door tijdens de rest van de workflow.

OpenSpec schrijft artefacten naar een van twee plaatsen: de openspec/-map van je project, of die van de winkel. Het kiest in deze volgorde, en de eerste optie die van toepassing is wint:

  1. --store <id> op een opdracht. Wint altijd, vanaf elke directory.
  2. De openspec/-map van je project. Als je project zijn eigen specs/- of changes/-mappen heeft, gebruikt OpenSpec die.
  3. De store:-regel in je project. Hoe een store-only-project zijn winkel registreert.
  4. defaultStore op je machine. De fallback wanneer geen van bovenstaande van toepassing is.

Als geen van deze van toepassing is en je geregistreerde winkels hebt, faalt de opdracht en geeft ze ze weer. Wanneer de id van één winkel overeenkomt met de naam van je repo in zijn origin-remote, noemt de foutmelding die winkel en de store:-regel die hem selecteert. OpenSpec kiest nooit zelfstandig een winkel op basis van de naam, omdat repos in verschillende organisaties dezelfde naam kunnen delen.

Wanneer OpenSpec een winkel selecteert, drukt het Using OpenSpec root: ... uit voordat de opdrachtoutput volgt.

De store:-regel (store-only-projecten) ​

Voeg één regel toe aan de openspec/config.yaml van je project:

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

Alles wat jij of je agent binnen je project uitvoert, gebruikt nu de winkel, zonder dat je een vlaggetje hoeft in te typen:

bash
# binnen web-app, verbonden
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
  • Zonder de regel: voer een gewone opdracht uit in een store-only-project en stopt OpenSpec met een foutmelding die je geregistreerde winkels opsomt.
  • Commit het: teamleden die je project klonen, krijgen de regel ook. Ze moeten de winkel nog steeds registreren op hun machine (stap 3 van Een winkel instellen), anders geeft OpenSpec een fout en vertelt hen deze te registreren.
  • Naast echte mappen: als je project ook specs/- of changes/-mappen heeft, gebruikt OpenSpec die en negeert de regel, met een waarschuwing.

Integraties installeren in een store-only-repo ​

Voer init uit vanuit de root van de code-repo om AI-tool-integratiebestanden te installeren zonder planning terug naar die repo te verplaatsen:

bash
# binnen web-app, op de repository-root
openspec init --tools claude
  • Integratiebestanden: geschreven in de code-repo.
  • openspec/config.yaml: behouden byte-voor-byte, inclusief de store:-regel.
  • openspec/specs/ en openspec/changes/: niet aangemaakt in de code-repo.

OpenSpec weigert deze opdracht vanuit een subdirectory van de code-repo. Voer hem uit vanaf de repository-root.

OpenSpec weigert ook --language hier omdat de taal thuishoort in de configuratie van de externe winkel. Voer init uit in de winkel-root of bewerk die configuratie direct.

defaultStore op je machine ​

Stel dit één keer in als elk project waarin je werkt dezelfde winkel gebruikt. OpenSpec valt terug op deze instelling wanneer het geen vlag, geen lokale openspec/-map en geen store:-regel vindt:

bash
# gebruik team-plans wanneer niets anders een winkel noemt
openspec config set defaultStore team-plans

# ongedaan maken
openspec config unset defaultStore

Opdrachten die lokaal blijven. init, update, templates, schemas en de openspec schema-subopdrachten werken alleen op de huidige directory en nemen geen --store.

Specificaties en wijzigingen van een repo naar de winkel verplaatsen ​

Om een repo van repo-lokaal naar store-only te brengen:

  1. Verplaats alles in de openspec/specs/- en openspec/changes/-mappen van de repo naar dezelfde mappen in de winkel.
  2. Verwijder de nu lege mappen, zodat de openspec/-map van de repo alleen config.yaml bevat.
  3. Voeg de store:-regel toe aan die config.yaml.

openspec status binnen de repo begint nu met Using OpenSpec root: team-plans.

Werken in de winkel ​

De workflows veranderen niet, voor jou of voor je agent. Voorstellen, toepassen en archiveren lopen zoals altijd. Het enige verschil is waar de artefacten worden aangemaakt, en het bovenstaande gedeelte behandelt dat.

Maak een wijziging aan vanuit een store-only-repo en deze belandt in de winkel:

bash
# binnen web-app; de store: regel routeert dit naar 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
  • Waar het terechtkwam: in de winkel-repo, niet naast je code.
  • Delen ervan: de wijziging bestaat alleen in je checkout tot je de winkel-repo commit en pusht. Teamleden zien het wanneer zij pullen. Dezelfde geldt voor elk artefact dat de workflows schrijven.
  • Paden in de documentatie: overal waar de documentatie een openspec/-pad tonen, is in een winkel-setup die map de winkel.

Wanneer artefacten ergens worden aangemaakt waar je niet verwachtte, controleert openspec doctor je setup zonder iets te wijzigen en drukt het een oplossing af voor elke bevinding:

bash
# controleer de huidige root en zijn winkels
openspec doctor
yaml
Doctor

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

References
  (none declared)

openspec context somt de root en winkels op waarmee je huidige directory werkt, wanneer je hetzelfde overzicht wilt zonder de controles.

Om de winkel en een repo in één editorvenster te openen, zodat je agent beide kan lezen, zie Worksets (beta).

Specificaties uit een andere store lezen ​

Je repo kan zijn eigen openspec/-map behouden en je agent toch specificaties uit een andere store laten lezen. Geef die store op onder references: in de openspec/config.yaml van de repo:

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

Referenties zijn alleen-lezen. Je werk blijft in je repo en de referentie verandert alleen wat aan je agent wordt verteld.

Wanneer een workflow een artefact aanmaakt, worden de instructies ervan aangevuld met een index van de specificaties van de store waarnaar wordt verwezen, met voor elke specificatie een samenvatting van één regel en het exacte commando om die op te halen:

xml
<referenced_stores>
<!-- Alleen-lezen upstream-context. Haal op wat je nodig hebt; citeer wat je gebruikt. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Regels voor het in rekening brengen en terugbetalen van klanten.
  Ophalen: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Een referentie kan ook de clone-URL van de store bevatten, voor machines die die store nog niet hebben:

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

Als de URL is opgegeven, maakt openspec doctor van een ontbrekende store een oplossing die je kunt plakken:

yaml
# uitvoer afgebroken om te passen
Referenties
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: De store 'design-system' waarnaar wordt verwezen, is niet geregistreerd op deze machine.
    Oplossing: 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

Bèta-beperkingen ​

  • De vorm kan veranderen: namen van commando's, flags en bestandsformaten kunnen tussen releases veranderen. Lees deze pagina opnieuw na het upgraden.
  • Geen synchronisatie, bewust zo bedoeld: OpenSpec kloont, pullt of pusht nooit. Een verouderde checkout toont verouderde specificaties totdat je een pull uitvoert, en referenties worden gelezen uit wat er op schijf staat.
  • Eén checkout per storenaam: het registreren van een tweede map onder een naam die al is geregistreerd, mislukt, met de aanwijzing om eerst openspec store unregister uit te voeren.