Hydra leerlijn — Deel 1: Wat is Hydra?

Hydra werkt op OpenSpec-changes. Ben je nog niet bekend met begrippen als spec, change, requirement en scenario? Doe dan eerst de OpenSpec-leerlijn (deel 1 + 2, samen ~30 minuten). Dat scheelt veel terugzoeken in de rest van deze modules.

Een groot deel van Hydra's interne werking leunt op Claude Skills: opsx-*, hydra-gate-*, team-*, test-*. Als je nog nooit een skill geschreven of bekeken hebt, doe dan eerst deel 1 van de Claude Skills-leerlijn (10 minuten). Dat maakt deel 4 van deze leerlijn — waar we de skill-families in Hydra openleggen — veel makkelijker te volgen.

Hydra is Conductions interne agentic CI/CD-platform: een fabriek die OpenSpec-changes omzet in code op een feature branch, gecontroleerd door mechanische gates en, als je daarom vraagt, gereviewd door drie AI-stages. 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 zeven; aan het eind sta je klaar voor deel 2 over de drie pipelines.

Wil je meelezen in je editor? Zodra je repo-toegang hebt, kun je Hydra nu alvast clonen zodat je de bestanden waar de leerlijn naar verwijst direct kunt openen:

git clone [email protected]:ConductionNL/hydra.git
cd hydra

Alleen lezen kan ook prima — de clone wordt pas een harde eis in Deel 5, waar je een echte run start.

De twee repo's: Hydra vs .github

Voor we erin duiken: een korte oriëntatie die elke volgende module makkelijker leesbaar maakt. Twee Conduction-repo's komen continu terug in deze leerlijn, en ze hebben gescheiden taken:

• ConductionNL/hydra (privé) — de fabriek. De pipeline-flows (flows/), de agent-personas (Al Gorithm, Juan Claude, Clyde, Axel), de overgebleven operator-scripts, de .claude/skills/-catalogus (hydra-gate-*, opsx-*, test-*), OpenSpec-changes. Alles wat draait. Clone alleen als je Hydra lokaal wilt draaien of een skill wilt aanpassen.
• ConductionNL/.github (publiek) — de handleiding. Developer-guides, way-of-work, ISO-compliance, de publieke Hydra-1-pager die je (optioneel) als warming-up leest, en gedeelde tooling: de globale Claude-settings en het pakket conduction/hydra-gates waarin de gate-logica zit (deel 3). Alles wat je leest of installeert.

Hydra is de fabriek, .github is de handleiding. Twee repo's, twee doeleinden. De volledige uitsplitsing staat in .github/docs/hydra/README.md.

In één zin

Hydra is een label-gedreven pipeline die een OpenSpec-change omzet in een feature branch met code en een PR waarin de gate-uitslag staat — klaar voor menselijke review en goedkeuring.

Geen "AI-assistent die de developer helpt", maar een fabriek. Je stopt er een OpenSpec-change in en aan de andere kant komt er een PR uit. Die merget Hydra nooit zelf.

Concreet: Hydra werkt op het openspec/changes/<slug>/-mapje — proposal.md, design.md, tasks.md en de spec-delta. Als die termen nieuw zijn, doe eerst de OpenSpec-leerlijn (zie tip bovenaan).

Hoe een change door Hydra reist

Een kort overzicht; deel 2 loopt elke stap langs.

1. Build. Een agent implementeert de change in een checkout van de basisbranch. De pipeline, niet de agent, commit en pusht het resultaat naar feature/<issue>/hydra-build.
2. Gates. De pipeline draait de hydra-gates-suite over de diff. Faalt er een gate, dan volgt één fix-ronde: de agent krijgt de gate-output en repareert alleen wat daarin genoemd wordt, waarna de gates nog één keer draaien.
3. PR. Hydra opent een PR, of de gates nu groen eindigden (build:pass) of rood (build:fail). De gate-output staat in de PR-body.
4. Review, als je erom vraagt. Niets zet automatisch een review in de wachtrij. Zodra iemand het issue het label code-review:queued geeft, lopen er drie stages na elkaar, elk alleen als de vorige slaagde: code review, security review, applier.
5. Een mens merget. Geen enkele flow merget een PR, en geen enkele flow zet een done-label.

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 changes kunnen schrijven, en hoe snel die changes code worden. Hydra automatiseert die tweede stap, met drie expliciete doelen:

1. Doorlooptijd verkorten. De stap van een uitgeschreven change naar een eerste reviewbare PR doet een agent, niet een mens.
2. Kwaliteit borgen. Elke build draait de mechanische hydra-gates-suite voordat de PR opengaat, en de PR laat de uitslag zien. Daarbovenop zitten drie onafhankelijke AI-reviewstages die je in de wachtrij kunt zetten.
3. Vier-ogenprincipe behouden. Hydra merget niet. Er bestaat geen auto-merge-pad: een mens leest de PR en drukt op de knop.

De vier personas

Hydra kent vier personas. Elk speelt één rol en heeft een eigen brief onder agents/<persona>/. Je hoeft hun namen nu niet uit het hoofd te kennen — ze komen terug in deel 2 — maar het helpt om het rollenpatroon vroeg te zien:

Over modellen: de agents/<persona>/config.yaml van elke persona noemt Sonnet. De flows zelf geven geen model mee, dus een stage draait op het model waarmee de hermiq-runner die hem uitvoert is ingesteld. Omgevingsvariabelen als HYDRA_BUILDER_MODEL sturen de flows niet; HYDRA_REVIEWER_MODEL wordt alleen gelezen door het handmatige scripts/manual-review.sh.

Historische noot: een eerder ontwerp liet de builder op Haiku draaien — bouwen leek goedkoop patroonwerk. In de praktijk werd Haiku betrapt op het overslaan van quality gates, ondanks expliciete instructies, en is de config van de builder naar Sonnet gezet. Lees je oudere docs waarin "builder = Haiku" staat, dan weet je waarom die verouderd zijn.

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 gereed is voor Hydra: hij heeft de stage-labels (scripts/create-labels.sh maakt ze aan), de change staat gecommit op de development-branch, en de hydra-gates-suite geeft er een zinvolle uitslag op.

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 maar 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 changes (of specs). Die worden vooraf aangeleverd, of een mens schrijft ze met de hand (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 merget niet. Niet na een groene build, niet na drie geslaagde reviews, en ook niet bij een issue met het label yolo: geen enkele flow leest dat label.

Test jezelf

Vier korte vragen om te checken of je dit deel begrepen hebt. Vastgelopen? Klik Hint. Benieuwd naar het antwoord? Klik Antwoord.

Volgende stap

Nu je weet wat Hydra is, kijken we in deel 2 binnen in de drie pipelines.

Deel 2 — De drie pipelines

Lees meer

Publieke Hydra-overzichtspagina

Lees meer

Het volledige architectuur-document (privé)

Lees meer