Skip to the content
Software Made Clear
About

Factory · 19 nodes

Running a software factory

A pipeline of narrow agents carrying a change from a request to a deployed result, with a person on every decision that matters — mechanism before plumbing.

Is this path right for me?

ASSUMES

That you have watched a coding agent produce something plausible and wrong, and had to explain it to someone afterwards.

GIVES YOU

A vocabulary for arguing about where automation stops, and the numbers to argue with.

LEADS TO

Distributed basics — a factory is a distributed system whose workers happen to be language models. Follow that path to understand the systems beneath the pipeline.

Nothing is tracked and nothing is locked — the map exists so you can see where an article sits.

Suggested start Written Not written yet Optional or subtopic

  1. NODE 01 · REQUIRED Suggested start

    What a software factory is

    See why a pipeline of coding agents is two loops rather than a conveyor belt, what the return arrow does, and which published numbers do not transfer.

    • Two loops
    • Narrow agents

  2. NODE 02 · REQUIRED Written

    Hand-offs through artifacts

    See why agents in a pipeline never call each other, what the orchestrator is actually for, and which system holds the state when a run dies halfway.

    • No hidden chat
    • Durable state

  3. NODE 03 · REQUIRED Written

    The harness

    See what the shared instruction files actually do, why they need a precedence order, and why the harness regresses far more often than the model does.

    • Rule precedence
    • Versioned instructions

  4. NODE 04 · REQUIRED Written

    From vague request to ready ticket

    See why the arrow that sends a request back is the one that decides whether a factory works, what a context pack holds, and what must never be rewritten.

    • Definition of Ready
    • Clarification loop

  5. NODE 05 · REQUIRED Written

    The builder, and its repair loop

    See why the agent that writes the code is the least interesting one in a factory, what its repair loop must be capped at, and what it may never touch.

    • Claim atomically
    • Three attempts, then a person

  6. NODE 06 · REQUIRED Written

    When an agent stops and asks

    See what an agent must record when it blocks, who the question should go to, and why the resume path — not the question — is the half teams forget to build.

    • Structured question
    • Resume with context

  7. NODE 07 · REQUIRED Written

    The PR review agent

    See why the unit of review is not the commits an author pushed, what the build already owns, and why letting the reviewer push fixes costs you its independence.

    • Effective diff
    • Escalation categories

  8. NODE 08 · REQUIRED Written

    The human merge gate

    See why a person approving every merge is a design property rather than a trust issue, how attention scales with risk, and how the gate really fails.

    • Risk tiers
    • Rubber-stamping

  9. NODE 09 · REQUIRED Written

    Prompt injection in a pipeline

    See why hidden instructions in a ticket or a log line are an architecture problem, how removing one capability per agent closes it, and what is left over.

    • Lethal trifecta
    • Untrusted text

  10. NODE 10 · REQUIRED Written

    Scoped credentials and the kill switch

    See why a permission matrix belongs to the workflow, not the system, why the interesting cells are the empty ones, and why one off switch is not a kill switch.

    • Permission matrix
    • Four levels of stop

  11. NODE 11 · REQUIRED Written

    Golden sets: testing the factory

    See why a change to shared agent instructions needs a regression gate, what belongs in the replay set, and why a per-attempt success rate flatters a pipeline.

    • Replay
    • Compounding reliability

  12. NODE 12 · REQUIRED Written

    Deterministic steps and AI steps

    See which parts of an automated run belong in a script, which genuinely need judgement, and why an instruction file can only ask where a hook can refuse.

    • Hooks, not prompts
    • Where judgement earns its cost

  13. NODE 13 · REQUIRED Written

    Ephemeral environments and seed data

    See why a git clone is not a runnable system, why every agent run needs a throwaway database of its own, and why the seed data must be synthetic.

    • Throwaway database
    • Synthetic records

  14. NODE 14 · OPTIONAL Written

    Orchestrator, or just a pipeline?

    See why a first agent workflow runs fine on the build system you already have, and the specific signals that say a durable engine has earned its place.

    • Durable workflow
    • When it earns its place

  15. NODE 15 · REQUIRED Written

    Verifying after the deploy

    See why a green build is not evidence a change works, how to wait for the deployed revision instead of the clock, and where post-deploy checks turn dangerous.

    • Revision match
    • What replay may touch

  16. NODE 16 · REQUIRED Written

    Incidents back into the backlog

    See how fingerprinting turns ten thousand production errors into one prioritised defect, and why the polling cursor and the release decide whether it works.

    • Fingerprinting
    • One ticket, not hundreds

  17. NODE 17 · REQUIRED Written

    What a merged change costs

    See why the price per token predicts almost nothing about an agent bill, what actually drives it, and which levers cut it — in order of how much they save.

    • Cost per merged change
    • Model routing

  18. NODE 18 · OPTIONAL Written

    Measuring a factory honestly

    See why a baseline collected before you start is the only thing that makes a target testable, and which of your metrics improve fastest by being gamed.

    • Baseline first
    • Metrics that flatter

  19. NODE 19 · REQUIRED Written

    Who owns the factory

    See which jobs a software factory quietly creates, why each one needs a named person rather than a team, and which unclaimed roles fail first in an incident.

    • Named roles
    • Who can stop it