Retrieved article excerpt
Open article · Retrieved 2026-09-14T19:22:27.460354+00:00
# build2me
**Map the solution space before you build the software — so a swarm of agents can
work in parallel without coordinating, and without a human reviewing code.**
Work is split into contracts, each carrying the command that decides whether
it is satisfied. Agents pick contracts off a ranked frontier without claiming
them, a verifier is the only judge, finished parts compose by cascade — and
contracts keep evolving as understanding grows, version by version, with the
reopened downstream routed automatically.
[Protocol](https://github.com/shitianfang/build2me/blob/main/PROTOCOL.md) · [Stub semantics](https://github.com/shitianfang/build2me/blob/main/STUBS.md) · [Rendered DAG](https://github.com/shitianfang/build2me/blob/main/docs/DAG.md) · [Race 001](https://github.com/shitianfang/build2me/blob/main/races/001-deprecation-cascade.md) · [中文](https://github.com/shitianfang/build2me/blob/main/README.zh-CN.md)
[verify](https://github.com/shitianfang/build2me/actions/workflows/verify.yml)
**14 / 16 contracts Done · frontier empty · 2 statements revised live · built by a swarm under its own protocol**
```
node tools/init.mjs ../my-system --root my-system # scaffold your own project
```
---
## Why this exists
Point a swarm of agents at one codebase and the old ways break in two places:
1. **They collide on files.** Three agents editing the same module is a merge
disaster.
2. **They queue behind review.** A PR needs a human to read it, and that human
is the bottleneck — it does not matter how fast the agents are.
[Prove2Me](https://arxiv.org/abs/2608.28433) hit both of these first. Its
authors tried multi-agent co-editing (agents interfere) and a git PR workflow
(review stalls) before inventing anything, and answered by **moving trust from
review to immutable statements plus a checker**. In Lean that checker is free:
the compiler says it type-checks, and it is proved. On that footing a swarm of
Claude agents [formalized Fermat's Last Theorem in 11
days](https://www.anthropic.com/research/formalizing-fermats-last-theorem) —
30,300 theorems, with no human reviewing proofs during the run (Kevin Buzzard
reviewed the completed proof afterward).
build2me asks the obvious follow-up: **in software, what plays the part of the
compiler?**
The answer it commits to: **every unit of work carries its own acceptance
command.**
## Three objects
**1. Contract** — a statement of *what must be true*, silent about *how*. One
JSON file, and the `acceptance` command is the whole definition of done:
```
{
"name": "frontier-tool",
"title": "Frontier query (the scheduler)",
"interface": "CLI: node tools/frontier.mjs [--dir <project>] [--json]. Prints Open leaf contracts ranked by closability.",
"acceptance": "node --test acceptance/frontier-tool.test.mjs",
"nl_description": "Replaces task assignment. Any agent picks its next work item from this ranking; no locks, no claims.",
"serves": "root",
"env": "node>=20"
}
```
That one line settles it. There is no "close enough" and no "let me check with
someone" — the command exits 0 and the contract is Done, or it does not and the
contract is not.
**And contracts evolve — freely, at any time.** A title or description you
just edit in place. Changing what a contract *means* — interface, acceptance,
env — is one command:
```
node tools/revise.mjs search-index --set interface="..." --reason "positions are now required"
# -> contracts/search-index-v2.json is the live statement from here on
# -> everything downstream reopens automatically, and the frontier lists
# each reopened contract with the new version to re-point at
```
Revise as often as understanding grows (`-v2`, `-v3`, …); abandon a whole
direction with a deprecation and the region stays on the map as explored
territory. Under the hood every version is its own permanent file — like git,
where you edit freely yet every commit is immutable. That implementation
detail is what buys three things at swarm scale: an agent mid-build never has
the statement swapped under it, humans audit only new statements (never
re-read old ones for sneaked edits), and everything ever verified stays
verifiable against exactly what it was verified for.
**2. Submission** — an attempt at a contract, in `impl/<contract>/<id>/meta.json`.
Either an `implementation`, or a `decomposition` that reduces the contract to
children it `imports`. Those imports are the DAG's edges:
```
{ "contract": "calc", "kind": "decomposition", "imports": ["add", "mul"],
"files": ["src/calc.mjs"], "notes": "calc implemented against add and mul" }
```
**3. Law** — one enforced floor per quality dimension, `laws/<id>.json`:
```
{
"id": "l5-tool-size",
"dimension": "complexity",
"statement": "no kernel tool exceeds 400 lines; split it or amend this law deliberately",
"check": "node laws/checks/l5-tool-size.mjs"
}
```
The verifier runs every law's `check` on every pass and fails verification on
violation.
> *A law is only a law if something enforces it; prose without a check is
> advice.*
Laws are written when a problem bites, not in advance: measure today's level,
freeze it as the floor, and from then on that ground cannot be lost silently.
That is a **ratchet** — what went green may never quietly go red. Which
dimensions a project needs is discovered while building. `laws/laws.md` is the
human-readable index.
---
Everything else — statuses, verdicts, the work queue, completion — is
**derived** by the verifier. Nothing is stored, nothing is negotiated.
| term | meaning |
| --- | --- |
| `Open` / `Done` / `Deprecated` | a contract's derived status |
| `ACCEPTED` | the submission's imports are all Done and the contract's gate passed |
| `SKETCH_ACCEPTED` | a valid submission still waiting on Open children |
| `GATE_FAILED` | imports ready, gate ran, gate said no |
| **cascade** | when a sketch's last child closes, the *parent's* gate runs for real |
| **closability** | how many ancestors would auto-resolve if this leaf closed — the scheduler's only number |
## How it runs
The kernel is two tools:
- **`verify.mjs`** reads the project state, runs each contract's own acceptance
command, and derives every status by fixpoint.
- **`frontier.mjs`** prints the Open contracts ranked by closability. That
ranking is the work queue.
**The kernel decides admissibility, not quality.** A contract is Done exactly
when its gate passed. That is a binary, and binaries are blind to everything a
gate does not test. When several submissions pass the same gate, a second,
*optional* layer ranks them: blind pairwise review against a rubric written
before the solutions existed. Race 001 below is the receipt for why that layer
is in the diagram.
**Agents are interchangeable.** They read the frontier, do work, submit. So:
- nothing is reserved, so an agent never waits;
- a crashed agent blocks nobody;
- two agents on one contract is a **cost, never a conflict** — contracts are
immutable, so anything ever built against one stays valid and there is
nothing to arbitrate at merge time;
- the race rule is simply **first accepted wins**.
**The loop every agent runs:**
```
node tools/frontier.mjs # 1. pick an Open contract, prefer high closability
# 2. search existing contracts and submissions — reuse beats rebuilding
# 3. implement it, or decompose it into new child contracts
node tools/verify.mjs # 4. run the kernel locally until green
# 5. submit — branch + PR; CI runs this same kernel
```
```
flowchart TB
H["HUMANS<br/>audit top-level contracts · amend laws · arbitrate trade-offs"]
subgraph AG["AGENTS — any number, no coordination between them"]
direction LR
A1["agent"]
A2["agent"]
A3["agent"]
end
subgraph ST["PROJECT STATE — plain files under git"]
direction LR
C["contracts/<br/>immutable statements"]
I["impl/<br/>submissions"]
L["laws/<br/>axioms · deprecations"]
end
subgraph KE["KERNEL — the only judge of admissibility"]
direction LR
V["verify.mjs<br/>fixpoint status · runs gates"]
F["frontier.mjs<br/>closability ranking"]
end
S["SELECTION (optional)<br/>blind rubric ranking among accepted rivals"]
H -->|"publish audited statements"| ST
AG -->|"publish contracts · submit work"| ST
ST --> KE
KE -->|"verdicts · cascade"| ST
KE -->|"what to work on next"| AG
KE -->|"several ACCEPTED rivals"| S
S -->|"which one to keep"| ST
```
Loading
## What this is for
Three things matter when agents build something bigger than one session:
**1. A map of the solution space.** Which parts are solved — verified, and
nobody can quietly break them again. Which parts are still open. Which paths
were tried, failed, and why — kept, so the next agent doesn't pay for the same
dead end twice. The map is the repository itself: `contracts/` are the nodes,
verdicts mark the solved regions, failed submissions and deprecations mark the
explored dead ends, and `node tools/graph.mjs --format json` prints the whole
map — per-node attempt history, abandonment reasons, and each dimension's
floor — for any tool to render.
**2. Decomposition follows the task — it is never fixed up front.** At the
start you don't know what the right parts are, or which qualities will need
optimizing. So you split the task as you understand it today; when building
teaches you a better split, deprecate and re-split — history stays. Dimensions
are discovered the same way: a page that got slow, a module nobody can read, a
doc that lied.
**3. A foothold in every dimension, and ratchets everywhere.** "It works" is
one dimension; its foothold is the acceptance gate. Every other quality the
task turns out to need gets the same treatment the moment it bites. Progress
means closing open contracts and deliberately tightening floors. Never
backwards.
**The honest limit:** a task that fits inside one session's context is cheaper
done directly in that session. This pays off when the work outlives its
workers — sessions end; the map remains.
## Start your own project
Requires Node ≥ 20, git, and bash (for the immutability check). No npm
dependencies.
```
$ git clone https://github.com/shitianfang/build2me
$ cd build2me
$ node tools/init.mjs ../my-system --root my-system
build2me project created at /.../my-system
root contract: my-system (14 files written)
next:
1. edit contracts/my-system.json — say what the system must do
2. node tools/verify.mjs --dir ../my-system # green, root Open
3. node tools/frontier.mjs --dir ../my-system # your work queue
4. decompose: publish child contracts with gates, then submit a
decomposition on my-system that imports them (PROTOCOL.md)
```
You get the kernel, a root contract, a starter completion gate, `laws/`, a CI
workflow that runs the verifier and enforces immutability, and `PROTOCOL.md` for
the agents who will work there. Then: write what the system must do, publish
child contracts **each with its gate**, and submit a decomposition importing
them. From that point the frontier is your backlog.
To watch the mechanics first, this repo ships a miniature project — a sketched
parent (`calc`) over one Done child (`add`) and one Open child (`mul`):
```
$ node tools/verify.mjs --dir acceptance/fixtures/demo
add DONE
sub-001 implementation -> ACCEPTED
calc OPEN
dec-001 decomposition -> SKETCH_ACCEPTED
mul OPEN
1 done, 2 open, 0 deprecated
$ node tools/frontier.mjs --dir acceptance/fixtures/demo
closability contract
1 mul Multiplication
```
`mul` is the entire work queue, and `closability 1` says closing it also closes
`calc`. Implement `mul` and `calc`'s integration gate runs by cascade —
[acceptance/example-flow.test.mjs](https://github.com/shitianfang/