OpenSpec

Migreren naar OPSX ​

Deze handleiding helpt u bij de overgang van de legacy OpenSpec-workflow naar OPSX. De migratie is ontworpen om soepel te verlopen—uw bestaande werk wordt behouden en het nieuwe systeem biedt meer flexibiliteit.

Wat verandert er? ​

OPSX vervangt de oude fase-gebaseerde workflow door een vloeibare, actie-gebaseerde aanpak. Hier is de belangrijkste verschuiving:

AspectLegacyOPSX
Commando's/openspec:proposal, /openspec:apply, /openspec:archiveStandaard: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (uitgebreide workflow-commando's optioneel)
WorkflowAlle artefacten tegelijk aanmakenIncrementeel of tegelijk aanmaken—uw keuze
TerugkerenOnhandige fasepoortenNatuurlijk—elk artefact op elk moment bijwerken
AanpassingVaste structuurSchema-gedreven, volledig aanpasbaar
ConfiguratieCLAUDE.md met markers + project.mdSchone configuratie in openspec/config.yaml

De filosofische verandering: Werk is niet lineair. OPSX doet niet meer alsof het dat wel is.

Voordat u begint ​

Uw bestaande werk is veilig ​

Het migratieproces is ontworpen met behoud in gedachten:

  • Actieve wijzigingen in openspec/changes/ — Volledig behouden. U kunt deze voortzetten met OPSX-commando's.
  • Gearchiveerde wijzigingen — Onaangeroerd. Uw geschiedenis blijft intact.
  • Hoofdspecificaties in openspec/specs/ — Onaangeroerd. Dit zijn uw bron van waarheid.
  • Uw inhoud in CLAUDE.md, AGENTS.md, enz. — Behouden. Alleen de OpenSpec-markerblokken worden verwijderd; alles wat u hebt geschreven blijft staan.

Wat wordt verwijderd ​

Alleen OpenSpec-beheerde bestanden die worden vervangen:

WatWaarom
Verouderde slash-commando-mappen/bestandenVervangen door het nieuwe skills-systeem
openspec/AGENTS.mdVerouderde workflow-trigger
OpenSpec-markers in CLAUDE.md, AGENTS.md, enz.Niet langer nodig

Verouderde commandolocaties per tool (voorbeelden — uw tool kan verschillen):

  • Claude Code: .claude/commands/openspec/
  • Cursor: .cursor/commands/openspec-*.md
  • Devin Desktop, voorheen Windsurf: .windsurf/workflows/openspec-*.md
  • Cline: .clinerules/workflows/openspec-*.md
  • Roo: .roo/commands/openspec-*.md
  • GitHub Copilot: .github/prompts/openspec-*.prompt.md (alleen IDE-extensies; niet ondersteund in Copilot CLI)
  • Codex: OpenSpec gebruikt nu de canonieke .agents/skills/openspec-*-padstructuur. OpenSpec-beheerde SKILL.md-bestanden onder het vroegere .codex/skills-pad worden alleen gereconcilieerd nadat vervangers bestaan; aangepaste bestanden en afwijkende kopieën blijven op hun plaats. Als een gemarkeerde .agents-boom al OpenSpec-skills bevat, behoudt OpenSpec de bestaande Codex ($openspec-*) of generieke (/openspec-*) weergave in plaats van te gokken op basis van de verouderde map. Selecteer codex expliciet met openspec init om het eigendom over te schakelen. Opruiming van verouderde prompts richt zich nog steeds alleen op de toegestane bestandsnamen van OpenSpec in $CODEX_HOME/prompts of ~/.codex/prompts.
  • En anderen (Augment, Continue, Amazon Q, enz.)

De migratie detecteert welke tools u hebt geconfigureerd en ruimt hun verouderde bestanden op.

De verwijderlijst kan lang lijken, maar dit zijn allemaal bestanden die OpenSpec oorspronkelijk heeft aangemaakt. Uw eigen inhoud wordt nooit verwijderd.

Wat uw aandacht vereist ​

Eén bestand vereist handmatige migratie:

openspec/project.md — Dit bestand wordt niet automatisch verwijderd omdat het projectcontext kan bevatten die u hebt geschreven. U moet:

  1. De inhoud ervan beoordelen
  2. Nuttige context verplaatsen naar openspec/config.yaml (zie de richtlijnen hieronder)
  3. Het bestand verwijderen wanneer u klaar bent

Waarom wij deze wijziging hebben doorgevoerd:

Het oude project.md was passief — agents konden het lezen, hoefden het niet te lezen, en konden vergeten wat ze hadden gelezen. We vonden de betrouwbaarheid inconsistent.

De nieuwe config.yaml-context wordt actief geïnjecteerd in elke OpenSpec-planningsaanvraag. Dit betekent dat uw projectconventies, tech stack en regels altijd aanwezig zijn wanneer de AI artefacten aanmaakt. Hogere betrouwbaarheid.

De afweging:

Omdat context in elke aanvraag wordt geïnjecteerd, wilt u beknopt blijven. Focus op wat echt belangrijk is:

  • Tech stack en belangrijke conventies
  • Niet voor de hand liggende beperkingen die de AI moet kennen
  • Regels die eerder vaak werden genegeerd

Maak u geen zorgen over het perfect krijgen. We leren nog steeds wat hier het beste werkt, en we zullen de contextinjectie verbeteren naarmate we experimenteren.

De migratie uitvoeren ​

Zowel openspec init als openspec update detecteren verouderde bestanden en begeleiden u door hetzelfde opruimingsproces. Gebruik wat bij uw situatie past:

  • Nieuwe installaties gebruiken standaard profiel core (propose, explore, apply, update, sync, archive).
  • Gemigreerde installaties behouden uw eerdere geïnstalleerde workflows door een custom-profiel te schrijven wanneer nodig.

openspec init gebruiken ​

Voer dit uit als u nieuwe tools wilt toevoegen of wilt herconfigureren welke tools zijn ingesteld:

bash
openspec init

Het init-commando detecteert verouderde bestanden en begeleidt u door de opruiming:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

Wat er gebeurt als u ja zegt:

  1. Verouderde slash-commando-mappen worden verwijderd
  2. OpenSpec-markers worden verwijderd uit CLAUDE.md, AGENTS.md, enz. (uw inhoud blijft staan)
  3. openspec/AGENTS.md wordt verwijderd
  4. Nieuwe skills worden geïnstalleerd in .claude/skills/
  5. openspec/config.yaml wordt aangemaakt met een standaard-schema

openspec update gebruiken ​

Voer dit uit als u alleen wilt migreren en uw bestaande tools naar de nieuwste versie wilt bijwerken:

bash
openspec update

Het update-commando detecteert en ruimt ook verouderde artefacten op, en werkt daarna gegenereerde skills/commando's bij om ze af te stemmen op uw huidige profiel en leveringsinstellingen.

Niet-interactieve / CI-omgevingen ​

Voor gescripteerde migraties:

bash
openspec init --force --tools claude

De --force-vlag slaat prompts over en accepteert opruiming automatisch.

Dit omvat opruiming van OpenSpec-beheerde Codex-promptbestanden in de globale Codex-promptmap. Opruiming richt zich alleen op de toegestane verouderde Codex-promptbestandsnamen van OpenSpec, verwijdert ze alleen nadat vervangende .agents/skills/openspec-*-skills bestaan, en behoudt alle andere bestanden.

project.md migreren naar config.yaml ​

Het oude openspec/project.md was een vrijvormig markdown-bestand voor projectcontext. Het nieuwe openspec/config.yaml is gestructureerd en — cruciaal — wordt geïnjecteerd in elke planningsaanvraag, zodat uw conventies altijd aanwezig zijn wanneer de AI werkt.

Vóór (project.md) ​

markdown
# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

Na (config.yaml) ​

yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

Belangrijke verschillen ​

project.mdconfig.yaml
Vrijvormig markdownGestructureerd YAML
Eén tekstblokAparte context en regels per artefact
Onduidelijk wanneer het wordt gebruiktContext verschijnt in ALLE artefacten; regels verschijnen alleen in overeenkomende artefacten
Geen schemakeuzeExpliciet schema:-veld stelt standaardworkflow in

Wat te behouden, wat te laten vallen ​

Wees selectief bij de migratie. Vraag uzelf: "Heeft de AI dit nodig voor elke planningsaanvraag?"

Goede kandidaten voor context:

  • Tech stack (talen, frameworks, databases)
  • Belangrijke architectuurpatronen (monorepo, microservices, enz.)
  • Niet voor de hand liggende beperkingen ("we kunnen bibliotheek X niet gebruiken omdat...")
  • Kritieke conventies die vaak worden genegeerd

Verplaats naar rules:

  • Artefact-specifieke opmaak ("gebruik Given/When/Then in specificaties")
  • Reviewcriteria ("voorstellen moeten een rollback-plan bevatten")
  • Deze verschijnen alleen voor het overeenkomende artefact, waardoor andere aanvragen lichter blijven

Volledig weglaten

  • Algemene best practices die de AI al kent
  • Uitgebreide uitleg die samengevat kan worden
  • Historische context die geen invloed heeft op het huidige werk

Migratiestappen ​

  1. config.yaml aanmaken (als het nog niet door init is aangemaakt):

    yaml
    schema: spec-driven

  2. Uw context toevoegen (wees beknopt — dit gaat in elke aanvraag):

    yaml
    context: |
  Uw projectachtergrond komt hier.
  Focus op wat de AI echt moet weten.

  3. Regels per artefact toevoegen (optioneel):

    yaml
    rules:
  proposal:
    - Uw voorstel-specifieke richtlijnen
  specs:
    - Uw specificatie-schrijfrules

  4. project.md verwijderen zodra u alles nuttige hebt verplaatst.

Denk er niet te lang over na. Begin met de essentials en iterer. Als u merkt dat de AI iets belangrijks mist, voeg het toe. Als context te opgeblazen voelt, knip het terug. Dit is een levend document.

Hulp nodig? Gebruik deze prompt ​

Als u zich afvraagt hoe u uw project.md moet distilleren, vraag uw AI-assistent:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

De AI helpt u te bepalen wat essentieel is en wat kan worden teruggedrongen.

De nieuwe commando's ​

Beschikbaarheid van commando's is profielafhankelijk:

Standaard (core-profiel):

CommandoDoel
/opsx:proposeMaak een wijziging aan en genereer planningsartefacten in één stap
/opsx:exploreDenk na over ideeën zonder structuur
/opsx:applyImplementeer taken uit tasks.md
/opsx:updateHerzie de planningsartefacten van een wijziging en houd ze coherent
/opsx:syncVoeg delta-specificaties samen met hoofdspecificaties
/opsx:archiveFinaliseer en archiveer de wijziging

Uitgebreide workflow (aangepaste selectie):

CommandoDoel
/opsx:newStart een nieuw wijzigingsscaffold
/opsx:continueMaak het volgende artefact aan (één tegelijk)
/opsx:ffFast-forward — maak planningsartefacten tegelijk aan
/opsx:verifyValideer of de implementatie overeenkomt met specificaties
/opsx:bulk-archiveArchiveer meerdere wijzigingen tegelijk
/opsx:onboardBegeleide eind-tot-eind onboardingsworkflow

Schakel uitgebreide commando's in met openspec config profile, en voer daarna openspec update uit.

Commandomapping vanaf verouderde versie ​

VerouderdOPSX-equivalent
/openspec:proposal/opsx:propose (standaard) of /opsx:new dan /opsx:ff (uitgebreid)
/openspec:apply/opsx:apply
/openspec:archive/opsx:archive

Nieuwe mogelijkheden ​

Deze mogelijkheden maken deel uit van de uitgebreide workflow-commandoset.

Granulaire artefactcreatie:

/opsx:continue

Maakt één artefact tegelijk aan op basis van afhankelijkheden. Gebruik dit wanneer u elke stap wilt beoordelen.

Verkenmodus:

/opsx:explore

Denk na over ideeën met een partner voordat u zich committeert aan een wijziging.

De nieuwe architectuur begrijpen ​

Van gefaseerd naar vloeiend ​

De oude workflow forceerde een lineaire voortgang:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  PLANNINGS-  │ ───► │ IMPLEMENTATIE│ ───► │ ARCHIVERINGS-│
│    FASE      │      │     FASE     │      │     FASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Als je in de implementatiefase zit en realiseert dat het ontwerp verkeerd is?
Helaas. Fase-poorten laten je niet eenvoudig teruggaan.

OPSX gebruikt acties, geen fasen:

         ┌───────────────────────────────────────────────┐
         │           ACTIES (geen fasen)                 │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │               willekeurige volgorde           │
         └───────────────────────────────────────────────┘

Afhankelijkheidsgraaf ​

Artefacten vormen een gerichte graaf. Afhankelijkheden zijn mogelijkmakers, geen poorten:

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

Wanneer je /opsx:continue uitvoert, controleert het wat klaar is en biedt het volgende artefact aan. Je kunt ook meerdere gereedstaande artefacten in willekeurige volgorde aanmaken.

Skills versus Commando's ​

Het oude systeem gebruikte tool-specifieke opdrachtbestanden:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX gebruikt de opkomende skills-standaard:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Skills worden herkend in meerdere AI-codeertools en bieden rijkere metadata.

Codex is volledig op skills gebaseerd in OPSX. OpenSpec genereert niet langer aangepaste Codex-promptbestanden; gebruik in plaats daarvan de gegenereerde .agents/skills/openspec-*-mappen.

Bestaande wijzigingen voortzetten ​

Je lopende wijzigingen werken naadloos met OPSX-commando's.

Heb je een actieve wijziging van de oude workflow?

/opsx:apply add-my-feature

OPSX leest de bestaande artefacten en gaat verder waar je gebleven was.

Wil je meer artefacten toevoegen aan een bestaande wijziging?

/opsx:continue add-my-feature

Toont wat klaar is om aan te maken op basis van wat al bestaat.

Wil je de status zien?

bash
openspec status --change add-my-feature

Het nieuwe configuratiesysteem ​

Structuur van config.yaml ​

yaml
# Vereist: Standaardschema voor nieuwe wijzigingen
schema: spec-driven

# Optioneel: Projectcontext (max 50KB)
# Wordt in ALLE artefactinstructies geïnjecteerd
context: |
  Your project background, tech stack,
  conventions, and constraints.

# Optioneel: Regels per artefact
# Wordt alleen in overeenkomende artefacten geïnjecteerd
rules:
  proposal:
    - Inclusief terugdraaiplan
  specs:
    - Gebruik het Given/When/Then-formaat
  design:
    - Documenteer fallback-strategieën
  tasks:
    - Opsplitsen in brokken van maximaal 2 uur

Schemaresolutie ​

Bij het bepalen welk schema te gebruiken, controleert OPSX in volgorde:

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

Beschikbare schema's ​

SchemaArtefactenMeest geschikt voor
spec-drivenproposal → specs → design → tasksDe meeste projecten

Toon alle beschikbare schema's:

bash
openspec schemas

Aangepaste schema's ​

Maak je eigen workflow:

bash
openspec schema init my-workflow

Of fork een bestaande:

bash
openspec schema fork spec-driven my-workflow

Zie Aanpassingen voor details.

Probleemoplossing ​

"Oude bestanden gedetecteerd in niet-interactieve modus" ​

Je draait in een CI- of niet-interactieve omgeving. Gebruik:

bash
openspec init --force

Commando's verschijnen niet na migratie ​

Herstart je IDE. Skills worden gedetecteerd bij het opstarten.

"Onbekende artefact-ID in regels" ​

Controleer of je rules:-sleutels overeenkomen met de artefact-ID's van je schema:

  • spec-driven: proposal, specs, design, tasks

Voer dit uit om geldige artefact-ID's te zien:

bash
openspec schemas --json

Configuratie wordt niet toegepast ​

  1. Zorg ervoor dat het bestand op openspec/config.yaml staat (niet .yml)
  2. Valideer de YAML-syntax
  3. Configuratiewijzigingen worden onmiddellijk van kracht—geen herstart nodig

project.md niet gemigreerd ​

Het systeem behoudt project.md bewust omdat het je eigen inhoud kan bevatten. Bekijk het handmatig, verplaats nuttige onderdelen naar config.yaml, en verwijder het daarna.

Wil je zien wat er zou worden opgeschoond? ​

Voer init uit en weiger de opschoonprompt—je ziet de volledige detectiesamenvatting zonder dat er wijzigingen worden aangebracht.

Snel referentie ​

Bestanden na migratie ​

project/
├── openspec/
│   ├── specs/                    # Ongewijzigd
│   ├── changes/                  # Ongewijzigd
│   │   └── archive/              # Ongewijzigd
│   └── config.yaml               # NIEUW: Projectconfiguratie
├── .claude/
│   └── skills/                   # NIEUW: OPSX skills
│       ├── openspec-propose/     # default core profile
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # uitgebreid profiel voegt new/continue/ff/etc. toe
├── CLAUDE.md                     # OpenSpec-markeringen verwijderd, jouw inhoud behouden
└── AGENTS.md                     # OpenSpec-markeringen verwijderd, jouw inhoud behouden

Wat is verdwenen ​

  • .claude/commands/openspec/ — vervangen door .claude/skills/
  • openspec/AGENTS.md — verouderd
  • openspec/project.md — migreer naar config.yaml, verwijder daarna
  • OpenSpec-markeringsblokken in CLAUDE.md, AGENTS.md, etc.

Commandospiekbriefje ​

/opsx:propose      Snel starten (standaard kernprofiel)
/opsx:apply        Taken implementeren
/opsx:archive      Afronden en archiveren

# Uitgebreide workflow (indien ingeschakeld):
/opsx:new          Een wijziging opzetten
/opsx:continue     Volgend artefact aanmaken
/opsx:ff           Planartefacten aanmaken

Hulp verkrijgen ​