TUTORIAL | OpenSpec — wat is het en je eerste change

[WilcoLouwerse]

Achtergrond

OpenSpec (openspec.dev) is de basis van onze spec-driven workflow: requirements en scenario's worden eerst in de spec vastgelegd, daarna pas geïmplementeerd. Veel collega's komen OpenSpec voor het eerst tegen via een openspec/ map of een opsx-skill, zonder een duidelijke leerlijn.

Doel

Een Nederlandstalige, publiek toegankelijke tutorial op conduction.nl/academy die in één korte sessie uitlegt wat OpenSpec is, waarom we het gebruiken, en hoe je je eerste change schrijft. Eventueel opgesplitst in een korte "Wat is OpenSpec?" + een vervolgtutorial "Je eerste OpenSpec change".

Doelgroep

Nieuwe developers en partners die met onze codebases werken. Voorkennis: basis Git en Markdown.

Voorgestelde structuur (chaining)

Voorstel: twee korte tutorials.

1. Wat is OpenSpec? — concept, waarom spec-first, terminologie (capabilities, requirements, scenarios, changes), verschil met losse README's. Linkt door naar 2.
2. Je eerste OpenSpec change — een change starten met /opsx-new, een spec-delta schrijven, tasks genereren, en valideren.

Optioneel deel 3: Spec-coverage in een bestaande codebase (retrofit) — voor later.

Bestaande documentatie (referenties)

In /home/wilco/.github/docs/claude/ staat al materiaal:

• docs/claude/commands-openspec.md
• docs/claude/writing-specs.md
• docs/claude/retrofit.md
• docs/claude/writing-docs.md

Externe referentie: openspec.dev.

Pluvo-vragen (minimaal 4)

Voorbeelden:

1. Wat is het kernverschil tussen een capability/spec en een change?
2. Waarom schrijven we eerst een spec-delta voordat we code aanpassen?
3. Wat zijn de drie bouwstenen van een requirement (en wat doet een scenario)?
4. Waar staan de openstaande changes in een project, en hoe valideer je ze?
5. Wanneer archiveer je een change?

Op te leveren

• Tutorial(s) in MDX op ConductionNL/conduction-website onder academy/
• Cross-links naar gerelateerde tutorials (Hydra, Workstation Setup)
• Minimaal 4 Pluvo-vragen per deel
• Linkcheck
• Peer review

Schrijfstijl

Volg de Conduction-schrijfstijl (zie identity.conduction.nl). Voorbeeldstructuur: Bestanden bij een Woo-publicatie uploaden. Houd de tutorials kort; liever twee gekoppelde dan één lange.

Tijdregistratie

Uren op dit issue boeken op de Jira-issue van het SLIM-account.

[WilcoLouwerse]

Korte update — branch tutorial/openspec-introductie klaar met parts 1 + 2 (commit b3864a1). PR volgt zo.