Workflows

Deze gids behandelt veelvoorkomende workflow-patronen voor OpenSpec en wanneer je elk patroon gebruikt. Voor basisconfiguratie, zie Aan de slag. Voor commandoreferentie, zie Commands.

Filosofie: Acties, Geen Fasen

Traditionele workflows dwingen je door fasen: planning, dan implementatie, dan klaar. Maar echt werk past niet netjes in hokjes.

OPSX hanteert een andere aanpak:

text

Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

Belangrijkste principes:

Acties, geen fasen - Commands zijn dingen die je kunt doen, geen fases waarin je vastzit
Afhankelijkheden zijn mogelijkmakers - Ze tonen wat mogelijk is, niet wat er vervolgens verplicht is

Aanpassing: OPSX-workflows worden aangestuurd door schema's die artefactreeksen definiëren. Zie Aanpassing voor details over het maken van aangepaste schema's.

Workflow in één oogopslag

De standaard workflow blijft flexibel: exploratie en verificatie zijn optioneel, en je kunt planningsartefacten bijwerken wanneer de implementatie iets nieuws aan het licht brengt.

mermaid

flowchart TD
    Idea["Idee of probleem"] --> Explore["/opsx:explore<br/>(optioneel)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planningsartefacten<br/>gereed?"}
    Review -->|"Verfijnen"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implementeren"| Apply["/opsx:apply"]
    Apply -->|"Plan gewijzigd"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optioneel, eigen selectie)"]
    Apply --> Sync["/opsx:sync<br/>(optioneel vóór archivering)"]
    Verify --> Verified{"Gereed om te archiveren?"}
    Verified -->|"Implementatie corrigeren"| Apply
    Verified -->|"Plan herzien"| Update
    Verified -->|"Gereed"| Sync
    Verified -->|"Gereed"| Archive
    Sync --> Archive

De AI-assistent stuurt de workflow, terwijl de CLI zorgt voor deterministische scaffolding, status en artefactinstructies:

mermaid

sequenceDiagram
    actor Mens
    participant Assistant as AI-assistent
    participant CLI as OpenSpec CLI
    participant Files as Planning- en implementatiebestanden

    Mens->>Assistant: /opsx:propose "wijziging"
    Assistant->>CLI: openspec new change
    CLI->>Files: Wijzigingsmetadata scaffolden
    Assistant->>CLI: Status en artefactinstructies opvragen
    CLI-->>Assistant: Buildvolgorde, paden en sjablonen
    Assistant->>Files: Schema-gedefinieerde planningsartefacten schrijven
    Assistant-->>Mens: Artefacten ter beoordeling presenteren

    Mens->>Assistant: /opsx:apply
    Assistant->>CLI: Applicatie-instructies opvragen
    CLI-->>Assistant: Contextbestanden en taakstatus
    Assistant->>Files: Taken implementeren en checkboxes bijwerken
    Assistant-->>Mens: Implementatiestatus rapporteren

    Mens->>Assistant: /opsx:archive
    Assistant->>CLI: Archiefinvoer en artefactstatus opvragen
    CLI-->>Assistant: Planningpaden en artefactvoltooiing
    Assistant->>Files: Taakstatus lezen en deltaspecificaties vergelijken
    opt Deltaspecificaties bestaan
        Assistant-->>Mens: Synchronisatie aanbieden vóór archivering
        alt Sync geaccepteerd
            Mens->>Assistant: Sync bevestigen
            Assistant->>Files: Deltaspecificaties samenvoegen in hoofdspecificaties
        else Sync overgeslagen
            Mens->>Assistant: Archiveren zonder synchronisatie
        end
    end
    Assistant->>Files: De wijziging naar het archief verplaatsen
    Assistant-->>Mens: Archieflocatie en synchronisatieresultaat rapporteren

    Note over Mens,CLI: CLI-alternatief: openspec archive change-name --yes slaat bevestigingsprompts over. Het valideert nog steeds, past vervolgens eventuele deltaspecificaties toe en archiveert

Twee modi

Standaard snelle pad (`core`-profiel)

Nieuwe installaties standaardiseren op core, dat biedt:

/opsx:explore
/opsx:propose
/opsx:apply
/opsx:update
/opsx:sync
/opsx:archive

Typische flow:

text

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (optioneel)

Begin met verkennen (de gewoonte die het waard is om te vormen)

/opsx:explore maakt deel uit van het standaardprofiel, geen geavanceerde toevoeging. Het is de zet die je doet wanneer je een probleem hebt maar nog geen plan—wat met een AI-assistent meestal het geval is.

text

Jij: /opsx:explore

AI:  Wat wil je verkennen?

Jij: Onze zoekresultaten voelen verouderd aan. Ik weet niet zeker of het caching,
     indexing, of de query zelf is.

AI:  Laat me kijken... [leest de zoekservice en cachelaag]
     Het is de index: die wordt alleen 's nachts herbouwd, dus bewerkingen komen
     pas de volgende dag in de resultaten. Twee opties: herbouwen bij schrijven
     (eenvoudig, meer belasting) of een korte-TTL-cache-invalidatie (meer
     bewegende delen, minder belasting). Gezien je schrijfvolume laag is, is
     herbouwen-bij-schrijven de schonere oplossing. Wil je het afbakenen?

Jij: Ja.

Jij: /opsx:propose rebuild-search-index-on-write

Explore maakt geen artefacten aan en schrijft geen code. Het is een vrijblijvend, risicoloos gesprek dat een vaag probleem omzet in een precieze wijziging, zodat het voorstel dat volgt scherp is. Weet je al precies wat je wilt? Sla het over en ga direct naar /opsx:propose. Volledige gids: Eerst verkennen.

Uitgebreide/volledige workflow (eigen selectie)

Als je expliciete scaffold-en-build-commando's wilt (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), schakel ze dan in met:

bash

openspec config profile
openspec update

Workflowpatronen (uitgebreide modus)

Snelle feature

Wanneer je weet wat je wilt bouwen en het alleen nog moet uitvoeren:

text

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Voorbeeldgesprek:

text

Jij: /opsx:new add-logout-button

AI:  Aangemaakt openspec/changes/add-logout-button/
     Gereed om te maken: proposal

Jij: /opsx:ff

AI:  Alle planningsartefacten maken...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Gereed voor implementatie!

Jij: /opsx:apply

AI:  Taken doorwerken...
     ✓ Uitlogknop aan header toegevoegd
     ✓ Sessie wissen geïmplementeerd
     ✓ Bevestigingsdialoog toegevoegd
     Alle taken voltooid!

Jij: /opsx:archive

AI:  ✓ Specificaties samengevoegd
     ✓ Wijziging gearchiveerd

Het beste voor: Kleine tot middelgrote features, bugfixes, eenvoudige wijzigingen.

Verkennend

Wanneer vereisten onduidelijk zijn of je eerst moet onderzoeken:

text

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Voorbeeldgesprek:

text

Jij: /opsx:explore

AI:  Wat wil je verkennen?

Jij: Ik wil de paginalaadsnelheid verbeteren, maar ik weet niet zeker
     waar de knelpunten zitten.

AI:  Laat me helpen onderzoeken...
     [Analyseert bundelgroottes, identificeert trage queries, beoordeelt
     component-renderpatronen]

     Ik heb drie belangrijke knelpunten gevonden:
     1. Grote, niet-geoptimaliseerde afbeeldingen
     2. Synchronous data fetching in ProductList
     3. Re-renders door contextwijzigingen

     Welke wil je als eerste aanpakken?

Jij: Laten we het data-fetching-probleem aanpakken.

Jij: /opsx:new optimize-product-list-fetching

AI:  Wijziging aangemaakt. Gereed om te maken: proposal

Jij: /opsx:continue

AI:  Voorstel maken op basis van onze verkenning...
     [Schrijft voorstel met inzichten uit het onderzoek]

     Gereed om te maken: specs, design
     Welke wil je als volgende?

Jij: /opsx:continue

AI:  Specificaties maken...

Het beste voor: Prestatieoptimalisatie, debugging, architectuurbeslissingen, onduidelijke vereisten.

Parallelle wijzigingen

Aan meerdere wijzigingen tegelijk werken:

text

Wijziging A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in uitvoering)
                                         │
                                    contextwissel
                                         │
Wijziging B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Voorbeeldgesprek:

text

Jij: Ik werk aan add-dark-mode maar ben onderbroken voor een bugfix

Jij: /opsx:new fix-login-redirect

AI:  Aangemaakt openspec/changes/fix-login-redirect/

Jij: /opsx:ff

AI:  ✓ Planningsartefacten aangemaakt

Jij: /opsx:apply

AI:  Werken aan fix-login-redirect...
     [Implementeert de fix]
     Alle taken voltooid!

Jij: /opsx:archive

AI:  ✓ fix-login-redirect gearchiveerd

Jij: Laten we teruggaan naar dark mode

Jij: /opsx:apply add-dark-mode

AI:  add-dark-mode hervatten...
     Verdergaan bij taak 2.3: Header bijwerken...

Het beste voor: Parallelle werkstromen, dringende onderbrekingen, teamsamenwerking.

Wanneer je meerdere voltooide wijzigingen hebt, gebruik dan /opsx:bulk-archive:

text

Jij: /opsx:bulk-archive

AI:  3 voltooide wijzigingen gevonden:
     - add-dark-mode (alle taken gedaan)
     - fix-login-redirect (alle taken gedaan)
     - update-footer (alle taken gedaan)

     Controleren op spec-conflicten...
     ⚠ add-dark-mode en update-footer raken beide specs/ui/

     Codebase inspecteren om op te lossen...
     Beide wijzigingen zijn geïmplementeerd. Zal ze in chronologische volgorde toepassen.

     Alle 3 wijzigingen archiveren?

Jij: Ja

AI:  ✓ add-dark-mode gearchiveerd
     ✓ fix-login-redirect gearchiveerd
     ✓ update-footer gearchiveerd
     Specificaties samengevoegd in volgorde: add-dark-mode → update-footer

Bulk archive detecteert wanneer meerdere wijzigingen dezelfde specificaties raken en lost conflicten op door te controleren wat daadwerkelijk is geïmplementeerd.

Een wijziging voltooien

De aanbevolen voltooiingsflow:

text

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              valideert          biedt sync aan
              implementatie      indien nodig

Verifiëren: controleer je werk

/opsx:verify valideert de implementatie tegen je artefacten op drie dimensies:

text

Jij: /opsx:verify

AI:  add-auth verifiëren...

     VOLLEDIGHEID
     ✓ Alle 12 taken in tasks.md zijn aangevinkt
     ✓ Alle vereisten in specs hebben overeenkomstige code
     ⚠ Scenario "Sessietime-out na inactiviteit" niet getest

     CORRECTHEID
     ✓ Implementatie komt overeen met de intentie van de spec
     ✓ Randgevallen uit scenario's worden afgehandeld
     ✓ Fouttoestanden komen overeen met spec-definities

     COHERENTIE
     ✓ Ontwerpbeslissingen weerspiegeld in codestructuur
     ✓ Naamgevingsconventies consistent met design.md
     ⚠ Ontwerp vermeldt "event-driven" maar implementatie gebruikt polling

     SAMENVATTING
     ─────────────────────────────
     Kritieke problemen: 0
     Waarschuwingen: 2
     Gereed om te archiveren: Ja (met waarschuwingen)

     Aanbevelingen:
     1. Test toevoegen voor het sessietime-out-scenario
     2. Overweeg refactoring naar event-driven zoals ontworpen, of werk design.md bij

Wat verify controleert:

Dimensie	Wat het valideert
Volledigheid	Alle taken gedaan, alle vereisten geïmplementeerd, scenario's gedekt
Correctheid	Implementatie komt overeen met spec-intentie, randgevallen afgehandeld
Coherentie	Ontwerpbeslissingen weerspiegeld in code, patronen consistent

Verify blokkeert archivering niet, maar brengt problemen aan het licht die je wellicht eerst wilt aanpakken.

Archiveren: de wijziging finaliseren

/opsx:archive voltooit de wijziging en verplaatst deze naar het archief:

text

Jij: /opsx:archive

AI:  add-auth archiveren...

     Artefactstatus:
     ✓ proposal.md bestaat
     ✓ specs/ bestaat
     ✓ design.md bestaat
     ✓ tasks.md bestaat (12/12 taken voltooid)

     Deltaspecificaties: nog niet gesynchroniseerd naar hoofd
     → Wil je nu synchroniseren?

Jij: Ja

AI:  ✓ Specificaties gesynchroniseerd naar openspec/specs/auth/spec.md
     ✓ Verplaatst naar openspec/changes/archive/2025-01-24-add-auth/

     Wijziging succesvol gearchiveerd.

Archive vraagt om bevestiging als specificaties niet gesynchroniseerd zijn. Het blokkeert niet bij onvolledige taken, maar waarschuwt wel.

Wanneer wat gebruiken

`/opsx:ff` vs `/opsx:continue`

Situatie	Gebruik
Duidelijke vereisten, klaar om te bouwen	`/opsx:ff`
Verkennen, elke stap willen beoordelen	`/opsx:continue`
Voorstel willen itereren vóór specificaties	`/opsx:continue`
Tijdsdruk, snel moeten handelen	`/opsx:ff`
Complexe wijziging, controle willen	`/opsx:continue`

Vuistregel: Als je de volledige omvang vooraf kunt beschrijven, gebruik dan /opsx:ff. Als je al doende uitzoekt, gebruik dan /opsx:continue.

Wanneer bijwerken vs. opnieuw beginnen

Een veelgestelde vraag: wanneer is het bijwerken van een bestaande wijziging acceptabel, en wanneer moet je een nieuwe starten?

De bestaande wijziging bijwerken wanneer:

Dezelfde intentie, verfijnde uitvoering
De scope versmalt (MVP eerst, rest later)
Leergedreven correcties (codebase is anders dan verwacht)
Ontwerpaanpassingen op basis van implementatie-ontdekkingen

Een nieuwe wijziging starten wanneer:

De intentie fundamenteel is veranderd
De scope is geëxplodeerd naar volledig ander werk
De oorspronkelijke wijziging als "klaar" op zichzelf kan worden gemarkeerd
Patches meer zouden verwarren dan verduidelijken

text

                     ┌─────────────────────────────────────┐
                     │     Is dit hetzelfde werk?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Zelfde intentie?   >50% overlap?     Kan het origineel
          Zelfde probleem?   Zelfde scope?     "klaar" zijn zonder
                 │                  │          deze wijzigingen?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      JA               NEE JA           NEE  NEE              JA
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    BIJWERKEN         NIEUW  BIJWERKEN  NIEUW  BIJWERKEN     NIEUW

Voorbeeld: "Dark mode toevoegen"

"We moeten ook aangepaste thema's ondersteunen" → Nieuwe wijziging (scope geëxplodeerd)
"Systeemvoorkeurdetectie is moeilijker dan verwacht" → Bijwerken (zelfde intentie)
"Laten we eerst de toggle uitbrengen, voorkeuren later toevoegen" → Bijwerken en archiveren, daarna nieuwe wijziging

Beste werkwijzen

Houd wijzigingen gefocust

Eén logische werkeenheid per wijziging. Als je bezig bent met "functie X toevoegen en ook Y refactoren", overweeg dan twee aparte wijzigingen.

Waarom het belangrijk is:

Makkelijker te beoordelen en te begrijpen
Schonere archiefgeschiedenis
Kan onafhankelijk worden vrijgegeven
Eenvoudigere terugdraaimogelijkheid indien nodig

Gebruik `/opsx:explore` bij onduidelijke vereisten

Voordat je je vastlegt op een wijziging, verken de probleemruimte:

text

Jij: /opsx:explore

AI:  Wat wil je verkennen?

Jij: Hoe moeten we rate limiting voor onze API aanpakken?

AI:  Laat me je huidige opzet en opties onderzoeken...
     [Onderzoekt codebase, overweegt patronen]

     Ik zie drie mogelijke benaderingen:
     1. Middleware-gebaseerd (eenvoudig, per endpoint)
     2. Redis-ondersteund (schaalbaar, gedeelde status)
     3. Token bucket per gebruiker (eerlijk, complex)

     Jullie huidige stack suggereert #1 of #2. Wat is jullie schaal?

Verkenning maakt het denken helder voordat je artefacten aanmaakt.

Verifieer voordat je archiveert

Gebruik /opsx:verify om te controleren of de implementatie overeenkomt met de artefacten:

text

Jij: /opsx:verify

AI:  Verifiëren van add-dark-mode...

     ✓ Alle taken in tasks.md zijn afgevinkt
     ✓ Vereisten in specificaties hebben bijbehorende code
     ✓ Ontwerpbeslissingen zijn terug te vinden in de implementatie

     Klaar om te archiveren!

Vang mismatches op voordat je de wijziging afrondt.

Geef wijzigingen een duidelijke naam

Goede namen maken openspec list bruikbaar:

text

Goed:                          Vermijd:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Commando-overzicht

Voor volledige commandodetails en opties, zie Commands.

Commando	Doel	Wanneer te gebruiken
`/opsx:propose`	Wijziging + planningartefacten aanmaken	Snel standaardpad (`core` profiel)
`/opsx:explore`	Ideeën doordenken met de AI	Begin hiermee als je twijfelt: onduidelijke vereisten, onderzoek, opties vergelijken
`/opsx:new`	Start een wijzigingsscaffold	Uitgebreide modus, expliciete artefactcontrole
`/opsx:continue`	Maak het volgende artefact	Uitgebreide modus, stapsgewijze artefactcreatie
`/opsx:ff`	Maak alle planningartefacten	Uitgebreide modus, duidelijke scope
`/opsx:apply`	Taken implementeren	Klaar om code te schrijven
`/opsx:verify`	Implementatie valideren	Uitgebreide modus, voor archiveren
`/opsx:sync`	Delta-specificaties samenvoegen	Uitgebreide modus, optioneel
`/opsx:archive`	Wijziging afronden	Alle werk is klaar
`/opsx:bulk-archive`	Meerdere wijzigingen archiveren	Uitgebreide modus, parallel werk

Volgende stappen

Goede specificaties schrijven - Hoe een sterke vereiste en scenario eruit zien, en hoe een wijziging op de juiste grootte te houden
Een wijziging beoordelen - De snelle scan van een opgesteld plan voordat er code wordt geschreven
OpenSpec in een team - Hoe wijzigingen in branches en pull requests passen
Commands - Volledige commandoreferentie met opties
Concepten - Diepere duik in specificaties, artefacten en schema's
Aanpassing - Maak eigen workflows

Workflows ​

Filosofie: Acties, Geen Fasen ​

Workflow in één oogopslag ​

Twee modi ​

Standaard snelle pad (core-profiel) ​

Begin met verkennen (de gewoonte die het waard is om te vormen) ​

Uitgebreide/volledige workflow (eigen selectie) ​

Workflowpatronen (uitgebreide modus) ​

Snelle feature ​

Verkennend ​

Parallelle wijzigingen ​

Een wijziging voltooien ​

Verifiëren: controleer je werk ​

Archiveren: de wijziging finaliseren ​

Wanneer wat gebruiken ​

/opsx:ff vs /opsx:continue ​

Wanneer bijwerken vs. opnieuw beginnen ​

Beste werkwijzen ​

Houd wijzigingen gefocust ​

Gebruik /opsx:explore bij onduidelijke vereisten ​

Verifieer voordat je archiveert ​

Geef wijzigingen een duidelijke naam ​

Commando-overzicht ​

Volgende stappen ​

Workflows

Filosofie: Acties, Geen Fasen

Workflow in één oogopslag

Twee modi

Standaard snelle pad (`core`-profiel)

Begin met verkennen (de gewoonte die het waard is om te vormen)

Uitgebreide/volledige workflow (eigen selectie)

Workflowpatronen (uitgebreide modus)

Snelle feature

Verkennend

Parallelle wijzigingen

Een wijziging voltooien

Verifiëren: controleer je werk

Archiveren: de wijziging finaliseren

Wanneer wat gebruiken

`/opsx:ff` vs `/opsx:continue`

Wanneer bijwerken vs. opnieuw beginnen

Beste werkwijzen

Houd wijzigingen gefocust

Gebruik `/opsx:explore` bij onduidelijke vereisten

Verifieer voordat je archiveert

Geef wijzigingen een duidelijke naam

Commando-overzicht

Volgende stappen