Schemas

Ändere, was OpenSpec produziert: die Artefakte, ihre Reihenfolge und ihre Vorlagen.

Ein Schema definiert, was ein Änderungsvorschlag produziert: welche Artefakte, in welcher Reihenfolge, aus welchen Vorlagen. Zum Beispiel produziert spec-driven, das mitgelieferte Standardschema, diese vier Artefakte in etwa dieser Reihenfolge, wobei jedes auf dem vorherigen aufbaut:

proposal → specs → design → tasks

Fork ein Schema, wenn diese Artefakte andere Dokumente sein sollen – ob weniger davon, andere Namen oder eine andere Struktur.

Wo Schemas liegen

OpenSpec sucht nach einem Schema an drei Stellen, in dieser Reihenfolge, und verwendet das erste, das es findet:

1. In deinem Projekt: openspec/schemas/, zusammen mit dem Repository versioniert, damit dein ganzes Team es erhält.
2. Auf deinem Rechner: ~/.local/share/openspec/schemas auf macOS und Linux (oder unter $XDG_DATA_HOME, falls du es gesetzt hast), oder %LOCALAPPDATA%\openspec\schemas auf Windows. Schemas hier sind in jedem Projekt verfügbar, in dem du arbeitest.
3. Im Paket: die eingebauten Schemas wie spec-driven liegen innerhalb von openspec selbst.

Derselbe Name kann an mehr als einem Ort existieren, und der spezifischere Ort gewinnt. openspec schema which zeigt, welche Kopie in Gebrauch ist:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Was in einem Schema steckt

Ein Schema ist durch einen Ordner mit einfachen Dateien definiert: ein schema.yaml, das die Artefakte deklariert, und eine Vorlage für jedes Artefakt. Hier ist das eingebaute spec-driven:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: deklariert jedes Artefakt, die Datei, die es generiert, die Vorlage, von der es ausgeht, was es zuerst erfordert und die Anweisung, die der Agent beim Erstellen erhält. Der Vertrag jedes Feldes befindet sich in schema.yaml.
• templates/: ein Markdown-Gerüst pro Artefakt, das der Agent ausfüllt.

Hier ist der Eintrag des tasks-Artefakts in schema.yaml, gekürzt:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

Die eingebauten Schemas liegen innerhalb des openspec-Pakets, du bearbeitest sie also niemals direkt. Du erhältst deine eigene Kopie durch Forken.

Dein eigenes benutzerdefiniertes Schema erstellen

Es gibt zwei Möglichkeiten, ein eigenes Schema zu erhalten:

1. Fork ein bestehendes Schema und bearbeite deine Kopie. Beginne hier, wenn ein bestehendes Schema dem nahe kommt, was du willst, weil alles darin bereits funktioniert.
2. Beginne von Grund auf, wenn keines passt, und generiere ein leeres Schema mit openspec schema init.

Ein bestehendes Schema forken

1. Fork das Schema, von dem du ausgehen möchtest, ausgeführt von deinem Projektroot:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Übergib ein zweites Argument, um den Namen zu wählen (openspec schema fork spec-driven team-flow). Namen sind kebab-case.

2. Bearbeite die Kopie: schema.yaml und die Vorlagen. Deine Fork bearbeiten beschreibt, was zu ändern ist.

3. Validiere es:

   openspec schema validate spec-driven-custom

   Dies ist der eine Befehl, der ein kaputtes Schema (fehlende Vorlagen, schlechtes YAML, Abhängigkeitszyklen) abfängt, bevor du mitten in einer Änderung steckst.

4. Richte dein Projekt in openspec/config.yaml darauf ein. Dieser Schritt liegt bei dir, da fork config.yaml unberührt lässt:

   schema: spec-driven-custom

5. Neue Änderungsvorschläge folgen nun deinem Schema. Zuvor erstellte Änderungen behalten das Schema, mit dem sie begonnen haben.

Um den Standard überall zu ersetzen, ohne config.yaml anzufassen, forke unter demselben Namen: openspec schema fork spec-driven spec-driven. Deine Projektkopie überschattet dann das eingebaute Schema, wie in Wo Schemas liegen erklärt.

Von Grund auf beginnen

openspec schema init generiert ein neues Schema, statt eines zu kopieren:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

Das Gerüst ist karg. Artefakte stammen nur aus den vier eingebauten IDs, und die generierten Vorlagen tragen keine Anweisungen, sodass der Agent weniger Hilfestellung erhält, bis du deine eigenen schreibst. Von dort gelten die Fork-Schritte unverändert: validiere es, dann richte config.yaml darauf ein.

Deine Fork bearbeiten

Eine Fork hat zwei Arten von Dateien zu bearbeiten:

• templates/ ändern das Gerüst jedes Dokuments. Füge eine Sektion in die tasks-Vorlage ein und jedes neue tasks.md beginnt damit. Behalte den #-Titel in der ersten Zeile: das Artefakt erbt ihn, sodass jede generierte Datei als tituliertes Dokument geöffnet wird.
• schema.yaml ändert den Workflow selbst: welche Artefakte existieren, was jedes zuerst erfordert und die Anweisung, die der Agent beim Erstellen erhält.

Um zum Beispiel das Design-Dokument für einen schlankeren Workflow zu entfernen:

1. Lösche den design-Eintrag aus schema.yaml.

2. Entferne design aus der requires-Liste von tasks.

3. Validiere:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

Wenn du Schritt 2 überspringst, fängt die Validierung das ab:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

Validiere nach jeder manuellen Bearbeitung. Ein kaputtes Schema taucht sonst mitten in einer Änderung auf, wenn ein Workflow nach einer Datei verlangt, die nicht existiert. Wie bei config.yaml erreichen Schema-Bearbeitungen den Agenten beim nächsten Lauf.

Eine Fork ist ein Schnappschuss

openspec update aktualisiert die installierten Skills und Befehle und berührt niemals openspec/schemas/. Deine Fork funktioniert weiterhin genau so, wie du sie hinterlassen hast – was auch bedeutet, dass sie keine Verbesserungen mehr erhält, wenn sich das eingebaute Schema weiterentwickelt. Um diese später zu übernehmen, forke das eingebaute Schema erneut unter einem neuen Namen und portiere die Unterschiede über.

Schemas teilen

Ein Schema zu teilen bedeutet, seinen Ordner zu kopieren.

• Mit deinem Team: Committe openspec/schemas/ und alle im Repository verwenden es.
• Über deine Projekte hinweg: Lege den Ordner im benutzerlevel-Verzeichnis aus Wo Schemas liegen ab.
• Aus der Community: der Community-Katalog listet geteilte Schemas auf. Kopiere eines nach openspec/schemas/<name> und es funktioniert wie dein eigenes.

Wir arbeiten an einem Schema-Registry, öffentlich und privat, damit Schemas nach Namen installiert werden können, statt von Hand kopiert zu werden.

OpenSpec mit Superpowers verwenden

Das communitygepflegte superpowers-bridge-Schema verbindet OpenSpec-Artefakte mit Superpowers-Ausführungsskills. Befolge die Installations- und Kompatibilitätshinweise des Bridges, bevor du ihn in dein Projekt kopierst.

Der Bridge wird außerhalb von OpenSpec veröffentlicht. OpenSpec testet oder versioniert seine Superpowers-Integration nicht.