OpenSpec

Stores: Planung in einem eigenen Repository ​

Beta. Stores, Referenzen, Arbeitskontexte und Worksets sind neu. Befehlsnamen, Flags, Dateiformate und JSON-Ausgaben können sich zwischen den Releases noch ändern. Jeder unten stehende Durchlauf wurde mit der aktuellen Build-Version durchgeführt, aber lesen Sie diese Anleitung nach einem Upgrade bitte erneut durch.

Das Problem, das dadurch gelöst wird ​

OpenSpec lebt normalerweise innerhalb eines einzigen Code-Repositories: Ein openspec/-Ordner neben Ihrem Code, der Spezifikationen und Änderungen für dieses Repository enthält.

Dies passt nicht mehr, sobald Ihre Planungen über ein einzelnes Repository hinausgehen:

  • Ihre Arbeit erstreckt sich über mehrere Repositories – eine Funktion betrifft beispielsweise den API-Server, die Webanwendung und eine gemeinsam genutzte Bibliothek. In welchem openspec/-Ordner sollte die Planung liegen?
  • Ihr Team plant vor dem Existieren von Code oder plant Dinge, die in diesem Repository niemals zu Code werden.
  • Anforderungen werden von einem Team erstellt und von anderen konsumiert. Die Wiki-Version weicht auseinander, und Ihr Coding-Agent kann sie ohnehin nicht lesen.

Ein Store ist die Lösung: ein eigenständiges Repository, dessen einzige Aufgabe die Planung ist. Es hat dieselbe openspec/-Struktur, die Sie bereits kennen – Spezifikationen und Änderungen – sowie eine kleine Identitätsdatei. Sie registrieren es einmalig auf Ihrer Maschine bei Namen, und anschließend können alle normalen OpenSpec-Befehle von überall darauf zugreifen.

Die Struktur ​

            team-plans  (a store: planning in its own repo)
            ├── .openspec-store/store.yaml     identity: "I am team-plans"
            └── openspec/
                ├── specs/      what is true
                └── changes/    what is in motion
                      ▲
                      │ registered on each machine by name;
                      │ shared by pushing/cloning like any repo
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (code repo)   (code repo)    (code repo)

Zwei Regeln halten dies einfach:

  1. Ein Store ist einfach ein Git-Repo. Du committest, pushst, pullst und reviewst es selbst. OpenSpec klont, synchronisiert oder pusht niemals etwas von selbst.
  2. Deklarationen, keine Maschinerie. Repos können deklarieren, wie sie zu Stores stehen (weiter unten gezeigt). Deklarationen ändern, was OpenSpec dir sagen kann — niemals, wo deine Befehle agieren.

Fünf Minuten bis zu deinem ersten Store ​

Zwei Befehle bringen dich von null zu einem funktionierenden, Store-skopierten Change:

bash
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.
bash
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

Das ist das gesamte Modell. Ab hier ist der Lebenszyklus genau das, was du kennst — status, instructions, validate, archive — mit --store team-plans auf jedem Befehl, und jeder ausgegebene Hinweis trägt das Flag für dich. Die Zeile Using OpenSpec root: sagt dir immer, wo ein Befehl wirkt.

Story: ein Team, ein Planungs-Repo ​

Ein Team hält seine Specs und Changes in team-plans, anstatt sie über Code-Repos zu verstreuen.

Tag eins (wer auch immer es einrichtet):

bash
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

Die Übergabe von --remote zeichnet die Clone-URL in der Identitätsdatei des Stores selbst (.openspec-store/store.yaml) im initialen Commit auf. Jeder zukünftige Clone weiß von Geburt an, woher er kommt, sodass Health-Checks und Fehlermeldungen einen vollständigen, einfügbaren Fix für Teammitglieder drucken können, die ihn noch nicht haben.

Jedes Teammitglied (einmal pro Maschine):

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

Von da an arbeitet jeder im selben Planungs-Repo per Name:

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

Das Teilen von Arbeit ist git, absichtlich. Ein Change, den du erstellst, existiert nur in deinem Checkout, bis du ihn committest und pushst — genau wie Code. Pläne erhalten Branches, Pull Requests und Review kostenlos, weil ein Store ein gewöhnliches Repo ist.

Einbinden der Code-Repos des Teams. Ein Code-Repo, dessen Planung vollständig externalisiert ist, benötigt genau eine Zeile in openspec/config.yaml:

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

Jetzt wirkt jeder OpenSpec-Befehl, der innerhalb von web-app ausgeführt wird, auf team-plans, ganz ohne Flags:

bash
cd ~/src/web-app
openspec status --change add-login
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
...

Der Zeiger ist ein Fallback, niemals ein Override: eine explizite --store-Angabe gewinnt immer, und wenn das Repo eigene echte Planungsordner erhält, gewinnen diese (mit einer Warnung, den veralteten Zeiger zu entfernen).

Eine Standardeinstellung für jedes Repo auf deiner Maschine. Wenn du über viele Code-Repos hinweg arbeitest, die alle in denselben Store planen, setze es einmal global, anstatt die store:-Zeile jedem Repo hinzuzufügen:

bash
openspec config set defaultStore team-plans

Jetzt löst jeder Befehl, der außerhalb eines Planungs-Roots ausgeführt wird — und ohne --store und ohne Projekt-Zeiger — zu team-plans auf. Es sitzt am Ende der Prioritätsliste, sodass --store, ein lokaler Root und ein Projekt-store:-Zeiger weiterhin gewinnen. Das Root-Banner und der JSON-root-Block melden source: "global_default" mit der Store-ID, sodass du immer ein maschinenweites Standard von einem eigenen Zeiger des Repos unterscheiden kannst. Entferne es mit openspec config unset defaultStore. Wenn die ID nicht registriert ist, geben Befehle einen Fehler aus und sagen dir, sie zu registrieren oder das veraltete Standard zu entfernen.

Beispiel: ein Feature, zwei Komponenten-Repos ​

Angenommen, add-checkout-promo ändert sowohl checkout-api als auch checkout-web. Das Team möchte einen gemeinsamen Produktvertrag, während jedes Code-Repo weiterhin seine eigenen Implementierungsaufgaben, seinen eigenen Branch und sein eigenes Review benötigt.

Verwende zwei Ebenen:

  1. Halte das gemeinsame Verhalten in team-plans.
  2. Halte Implementierungspläne in jedem Komponenten-Repo und referenziere den Store als schreibgeschützten Upstream-Kontext.

Zuerst plane den gemeinsamen Vertrag im Store:

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

Der Vorschlag und die Specs sollten das Verhalten an der Grenze zwischen den Komponenten beschreiben — zum Beispiel die Promotionsfelder, die der Service zurückgibt, und wie das Frontend einen nicht berechtigten Checkout behandelt. Review diesen Change im Store-Repo wie jeden anderen Branch und Pull Request.

Welchen Kontext sieht die Planung? ​

Die Auswahl eines Stores ändert den OpenSpec-Root; er entdeckt oder liest nicht jedes Code-Repo, das diesen Store verwendet. Store-Anweisungen sehen die Artefakte und den konfigurierten Kontext im Store. Sie sehen Komponentencode nur, wenn diese Ordner auch für den Agenten oder Editor verfügbar sind und der Agent sie liest.

Ein Workset ist eine bequeme Möglichkeit, den Planungs-Store und beide Code-Repos zusammen zu öffnen:

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

Dies macht die Ordner in einem IDE-Workspace sichtbar. Es kopiert keinen Quellkontext in den Store, wählt keine betroffenen Repos aus und gewährt einem Agenten keine Erlaubnis, sie zu bearbeiten. Lege dauerhafte komponentenübergreifende Fakten in die gemeinsamen Specs; verlasse dich nicht darauf, dass ein Planer sich an Quellcode erinnert, den er zufällig inspiziert hat.

Wie beginnt die Implementierung in jedem Repo? ​

Wenn keine explizite --store-Angabe oder ein näherer openspec/-Root zutrifft, leitet ein store: team-plans-Zeiger Befehle zu diesem Store. Er teilt keine Store-Aufgabenliste nach dem Verzeichnis, aus dem apply aufgerufen wurde. OpenSpec leitet derzeit keine Aufgaben an Repos weiter.

Wenn jede Komponente einen unabhängig skopierten Apply-/Review-Zyklus benötigt, gib ihr einen lokalen OpenSpec-Root und referenziere den zentralen Store, anstatt auf ihn zu zeigen:

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

Nachdem der gemeinsame Vertrag genehmigt und in den Haupt-Specs des Stores verfügbar ist, erstelle einen kleinen lokalen Change für den Teil der Komponente:

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

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

Der Referenzindex in den Anweisungen jedes Repos liefert die Zusammenfassung der Store-Spec und den genauen Abrufbefehl openspec show ... --store team-plans. Jeder lokale Vorschlag zitiert diesen gemeinsamen Vertrag, und seine Aufgaben beschreiben nur die Arbeit in dieser Komponente. Dann führe /opsx:apply in jedem Repo separat aus; die Root-Auflösung hält die Artefakte und Implementierungsänderungen auf dieses Repo skopiert. Die Service- und Frontend-Änderungen können nun unabhängig getestet, reviewt, gemerged und archiviert werden.

Wenn die Implementierung beginnen muss, während der gemeinsame Store-Change noch aktiv ist, hole ihn explizit mit openspec show add-checkout-promo --store team-plans; Referenzindizes listen kanonische Store-Specs, nicht aktive Store-Änderungen. Halte den Store-Branch und die Komponenten-Branches in ihren Pull-Request-Beschreibungen verlinkt, damit Reviewer sehen können, welche Version des Vertrags jede Implementierung befolgt.

Story: Anforderungen, die Teamgrenzen überschreiten ​

Ein Plattform-Team besitzt die Anforderungen. Produktteams bauen gegen sie, in ihren eigenen Repos, mit ihren eigenen Designs. Eine Referenz beschreibt diese Beziehung, ohne die Arbeit von jemandem zu verschieben.

   platform-reqs (store)                 api-server (code repo)
   owned by the platform team            owned by a product team
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ reads    │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (their own designs)    │
   │   platform work          │          │ openspec/changes/        │
   │                          │          │   (their own work)       │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

Das Produktteam deklariert, worauf es zurückgreift in seinem openspec/config.yaml:

yaml
references:
  - platform-reqs

Referenzen sind schreibgeschützter Kontext. Das Repo behält seinen eigenen openspec/-Root; die Arbeit bleibt dort. Was sich ändert: openspec instructions in diesem Repo enthält jetzt einen Index der Specs des referenzierten Stores — jede mit einer einzeiligen Zusammenfassung und dem genauen Abrufbefehl (openspec show <spec-id> --type spec --store platform-reqs). Ein Agent, der in api-server arbeitet, kann die Upstream-Zahlungsanforderungen finden, sie zitieren und sein Low-Level-Design im eigenen Root des Repos schreiben — ohne dass jemand Kontext herumkopiert.

Eine Referenz kann ihre Clone-Quelle tragen, sodass Teammitglieder, die den Store noch nicht haben, einen vollständigen Fix anstelle einer Sackgasse erhalten:

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

Wenn du den Plan und den Code zusammen offen haben möchtest, erstelle ein Workset. Dies ist persönlich und explizit: Jede Person wählt die Ordner, mit denen sie tatsächlich auf ihrer Maschine arbeitet. Nichts über diese lokalen Checkout-Pfade wird in das gemeinsame Planungs-Repo committet.

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

Zwei Fragen, die du immer stellen kannst ​

„Ist meine Einrichtung gesund?" — openspec doctor prüft den aktuellen Root und seine referenzierten Stores, schreibgeschützt, mit einem einfügbaren Fix pro Befund:

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

„Womit arbeite ich?" — openspec context setzt den Arbeitsbereich aus OpenSpec-Deklarationen zusammen: den Root und die Stores, die er referenziert.

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 unterstützen --json für Agenten. openspec context --code-workspace <path> schreibt zusätzlich eine VS-Code-Workspace-Datei, die den gesamten Satz enthält — der einzige Schreibvorgang, den dieser Befehl ausführt.

Worksets: Ordner wieder öffnen, an denen Sie gemeinsam arbeiten ​

Unabhängig von den oben genannten Punkten: Die meisten Benutzer öffnen in jeder Sitzung dieselben wenigen Ordner – das Planungs-Repository sowie zwei oder drei Code-Repositories. Ein Workset ist eine persönliche, benannte Ansicht genau dieser Ordner, die mit einem einzigen Befehl in Ihrem bevorzugten Tool wieder geöffnet wird.

  workset "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       alle drei werden in Ihrem Tool geöffnet
bash
openspec workset create platform \
  --member ~/openspec/team-plans --member ~/src/api-server \
  --tool code
openspec workset list
platform  (öffnet in VS Code)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

openspec workset open platform startet dann das gespeicherte Tool: Editoren (VS Code, Cursor) öffnen ein Fenster mit allen Mitgliedern und kehren anschließend zurück. Das erste Mitglied ist das primäre. Überschreiben Sie das Tool jederzeit mit --tool <id>.

Worksets sind bewusst kein gemeinsamer Zustand. Sie befinden sich auf Ihrem Rechner, werden niemals committet und treffen keine Aussagen über die Arbeit – sie speichern lediglich, welche Ordner Sie gerne gemeinsam geöffnet haben möchten. Das Entfernen eines Worksets berührt die Member-Ordner nicht. Neue Tools sind Konfiguration, kein Code: Alles, was über eine Workspace-Datei oder pro-Ordner-Anhangsflags gestartet werden kann, kann unter dem Schlüssel openers in der globalen Konfiguration (openspec config edit) hinzugefügt werden.

Wie Befehle entscheiden, wo sie wirken sollen ​

Jeder normale Befehl löst seinen Root auf dieselbe Weise auf, in dieser Reihenfolge:

1. --store <id>          Sie haben es explizit angegeben → dieses Store
2. nächstes openspec/    hier befindet sich ein echter   → dieses Repo
   (vom aktuellen Verzeichnis aus nach oben suchend)     Planungs-Root
3. store: Zeiger         config.yaml deklariert einen    → dieses Store
                         Store
4. defaultStore          globale Konfiguration legt ein   → dieses Store
                         Standard für den Rechner fest
5. keiner der oben       Stores auf diesem Rechner       → Fehler mit einem
   genannten vorhanden?   registriert?                    Auswahlhinweis
                         Keine Stores registriert?       → das aktuelle
                                                          Verzeichnis
                                                          (klassisches Verhalten)

Die Zeile Using OpenSpec root: (und der Block root in der --json-Ausgabe) zeigt Ihnen an, welcher Fall zutrifft.

Bekannte Einschränkungen ​

  • Beta-Status. Alles auf dieser Seite kann zwischen Releases geändert werden – Namen, Flags, Dateiformate, JSON-Schlüssel.
  • Ein Checkout pro Store-ID pro Maschine. Die Registrierung eines zweiten Checkouts unter derselben ID schlägt fehl, mit einem Hinweis zur vorherigen Ausführung von store unregister.
  • Kein Sync, niemals – aus Designgründen. OpenSpec klont, zieht oder pusht nie. Ein veralteter Checkout zeigt veraltete Spezifikationen, bis Sie ziehen; Referenzen werden live aus dem Index des aktuell auf der Festplatte befindlichen Inhalts erstellt.
  • Leere Planungsordner können fehlen. Ein neuer Store muss noch nicht über openspec/changes/, openspec/specs/ oder openspec/changes/archive/ in Git verfügen. Dies wird während der Beta akzeptiert; diese Ordner erscheinen, sobald normale Befehle Dateien dafür erstellen.
  • Zeiger-Repositories bleiben Zeiger. Ein Repository, das nur Konfiguration enthält und dessen openspec/config.yaml store: <id> deklariert, wird als externalisierte Planung behandelt, nicht als zu registrierender Store-Checkout. Entfernen Sie zuerst die Zeile store:, wenn Sie dieses Repository absichtlich in einen lokalen Store-Root umwandeln möchten.
  • Einige Befehle bleiben, wo sie sind. templates und die veralteten Nomenformen (openspec change show, ...) wirken nur im aktuellen Verzeichnis – kein --store. schemas folgt der kanonischen Prioritätsreihenfolge zur Root-Auswahl und akzeptiert --store <id>, behält dabei jedoch seine erfolgreiche JSON-Array-Struktur unverändert bei.
  • Maschinenbezogener Zustand ist maschinenbezogen. Die Store-Registry und Worksets sind lokale Einstellungen. Nichts an der Layoutstruktur Ihres Rechners wird jemals in die gemeinsame Planung committet.
  • Zwei Startstile für Worksets. Ein Tool, das nicht mit einer Workspace-Datei oder pro-Ordner-Anhangsflags gestartet werden kann, kann nicht als Öffner hinzugefügt werden.
  • Agent-JSON hat eine bekannte Groß-/Kleinschreibungssplit (Store-Familien-Schlüssel sind snake_case, Workflow-Familien camelCase). Dokumentiert im Agent Contract; die Vereinheitlichung wurde auf eine versionierte Veröffentlichung verschoben.

Wo die Dinge gespeichert sind ​

WasWoGeteilt?
Planung eines Stores<store>/openspec/ (specs, changes)Ja – committen und pushen
Identität eines Stores<store>/.openspec-store/store.yamlJa – mit dem Store committet
Die Store-Registry<data dir>/openspec/stores/registry.yamlNein – nur für diesen Rechner
Worksets<data dir>/openspec/worksets/Nein – nur für diesen Rechner

<data dir> ist ~/.local/share/openspec unter macOS und Linux (bzw. $XDG_DATA_HOME/openspec, wenn gesetzt) und %LOCALAPPDATA%\openspec unter Windows.

Referenz ​

Exakte Flags und JSON-Strukturen für jeden Befehl auf dieser Seite: CLI reference (Stores, Doctor, Working context, Personal worksets) und der agent contract.