academy: internal Hydra leerlijn (6 chained Dutch tutorials)

Initial draft of the internal Hydra learning track requested in
ConductionNL/.github#50. Six short modules (10-20 min each) that take a
reader from "what is Hydra" through a real local run to recovery
patterns, with cross-links forming a complete chain.

All six are marked draft: true + unlisted: true so they stay out of the
public build while the hosting decision (private repo / unlisted route /
besloten branch — first checkbox in #50) is still open. Each page
carries an "Intern document — niet extern delen" banner top and bottom.

Tutorial 5 covers HYDRA_LABEL_PREFIX (ConductionNL/hydra#253) in
depth — the personal-namespace knob that lets multiple devs run Hydra
against the same target repos without colliding on stage labels.
Tutorials 2 and 6 reference it where it intersects with the pipeline
and recovery flows.

Per the updated issue, the new public 1-pager at
.github/docs/hydra/README.md is linked as an optional warm-up from
tutorial 1.

Each tutorial ends with 4 Pluvo questions ready to be lifted into the
Pluvo platform later.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: WilcoLouwerse

academy/2026-05-12-hydra-tutorial-1-wat-is-hydra/index.mdx

@@ -0,0 +1,144 @@
+---
+slug: hydra-tutorial-1-wat-is-hydra
+title: "Hydra leerlijn — Deel 1: Wat is Hydra?"
+contentType: tutorial
+authors: [conduction]
+date: 2026-05-12
+summary: Een korte introductie op Hydra, Conductions agentic CI/CD-platform. Wat doet het, waarom bestaat het, en welke plek het heeft binnen onze app-fabriek. Eerste van zes korte modules.
+tags: [Hydra, AI, CI/CD, Intern, Tutorial series]
+apps: []
+durationMinutes: 10
+series: hydra-tutorial
+partNumber: 1
+draft: true
+unlisted: true
+---
+
+import {Outcomes, Outcome, Prerequisites, PrerequisiteItem, NextSteps, NextStep, HexCard, ContactCta} from '@conduction/docusaurus-preset/components';
+
+:::warning Intern document — niet extern delen
+Deze leerlijn beschrijft IP van Conduction (skills, gates, prompts, pipelines) en is bedoeld voor medewerkers, vertrouwde ZZP-developers en partners onder NDA. Niet doorsturen, niet publiceren, niet citeren in publieke kanalen.
+:::
+
+Hydra is Conductions interne **agentic CI/CD-platform**: een fabriek die OpenSpec-voorstellen omzet in gereviewde, geteste code op een feature branch. Deze module legt in tien minuten uit wát Hydra is, waaróm het bestaat, en hoe het past binnen onze app-fabriek. Het is het eerste deel van een leerlijn van zes; aan het eind sta je klaar voor deel 2 over de drie pipelines.
+
+{/* truncate */}
+
+<Outcomes title="Wat je leert in dit deel">
+  <Outcome>Wat Hydra is in één zin, en waarom we het hebben gebouwd.</Outcome>
+  <Outcome>De vier container-personas in grote lijnen: Al Gorithm, Juan Claude, Clyde, Axel.</Outcome>
+  <Outcome>Wanneer je Hydra wél inzet, en wanneer juist niet.</Outcome>
+</Outcomes>
+
+<Prerequisites title="Wat je nodig hebt">
+  <PrerequisiteItem>Toegang tot de (private) <a href="https://github.com/ConductionNL/hydra">ConductionNL/hydra</a> repo. Vraag dit aan bij je teamlead als je nog geen lid bent.</PrerequisiteItem>
+  <PrerequisiteItem>Basiskennis Git, GitHub issues + PRs, en een idee van wat een Nextcloud-app is.</PrerequisiteItem>
+  <PrerequisiteItem>Bekendheid met Claude Code-CLI op hoofdlijnen (we duiken hier niet in commando's; daarvoor zie deel 4).</PrerequisiteItem>
+  <PrerequisiteItem>Optioneel — de publieke 1-pagina-versie op <a href="https://github.com/ConductionNL/.github/blob/main/docs/hydra/README.md">.github/docs/hydra/README.md</a>. Goede warming-up als je nooit eerder van Hydra hebt gehoord.</PrerequisiteItem>
+</Prerequisites>
+
+## In één zin
+
+Hydra is een **stateless, label-gedreven pipeline** die OpenSpec-voorstellen verandert in feature branches met code, tests, een review-history en een PR — klaar voor menselijke goedkeuring.
+
+Geen "AI assistent die de developer helpt", maar een **fabriek**. Je gooit er een spec in en aan de andere kant rolt er een PR uit waar twee onafhankelijke reviewers naar gekeken hebben.
+
+## Waarom bestaat Hydra?
+
+Conduction bouwt veel open-source apps voor de Nextcloud-werkplek. Het ritme van die fabriek wordt bepaald door twee dingen: hoe snel we **specs** kunnen schrijven, en hoe snel die specs **code** worden. Hydra automatiseert die tweede stap, met drie expliciete doelen:
+
+1. **Doorlooptijd verkorten.** Een gemiddeld OpenSpec-voorstel wordt zonder Hydra in een halve dag tot drie dagen geïmplementeerd. Met Hydra is dat een halfuur tot een paar uur, afhankelijk van complexiteit.
+2. **Kwaliteit borgen.** Geen enkele PR komt het systeem uit zonder mechanische quality gates (PHPCS, Psalm, PHPStan, ESLint, PHPUnit), een onafhankelijke code review en een onafhankelijke security review. Twee paar AI-ogen vóór er een mens kijkt.
+3. **4-eyes principle behouden.** Hydra **merge-t niet zelf** — behalve wanneer een issue expliciet de `yolo`-vlag heeft, en zelfs dan moeten alle gates groen zijn. Een mens drukt op de knop.
+
+## De vier personas
+
+Hydra is intern opgebouwd uit vier ephemere container-personas. Elk speelt één rol, in één container, met scoped credentials en strakke turn-budgets. Je hoeft hun namen nu niet uit het hoofd te kennen — ze komen terug in deel 2 — maar het helpt om vroeg het rollenpatroon te zien:
+
+<HexCard title="Al Gorithm (builder, Haiku)">
+  Bouwt code uit de spec. Ziet nooit reviews terug. Stopt na een vast turn-budget.
+</HexCard>
+
+<HexCard title="Juan Claude van Damme (code reviewer, Sonnet)">
+  Leest alleen de PR-diff, niet de spec. Kan zelf mechanische fixes doorvoeren binnen scope.
+</HexCard>
+
+<HexCard title="Clyde Barcode (security reviewer, Sonnet)">
+  Loopt na Juan Claude. Zelfde shape, plus Semgrep en patroon-matching op CWE-klassen.
+</HexCard>
+
+<HexCard title="Axel Pliér (applier, Sonnet — géén schrijfrechten)">
+  Beslist binair: gaat dit door of niet? Leest beide reviews en de uiteindelijke code. Géén fix-tools.
+</HexCard>
+
+Belangrijk: **Al Gorithm draait op Haiku, de andere drie op Sonnet** (met Opus als fallback). Reden: bouwen volgt patronen en is goedkoop te doen met Haiku; oordelen vraagt meer diepgang. Op Claude Max heb je een aparte Sonnet-only en all-models quota, dus deze splitsing rekt het budget op.
+
+## Wanneer wel, wanneer niet
+
+Hydra is geen wondermiddel. De vuistregel:
+
+**Wel inzetten als:**
+
+- Het werk past binnen één coherente OpenSpec-change (één feature, niet een refactor van het hele systeem).
+- De acceptatiecriteria mechanisch te toetsen zijn (er bestaan tests of die zijn met PHPUnit/Newman/Playwright snel te schrijven).
+- De doel-repo is **gereed** voor Hydra: heeft `hydra-gate-*` labels, een `app-config.json`, en draait de standaard quality-suite.
+
+**Niet inzetten als:**
+
+- Het gaat om een eenmalige spike, prototype, of "even iets uitproberen" zonder reviewer-discipline.
+- De architectuur wijzigt op een manier die niet in één PR past (multi-repo refactor, breaking schema-change met datamigratie).
+- Je geen vertrouwen hebt in de gates op de doel-repo — Hydra is alleen zo veilig als zijn quality checks.
+- Het werk vereist menselijke onderhandeling met een externe partij (klant, leverancier) voordat het kan beginnen.
+
+## Wat Hydra **niet** doet
+
+Een veelgemaakte vergissing: denken dat Hydra je hele product bedenkt. Het tegendeel is waar.
+
+- **Hydra schrijft geen specs.** Die worden vooraf aangeleverd, of een mens schrijft ze handmatig (met `/opsx-ff`).
+- **Hydra doet niet aan visie of strategie.** Welke features we bouwen is een mensenkeuze.
+- **Hydra besluit niet over architectuur.** Daarvoor zijn ADR's, beheerd door mensen (zie `hydra/openspec/architecture/`).
+- **Hydra merge-t niet eigenmachtig.** Behalve `yolo`-issues — en daar zijn alle gates nog steeds harde voorwaarden.
+
+## Pluvo-vragen
+
+Vier begripsvragen om dit deel af te ronden. Antwoorden staan in de tekst hierboven.
+
+1. **Wat is het primaire doel van Hydra?**  
+   *(Hint: het draait om twee dingen — doorlooptijd en kwaliteitsborging op een specifieke stap in onze fabriek.)*
+
+2. **Waarom kiest Hydra voor mechanische quality gates (PHPCS, Psalm, PHPStan, ESLint, PHPUnit) in plaats van alleen AI-review?**  
+   *(Hint: AI-reviewers kunnen overtuigend klinken zonder feitelijk correct te zijn — wat hebben mechanische gates dat AI per definitie niet heeft?)*
+
+3. **Welke vier personas heeft Hydra, en welke is degene die NIET kan schrijven?**  
+   *(Hint: drie schrijven of fixen, één is bewust read-only — die rol is een binaire gate.)*
+
+4. **Noem twee situaties waarin je Hydra juist NIET inzet en handmatig werkt.**  
+   *(Hint: denk aan scope, aan reviewer-discipline op de doel-repo, en aan menselijke onderhandeling.)*
+
+<NextSteps title="Volgende stap" lede="Nu je weet wat Hydra is, kijken we in deel 2 binnen in de drie pipelines.">
+  <NextStep
+    title="Deel 2 — De drie pipelines"
+    href="/academy/hydra-tutorial-2-drie-pipelines"
+    description="Build, code review, security review. Wie doet wat, in welke volgorde, en hoe komt een issue uiteindelijk bij needs-input of done."
+  />
+  <NextStep
+    title="Publieke Hydra-overzichtspagina"
+    href="https://github.com/ConductionNL/.github/blob/main/docs/hydra/README.md"
+    description="De openbare 1-pagina-versie in onze .github-repo. Bedoeld voor wie alleen het wat-en-hoe op hoofdlijnen hoeft te weten, zonder IP-details."
+  />
+  <NextStep
+    title="Het volledige architectuur-document (privé)"
+    href="https://github.com/ConductionNL/hydra/blob/main/openspec/project.md"
+    description="Voor wie nu al het hele plaatje wil zien — alle details, geen samenvattingen. Vereist toegang tot de privé hydra-repo."
+  />
+</NextSteps>
+
+<ContactCta
+  title="Vragen over Hydra of deze leerlijn?"
+  body="Spreek je teamlead aan of stel je vraag in #hydra op Slack. Issues op deze tutorial graag op het bijbehorende GitHub-issue."
+  cta={{ label: "Mail het Hydra-team", href: "mailto:wilco@conduction.nl?subject=Hydra%20leerlijn%20deel%201" }}
+/>
+
+---
+
+*Intern document — niet extern delen.*

academy/2026-05-12-hydra-tutorial-2-drie-pipelines/index.mdx

@@ -0,0 +1,179 @@
+---
+slug: hydra-tutorial-2-drie-pipelines
+title: "Hydra leerlijn — Deel 2: De drie pipelines"
+contentType: tutorial
+authors: [conduction]
+date: 2026-05-12
+summary: Build, code-review en security-review. Wie doet wat, in welke volgorde, en hoe een label-state-machine de hele rit aan elkaar plakt. Tweede van zes korte modules.
+tags: [Hydra, Pipelines, Personas, Intern, Tutorial series]
+apps: []
+durationMinutes: 15
+series: hydra-tutorial
+partNumber: 2
+draft: true
+unlisted: true
+---
+
+import {Outcomes, Outcome, Prerequisites, PrerequisiteItem, NextSteps, NextStep, HexCard} from '@conduction/docusaurus-preset/components';
+
+:::warning Intern document — niet extern delen
+Deze leerlijn beschrijft IP van Conduction. Niet doorsturen, niet publiceren, niet citeren in publieke kanalen.
+:::
+
+In deel 1 zag je dat Hydra vier personas heeft. In dit deel kijken we naar de **pipeline**: hoe die personas na elkaar werken aan één issue, welke labels de overgangen markeren, en wanneer de pijplijn afslaat naar `needs-input`. Aan het eind weet je het label-state-machine van Hydra van buiten en kun je een issue terugleiden naar de juiste fase als hij ergens vastloopt.
+
+{/* truncate */}
+
+<Outcomes title="Wat je leert in dit deel">
+  <Outcome>De drie pipelines (build, code-review, security-review) en hoe ze sequentieel op elkaar overdragen.</Outcome>
+  <Outcome>Het complete label-state-machine: <code>build:queued → ... → done / needs-input</code>.</Outcome>
+  <Outcome>Wat de applier (Axel Pliér) doet, en waarom hij overgeslagen kan worden.</Outcome>
+  <Outcome>Het verschil tussen <code>retry:queued</code> en <code>rebuild:queued</code>.</Outcome>
+</Outcomes>
+
+<Prerequisites title="Wat je nodig hebt">
+  <PrerequisiteItem>
+    Deel 1 doorgenomen: <a href="/academy/hydra-tutorial-1-wat-is-hydra">Wat is Hydra?</a>
+  </PrerequisiteItem>
+  <PrerequisiteItem>Een idee van wat labels op een GitHub-issue zijn en hoe je die toevoegt.</PrerequisiteItem>
+</Prerequisites>
+
+## Drie pipelines, één pijplijn
+
+Hydra heeft technisch gezien drie pipelines: **build**, **code-review** en **security-review**. Maar in praktijk werken ze altijd in dezelfde volgorde, automatisch aangestuurd door labels. Onder de motorkap is dat één state-machine:
+
+```
+ready-to-build (of <prefix>-ready-to-build op een dev-werkstation — zie deel 5)
+    ↓
+build:queued → build:running → build:pass
+    ↓
+code-review:queued → :running → :pass / :fail
+    ↓  (altijd doorlopen — ook bij :fail)
+security-review:queued → :running → :pass / :fail
+    ↓
+beslissing:
+    beide reviews :pass + 0 fixes → done (Axel overgeslagen)
+    beide reviews :pass + ≥1 fix → applier:queued → :running → :pass / :fail
+    één van beide reviews :fail   → needs-input (Axel overgeslagen, mens beslist)
+```
+
+De pijplijn heeft één belangrijke regel: **iedere uitkomst na review is terminaal**. Hydra fix-t niet automatisch in een loop. Slaagt het in één run, mooi. Slaagt het niet, dan komt het issue op `needs-input` en moet een mens beslissen wat de volgende stap is. Daarover meer in deel 6.
+
+## Pipeline 1: Build (Al Gorithm, Haiku)
+
+De builder krijgt de spec, een schone clone van de doel-repo, en een turn-budget. Geen review-history, geen feedback van eerdere runs. Hij implementeert de tasks uit `tasks.md`, draait de quality-suite, opent een draft-PR.
+
+Volgorde binnen de build-fase:
+
+1. **Implementatie** — leest `proposal.md`, `design.md`, `tasks.md`, schrijft code.
+2. **Quality checks** — PHPCS, PHPMD, Psalm, PHPStan, ESLint, Stylelint, `composer audit`, `npm audit`.
+3. **PHPUnit + Newman** — backend en API-tests.
+4. **Browser-tests** — Playwright MCP loopt door de UI heen.
+5. **`fix-quality` / `fix-browser`** — als checks rood worden, krijgt Al Gorithm één tot twee pogingen om mechanisch te repareren. Dit is een *pre-review* fixup, geen review-loop.
+6. **Verdict** — `build:pass` (PR is opengezet) of `build:fail` (kapotte build, `needs-input`).
+
+Belangrijk: Al Gorithm draait op **Haiku**. Reden uit deel 1: hij volgt patronen, hij oordeelt niet. Door hem op Haiku te zetten houden we Sonnet-budget vrij voor de reviewers.
+
+<HexCard title="Wat ziet de builder niet?">
+  Geen reviews, geen verdict-history, geen labels behalve het eigen <code>build:*</code>. Hij weet dus niet dat een eerdere reviewer iets afkeurde — die feedback bereikt hem alleen via een expliciete <code>retry:queued</code>-cyclus (zie onder).
+</HexCard>
+
+## Pipeline 2: Code review (Juan Claude van Damme, Sonnet)
+
+Zodra `build:pass` gezet wordt, queue-t de supervisor automatisch `code-review:queued`. Juan Claude pakt het op:
+
+1. Leest **alleen de PR-diff** (`HYDRA_REVIEW_SCOPE=diff`, ADR-020). Niet de spec, niet de hele repo. Zo blijft de scope behapbaar en wordt elke regel die hij commentaar geeft daadwerkelijk in deze PR aangeraakt.
+2. Loopt de ADR-bibliotheek en gate-skills langs (zie deel 3).
+3. Voor **mechanische, in-scope fouten** mag hij zelf fixen (ADR-021: bounded-fix scope). PHPCS-headers ontbreken? Hij voegt ze toe. Pijnlijke variabele-naam? Niet zijn pakkie-an.
+4. Voor elk gevonden probleem schrijft hij een inline-comment op de PR met prefix `[fixed:...]` of `[unfixed:...]`.
+5. Hij commit + pusht zijn fixes naar de feature branch en zet `code-review:pass` of `code-review:fail` op het issue.
+
+De verdict-JSON die hij schrijft (`reviews/1.json`) bevat `fixes_applied[]` en `unfixed[]` — dat is wat Axel Pliér later leest om zijn binaire beslissing te nemen.
+
+## Pipeline 3: Security review (Clyde Barcode, Sonnet)
+
+Direct na code-review (of die nu `:pass` of `:fail` was) queue-t de supervisor `security-review:queued`. Clyde Barcode loopt op de PR-staat ná Juan Claude's fixes:
+
+- Zelfde shape als code-review, plus **Semgrep** en patroon-matching op CWE-klassen (SQL-injectie, XSS, path-traversal, hardcoded secrets, …).
+- Mag ook bounded fixes pushen in PR-mode.
+- Schrijft `security-review:pass` of `security-review:fail`.
+
+Waarom sequentieel en niet parallel? Omdat Clyde reviewed wat Juan Claude heeft achtergelaten. Parallel zou betekenen dat Clyde naar pre-fix code kijkt — dan zou hij security-issues vinden die Juan Claude al weggepoetst had en moet je de verdicts gaan reconciliëren. Sequentieel is simpeler en duidelijker.
+
+## De applier: Axel Pliér's binaire gate
+
+Met beide reviews binnen heeft Hydra drie opties:
+
+1. **Beide reviews `:pass` én Juan en Clyde hebben samen 0 fixes gepusht.**  
+   Niets veranderd ná de oorspronkelijke build, dus geen nieuwe risico's. **Axel wordt overgeslagen.** Issue krijgt `done`. Bespaart tokens.
+
+2. **Beide reviews `:pass` én er is ≥ 1 fix gepusht.**  
+   De code is gewijzigd na de oorspronkelijke build. Voor we vertrouwen op de uiteindelijke staat draait de orchestrator opnieuw de mechanische gates (PHPCS, Psalm, PHPStan, ...). Slagen die, dan komt Axel Pliér aan zet. Hij leest:
+   - de uiteindelijke diff,
+   - de `fixes_applied[]` + `unfixed[]` uit beide reviews,
+   - alle inline-comments op de PR.
+   
+   En geeft één binair antwoord: `{pass: true}` of `{pass: false, blocking: [...]}`. Hij heeft géén Write- of Edit-tools. Hij oordeelt, hij grijpt niet in.
+
+3. **Eén van beide reviews `:fail`.**  
+   De reviewers zijn de autoriteit. Axel wordt overgeslagen. Issue gaat naar `needs-input`. Een mens beslist of dit een `retry:queued` of `rebuild:queued` waard is (zie deel 6).
+
+## Labels: één bron van waarheid
+
+Hydra is **stateless**. Het hele state-machine staat op de issue-labels op GitHub. De supervisor (de daemon) leest om de zoveel seconden de labels en beslist wat te doen. Crasht een container, dan kijkt de supervisor opnieuw naar de labels en pakt op waar het ophield.
+
+Per stage zijn er vier mogelijke states: `:queued`, `:running`, `:pass`, `:fail`. Die staan **altijd op het issue, nooit op de PR.** Dat is een bewuste keuze: het issue is de eenheid van werk, de PR is een artefact van een buildcycle.
+
+Naast de stage-labels zijn er metadata-labels die ernaast bestaan:
+
+| Label | Betekenis |
+|---|---|
+| `openspec` | Issue volgt het OpenSpec-werkmodel |
+| `yolo` | Mag auto-mergen mits alle gates groen zijn — geen menselijke approve nodig |
+| `agent-maxed-out` | Persona heeft zijn turn-budget opgemaakt; output is mogelijk incompleet |
+| `needs-input` | Hydra heeft de pijplijn gestopt, mens is aan zet |
+
+## `retry:queued` versus `rebuild:queued`
+
+Twee menselijk-getriggerde herstel-labels die teruggrijpen in de pijplijn. Allebei **single-shot** (geen loop):
+
+- **`retry:queued`** — de bestaande PR blijft staan. Hydra bouwt een `feedback.md` met daarin de `unfixed[]`-bevindingen + applier-blockers, dispatcht Al Gorithm in `HYDRA_MODE=fix`, gescoped tot precies de geflagde bestanden. Goedkoop. Geschikt voor: "de reviewers hadden gelijk, builder moet alleen even bijschaven".
+- **`rebuild:queued`** — bestaande PR sluit, branch reset naar `development`, alle cycle-labels eraf, terug naar `build:queued`. Duur. Geschikt voor: "de aanpak van Al Gorithm klopte niet, we beginnen opnieuw met dezelfde spec".
+
+Stelregel: pak altijd het goedkoopste herstel eerst. Eerst `gh pr update-branch <N>` (development → PR mergen), dan `retry:queued`, dan pas `rebuild:queued`. Deel 6 gaat hier dieper op in.
+
+## Pluvo-vragen
+
+1. **In welke volgorde lopen de drie pipelines, en waarom is security-review sequentieel ná code-review en niet parallel?**  
+   *(Hint: denk aan wat Clyde Barcode leest — de pre- of de post-fix versie.)*
+
+2. **Wat is het verschil tussen <code>build:fail</code> en <code>code-review:fail</code> qua vervolgactie?**  
+   *(Hint: één leidt direct tot <code>needs-input</code>; bij de andere loopt de pijplijn nog door naar de volgende stage.)*
+
+3. **In welke situatie wordt Axel Pliér (de applier) overgeslagen, en waarom is dat een bewuste keuze?**  
+   *(Hint: er zijn twee scenario's — beide gaan over of er iets *veranderd* is na de oorspronkelijke build.)*
+
+4. **Wanneer kies je <code>retry:queued</code> en wanneer <code>rebuild:queued</code>?**  
+   *(Hint: de keuze hangt af van of de oorspronkelijke build-aanpak deugde of niet.)*
+
+<NextSteps title="Volgende stap" lede="Nu je het pipeline-skelet ziet, gaan we in deel 3 in op de quality gates — de mechanische scheidsrechters die alle drie de personas in toom houden.">
+  <NextStep
+    title="Deel 3 — Quality gates"
+    href="/academy/hydra-tutorial-3-quality-gates"
+    description="Wat zijn de gates? Waarom mechanisch en niet AI-geoordeeld? Wat doe je als een gate fout positief slaat?"
+  />
+  <NextStep
+    title="Vorige stap — Wat is Hydra?"
+    href="/academy/hydra-tutorial-1-wat-is-hydra"
+    description="Korte herhaling van het waarom en de vier personas."
+  />
+  <NextStep
+    title="De pipeline-architectuur in detail"
+    href="https://github.com/ConductionNL/hydra/blob/main/docs/pipeline-overview.md"
+    description="De volledige pipeline-overview-doc, met alle subtiliteiten over rate-limit fallback, sloten en cron-schedule."
+  />
+</NextSteps>
+
+---
+
+*Intern document — niet extern delen.*