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
Operations · 30

Design an enterprise software factory: the blueprint and the rollout

The full reference design, four maturity levels, pilot selection, the rollout plan, the architecture review, decision trees for the big choices, operating checklists and the capstone.

You will design
An enterprise factory as ten components, each with an owner and the evidence it leaves.
You will choose
A pilot that produces evidence, and a rollout where every phase ends with a record, not a date.
You will check
A design against review rules and eleven decisions, and say plainly where the WatchAlgo analogy stops.

The synthetic insurer's architecture board meets on a Tuesday. The platform team has been through everything on this site: Example A's reproducible line, Example B's oracle overruling a stand-in's "done", Example C's intake service with its four gates, Example D's run record that survives a crash, a provenance check, a scheduler that knows which tasks are independent. The chair asks one question: "So what do we build first, who owns it, and how will we know it works?"

Nobody can answer in one sentence. The parts are all there, but parts are not a design. Without one, two things happen in most organizations. Either the first project measures "time to generated code", which looks dramatic and says nothing about production, or the team builds every component at once and the pilot stalls in security review. The board needs a blueprint: the components, in an order, with owners, with evidence that moves the factory from one level to the next.

The learner's question: how do you combine the parts of the previous twenty-nine chapters into one factory an enterprise can run, start it on a product that teaches you something, and know when it has earned more autonomy?

A blueprint is a design someone else can check#

Plain English. A blueprint for a factory says what the parts are, who answers for each, what record each part leaves behind, and how work flows between them. If a reviewer cannot point at the record, the part does not exist yet.

A reference blueprint is that design written down for a whole software factory: its components, their owners, the evidence each leaves and the connections between them. The tiny example: "workcell, owned by the platform team, leaves one credential record per run, scoped to one repository." The consequence is that the design becomes reviewable before anything runs, and a rollout can follow it in order. The trade-off is that a blueprint invites building all of it at once, which is the mistake the rollout section exists to prevent.

Before AI. A car plant has a plant layout: stations, conveyors, quality checkpoints, a maintenance crew and a quality office, each with a supervisor. Regulated software shops had the same thing as a written SDLC: an intake form, an architecture standard, a build server, a test environment, a change board and an on-call rota. The blueprint below is that layout for a line where some stations may be staffed by a model.

The blueprint has ten components. The first three decide what to build, the next three build it, two prove and release it, and two run all the time around everything else. Each has a home chapter on this site; the table says what it is for, who owns it at the insurer, and the record a reviewer can ask for.

ComponentIts jobOwner at the insurerEvidence a reviewer can ask forHome
Demand intakeroles, business goal, acceptance examples, priorities, constraints, risk tier, human sign-offsubmissions product ownersigned demand with risk tier highdemand
Pattern registryversioned patterns with owner, applicability, stack, constraints, approved dependencies, migrations, deprecationplatform teamapproved list: PAT-INTAKE-API 2.1.0learning-loop, governance
Spec compiler and validatorschema and semantic checks; unknowns become questions, never guessesplatform teamS1 verdict and the questions it raisedspecification
Plannerstation graph, ownership, data and resource boundaries; parallel only where independentplatform teamthe graph and its levelsstations, scaling
Workcellephemeral worker, scoped credentials, sandboxed tools, resource limits, task contextplatform team, reviewed by securityone credential record per runscaling
Artifacts and stateimmutable outputs, commit SHAs, package digests, provenance, run ids, checkpointsplatform teammanifest digests and the run recordsmallest-factory, long-runs
Verificationdeterministic tests, contracts, evals, security and policy checks, human reviewgate owners, never the producergate report joined to the digestcorrectness, cicd
Releasebuild, sign and record provenance, staging, canary, promotion, rollbackrelease approverrollout manifest and verified provenancecicd, governance
Operationstelemetry, defects, postmortems, pattern updates, metrics, owner on callsubmissions team on calldefect records and their classeslearning-loop, metrics
Governanceteam responsibilities, approved tools, data access, exceptions, auditssecurity reviewer and complianceversioned policy and the exception loggovernance

Three of the components need a name of their own, because the earlier chapters used them without one.

A pattern registry is the place where every pattern version is recorded with its owner, what it applies to and when it will be retired. For example, PAT-INTAKE-API 2.1.0 is approved and 1.9.0 is not. Because the factory reads the registry before any station runs, "use an approved pattern" becomes a lookup instead of advice. The cost is that a new pattern version waits for approval, so the approval path for patches must be fast.

A spec compiler is the first station of every run: it checks a spec's structure and meaning against the pattern and turns every gap into a question with an owner. Example C's S1-validate-spec refuses a spec with an unfilled extension point, or one that opens the decision route to the agent, before anything else starts. It is called a compiler because it turns a request into a checked input for the planner; it does not generate the product.

A workcell is the short-lived box one station attempt runs in: one checkout, a credential scoped to one target and one run, sandboxed tools, resource limits and only the context that task needs. For FR-0003 it may write to one repository and reach two hosts, and it is gone when the attempt ends. The boundary is a property of the runtime, so an injected instruction cannot reach further than the task (Scaling safely).

Diagram: The ten components of an enterprise software factory, and the loop that closes them

Read left to right. Before any work, demand intake classifies the request, the pattern registry offers an approved pattern, and the spec compiler turns gaps into questions. During the work, the planner builds the station graph, each attempt runs in a workcell, and every output lands as an immutable artifact with a run record. Verification and release decide what reaches production. Operations and governance run all the time: defects become pattern updates in the registry, and governance sets the approved list and the policy every release passes.

  1. Decide what to build
    1. demand intake: Classifies the request and gets a person's sign-off before any pattern is chosen.
    2. pattern registry: Lists the approved pattern versions, their owners and what each applies to.
    3. spec compiler: Validates the spec against the pattern and turns every gap into a question with an owner.
  2. Build
    1. planner: Builds the station graph and runs tasks in parallel only when they share no write set.
    2. workcell: Runs one station attempt with a per-run credential, sandboxed tools and resource limits.
    3. artifacts and state: Keeps immutable outputs by digest, with provenance, run ids and checkpoints for resume.
  3. Prove and release
    1. verification: Checks the producer did not write: deterministic tests, contracts, evals, security and policy, human review.
    2. release: Builds, signs, stages and promotes the same digest; rolls back when a threshold is crossed.
  4. Run and govern
    1. operations: Watches the factory and its products, records defects and postmortems, and has an owner on call.
    2. governance: Assigns decisions to roles, keeps the approved tool and data lists, the exception process and audits.

The map reads left to right, but two of its arrows run backwards, and they are what make it a factory rather than a pipeline. Operations sends defect classes back to the pattern registry as new pattern versions, and governance feeds the registry its approved list and tells release who must approve. Every other arrow carries an artifact or a verdict, never a conversation.

Component fields, in more depthWhat each component must hold before a review accepts it

Demand intake holds the nine dimensions of demand classification: users and roles, outcomes, data classes, upstream and downstream systems, security, compliance, deployment targets, service levels, maintainers. It also holds an unknowns register and the risk tier, set by harm, reversibility and regulation, highest signal wins.

Pattern registry entries carry: id and semantic version; owner; the product kinds the pattern applies to and the ones it is wrong for; tech stack; constraints that admit no exception (for PAT-INTAKE-API, only underwriter may decide); approved dependencies; the migration from the previous major version; and a deprecation date. A registry entry with no deprecation date is a pattern nobody plans to retire.

Planner output is a graph plus its levels, as Example D's dag.py : topo_levels produces: tasks inside one level have no path between them. The planner must also record each task's write set, because independence in the graph is not the same as independence on disk.

Workcell fields: the credential's scope and expiry, the network allowlist, the command allowlist for that station, time, attempt and cost budgets charged to a tenant, and the context handed in. No secret enters the context or the trace.

Artifacts and state follow Example D's schema: factory_runs (run id, pattern version, specification hash, status) and station_attempts (station, attempt, status, input hash, artifact reference, test evidence reference, error class). Artifacts are content-addressed, so a rerun with the same input hash reuses them with no second write.

Verification has one rule above all others: the producer never writes the check that accepts its work. Evals are invoked as gates; designing them belongs to Eval Engineering.

Release promotes one digest through environments and rolls back to the previous digest. Example C's rollout manifest names a 5 percent canary for 60 minutes and three rollback conditions, including "any log line containing an unmasked email address"; it is documentation only and deploys nothing.

Operations owns the factory as a product with its own users: the domain teams. It needs telemetry on runs (attempts, yields, queue times, cost per accepted unit), a defect taxonomy and a postmortem habit whose output is a pattern change, not a note.

Governance owns who decides what, the approved tool and data-access lists, the exception process with expiry dates, and the audit that counts exceptions per rule.

How the ten combine: one factory run, end to end#

Follow factory run FR-0003, which builds the broker intake service, through all ten. The submissions product owner signs the demand: outside partners, regulated personal data, an email channel upstream, events downstream, risk tier high. The factory reads the registry and finds PAT-INTAKE-API 2.1.0 approved. S1-validate-spec checks SPEC-INTAKE-001 against it; an empty extension point would have become a question to the spec owner, and no worker would have started.

The planner turns the pattern's station graph into an order: S1-validate-spec, then S2-generate-contracts, S3-assemble-service, S4-write-manifest. Each attempt runs in a workcell that can write one repository. Each output lands by digest, and the run record says which attempt produced it. Verification runs the four gates of Example C (unit tests, contract check, schema compatibility, secret scan); none of them was written by a station worker. Release signs provenance, promotes the same digest to a 5 percent canary, and rolls back on the written conditions. The submissions team is on call. A defect found in production becomes a record with a class, and a recurring class becomes PAT-INTAKE-API 2.1.1. Governance decided, before any of this, which roles approve which of these steps.

Notice what never happens in that walk. No agent decides anything about an insurance case: the factory builds a service in which an underwriting agent recommends and an underwriter decides, and that boundary is enforced by the service's role check, not by the agent's instructions. Ownership and authorization must be enforced independently of agent instructions. A shared tool or component may serve many teams; the credential and the policy, not the prompt, decide what each team's run may touch. Building versus operating keeps the two runs apart: FR-0003 builds; run-7f3a later processes SUB-1004.

Six ways to arrange the work, and which one this blueprint assumesA deterministic graph with agents only at semantic stations

Insurance factory, part 2 is the home of the six arrangements; this is the blueprint-level summary. This site's recommendation for an enterprise factory is the last row, with the others used inside it where they fit.

ArrangementWhere it fitsWhere it fails
One agent per full requestsmall, one-owner jobs with an external checkthe agent writes the code and its tests; self-report is the only evidence
Sequential stationsdependent steps, each with its own checkthroughput capped by the slowest station
Parallel specialistsindependent work items with disjoint write setsshared files turn parallel work into rework
Manager-workermany similar units from one queue (WatchAlgo's September line)the manager becomes a single point of state unless the record is durable
Planner-executorwork whose plan must be inspected before executiona plan nobody checks is a long prompt
Deterministic graph, agents only at semantic stationsenterprise factoriesnone structural; the cost is the discipline of writing the graph and the checks

The last row is the shape of every example on this site: Example A has no model at all; Examples B and D put a scripted stand-in only where a model would write new logic; Example C's four factory stations are deterministic and its only agent is a runtime component of the product it builds.

The smallest primitive: an architecture review as code#

An architecture review is a check, by people outside the team that designed it, of whether a factory design meets written rules. The tiny example: "every component has a named owner" is a rule; "operations: owner missing" is a finding. Most of a review is judgment, but a surprising part is mechanical, and the mechanical part should run every time the design changes.

The script below was written for this page as a teaching reconstruction and run on 2026-11-20. It holds the pilot blueprint as data (ten components, the four tasks of FR-0003 with their write sets, the decision roles and the agent roles) and checks eight rules. What it demonstrates: structural gaps found while they are a line in a design. What it does not demonstrate: whether the owners are the right people, or whether the gates check the right properties. Those stay with the reviewers.

def review(bp: dict) -> list:
    """Return findings. An empty list means the review found nothing; it is not an approval."""
    found = []
    for name in COMPONENTS:
        c = bp["components"].get(name)
        if c is None:
            found.append(f"{name}: component missing")
        elif not c.get("owner") or not c.get("evidence"):
            found.append(f"{name}: needs a named owner and the evidence it leaves")
    tasks = bp["tasks"]
    names = sorted(tasks)
    for i, a in enumerate(names):
        for b in names[i + 1:]:
            independent = a not in ancestors(tasks, b) and b not in ancestors(tasks, a)
            shared = set(tasks[a]["writes"]) & set(tasks[b]["writes"])
            if independent and shared:
                found.append(f"planner: {a} and {b} may run in parallel but both write {sorted(shared)}")
    comp = bp["components"]
    if "*" in comp.get("workcell", {}).get("credential_scope", "*"):
        found.append("workcell: credential is not scoped to one target and one run")
    if comp.get("verification", {}).get("checks_written_by_producer", True):
        found.append("verification: the producer writes the checks that accept its work")
    rel = comp.get("release", {})
    if not rel.get("canary") or not rel.get("rollback_to"):
        found.append("release: needs a canary and a rollback target")
    if set(bp["decision_roles"]) & set(bp["agent_roles"]):
        found.append("governance: an agent role holds a decision route")
    if not comp.get("governance", {}).get("exceptions_expire"):
        found.append("governance: exceptions have no expiry")
    for u in bp["unknowns"]:
        if not u.get("owner"):
            found.append(f"spec_compiler: unknown without an owner: {u['question']}")
    return found

Run on the pilot blueprint, then on a copy with six changes: the operations owner removed, the workcell credential widened to repo:*, S3-assemble-service made to depend only on S1 while also writing openapi.json, the underwriting agent added to the decision roles, and an unknown left without an owner.

pilot blueprint: no findings
changed blueprint:
  operations: needs a named owner and the evidence it leaves
  planner: S2-generate-contracts and S3-assemble-service may run in parallel but both write ['openapi.json']
  workcell: credential is not scoped to one target and one run
  governance: an agent role holds a decision route
  spec_compiler: unknown without an owner: Who may see broker emails unmasked?

The planner finding is the subtle one. Nothing in the changed graph is wrong as a graph: S2 and S3 both follow S1, so a scheduler would run them side by side. Only the write sets show that both would write the contract file, which is how a parallel plan turns into an overwrite. The governance finding is the one that must never reach production: the decision route belongs to underwriter, and a design that lists an agent there fails review whatever the tests say. "No findings" is not an approval. It means the people in the room can spend their time on what code cannot judge.

Four maturity levels, entered with evidence#

A factory should not be trusted all at once. A maturity level is one of four stages a factory reaches for one kind of product, entered only when named evidence exists. The tiny example: the insurer's factory is at level 3 for intake services and level 1 for everything else. The consequence is the site's rule that autonomy is earned per risk tier: less human checking is allowed only where records show it is safe. The trade-off is patience; a team that skips a level usually discovers the missing evidence during its first incident.

LevelNameEntry criteriaEvidence that admits itOn this site
1Repeatableone versioned pattern; specs checked by S1; deterministic stations; a manifest per runbyte-identical rerun; refusals recorded with reasonsExample A
2Verifiedevery station has a check the producer did not write; durable run record; failures classified before retry; bounded retries with escalationgate reports; a resume after a crash with no duplicate write; first-pass yield measuredExamples B and D
3Governedapproved pattern registry; scoped workcells; policy as code naming approvers by risk class; signed provenance; canary and rollback; owner on callprovenance verified at deployment; an automatic rollback seen in a rehearsal; audit trail of approvals; pilot metrics against a baselineExample C plus the governance chapter
4Learningdefect taxonomy feeding versioned pattern changes; blast radius from the catalog; per-tenant quotas; cost per accepted unit tracked; delivery metrics per productnext batch compared fairly on a fixed mix; a postmortem that produced a pattern version; exceptions counted per rulethe learning-loop, scaling and metrics chapters

Two rules keep the table honest. A level is held per product kind and risk tier, never by the whole organization. And a level can be lost: if the run record stops being written, the factory is back at level 1 for that product, whatever it once proved.

Guideline (DORA, read 2026-11-20): DORA currently publishes five software delivery performance metrics, grouped as throughput (change lead time, deployment frequency, failed deployment recovery time) and instability (change fail rate, deployment rework rate). They measure the products the factory ships at level 4; the factory's own line metrics are Factory quality engineering.

How factories fake a maturity levelFour counterfeits a reviewer should recognize

A green dashboard without a denominator. "98 percent of runs succeeded" with no count of refused specs, escalations or incomplete runs claims level 2 while hiding the record level 2 requires. Example D's runs end succeeded or incomplete, never a quiet success with a missing station.

Provenance that is written but never checked. Level 3 asks for provenance verified at deployment, against expectations the reviewer set. A factory that writes signed statements nobody verifies holds level 2 with paperwork.

A rollback that has never run. A rollback threshold in a manifest is a claim. The entry evidence is a rehearsal in which the canary crossed it and the previous digest came back without a person.

Learning measured against a moving checker. Level 4 compares the next batch with the last on a fixed mix with the checker's version held constant. WatchAlgo's validator drift, where rules tightened after files were written, shows how a stricter checker makes a better line look worse, or the reverse.

Choosing the pilot#

A pilot is the first product the factory builds for real use, chosen because it will produce evidence. The tiny example: the insurer pilots the broker intake service, not the underwriting decision. The consequence is that the pilot's job is measurement, not speed: it compares the factory with the old way on the same kind of work. The trade-off is that the most exciting candidate is usually the worst pilot.

Diagram: Choosing a pilot: five questions, asked in order

Ask the questions in order. A pilot needs a reference pattern that fits, a baseline from building the same kind of product the old way, a release that can be undone, every consequential decision left with a person, and a small integration surface whose owners will answer. Each no sends you to a different candidate, not to a bigger factory. The insurer's broker intake service passes all five; replacing the legacy policy administration system fails the second and the fifth.

  1. Ask in order
    1. does a reference pattern fit?: An approved pattern already covers this kind of product.
    2. is there a baseline from the old way?: The team has built this kind of product by hand and can say how long it took and what escaped.
    3. can a release be undone?: A canary and a rollback to the previous digest are possible.
    4. does a person keep every consequential decision?: No step of the product decides an outcome for a customer or a regulator without a person.
    5. is the integration surface small and owned?: Few outside systems, each with an owner who will agree a contract.
  2. Verdict
    1. good pilot: Builds evidence the next decision can rest on.
    2. not a pilot: pick another candidate: The critical path would be discovery and negotiation, not the factory.

Each "no" sends you to a different candidate, not to a bigger factory. The table applies the five questions to the worked pilot and to a tempting bad one.

CriterionBroker intake service (good pilot)Legacy policy administration replacement (bad pilot)
A reference pattern fitsyes: PAT-INTAKE-API 2.1.0 existsno: a modernization adapter pattern would need recorded legacy behavior first
A baseline existsyes: the team built intake services by hand before (Example C's README calls this one the fifth this year)no: nobody has replaced this system, so nothing to compare with
A release can be undoneyes: 5 percent canary, three written rollback conditionspartly: a cutover of policy records is hard to reverse
Every consequential decision stays with a personyes: the underwriter decides; the agent recommendsunclear until the old system's hidden rules are found
The integration surface is small and ownedthree boundaries: email channel, roof-data provider, event consumersevery downstream system that reads policy data

The intake service is a high-risk product, and that is acceptable for a pilot because the factory's own risk is bounded: it builds a service that never decides, the gates are proven to fail on planted defects, and the release can be undone. The legacy replacement fails on the second and fifth questions. Its critical path would be discovering undocumented behavior and negotiating with every consumer, so a pilot there would measure the organization's calendar, not the factory. One candidate is never a pilot at any level: a product in which an agent approves, declines, binds or quotes. This site's recommendation: pilot the intake endpoint and its validation first, and add the agentic recommendation workflow as the next wave once level 2 evidence exists.

The pilot's economics. The economics model's pilot preset is one generation agent at the factory's one semantic station (for the intake service, a coding agent drafting the business-rule module and fixtures from the spec), a base first-pass yield of 0.6, and one reviewer, over one 8-hour shift. Run on a scratch copy of examples/sim/ on 2026-11-20 with a short script that prints the model's result for the preset (selected lines; simulated, illustrative; cost in illustrative units, never currency):

pilot inputs: {"agents": 1, "reviewers": 1, "base_yield": 0.6}
  first_pass_yield           0.6
  attempts_per_hour          3.0
  candidates_per_hour        1.8
  review_capacity_per_hour   5.0
  accepted_per_hour          1.8
  bottleneck                 generation
  accepted                   14.4
  total_cost_units           667.2
  cost_per_accepted          46.333
  cost_per_generated         27.8
  attempts_per_accepted      1.667

The pilot is the most expensive configuration in the lab per accepted unit (46.333, against 27.549 for the default of two agents and a 0.7 yield), and that is correct for a pilot. The reviewer is paid for the whole shift (480 of the 667.2 units) and sits idle most of it: review capacity is 5 per hour, the agent delivers 1.8 candidates. A pilot buys a baseline, a yield measurement and a list of defect classes. Optimizing it would hide the very numbers it exists to produce.

What the pilot's sensitivity says about the next stepYield first, a second agent second, never a second reviewer yet

The model's sensitivity function, run on the same scratch copy, moves each input 20 percent down and up (integers by at least one) and reports cost per accepted unit (simulated, illustrative):

  agents          1 -> 46.333   2 -> 30.807   (base 46.333)
  base_yield      0.48 -> 55.917   0.72 -> 39.944   (base 46.333)
  reviewers       1 -> 46.333   2 -> 79.667   (base 46.333)
  review_minutes  10 -> 46.333   14 -> 46.333   (base 46.333)
  escape_rate     0.032 -> 44.733   0.048 -> 47.933   (base 46.333)

A second reviewer almost doubles the cost, because review is not the bottleneck. Review minutes do not matter at all in this range, for the same reason. Raising the yield from 0.6 to 0.7, the kind of change one pattern fix can buy, gives 2.1 accepted per hour at 40.857; a second agent gives 3.42 at 30.807 and leaves generation the bottleneck. The order this suggests is the order of the rollout: fix the pattern until yield stops moving, then add generation capacity while watching review, and only add reviewers when the review queue grows. Factory quality engineering shows the other side: past the review limit, or on shared files, more agents make the line slower and dearer.

The rollout plan#

A rollout that promises dates for building a factory makes the same mistake as a pilot that measures generated code. The plan below has five phases, and each ends with an exit check that is a record someone can read, and a stop rule written before the phase begins.

Diagram: The rollout: five phases, each ending with evidence, never with a date

Three lanes over five phases. The platform team builds the factory up one maturity level at a time; the submissions team brings the pilot product through; security, compliance and the release approver act at the points the policy names. Every phase ends with an exit check that is a record someone can read, and a stop rule that is written before the phase starts. No phase has a promised duration.

  1. Platform team
    1. register the pattern, scope the identity: PAT-INTAKE-API 2.1.0 approved; the factory identity can write one repository per run.
    2. gates and a durable run record: Every station has a check the producer did not write; a crash resumes with no duplicate write.
    3. blast radius from the catalog: A pattern patch reaches both products and the selective suite runs.
    4. quotas, family of patterns: A second team and a second pattern, with per-tenant budgets and defect classes feeding versions.
  2. Submissions team
    1. baseline and signed spec: Lead time, yield and escapes of the last hand-built intake services; the spec signed by its owner.
    2. the pilot built and tested: The factory builds the intake service in non-production environments with synthetic data.
    3. canary with an owner on call: A small share of real traffic, rollback conditions fixed in advance, the team on call.
    4. claims team builds its intake product: A second team uses the pattern without the platform team writing its rules.
  3. Review roles
    1. security review of the factory identity: The factory's own permissions pass security review like any service account.
    2. release approver, provenance verified: Signed provenance checked at deployment; the release approver signs the promotion.
    3. audit of exceptions and approvals: Open exceptions counted per rule; expired ones closed or renewed by their approver.

The platform team raises the factory one maturity level at a time; the submissions team brings the pilot through; the review roles act where the policy names them. The arrows between lanes are evidence: a phase starts when the previous one's record exists.

PhaseWhat happensExit check (a record)Stop rule, written in advance
Preparebaseline the last hand-built intake services; register PAT-INTAKE-API 2.1.0; security review of the factory identity; sign SPEC-INTAKE-001level 1: a byte-identical rerun of FR-0003; baseline lead time, yield, escapesthe factory identity cannot be scoped to one repository per run
Build off productiongates, run record and resume in non-production environments with synthetic datalevel 2: four gates pass and are proven to fail on planted defects; a resume with no duplicate writegates cannot be kept outside the producer's reach
Controlled releasecanary with written rollback conditions, release approver, provenance verified, team on calllevel 3: a rehearsed automatic rollback; pilot lead time and cost per accepted unit against the baselinecost per accepted unit or escapes worse than the baseline at equal acceptance
Second productthe claims team builds claim-notice-intake on the same pattern; a pattern patch reaches both productsblast radius computed from the catalog; selective suite run; no platform-team edits to the claims team's rulesthe second team needs a fork of the pattern
Widena second pattern and a second team, per-tenant quotas, defect classes feeding versionslevel 4: next batch compared on a fixed mix; exceptions counted per rulequotas or ownership cannot be enforced by the runtime

The stop rules matter more than the exit checks. A pilot that cannot beat its baseline on cost per accepted unit, at equal acceptance, has taught the organization something valuable, and the honest response is to stop or change the design, not to widen it.

The eleven decisions, in one place#

Each decision below has a home chapter with its diagram, its full criteria and its worked counterexample. This table is the index a reviewer keeps open.

DecisionOptionsChoose by, in orderCounterexampleFailure modesHome
Script or template enough, or an agentic factory?hand-written code; template or generator; deterministic factory; model at semantic stationshow often it repeats; parameters or logic vary; cost of an escape; evidence needed per artifactExample A needs no model until a spec asks for logic outside its catalog (median_sorted, refused)template where logic varies; factory for a one-off; model where parameters sufficepattern
How many stations?one; a few coarse; many fineown check; own owner; own failure policy; reused or parallel outputExample A's render station has no validator and earns its place only by its reusable artifacttoo few: failures say nothing; too many: contracts nobody keeps truestations
One agent, specialized agents, or functions?functions; one agent; specialized agents per semantic stationwritable as code ahead of time; checkable by code the agent cannot edit; different briefs, tools or permissionsWatchAlgo's specialization was by instructions, same model; its elaborate role engine shows no outputone agent grading itself; a validator agent where a function would doai-enters
Run in parallel?sequential; parallel over independent units; parallel over shared filesdisjoint write sets; shared ceiling below its limit; integration fast enough8 workers on shared files: rework 20 to 40 percent, throughput down (simulated, illustrative)overwrites; throttling at a shared quota; a longer queue at integrationbacklog
Local CLI loop or distributed queue workers?local loop with file queue; queue service with workersmachines needed; steps waiting on people; who reads the records; where the real ceiling isWatchAlgo's ceiling was the account; more servers would not have raised itrecords on one laptop; partial failures across machinesbacklog
One repository or several?monorepo; several with integration contracts; hybridownership; release together; whole build per change; access rightsthe roof-data provider is a contract in every layoutboundaries that exist only on the diagram; releases as integration tests in productiondata-integration
One pattern or a family?one line; declared variants; family sharing components; separateshared station graph; same reasons and schedule for change; owners; cost of a missed fixWatchAlgo's visualization station had two major versions side by side, unrecordedswitches nobody can test; a fix landed in one sibling onlylearning-loop
Manual approval or automated gate?automated only; automated then a person; person onlyreversibility; risk class; machine-checkability; cost of delaya rollback threshold raised from 2 to 20 percent passes every gaterubber-stamp approvals; gates that check the wrong thingcicd
Integrate into the delivery platform or build new?integrate; extend once; build beside, with an ownerplatform holds the product kind; scoped identity possible; owner in a year; reviews to repeatWatchAlgo rightly built nothing beyond scripts; the insurer's reviewer asks for the catalog on Mondaya registry deployments cannot find; a second catalog that driftsplatform
Golden path or justified deviation?strict; logged exception with expiry; change the pathseverity of harm; deviation still checkable; how many teams askhuman_decision_roles: ["underwriter"] admits no exceptionworkarounds around the gate; exceptions that never expireplatform
How to estimate economic benefit?output volume; cost per generated; cost per accepted unit; lead time and cost to an outcomeaccepted units; every attempt and reviewer hour; a measured baseline; a link to an outcomesix agents halve cost per generated (18.32 to 8.556) and raise cost per accepted (27.549 to 30.8), simulated, illustrativevolume rewards retries; leaving out reviewers hides the bottleneckmetrics

Read down the "Choose by" column and one question repeats in different words: what is the least machinery that produces this artifact reliably, and what evidence would justify more?

Where the analogy with WatchAlgo fails#

WatchAlgo is the case that made the factory idea concrete on this site: one folder per problem, a file-locked queue, short command-line workers, acceptance written in code that ignores the workers' own reports, checkpoint commits. It is tempting to read the enterprise chapters as "WatchAlgo, scaled up". The table says where that reading breaks.

DimensionWatchAlgo algorithm factoryEnterprise delivery factoryWhat carries over
Unit independenceindependent units, one folder each; no unit reads anothershared state: one codebase, shared schemas, databases, merge conflictsthe work list rebuilt from durable state; parallel only on disjoint write sets
Users and permissionsthe line has no external users, change approval or production data (docs/EVIDENCE.md section 11)authorization on every route; an agent is a principal with a roledeny by default, enforced outside any instructions
Correctnessoften oracle-checkable: run the reference code on the test inputsbusiness acceptance: "is this submission complete" has no cheap oraclethe producer never writes the check that accepts it
Regulationno regulatorcompliance: data handling, retention, audit records, model use in decisionsevidence kept per artifact, readable without the team
Operationsno on-call; a missing facet renders as "Coming Soon"an owner on call, incidents, rollback, postmortemsdefects classified, fixed in the pattern
Integrationno external systems in the linelegacy systems, providers and event consumers, each with an owner and a release cyclecontracts at boundaries, tested on both sides
Requirementswell-known problems, fixed before the line startsuncertain requirements, an unknowns register, people to negotiate withunknowns become questions, never guesses
Human reviewno human review record (author: "no manual review")approvals routed by risk tier, recordedsampled, recorded review where code cannot judge
Publicationfiles in a folder, a static site; the deploy record is unknowngoverned deployment: signed provenance, canary, promotion, rollbackpublish only what passed every station, from a recorded commit
Cost of a defecta wrong expected output on a learning page (86 found later in one category)a wrong outcome for a customer, regulated data exposedescapes counted and costed
The limiting resourcean account's usage limitpeople, approvals and other teams' calendarsWIP limits set by the slowest shared resource

Read the right-hand column and the lesson is not small: the working core (durable queue, stateless workers, independent acceptance, checkpoints, classified failures) is reusable. Read the middle column and the lesson is plainer still. A single algorithm factory pattern does not constitute an enterprise SDLC. It supplies one tested way to manufacture independent, checkable units. Requirements negotiation, shared codebases, authorization, compliance review, change approval, staged rollout, incident response and the many people around them are the rest of the delivery process, and the blueprint above exists to hold them.

What a factory does not promise#

No page on this site promises that enterprise software can be built in days, and the blueprint is where that promise would be easiest to make. A factory shortens the build: Example C's four stations are code that a reader reruns on one machine. For the insurer's intake service, the build is not what decides the go-live date. Five things dominate the critical path, as demand classification laid out: integration with systems other teams own, regulation of personal data and decision support, legacy behavior nobody wrote down, security approvals on the security team's schedule, and requirements nobody has decided yet (the scenario's submission has 63 fields; the example carries 11 plus one).

What a factory can honestly do is make each of them visible early: a generated contract gives the security reviewer something precise, an unknowns register surfaces questions on day one, and stop rules say what evidence the organization is waiting for. It cannot make another team's approval arrive sooner.

What this is not. This page designs the factory that builds many products. One change's path through review, CI and production is Diff to Deploy; the controls around one coding agent's run are Harness Engineering; the control plane that schedules agents in general is Agent Orchestration Engineering; graders and golden sets the factory invokes as gates are Eval Engineering; planning one change before the first meeting is Ask to Release.
In a coding agent. In this blueprint a coding agent such as Claude Code or Codex, running headless, is a worker inside a workcell at one semantic station: it receives one work item from the planner and a scoped checkout, writes code, and exits. The verification component, not the agent's summary, decides whether its artifact advances, and a person with merge rights reviews. Its instructions file belongs to the pattern registry entry and is versioned with the templates.

The architecture review checklist#

A review asks the same questions of every factory design. The left column is the question; the right is the record that answers it. The review script above automates five of them.

ComponentThe question the reviewer asksThe record that answers it
Demand intakeIs the risk tier set from harm, reversibility and regulation, and signed by a person?signed demand, tier, unknowns register with owners
Pattern registryIs the pattern version approved, owned, and dated for deprecation?registry entry
Spec compilerDoes it refuse an unfilled extension point and a decision route opened to an agent?the two refusal tests
PlannerDo tasks that may run in parallel have disjoint write sets?graph levels plus write sets
WorkcellIs every credential scoped to one target and one run, with network and command allowlists and budgets?credential records per run
Artifacts and stateCan a resume prove no duplicate write and no lost progress?run record and a crash-resume test
VerificationDid anyone who produced the artifact write a check that accepts it?gate ownership list
ReleaseIs the same digest promoted, and has the rollback run in a rehearsal?rollout manifest, rehearsal record
OperationsWho is on call, and where do defect classes go?rota, defect records, pattern versions
GovernanceWhich changes need which person, and do exceptions expire?versioned policy, exception log

Pattern (ADR, read 2026-11-20): each accepted or rejected review outcome can be kept as an architecture decision record: one decision with its context, the decision, its status and its consequences, kept in the repository and superseded rather than deleted when a later decision changes it. A factory's review history is then a decision log the next reviewer can read.

Operational checklists#

The architecture review happens once per design. Operations happen every day, and four moments deserve a checklist.

MomentCheck
Before a runspec passed S1; pattern version approved; workcell credential issued for this run only; budget charged to a tenant
During a runqueue time and attempts per station visible; failures classified before any retry; a station that keeps failing escalates, it does not loop
After a failurerun marked incomplete, never succeeded; defect recorded with class, station and cause; a recurring class opens a pattern change
Every weekopen exceptions and their expiry; cost per accepted unit and first-pass yield per product; workers and schedules inventoried with an owner
Operational checklists, in depthThe detail behind each row, with the chapter that owns it

Before a run. The spec compiler's verdict is attached to the run record, so a run without one cannot start. The pattern version is read from the registry, never from the spec alone. The workcell credential is issued when the run starts and expires when it ends; a credential that outlives its run is a finding. The run's budget (attempts, time, cost units) is charged to the tenant's quota (Scaling safely).

During a run. Queue time per station shows the bottleneck before it shows as lateness (Factory quality engineering). A failure is classified as content, limit, infrastructure or unknown before any retry; an unknown failure stops and asks. WatchAlgo's retry storm is the reason: one unrecognized limit message turned a pause into 11,503 failed tasks (The WatchAlgo story). Bounded retries end in escalation to a named person, as Example D's FR-0007 does after three invariant_violation attempts.

After a failure. The run status says incomplete and names the blocked stations. The defect record carries a class from the taxonomy, the station, the pattern version and the rework cause (Factory learning loop). A recurring class becomes a pattern change with a blast radius and a selective suite, approved by the pattern's owner. A postmortem whose output is only a note has not finished.

Every week. Exceptions are reviewed before they expire and counted per rule (Enterprise governance). Yield and cost per accepted unit are compared per product on a fixed mix. Every scheduled or automated worker is on an inventory with an owner and a retirement date; the WatchAlgo evidence records a cron job still running a watchdog that would start generation sessions if its binary reappeared.

Try it#

The wizard opens on the blueprint preset: the insurer's broker document intake. Change the choices to see which stations, gates, approvals and questions a different product earns. It plans; it never deploys.

The same information for a reader without JavaScript (from docs/LABS.md, examples/labcore/b_wizard.py, synthetic rules; the blueprint row also re-run on a scratch copy on 2026-11-20):

PresetChoicesPatternStationsGatesHuman approvalsOpen questions
defaultCRUD portal, internal staff, internal data, own database, low risk, container platformPAT-CRUD-PORTAL 1.2.0 (this lab's own)7: S1-validate-spec, S2-generate-data-model, S3-generate-api, S4-generate-ui, S5-run-tests, S-generate-migrations, S6-write-manifest6: unit tests, contract check, migration dry run, security scan, human approval, promote2: spec owner before any agent starts; a person with merge rights before merge2
blueprintdocument intake / RAG agent, outside partners, regulated personal data, REST APIs + event stream + document store + model provider, high risk, container platformPAT-INTAKE-API 2.1.0 (Example C)7: S1-validate-spec, S2-generate-contracts, S3-assemble-service, S-build-retrieval-index, S-generate-event-schemas, S-run-golden-case-evals, S4-write-manifest9: unit tests, contract check, event schema compatibility, security scan, PII masking check, evals on golden cases, human approval, canary with automatic rollback, promote7, including a release approver, a security reviewer, the domain owner, a compliance reviewer, and at run time a person deciding every case7

Then open the economics lab on the pilot preset and move one slider at a time: yield, then agents, then reviewers.

The same information without JavaScript (from docs/LABS.md, examples/sim/economics.py, illustrative cost units, one 8-hour shift; simulated, illustrative):

PresetAgents · reviewersFirst-pass yieldAccepted per hourBottleneckReview queue at end · average waitCost per acceptedCost per generated
pilot1 · 1 (yield 0.6)0.61.8generation0 · 0 h46.33327.8
default2 · 10.6653.99generation0 · 0 h27.54918.32
more-agents6 · 10.5255.0review35.6 · 3.56 h30.88.556
more-reviewers6 · 30.5259.45generation0 · 0 h32.76217.2
shared-files-22 · 1, conflict 0.15 per extra agent0.5953.57generation0 · 0 h29.84917.76
shared-files6 · 1, conflict 0.15 per extra agent0.1753.15generation0 · 0 h44.197.733

No model takes part in either lab, and the agent in every example is a scripted stand-in, so these results show how the factory mechanics work, not how good any model is.

WatchAlgo in practice#

Read against the maturity table, WatchAlgo's September line is a strong level 2 for its own kind of product and does not attempt level 3, which is a fair design for a solo content site.

Observed in the repository (docs/EVIDENCE.md rows 7, 11 and 12, scripts/viz/pipeline.py, commit 971863f2): acceptance is deterministic code that ignores the workers' own reports (verify_solution, verify_viz); the queue lives on disk under a file lock and can be rebuilt from the files, so disk is the source of truth; retries stop at three. Observed (scripts/viz/supervise.sh, commit 017ed6b9): the supervisor restarts the driver and commits a checkpoint every 30 minutes. Those are level 2 entry criteria met in a real factory.

Observed (docs/EVIDENCE.md rows 15 and 17, section 5): there is no human review record, the workers ran with permissions skipped rather than scoped, and the deploy record is unknown; the live site is consistent with a command-line deploy of a working tree, which is an inference. Teaching reconstruction: in blueprint terms there is no workcell boundary, no governance component and no release component with provenance, so level 3 was never in scope. Reported by the author: 3,246 problems with descriptions, solutions and visualizations in three flavors, produced by a repeatable process over 30+ hours; The WatchAlgo story holds the reconciliation (3,246 problems; 2,380 units complete on the machine).

Enterprise translation#

At the insurer, the blueprint becomes a short list of commitments that the architecture board can approve one at a time. The platform team owns six components (registry, spec compiler, planner, workcell, artifacts and state, and the factory's own operations); the submissions team owns its demand, its spec, its rules and its on-call; the security reviewer and compliance own governance and the release approvals the policy routes to them. Nothing is built that the existing delivery platform already provides: the factory plugs into the catalog, the artifact registry and the CI system as one more user (Platform foundations).

What dominates the first months is not the factory's code. It is the security review of the factory's own identity, agreement on which changes count as high-risk, the baseline measurement of the last hand-built intake services, and the rollback rehearsal. This site's recommendation: put those four on the rollout plan as named items with owners on the first day, because they are the items a pilot report will otherwise blame for being "late".

Failure test#

The failure: a well-meaning change to the blueprint lets the planner run S3-assemble-service alongside S2-generate-contracts to save time, and both write openapi.json. On most runs the timing hides it. On some, the service is assembled from a contract that is overwritten a moment later, and the gate report, written against the final file, is green.

How the factory catches it: at design time, not at run time. The architecture review compares the write sets of every pair of tasks the graph allows in parallel and reports the overlap (the planner finding above). At run time, the artifacts-and-state component would catch the symptom only indirectly: two attempts recording different digests for one file.

What to run or toggle: save the review script from this page next to its blueprint data and run it; then remove S2-generate-contracts from S3's dependencies and add openapi.json to S3's write set, and run it again. In the wizard, switch the risk tier from high to low and count which approvals disappear; then check the result against the architecture review checklist above.

Where to go deeper#

The capstone exercise#

Design a factory for a second product, then review it. Open the wizard and describe a product the insurer also needs: an adapter in front of the legacy policy administration system that publishes policy changes as events, used by internal staff, holding confidential data, medium risk, on premises. Write down its stations, gates, approvals and open questions. Then check your design against the architecture review checklist and the operational checklists on this page, and write one finding the wizard did not raise.

A worked answerWhat the wizard plans, and three findings the checklist adds

The wizard's planner, run on a scratch copy of examples/labcore/ on 2026-11-20 with those choices (synthetic rules; the pattern id is the lab's own):

== capstone: legacy policy adapter
pattern: PAT-LEGACY-ADAPTER 1.0.0 (synthetic)
stations: S1-validate-spec, S2-record-legacy-behavior, S3-generate-adapter, S4-run-replay-tests, S-generate-event-schemas, S5-write-manifest
gates: unit tests, event schema compatibility, security scan, PII masking check, human approval, canary with automatic rollback, promote
  approval before any agent starts: the spec owner signs the spec
  approval before merge: a person with merge rights reviews the change
  approval before promotion: a release approver signs off
  approval before promotion: operations schedules the change window
  unknown: Who owns this product after it ships?
  unknown: What does done mean, as acceptance criteria a test can check?
  unknown: Which fields are personal or confidential, and who may see them unmasked?
  unknown: Which legacy behaviors must stay exactly the same?
  unknown: Who consumes each event, and how long must old event versions stay readable?
  unknown: Which signal triggers a rollback, and at what threshold?

Three findings the checklist adds. Verification: there is no contract check gate, yet the adapter has consumers on the event side; the replay tests prove the adapter matches the legacy system, not that consumers can read what it publishes. Release: a canary on premises over a system of record needs a rehearsed rollback that does not leave two systems disagreeing; the rollback record is the hardest evidence here. Demand intake: the legacy system's owner must own S2-record-legacy-behavior, because only they can say which recorded behaviors are bugs. And the anti-claim applies in full: the critical path is the recording of legacy behavior and the agreement of every event consumer, not generation. This product is a good second wave and a bad pilot, for exactly the reasons in the pilot table.

Exercises#

  1. A team reports that its factory is "at level 3" because every artifact carries signed provenance. What do you ask for?
Answer 1The verification record, and a rollback rehearsal

Level 3 is admitted by provenance verified at deployment against the reviewer's expectations, an automatic rollback seen in a rehearsal, and approvals on the record. Signing without verification is level 2 with paperwork.

  1. The board wants the pilot to be the underwriting decision for small risks, "because that is where the savings are". Your answer?
Answer 2Never a pilot, at any level

A product in which an agent approves, declines, binds or quotes fails the fourth pilot question outright, and this site's rules keep every insurance decision with an authorized underwriter. Pilot the intake service, which builds evidence without moving a decision.

  1. After a pattern fix, the pilot's yield rises from 0.6 to 0.7. What does the economics model say should come next, and what should not?
Answer 3More generation capacity, watching review; not a second reviewer

Cost per accepted falls to 40.857 at 2.1 accepted per hour; generation is still the bottleneck, so a second agent pays (30.807 at 3.42 per hour), while a second reviewer raises cost to 79.667. Simulated, illustrative.

Advanced perspective#

The factory is a product, with users, an owner and service levelsWho is on call when the factory itself breaks

The ten components describe the factory's architecture; they do not say who answers when it fails at night. Treat the factory as a product whose users are domain teams. It needs its own catalog entry, its own owner, its own service levels (for example: share of runs that end succeeded or incomplete with a correct record, never a silent success; time from a filed defect class to a released pattern version) and its own on-call rota, separate from the products it builds. Without that, a broken spec compiler becomes every domain team's problem and nobody's job.

One useful distinction from outside writing: Article (Kief Morris on martinfowler.com, read 2026-11-20): when output is bad, a person working in the loop fixes the artifact, while a person working on the loop fixes the harness that produced it. In blueprint terms, operations that only repair products are working in the loop; operations whose defect records end in pattern versions are working on it, and only the second raises a maturity level.

Why levels cannot be skipped, and when they can be held unevenlyGovernance without verification is ceremony; verification without a record is luck

Each level's evidence is built from the one below. Provenance (level 3) signs a gate report; if the gates are written by the producer (missing level 2), the signature certifies a self-report. Learning (level 4) compares batches; without a durable record of attempts and defect classes (level 2), there is nothing to compare. A factory that buys a signing service before its gates are independent has bought ceremony.

Levels can, and usually should, be held unevenly across product kinds. The insurer can run intake services at level 3 while its first event workers sit at level 1, because they use a different pattern with different gates. What must never be uneven is the boundary: a level 1 product kind must not share workcell credentials, quotas or a registry entry with a level 3 kind, or the weaker one sets the real level of both.

Who may change the blueprintThe design itself is a governed artifact with a version

A blueprint changes: a new component appears (a retrieval-index station for document intake, an eval gate), an owner moves, a level's entry criteria tighten. Each change has a blast radius across every product kind the factory serves, the same way a pattern change does. So the blueprint deserves what this site gives every shared artifact: a version, an owner (the platform team, with the architect reviewing), a review by the roles it affects, and a record of the decision. The review script's rules are part of it, versioned with it, and changed through review like code.

The one change that needs more than review is lowering a gate for a risk tier. That is a policy change routed to the security reviewer and the domain owner, with the evidence that justifies it in front of them, never a convenience edit made to unblock a run.

In one breath#

An enterprise software factory is ten components, each with an owner and a record: demand intake, a pattern registry and a spec compiler decide what to build; a planner, workcells and immutable artifacts with a run record build it; verification and release prove and ship it; operations and governance close the loop and say who decides. It earns autonomy one maturity level at a time, per product kind, starting from a pilot chosen to produce evidence, such as the insurer's intake service, and a rollout whose phases end in records and stop rules, never dates. The working core WatchAlgo demonstrated carries over; the users, permissions, regulators, integrations and people it never had are what the rest of the blueprint is for.

The factory now builds a service, proves it with gates the producer did not write, and promotes a verified digest under a policy that names its approvers. What it hands over at the end of a run is one change to one product. The path of that change through review, CI, canary and production, seen from the change's side, is the subject of the next site in the series: Diff to Deploy.