GitHub
Table of contents

The AI Software Factory Guide

New here? Start with the introduction. Already have a question? Choose a part below or search all forty-four chapters.

Start readingBrowse chaptersSearch all chapters →
Browse by part

Find the chapter you need.

Six parts take you from understanding the factory to operating and improving it. Choose one to jump to its chapters.

  1. Part IUnderstandWhat is an AI Software Factory, what are its parts, and what principles hold it together?3 chapters
  2. Part IIDesignWhat records, decisions, authority, and economics must exist before any agent runs?7 chapters
  3. Part IIIBuildHow do you assemble capabilities, runtime, harnesses, environments, AI layers, and workflows?16 chapters
  4. Part IVProveHow do you know the factory's output is correct, safe, and releasable?7 chapters
  5. Part VOperateHow do you run it as a production platform?5 chapters
  6. Part VIImproveHow does it get better without authorizing itself?6 chapters
Find a starting point for your work
I have to explain or fund this executiveI have to draw the boundaries architectI have to review a workflow before launch design reviewI have to build it builderI have to run it operatorI have to prepare for or manage an incident reliabilityI have to scale delivery across factories enterprise
—
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

Understand

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

3 chaptersAll parts ↑
  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

Design

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

7 chaptersAll parts ↑
  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

Build

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

16 chaptersAll parts ↑
  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 Harnesses, feedback 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 goal-directed worker composed from a model, Agent Loop, Agent Harness, capabilities, context, state, and evaluation profile, with enterprise authority held by the Control Plane.
  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

Prove

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

7 chaptersAll parts ↑
  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

Operate

How do you run it as a production platform?

5 chaptersAll parts ↑
  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

Improve

How does it get better without authorizing itself?

6 chaptersAll parts ↑
  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