Topic: The software factory — a general architecture for the execution layer

This page is a curated overlay, not an ontology node. It gathers pages from across the wiki around one theme and links out to them; it stores no edges and changes no synthesis. See CONVENTIONS §The topic layer.

The question this topic answers: what is the general architecture of a software factory — which components make one up, which design decisions define one, and in what order are those decisions typically taken on? Where the runtime index compares the documented instances — sandcastle, warren, bernstein, sssf, gh-aw — concern by concern, this page describes the system they are all instances of: the anatomy every factory shares, four axes that locate any factory in the design space, and named profiles marking the configurations worth building toward. It also carries the layer’s glossary, including the canonical definition of control plane.

The term, generalized

“Software factory” arrives in the wiki as one tool’s proper name — sssf is the Super Simple Software Factory — but its author defines it generically, and the definition describes the whole layer rather than his instance of it:

“A software factory does one thing: it gives you more leverage on your prompt. How much leverage depends entirely on what you invest in it. At the low end you chain two agents together and hope. At the high end you build a system of agents plus code that runs without you.”

This page adopts that generic sense: a software factory is a system — code, service, or both — that turns units of intent (a ticket, a goal, a queue) into verified, merged changes by spawning coding-agent loops it does not itself contain, bounding what they may do, and checking what they claim. Every member of the runtime layer is a software factory or a kit for building one; the term names the assembled system, where runtime names the wiki’s node type for the substrate. The independent “loop engineering” frame (captured here) draws the same boundary from the other side: “Prompt, context, and harness engineering make one agent run better. Loop Engineering makes agent work repeatable, observable, and governable over time.”

Where the factory sits — the four layers

The wiki’s ontology places the factory precisely: it is the execution layer, one of three compute layers above the state layer.

flowchart TB
    P["<b>Process layer</b><br/>framework · capability · sdlc-stage<br/><i>what the agent does</i>"]
    H["<b>Harness layer</b><br/>Claude Code · pi · opencode · droid<br/><i>the agent loop itself</i>"]
    R["<b>Execution layer — the factory</b><br/>sandcastle · warren · bernstein · sssf · gh-aw<br/><i>where, when, and how loops run</i>"]
    S[("<b>State layer</b><br/>beads · seeds<br/><i>what survives the run</i>")]
    PAT["<b>one technique, four expressions</b><br/>worked example: deterministic gates"]
    P -- "runs_on" --> H
    R -- "runs (spawns)" --> H
    S -- "integrates_with" --> H
    P -- "a review skill runs the checks" --> PAT
    H -- "a hook blocks the tool call" --> PAT
    R -- "a required gate blocks the merge" --> PAT
    S -- "a gate issue blocks the work queue" --> PAT

The bottom half of the diagram is the layers’ one meeting point. The same technique recurs at every layer in a different material, and the factory’s version is always the enforced one: taking pattern-deterministic-gates as the worked example, a capability like gstack-qa runs the checks because a skill tells it to, claude-code’s hooks can block the offending tool call, bernstein’s required gate pipeline hard-blocks the merge, and a beads-gate bead blocks the ready frontier until the check clears. The wiki stores this as four backlink rosters on each pattern page — Applied by (capabilities), Provided by (harnesses), Enabled by (runtimes), Persisted by (stores) — and the same four-way split holds for pattern-worktree-isolation, pattern-autonomous-loop, and the rest of the factory’s pattern roster.

Two boundary tests from CONVENTIONS keep the layers apart. Against the harness: a harness is the loop; a runtime spawns loops. Against the store: a runtime spawns loops; a store is read by them — beads and seeds coordinate agents but launch none, so they sit below and beside the factory, which consumes them.

Anatomy of a factory

Strip the five documented runtimes to what they share and one machine remains. Every part below is optional in some member — sssf ships no isolation, sandcastle no memory, warren no real parallelism, gh-aw no mid-run steering — but the sockets are always these:

flowchart LR
    TRIG["<b>Trigger</b><br/>manual · schedule<br/>event · goal"] --> CP
    CP["<b>Control plane</b><br/>sequencing · retries · acceptance<br/><i>a script, a DAG, or a service</i>"]
    CP -- "dispatch<br/>(context in)" --> W
    subgraph ISO["Isolation substrate — inline · worktree · sandbox · remote fleet"]
        W["<b>Worker</b><br/>harness + model"]
    end
    W -- "claims<br/>(envelope out)" --> GATE["<b>Gates</b><br/>tests · lint · schema<br/>review · evidence"]
    GATE -- "fail → correction" --> W
    GATE -- "pass" --> OUT["branch → PR → merge"]
    STORE[("<b>Store</b><br/>work queue · memory · trace")]
    CP <--> STORE
    HUMAN["<b>Human</b>"] -. "steering / approval" .-> CP
    GATE -. "escalation" .-> HUMAN

Reading the diagram against the wiki: the trigger and the control plane’s next-action policy are pattern-autonomous-loop territory; the isolation box is pattern-worktree-isolation; running several workers at once inside it is pattern-wave-parallelism; the envelope crossing the seam is pattern-contract-first and its injection pattern-context-engineering; the gates are pattern-deterministic-gates refusing to accept the agent’s own report as evidence, sometimes strengthened by pattern-cross-model-review and pattern-fresh-context-subagents; the store’s memory half is pattern-knowledge-compounding; and a worker resuming across runs is pattern-session-handoff. The one empirical claim the five members unanimously support is about the gate: verification is the only concern every documented runtime implements — something between the agent’s report and the merge is always checked by code (what is checked varies: gh-aw’s gate vets the safety of outputs and leaves work quality to the PR’s own CI). That, more than any component, is what makes a factory a factory rather than a loop of hope.

The four axes

The layer’s 11-concern comparison matrix answers fine-grained questions; for designing a factory, four coarser, independently-movable decisions do most of the work. The option values for the trigger and intake axes are adopted from the loop-engineering taxonomy.

1. Control-plane location — who owns sequencing, retries, and acceptance: the prompt (the agent decides what happens next) or code (a script, DAG, or service decides, and the agent is a bounded step inside it). This is the layer’s sharpest idea — sssf states it as “moving the control plane out of the prompt and into Python”, bernstein as zero LLM tokens in the coordination loop.
2. Trigger model — what authorizes a run: manual bootstrap (a human command starting a repeatable contract), scheduled (a cadence), event-triggered (a webhook, failed check, label), or goal-driven (run until a verifiable goal is met).
3. Isolation substrate — where the worker acts: inline in the working checkout, a worktree/branch, a local sandbox (container, bwrap, microVM), or a remote fleet (pods, e2b/modal/daytona-style backends).
4. Autonomy scope — how work arrives: one bounded task handed in, a queue consumed (issues, PRs, tickets), or discovery (scanning for work, or reacting to failure signals).

These are axes, not a ladder — each moves independently. You can run a single bounded ticket on a remote fleet, or a fully code-owned control plane inline in your checkout with no isolation at all (that is exactly sssf). The levels intuition (“first one ticket to done, then loops and triggers, then sandboxes local and remote”) is real, but it describes a common path through the grid below, not an ordering the axes impose.

The morphological grid

Rows are the axes; cells are the option values, roughly lighter to heavier left to right. The markers place the four profiles — the recommended progressive configurations, each anchored to a documented runtime as evidence: 🎫 ticket runner (sssf), 🖥️ monitored service (warren), 🏭 fleet factory (bernstein), 📡 repo reactor (gh-aw). A fifth marker, 🧩 skill-pack factory (builder-skills), added 2026-09-26, places the one factory in the wiki that is built from instructions rather than a runtime.

Axis
Control-plane location	in the prompt — the agent sequences itself 🧩	in a script you own 🎫	in a deployed service 🖥️	in a deterministic DAG — scheduled 🏭 or compiled into CI 📡
Trigger model	manual bootstrap 🎫 🖥️ 🧩	scheduled 🖥️ 📡 🧩	event-triggered 🖥️ 📡	goal-driven (run to quiescence) 🏭
Isolation substrate	inline checkout 🎫	worktree / branch 🏭 🧩	local sandbox 🖥️	remote runners / fleet 🏭 📡
Autonomy scope	one bounded task 🎫	queue intake 🖥️ 🧩	scan discovery 🏭 📡	reactive (failure-signal) 📡 🧩

• 🎫 Ticket runner — one unit of intent runs unattended to a gated finish. Control plane in a script, human-triggered, everything else optional. sssf is the documented anchor: a stamped ADW chain, gates over a typed envelope, and — by admission — no sandbox, no parallelism, no PR flow. The cheapest configuration that is still a factory rather than a supervised session.

• 🖥️ Monitored service — continuous intake with a human watching. A deployed control plane dispatches sandboxed runs from a queue or cron, the human steers mid-run and merges the PRs. warren is the anchor: dispatch → bwrap/pod sandbox → steer → validate → auto-PR → reap, with .mulch/ memory compounding across runs.

• 🏭 Fleet factory — a goal becomes a task DAG scheduled by code across parallel isolated workers, with gates deciding what lands. bernstein is the anchor: pure-Python scheduling to quiescence, worktrees plus seven remote backends, janitor and review gates, never auto-merging past them.

• 📡 Repo reactor — the factory as standing repository automation: the repo’s own event stream (an opened issue, a failed check, a deploy error, a schedule) triggers a read-only agent whose writes pass through gated, pre-approved channels. gh-aw is the anchor: markdown workflows compiled into hardened Actions lock files, safe outputs behind a threat-detection verdict, budgets declared as data. Unlike the other three it is not a heavier stop on one path — it automates a different kind of work (the announcement’s “continuous” triage, documentation, hygiene) and typically runs alongside whichever profile does feature work.

• 🧩 Skill-pack factory (added 2026-09-26; anchored by a framework, not a runtime) — the whole factory is written as instructions, and the harness supplies everything else: scheduler, connectors, worktrees, and credentials. The control plane is the agent itself, following a per-action policy document. The Factory in builder-skills is the anchor. See the section below.

One honest caveat on the grid: sandcastle deliberately appears in no profile — it is the embeddable option, the SDK you would build any of these configurations from, so its position is a distribution fact, not a shape.

The progression 🎫 → 🖥️ → 🏭 is the adoption path the anchors themselves suggest — add triggers and sandboxes to a working ticket runner, add code-owned coordination and parallelism to a working service — and it agrees with the loop-engineering maturity rule of earning autonomy in order: “Persist state before increasing unattended runtime, establish external verification before adding more agents, and add production controls before actions can affect users or infrastructure.” The 📡 profile sits beside that path rather than on it, adoptable at any point. And because the axes are independent, skipping or reordering is legitimate whenever one axis’s need arrives early; the profiles are waypoints, not gates.

A factory with no runtime: the skill-pack pole

Added 2026-09-26. Every factory above was anchored by a member of the execution layer, and the grid’s first control-plane column, in the prompt, had no documented instance. The column was there only as the thing sssf defines itself against. The Factory in builder-skills fills it, deliberately: nine skills that turn feedback, telemetry, errors, and PR queues into gated changes, and that ship no code at all.

“Factory skills install agent instructions. They do not add integrations, credentials, scheduled jobs, or permission grants.”

It is filed as a framework, not a runtime, because it spawns nothing (see the layer call). Checked against the anatomy, though, every socket is filled, and the interesting part is what fills each one:

• Trigger — the host’s own scheduler. builder-factory creates one job per enabled workflow and then reads it back, because “a YAML schedule is only a request.”
• Control plane — the agent, reading .agent-factory/config.yaml (artifact-autonomy-policy). That file is “an agent-readable convention, not a validated schema.” Sequencing and retries are prompt-owned. Acceptance is policy-owned, set per action.
• Isolation — a fresh-per-run worktree requested from the host, with “keep the workflow manual rather than borrowing a shared checkout” when the host cannot provide one.
• Gates — head-bound check and review evidence with a soak that restarts on any change, and a split between merge and deploy (“a merge is not live proof”).
• Store — nothing of its own. State lives in the source systems (the issue, the Slack thread, the PR) and is re-read on every run, which is why coverage honesty (unavailable ≠ truncated ≠ empty) runs through every module.
• Human — a first-class queue rather than an interrupt: builder-factory-human-digest, read-only, grouped by underlying pattern.

What it contributes to the design space is an axis the grid did not have: how authority is decomposed. The four runtime profiles each have one coarse autonomy dial. The skill-pack pole has ten, one each for fix, reply, close, review, approve, publish, merge, deploy, recover, and notify, with the rule that “the skills never infer permission for one action from another.” The wiki now records this as pattern-action-gating. gh-aw’s safe outputs reach the same decomposition from the runtime side, compiled into the CI job graph where the agent cannot break it. The two together define the axis. At one end, prose policy the agent is trusted to obey, portable to any harness and adoptable today. At the other, structural channels the agent cannot bypass, bound to one platform.

The honest cost is the one sssf was built to avoid. When the control plane lives in the prompt, every safety property depends on the model following the instructions. The Factory’s response is to be conservative everywhere the prompt could slip: defaults off, “missing or unclear policy means hold”, read back every write. It does not claim the guarantees a code-owned plane gives. It suits a team that wants the factory’s shape before committing to a runtime. Following the adoption path above, it is a plausible first step before 🎫 or 🖥️, and it can keep running as the policy layer afterwards.

Relation to the other maturity frames

The wiki now holds three level-shaped frames, and they measure different things — this page’s profiles should not be read as a fourth rung set. topic-agent-readiness scores the repository and organization the agent works in (two external rubrics, five levels, payoff at L3–L4); its subject is the substrate’s fitness, and a fleet factory pointed at a Level-2 repo just produces broken PRs faster. The loop-engineering maturity model (levels 0–6, manual prompting → production-supervised) scores one recurring workflow’s operating controls — durable state, verification, budgets, supervision — and explicitly warns that “levels describe capability, not ambition.” This page’s profiles describe the execution shape of the whole factory — where the control plane, triggers, isolation, and intake sit. The three compose rather than compete: readiness says whether the repo can support a factory, the profile says what shape of factory, and the loop maturity model says how governed each of its recurring workflows is. topic-harness-engineering sits underneath all three, governing the single run the factory repeats.

Glossary

The execution layer’s working vocabulary. Definitions link to the pages that ground them; this list defines, it does not re-argue.

• software factory — a system of agents plus code that turns units of intent into verified, merged changes by spawning bounded agent loops and gating their claims; the generic sense of sssf’s proper name, adopted by this page for the assembled systems the runtime layer’s members build or are.
• control plane — the component that owns sequencing, retries, and acceptance: which work runs next, what happens on failure, and what counts as done. Its defining question is location — in the prompt (the agent decides) or in code (a script, DAG, or service decides). warren is a self-hostable control-plane service; bernstein’s is a deterministic DAG scheduler; sssf’s is a stamped Python script, and its pitch — “moving the control plane out of the prompt and into Python” — is the term’s sharpest use in the wiki; gh-aw shows the plane need not be a running process at all — its policy is compiled into the CI job topology before anything executes.
• execution layer — the wiki’s name for the layer these systems form; the node type is runtime, kept despite the word’s overloading (language/container/model runtimes are unrelated). See CONVENTIONS §The execution layer for why it was not named orchestrator.
• framework / harness / runtime — the three compute layers, disambiguated: a framework ships methodology (skills and commands that perform lifecycle stages); a harness is the agent loop that executes them (Claude Code, pi); a runtime spawns and wraps harnesses. The boundary tests: a harness is the loop, a runtime spawns loops; a framework performs stages, the other two perform none.
• gate — a code-enforced check between an agent’s claim and its acceptance: tests, lint, schema validation, or a review pass that can hard-block a merge. See pattern-deterministic-gates. A receipt-based gate additionally demands recorded evidence — commands, logs, trace IDs, PR links — rather than assertions; pattern-evidence-before-claims is the wiki’s form of that rule.
• envelope — a typed, schema-validated document that crosses the seam between control plane and agent (and between agents), replacing conversation as the interface; re-prompted until it validates. sssf’s Pydantic envelopes are the documented instance; the general move is pattern-contract-first.
• ADW (AI Developer Workflow) — sssf’s term for the generic concept of a workflow script: the code file that is the control plane for one factory run, owning phase order, retries, and the acceptance decision.
• safe outputs — gh-aw’s term for structurally gated writes: the agent runs with no write permission and emits typed requests (create-issue, add-comment, create-pull-request, …) that separate jobs with minimal scoped tokens apply, only after a threat-detection verdict. The structural-prevention shape of pattern-edit-guardrails.
• loop contract — the loop-engineering frame’s reviewable specification for one recurring agent job: eleven decisions (objective, trigger, intake, workspace, context, delegation, verification, state, budget, escalation, exit) that would otherwise be hidden defaults. An externalized control-plane policy in document form.
• trigger — what authorizes a run: manual bootstrap, schedule, event, or a verifiable goal. The factory’s front door; axis 2 above.
• intake — where work comes from once running is authorized: consumed from a queue, found by a scan, or provoked by a reactive failure signal. Distinct from the trigger: a nightly schedule (trigger) may scan for drift (intake).
• isolation / sandbox / worktree — the boundary around a worker’s writes: a git worktree or branch, an OS/container sandbox, or a remote machine; substituting for or supplementing trust in the agent. See pattern-worktree-isolation; sssf’s post-hoc rollback (pattern-edit-guardrails) is the detect-and-revert alternative when no boundary exists.
• steering (HITL) — human-in-the-loop influence on a running factory: warren’s real-time mid-run steer, bernstein’s gate-shaped approvals, or nothing mid-run at all (sssf, where the human is the first phase and the exit code).
• AFK autonomy — unattended operation to a completion signal: the run continues without a human present, bounded by budgets and ended by gates. See pattern-autonomous-loop.
• exit condition — what proves a loop succeeded, and what stops it without success; the loop-engineering contract’s final part, and the two-question form in sssf — all phases green and accepted= — shows completion and acceptance are separable.
• budget — the cap on one run’s autonomy: iterations, retries, tokens, cost, wall-clock, concurrency. Every documented runtime bounds at least one of these; bernstein adds a cost kill-switch and circuit breaker.
• escalation — the designed path from the factory to a named human when gates fail repeatedly, judgment is required, or budgets exhaust: a PR, an issue, an approval card, a queue of human-needed items (beads’ bd human).
• maker/checker — the separation rule that the acting agent never decides its own work is done: a different gate, model, or session verifies. The wiki’s enforced instances are pattern-cross-model-review and pattern-fresh-context-subagents.

See Also

• runtime/index.md — the layer’s navigational index: members, the pattern roster, and the 11-concern orchestration matrix this page’s axes distill.
• topic-agent-readiness — the substrate’s maturity; what has to be true of the repo before any profile here pays off.
• topic-harness-engineering — the controls around the single run the factory repeats; the factory is that steering loop moved out of the room.
• sssf · warren · bernstein · gh-aw — the four profile anchors; builder-skills — the 🧩 skill-pack pole, a framework rather than a runtime; sandcastle — the embeddable substrate beneath them.
• Further instances, documented as prose only: OpenHands SDK (open-source remote-fleet runtime, deprioritized as closer to the hosted IDE-agent systems), Conductor, Container-use, Sculptor, Vibe-Kanban (sunset); see the broader category.
• IndyDevDan, Super Simple Software Factory (capture) · ChaoYue, Awesome Loop Engineering (capture).