Software Factory Template

In short

• A project-agnostic scaffold that wraps AI coding agents in deterministic gates: shell hooks and CI checks that block, instead of prompts that ask.
• Extracted from a factory that built a real product. Nothing here is speculative tooling.
• Every gate is proven by a break/fix fixture — we've watched each one catch the defect it exists for.
• MIT licensed.

Quick start

# one shot — fetch, then set up the current repo:
cd your-project
curl -fsSL https://softwareaifactory.sh/install.sh | sh -s -- init --pack go

# polyglot? pass several — e.g. a Go backend with a TypeScript frontend:
curl -fsSL https://softwareaifactory.sh/install.sh | sh -s -- init --pack go,typescript

# later, from inside the repo — pull framework updates (a reviewable diff):
curl -fsSL https://softwareaifactory.sh/install.sh | sh -s -- upgrade

# installs and upgrades are pinned to the latest release; --ref takes any branch or tag:
curl -fsSL https://softwareaifactory.sh/install.sh | sh -s -- init --ref main
curl -fsSL https://softwareaifactory.sh/install.sh | sh -s -- upgrade --ref main

The installer only fetches: it clones the template into ~/.software-factory-template and stops. It runs nothing it downloaded. Prefer to inspect first?

curl -fsSLO https://softwareaifactory.sh/install.sh && less install.sh && sh install.sh

factory-init.sh detects your stack, writes factory.yaml, installs the hooks, then runs a break/fix self-test so you watch a gate fire before it declares success. Afterward, try pushing straight to main, or committing with the message fix: verified the thing. Both get blocked. That's the product.

Getting started

1. Read docs/CONCEPTS.md (~5 min) — why the gates exist.
2. Run factory-init in your repo to install the hooks and prove they fire.
3. Run ./factory doctor any time to see which gates are armed, inert, or stale — and watch every armed gate fire on its own break/fix proof.
   • ./factory report shows what the gates caught, enforced at 0 model tokens, plus one clearly-labeled cost estimate — no vanity "tokens saved" number.
   • ./factory metrics shows what the factory is doing to your repo: gates armed vs inert, what they blocked, rework, reverts, whether claims carry evidence. Mostly from git history, so it works the day you install. --json to export, --html for a page. Local only — nothing is transmitted.
4. Read docs/ADAPTING.md "Adopting incrementally" to arm gates one at a time.
5. Open docs/HOOKS.md when a gate blocks you and you want to know why.

The idea

A prompt that says "never edit test files" is a request an agent may or may not honor. A shell hook that exits 2 on the edit is a fact. Put the control in a hook, not in the prompt — that principle is due to Birgitte Böckeler (Thoughtworks), and this template applies it to commit discipline, push gates, role separation, and citation integrity.

The second idea is the Verification Contract: only claim what you've observed. Three claim levels (WROTE / RAN / OBSERVED), every check proven by watching it fail. See docs/CONCEPTS.md.

The third idea is that this is already a graph. The vocabulary everyone's chasing — prompt, loop, harness, graph — maps straight onto what's here: roles are the nodes, gates are the verified edges, the reviewer is the skeptic that never wrote the code, and models tier by role. You don't adopt a graph framework; the graph is the floor, and it runs the same on Claude Code, opencode, and Codex because the roles are canonical. The mapping is in docs/CONCEPTS.md.

What's inside

Pack maturity

Labels are evidence, not roadmap: battle-tested means a real project shipped under the pack, beta means at least one real repo adopted it, experimental means no proven adopter yet (the label tracks adoption, not completeness).

Frameworks ride on the language pack, not their own: React and Vue use the TypeScript pack (Biome auto-applies its react/vue rules), Spring Boot uses the Java pack (JUnit 5 + Testcontainers). factory-init detects them and points you at the right pack. Install several at once for polyglot repos — --pack go,typescript.

The Go runtime conversion spec governs a
staged migration with backward compatibility, recovery and safe cleanup. Go
reader, configuration-export and artifact-verification candidates are available
for development; no default runtime cutover or packaged conversion has shipped.

Cost & models

./factory budget plan --harness codex --session work --task issue-1 previews
limits without calling a model. The opt-in run command bounds factory-managed
invocations and records metadata for Codex, Claude Code, and OpenCode. Reports
distinguish reported tokens, client cost estimates, and unknown usage; they do
not claim a strict dollar cap. See budget controls.

For manual checks or explicitly bounded implement/check/review/repair, see
Loop engineering. factory loop plan makes no model calls.

Each role runs on a cost-appropriate model. The reviewer and spec-writer get a frontier model; the low-stakes roles — refactorer, wiki-maintainer, background tasks — get a cheaper one. Because opencode, Claude, and Codex have different native model namespaces, each carries its own per-tier defaults (verified current, overridable in factory.yaml):

It's a routing change only — no gate is relaxed, so the same hooks check the output whichever model produced it. That's what lets a cheaper model run safely on the low-stakes roles. The default (standard) profile runs two tiers — frontier and default; the opt-in economy profile adds the cheaper third. To reconfigure later, edit factory.yaml (change a model, or flip cost_profile) and run make sync-harnesses — one edit re-routes all three harnesses. See docs/COST_AND_TOKENS.md.

Documentation

• docs/CONCEPTS.md — why the rules exist, including the full Verification Contract
• docs/ADAPTING.md — adopting the factory in an existing project
• docs/COST_AND_TOKENS.md — the cost profile and per-harness model tiers
• docs/MODELS.md — choosing a model provider; blank means inherit, so no provider is assumed
• docs/REVIEW_LANE.md — the opt-in adversarial PR review: what it costs, and the privilege boundary
• docs/METRICS.md — what the factory is doing to your repo; local only, no exporters, no server
• docs/LOOPS.md — manual checks, bounded repair and checkpoint handoffs
• docs/FEATURE_ROADMAP.md — stable feature priorities and completion tracking
• docs/WORKFLOWS.md — workflow recipes (graph engineering) and the workflow-lint gate
• docs/HOOKS.md — every hook: when it fires, exit codes, what a failure looks like
• docs/PATTERNS.md — failure patterns we hit in practice, and the fixes
• docs/FACTORY_RULES.md — the operational rulebook agents read
• docs/GLOSSARY.md — terms defined
• specs/TEMPLATE.md — a spec template to copy
• eval/README.md — how the template evaluates agent quality

Contributing

Contributions are welcome. The template runs its own factory checks and
acceptance fixtures. Self-hosting explains local hook
activation, CI review and the boundaries between source templates and adopters.

• CONTRIBUTING.md — the workflow, the gates, and the break/fix fixture rule
• CODE_OF_CONDUCT.md — the standards we hold each other to
• SECURITY.md — reporting vulnerabilities privately

New to the codebase? Start with docs/GLOSSARY.md and
docs/CONCEPTS.md. Bug reports and feature requests have issue
templates; PRs have a checklist tied to the gates above.

License

MIT. See LICENSE.