Aanpassingen

OpenSpec biedt drie niveaus van aanpassing:

Niveau	Wat het doet	Geschikt voor
Projectconfiguratie	Standaardinstellingen instellen, context/regels injecteren	De meeste teams
Aangepaste schema's	Eigen workflow-artefacten definiëren	Teams met unieke processen
Globale overschrijvingen	Schema's delen over alle projecten	Gevorderde gebruikers

---

Projectconfiguratie

Het bestand openspec/config.yaml is de eenvoudigste manier om OpenSpec aan te passen voor jouw team. Hiermee kun je:

• Een standaardschema instellen – Sla --schema over bij elk commando
• Projectcontext injecteren – AI ziet je techstack, conventies, enz.
• Per-artefactregels toevoegen – Aangepaste regels voor specifieke artefacten
• Per-bewerkingsrichtlijnen toevoegen – Adviserende voorkeuren voor apply- en archive-werk
• Integratiekeuzes onthouden – bijv. de opt-in voor de GitHub Copilot cloud coding agent

Snelle installatie

openspec init

Deze leidt je interactief door het aanmaken van een configuratie. Of maak er handmatig een:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API-stijl: RESTful, gedocumenteerd in docs/api.md
  Testen: Jest + React Testing Library
  We hechten waarde aan achterwaartse compatibiliteit voor alle publieke API's

rules:
  proposal:
    - Voeg een rollback-plan toe
    - Identificeer betrokken teams
  specs:
    - Gebruik het Given/When/Then-formaat
    - Verwijs naar bestaande patronen voordat je nieuwe bedenkt

operations:
  apply:
    guidance:
      - Voer gerichte tests uit voordat je de volledige suite draait
  archive:
    guidance:
      - Houd de voltooiingssamenvatting beknopt

# Ingesteld door `openspec init` wanneer je kiest voor (of afwijst) de GitHub Copilot
# cloud coding agent; bepaalt of `init`/`update` de bijbehorende bestanden genereert.
githubCopilot:
  cloudAgent: false

Hoe het werkt

Standaardschema:

# Zonder configuratie
openspec new change my-feature --schema spec-driven

# Met configuratie – schema is automatisch
openspec new change my-feature

Context- en regelinjectie:

Bij het genereren van elk artefact worden jouw context en regels in de AI-prompt geïnjecteerd:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Voeg een rollback-plan toe
- Identificeer betrokken teams
</rules>

<template>
[Ingebouwd sjabloon van het schema]
</template>

• Context verschijnt in ALLE artefacten
• Regels verschijnen ALLEEN voor het overeenkomstige artefact

Operationele richtlijnen:

operations.apply.guidance en operations.archive.guidance zijn optionele lijsten van adviserende instructies voor hoe een agent die bewerkingen moet uitvoeren. Ze zijn gescheiden van rules: operationele richtlijnen leggen geen beperkingen op aan artefactinhoud, en artefactregels worden nooit als operationele richtlijnen hergebruikt.

Apply en archive halen deze invoer op tijdens uitvoering:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Beide antwoorden retourneren de huidige project‑context en overeenkomstige operationGuidance als aparte optionele velden. Elke aanroep leest een nieuwe momentopname vanuit de opgeloste root. Wanneer --store <id> is geselecteerd, komen de wijziging, context en richtlijnen allemaal uit die store in plaats van uit de huidige repository. Het archive-instructiecommando is alleen-lezen: het inspecteert of voegt geen delta-specs samen, schrijft geen hoofdspecs, verplaatst de wijziging niet en voert de statische archive-workflow niet uit.

Projectcontext is een vereiste invoer op promptniveau. Gegenereerde workflows lezen deze en passen relevante projectfeiten, conventies en beperkingen toe. Operationele richtlijnen zijn optioneel aanvullend advies: workflows overwegen elke vermelding en volgen vermeldingen die toepasbaar en compatibel zijn met de ingebouwde workflow.

Beide velden blijven gescheiden van CLI-gestuurde staat, opgeloste paden, ingebouwde stappen, expliciete gebruikerskeuzes en artefactregels. Een workflow rapporteert contextconflicten terwijl de sturende waarde behouden blijft. Het volgt geen ontoepasbare of tegenstrijdige richtlijnen en legt uit waarom. Geen van beide velden is een afdwingbare controle en workflows kopiëren hun tekst niet naar implementatiebestanden, specificaties, wijzigingsartefacten of samenvattingen, tenzij de gebruiker die inhoud afzonderlijk opvraagt.

Invoerveiligheid bij archivering en spec-sync:

Archive, bulk archive en standalone sync gebruiken artifactPaths.specs.existingOutputPaths uit openspec status --json als de enige bron voor delta-specs. Een schema zonder specs-artefact, of een wijziging waarvan de concrete outputlijst leeg is, heeft niets te synchroniseren; andere artefacten worden niet gebruikt om delta-specs af te leiden.

Voordat een semantische merge een hoofdspec schrijft, verbruikt de workflow de huidige uitvoer van openspec instructions specs --change <name> --json. De geretourneerde specs-regels beperken alleen de hoofdspecs die door die merge worden geproduceerd. Enkele archive geeft die momentopname door aan inline sync, standalone sync haalt deze direct op en bulk archive verkrijgt elke benodigde momentopname vóór zijn eerste spec-schrijfactie. Een niet-nul- of ongeldige JSON-reactie op archive/specs-instructies is een opzoekfout, niet een lege invoer: de workflow stopt vóór de betreffende spec-schrijfactie of wijzigingsverplaatsing (bij bulk archive vóór enige batch-schrijfactie of -verplaatsing).

Deze configuratie verandert de uitvoeringsfasen van archive, gebruikersprompts, bestandssysteembewerkingen, eigendom van semantische merges, het directe openspec archive-commando of de structuur en uitvoer van artefact‑rules niet.

Schema-resolutievolgorde

Wanneer OpenSpec een schema nodig heeft, controleert het in deze volgorde:

1. CLI-vlag: --schema <name>
2. Wijzigingsmetadata (.openspec.yaml in de wijzigingsmap)
3. Projectconfiguratie (openspec/config.yaml)
4. Standaard (spec-driven)

---

Aangepaste schema's

Wanneer de projectconfiguratie niet volstaat, maak je je eigen schema met een volledig aangepaste workflow. Aangepaste schema's bevinden zich in de map openspec/schemas/ van je project en worden samen met je code onder versiebeheer gezet.

your-project/
├── openspec/
│   ├── config.yaml        # Projectconfiguratie
│   ├── schemas/           # Hier staan de aangepaste schema's
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Jouw wijzigingen
└── src/

Een bestaand schema forken

De snelste manier om aan te passen is door een ingebouwd schema te forken:

openspec schema fork spec-driven my-workflow

Hiermee wordt het volledige spec-driven-schema naar openspec/schemas/my-workflow/ gekopieerd, waar je het vrij kunt bewerken.

Wat je krijgt:

openspec/schemas/my-workflow/
├── schema.yaml           # Workflowdefinitie
└── templates/
    ├── proposal.md       # Sjabloon voor het voorstel-artefact
    ├── spec.md           # Sjabloon voor specificaties
    ├── design.md         # Sjabloon voor ontwerp
    └── tasks.md          # Sjabloon voor taken

Bewerk nu schema.yaml om de workflow te wijzigen, of bewerk de sjablonen om te veranderen wat de AI genereert.

Een schema vanaf nul maken

Voor een volledig nieuwe workflow:

# Interactief
openspec schema init research-first

# Niet-interactief
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Schemastructuur

Een schema definieert de artefacten in je workflow en hoe deze van elkaar afhankelijk zijn:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: De aangepaste workflow van mijn team

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initiële voorsteldocument
    template: proposal.md
    instruction: |
      Maak een voorstel dat uitlegt WAAROM deze wijziging nodig is.
      Focus op het probleem, niet op de oplossing.
    requires: []

  - id: design
    generates: design.md
    description: Technisch ontwerp
    template: design.md
    instruction: |
      Maak een ontwerpdocument dat uitlegt HOE te implementeren.
    requires:
      - proposal    # Kan pas een ontwerp maken als er een voorstel is

  - id: tasks
    generates: tasks.md
    description: Implementatie checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Belangrijke velden:

Veld	Doel
id	Unieke identificatie, gebruikt in commando's en regels
generates	Uitvoerbestandsnaam (ondersteunt globs zoals specs/**/*.md)
template	Sjabloonbestand in de map templates/
instruction	AI-instructies voor het maken van dit artefact
requires	Afhankelijkheden - welke artefacten eerst moeten bestaan

Zet de artefacten in de volgorde waarin je ze geschreven wilt hebben. requires bepaalt wat mogelijk is; de volgorde van de lijst artifacts: bepaalt wat eerst komt wanneer meerdere artefacten tegelijk klaar zijn.

Sjablonen

Sjablonen zijn Markdown-bestanden die de AI sturen. Ze worden in de prompt geïnjecteerd bij het maken van dat artefact.

<!-- templates/proposal.md -->
## Why

<!-- Leg de motivatie voor deze wijziging uit. Welk probleem lost dit op? -->

## What Changes

<!-- Beschrijf wat er zal veranderen. Wees specifiek over nieuwe mogelijkheden of aanpassingen. -->

## Impact

<!-- Beïnvloede code, API's, afhankelijkheden, systemen -->

Sjablonen kunnen bevatten:

• Sectiekoppen die de AI moet invullen
• HTML-opmerkingen met richtlijnen voor de AI
• Voorbeeldindelingen die de verwachte structuur tonen

Valideer je schema

Voordat je een aangepast schema gebruikt, valideer het:

openspec schema validate my-workflow

Dit controleert:

• of de syntax van schema.yaml correct is
• of alle gerefereerde sjablonen bestaan
• of er geen circulaire afhankelijkheden zijn
• of de artefact-ID's geldig zijn

Gebruik je aangepaste schema

Eenmaal aangemaakt, gebruik je schema met:

# Geef op via opdrachtregel
openspec new change feature --schema my-workflow

# Of stel in als standaard in config.yaml
schema: my-workflow

Schemaresolutie debuggen

Weet je niet welk schema wordt gebruikt? Controleer met:

# Zie waar een specifiek schema vandaan komt
openspec schema which my-workflow

# Lijst alle beschikbare schema's op
openspec schema which --all

De output laat zien of het uit je project, de gebruikersmap of het pakket komt:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Opmerking: OpenSpec ondersteunt ook schema's op gebruikersniveau in ~/.local/share/openspec/schemas/ om te delen tussen projecten, maar schema's op projectniveau in openspec/schemas/ worden aanbevolen omdat ze samen met je code onder versiebeheer staan.

---

Voorbeelden

Snelle iteratieworkflow

Een minimale workflow voor snelle iteraties:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Snelle iteratie met minimale overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Snel voorstel
    template: proposal.md
    instruction: |
      Maak een beknopt voorstel voor deze wijziging.
      Richt je op het wat en waarom, sla gedetailleerde specificaties over.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementatie checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Een review-artefact toevoegen

Fork de standaard en voeg een reviewstap toe:

openspec schema fork spec-driven with-review

Bewerk vervolgens schema.yaml om toe te voegen:

  - id: review
    generates: review.md
    description: Pre-implementatie review checklist
    template: review.md
    instruction: |
      Maak een reviewchecklist gebaseerd op het ontwerp.
      Neem beveiligings-, prestatie- en testoverwegingen op.
    requires:
      - design

  - id: tasks
    # ... bestaande takenconfiguratie ...
    requires:
      - specs
      - design
      - review    # Nu vereisen taken ook een review

---

Community-schema's

OpenSpec ondersteunt ook door de community onderhouden schema's die via zelfstandige repositories worden verspreid. Deze bieden opinionated workflows die OpenSpec integreren met andere tools of systemen, vergelijkbaar met hoe de community-extensiecatalogus van github/spec-kit werkt voor spec-kit.

Community-schema's worden niet in de kern van OpenSpec opgenomen — ze bevinden zich in hun eigen repositories met hun eigen releasecyclus. Om er een te gebruiken, kopieer je de schemabundel naar de map openspec/schemas/<schema-name>/ van je project (de README van elke repo bevat installatie-instructies).

Schema	Onderhouder	Repository	Beschrijving
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Legt wijzigingsintentie, waarneembaar gedrag, technisch ontwerp en duurzame architectuurbeslissingen vast vóór implementatie. Voegt een wijzigingslokaal ADR-reviewmanifest toe en schrijft gekwalificeerde langlevende beslissingen als onveranderlijke, vervangbare ADR's.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Integreert OpenSpec's artefactgovernance met de uitvoeringsvaardigheden van obra/superpowers (brainstormen, plannen schrijven, TDD via subagents, code review, afronding). Voegt een evidence-first retrospective-artefact toe dat een gat vult dat Superpowers van nature niet dekt.
nanopm	@nmrtn	nmrtn/nanopm	PM-first workflow. Voert de planningspijplijn van nanopm uit (audit → strategie → roadmap → PRD) stroomopwaarts van implementatie. Overbrugt productplanning naar de spec-gedreven engineeringworkflow van OpenSpec. Artefacten worden gelezen uit .nanopm/ indien aanwezig — het voorstel haalt de audit, het ontwerp haalt de strategie en de taken halen de uitsplitsing van de PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	End-to-end testrunbooks op capability-niveau. Elke capability krijgt een onveranderlijke spec, een onveranderlijk taken-sjabloon en één getijdstempelde uitvoeringsregistratie per uitvoering. Asserties zijn alleen waarneembaar gedrag (HTTP-status, response-body, persistente staat — nooit log-substrings); elke run registreert start/eind UTC, duur en best-geschat LLM-tokenverbruik.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Spec-gedreven workflow met TDD-discipline en een tegenstrijdige review-stap. Verloop: proposal → specs → design → review → test-plan → tasks → apply → verify. review wordt geschreven door een reviewer met een verse context en alleen-lezen (een tweede model indien beschikbaar) en geeft een VERDICT:-regel die de agent vertelt om test-plan, tasks en apply te blokkeren; OpenSpec controleert alleen of artefacten bestaan, dus dwing de blokkering af met je eigen CI of hook. test-plan koppelt elke spec-scenario aan een benoemde test en dient tevens als rood/groen-grootboek dat verify controleert.

Wil je een community-schema bijdragen? Open een issue met een link naar je repository, of dien een PR in door een rij aan deze tabel toe te voegen.

---

Zie ook

• CLI-referentie: Schemaopdrachten - Volledige opdrachtdocumentatie