Skip to main content
AcademytutorialHydra tutorial series — Part 1: What is Hydra?

Hydra tutorial series — Part 1: What is Hydra?

A short introduction to Hydra, Conduction's agentic CI/CD platform. What it does, why it exists, and where it sits inside our app factory. The first of seven short modules.

TutorialHydraAICI/CDTutorial series
Conduction·12 mei 202612 min read

Hydra runs on OpenSpec changes. If you're not yet familiar with terms like spec, change, requirement and scenario, take the OpenSpec tutorial series first (parts 1 and 2, roughly 30 minutes together). It will save you a lot of backtracking in the rest of these modules.

A large part of Hydra's internals leans on Claude Skills: opsx-*, hydra-gate-*, team-*, test-*. If you've never written or read a skill, take part 1 of the Claude Skills tutorial series first (10 minutes). That makes part 4 of this series — where we open up the skill families inside Hydra — a lot easier to follow.

Hydra is Conduction's internal agentic CI/CD platform: a factory that turns OpenSpec changes into code on a feature branch, checked by mechanical gates and, when you ask for it, reviewed by three AI stages. This module explains in ten minutes what Hydra is, why it exists, and how it fits inside our app factory. It is the first part of a seven-part series; by the end you're ready for part 2 on the three pipelines.

Want to follow along in your editor? Once you have repo access, clone Hydra now so you can open files referenced in the series as we go:

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

Reading-only is totally fine too — the clone only becomes a hard requirement in Part 5, where you actually trigger a run.

The two repos: Hydra vs .github

Before we dive in, a quick orientation that will make every later module easier to read. Two Conduction repos come up constantly across the series, and they have separate jobs:

  • ConductionNL/hydra (private) — the factory. The pipeline flows (flows/), the agent personas (Al Gorithm, Juan Claude, Clyde, Axel), the remaining operator scripts, the .claude/skills/ catalogue (hydra-gate-*, opsx-*, test-*), OpenSpec changes. Everything that runs. Clone it only if you want to run Hydra locally or modify a skill.
  • ConductionNL/.github (public) — the manual. Developer guides, way-of-work, ISO compliance, the public Hydra one-pager you're (optionally) reading as warm-up, and shared tooling: the global Claude settings, and the conduction/hydra-gates package that holds the gate logic (part 3). Everything you read or install.

Hydra is the factory, .github is the manual. Two repos, two purposes. The full breakdown lives in .github/docs/hydra/README.md.

In one sentence

Hydra is a label-driven pipeline that turns an OpenSpec change into a feature branch with code and a PR carrying the gate results — ready for human review and approval.

Not an "AI assistant that helps the developer", but a factory. You put an OpenSpec change in one end and a PR comes out the other end. Hydra never merges it.

Concretely: Hydra works on the openspec/changes/<slug>/ folder — proposal.md, design.md, tasks.md and the spec delta. If those terms are new, take the OpenSpec series first (see tip at the top).

How a change travels, end to end

A short overview; part 2 goes through every step.

  1. Build. An agent implements the change in a checkout of the base branch. The pipeline, not the agent, commits and pushes the result to feature/<issue>/hydra-build.
  2. Gates. The pipeline runs the hydra-gates suite over the diff. If any gate fails, there is one fix pass: the agent gets the gate output and fixes only what it names, and the gates run once more.
  3. PR. Hydra opens a PR whether the gates ended green (build:pass) or red (build:fail). The gate output is in the PR body.
  4. Review, when asked. Nothing queues a review automatically. When someone labels the issue code-review:queued, three stages run one after another, each only if the previous one passed: code review, security review, applier.
  5. A human merges. No flow merges a PR, and no flow sets a done label.

Why does Hydra exist?

Conduction builds a lot of open-source apps for the Nextcloud workplace. The rhythm of that factory is determined by two things: how fast we can write changes, and how fast those changes become code. Hydra automates that second step, with three explicit goals:

  1. Shorten lead time. The step from a written change to a first reviewable PR is done by an agent, not by hand.
  2. Lock in quality. Every build runs the mechanical hydra-gates suite before its PR is opened, and the PR shows the result. On top of that sit three independent AI review stages you can queue.
  3. Preserve the four-eyes principle. Hydra does not merge. There is no auto-merge path: a human reads the PR and presses the button.

The four personas

Hydra has four personas. Each plays one role and has its own brief under agents/<persona>/. You don't have to memorise their names now — they come back in part 2 — but it helps to spot the role pattern early:

About models: each persona's agents/<persona>/config.yaml names Sonnet. The flows themselves pass no model flag, so a stage runs on whatever model the hermiq runner that executes it is configured with. Environment variables such as HYDRA_BUILDER_MODEL do not steer the flows; HYDRA_REVIEWER_MODEL is read only by the manual scripts/manual-review.sh.

History note: an earlier design ran the builder on Haiku — building looked like cheap pattern-following. In practice Haiku was caught skipping quality gates despite explicit instructions, so the builder's config was moved to Sonnet. If you read older docs that say "builder = Haiku", this is why they're out of date.

When to use, when not

Hydra is no silver bullet. The rule of thumb:

Use it when:

  • The work fits inside one coherent OpenSpec change (one feature, not a refactor of the whole system).
  • The acceptance criteria can be checked mechanically (tests exist, or can be written quickly with PHPUnit/Newman/Playwright).
  • The target repo is ready for Hydra: it has the stage labels (scripts/create-labels.sh creates them), the change is committed on its development branch, and the hydra-gates suite gives a meaningful result on it.

Don't use it when:

  • It's a one-off spike, prototype, or "let's try something" without reviewer discipline.
  • The architecture changes in a way that doesn't fit one PR (multi-repo refactor, breaking schema change with data migration).
  • You don't trust the gates on the target repo — Hydra is only as safe as its quality checks.
  • The work requires human negotiation with an external party (customer, vendor) before it can start.

What Hydra does not do

A common mistake: thinking Hydra invents your whole product. The opposite is true.

  • Hydra doesn't write changes (or specs). Those are provided up front, or a human writes them by hand (with /opsx-ff).
  • Hydra doesn't do vision or strategy. What features we build is a human choice.
  • Hydra doesn't decide architecture. That's what ADRs are for, maintained by humans (see hydra/openspec/architecture/).
  • Hydra doesn't merge. Not after a green build, not after three passed reviews, and not for an issue labelled yolo: no flow reads that label.

Test yourself

Four short questions to check whether you've understood this part. Stuck? Click Hint. Curious about the answer? Click Answer.

1. What is Hydra's primary purpose?

Hint

Hydra does one specific step in our factory. Which step, and what does it hand over at the end?

Answer

Hydra automates the step from OpenSpec change to feature branch + PR. Three explicit goals:

  1. Shorten lead time — an agent does the implementation step, not a person.
  2. Lock in quality — every build runs the mechanical hydra-gates suite and the PR shows the result; three AI review stages can be queued on top.
  3. Preserve the four-eyes principle — Hydra never merges; a human presses the button. There is no exception for yolo.

2. Why does Hydra rely on mechanical quality gates rather than only AI review?

Hint

AI reviewers can sound convincing without being factually correct. Mechanical checks have one property AI review by definition lacks.

Answer

Mechanical gates are deterministic and unpersuadable. The same diff gives the same result, and a well-reasoned story doesn't change it. Two consequences:

  1. Every PR carries an objective result — the gate output is in the PR body, and a build whose gates stay red is labelled build:fail, so a human sees that before deciding whether to queue a review.
  2. Standards are enforceable across the whole fleet — the same gates run on every repo, whoever reviews that day. A review stage that can't show it ran the gates is not accepted as a pass.

AI review sits on top, not in place of. The two layers catch different classes of problems.

3. What are Hydra's four personas, and which one may NOT change code?

Hint

One persona's role is a binary gate ("does this pass or not?"). Its brief gives it no fix authority.

Answer

The four personas:

  • Al Gorithm — builder. Writes code; the pipeline commits and pushes it.
  • Juan Claude van Damme — code reviewer. His brief allows bounded, mechanical fixes.
  • Clyde Barcode — security reviewer. The same, with a security brief.
  • Axel Pliér — applier. Gives one binary answer: pass or fail. He judges, he doesn't intervene.

4. Name two situations in which you would NOT use Hydra and work by hand instead.

Hint

Think about: does the work fit in one change, is the target repo ready, and is there a non-technical issue that has to be resolved first?

Answer

A few common ones:

  • The work doesn't fit in one OpenSpec change — multi-repo refactor, breaking schema change with data migration.
  • The target repo isn't ready — no stage labels, no change committed on development, or gates you don't trust on that repo. Hydra is only as safe as its gates.
  • Spike or prototype without reviewer discipline — "just trying something out". The overhead isn't worth the gain.
  • Human negotiation required — a customer, vendor or legal point has to be resolved first before the work can begin.

Next step

Now that you know what Hydra is, in part 2 we look inside the three pipelines.

Part 2 — The three pipelines
Read more
Public Hydra overview page
Read more
The full architecture document (private)
Read more