System schematic · rev 2026-08
Inside the factory
One delivery pipeline does the building. Sixty-five background loops keep the whole plant running while nobody watches. Everything reads and writes the same surface: GitHub issues, PRs, and labels.
Floor plan
Intent in
/hf.issue
becomes a labeled GitHub issue
Delivery pipeline
Orchestrator
hydraflow-find
PlannerRunner
hydraflow-plan
AgentRunner
hydraflow-ready
ReviewRunner
hydraflow-review
state machine = the labels themselves · adr-0002
Release train · adr-0042
Caretaker fleet · 65+ loops · adr-0029
bay detail ↓Foundation · ports & fakes · adr-0047
GitHub · model providers (Claude, Codex, failover) · git worktrees — every port ships a high-fidelity fake, so the whole plant runs air-gapped in tests.
The loop fleet
Eight bays, as the System console groups them. The pipeline builds the software; the fleet keeps the factory able to keep building it.
Repo Health
20 loopsKeeps every managed repo clean, green, and safe: garbage collection, stale-issue cleanup, CI watching, flake tracking, security patching, label-drift repair.
Governance & Audit
12 loopsDetects drift between declared intent and live state — branch protection, ADR citations, repo principles, quality gates — and files evidence instead of silently fixing.
Learning & Insights
11 loopsFeeds what the factory learns back into the factory: per-repo wikis compiled from real runs, adversarial prompt evals, review-insight mining, pricing refresh.
Operations
8 loopsUnsticks and recovers: stalled PRs get requeued, conflicting merges get rebased, epics get swept, GitHub traffic is served from one shared cache, spend is capped.
Autonomy
7 loopsPushes work through without a human when it's safe — pre-flight checks for auto-dispatched agents, bounded triage retries, thrash detection, human directives when it isn't.
Intake
4 loopsTurns raw signal into work: bug reports become structured issues, recurring log errors get clustered and filed, proposed ADRs face a three-judge council.
Meta-Observability
3 loopsMeasures the machinery itself: pipeline-trend analysis and auto-tuning, per-loop fitness scorecards, and a supervisor with the standing goal of keeping the factory alive.
Release
2 loopsThe train to main: cuts release candidates from staging on a fixed cadence behind a full regression gate, and bisects the culprit PR automatically when a candidate goes red.
Load-bearing decisions
The factory runs on 125 Architecture Decision Records. These six carry most of the weight.
ADR-0002
Labels are the state machine
Pipeline state lives on GitHub labels, not in a hidden database. Any human or agent can read an issue and know exactly where it is — and a restart resumes from the labels.
ADR-0003
A worktree per agent
Every agent works in its own git worktree inside a Docker container. Parallel implementations never collide, and a misbehaving agent can be discarded with its workspace.
ADR-0047
Ports with fakes
Every external surface — GitHub, model providers, the workspace — sits behind a Port with a high-fidelity fake. The entire factory runs air-gapped in tests (MockWorld), down to full-machine scenarios.
ADR-0029
The caretaker pattern
Every background loop is a bounded caretaker: it ticks on an interval, does one job, carries a kill switch, and gets fitness-scored. Loops that stop earning their keep are visible.
ADR-0042
Two-tier release
Agent PRs merge to staging all day. A promotion loop cuts release-candidate PRs to main on a fixed cadence, gated by the full regression suite — main only moves when the train is green.
ADR-0021
Persisted state, crash recovery
Every in-flight issue, retry counter, and rollup is JSON-persisted. Kill the process mid-run and it picks up where it left off — worktrees, PRs, labels and all.
The factory documents itself
Loop registry, port map, label state machine, module graph, and the full ADR index are regenerated from the code every four hours and on every PR.