Hydra tutorial series — Part 2: The three pipelines

In part 1 you saw that Hydra has four personas. In this part we look at the pipeline: how those personas work on one issue one after another, which labels mark the transitions, and when the pipeline diverts to needs-input. By the end you'll know Hydra's label state machine inside out and you'll be able to steer an issue back to the right phase if it gets stuck somewhere.

Three pipelines, one pipeline

Hydra technically has three pipelines: build, code-review and security-review. But in practice they always run in the same order, automatically driven by labels. Under the hood it's one state machine:

ready-to-build (or <prefix>-ready-to-build on a dev workstation — see part 5)
    ↓
build:queued → build:running → build:pass
    ↓
code-review:queued → :running → :pass / :fail
    ↓  (always traversed — even on :fail)
security-review:queued → :running → :pass / :fail
    ↓
decision:
    both reviews :pass + 0 fixes → done (Axel skipped)
    both reviews :pass + ≥1 fix → applier:queued → :running → :pass / :fail
    one of the reviews :fail     → needs-input (Axel skipped, human decides)

The pipeline has one important rule: every outcome after review is terminal. Hydra doesn't automatically fix in a loop. If it succeeds in one run, great. If not, the issue lands on needs-input and a human has to decide the next step. More on that in part 6.

Pipeline 1: Build (Al Gorithm, Haiku)

The builder receives the change, a clean clone of the target repo, and a turn budget. No review history, no feedback from earlier runs. He implements the tasks from tasks.md, runs the quality suite, opens a draft PR.

Order within the build phase:

1. Implementation — reads proposal.md, design.md and tasks.md from openspec/changes/<slug>/ in the target repo, writes code.
2. Quality checks — PHPCS, PHPMD, Psalm, PHPStan, ESLint, Stylelint, composer audit, npm audit.
3. PHPUnit + Newman — backend and API tests.
4. Browser tests — Playwright MCP walks through the UI.
5. fix-quality / fix-browser — if checks go red, Al Gorithm gets one or two attempts to mechanically repair. This is a pre-review fixup, not a review loop.
6. Verdict — build:pass (PR has been opened) or build:fail (broken build, needs-input).

Important: Al Gorithm runs on Haiku. Reason from part 1: he follows patterns, he doesn't judge. By putting him on Haiku we keep the Sonnet budget free for the reviewers.

Pipeline 2: Code review (Juan Claude van Damme, Sonnet)

Once build:pass is set, the supervisor automatically queues code-review:queued. Juan Claude picks it up:

1. Reads only the PR diff (HYDRA_REVIEW_SCOPE=diff, ADR-020). That keeps the scope manageable and ensures every line he comments on is actually touched in this PR.
2. Walks the ADR library and gate skills (see part 3).
3. For mechanical, in-scope errors he may fix himself (ADR-021: bounded-fix scope). Missing PHPCS headers? He adds them. Awkward variable name? Not his department.
4. For each finding he writes an inline comment on the PR with prefix [fixed:...] or [unfixed:...].
5. He commits and pushes his fixes to the feature branch and sets code-review:pass or code-review:fail on the issue.

Juan doesn't write out his fixes_applied[] and unfixed[] as JSON himself — the orchestrator only bundles them into one round file after the next step (Clyde). See "How verdicts are persisted" below.

Pipeline 3: Security review (Clyde Barcode, Sonnet)

Right after code review (whether :pass or :fail), the supervisor queues security-review:queued. Clyde Barcode runs on the PR state after Juan Claude's fixes:

• Same shape as code review, plus Semgrep and pattern matching on CWE classes (SQL injection, XSS, path traversal, hardcoded secrets, …).
• May also push bounded fixes in PR mode.
• Writes security-review:pass or security-review:fail.

Why sequential and not parallel? Because Clyde reviews what Juan Claude left behind. Parallel would mean Clyde looks at pre-fix code — he would then find security issues that Juan Claude had already cleaned up and you'd have to reconcile verdicts. Sequential is simpler and clearer.

How verdicts are persisted

After a complete review round (Juan + Clyde back to back), the orchestrator bundles both verdicts into one file on the feature branch: openspec/changes/<slug>/reviews/<round>.json in the target repo. Rounds number sequentially — 1.json after the first pass, 2.json after a retry:queued cycle, and so on (just ls reviews/*.json | wc -l plus one). That file holds the fixes_applied[] and unfixed[] from both reviewers combined — which is what Axel Pliér will read later. An aggregated status snapshot runs alongside in openspec/changes/<slug>/hydra.json (see part 6 for the structure and how to read it).

The applier: Axel Pliér's binary gate

With both reviews in, Hydra has three options:

1. Both reviews :pass and Juan and Clyde together pushed 0 fixes.
   Nothing changed after the original build, so no new risks. Axel is skipped. Issue gets done. Saves tokens.

2. Both reviews :pass and ≥ 1 fix was pushed.
   The code has changed since the original build. Before we trust the final state, the orchestrator reruns the mechanical gates (PHPCS, Psalm, PHPStan, ...). If those pass, Axel Pliér is up. He reads:

   • the final diff,
   • the fixes_applied[] + unfixed[] from both reviews,
   • all inline comments on the PR.

   And gives one binary answer: {pass: true} or {pass: false, blocking: [...]}. He has no Write or Edit tools. He judges, he doesn't intervene.

3. One of the reviews :fail.
   The reviewers are the authority. Axel is skipped. Issue goes to needs-input. A human decides whether this warrants a retry:queued or rebuild:queued (see part 6).

Labels: one source of truth

Hydra is stateless. The whole state machine lives on the issue labels on GitHub. The supervisor (the daemon) reads the labels every few seconds and decides what to do. If a container crashes, the supervisor looks at the labels again and picks up where it left off.

Per stage there are four possible states: :queued, :running, :pass, :fail. They always live on the issue, never on the PR. That's a deliberate choice: the issue is the unit of work, the PR is an artefact of a build cycle.

Alongside the stage labels there are metadata labels that live next to them:

retry:queued versus rebuild:queued

Two human-triggered recovery labels that reach back into the pipeline. Both single-shot (no loop):

• retry:queued — the existing PR stays. Hydra builds an ephemeral feedback.md (in a /tmp/hydra-retry-XXXXXX/ working directory, not committed) containing the unfixed[] findings + applier blockers, mounts it as /workspace/feedback.md in the builder container, and dispatches Al Gorithm in HYDRA_MODE=fix scoped to exactly the flagged files. Cheap. Suitable for: "the reviewers were right, builder just needs to touch up a few things".
• rebuild:queued — existing PR closes, branch resets to development, all cycle labels removed, back to build:queued. Expensive. Suitable for: "Al Gorithm's approach was wrong, we're starting over with the same change".

Rule of thumb: always go for the cheapest recovery first. First gh pr update-branch <N> (merge development → PR), then retry:queued, only then rebuild:queued. Part 6 goes into this in more depth — including the label cleanup steps required before applying either trigger (removing needs-input and fail labels first, otherwise the supervisor won't pick up the queue entry).

Test yourself

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