About this manual

A tutorial about factories, written by a factory. It would be strange not to say so, and stranger still not to show the gates.

What it is

A working manual on the software-factory model as it stood in July 2026, written for two people: an engineering lead who has been asked whether their team can go dark and needs a defensible answer, and a skeptic who assumes this entire genre is repackaged marketing.

It is built as a textbook over a registry. The seven stations carry the durable argument. Every volatile fact — a company’s throughput, a benchmark score, a review cost — lives in _data/ with the date it was true and the source it came from, and is rendered into the pages from there.

The rule, stated precisely enough to be checkable: no figure about the state of the field is typed into prose. Every one of them arrives through a registry lookup carrying its own as-of date and evidence tier, and the build refuses a figure missing either. (Ordinary counting still happens in sentences — five stages, seven stations — and is not what the rule is about.) That is why a development six months from now costs one registry edit and one line in the update log rather than a rewrite.

The signed note

This site is AI-generated. The prose, the layout, the diagrams and the registries were produced by Claude, driven through a five-stage pipeline by Jörn Dinkla. Saying so is the reason the site is worth reading, not a disclaimer attached at the end. A manual arguing that the interesting question is where the human gates sit has an obligation to show its own.

Which gates were lit

Stage	Who decided	What it produced
Brief	Human	the purpose, the two readers, the page inventory that defines done
Design	Human	approval of a static mock before a single file was scaffolded
Scaffold	Machine	template, tokens, screenshot harness — deterministic floor green
Build loop	Machine, then human	pages written and revised; two independent judges over the pixels and the prose, capped at three rounds; then a person reads it
Publish	Human	repository name, visibility, and the decision to make it live

Three of the five gates are human. The two that are not still hand back to a person before anything becomes visible.

What the machine was not trusted with

Deciding what counts as evidence. The tier attached to every source (and its limits) is an editorial policy enforced by a validator that fails the build, rather than a judgment call made at writing time.
Inventing links. Most sources here carry no URL, because the documents this site was compiled from recorded them without one. Plausible-looking links would have been the easiest thing on this page to fabricate.
The design. A static mock was approved by a person before any page existed, on the argument that a mock is cheap to reject and a finished site is not.

How to update it

The procedure, concretely, for whoever holds this next — including a future model:

Edit the entry in _data/landscape.yml or _data/sources.yml. Give the figure a new as_of date and a source id that exists. just build runs the registry validator first and refuses anything with a missing date, an unknown evidence tier, or a dangling source reference.
Append a dated entry to _updates/, naming what it affects. Do not edit past entries — the trail of what this site used to claim is part of the record.
Leave the stations alone unless the argument moved. If a chapter has to change, say so in the update entry, because that is a different kind of event from a number going stale.

Provenance

The conceptual frame comes from Addy Osmani’s writing on light and dark factories and Dex Horthy’s talk on why software factories fail; the survey of the field comes from a research compilation of the state of the art in mid-2026; the vocabulary is attributed, term by term, in the glossary. The one part not compiled from anyone else’s work is the case study, which is explicit about what one operator’s ten runs cannot demonstrate.

Corrections are welcome and, given the subject, expected.