All chapters
  1. Start hereA software factory, from first principles
  2. Primitive · 1A factory, before AI: input, transformation, check, output
  3. Primitive · 2From repetition to a pattern: what stays, what varies, what to leave alone
  4. Primitive · 3The specification as an executable contract
  5. Primitive · 4Build the smallest factory: four stations, two specs, one manifest
  6. Primitive · 5Assembly stations: typed contracts, owners and failure handling
  7. Primitive · 6AI enters the factory: what a model adds, and what stays deterministic
  8. WatchAlgo · 7The WatchAlgo production story: what the repository shows
  9. WatchAlgo · 8A problem as a production unit: the files one unit must contain
  10. WatchAlgo · 9Station by station: description, solution, implementations, visualization
  11. WatchAlgo · 10The visualizer factory: from algorithm state to renderable steps
  12. WatchAlgo · 11Three flavors and three languages: two different contracts
  13. WatchAlgo · 12Looping over a large backlog: scheduling, limits and a failed-case queue
  14. WatchAlgo · 13Long-running agent execution: context, checkpoints and token limits
  15. WatchAlgo · 14Evidence of correctness: tests the producer cannot talk its way past
  16. WatchAlgo · 15The factory learning loop: defects change the pattern, not only the unit
  17. Enterprise · 16Classify the enterprise demand before choosing a pattern
  18. Enterprise · 17Reference enterprise patterns and their variation points
  19. Enterprise · 18Platform foundations: golden paths, templates, registries and catalogs
  20. Enterprise · 19Pattern versus configuration versus business logic
  21. Enterprise · 20Insurance factory, part 1: building the intake contract
  22. Enterprise · 21Insurance factory, part 2: building the underwriting workflow
  23. Enterprise · 22Insurance factory, part 3: trust and observability built in
  24. Enterprise · 23Data and integration engineering: contracts that survive change
  25. Enterprise · 24The CI/CD and deployment factory: from pull request to production
  26. Enterprise · 25Enterprise governance: owners, approved patterns and provenance
  27. Enterprise · 26Scaling safely: many teams, many agents, one set of boundaries
  28. Operations · 27Factory quality engineering: measuring accepted output, not activity
  29. Operations · 28Failure and recovery scenarios: what breaks a factory, and what restores it
  30. Operations · 29The landscape: which tool for which job, read from its own documentation
  31. Operations · 30Design an enterprise software factory: the blueprint and the rollout
  32. ReferenceSources and verification
  33. ReferenceGlossary
  34. AboutAbout this site
THE FACTORY
A pattern plus a specification, through stations whose work is checked by someone else.
THE CASE
WatchAlgo: 3,246 problem units described, 2,380 complete with solution and visualization, read from the repository.
YOU BUILD
Four runnable factories, from four plain stations to a resumable supervisor on SQLite.

A team needs fifty similar things built. Fifty algorithm lessons, or fifty small services that each take a form, check it and store it. The first one is built by hand and it is good. By the tenth, the team notices that most of the work repeats: the same folder layout, the same checks, the same release steps. Only a few decisions really change from one product to the next. By the thirtieth, someone suggests letting coding agents do the repetitive part, many of them at once.

That suggestion is where most trouble starts. An agent can write a plausible solution in seconds and report "done, all tests pass" with complete confidence. Ten agents can do it ten times faster. Nothing in that sentence says the solutions are right, that the tests were the right tests, that two agents did not edit the same file, or that a reviewer can keep up. Speed of generation is not the limit. Trustworthy completion is.

This site is about the system that makes repeated software production trustworthy. It calls that system a software factory, and it means the word literally.

What is the factory?#

A software factory is a production system, not a metaphor for "many agents writing code". It takes a validated specification for one product, combines it with a reusable pattern that fixes the shape every product shares, and sends the work through assembly stations. Each station has declared inputs, outputs, a check and an owner. A quality gate that the station did not write decides whether the work advances. Every run leaves versioned artifacts with hashes and a run record you can resume after a crash. What fails comes back as a defect that changes the pattern, not only the product.

Plain English. A pattern says "every product looks like this". A specification says "this product does that". Stations do the work. Gates decide whether the work is good enough to move on, and they are never the same thing that did the work.

Diagram: The factory line · from demand to a versioned artifact, and back into the pattern

Read left to right. Demand is classified and turned into a specification that code checks before any station runs. A versioned pattern is chosen and the specification is injected into it. The planner builds a dependency graph and assigns stations, in parallel only where work is independent. Stations produce artifacts. Verification that the stations did not write decides what is accepted, and release gates decide what ships. Defects and measurements return as the next version of the pattern.

  1. 1 · Demand
    1. backlog and request: Demand is classified: users, data, systems, risk. Unknowns become questions, not guesses.
  2. 2 · Pattern + spec
    1. versioned pattern: The pattern fixes structure, interfaces, conventions and the station graph. The spec fills the variation points.
  3. 3 · Plan
    1. dependency graph: The planner orders stations by dependency and runs independent ones in parallel within limits.
  4. 4 · Stations
    1. station work: Each station consumes declared inputs and writes an immutable artifact with a hash.
  5. 5 · Verify and release
    1. independent gates: Checks the producer did not write decide what is accepted; release gates decide what ships.
  6. 6 · Learn
    1. defects and metrics: Every run is recorded. Defects are classified, and fixes go into the pattern so the next batch inherits them.

Read the diagram top to bottom. Demand becomes a specification that is checked before any work starts. A versioned pattern is selected and the specification is injected into it. A planner builds the dependency graph and assigns stations, in parallel only where the work is really independent. Stations produce artifacts; independent verification decides what is accepted; release gates decide what ships. What the factory learns from defects flows back into the next version of the pattern.

Before AI. None of this is new. Maven archetypes and Spring Initializr generate a project from a template; Make and Gradle build a dependency graph; Jenkins and GitHub Actions run stages with gates; platform teams publish a golden path. What a language model adds is the ability to fill in variable business logic from a description. It also adds non-determinism, context limits and confident wrong answers, which is why the checks around it must get stronger, not weaker.

The smallest version of the whole idea fits in one lab. Edit the specification below and four deterministic stations run again: validate, render, test, write a manifest. Change one example so it is wrong, and the test station refuses it.

StationWhat it does with the running-sum specWhat makes it fail
S1 validateChecks the spec against its versioned schemaa missing field, such as acceptance criteria
S2 renderFills the pattern's template with the spec: same input, same bytesnothing: it has no judgment to get wrong
S3 testRuns every example in the spec against the artifactan example whose expected output is wrong
S4 manifestRecords spec hash, artifact hashes and test evidenceit runs only after S3 passes

The smallest factory chapter builds exactly this in Python and proves that two runs give byte-identical manifests.

What did WatchAlgo demonstrate?#

WatchAlgo is the author's algorithm-learning product. Its content folder holds one folder per algorithm problem, and a complete folder carries three files: a problem description, a solution and a visualization. The author reports that 3,246 problems were implemented with descriptions, solutions and visualizations in three flavors, that specialized agents handled individual station responsibilities, and that the repeatable process ran in long sessions of 30 or more hours until token limits required intervention.

This site treats those as what they are. Some things can be checked in the repository, and were. Others are the author's report, and are labelled that way. The WatchAlgo chapter keeps three columns apart:

ColumnWhat it holdsExample
Observed in the repositoryFolders, files, fields and commits anyone can open3,246 problem folders with a description; 2,773 with a solution; 2,380 also with a visualization; plus one empty folder whose name is an unexpanded shell expression
Reported by the authorThe operational account, not measured hereruns of 30 or more hours until token limits
Teaching reconstructionAn architecture this site proposes to explain the ideaa station map and a toy unit with solution, oracle and visualization

So the author's 3,246 is a correct count of described problems, with one qualifier the repository adds: not all of them are solved and visualized yet, and the pages that lack a file show a "coming soon" placeholder. What the case demonstrates is a pattern applied at scale: one fixed unit contract, filled in thousands of times, where each unit is independent of the others, and where the factory's own defect logs record errors that later stations caught. "Three flavors" turns out to mean three narrative styles of the same lesson, and the code itself appears in three languages, which are two different contracts with two different kinds of check (flavors). What the case does not demonstrate is an enterprise delivery process. Algorithm units have no users with permissions, no shared database, no regulator and no on-call rotation. The blueprint chapter lists exactly where the analogy fails.

How does this apply to an enterprise?#

The enterprise chapters build a second, synthetic case end to end. An insurer sells commercial property insurance through brokers. A broker's email becomes a submission; an underwriting agent gathers evidence and writes a recommendation; a human underwriter decides. On this site the insurer is the factory's customer: the factory builds the intake service and the underwriting-review workflow from a pattern and a product specification. It never makes an underwriting decision itself, and in the software it builds, the model recommends; a person decides.

This is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but the insurer, people, rules and numbers are invented, and nothing here reports the quality of a real system or model.

The enterprise version adds what the algorithm factory never needed: classifying the demand before choosing a pattern, authorization and audit as stations the factory installs in every product, contracts that survive schema changes, release gates with canary and rollback, owners for every pattern, and supply-chain provenance a reviewer can check. It also adds the honest limit. A well-specified product on a standard pattern can be accelerated a lot. A product whose critical path is integration with a legacy system, a security approval or an undecided requirement cannot be accelerated by generating code faster, and no page here pretends otherwise.

What do you build here?#

Four runnable examples, all standard-library Python, all with tests, none with an API key or a network call. Where a model would act, a scripted stand-in plays its part, so the results show how the factory mechanics work, not how good any model is.

Fourteen labs let you change the inputs and watch the factory respond: a spec quality gate, a station conveyor, a WatchAlgo problem explorer built from real excerpts, a batch simulator, a token-limit recovery, release gates and a cost model that shows when adding agents makes the line slower and more expensive.

Where this fits#

Software Factory Engineering is one subject in a series of guides by the same author. Each site owns one question about agentic software and links the others where the subjects meet, instead of repeating them. This one is marked below.

INSTRUCTPrompt EngineeringHow instructions are written, composed, ranked, versioned and defended. CURATEContext EngineeringThe working set the model can see now: selection, retrieval, budget, compaction. REMEMBERMemory EngineeringDurable information and saved execution state, and the difference. CONNECTAgent CommunicationMessages between agents, the A2A protocol, and A2A versus MCP. IDENTIFYAuth EngineeringIdentity, delegation, enforcement and audit for every caller and every hop. PROTECTGuardrails EngineeringEnforceable checks around a probabilistic agent. SEEObservability EngineeringEvidence of what happened: logs, metrics, traces, audit events, replay. ACTTools EngineeringCallable capabilities: schema, execution, MCP tools. INTEGRATEMCP EngineeringShared capabilities across teams: when MCP is justified, identity, authorization, governance. RETRIEVERAG EngineeringRetrieval from SQL rows to production: embeddings, vector indexes, hybrid search, reranking. STRUCTUREStructured Output EngineeringTyped contracts: shape, validation, repair, evolution. COORDINATEAgent OrchestrationThe control plane: what runs next, under which condition. RECOVERAgent ReliabilityAcceptable outcomes despite failures, retries, load and changing dependencies. PublishedHarness EngineeringThe runtime around a model call: the agent harness. PublishedEvals for agentic softwareMeasurement: graders, golden sets, judges, trials, release gates. PLANAsk to ReleasePlanning a change before the first meeting. PRODUCE · you are hereSoftware Factory EngineeringSpecs and reusable patterns turned into independently tested software through governed assembly stations. SHIPDiff to DeployShipping a change with coding agents: hooks, review, lanes, CI.

Three neighbours matter most. Harness Engineering explains the controls around one agent's run; this site explains the production system that many such runs feed. Diff to Deploy, just after this site, follows one change from a diff to production; this site creates many products from one pattern and hands each to that path. Evals for agentic software explains how to measure quality; this site invokes those measurements as gates and decides what advances.

What this is not. This site does not teach how to write prompts, how to orchestrate agents at runtime or how to grade model output. Those have their own sites above. It teaches how to arrange specifications, patterns, stations, gates and run records so that repeated production can be trusted.

How to read this site#

Each chapter starts from a moment where its problem bites, explains the idea in plain words, shows the smallest working version, then gives the same five modules: Try it, WatchAlgo in practice, Enterprise translation, Failure test and Where to go deeper. Advanced notes for experienced readers are folded. If you know a part well, skip it; every chapter links back to the words it uses, and the glossary has them all.

Part I · The primitive. From one function to a tiny factory you can run. A beginner can stop after chapter 5 with a reproducible factory.

Part II · WatchAlgo. The case study, grounded in the repository: the unit, the stations, the visualizer, the flavors, the backlog, long runs, correctness and the learning loop.

Part III · Enterprise. From demand to a governed factory that builds a synthetic insurance service.

Part IV · Operations. Measuring accepted output, recovering from failure, choosing tools, and designing the whole factory.

In one breath#

A software factory is a production system: a checked specification and a versioned pattern go in, stations with declared contracts do the work, gates that the producer did not write decide what advances, and every run leaves artifacts and a record you can resume. WatchAlgo shows a repeated algorithm pattern filled in thousands of times; the enterprise chapters show what a factory must add when products have users, data, permissions and owners. The measure of a factory is accepted, verified output, never the number of agents or the volume of generated code.

Start with chapter 1, where the whole idea fits in one small function and four questions about it.