Hydra tutorial series — Part 1: What is Hydra?

Hydra is Conduction's internal agentic CI/CD platform: a factory that turns OpenSpec proposals into reviewed, tested code on a feature branch. 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 six-part series; by the end you're ready for part 2 on the three pipelines.

In one sentence

Hydra is a stateless, label-driven pipeline that turns OpenSpec proposals into feature branches with code, tests, a review history and a PR — ready for human approval.

Not an "AI assistant that helps the developer", but a factory. You throw an OpenSpec change in one end and out the other end rolls a PR that two independent reviewers have looked at.

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).

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. Without Hydra, an average OpenSpec proposal takes half a day to three days to implement. With Hydra, it's half an hour to a few hours, depending on complexity.
2. Lock in quality. No PR leaves the system without mechanical quality gates (PHPCS, Psalm, PHPStan, ESLint, PHPUnit), an independent code review and an independent security review. Two pairs of AI eyes before a human looks.
3. Preserve the four-eyes principle. Hydra does not merge on its own — except when an issue explicitly carries the yolo flag, and even then all gates have to be green. A human presses the button.

The four personas

Internally, Hydra is built from four ephemeral container personas. Each plays one role, in one container, with scoped credentials and tight turn budgets. You don't have to memorise their names now — they come back in part 2 — but it helps to spot the role pattern early:

Important: Al Gorithm runs on Haiku, the other three on Sonnet (with Opus as fallback). Reason: building follows patterns and is cheap on Haiku; judgement needs more depth. On Claude Max you have separate Sonnet-only and all-models quotas, so this split stretches the budget.

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: has the hydra-gate-* labels, an app-config.json, and runs the standard quality suite.

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 on its own authority. Except for yolo issues — and there, all gates are still hard requirements.

Test yourself

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