OpenSpec

Stores (Beta) ​

Planen Sie Änderungen, die mehrere Repositories umfassen: ein Store, viele Repos.

OpenSpec liegt normalerweise innerhalb eines Repos: ein openspec/-Ordner neben dem Code, den es plant. Ein Store verschiebt diesen Ordner in ein eigenes Repository, und mehrere Code-Repos können ihn sich teilen.

Nach einer einmaligen Einrichtung auf jedem Rechner können Befehle wie status, new change und archive im Store von jedem Verzeichnis aus verwendet werden.

         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)

Sie teilen einen Store mit Git genauso, wie Sie Code teilen: committen, pushen, pullen und selbst reviewen. Specs und Changes erhalten auf die gleiche Weise Branches und Pull Requests wie Code.

Wann Sie einen benötigen ​

Zwei häufige Gründe, einen Store zu verwenden:

  • Frontend und Backend in separaten Repos: Eine Funktion betrifft beide, und der Plan braucht ein einziges Zuhause statt zwei Hälften.

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

  • Ein Produkt, mehrere Client-Repos: Android, iOS und Web werden aus ihren eigenen Repos ausgeliefert, teilen sich aber ein erwartetes Verhalten. Eine Spec beschreibt Verhalten, nicht Implementierung, daher dient eine Spec allen drei.

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

Sie können mehr als einen Store haben, obwohl wir empfehlen, die Anzahl gering zu halten.

Einrichtung eines Stores ​

Eine Person erstellt den Store, dann schließen sich alle anderen an.

  1. Store erstellen (eine Person, einmal pro Team). Führen Sie openspec store setup aus und beantworten Sie die Eingabeaufforderungen:

    bash
    # von überall aus ausführen; es fragt, was erstellt werden soll und wo
openspec store setup

    Es stellt drei Fragen:

    • Store-Name: team-plans
    • Wo soll dieser Store gespeichert werden?: vorausgefüllt mit ~/openspec/<name>, drücken Sie Enter, um es zu übernehmen, oder geben Sie einen anderen Pfad ein
    • Diesen Store erstellen?: zeigt an, was gleich erstellt wird, antworten Sie mit Ja

    Danach wird der Ergebnis angezeigt:

    yaml
    Store bereit: team-plans
Speicherort: ~/openspec/team-plans
OpenSpec-Wurzel: bereit
Registry: registriert

Nächster Schritt: Führen Sie normale OpenSpec-Befehle gegen diesen Store aus, z. B.:
  openspec new change <change-id> --store team-plans
Geben Sie diesen Store frei, indem Sie ihn committen und pushen wie jedes Git-Repository.

  2. Auf den Git-Host pushen. Erstellen Sie zunächst ein leeres team-plans-Repository auf Ihrem Host. Das Setup fügt kein Git-Remote hinzu, daher verbinden Sie den Store mit diesem Repository und pushen Sie:

    bash
    # Verbinden Sie den Store mit dem leeren Repository auf Ihrem Git-Host
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# Veröffentlichen
git push -u origin main

  3. Store beitreten (jeder Teamkollege, einmal pro Maschine):

    bash
    # Store auf Ihre Maschine holen
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# OpenSpec mitteilen, wo er liegt
openspec store register ~/openspec/team-plans
    yaml
    Store registriert: team-plans
Speicherort: /Users/you/openspec/team-plans
OpenSpec-Wurzel: bereit
Registry: registriert

    Die Registrierung teilt Ihrer Maschine mit, wo dieser Store liegt. Der Store-Name ist bereits in .openspec-store/store.yaml enthalten. Das Setup hat die Kopie des Erstellers registriert, daher benötigen nur geklonte Kopien diesen Schritt.

  4. Bestätigen Sie, dass es funktioniert hat, aus einem beliebigen Verzeichnis:

    bash
    # Jeder OpenSpec-Befehl erreicht den Store über den Namen
openspec status --store team-plans
    yaml
    Verwendete OpenSpec-Wurzel: team-plans (/Users/you/openspec/team-plans)
Keine aktiven Changes. Erstellen Sie einen mit: openspec new change <name> --store team-plans

Arten der Einrichtung ​

OpenSpec hat drei Einrichtungsarten. Der Rest dieser Seite verwendet diese Namen:

  • repo-local: OpenSpec innerhalb Ihres Repos, ohne Store. Der Standard.
  • nur Store: Ihr Repo behält keine eigenen Specs oder Changes. Alles liegt im Store.
  • optionaler Store: Ihr Projekt hat einen eigenen openspec/-Ordner und erreicht bei Bedarf einen Store.

Der Standard: OpenSpec innerhalb Ihres Repos (repo-local) ​

openspec init legt einen openspec/-Ordner neben Ihren Code, und die Specs und Changes dieses Repos liegen dort. Kein Store ist beteiligt. Dies ist die Einrichtung, die Einrichtung Ihres Projekts beschreibt, und die meisten Projekte benötigen keine andere.

web-app  (Code-Repo)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec außerhalb Ihres Repos, in einem Store (store-only) ​

Das Repo behält keine eigenen Specs oder Changes. Alles, was plant, liegt im Store, und eine Zeile in der Konfiguration des Repos verbindet beides.

Verbreitet, wenn ein Team alle Repos baut und an einem Ort plant. Die Beispiele oben haben alle diese Form.

team-plans  (Store)
└── openspec/
    ├── specs/       die Specs des Repos liegen hier
    └── changes/     auch seine Changes
          ▲
          │ store: team-plans   (die verbindende Zeile)
web-app  (Code-Repo)
└── openspec/
    └── config.yaml    nichts weiter

OpenSpec in Ihrem Repo und in einem Store (store-optional) ​

Das Repo bleibt für seine eigene Arbeit repo-lokal, während der Store die gemeinsamen Specs und Changes enthält. Innerhalb des Repos verwendet OpenSpec den openspec/-Ordner Ihres Projekts und erreicht den Store nur, wenn Sie --store übergeben.

Verbreitet, wenn ein Repo OpenSpec verwendet hat, bevor der Store existierte, oder wenn ein weitgehend unabhängiges Repo nur gelegentlich gemeinsame Arbeiten berührt.

team-plans  (Store)
└── openspec/          die gemeinsamen Specs und Changes
          ▲
          │ nur wenn Sie --store team-plans übergeben
web-app  (Code-Repo)
└── openspec/          die eigenen dieses Repos
    ├── config.yaml
    ├── specs/
    └── changes/

Ein Repo kann repo-lokal beginnen und seine Specs und Changes später in den Store verschieben. Specs und Changes eines Repos in den Store verschieben zeigt, wie.

Wo Artefakte beim Verwenden von Stores erstellt werden ​

Wenn Sie einen Store verwenden, muss OpenSpec auch entscheiden, wo die Artefakte erstellt werden. Dies hängt von Ihrer Einrichtung ab:

  • nur Store (Ihr Projekt schreibt nur in den Store): Jedes Artefakt wird im Store erstellt. Die store:-Zeile unten dokumentiert dies.
  • optionaler Store (Ihr Projekt hat einen eigenen openspec/-Ordner und verwendet auch einen Store): Artefakte werden in Ihrem Projekt erstellt, es sei denn, Sie nennen den Store in Ihrer Anfrage oder übergeben --store für diesen Change. Ihr Agent trägt dann das Flag durch den Rest des Workflows.

OpenSpec schreibt Artefakte an einen von zwei Orten: den openspec/-Ordner Ihres Projekts oder den des Stores. Die Auswahl erfolgt in dieser Reihenfolge, und die erste zutreffende Option gewinnt:

  1. --store <id> in einem Befehl. Gewinnt immer, aus jedem Verzeichnis.
  2. Der openspec/-Ordner Ihres Projekts. Wenn Ihr Projekt eigene specs/- oder changes/-Ordner hat, verwendet OpenSpec diese.
  3. Die store:-Zeile in Ihrem Projekt. Wie ein Projekt mit nur Store seinen Store erfasst.
  4. defaultStore auf Ihrer Maschine. Der Fallback, wenn keine der obigen Optionen zutrifft.

Wenn keine davon zutrifft und Sie Stores registriert haben, schlägt der Befehl fehl und listet sie auf. Wenn die ID eines Stores dem Namen Ihres Repos in seinem origin-Remote entspricht, nennt der Fehler diesen Store und die store:-Zeile, die ihn auswählt. OpenSpec wählt niemals selbst einen Store nach Namen, da Repos in verschiedenen Organisationen einen Namen teilen können.

Wenn OpenSpec einen Store auswählt, gibt es Using OpenSpec root: ... vor der Befehlsausgabe aus.

Die store:-Zeile (Projekte mit nur Store) ​

Fügen Sie eine Zeile zur openspec/config.yaml Ihres Projekts hinzu:

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

Alles, was Sie oder Ihr Agent innerhalb Ihres Projekts ausführen, verwendet jetzt den Store, ohne dass ein Flag eingegeben werden muss:

bash
# innerhalb web-app, verbunden
openspec status
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Keine aktiven Changes. Erstellen Sie einen mit: openspec new change <name> --store team-plans
  • Ohne die Zeile: Führen Sie einen einfachen Befehl in einem Projekt mit nur Store aus, und OpenSpec stoppt mit einem Fehler, der Ihre registrierten Stores auflistet.
  • Committen: Teamkollegen, die Ihr Projekt klonen, erhalten die Zeile ebenfalls. Sie müssen den Store weiterhin auf ihrer Maschine registrieren (Schritt 3 der Store-Einrichtung), oder OpenSpec meldet einen Fehler und teilt ihnen mit, ihn zu registrieren.
  • Neben echten Ordnern: Wenn Ihr Projekt auch specs/- oder changes/-Ordner hat, verwendet OpenSpec diese und ignoriert die Zeile, mit einer Warnung.

Integrationen in einem Repo mit nur Store installieren ​

Führen Sie init vom Wurzelverzeichnis des Code-Repos aus, um KI-Tool-Integrationsdateien zu installieren, ohne die Planung zurück in dieses Repo zu verschieben:

bash
# innerhalb web-app, im Wurzelverzeichnis des Repos
openspec init --tools claude
  • Integrationsdateien: Werden im Code-Repo geschrieben.
  • openspec/config.yaml: Wird Byte für Byte erhalten, einschließlich der store:-Zeile.
  • openspec/specs/ und openspec/changes/: Werden nicht im Code-Repo erstellt.

OpenSpec verweigert diesen Befehl aus einem Unterverzeichnis des Code-Repos. Führen Sie ihn vom Wurzelverzeichnis des Repos aus.

OpenSpec verweigert hier auch --language, da die Sprache in der Konfiguration des externen Stores gehört. Führen Sie init im Wurzelverzeichnis des Stores aus oder bearbeiten Sie diese Konfiguration direkt.

defaultStore auf Ihrer Maschine ​

Setzen Sie ihn einmal, wenn jedes Projekt, in dem Sie arbeiten, denselben Store verwendet. OpenSpec fällt darauf zurück, wenn er kein Flag, keinen lokalen openspec/-Ordner und keine store:-Zeile findet:

bash
# team-plans verwenden, wenn sonst nichts einen Store nennt
openspec config set defaultStore team-plans

# Rückgängig machen
openspec config unset defaultStore

Befehle, die lokal bleiben. init, update, templates, schemas und die openspec schema-Unterbefehle wirken nur auf das aktuelle Verzeichnis und akzeptieren kein --store.

Specs und Changes eines Repos in den Store verschieben ​

Um ein Repo von repo-local auf nur Store umzustellen:

  1. Verschieben Sie alles aus openspec/specs/ und openspec/changes/ des Repos in die gleichen Ordner im Store.
  2. Löschen Sie die jetzt leeren Ordner, sodass der openspec/-Ordner des Repos nur config.yaml enthält.
  3. Fügen Sie die store:-Zeile zu dieser config.yaml hinzu.

openspec status innerhalb des Repos beginnt jetzt mit Using OpenSpec root: team-plans.

Im Store arbeiten ​

Die Workflows ändern sich nicht, weder für Sie noch für Ihren Agenten. Propose, apply und archive laufen wie immer. Der einzige Unterschied ist, wo die Artefakte erstellt werden, und der Abschnitt oben behandelt das.

Erstellen Sie einen Change aus einem Repo mit nur Store, und er landet im Store:

bash
# innerhalb web-app; die store:-Zeile leitet dies an team-plans
openspec new change add-login
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Change 'add-login' erstellt unter /Users/you/openspec/team-plans/openspec/changes/add-login/
Schema: spec-driven
Nächster Schritt: openspec status --change add-login --store team-plans
  • Wohin er ging: In das Store-Repo, nicht neben Ihren Code.
  • Freigeben: Der Change existiert nur in Ihrem Checkout, bis Sie das Store-Repo committen und pushen. Teamkollegen sehen ihn, wenn sie pullen. Gleiches gilt für jedes Artefakt, das die Workflows schreiben.
  • Pfade in der Dokumentation: Wo immer die Dokumentation einen openspec/-Pfad zeigt, ist dieser Ordner in einer Store-Einrichtung der des Stores.

Wenn Artefakte dort erstellt werden, wo Sie es nicht erwartet haben, prüft openspec doctor Ihre Einrichtung, ohne etwas zu ändern, und gibt eine Korrektur für jeden Befund aus:

bash
# Aktuelle Wurzel und ihre Stores prüfen
openspec doctor
yaml
Doctor

Wurzel
  Speicherort: /Users/you/openspec/team-plans
  OpenSpec-Wurzel: ok
  Store: team-plans (Metadaten ok)

Referenzen
  (keine deklariert)

openspec context listet die Wurzel und Stores auf, mit denen Ihr aktuelles Verzeichnis arbeitet, wenn Sie dieselben Informationen ohne die Prüfungen möchten.

Um den Store und ein Repo in einem Editorfenster zu öffnen, damit Ihr Agent beides lesen kann, siehe Worksets (Beta).

Specs aus einem anderen Store lesen ​

Ihr Repository kann seinen eigenen openspec/-Ordner behalten und Ihr Agent kann dennoch Specs aus einem anderen Store lesen. Deklarieren Sie diesen Store unter references: in der openspec/config.yaml des Repositories:

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

Referenzen sind schreibgeschützt. Ihre Arbeit bleibt in Ihrem Repository, und die Referenz ändert nur, was Ihrem Agenten mitgeteilt wird.

Wenn ein Workflow ein Artifact erstellt, erhalten seine Anweisungen einen Index der Specs des referenzierten Stores, jeweils mit einer einzeiligen Zusammenfassung und dem exakten Befehl zum Abrufen:

xml
<referenced_stores>
<!-- Schreibgeschützter Upstream-Kontext. Holen Sie ab, was Sie benötigen; zitieren Sie, was Sie verwenden. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Regeln für die Abbuchung und Rückerstattung von Kunden.
  Fetch: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Eine Referenz kann auch die Clone-URL des Stores enthalten, für Maschinen, die diesen Store noch nicht haben:

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

Mit deklarierter URL wandelt openspec doctor einen fehlenden Store in eine einfügbare Korrektur um:

yaml
# Ausgabe umbrochen zur Anpassung
Referenzen
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Referenzierter Store 'design-system' ist auf diesem Rechner nicht registriert.
    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

Beta-Einschränkungen ​

  • Die Struktur kann sich ändern: Befehlsnamen, Flags und Dateiformate können sich zwischen Releases ändern. Lesen Sie diese Seite nach dem Upgrade erneut.
  • Keine Synchronisierung, beabsichtigt: OpenSpec klont, pullt oder pusht nie. Ein veralteter Checkout zeigt veraltete Specs, bis Sie pullen, und Referenzen werden von dem gelesen, was auf der Platte liegt.
  • Ein Checkout pro Store-Name: Das Registrieren eines zweiten Ordners unter einem bereits registrierten Namen schlägt fehl, mit dem Hinweis, zuerst openspec store unregister auszuführen.