Hydra

Hydra is Conduction's agentic spec-driven CI/CD pipeline. It takes an OpenSpec change proposal and runs it through a multi-stage AI pipeline — Builder, automated quality tests, parallel Code and Security Review — and produces a draft pull request ready for a single human approval. No code reaches main without a human in the loop.

It is the factory, not the product. The applications Hydra builds live under Conduction (Codeberg, primary) with legacy/archived projects on the ConductionNL GitHub org; Hydra itself lives at Conduction/hydra.

How it works

Todo Builder Quality tests Browser tests Code review Security review Draft PR Archive

• Builder — implements the change, pushes the branch early, opens a draft PR. The accent of the build phase.
• Quality tests — lint, phpcs, phpmd, psalm, phpstan, phpmetrics, composer audit, eslint, stylelint, npm audit, PHPUnit, Newman. A failure loops back to the Builder for a bounded fix-quality round.
• Browser tests — Playwright MCP runs the GIVEN/WHEN/THEN acceptance criteria against a live Nextcloud. Failures loop back to the Builder for a bounded fix-browser round.
• Code review — reads diff + ADRs, applies bounded in-scope fixes directly to the PR branch. A fail verdict escalates to needs-input — no retry loop (ADR-013).
• Security review — runs after the code reviewer hands off (sequential — reviewers share git state), same bounded fix authority. The orange-hex accent is here because security is the last gate before human approval.
• Draft PR — a human reviews and merges. With the yolo label, the pipeline approves and merges automatically.
• Archive — after merge, sync specs to Specter, generate test scenarios, update changelog.

Traceability. Every line of code traces to its spec via two paths: a @spec PHPDoc tag pointing at openspec/changes/{name}/tasks.md#task-N, and git blame → commit (#N) → PR Closes #N → issue → spec. Branch naming is feature/{issue-number}/{change-name} and every commit includes (#N).

Model selection. Default model for every persona is Sonnet. When the weekly Sonnet quota runs out, the Builder falls back to Haiku (cheaper, still good at pattern-following from tasks.md/design.md); the Reviewers and the Applier fall back to Opus (deeper, since judgment work is the last line of defense before human approval). Authoritative configuration lives in each persona's agents/<persona>/config.yaml in the hydra repo; runtime overrides via HYDRA_BUILDER_MODEL, HYDRA_REVIEWER_MODEL, HYDRA_APPLIER_MODEL, and their *_FALLBACK_MODEL counterparts.

How to use Hydra on your PR

You don't run Hydra yourself — you trigger it with labels.

1. Open an issue in the target repo with a clear acceptance description and add the ready-to-build label. Hydra picks it up.

2. Or, on an existing PR, request review from Hydra by adding a label:

   • code-review:queued — queue a code review.
   • security-review:queued — queue a security review.

   Reviews are sequential by design (the security review consumes the code review's git state). Setting both queued labels at once is not supported and will produce conflicts. Trigger them one at a time.

3. Crashes escalate to needs-input rather than auto-retrying. If a Hydra container fails, or either reviewer emits a fail verdict, you'll see a needs-input label so a human can investigate. There is no retry loop (ADR-013) — recovery is explicit via the retry:queued (fix the flagged findings) or rebuild:queued (start over) labels.

4. The yolo label means auto-merge after the pipeline passes. All phases still run; yolo only removes the human approval gate at the end.

Hydra repo vs .github repo

Hydra is the factory. .github is the manual.

Two separate repos, two distinct purposes, no overlap:

	Conduction/hydra (private)	Conduction/.github (public)
What it contains	Container images, agent personas, orchestration scripts, the .claude/skills/ catalogue (hydra-gate-*, opsx-*, test-*), OpenSpec changes, K8s manifests	Developer guides (docs/claude/), Way-of-Work and onboarding (docs/WayOfWork/), the public Hydra one-pager (docs/hydra/), ISO compliance (docs/iso/), global Claude settings (global-settings/), the usage-tracker tool
What it's for	Running the pipeline — everything that executes	Reading and configuring — everything you study, install once per machine, or hand to a new colleague
Clone it when	You want to run Hydra locally, modify a skill, inspect agent configs, or browse the OpenSpec change backlog	You want to read the docs offline, install the mandatory global Claude settings, or contribute to the developer handbook
Self-description	"Factory, not the product" — from hydra/README.md and hydra/CLAUDE.md	"Central hub for org-level defaults, developer guides, global tooling configuration, and shared documentation" — from .github/README.md

Each repo has its own docs/ directory, and that's not a duplication: Hydra's docs/ covers pipeline internals (container architecture, secrets, cron, retrospectives) — only relevant if you operate the pipeline. .github/docs/ is for everyone using the pipeline as a consumer.

Most developers only need .github. You only need the Hydra clone when you're working on the pipeline (skills, agents, container images) rather than with it (triggering it on your PR via labels).

The standard Hydra enforces

Hydra's mechanical gates are only half the answer to "will this merge?". The other half is the coding standard the gates check against, and that standard is Nextcloud's:

Conduction code must pass Nextcloud's own checks unchanged. We may be stricter than Nextcloud; we may not be different from it.

Formatting is owned by php-cs-fixer via conduction/coding-standard, which extends nextcloud/coding-standard and can only add to it — enforced by that package's invariant test rather than by review. PHP_CodeSniffer keeps only the semantic rules (named parameters, @spec, banned debug functions, removed Nextcloud APIs), with every whitespace and brace sniff removed so the two tools cannot contradict each other.

gate-65 coding-standard-adoption is what holds it in place. It fails an app that keeps a local ruleset, ships no .editorconfig, wires cs:fix to PHPCS, analyses against a nextcloud/ocp below its declared min-version — or pins the gates, the coding standard or the shared workflow instead of tracking the tip.

The full comparison against Nextcloud's own app CI/CD, including what we do not yet run, is in Way of Work → CI/CD and Code Standards.

Where to learn more

For a narrative introduction, the Academy's Hydra tutorial series walks through what Hydra is, the three pipelines, the quality gates, the skill catalogue, and how to start a real run — six short modules. Read it first if you're new to Hydra; come back here for the reference detail.

The deep technical detail stays in the hydra repo:

• hydra/README.md — quickstart and full pipeline overview.
• hydra/docs/ — pipeline-overview, agentic-workflow, container-architecture, github-workflow, deployment-models, agent-configuration.
• hydra/openspec/architecture/ — the org-wide ADRs (data layer, API, backend, frontend, security, container pool, and more). GitHub renders the directory as a browsable index; the directory itself is the authoritative list.
• hydra/.claude/skills/ — every gate (hydra-gate-*), every opsx command (opsx-*), and the Hydra-specific tooling.

For how Hydra fits into the broader Claude-driven development workflow, see Claude workflow.