Anatomy of a software factory
Seven primitives carry the load. Each exists because a specific failure is predictable when it is missing.
A software factory is not a tool you install. It is a set of parts arranged so that work can be admitted, attempted, judged and promoted with evidence at every step. Strip working factories down and the same seven parts appear, whatever the language, model or agent runtime.
The order below follows the work: it is admitted as an order, executed in a cell through a runner adapter, judged by gates, recorded in the ledger, informed by skill documents, and decided through a review deck.
Work order
Work order: the admitted unit of work: a human-readable contract stating one objective, its scope, its definition of done, and its limits on time, spend, retries and allowed effects.
Nothing enters a factory as a chat message. It enters as an order. The order is written before execution and is precise enough that the runtime can enforce it and an auditor can reconstruct it afterward: what may this attempt touch, what consequence can it cause, how will success be checked, and what happens if the check is unavailable.
Keeping the order as plain markdown with structured frontmatter is deliberate. It is the floor every richer interface renders from, so acceptance stays inspectable and portable even when the tooling changes.
Open-ended prompting, scope creep, and "done" meaning whatever the agent decided it meant.
Ephemeral cell
Ephemeral cell: a disposable, deny-by-default execution environment created for one attempt at one work order, granted only the capabilities that order needs, and destroyed when the attempt ends.
A cell might be a git worktree, a container or a virtual machine. What matters is that it begins with nothing, receives a scoped workspace, selected tools, allowlisted network routes and time-bound credentials for this order only, and leaves behind only artifacts, evidence and an execution record.
Cells are disposable; responsibility is not. A retry starts from recorded state in a fresh cell rather than inheriting an ever-growing private session, which keeps runs reproducible and keeps credentials out of anything that persists.
Ambient authority, contamination between tasks, and an agent quietly accumulating state nobody can inspect.
Runner adapter
Runner adapter: the thin layer that translates a work order into what one specific agent runtime needs, such as a prompt, permissions and settings, and normalizes what comes back into runtime-neutral events: work order in, events out.
Models and coding agents change faster than factories should. The adapter is where everything specific to one runtime lives, generated per order rather than hand-maintained. The ledger, the gates and the review deck never learn the vocabulary of a particular vendor.
That separation is what lets the same accountable work move from a local model on one attempt to a hosted model on the next, or to a different machine, without losing ownership of the outcome.
Lock-in to one agent runtime and vendor concepts leaking into the factory's permanent records.
Gate
Gate: an acceptance check that runs outside the execution that attempted the work. A run can produce evidence; it cannot certify its own outcome. Together a lane's gates form its gate wall.
A model saying "done" is never evidence that the work is done. Gates freeze acceptance relative to the attempt being judged and record their verdict independently. Safety and conformance checks such as authority, scope, data boundaries and provenance stay deterministic; outcome quality uses whatever the work calls for, from tests and static analysis to sampled human review.
A gate fails closed when required evidence is missing. A red verdict is information, not an ending: the failure output returns to the order as context for a fresh, bounded retry.
Self-grading, reward hacking against a visible proxy, and humans rubber-stamping work they did not examine.
Ledger
Ledger: the append-only record of every state transition and execution attempt, so any outcome can be reconstructed without reading a transcript: who owned it, what ran, what it cost, what the gates said, and what was promoted.
Chat can present or steer work, but in a factory the conversation is never the source of truth. The ledger records orders, attempts, tools, artifacts, gate verdicts, model and provider, cost, latency, retries and approvals.
It does three jobs from one record. Audit: explaining how a lasting effect happened. Diagnosis: reconstructing a failure even when model behavior is not reproducible. Measurement: knowing the cost per accepted outcome at equal or better verified quality, which is the number that decides whether cheaper routing or more autonomy is safe.
Unexplainable changes, and cost or quality claims nobody can check.
Skill document
Skill document: a versioned, own-authored document that teaches agents how to perform a repeatable class of work. It is where a factory's accumulated know-how lives, and where improvement is applied.
Harness code should be small and boring. The cleverness migrates into skill documents: conventions, procedures, examples and checks for one class of work, loaded only when an order calls for them.
Because skills change behavior, they are treated like maintained software: a clear trigger and scope, a version, provenance, test cases, and review with the same care as a code diff. A retro on a failed order produces a proposed edit to a skill, which goes through the same factory as any other change.
Monolithic instruction files that rot, unaudited third-party behavior, and lessons that are learned once and lost.
Review deck
Review deck: a compact, per-order record prepared for the human decision: the order, what changed, the gate verdicts, the cost, and the proposed consequence with its reversal plan. One focused judgment instead of a transcript.
Attention is the scarce resource in a factory. Watching every tool call creates fatigue without improving authority. The review deck concentrates judgment where state will actually change: merge, deploy, publish, send or spend.
The deck is assembled after the gates pass, so the person reviewing supplies one decision rather than supervising the execution. As a narrow, reversible class of action builds a verified record, the decision it asks for can graduate from explicit approval toward evidence-earned pre-authorization.
Approval fatigue, transcript archaeology, and consequences nobody consciously authorized.