Schema's

Wijzig wat OpenSpec produceert: de artefacten, hun volgorde en hun sjablonen.

Een schema definieert wat een wijzigingsvoorstel produceert: welke artefacten, in welke volgorde, vanaf welke sjablonen. Het standaard meegeleverde schema spec-driven produceert bijvoorbeeld deze vier in ongeveer deze volgorde, elk voortbouwend op wat eraan voorafging:

proposal → specs → design → tasks

Fork een schema wanneer u wilt dat deze andere documenten worden, of dat nu minder ervan zijn, andere namen of een andere structuur betreft.

Waar schema's zich bevinden

OpenSpec zoekt naar een schema op drie plaatsen, in volgorde, en gebruikt het eerste dat het vindt:

1. Uw project: openspec/schemas/, gecommit met de repo zodat uw hele team het krijgt.
2. Uw machine: ~/.local/share/openspec/schemas op macOS en Linux (of onder $XDG_DATA_HOME als u het heeft ingesteld), of %LOCALAPPDATA%\openspec\schemas op Windows. Schema's hier zijn beschikbaar in elk project waaraan u werkt.
3. Het pakket: de ingebouwde schema's, zoals spec-driven, worden meegeleverd binnen openspec zelf.

Dezelfde naam kan op meer dan één plaats bestaan, en de meer specifieke locatie wint. openspec schema which toont welke kopie in gebruik is:

$ openspec schema which spec-driven
Schema: spec-driven
Bron: project
Pad: /your-project/openspec/schemas/spec-driven

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

Wat bevat een schema

Een schema wordt gedefinieerd door een map met plattestandbestanden: één schema.yaml dat de artefacten declareert, en een sjabloon voor elk ervan. Hier is de ingebouwde spec-driven:

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

• schema.yaml: declareert elk artefact, het bestand dat het genereert, het sjabloon waar het van start, wat het eerst vereist, en de instructie die de agent ontvangt bij het maken ervan. De contract van elk veld staat in schema.yaml.
• templates/: één markdown-skelet per artefact, dat de agent invult.

Hier is de vermelding van het tasks-artefact in schema.yaml, ingekort:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...wat de agent verteld wordt bij het maken van tasks.md...
    requires:
      - specs
      - design

De ingebouwde schema's worden binnen het openspec-pakket meegeleverd, dus u bewerkt ze nooit op hun plaats. U krijgt uw eigen kopie door te forken.

Uw eigen aangepaste schema maken

Er zijn twee manieren om uw eigen schema te krijgen:

1. Fork een bestaand schema en bewerk uw kopie. Begin hier wanneer een bestaand schema dicht bij is wat u wilt, omdat alles erin al werkt.
2. Begin vanaf nul wanneer geen van beide past, door een leeg schema op te zetten met openspec schema init.

Een bestaand schema forken

1. Fork het schema waar u van wilt starten, uitgevoerd vanaf uw projectroot:

   $ openspec schema fork spec-driven
   
   Opmerking: Schema-commando's zijn experimenteel en kunnen veranderen.
   ✔ 'spec-driven' geforkt naar 'spec-driven-custom'
   
   Bron: .../openspec/schemas/spec-driven (package)
   Bestemming: /your-project/openspec/schemas/spec-driven-custom

   Geef een tweede argument op om de naam te kiezen (openspec schema fork spec-driven team-flow). Namen zijn in kebab-case.

2. Bewerk de kopie: schema.yaml en de sjablonen. Uw fork bewerken behandelt wat u kunt veranderen.

3. Valideer het:

   openspec schema validate spec-driven-custom

   Dit is het enige commando dat een gebroken schema opvangt (ontbrekende sjablonen, slechte YAML, afhankelijkheidscycli) voordat u midden in een wijziging zit.

4. Richt uw project erop in openspec/config.yaml. Deze stap is aan u omdat fork config.yaml onaangeroerd laat:

   schema: spec-driven-custom

5. Nieuwe wijzigingsvoorstellen volgen nu uw schema. Eerder gemaakte wijzigingen behouden het schema waarmee ze begonnen.

Om de standaard overal te vervangen zonder config.yaml aan te raken, fork naar dezelfde naam: openspec schema fork spec-driven spec-driven. De kopie van uw project schaduwt dan de ingebouwde, zoals Waar schema's zich bevinden uitlegt.

Vanaf nul beginnen

openspec schema init zet een nieuw schema op in plaats van er een te kopiëren:

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

✔ Schema 'lite' aangemaakt
Schema aangemaakt op: /your-project/openspec/schemas/lite
Artefacten: proposal, tasks

Het skelet is kaal. Artefacten komen alleen van de vier ingebouwde id's, en de gegenereerde sjablonen bevatten geen instructies, dus de agent krijgt minder begeleiding totdat u uw eigen schrijft. Vanaf daar zijn de fork-stappen ongewijzigd van toepassing: valideer het, en richt config.yaml erop.

Uw fork bewerken

Een fork heeft twee soorten bestanden om te bewerken:

• templates/ veranderen het skelet van elk document. Voeg een sectie toe aan het tasks-sjabloon en elke nieuwe tasks.md begint ermee. Houd de #-titel op de eerste regel: het artefact erft hem, zodat elk gegenereerd bestand opent als een getiteld document.
• schema.yaml verandert de workflow zelf: welke artefacten bestaan, wat elk ervan eerst vereist, en de instructie die de agent krijgt bij het maken ervan.

Bijvoorbeeld, om het design-document te verwijderen voor een slankere flow:

1. Verwijder de design-vermelding uit schema.yaml.

2. Verwijder design uit de requires-lijst van tasks.

3. Valideer:

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

Sla stap 2 over en validatie vangt het op:

✗ Schema 'spec-driven-custom' heeft fouten:
  fout: Ongeldige afhankelijkheidsreferentie in artefact 'tasks': 'design' bestaat niet

Valideer na elke handmatige bewerking. Een gebroken schema verschijnt anders midden in een wijziging, wanneer een workflow om een bestand vraagt dat er niet is. Net als config.yaml bereiken schema-bewerkingen de agent bij de volgende uitvoering.

Een fork is een momentopname

openspec update ververst de geïnstalleerde vaardigheden en commando's, en het raakt openspec/schemas/ nooit aan. Uw fork blijft exact werken zoals u hem achterliet, wat ook betekent dat het stopt met het ontvangen van verbeteringen wanneer het ingebouwde schema evolueert. Om die later op te pakken, fork het ingebouwde opnieuw onder een nieuwe naam en draag de verschillen over.

Schema's delen

Een schema delen betekent zijn map kopiëren.

• Met uw team: commit openspec/schemas/ en iedereen op de repo gebruikt het.
• Over uw projecten: zet de map in de gebruikersniveau-map uit Waar schema's zich bevinden.
• Van de community: de communitycatalogus vermeldt gedeelde schema's. Kopieer er een naar openspec/schemas/<name> en het werkt als uw eigen.

We werken aan een schema-register, publiek en privaat, zodat schema's op naam kunnen worden geïnstalleerd in plaats van met de hand gekopieerd.

OpenSpec gebruiken met Superpowers

Het door de community onderhouden superpowers-bridge schema verbindt OpenSpec-artefacten met Superpowers uitvoeringsvaardigheden. Volg de installatie- en compatibiliteitsnotities van de bridge voordat u hem naar uw project kopieert.

De bridge wordt buiten OpenSpec uitgebracht. OpenSpec test de Superpowers-integratie niet en wijst er geen versienummer aan toe.