AI Software FactoryThe Guide
Menu
Table of contents

The AI Software Factory Guide

Six parts, forty-four chapters, and a reference shelf. Read it front to back, or enter at the part that matches your question.

Start with chapter 1How to read this guide
The journey

Understand → Design → Build → Prove → Operate → Improve

Each part answers one question. The chapters inside it answer that question in order.

  1. IUnderstandWhat is an AI Software Factory, what are its parts, and what principles hold it together?
  2. IIDesignWhat records, decisions, authority, and economics must exist before any agent runs?
  3. IIIBuildHow do you assemble capabilities, runtime, harnesses, environments, AI layers, and workflows?
  4. IVProveHow do you know the factory's output is correct, safe, and releasable?
  5. VOperateHow do you run it as a production platform?
  6. VIImproveHow does it get better without authorizing itself?
—
Front matter

Before you start

  1. 0
    How to read this guideWhat this guide is, who it is for, its eight-stage value stream and six-area architecture, the six-part journey, and the conventions used in every chapter.
  2. 0
    What this guide coversA concise ownership map from the guide's eight-stage value stream and six architectural areas to the chapters that define each concept in full.
→
The primary reader model

Intent → Plan → Define Agent → Execute through Harness → Apply Skills → Evaluate → Improve → Deliver Software

Eight concise stage briefs: click any stage for its contract, decision owner, required evidence, common failure, and canonical chapter links.

8 stages
  1. S1
    Stage 1 · Builder IntentHow a request becomes a governed Mission Spec with an explicit outcome, constraints, context, acceptance criteria, and risk before planning begins.
  2. S2
    Stage 2 · PlanHow an approved Mission Spec becomes a versioned Plan, Quality Contract, governed work graph, and capability-routing decision before execution is authorized.
  3. S3
    Stage 3 · Define AgentHow released work is bound to exact, eligible capability versions and frozen in an execution manifest before a worker is admitted.
  4. S4
    Stage 4 · Execute through HarnessHow a frozen execution manifest becomes bounded, durable, recoverable work and an immutable Candidate under deterministic harness control.
  5. S5
    Stage 5 · Apply SkillsHow versioned organizational methods are bound before execution, applied inside the harness, measured, and matured into deterministic automation.
  6. S6
    Stage 6 · EvaluateHow an immutable Candidate becomes independent, criterion-linked, exact-current evidence and a Quality Gate decision.
  7. S7
    Stage 7 · ImproveHow attributed evaluation and outcome signals become tested, reversible Improvement Candidates for future factory versions through governed promotion.
  8. S8
    Stage 8 · Deliver SoftwareHow an eligible Candidate receives an explicit, risk-proportional decision and moves through merge, release, activation, and production verification.
I
Part I — Understand

What is an AI Software Factory, what are its parts, and what principles hold it together?

What an AI Software Factory is, what its parts are, and what principles of trust, evidence, and authority hold it together.

3 chapters
  1. 1
    Why software engineering is changingCode generation is becoming cheap while accountability stays expensive; an AI Software Factory is the operating model that converts governed intent into validated customer value, and this chapter explains why that model, not a faster editor, is the unit worth building.
  2. 2
    The factory in one viewThe guide's two orientation models — an eight-stage value stream from intent to delivered outcome and a six-area architecture that assigns system responsibility — with the records, decisions, evidence, and human authority that connect them.
  3. 3
    First principles: trust, evidence, and authorityAutonomy is a scoped, revocable grant of authority that is earned through independent evidence, bounded by risk, and always backed by a named human — never a property of the model.
II
Part II — Design

What records, decisions, authority, and economics must exist before any agent runs?

The operating model, authoritative records, specifications, governance, economics, and multi-repository decisions that must exist before any agent runs.

7 chapters
  1. 4
    The human–agent operating modelHow people, agents, and deterministic systems divide decisions, execution, oversight, and accountability — through explicit roles, decision rights, a governed lifecycle with durable handoffs, escalation that presents a decision rather than a transcript, and a paved road fast enough that builders of every kind choose it.
  2. 5
    Authoritative records: from company to releaseThe twelve records that carry intent, authority, causality, evidence, and acceptance through an AI Software Factory, the companion records (Constitution, Mission Spec, Quality Contract, Factory Version, manifest, Context Package, Candidate, Verification Subject) that pin down what the spine would otherwise carry loosely, the traceability chain that joins them, and how a factory keeps a lower-level fact from silently rewriting a higher-level decision.
  3. 6
    Intent and specification engineeringHow business intent becomes a governed, versioned, testable specification before any agent is given implementation authority — the five things to extract from intent, the Plan as an executable contract, the task graph, approval semantics — from the Business Understanding layer through Mission, Plan, and WorkOrder to the prototype-as-spec workflow.
  4. 7
    Governance, policy, and risk-proportional approvalHow organizational intent becomes bounded machine authority — versioned policy, authorization envelopes, risk bands and risk-tiered review, decision rights, separation of duties, human-in-the-loop done right, waivers as product data, trust ceilings, autonomy per action class, ten control families, and the emergency controls that revoke authority when a run turns unsafe.
  5. 8
    Economics, metrics, and human attentionHow to measure trusted customer value, factory performance, and human attention without mistaking activity for outcomes.
  6. 9
    Tokenomics and factory economicsHow architecture drives model and context spend, how execution budgets control it, and how to measure full factory cost and ROI.
  7. 10
    Multi-repository design and coordinated deliveryHow a factory discovers, scopes, changes, verifies, merges, releases, and rolls back work that spans several repositories without pretending that several commits are one atomic change.
III
Part III — Build

How do you assemble capabilities, runtime, harnesses, environments, AI layers, and workflows?

The Agent Factory, control and execution planes, durable execution, harnesses, environments, agent architecture, models, loops, the 12-layer stack, and autonomous workflows.

16 chapters
  1. 11
    The Agent FactoryHow reusable agents, tools, model profiles, configurations, and evaluation assets become versioned, resolvable, certified, and revocable capabilities.
  2. 12
    Skills as packagesHow to package, evaluate, publish, specialize, improve, and retire skills as governed reusable capabilities rather than loose prompt files.
  3. 13
    Control plane, orchestrator, and execution planeSeparate durable authority from failure-prone execution, connect them with an orchestrator that coordinates but never mints authority, and give every runtime component an explicit contract.
  4. 14
    Durable execution: tasks, attempts, leases, and recoveryKeep the Task stable, append immutable Attempts, own execution through leases and fencing, make every side effect idempotent, and recover by classification rather than blind retry.
  5. 15
    Coding harnesses and agent protocolsHow a factory adopts coding harnesses behind an owned execution contract and places MCP, ACP, AG-UI, and A2A at the boundaries they actually standardize.
  6. 16
    Harness engineeringHow to engineer reproducible agent sessions, inner, outer, and meta loops, lifecycle controls, event streams, adapters, and conformance evidence.
  7. 17
    Development environments, sandboxes, and computeHow to give every Attempt a reproducible place to work, contain what it can do there, decide where that place runs, and make sure it cannot publish its own result.
  8. 18
    Agent architecture: loop, MCP, tools, context, and memoryAn engineering agent is a governed runtime composition around a fallible model — an execution loop, a protocol boundary for capabilities, behavioral tool contracts, a context compiler, and a memory lifecycle — with authority held by the runtime, never by the model.
  9. 19
    Data, knowledge, and semantic engineeringHow data understanding, governed knowledge preparation, semantic contracts, ontology maturity, and context graphs make trustworthy retrieval possible.
  10. 20
    Context engineeringHow to compile the minimum sufficient, permission-aware, attributable Context Package for one decision and manage its full lifecycle.
  11. 21
    Models and capability selectionHow to describe and qualify models as exact, replaceable capability profiles rather than vendor identities or leaderboard positions.
  12. 22
    Routing and the escalation ladderHow policy routes each workload to the cheapest qualified capability, escalates on evidence, and preserves security and quality through fallback.
  13. 23
    Agent and loop engineeringHow to choose the least agentic mechanism, shape work as a graph, and coordinate specialized agents through explicit collaboration and verification contracts.
  14. 24
    Loop engineering patterns and defaultsHow production loops measure progress, classify attempts, bound retries and cost, detect oscillation, and stop or escalate honestly.
  15. 25
    The 12-layer production AI agent stackThe twelve engineering disciplines that turn a capable agent into a dependable production system, what each decides, how they hand work to each other, the six contracts every layer must publish, and the order in which to build them.
  16. 26
    Autonomous engineering workflowsHow to admit a repository the factory is allowed to change, define the first workflow (governed issue-to-pull-request delivery) and the eight workflow products that follow it, and give each workflow its own trigger, proof shape, authority, and autonomy.
IV
Part IV — Prove

How do you know the factory's output is correct, safe, and releasable?

Quality and evidence architecture, testing, evaluation, proof packages and certificates, progressive delivery, and security.

7 chapters
  1. 27
    Quality and evidence architectureHow the factory turns every completion claim into a traceable, challengeable, time-bound proof — and why that proof, not the agent's confidence, is what earns autonomy.
  2. 28
    Testing strategy for agentic changeHow to assemble a risk-based portfolio of test methods, select tests by change impact, keep test infrastructure trustworthy, and stop agents from grading their own homework.
  3. 29
    Evaluation engineeringHow representative tasks, governed datasets, calibrated graders, repeated trials, and uncertainty measure a complete agent configuration.
  4. 30
    Evals as factory assetsHow trace capture, replay, drift controls, evaluation windows, scorers, and promotion ladders turn evals into operated factory assets.
  5. 31
    Quality contracts, proof packages, and certificatesHow to compile intent, policy, and risk into an executable Quality Contract before an agent runs, bind every piece of evidence to an exact artifact, decide release eligibility deterministically, and issue a bounded, revocable certificate that means exactly what it says.
  6. 32
    CI/CD, progressive delivery, and production verificationHow a validated commit becomes an immutable artifact, moves through compatibility and migration controls, is exposed progressively, is verified against real traffic, and is rolled back or corrected when production disagrees with the evidence that released it.
  7. 33
    Security: identity, secrets, threats, and supply chainHow to give every factory action an authenticated principal, scoped authority, isolated execution, bounded data access, and immutable evidence; how to threat-model agents that read hostile content and act through tools; and how to prove what was built, by whom, from what.
V
Part V — Operate

How do you run it as a production platform?

The platform, observability and forensics, resilience and incidents, control surfaces and storage, and enterprise adoption.

5 chapters
  1. 34
    The factory as a platformHow to run the factory as an internal product — a portal and catalog that humans and agents share, golden paths with an escape hatch, and a scheduler that turns business priority, fairness, budgets, and cost attribution into explicit, observable policy.
  2. 35
    Observability, telemetry, and forensicsHow to see what the factory is doing without mistaking what it observed for what it decided — a correlation spine from intent to outcome, shared trace and span semantics for agent runtimes, four kinds of health, cost attribution that rolls up without double counting, and forensic bundles that survive an incident.
  3. 36
    Resilience, incidents, and the control towerHow to keep a factory that has authority over other systems safe when it fails — failure domains, RTO/RPO by capability, authority-preserving failover, SLOs and error budgets, FinOps, the control tower's observe-to-improve loop, drift detection, and an incident framework that finds which layer failed and proves recovery before closing.
  4. 37
    Control surfaces, event contracts, and storageHow operators see, direct, interrupt, and judge autonomous work through decision-oriented surfaces, and how the factory's triggers, events, workflow versions, and stores are contracted so that what the operator sees is true.
  5. 38
    Enterprise adoption and the infrastructure landscapeHow an organization measures factory maturity by evidence rather than enthusiasm, advances one corridor at a time, chooses what to buy, build, and host, and satisfies the enterprise controls that decide whether a factory can run at all.
VI
Part VI — Improve

How does it get better without authorizing itself?

Production feedback and the merge queue, governed learning, Mission Control as a living case study, mastering the factory, and where this is going.

6 chapters
  1. 39
    Production feedback, automated review, and the agentic merge queueHow untrusted user feedback becomes a verified reproduction, a governed issue, and a fix that an agent keeps mergeable without ever taking the merge decision away from a human.
  2. 40
    Governed learningHow failures, outcomes, and human corrections become deterministic signals and governed Improvement Candidates without mutating live behavior.
  3. 41
    Meta-loops and the closed-loop factoryHow a factory defined as code harvests corrections, evaluates its own proposed changes, and promotes them by action class without self-authorizing.
  4. 42
    Mission Control as a living case studyWhat Mission Control is and is not, the full record-by-record walkthrough of how a Mission moves through it, what the retained evidence proves at the pinned commits, why its architecture was decided the way it was, and where its honest limits sit today.
  5. 43
    Mastering the factory: explaining, defending, and building itA mastery program for the person who has to build an AI Software Factory and also explain it, defend it, and lead the organization around it — four fluency levels, five audiences, the objections, the leader's three axes, a twelve-month build, a 30/60/90 for standing one up inside an organization, and a weekly rhythm.
  6. 44
    Where this is goingThe forward-looking material — composable stacks and open interfaces, the harness wars, extensible software with agents writing the extensions, the research frontiers, and a five-year roadmap — labeled as predictions and open questions rather than requirements.
A–F
Appendices

Reference, not sequence

Glossary, Mission Control case studies, research canon, coverage and maturity, changelog, reviewer guide, and architecture communication.

Open the reference shelf →

Reference

Mission Control case studies

Research