TUTORIAL | Hydra leerlijn (publiek)

[WilcoLouwerse]

Achtergrond

Hydra is onze AI-gedreven app-fabriek (builder + reviewer + security-reviewer pipelines) waarmee we Nextcloud-apps en componenten bouwen, reviewen en onderhouden. Er bestaat al uitgebreide documentatie, maar geen samenhangende leerlijn die nieuwe collega's, ZZP-ers of partners stap-voor-stap door het concept en het gebruik leidt.

Update 2026-05-19: de leerlijn wordt volledig publiek gepubliceerd op de Conduction-academy. Eerder was de aanname dat dit intern/besloten moest, maar Hydra zelf is geen geheim — de implementatiedetails leven in ConductionNL/hydra (private), maar het concept, de pipelines, de gates en het gebruik zijn gewoon te delen.

Doel

Een Nederlandstalige leerlijn over Hydra, opgebouwd uit meerdere korte, op elkaar volgende tutorials die ieder één concept behandelen. Lezers moeten na de hele lijn snappen wat Hydra is, waarom het bestaat, en hoe ze er praktisch mee aan de slag kunnen.

Doelgroep

Iedereen die met Hydra (of een vergelijkbare agentic CI/CD-pipeline) aan de slag wil — Conduction-medewerkers, ZZP-developers, partners, en geïnteresseerde lezers van buitenaf. Voorkennis: basis Git, Nextcloud-app development, Claude Code-CLI.

Voorgestelde leerlijn (chaining)

In plaats van één lange tutorial willen we een ketting van korte modules. Voorstel:

1. Wat is Hydra? — concept, doel, waarom AI-gedreven, plaats binnen Conduction. Linkt door naar 2.
2. De drie pipelines — builder, reviewer, security-reviewer; wanneer welke. Linkt door naar 3.
3. Quality gates — wat zijn de gates, waarom mechanisch, hoe falen ze. Linkt door naar 4.
4. Skills & commands — hoe skills passen in de loop. Linkt door naar 5.
5. Een Hydra-run starten op een echte app — eind-tot-eind voorbeeld.
6. Troubleshooting & escalatie — wat te doen als de pipeline vastloopt.

Iedere tutorial begint met "Doe eerst …" en eindigt met "Doe hierna …".

Bestaande documentatie (referenties)

De échte Hydra-documentatie staat in de (private) ConductionNL/hydra repo; dat is de primaire bron. De publieke .github-repo bevat daarnaast een Hydra-overzichtspagina onder docs/hydra/.

Primaire Hydra-bronnen:

• .github/docs/hydra/README.md — publieke overzichtspagina van Hydra: concept, pipeline-stages en gebruik (staat in de publieke .github-repo).
• hydra/README.md — 1-pagina-overzicht: wat is Hydra, hoe loopt de pipeline.
• hydra/CLAUDE.md — de architectuur-bijbel: pipeline-flow, vier container-personas (Al Gorithm, Juan Claude van Damme, Clyde Barcode, Axel Pliér), modelstrategie, label state-machine, slot-systeem, security-constraints, terminal-state guards, recovery-patronen (retry:queued / rebuild:queued).
• hydra/openspec/project.md — volledige architectuur-doc.
• hydra/openspec/architecture/ — 24 org-brede ADRs (constraints die de pipeline afdwingt). Met name ADR-013 (container-pool), ADR-020 (gate-scope = PR-diff), ADR-021 (bounded-fix scope).
• hydra/docs/ — operationele docs:
  • pipeline-overview.md
  • container-architecture.md
  • agentic-workflow.md
  • agent-configuration.md
  • github-workflow.md
  • deployment-models.md
  • context.md
  • docs/retrospectives/ — kant-en-klare faal-/leerverhalen (bv. decidesk-44-45-phase-g.md) als concreet materiaal voor "Troubleshooting & escalatie".
• hydra/scripts/ — referentie voor "hoe start ik een run" (hydra-supervisor.sh, orchestrate.sh, reconcile.sh, dev-run.sh, manual-review.sh).
• hydra/agents/ en hydra/personas/ — definities van de vier personas + 8 Nederlandse test-personas.
• hydra/.claude/skills/ — de hydra-gate-* skills (gate-uitleg) en opsx-* / team-* / test-* skills.

Aanvullend / context (géén Hydra-zelf, wel waarnaar Hydra raakt):

De docs in ConductionNL/.github/docs/claude/ gaan over app-bouw / OpenSpec / Claude-werkplek — niet over Hydra als systeem. Daar slechts naar verwijzen voor randonderwerpen, niet als hoofdbron:

• .github/docs/claude/workflow.md — noemt Hydra alleen als plek waar skills en shared config wonen.
• .github/docs/claude/retrofit.md — relevant voor het verhaal "hoe brengen we een bestaande app onder Hydra" (spec-traceability + retrofit).
• .github/docs/claude/app-lifecycle.md — refereert naar org-brede ADRs in hydra/openspec/architecture/.

Vertrouwelijkheid

Per beslissing 2026-05-19: leerlijn is publiek. unlisted: true en :::warning Intern document-callouts zijn verwijderd uit alle 6 tutorials (commit ff20e9d3). De private-repo-link naar ConductionNL/hydra in Deel 1 is verplaatst naar onderaan de prerequisites met expliciete framing "alleen nodig als je Hydra zelf wilt draaien".

• Hostingvorm: publieke academy-route, geen unlisted-flag
• Geen verwijzingen naar interne IP, klantnamen of credentials in voorbeeldcode — private-repo-link in Deel 1 is bewust en gemarkeerd
• Intern-callouts verwijderd op alle pagina's

Pluvo-vragen (minimaal 4 per tutorial)

Per deel-tutorial minimaal 4 begripsvragen, klaar om later in Pluvo te plaatsen. Voorbeelden voor deel 1 ("Wat is Hydra?"):

1. Wat is het primaire doel van Hydra?
2. Welke drie pipelines onderscheiden we, en in welke volgorde lopen ze?
3. Waarom kiest Hydra voor mechanische quality gates in plaats van alleen AI-review?
4. In welke situatie zou je Hydra niet inzetten en handmatig werken?

Op te leveren

• Beslissing over hostingvorm — publiek op de academy (eerdere keuze voor unlisted is herzien op 2026-05-19)
• Outline van de leerlijn (welke korte tutorials, in welke volgorde) — 6 chained tutorials in tutorial/hydra-leerlijn-intern (PR #37)
• Tutorial 1: Wat is Hydra? (+ 4 Pluvo-vragen) — 4 quizzes (Details collapsibles met hint + antwoord)
• Tutorial 2: De drie pipelines (+ 4 Pluvo-vragen) — 4 quizzes
• Tutorial 3: Quality gates (+ 4 Pluvo-vragen) — 4 quizzes
• Tutorial 4: Skills & commands (+ 4 Pluvo-vragen) — hernoemd naar hydra-tutorial-4-skills (commands zijn sinds Anthropics merge gewoon skills); 4 quizzes
• Tutorial 5: Een Hydra-run starten (+ 4 Pluvo-vragen) — 4 quizzes
• Tutorial 6: Troubleshooting & escalatie (+ 4 Pluvo-vragen) — 4 quizzes
• Cross-links tussen tutorials ("Doe eerst …" / "Doe hierna …") — Prerequisites verwijzen terug, NextSteps verwijzen vooruit, op alle 6 pagina's
• Peer review door iemand uit het Hydra-team — review uitgevoerd door @MWest2020 op PR #37, status: Changes Requested (ZZP-framing, scope creep, lockfile-dedupe-verantwoording)
• Linkcheck — Docusaurus build groen op laatste commit, maar nog te verifiëren: dat de .github/docs/hydra/README.md waar Deel 1 naar wijst bestaat en up-to-date is

Schrijfstijl

Volg de Conduction-schrijfstijl (zie identity.conduction.nl). Voorbeeldstructuur voor opzet: Bestanden bij een Woo-publicatie uploaden. Houd de tutorials kort en behapbaar; liever zes die naar elkaar linken dan één lange.

Tijdregistratie

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

[WilcoLouwerse]

Korte update — branch tutorial/hydra-leerlijn-intern klaar met 6 chained Nederlandse tutorials (commit 9a08a17). PR volgt zo.

[WilcoLouwerse]

Korte zij-update — in PR ConductionNL/conduction-website#46 (Claude Skills-leerlijn) is meteen de legacy "commands"-framing in de Hydra-leerlijn opgeschoond: hydra-tutorial-4-skills-commands → hydra-tutorial-4-skills, met alle cross-references bijgewerkt. Geen inhoudelijke wijziging aan de Hydra-leerlijn zelf — alleen naamgeving + framing zodat het consistent is met de Skills-leerlijn.

[WilcoLouwerse]

Heroverweging audience (2026-05-19)

Tijdens het verwerken van Marks review op PR #37 is besloten de Hydra-leerlijn volledig publiek te maken in plaats van intern/unlisted.

Concrete wijzigingen in commit ff20e9d3:

• unlisted: true verwijderd uit frontmatter van alle 6 tutorials
• :::warning Intern document — niet extern delen callout verwijderd op alle 6 pagina's
• Intern-tag verwijderd uit alle frontmatter
• ZZP/NDA-framing in Deel 1 verwijderd
• Private ConductionNL/hydra-prereq herframed naar "alleen nodig als je Hydra zelf wilt draaien", niet als leesvereiste

Gevolg voor de checklist hierboven

De "Vertrouwelijkheid"-sectie is daarmee deels achterhaald:

• Hostingvorm: niet meer unlisted maar publiek — issue-titel ("intern, niet publiek") klopt strict gesproken niet meer
• Voettekst "Intern document — niet extern delen": verwijderd, want niet meer intern
• Geen interne IP/credentials: blijft staan en is gecheckt

De issue-body laat ik staan voor historische context. Bij merge van PR #37 wordt deze issue gesloten — de huidige titel-mismatch is dan academisch.

Reden

Mark's review wees op een spanning tussen de framing "voor iedereen die het wil/kan gebruiken" en unlisted: true. Plus: de inhoud bevat geen écht gevoelige IP (geen credentials, geen klantnamen, geen ongepubliceerde architectuur die niet ook al in .github/docs/hydra/ staat). De drempel "intern, NDA-only" was hoger dan de inhoud rechtvaardigt.

[MWest2020]

Mark's review wees op een spanning tussen de framing "voor iedereen die het wil/kan gebruiken" en unlisted: true. Plus: de inhoud bevat geen écht gevoelige IP (geen credentials, geen klantnamen, geen ongepubliceerde architectuur die niet ook al in [.github/docs/hydra/](https://github.com/ConductionNL/.github/tree/main/docs/hydra) staat). De drempel "intern, NDA-only" was hoger dan de inhoud rechtvaardigt.

Ik heb enkel gewezen op SXXXXEE?

[WilcoLouwerse]

PR is ondertussen gemerged, nu nog naar main mergen en in Pluvo plaatsen