From be121efc8bc40b6ca958a896a70b99b1387c4908 Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Fri, 14 Aug 2026 18:20:16 +0200 Subject: [PATCH 1/8] docs: ontwerp CLAUDE.md-baseline en sessie-lifecycle-skills Legt vast: worktree- en plan-skills vendoren uit superpowers (MIT), brainstorm koppelen aan /plan, een minimale CLAUDE.md-template als werkafspraak op niveau Experiment, en cedafy-claude-md om die template op bestaande repos toe te passen met AskUserQuestion bij conflicten. Co-Authored-By: Claude Opus 5 (1M context) --- .../2026-08-14-claude-md-baseline-design.md | 205 ++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 docs/specs/2026-08-14-claude-md-baseline-design.md diff --git a/docs/specs/2026-08-14-claude-md-baseline-design.md b/docs/specs/2026-08-14-claude-md-baseline-design.md new file mode 100644 index 0000000..5134349 --- /dev/null +++ b/docs/specs/2026-08-14-claude-md-baseline-design.md @@ -0,0 +1,205 @@ +# CLAUDE.md-baseline en sessie-lifecycle-skills + +**Datum:** 2026-08-14 · **Status:** ontwerp, goedgekeurd · **Eigenaar:** [@CorneeldH](https://github.com/CorneeldH) + +## Probleem + +Drie dingen die nu ontbreken of botsen: + +1. **Geen CEDA-brede CLAUDE.md.** Elke repo verzint z'n eigen, of heeft er geen. Werk dat elke sessie opnieuw uitgelegd moet worden. +2. **Twee momenten in het werk worden structureel gemist.** Aan het begin: isolatie in een worktree, en nadenken vóór bouwen. Aan het eind: terugkijken en de context opschonen in plaats van doorrollen met een volle context. +3. **Skill-dubbeling.** De CEDA-skill `brainstorm` is een bijna-kloon van `superpowers:brainstorming`, terwijl twee superpowers-skills die CEDA wél mist (`using-git-worktrees`, `writing-plans`) niet beschikbaar zijn voor het team — superpowers is een persoonlijke plugin, geen org-tooling. + +## Uitgangspunten + +Deze zijn vastgesteld tijdens de brainstorm en liggen vast. + +- **Doelgroep is het CEDA-team**, niet één persoon. Alles wat we opleveren moet werken voor iemand zonder persoonlijke plugins. Distributie loopt via `cedanl/.github` → dev-dots-container. +- **Vendoren, niet dedupliceren.** `brainstorm` blijft bestaan; iemand heeft eraan gewerkt. We vullen aan wat ontbreekt. +- **Het sessie-einde wordt een CLAUDE.md-regel, geen hook.** Bewust advies in plaats van dwang, om mee te starten. +- **Claude besluit zelf dát het een eindpunt is, maar voert niets uit.** De gebruiker kiest of reflectie en `/clear` gebeuren. +- **De template gaat mee bij repo-init.** Elke repo bezit z'n eigen CLAUDE.md; geen centrale import. +- **CLAUDE.md blijft minimaal.** Alles wat maar soms relevant is, wordt een skill. + +### Waarom minimaal + +Uit de Claude Code-documentatie: CLAUDE.md wordt elke sessie geladen, dus alleen wat breed geldt hoort erin; domeinkennis en incidentele workflows horen in skills, die on-demand laden. "The over-specified CLAUDE.md" staat expliciet in de lijst met veelgemaakte fouten — te lang betekent dat Claude de helft negeert. De toets per regel is: *zou weglaten hiervan tot een fout leiden?* + +### Waarom de sessie-lifecycle dan wél in CLAUDE.md hoort + +Skills triggeren automatisch op hun `description`, gematcht tegen wat de gebruiker zegt. Dat werkt voor "maak een presentatie" of "welke grafiek past hier". Het werkt niet voor triggers die aan een *moment* hangen in plaats van aan een uiting: er is geen zin die de gebruiker uitspreekt bij "we staan op een natuurlijk eindpunt" of "dit wordt straks een commit". Die momenten hebben een instructie nodig die altijd geladen is. + +Dat is de scheidslijn die dit hele ontwerp draagt: + +| Trigger hangt aan | Voorbeeld | Waar het hoort | +|---|---|---| +| Een uiting van de gebruiker | "maak een marp", "welke grafiek" | skill-`description` | +| Een moment in het werk | vóór de eerste schrijfactie, na het sluiten van een issue | CLAUDE.md | + +Een routingtabel voor skills in CLAUDE.md is dus niet nodig, en meestal een pleister op zwakke descriptions. De juiste reparatie daarvoor is `create-skill` + `skills-ontology`. + +## Onderdeel 1: skills + +### Nieuw: `worktree` + +Port van `superpowers:using-git-worktrees` (MIT, © 2025 Jesse Vincent — attributie in de skill). CEDA-branchnaming (`issue--`, `fix-`). Volgt de bestaande CEDA-skillconventie: `description` en gebruikersgerichte output in het Nederlands, instructietekst in het Engels. + +Behoudt de kern van het origineel: eerst detecteren of je al geïsoleerd zit, dan het native mechanisme (`EnterWorktree`) gebruiken, en pas als laatste `git worktree add`. Die volgorde is niet cosmetisch — `git worktree add` gebruiken terwijl er een native tool is, levert worktrees op die de harness niet kent en niet opruimt. + +### Nieuw: `plan` + +Port van `superpowers:writing-plans`. Twee afwijkingen van het origineel: + +- Schrijft naar `docs/plans/`, niet naar `docs/superpowers/plans/`. +- Koppelt aan `/write-issue` in plaats van aan een losse takenlijst, zodat werk in het CEDA-board landt. + +### Aangepast: `brainstorm` + +Eén sectie erbij: bij een expliciete go is de vervolgstap `/plan`. Nu eindigt de skill in een beslis-samenvatting en houdt het daar op; dat is precies het gat dat `writing-plans` bij superpowers dicht. Geen herschrijving van de rest. + +### Ongemoeid + +`sparren`, `ship` en `branch-pr` overlappen met superpowers-equivalenten, maar zijn CEDA-specifieker en blijven zoals ze zijn. Buiten scope. + +## Onderdeel 2: de template + +Bestand: `werkafspraken/_claude-md-template.md`. De `<...>`-plekken worden per repo ingevuld. + +```markdown +# — projectinstructies + + Stack: . + +## Commando's +- Draaien: `` +- Testen: `` — draai gericht één testbestand, niet de hele suite +- Linten: `` + +## Sessie-start +- **Worktree vóór de eerste schrijfactie.** Elke wijziging die een commit wordt, + begint met `/worktree` op een eigen branch (`issue--`). Niet achteraf + verplaatsen. Uitzonderingen: read-only werk, en als de gebruiker "op main" zegt. +- **Bouw je iets nieuws of verander je gedrag? Eerst `/brainstorm`.** Geen code, + geen bestanden, geen "snelle POC" vóór een expliciete go. +- **Meerdere stappen of meerdere bestanden? Na de go `/plan`.** Is de diff in één + zin te beschrijven, sla planning over. + +## Sessie-einde +Je signaleert dit zelf — de gebruiker hoeft er niet om te vragen. Het is een +natuurlijk eindpunt als één van deze waar is: +- een issue is gesloten of een PR is geopend +- een plan is afgerond +- je bent klaar met een op zichzelf staand stuk werk en het volgende is een ander onderwerp +- je hebt jezelf twee keer op hetzelfde punt moeten corrigeren + +Rol dan **niet** door naar het volgende. Zeg dat je op een natuurlijk eindpunt +staat, en bied twee dingen aan: +- `/sessie-terugblik` draaien — alleen als de gebruiker ja zegt, nooit uit jezelf +- daarna `/clear`, met het volgende commando of doel als kant-en-klare + copy-paste-regel erbij + +Zegt de gebruiker niets over terugblikken en gaat hij door? Prima, laat het los +en kom er niet op terug. + +Uitzondering: een strak gekoppelde vervolgstap (repareren wat je net brak, één +taak over meerdere berichten) blijft in dezelfde sessie. + +Reden: lange sessies stapelen verouderde context op → tragere, slechtere output. + +## Bij compacteren +Bewaar altijd: de lijst gewijzigde bestanden, de testcommando's en openstaande +beslissingen. + +## Skills +De CEDA-skills laden zichzelf op basis van hun description. Roep ze desnoods +expliciet aan met `/naam`. Nooit `gh issue create` — gebruik `/write-issue`. + +## Valkuilen + +``` + +Ingevuld is dat ongeveer 45 regels. + +### Wat er bewust wél in staat ondanks "minimaal" + +- **`/write-issue` in plaats van `gh issue create`** — zonder die zin doet Claude uit zichzelf `gh issue create`. Weglaten veroorzaakt een fout, dus het blijft. +- **Gericht testen** — anders draait Claude standaard de volledige suite. +- **Lege valkuilen-sectie** — de plek waar het bestand per repo mag groeien, op bewijs. + +### Wat er bewust níet in staat + +Modulemap, architectuurbeschrijving, codestijlregels, en verwijzingen naar `standards/` en `werkafspraken/`. Die leest Claude zelf uit de code, of ze zitten al in skills. Codestijl is bovendien werk voor een linter, niet voor een taalmodel. + +## Onderdeel 3: de werkafspraak + +Bestand: `werkafspraken/claude-md.md`, volgens `_template.md`. + +- **Niveau: Experiment.** CLAUDE.md-tekst is advies, geen garantie: het model kan het missen. Dat hoort eerlijk in de afspraak te staan, en Experiment is het niveau dat daarbij past. +- **Eigenaar:** @CorneeldH. +- Opgenomen in de tabel in `werkafspraken/README.md`, in de `nav` van `mkdocs.yml`, en met de mirror onder `docs/werkafspraken/`. + +## Onderdeel 4: `cedafy-claude-md` + +Skill die de template toepast op een bestaande repo. Bestaat er nog geen CLAUDE.md, dan is het invullen en klaar. + +### Werking + +1. **Lezen** — de template plus de bestaande `CLAUDE.md`. +2. **Repo uitlezen** — stack, package manager, en de test-, lint- en run-commando's, voor de `<...>`-plekken. +3. **Per template-punt classificeren** in drie bakken: + - *ontbreekt* — staat niet in de huidige CLAUDE.md + - *al gedekt* — de huidige tekst zegt hetzelfde in andere woorden + - *tegenstrijdig* — de huidige tekst zegt iets anders +4. **Ontbrekend → direct invoegen.** Geen vraag; dat is de winst van de skill. +5. **Al gedekt → niets doen.** Geen tweede regel die hetzelfde zegt. +6. **Tegenstrijdig → `AskUserQuestion`**, per punt, met drie opties: de template volgen, de huidige regel houden, of combineren. Bij "combineren" staat de voorgestelde gecombineerde tekst in de optie zelf, zodat de keuze concreet is. Maximaal vier vragen per aanroep, dus gebatcht. +7. **Wegschrijven** — de antwoorden verwerkt, repo-eigen secties ongemoeid, plus een kort overzicht van wat is toegevoegd, wat is overgeslagen, en wat de gebruiker heeft beslist. + +### Wat telt als tegenstrijdig + +| Huidige CLAUDE.md | Template | Classificatie | +|---|---|---| +| "werk gewoon op main" | worktree vóór eerste schrijfactie | tegenstrijdig | +| "draai altijd de volledige suite" | gericht één testbestand | tegenstrijdig | +| "vraag altijd eerst om bevestiging" | brainstorm vóór bouwen | al gedekt | +| eigen commit-flow met extra stappen | geen tegenhanger | repo-eigen, ongemoeid | + +Twijfelgeval telt als tegenstrijdig, dus wordt er gevraagd. Liever een vraag te veel dan een stilzwijgend overschreven afspraak. + +### Wat de skill nooit doet + +Repo-eigen secties verwijderen, of het bestand herschrijven naar de volgorde van de template. Invoegen en aanpassen, niet vervangen. + +### Buiten scope + +De omgekeerde richting — signaleren dat een repo-eigen regel eigenlijk in de org-template thuishoort. Dat vraagt zicht op álle CLAUDE.md's tegelijk en hoort bij repo-context-as-data, niet bij deze skill. + +## Onderdeel 5: haakje in `init-repo` + +`init-repo` schrijft de template naar nieuwe repos. Bestaande repos worden niet automatisch bijgewerkt; die draaien eenmalig `cedafy-claude-md`. + +## Volgorde van uitvoeren + +1. **`sessie-terugblik` landen.** Staat nu uncommitted in worktree `skills/lifecycle` (daar nog onder de oude naam `sessie-reflectie`). Zonder deze stap verwijst de template naar een skill die niet bestaat. Harde voorwaarde voor stap 4. +2. `worktree` en `plan` vendoren. +3. `brainstorm` uitbreiden met de `/plan`-eindstap. +4. Template, werkafspraak, `werkafspraken/README.md`-tabel, `mkdocs.yml`-nav en de `docs/`-mirror. +5. `cedafy-claude-md`. +6. Haakje in `init-repo`. + +## Definition of Done + +- `worktree` en `plan` bestaan als CEDA-skills en komen door de skill-validator. +- `brainstorm` verwijst bij go naar `/plan`. +- `werkafspraken/_claude-md-template.md` bestaat en is ingevuld ≤ 50 regels. +- `werkafspraken/claude-md.md` bestaat op niveau Experiment, staat in de README-tabel, in de mkdocs-nav en heeft een mirror onder `docs/werkafspraken/`. +- `cedafy-claude-md` bestaat, en is gedraaid op minstens één bestaande repo mét eigen CLAUDE.md, waarbij een tegenstrijdigheid daadwerkelijk als vraag is voorgelegd. +- `init-repo` schrijft de template naar nieuwe repos. + +## No-gos + +- Geen hooks in deze ronde. Het sessie-einde blijft tekst. +- Geen opruiming van `sparren`, `ship` of `branch-pr`. +- Geen superpowers-plugin org-breed installeren. +- Geen automatische uitrol over bestaande repos. +- Geen routingtabel voor skills in CLAUDE.md. From b6e7a028379396a20e77c4c3dbffcc30838211ac Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Fri, 14 Aug 2026 18:25:04 +0200 Subject: [PATCH 2/8] docs: voeg regel voor aanklikbare bestandsverwijzingen toe aan template Kale paden tussen backticks kan de gebruiker niet openen. Regel dekt zowel chat als markdown, inclusief het worktree-pad. Co-Authored-By: Claude Opus 5 (1M context) --- docs/specs/2026-08-14-claude-md-baseline-design.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/specs/2026-08-14-claude-md-baseline-design.md b/docs/specs/2026-08-14-claude-md-baseline-design.md index 5134349..855e38c 100644 --- a/docs/specs/2026-08-14-claude-md-baseline-design.md +++ b/docs/specs/2026-08-14-claude-md-baseline-design.md @@ -106,6 +106,13 @@ taak over meerdere berichten) blijft in dezelfde sessie. Reden: lange sessies stapelen verouderde context op → tragere, slechtere output. +## Bestandsverwijzingen +Verwijs naar een bestand altijd als aanklikbare markdown-link, relatief vanaf de +root van de workspace: `[naam](pad/naar/bestand.md)`, een regel met `#L42`. Nooit +een kaal pad tussen backticks — dat kan de gebruiker niet openen. Dit geldt net +zo goed in de chat als in markdown-bestanden. Werk je in een worktree onder +`.claude/worktrees//`, dan hoort dat stuk in het pad. + ## Bij compacteren Bewaar altijd: de lijst gewijzigde bestanden, de testcommando's en openstaande beslissingen. @@ -124,6 +131,7 @@ Ingevuld is dat ongeveer 45 regels. - **`/write-issue` in plaats van `gh issue create`** — zonder die zin doet Claude uit zichzelf `gh issue create`. Weglaten veroorzaakt een fout, dus het blijft. - **Gericht testen** — anders draait Claude standaard de volledige suite. +- **Aanklikbare bestandsverwijzingen** — zonder die regel levert Claude kale paden tussen backticks, die de gebruiker niet kan openen. Tijdens deze brainstorm zelf misgegaan. - **Lege valkuilen-sectie** — de plek waar het bestand per repo mag groeien, op bewijs. ### Wat er bewust níet in staat From 327f2498d7222547edc87d7de608d03e73b399d2 Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Fri, 14 Aug 2026 18:36:39 +0200 Subject: [PATCH 3/8] feat(skills): vendor worktree en plan, koppel brainstorm aan /plan Twee sessie-start-skills die CEDA miste, overgenomen uit superpowers (MIT, (c) 2025 Jesse Vincent) en aangepast aan onze conventies: - worktree: CEDA-branchnaming (issue-- / fix-), projectsetup voor de uv/R/npm-stack, Nederlandse output. Kern van het origineel behouden: eerst detecteren of je al geisoleerd zit, dan het native mechanisme, en pas als laatste `git worktree add` -- die volgorde voorkomt worktrees die de harness niet kent en niet opruimt. - plan: schrijft naar docs/plans/ en laat de taken via /write-issue op het CEDA-board landen in plaats van in een losse checklist. De superpowers-specifieke uitvoerskills zijn eruit; die zijn niet org-breed beschikbaar. brainstorm krijgt de eindstap die ontbrak: bij een expliciete go is het vervolg /plan, tenzij de diff in een zin te beschrijven is. De description krijgt de terugwijzende exclusion-clause die daarbij hoort -- zonder die wijziging meldt de collectie-brede validator terecht overlappende triggerwoorden tussen brainstorm en plan. Validator: worktree, plan en brainstorm elk 0 fouten, 0 waarschuwingen. Collectie-breed 111 -> 110 waarschuwingen, geen enkele noemt de nieuwe skills. Refs docs/specs/2026-08-14-claude-md-baseline-design.md stap 2 en 3. --- .claude/skills/brainstorm/SKILL.md | 17 ++- .claude/skills/plan/SKILL.md | 201 +++++++++++++++++++++++++++++ .claude/skills/worktree/SKILL.md | 162 +++++++++++++++++++++++ 3 files changed, 378 insertions(+), 2 deletions(-) create mode 100644 .claude/skills/plan/SKILL.md create mode 100644 .claude/skills/worktree/SKILL.md diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index da2443d..f229522 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -1,6 +1,6 @@ --- name: brainstorm -description: Structureer een brainstorm van idee naar getoetst besluit vóór implementatie, met een beslis-samenvatting en aanbevelingen — geen code of bestanden. Wanneer iemand een idee wil uitwerken of een besluit wil voorbereiden voordat er code of een plan komt. +description: Structureer een brainstorm van idee naar getoetst besluit vóór implementatie, met een beslis-samenvatting en aanbevelingen — geen code of bestanden. Wanneer iemand een idee wil uitwerken of een besluit wil voorbereiden voordat er code of een plan komt. LET OP — ná de go hoort `plan`, niet dit. --- # Brainstorm @@ -64,8 +64,21 @@ Go? Dan [plan maken / bouwen wat hierboven staat]. Wait for an explicit go. On corrections: adjust, self-review again, present again. +### 8. After the go + +The brainstorm ends here; it does not turn into building. On an explicit go, hand over: + +| Scope of what was agreed | Next step | +|---|---| +| Multiple steps or multiple files | `/plan` — write the implementation plan first | +| The diff fits in one sentence | Build it directly, no plan | + +Say which one it is and why in one line, then start. Do not ask the user to choose between +planning and building when the criterion above already decides it. + ## Important -- Building starts only after an explicit go; the only follow-up is planning or building what was agreed. +- Building starts only after an explicit go; the only follow-up is `/plan` or building what + was agreed. - All user-facing output is in Dutch; keep it terse and recommendation-first. - Avoid the anti-patterns: working through a checklist of questions; asking what you can read yourself; premature constraints (narrowing the solution before the problem is clear); reopening locked decisions; listing options without a recommendation; multiple follow-ups without priority (one primary suggestion, alternatives secondary). diff --git a/.claude/skills/plan/SKILL.md b/.claude/skills/plan/SKILL.md new file mode 100644 index 0000000..b50eadd --- /dev/null +++ b/.claude/skills/plan/SKILL.md @@ -0,0 +1,201 @@ +--- +name: plan +description: Zet een genomen besluit om in een uitvoerbaar implementatieplan — bestandsindeling, taken die elk hun eigen testcyclus dragen, exacte paden en commando's, en per taak een issue op het CEDA-board. Gebruik na een go, bij "maak een plan" of "hoe pakken we dit aan", of bij werk over meerdere stappen of bestanden. LET OP — vóór de go hoort `brainstorm`, niet dit. +allowed-tools: Read Write Edit Grep Glob Bash AskUserQuestion Skill +license: MIT — afgeleid van superpowers (© 2025 Jesse Vincent) +metadata: + ceda-id: ceda.plan + ceda-version: "0.1.0" + ceda-type: workflow + ceda-subtype: "" + ceda-origin: extended + ceda-upstream: superpowers:writing-plans + ceda-source: https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md + ceda-activation: command + ceda-binding: default + ceda-execution: inline + ceda-scope: org + ceda-verifies: observable +--- + +# Plan + +Write the implementation plan for someone who knows how to program but knows nothing about +this codebase, this toolset, or this problem domain. Everything they need is in the plan: +which files, which code, which command, what output to expect. + +Derived from `superpowers:writing-plans` (MIT, © 2025 Jesse Vincent). Changed for CEDA: plans +live in `docs/plans/`, and the tasks land as issues via `/write-issue` instead of in a loose +checklist. + +## Workflow + +When the user invokes `/plan [optional: subject or path to a spec]`: + +### 1. Check the input + +A plan needs a decision that has already been made — a spec, a brainstorm summary, an issue +with an agreed approach. Is there none, then this skill is too early: run `/brainstorm` first +and come back after the go. + +Does the spec cover several independent subsystems? Then propose one plan per subsystem. Each +plan must produce working, testable software on its own. + +### 2. Map the file structure first + +Before any task exists, write down which files are created or modified and what each one is +responsible for. This is where the decomposition is decided; task boundaries follow from it. + +- One clear responsibility per file. Files that change together live together — split by + responsibility, not by technical layer. +- Smaller focused files over one large file. You reason better about what you can hold in + context at once, and edits land more reliably. +- In an existing codebase, follow the pattern that is there. Do not restructure on your own + initiative; a split is fair game when the file you are touching has already grown unwieldy. + +### 3. Cut the tasks + +A task is the smallest unit that carries its own test cycle and is worth a reviewer's +judgement. Fold setup, configuration, scaffolding, and documentation into the task whose +deliverable needs them. Split only where a reviewer could reject one task while approving the +one next to it. Every task ends in something independently testable. + +Within a task each step is one action of a few minutes: write the failing test, run it and see +it fail, write the minimal implementation, run it and see it pass, commit. + +### 4. Write the plan + +Save to `docs/plans/YYYY-MM-DD-.md`. + +Header: + +```markdown +# — implementatieplan + +**Doel:** <één zin: wat dit oplevert> +**Aanpak:** <2-3 zinnen> +**Stack:** + +## Randvoorwaarden + + + +--- +``` + +Per task: + +````markdown +### Taak N: + +**Bestanden:** +- Nieuw: `exact/pad/naar/bestand.py` +- Wijzigen: `exact/pad/bestaand.py:123-145` +- Test: `tests/exact/pad/test_bestand.py` + +**Interfaces:** +- Gebruikt: +- Levert: + +- [ ] **Stap 1: schrijf de falende test** + +```python +def test_specifiek_gedrag(): + assert functie(invoer) == verwacht +``` + +- [ ] **Stap 2: draai de test, zie hem falen** + +Draai: `uv run pytest tests/pad/test_bestand.py::test_specifiek_gedrag -v` +Verwacht: FAIL — "functie not defined" + +- [ ] **Stap 3: minimale implementatie** + +```python +def functie(invoer): + return verwacht +``` + +- [ ] **Stap 4: draai de test, zie hem slagen** + +Draai: `uv run pytest tests/pad/test_bestand.py::test_specifiek_gedrag -v` +Verwacht: PASS + +- [ ] **Stap 5: commit** + +```bash +git add tests/pad/test_bestand.py src/pad/bestand.py +git commit -m "feat: " +``` +```` + +### 5. No placeholders + +These are plan failures, not shortcuts. Never write them: + +- "TBD", "TODO", "later invullen", "details volgen" +- "voeg passende foutafhandeling toe" / "vang randgevallen af" +- "schrijf hier tests voor" without the actual test code +- "net als taak N" — repeat the code; tasks get read out of order +- a step that says what to do without showing how (code steps need a code block) +- a reference to a type, function, or method that no task defines + +### 6. Self-review + +Run this yourself, on the finished plan, against the spec. Not a subagent. + +1. **Coverage** — walk through every requirement in the spec. Can you point at the task that + implements it? List the gaps and add the missing tasks. +2. **Placeholders** — search your own plan for the patterns in step 5. Fix them. +3. **Type consistency** — do the names and signatures in later tasks match what earlier tasks + defined? `clearLayers()` in task 3 and `clearFullLayers()` in task 7 is a bug that costs an + entire execution round. + +Fix what you find inline and move on. No second review round. + +### 7. Land the tasks as issues + +Split into two questions, because they have different answers: + +- **The plan** stays a file in `docs/plans/`. It is the working document; it does not belong in + an issue body. +- **The tasks** become issues via `/write-issue`, so that the work lands on the CEDA board and + is visible to others. One issue per task, referring back to the plan file and the task number. + +Ask before creating anything: + +> Plan staat in `docs/plans/.md` — taken. +> Zal ik daar issues van maken op het CEDA-board, of houden we het bij het plan? + +Never call `gh issue create` directly; `/write-issue` owns the template and the board fields. + +### 8. Execute + +Execute task by task, in order, with a commit per task. Show the result after each task and +wait before starting the next one — that check is what makes the small tasks worth their cost. + +## Let op: het plan is voor iemand zonder context + +The most expensive mistake here is writing the plan for yourself. You know why a choice was +made and what the file is called; the person executing does not, and neither does a fresh +session of yourself after a context reset. Exact paths, complete code, literal commands with +the output you expect. "Similar to the one above" costs an execution round. + +## Verificatie + +`ceda-verifies: observable` — the plan is done when a reader who has not been part of this +conversation can answer, per task: which files, which code, which command, and what output +proves it works. Concretely, the step 6 checklist is clean: every spec requirement maps to a +task, no placeholder patterns remain, and the names in later tasks match the earlier ones. + +## Important + +- No code before the plan is agreed. Is there no decision yet, then `brainstorm` comes first. +- Issues only via `/write-issue`, and only after the user says yes — a plan of ten tasks is ten + issues on a shared board. +- This skill writes the plan and executes it. Reviewing and landing the result is `ship`, the + pull request is `branch-pr`. diff --git a/.claude/skills/worktree/SKILL.md b/.claude/skills/worktree/SKILL.md new file mode 100644 index 0000000..6a18847 --- /dev/null +++ b/.claude/skills/worktree/SKILL.md @@ -0,0 +1,162 @@ +--- +name: worktree +description: Zet een geïsoleerde werkplek op voordat er iets geschreven wordt — detecteert eerst of je er al in zit, gebruikt daarna het native worktree-mechanisme en pas als laatste git, en zet er een CEDA-branchnaam op. Gebruik bij "worktree", "aparte branch", "los van main werken", of voordat je aan een issue begint. LET OP — voor het afronden en pushen is er `ship`, voor de PR `branch-pr`. +allowed-tools: Read Grep Glob Bash AskUserQuestion +license: MIT — afgeleid van superpowers (© 2025 Jesse Vincent) +compatibility: Requires git 2.5+; a native worktree tool is used when the harness provides one +metadata: + ceda-id: ceda.worktree + ceda-version: "0.1.0" + ceda-type: workflow + ceda-subtype: "" + ceda-origin: extended + ceda-upstream: superpowers:using-git-worktrees + ceda-source: https://github.com/obra/superpowers/blob/main/skills/using-git-worktrees/SKILL.md + ceda-activation: command + ceda-binding: default + ceda-execution: inline + ceda-scope: org + ceda-verifies: measurable +--- + +# Worktree + +Ensure the work happens in an isolated workspace, on its own branch, **before** the first +write. Moving changes into a worktree afterwards is manual, error-prone work; creating the +worktree first costs one command. + +Derived from `superpowers:using-git-worktrees` (MIT, © 2025 Jesse Vincent). Changed for CEDA: +branch naming, project setup for the uv/R stack, and Dutch user-facing output. + +## Workflow + +When the user invokes `/worktree [optional: issue number or short description]`: + +### 1. Detect existing isolation + +**Check this before creating anything.** A worktree inside a worktree is the most common +failure here. + +```bash +GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) +GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) +BRANCH=$(git branch --show-current) +git rev-parse --show-superproject-working-tree 2>/dev/null # non-empty = submodule +``` + +`GIT_DIR != GIT_COMMON` **and** the submodule check is empty → you are already in a linked +worktree. Skip to step 4. Report in Dutch: + +> Je zit al geïsoleerd in `` op branch ``. Geen nieuwe worktree nodig. + +At a detached HEAD, add that a branch still has to be created before finishing. + +`GIT_DIR == GIT_COMMON`, or the submodule check returned a path → normal checkout, continue. + +### 2. Ask consent, unless it is already given + +Did the user ask for a worktree, or do the project instructions require one before the first +write? Then do not ask — that consent already exists. Otherwise: + +> Zal ik een aparte worktree opzetten? Dan blijft je huidige branch onaangeraakt. + +If the user declines, work in place and skip to step 4. "Op main" is a valid answer. + +### 3. Determine the branch name, then create the workspace + +CEDA branch naming: + +| Situation | Name | +|---|---| +| There is an issue | `issue--` | +| A fix without an issue | `fix-` | + +The slug is lowercase, hyphenated, three or four words at most. No issue number and no idea +what the work is? Then this skill is too early — the work is not defined yet. + +#### 3a. Native tool first + +Do you have a worktree tool from the harness — something named `EnterWorktree`, a +`/worktree` command, a `--worktree` flag? Use it, with the branch name from the table, and go +to step 4. + +This ordering is not cosmetic. `git worktree add` while a native tool exists produces +worktrees the harness does not know about, does not show, and does not clean up. + +#### 3b. Git fallback + +Only when there is no native tool. + +Directory, in this order: an explicit preference from the user or the project instructions; +otherwise an existing `.worktrees/` (wins) or `worktrees/`; otherwise `.worktrees/` at the +repository root. + +A project-local directory **must** be ignored before you create anything in it, otherwise the +worktree contents end up in `git status` and eventually in a commit: + +```bash +git check-ignore -q .worktrees || { echo ".worktrees/" >> .gitignore; git add .gitignore; git commit -m "chore: ignore .worktrees"; } +git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME" +cd ".worktrees/$BRANCH_NAME" +``` + +Fails on a permission error? The sandbox blocked it. Say so, work in the current directory, +and continue with step 4 — do not retry with escalating flags. + +### 4. Project setup + +A fresh worktree has no dependencies installed. Detect and run what applies: + +```bash +[ -f pyproject.toml ] && uv sync # CEDA default for Python +[ -f requirements.txt ] && [ ! -f pyproject.toml ] && uv pip install -r requirements.txt +[ -f DESCRIPTION ] && Rscript -e 'devtools::load_all()' +[ -f package.json ] && npm install # Slidev/Marp decks +``` + +No dependency file → skip this step, do not invent one. + +### 5. Verify a clean baseline + +Run the project's own test command (`uv run pytest`, `Rscript -e 'devtools::test()'`, whatever +the project instructions name). + +Tests failing **before** you change anything is the whole point of this step: without it you +cannot tell your own breakage from what was already broken. Report the failures and ask +whether to continue or investigate first. Never silently continue. + +No test suite at all? Say so in one line and continue. + +### 6. Report + +> Worktree klaar op ``, branch ``. +> Baseline: `` / `` / `` +> Klaar om aan `` te werken. + +## Let op: al geïsoleerd zijn is de normale toestand, niet de uitzondering + +Modern harnesses put a session in a worktree on their own. Step 1 exists because the failure it +prevents is invisible: a nested worktree looks like it works until the branches diverge and +neither the harness nor `git worktree list` shows what you expected. + +The same holds for a submodule — `GIT_DIR != GIT_COMMON` is true there too, which is why the +submodule check is part of step 1 and not an afterthought. + +## Verificatie + +`ceda-verifies: measurable` — after this skill, + +```bash +[ "$(cd "$(git rev-parse --git-dir)" && pwd -P)" != "$(cd "$(git rev-parse --git-common-dir)" && pwd -P)" ] && git branch --show-current +``` + +prints a branch name matching `issue--` or `fix-`. When the user declined +isolation, this check does not apply and the report says so explicitly. + +## Important + +- Never create a worktree when step 1 detects existing isolation, and never use + `git worktree add` when a native worktree tool exists. Both produce state nobody can see. +- Never create a project-local worktree directory that is not ignored. +- This skill only opens the workspace. Finishing it — review, commit, push — is `ship`; + opening the pull request is `branch-pr`. From bbfb4ed061d8aa81ef0253ce687b7b3177e0f433 Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Fri, 14 Aug 2026 18:40:21 +0200 Subject: [PATCH 4/8] feat(skills): cedafy-claude-md, en init-repo haakt aan de baseline cedafy-claude-md brengt een bestaande repo op de CEDA-baseline zonder weg te gooien wat die repo zelf al besloot. Elk template-punt gaat in een van drie bakken: ontbreekt (direct invoegen), al gedekt (niets doen), tegenstrijdig (voorleggen via het keuzemenu, drie opties, de gecombineerde tekst staat in de optie zelf). Twijfelgeval telt als tegenstrijdig -- een vraag te veel is goedkoper dan een stilzwijgend overschreven afspraak. De skill haalt het sjabloon via `gh api` uit cedanl/.github in plaats van uit een lokaal pad, want hij draait per definitie in een andere repo. init-repo schreef zijn eigen CLAUDE.md-sjabloon inline, met modulekaart, architectuur en projectstructuur erin. Dat is nu een verwijzing naar hetzelfde org-sjabloon, met de expliciete instructie die secties er niet aan toe te voegen: het bestand wordt elke sessie geladen, en te lang betekent half genegeerd. Description krijgt de terugwijzende clause naar cedafy-claude-md. Validator: beide 0 fouten, 0 waarschuwingen. Collectie-breed 110 waarschuwingen, geen enkele noemt een van de nieuwe skills. Refs docs/specs/2026-08-14-claude-md-baseline-design.md stap 5 en 6. --- .claude/skills/cedafy-claude-md/SKILL.md | 138 +++++++++++++++++++++++ .claude/skills/init-repo/SKILL.md | 33 +++--- 2 files changed, 151 insertions(+), 20 deletions(-) create mode 100644 .claude/skills/cedafy-claude-md/SKILL.md diff --git a/.claude/skills/cedafy-claude-md/SKILL.md b/.claude/skills/cedafy-claude-md/SKILL.md new file mode 100644 index 0000000..0410689 --- /dev/null +++ b/.claude/skills/cedafy-claude-md/SKILL.md @@ -0,0 +1,138 @@ +--- +name: cedafy-claude-md +description: Past de CEDA-baseline voor projectinstructies toe op een repo die er al een heeft — vult aan wat ontbreekt, laat staan wat al gedekt is, en legt elke tegenstrijdigheid als keuze voor in plaats van te overschrijven. Gebruik bij "projectinstructies bijwerken", "CEDA-conform maken" of "sessie-afspraken toevoegen". LET OP — bij een nieuwe repo doet `init-repo` dit al. +allowed-tools: Read Write Edit Grep Glob Bash AskUserQuestion +compatibility: Requires the gh CLI to fetch the template from cedanl/.github +metadata: + ceda-id: ceda.cedafy-claude-md + ceda-version: "0.1.0" + ceda-type: workflow + ceda-subtype: "" + ceda-origin: own + ceda-upstream: "" + ceda-source: werkafspraken/_claude-md-template.md + ceda-activation: command + ceda-binding: default + ceda-execution: inline + ceda-scope: org + ceda-verifies: observable +--- + +# Cedafy CLAUDE.md + +Bring an existing repository's `CLAUDE.md` in line with the CEDA baseline without throwing away +what the repository already decided for itself. Insert and adjust, never replace. + +Is there no `CLAUDE.md` yet? Then this is a fill-in job: take the template, fill in the +`<...>` slots from step 2, write it, done. The rest of this skill is about the harder case. + +## Workflow + +When the user invokes `/cedafy-claude-md [optional: path to the repository]`: + +### 1. Read both sides + +The template lives in `cedanl/.github`, not in the repository you are working in: + +```bash +gh api repos/cedanl/.github/contents/werkafspraken/_claude-md-template.md --jq .content | base64 -d +``` + +`gh` must run outside the sandbox here, and `unset GITHUB_TOKEN` first — see `branch-pr`. + +Then read the repository's own `CLAUDE.md`, in full. Not a grep for headings: the point of this +skill is judging what the existing text *means*, and a heading does not tell you that. + +### 2. Read the repository, for the slots + +The template has `<...>` slots. Fill them from the repository itself, not from assumptions: + +| Slot | Where it comes from | +|---|---| +| Stack, language version | `pyproject.toml`, `DESCRIPTION`, `package.json` | +| Package manager | a `uv.lock`, `renv.lock`, `package-lock.json` | +| Run, test, lint commands | the scripts in that same file, the CI workflow, the README | + +Cannot find a command? Leave the slot empty and say so at the end. An invented test command is +worse than a missing one — it fails in a session where nobody expects it. + +### 3. Classify every template point + +Three buckets. Do this per point, not per section, because one section can be half covered. + +| Bucket | Meaning | +|---|---| +| *ontbreekt* | The current `CLAUDE.md` does not say this at all | +| *al gedekt* | The current text says the same thing in different words | +| *tegenstrijdig* | The current text says something else | + +What counts as contradictory: + +| Current `CLAUDE.md` | Template | Bucket | +|---|---|---| +| "werk gewoon op main" | worktree before the first write | tegenstrijdig | +| "draai altijd de volledige suite" | one targeted test file | tegenstrijdig | +| "vraag altijd eerst om bevestiging" | brainstorm before building | al gedekt | +| an own commit flow with extra steps | no counterpart in the template | repo-eigen, leave alone | + +**A doubtful case counts as contradictory**, so it becomes a question. One question too many +beats an agreement that is silently overwritten — the user wrote that line for a reason you +cannot see from here. + +### 4. Insert what is missing, leave what is covered + +*Ontbreekt* → insert directly, in the template's wording. Do not ask; that is the whole point +of the skill. + +*Al gedekt* → do nothing. A second line saying the same thing in other words makes the file +longer and the instruction weaker. + +### 5. Put every contradiction to the user + +Per contradictory point, three options via the choice menu: + +1. follow the template +2. keep the current line +3. combine — **with the proposed combined text in the option itself**, so the choice is + concrete instead of a promise + +Four questions per call at most, so batch them. Do not ask them one at a time in chat: this is +a fixed set of answers, and a menu is faster and yields better answers than an open question. + +### 6. Write and report + +Process the answers, leave repo-specific sections untouched, and write the file. Then report, +in Dutch: + +> **Bijgewerkt:** `CLAUDE.md` +> - Toegevoegd: +> - Overgeslagen omdat het al gedekt was: +> - Jouw keuze: → +> - Slots die ik niet kon invullen: + +## Let op: de volgorde van het bestaande bestand blijft staan + +The temptation is to rewrite the file into the template's order — it reads better and the diff +looks clean. Do not. Someone put those sections in that order, and a reordering diff hides +which lines actually changed in the review. Insert at the place where the point belongs in the +existing structure, and add a section at the end only when there is no such place. + +## Verificatie + +`ceda-verifies: observable` — done when all three hold, checked against the diff: + +- every repo-specific section from before is still present, in the same order +- every point classified as *tegenstrijdig* has a user decision behind it, none silently + overwritten +- no point appears twice, once in the template's words and once in the repository's + +## Important + +- Never remove a repo-specific section, and never rewrite the file into the template's order. + Insert and adjust, not replace. +- Every contradiction goes to the user. A doubtful case is a contradiction. +- The reverse direction — noticing that a repo-specific rule actually belongs in the org + template — is out of scope. That needs a view of every `CLAUDE.md` at once and belongs with + repo-context-as-data. +- For a repository that has no `CLAUDE.md` because it is brand new, `init-repo` writes the + template as part of the scaffold. diff --git a/.claude/skills/init-repo/SKILL.md b/.claude/skills/init-repo/SKILL.md index 09e8fc0..4bfce19 100644 --- a/.claude/skills/init-repo/SKILL.md +++ b/.claude/skills/init-repo/SKILL.md @@ -1,6 +1,6 @@ --- name: init-repo -description: Initialize a new cedanl repository with the correct CEDA project structure. Use when starting a new project, creating a new repo, or scaffolding a repository. +description: Initialize a new cedanl repository with the correct CEDA project structure. Use when starting a new project, creating a new repo, or scaffolding a repository. LET OP — voor een repo die al bestaat en alleen de projectinstructies mist is er `cedafy-claude-md`. --- # Initialize CEDA Repository @@ -159,29 +159,22 @@ project-name/ #### CLAUDE.md -Use the template from `standards/project-structure.md`: +Do not write this one by hand. Fetch the org baseline and fill in its `<...>` slots: -```markdown -# [Project Name] - -## Overview -[description] - -## Standards -Follow CEDA technical standards: https://github.com/cedanl/.github/tree/main/standards/README.md - -## Tech Stack -[R or Python], key packages. +```bash +gh api repos/cedanl/.github/contents/werkafspraken/_claude-md-template.md --jq .content | base64 -d +``` -## Project Structure -[generated directory layout] +Fill the slots from the answers in step 1 and the structure you just generated: one line on +what this is, the stack and package manager, and the run/test/lint commands for the chosen +language. Leave the `## Valkuilen` section empty — it grows per repository, on evidence. -## How to Run -[commands for install + run] +Do **not** add a module map, an architecture description, or code style rules. Claude reads +those from the code itself, style is a linter's job, and every line in this file is loaded in +every session — a longer file means a file that gets half ignored. -## Data -[input/output formats, where data comes from] -``` +An existing repository that does not have this baseline yet is a job for `/cedafy-claude-md`, +not for this skill. #### README.md From 41c8df13adb99b9cc26e064b43715b18a6aeacae Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Sat, 15 Aug 2026 11:44:17 +0200 Subject: [PATCH 5/8] feat(skills): sluit de keten brainstorm -> plan -> uitvoering Zes punten uit de vergelijking met superpowers:brainstorming en superpowers:writing-plans, na een inhoudelijke evaluatie van wat daar wel en niet uit over te nemen valt. 1. Brainstorm liet geen artefact achter. De go heft de gate nu op voor precies een bestand: de beslis-samenvatting in docs/specs/. Plan leest dat bestand; zonder die stap bestaat de input van plan niet meer na een contextreset, een nieuwe sessie of een /worktree ertussen. 2. De scope-check in brainstorm zei "multiple independent parts are fine" en accepteerde dus wat plan daarna alsnog moest splitsen. Nu eerst decomponeren, in dezelfde vorm als plan stap 1. 3. Plan noemde worktree niet, terwijl die skill in deze branch staat en de uitvoering per taak commit. 4. Plan voerde uit in de sessie die het plan schreef - precies het faalpad waar de skill zelf tegen waarschuwt. Nu een verse subagent per taak, en de description dekt de uitvoering die de body al beschreef. 5. Beide skills eisen nu een todo per stap, zodat de gate en de self-review niet wegvallen op een onderwerp dat simpel voelt. 6. Brainstorm had geen ceda-metadata (validator: "nog niet gemigreerd") en geen allowed-tools. Ingevuld als ceda-origin: extended met upstream superpowers:brainstorming - de design-spec van deze PR noemt de skill zelf een bijna-kloon - maar zonder MIT-attributieregel, want de tekst is in huis geschreven en niet overgenomen. Bewust niet overgenomen, met de reden in de body van beide skills: de reviewer-subagent-prompts (upstream dispatcht ze zelf niet meer; hun SKILL.md noemt de self-review expliciet inline) en de visual companion (~1400 regels gebundelde node/bash-server; hoort bij de ontwerp-skills en vergt een eigen externe-skill-audit). Validator: brainstorm, plan en worktree groen, nul waarschuwingen; de collectie blijft op 12 fouten en 110 waarschuwingen, legacy 54 -> 53. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/skills/brainstorm/SKILL.md | 74 +++++++++++++++++++++++++++--- .claude/skills/plan/SKILL.md | 63 ++++++++++++++++++++----- 2 files changed, 118 insertions(+), 19 deletions(-) diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index f229522..f903048 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -1,16 +1,46 @@ --- name: brainstorm -description: Structureer een brainstorm van idee naar getoetst besluit vóór implementatie, met een beslis-samenvatting en aanbevelingen — geen code of bestanden. Wanneer iemand een idee wil uitwerken of een besluit wil voorbereiden voordat er code of een plan komt. LET OP — ná de go hoort `plan`, niet dit. +description: Structureer een brainstorm van idee naar getoetst besluit vóór implementatie, en leg dat besluit na de go vast als document dat het plan daarna kan lezen — geen code. Wanneer iemand een idee wil uitwerken of een besluit wil voorbereiden voordat er code of een plan komt. LET OP — ná de go hoort `plan`, niet dit. +allowed-tools: Read Write Grep Glob Bash AskUserQuestion Skill +metadata: + ceda-id: ceda.brainstorm + ceda-version: "0.2.0" + ceda-type: workflow + ceda-subtype: "" + ceda-origin: extended + ceda-upstream: superpowers:brainstorming + ceda-source: https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md + ceda-activation: command + ceda-binding: default + ceda-execution: inline + ceda-scope: org + ceda-verifies: observable --- # Brainstorm -Structured brainstorming from an idea to a tested decision, before any implementation or plan. The output is a decision summary with recommendations — never code, files, or commits. Respond to the user in Dutch, caveman-terse. +Structured brainstorming from an idea to a tested decision, before any implementation or plan. The output is a decision summary with recommendations — never code. Respond to the user in Dutch, caveman-terse. + +`ceda-origin: extended` records the maintenance link with `superpowers:brainstorming`: the +spine is the same (hard gate, "too simple" does not exist, 2-3 approaches, present in sections, +self-review, hand off to the plan), so an upstream change to that spine is worth reading here. +The text is CEDA's own — written in-house, Dutch, assumptions-first with confidence levels — +so there is no MIT attribution line, unlike `plan` and `worktree`, which are ports. + +What upstream carries and this skill deliberately does not: the reviewer-subagent prompt +(upstream abandoned it themselves — their own `SKILL.md` says the self-review is inline, "not +a subagent dispatch") and the browser-based visual companion (a bundled node server; visual +questions belong with `ui-designer` and `vormgever-npuls-huisstijl`, and a bundled server needs +its own `externe-skill-audit`). ## Workflow When the user invokes `/brainstorm [optioneel: onderwerp]`: +Create a todo per numbered step below and work them off in order. Steps that do not +apply — no real choice in step 4, for instance — you close with one line saying why. +The todo list is what keeps the gate from being skipped on a topic that feels simple. + ### Hard gate Until an explicit go: @@ -19,6 +49,9 @@ Until an explicit go: - No scaffolding, no installing dependencies, no "quick POC" - Do not start other skills or plan mode; the only follow-up after go is planning or building what was agreed +The go lifts the gate for exactly one file: the decision summary from step 7. Nothing else +gets written, ever, by this skill. + "Too simple to brainstorm" does not exist: for simple topics the summary is a few lines, but it always comes. ### Communication @@ -31,7 +64,13 @@ Before asserting anything, read the relevant files, docs, and recent commits. Wh ### 2. Scope check -Multiple independent parts are fine. +Does the idea cover several independent subsystems — parts that could be built, tested and +used without each other? Say so before you ask anything else, and decompose first: name the +parts, say how they relate, propose an order. Then brainstorm the first part through the rest +of this workflow. Each part gets its own summary and its own `/plan`. + +Do not spend questions on the details of something that has to be split anyway. `plan` splits +the same way (one plan per subsystem); deciding it here saves the round trip. ### 3. Assumptions first @@ -64,21 +103,42 @@ Go? Dan [plan maken / bouwen wat hierboven staat]. Wait for an explicit go. On corrections: adjust, self-review again, present again. -### 8. After the go +### 8. Write the summary down + +Only after the go. Save the same summary — unchanged, plus a `# ` heading and the +date — to `docs/specs/YYYY-MM-DD-.md` and commit it. -The brainstorm ends here; it does not turn into building. On an explicit go, hand over: +This is not bookkeeping. `plan` reads this file: it needs a decision that was already made, +and after a context reset, a new session, or a `/worktree` in between, the chat summary is +gone. Whatever is not in the file does not reach the plan. Say where you saved it. + +Does the repo have no `docs/` at all, then say so and keep the summary in the chat — do not +create a documentation structure on your own initiative. + +### 9. After the go + +The brainstorm ends here; it does not turn into building. Hand over: | Scope of what was agreed | Next step | |---|---| -| Multiple steps or multiple files | `/plan` — write the implementation plan first | +| Multiple steps or multiple files | `/plan docs/specs/.md` — write the implementation plan first | | The diff fits in one sentence | Build it directly, no plan | Say which one it is and why in one line, then start. Do not ask the user to choose between planning and building when the criterion above already decides it. +## Verificatie + +`ceda-verifies: observable` — the brainstorm is done when the decision summary exists as a +file and a reader who was not part of this conversation can tell from it what was decided, +what is an assumption, and what the next step is. Concretely: `docs/specs/-.md` +is committed, every locked decision in the chat is in it, and it names `/plan` or the one-line +build as the follow-up. + ## Important - Building starts only after an explicit go; the only follow-up is `/plan` or building what - was agreed. + was agreed. The one file this skill writes is the summary in `docs/specs/`, and only after + the go. - All user-facing output is in Dutch; keep it terse and recommendation-first. - Avoid the anti-patterns: working through a checklist of questions; asking what you can read yourself; premature constraints (narrowing the solution before the problem is clear); reopening locked decisions; listing options without a recommendation; multiple follow-ups without priority (one primary suggestion, alternatives secondary). diff --git a/.claude/skills/plan/SKILL.md b/.claude/skills/plan/SKILL.md index b50eadd..7a88c27 100644 --- a/.claude/skills/plan/SKILL.md +++ b/.claude/skills/plan/SKILL.md @@ -1,7 +1,7 @@ --- name: plan -description: Zet een genomen besluit om in een uitvoerbaar implementatieplan — bestandsindeling, taken die elk hun eigen testcyclus dragen, exacte paden en commando's, en per taak een issue op het CEDA-board. Gebruik na een go, bij "maak een plan" of "hoe pakken we dit aan", of bij werk over meerdere stappen of bestanden. LET OP — vóór de go hoort `brainstorm`, niet dit. -allowed-tools: Read Write Edit Grep Glob Bash AskUserQuestion Skill +description: Zet een genomen besluit om in een uitvoerbaar implementatieplan — bestandsindeling, taken met eigen testcyclus, exacte paden en commando's, een issue per taak — en voert dat plan daarna taak voor taak uit. Gebruik na een go, bij "maak een plan" of "hoe pakken we dit aan", of bij werk over meerdere stappen of bestanden. LET OP — vóór de go hoort `brainstorm`, niet dit. +allowed-tools: Read Write Edit Grep Glob Bash Task AskUserQuestion Skill license: MIT — afgeleid van superpowers (© 2025 Jesse Vincent) metadata: ceda-id: ceda.plan @@ -25,22 +25,42 @@ this codebase, this toolset, or this problem domain. Everything they need is in which files, which code, which command, what output to expect. Derived from `superpowers:writing-plans` (MIT, © 2025 Jesse Vincent). Changed for CEDA: plans -live in `docs/plans/`, and the tasks land as issues via `/write-issue` instead of in a loose -checklist. +live in `docs/plans/`, the input is the brainstorm summary in `docs/specs/`, and the tasks land +as issues via `/write-issue` instead of in a loose checklist. + +Upstream also ships `plan-document-reviewer-prompt.md`, a subagent that reviews the finished +plan. Not ported: upstream's own `SKILL.md` no longer dispatches it and says the check is a +"checklist you run yourself — not a subagent dispatch". That checklist is step 6 here. ## Workflow When the user invokes `/plan [optional: subject or path to a spec]`: +Create a todo per numbered step below and work them off in order. The steps that get skipped +under time pressure — the self-review in step 6 and the file structure in step 2 — are exactly +the ones that cost an execution round. + ### 1. Check the input -A plan needs a decision that has already been made — a spec, a brainstorm summary, an issue -with an agreed approach. Is there none, then this skill is too early: run `/brainstorm` first -and come back after the go. +A plan needs a decision that has already been made. In order of preference: + +1. A brainstorm summary in `docs/specs/YYYY-MM-DD-.md` — what `/brainstorm` leaves + behind after the go. Was no path given, look there for the most recent file and name which + one you are using. +2. An issue with an agreed approach, or a spec somewhere else in the repo. + +Is there none of these, then this skill is too early: run `/brainstorm` first and come back +after the go. A decision that only exists in the chat scrollback is not an input — the plan is +written for someone who was not there, and that includes you after a context reset. Does the spec cover several independent subsystems? Then propose one plan per subsystem. Each plan must produce working, testable software on its own. +**Isolated workspace.** Is the work going to touch the repo you are standing in, and are you +on `main` or in a worktree that belongs to something else? Then run `/worktree` before you +write the plan. The execution in step 8 commits per task, and those commits need a branch of +their own. + ### 2. Map the file structure first Before any task exists, write down which files are created or modified and what each one is @@ -72,6 +92,11 @@ Header: ```markdown # — implementatieplan +> **Uitvoering:** taak voor taak, een verse subagent per taak, één commit per taak. De stappen +> zijn aanvinkbaar (`- [ ]`); wie dit plan oppakt hoeft de sessie waarin het geschreven is niet +> gezien te hebben. + +**Bron:** **Doel:** <één zin: wat dit oplevert> **Aanpak:** <2-3 zinnen> **Stack:** @@ -175,8 +200,20 @@ Never call `gh issue create` directly; `/write-issue` owns the template and the ### 8. Execute -Execute task by task, in order, with a commit per task. Show the result after each task and -wait before starting the next one — that check is what makes the small tasks worth their cost. +One task at a time, in order, a commit per task. Dispatch a **fresh subagent per task**: it +gets the plan file and the task number, nothing else — no scrollback, no memory of why a +choice was made. That is the whole point of writing exact paths, complete code and literal +commands: the plan gets tested by the only reader who cannot fill in the gaps from memory. +Executing everything yourself in the session that wrote the plan hides exactly the holes step 6 +is looking for. + +After each task: read the diff, run the test the task names, show the result, and wait before +starting the next one. A subagent that got stuck or improvised is a defect in the plan — repair +the plan first, then re-dispatch. + +Is a task too small to be worth a subagent (one line, one file)? Then do it inline and say so. + +Handing the plan to a new session instead is equally valid; the file is written for that. ## Let op: het plan is voor iemand zonder context @@ -194,8 +231,10 @@ task, no placeholder patterns remain, and the names in later tasks match the ear ## Important -- No code before the plan is agreed. Is there no decision yet, then `brainstorm` comes first. +- No code before the plan is agreed. Is there no decision yet, then `brainstorm` comes first, + and its summary in `docs/specs/` is the input here. - Issues only via `/write-issue`, and only after the user says yes — a plan of ten tasks is ten issues on a shared board. -- This skill writes the plan and executes it. Reviewing and landing the result is `ship`, the - pull request is `branch-pr`. +- This skill writes the plan and drives its execution, a fresh subagent per task. The isolated + workspace is `worktree`, reviewing and landing the result is `ship`, the pull request is + `branch-pr`. From 188bfb75437b1f3c9183c938e29aba0167fad4e8 Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Sat, 15 Aug 2026 11:56:56 +0200 Subject: [PATCH 6/8] docs(skills): herkomst naar README, brainstorm sluit af met het plan-commando Vier aanscherpingen op de vorige commit. - Geen docs/specs/? Brainstorm stelt nu voor die aan te maken, met het pad erbij, in plaats van terug te vallen op de chat. Zegt de gebruiker nee, dan noemt de skill wat dat kost: plan heeft geen input. - Stap 9 sluit af met het letterlijke commando, pad ingevuld, plus de vraag of hij het zal draaien. De overgang was eerder alleen een tabelregel. - Brainstorm krijgt de MIT-attributieregel, gelijk aan plan en worktree. De ruggengraat is die van upstream; dan hoort de bronvermelding erbij, ook al is de tekst in huis geschreven. - De uitleg over wat we niet overnemen is documentatie over skills, geen instructie aan het model, en verhuist daarom uit beide SKILL.md-bodies naar .claude/skills/README.md. Die README beschrijft de collectie, de drie gevendorde skills met hun upstream, en per niet-overgenomen onderdeel de reden: de reviewer-prompts, de visual companion, en executing-plans / subagent-driven-development. Hoort op termijn in docs/; dat staat er als slotregel bij. Validator: brainstorm en plan groen, collectie onveranderd op 63 skills, 12 fouten, 110 waarschuwingen. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/skills/README.md | 62 ++++++++++++++++++++++++++++++ .claude/skills/brainstorm/SKILL.md | 46 +++++++++++++--------- .claude/skills/plan/SKILL.md | 7 +--- 3 files changed, 91 insertions(+), 24 deletions(-) create mode 100644 .claude/skills/README.md diff --git a/.claude/skills/README.md b/.claude/skills/README.md new file mode 100644 index 0000000..f04766b --- /dev/null +++ b/.claude/skills/README.md @@ -0,0 +1,62 @@ +# CEDA-skills + +De org-brede skillcollectie. Eén map per skill, met een `SKILL.md` die de frontmatter uit de +Agent Skills-spec draagt plus het CEDA-`metadata`-blok. Zie `skills-ontology` voor wat die +velden betekenen en `create-skill` voor het aanmaken en valideren. + +```bash +python3 .claude/skills/create-skill/scripts/validate-skill.py .claude/skills # hele collectie +python3 .claude/skills/create-skill/scripts/validate-skill.py .claude/skills/ # één skill +``` + +## Herkomst: wat we uit superpowers hebben overgenomen + +[superpowers](https://github.com/obra/superpowers) (MIT, © 2025 Jesse Vincent) is een +persoonlijke plugin, geen org-tooling. Wat het team nodig heeft is daarom gevendord: een kopie +in deze collectie, met `ceda-origin: extended` en `ceda-upstream` als onderhoudslink, zodat +bijwerken mogelijk blijft. + +| CEDA-skill | Upstream | Aangepast voor CEDA | +|---|---|---| +| `brainstorm` | `brainstorming` | Nederlands en caveman-bondig; aannames-eerst met confidence in plaats van een vragenronde; samenvatting landt in `docs/specs/` als input voor `/plan` | +| `plan` | `writing-plans` | Plan in `docs/plans/`; input is de samenvatting uit `docs/specs/`; taken worden issues via `/write-issue` in plaats van een losse checklist | +| `worktree` | `using-git-worktrees` | CEDA-branchnaamgeving; detecteert eerst of je al in een worktree zit | + +`brainstorm` is een randgeval: de tekst is in huis geschreven (commit `19d7e2f`), maar de +ruggengraat is die van upstream — hard gate, "te simpel bestaat niet", 2-3 aanpakken, in delen +presenteren, self-review, doorgeven aan het plan. Daarom `extended` en niet `own`: verandert +upstream die ruggengraat, dan is dat hier het lezen waard. + +## Wat we bewust niet hebben overgenomen + +**De reviewer-subagent-prompts.** Upstream levert `brainstorming/spec-document-reviewer-prompt.md` +en `writing-plans/plan-document-reviewer-prompt.md`: losse prompts om een subagent de spec of +het plan te laten nakijken. Geen van beide upstream-`SKILL.md`'s roept ze nog aan; writing-plans +zegt zelfs expliciet *"This is a checklist you run yourself — not a subagent dispatch"*. De +bestanden komen uit een plan van januari 2026 en zijn blijven liggen toen die review naar inline +verhuisde. Onze self-review-stap in `brainstorm` en `plan` is die inline-versie. Overnemen zou +een ronde terugzetten die upstream zelf geschrapt heeft. + +**De visual companion.** Upstream `brainstorming` heeft een browsergebaseerde metgezel voor +mockups en diagrammen: een gids van ~300 regels plus ~1.400 regels node/bash (lokale HTTP- en +WebSocket-server met session-key, `--open` naar een browsertab). Niet overgenomen, om vier +redenen: + +1. `brainstorm` is een beslisskill; de output is een beslis-samenvatting, geen mockup. Visuele + keuzes horen bij `ui-designer`, `ontwerper-digitaal-product` en `vormgever-npuls-huisstijl`. +2. Gebundelde scripts zijn oppervlak 3 uit `externe-skill-audit`. Een meegeleverde server vergt + een volledige audit en een expliciete `allowed-tools`-grant, in een publieke repo. +3. Upstream noemt hem zelf *"still new and can be token-intensive"*. +4. 1.400 gevendorde regels die we op upstream moeten blijven volgen. + +Wil iemand dit alsnog: eigen skill, eigen audit — niet stil aan `brainstorm` plakken. + +**`executing-plans` en `subagent-driven-development`.** Upstream eindigt `writing-plans` in een +keuze tussen die twee uitvoeringsskills. Wij hebben ze niet geport; `plan` stap 8 doet de +verkorte versie zelf (verse subagent per taak, review tussendoor). Als de uitvoering complexer +wordt dan die stap aankan, is dit het eerste dat alsnog moet komen. + +--- + +Deze pagina hoort op termijn in de gepubliceerde documentatie (`docs/`), niet in `.claude/`. +Hij staat hier zolang de skillcollectie zelf nog geen plek in de mkdocs-navigatie heeft. diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index f903048..77dc403 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -2,6 +2,7 @@ name: brainstorm description: Structureer een brainstorm van idee naar getoetst besluit vóór implementatie, en leg dat besluit na de go vast als document dat het plan daarna kan lezen — geen code. Wanneer iemand een idee wil uitwerken of een besluit wil voorbereiden voordat er code of een plan komt. LET OP — ná de go hoort `plan`, niet dit. allowed-tools: Read Write Grep Glob Bash AskUserQuestion Skill +license: MIT — afgeleid van superpowers (© 2025 Jesse Vincent) metadata: ceda-id: ceda.brainstorm ceda-version: "0.2.0" @@ -21,17 +22,10 @@ metadata: Structured brainstorming from an idea to a tested decision, before any implementation or plan. The output is a decision summary with recommendations — never code. Respond to the user in Dutch, caveman-terse. -`ceda-origin: extended` records the maintenance link with `superpowers:brainstorming`: the -spine is the same (hard gate, "too simple" does not exist, 2-3 approaches, present in sections, -self-review, hand off to the plan), so an upstream change to that spine is worth reading here. -The text is CEDA's own — written in-house, Dutch, assumptions-first with confidence levels — -so there is no MIT attribution line, unlike `plan` and `worktree`, which are ports. - -What upstream carries and this skill deliberately does not: the reviewer-subagent prompt -(upstream abandoned it themselves — their own `SKILL.md` says the self-review is inline, "not -a subagent dispatch") and the browser-based visual companion (a bundled node server; visual -questions belong with `ui-designer` and `vormgever-npuls-huisstijl`, and a bundled server needs -its own `externe-skill-audit`). +Shares its spine with `superpowers:brainstorming` (MIT, © 2025 Jesse Vincent). Changed for +CEDA: Dutch and caveman-terse, assumptions-first with confidence levels instead of a question +round, and the summary lands in `docs/specs/` as the input for `/plan`. Which parts of upstream +are deliberately not here, and why: [`.claude/skills/README.md`](../README.md). ## Workflow @@ -110,22 +104,36 @@ date — to `docs/specs/YYYY-MM-DD-.md` and commit it. This is not bookkeeping. `plan` reads this file: it needs a decision that was already made, and after a context reset, a new session, or a `/worktree` in between, the chat summary is -gone. Whatever is not in the file does not reach the plan. Say where you saved it. +gone. Whatever is not in the file does not reach the plan. -Does the repo have no `docs/` at all, then say so and keep the summary in the chat — do not -create a documentation structure on your own initiative. +Does the repo have no `docs/specs/` yet? Then propose creating it — one line, with the path +you intend to use — and create it once the user agrees. Say no, and the summary stays in the +chat; then also say what that costs: `plan` has no input and the decision has to be repeated +by hand. -### 9. After the go +### 9. Hand over -The brainstorm ends here; it does not turn into building. Hand over: +The brainstorm ends here; it does not turn into building. Two routes: | Scope of what was agreed | Next step | |---|---| -| Multiple steps or multiple files | `/plan docs/specs/.md` — write the implementation plan first | +| Multiple steps or multiple files | `/plan` on the spec — write the implementation plan first | | The diff fits in one sentence | Build it directly, no plan | -Say which one it is and why in one line, then start. Do not ask the user to choose between -planning and building when the criterion above already decides it. +Say which one it is and why in one line. Close with the literal command, path filled in, so +the user can copy it or say go: + +> Besluit staat in `docs/specs/2026-08-15-.md`. Meerdere bestanden, dus eerst een +> plan: +> +> ``` +> /plan docs/specs/2026-08-15-.md +> ``` +> +> Zal ik dat draaien? + +Do not ask the user to choose between planning and building when the criterion above already +decides it — the only question is whether you start now. ## Verificatie diff --git a/.claude/skills/plan/SKILL.md b/.claude/skills/plan/SKILL.md index 7a88c27..1cd427a 100644 --- a/.claude/skills/plan/SKILL.md +++ b/.claude/skills/plan/SKILL.md @@ -26,11 +26,8 @@ which files, which code, which command, what output to expect. Derived from `superpowers:writing-plans` (MIT, © 2025 Jesse Vincent). Changed for CEDA: plans live in `docs/plans/`, the input is the brainstorm summary in `docs/specs/`, and the tasks land -as issues via `/write-issue` instead of in a loose checklist. - -Upstream also ships `plan-document-reviewer-prompt.md`, a subagent that reviews the finished -plan. Not ported: upstream's own `SKILL.md` no longer dispatches it and says the check is a -"checklist you run yourself — not a subagent dispatch". That checklist is step 6 here. +as issues via `/write-issue` instead of in a loose checklist. Which parts of upstream are +deliberately not here, and why: [`.claude/skills/README.md`](../README.md). ## Workflow From 3dccdcc788bebb9d1b60094836b099e4bd2e2d5c Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Sat, 15 Aug 2026 12:00:29 +0200 Subject: [PATCH 7/8] fix(skills): brainstorm stuurt het plan naar een schone sessie De afsluiting bood aan /plan meteen te draaien. Dat slaat de test over waarvoor de samenvatting bestaat: het plan moet uit het bestand geschreven worden door een lezer zonder dit gesprek in context. Nu: /clear, daarna /plan , en geen aanbod om het hier te doen. Plan stap 1 dekt het geval dat iemand toch in dezelfde sessie blijft -- werk uit het bestand, zeg dat, en repareer het bestand als de chat iets heeft wat er niet in staat. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/skills/brainstorm/SKILL.md | 15 +++++++++------ .claude/skills/plan/SKILL.md | 5 +++++ 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index 77dc403..d4afbb3 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -120,20 +120,23 @@ The brainstorm ends here; it does not turn into building. Two routes: | Multiple steps or multiple files | `/plan` on the spec — write the implementation plan first | | The diff fits in one sentence | Build it directly, no plan | -Say which one it is and why in one line. Close with the literal command, path filled in, so -the user can copy it or say go: +Say which one it is and why in one line. Close with the literal command, path filled in, and +send the user to a clean session for it: > Besluit staat in `docs/specs/2026-08-15-.md`. Meerdere bestanden, dus eerst een -> plan: +> plan. Draai `/clear` en daarna: > > ``` > /plan docs/specs/2026-08-15-.md > ``` -> -> Zal ik dat draaien? + +Do not offer to run `/plan` yourself in this session. The plan has to be written from the file, +by a reader without this conversation in context — that is the test of whether the summary is +complete, and running it here skips exactly that test. The same reason the plan itself is +executed by a fresh subagent per task. Do not ask the user to choose between planning and building when the criterion above already -decides it — the only question is whether you start now. +decides it. ## Verificatie diff --git a/.claude/skills/plan/SKILL.md b/.claude/skills/plan/SKILL.md index 1cd427a..4027769 100644 --- a/.claude/skills/plan/SKILL.md +++ b/.claude/skills/plan/SKILL.md @@ -50,6 +50,11 @@ Is there none of these, then this skill is too early: run `/brainstorm` first an after the go. A decision that only exists in the chat scrollback is not an input — the plan is written for someone who was not there, and that includes you after a context reset. +Standing in the session that produced the brainstorm — no `/clear` in between? Then work from +the file anyway, and say so. A hole in the summary that you fill in from memory is a hole the +executor hits later. Is the file missing something the chat does have, then repair the file +first. + Does the spec cover several independent subsystems? Then propose one plan per subsystem. Each plan must produce working, testable software on its own. From 6f9c7233168053d7fab902d5e41ddaa7f3833e8b Mon Sep 17 00:00:00 2001 From: Corneel den Hartogh <6919390+CorneeldH@users.noreply.github.com> Date: Mon, 17 Aug 2026 18:26:54 +0200 Subject: [PATCH 8/8] feat: shrink sessie-terugblik to 0.5.0, drop 'Wat de agent zag' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill's own rule is that it does not reconstruct the session mechanically. That section was the exception to it, and ceda-reflect now gives it a proper home: agent-observaties-*.md in the same data repo, same frontmatter keys, same commit SHAs, so the two join. Verified nothing is orphaned: cedanl/repo-context-as-data holds zero sessie-terugblik-*.md files. The question set is unchanged — all four questions intact. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/skills/sessie-terugblik/SKILL.md | 20 +++++++--------- .../sessie-terugblik/references/vragenset.md | 24 ++----------------- 2 files changed, 11 insertions(+), 33 deletions(-) diff --git a/.claude/skills/sessie-terugblik/SKILL.md b/.claude/skills/sessie-terugblik/SKILL.md index 7d186d5..2464672 100644 --- a/.claude/skills/sessie-terugblik/SKILL.md +++ b/.claude/skills/sessie-terugblik/SKILL.md @@ -5,7 +5,7 @@ allowed-tools: Read Grep Glob Write Bash compatibility: Requires git, python3 and the gh CLI with write access to cedanl/repo-context-as-data metadata: ceda-id: ceda.sessie-terugblik - ceda-version: "0.4.0" + ceda-version: "0.5.0" ceda-type: workflow ceda-subtype: "" ceda-origin: own @@ -96,19 +96,17 @@ naam: commits: .. commit-aantal: entire-checkpoints: [] -skill-versie: "0.4.0" +skill-versie: "0.5.0" --- ``` Daaronder de secties `## Werkwijze`, `## Gebruikt`, `## Ging goed` en `## Blinde vlekken` — -in de woorden van de deelnemer. Dan `## Wat de agent zag` met jouw eigen waarnemingen uit deze -sessie (weglaten als je er geen hebt), en tot slot `## Acties` als checklist. +in de woorden van de deelnemer. En tot slot `## Acties` als checklist. -De regels voor die twee laatste secties staan in `references/vragenset.md`. Kern: jouw -waarnemingen komen ná de antwoorden en staan apart, en acties komen uit wat er gezegd is plus -wat van jouw waarnemingen is blijven staan — nooit uit wat jij er zelf bij bedenkt. +De regels voor `## Acties` staan in `references/vragenset.md`. Kern: acties komen uit wat er +gezegd is, nooit uit wat jij er zelf bij bedenkt. Wil de deelnemer acties toewijzen aan iemand, verwijs dan naar `write-issue`; deze skill maakt geen issues aan. @@ -154,10 +152,10 @@ zijn. Nooit benaderen, nooit "ongeveer deze periode". Een verkeerde SHA is erger Wat deze skill **niet** doet: de sessie machinaal reconstrueren. Geen transcript-analyse, geen samenvatting van tool-gebruik, geen tokens-per-stap. Die laag hoort bij de checkpoint-tooling. -Wat wél mag is `## Wat de agent zag`: een handvol waarnemingen die je kunt aanwijzen — een -skill die niet vuurde terwijl die had gepast, een correctie die nodig was, een omweg. Dat is -geen reconstructie maar een aanvulling, en hij staat apart van de antwoorden zodat het verschil -zichtbaar blijft. De regels staan in `references/vragenset.md`. +Die machinale laag hoort nu bij `ceda-reflect`: correcties, toolfouten en afgewezen tool-calls +landen als `agent-observaties-*.md` in dezelfde data-repo, met dezelfde frontmatter-sleutels. +Beide bestanden wijzen naar dezelfde commits, dus ze zijn achteraf samen te brengen. Zie +`cedanl/ceda-skills-library`, `plugins/ceda-reflect/`. ## Let op: het tokengetal dekt één sessie, niet één werkdag diff --git a/.claude/skills/sessie-terugblik/references/vragenset.md b/.claude/skills/sessie-terugblik/references/vragenset.md index 5cdd58a..d6da86e 100644 --- a/.claude/skills/sessie-terugblik/references/vragenset.md +++ b/.claude/skills/sessie-terugblik/references/vragenset.md @@ -48,34 +48,14 @@ uitkomst; die leeg laten is beter dan er iets bij verzinnen. fout is maar wel een openstaand risico — vraag je alleen naar blinde vlekken, dan blijft die onbesproken. -## Wat de agent zelf zag - -Ná de vier vragen, nooit ervoor: voeg toe wat jij in deze sessie zag en de deelnemer niet -noemde. Dit is de enige plek waar jouw waarneming in het bestand komt, en hij staat apart -onder `## Wat de agent zag`. - -Wat hier hoort — alleen dingen die je kunt aanwijzen: - -- een skill of hulpmiddel dat niet vuurde terwijl het had gepast, met wat het gescheeld had -- een correctie die de deelnemer moest geven, en waarop -- een stap die opnieuw moest, of een omweg die achteraf niet nodig was -- iets wat gevraagd is en niet geleverd - -Wat hier niet hoort: oordelen over de persoon, advies voor de volgende keer, complimenten, en -alles wat je niet aan een concreet moment in deze sessie kunt ophangen. Geen waarneming? Laat -de sectie weg. - -Leg het voor voordat je wegschrijft, samen met de acties. De deelnemer mag regels schrappen — -dit is diens terugblik, niet jouw beoordeling. - ## Wat je met de antwoorden doet - **Overnemen in de woorden van de deelnemer.** Parafraseren maakt het gladder en daarmee waardelozer. Ruim hooguit de haperingen op. - **Niet oordelen, niet corrigeren.** Klopt iets feitelijk niet, noteer het dan zoals het gezegd is; de afwijking tussen beeld en werkelijkheid is zelf een bevinding. -- **Acties destilleer je uit wat er gezegd is**, plus wat er onder `## Wat de agent zag` staat - en is blijven staan. Leg ze voor voor je ze in de checklist zet. +- **Acties destilleer je uit wat er gezegd is.** Leg ze voor voor je ze in de checklist + zet. Nooit uit wat jij er zelf bij bedenkt. - **Geen ongevraagd advies over verbruik.** Het tokengetal staat al in de frontmatter; begint de deelnemer er zelf over, dan praat je erover, anders niet.