/build

Audience: coding agents and integration operators. CLI commands and schemas below are system reference, not a user checklist. Users can follow Quickstart.

In plain words: Build is where the agent writes the code and tests the agreement calls for. You do nothing here unless the agent asks you a question that only you can answer. The work happens in a sandbox (an isolated copy), so your checkout is not touched. The harness prepares tools, tracks tasks, and recovers from setup problems itself. You get the finished work inside the sandbox, then Prove starts automatically. Build never delivers anything to your project; only /land does.

For agents and integrators

/build <change>

Build uses one model-facing command:

claude-foundation advance <change> --through proven

The coordinator validates the agreement, creates or synchronizes the isolated workspace, compiles task dependencies, accounts for active leases, and returns one protocol-v6 action. After doing that action, the agent calls the exact resume route. It never reconstructs a sandbox → packet → plan → dispatch chain. Proof starts in the same call only once Build is complete, so /build needs no separate Build DONE round trip; it stops at proven and never Lands. --through build still stops at Build when that is all you want.

The seven actions

Action	Meaning
WORKING	Harness work is still running (a proof or a Land transaction); wait for it instead of starting another
EDIT	Implement only the returned task(s), workspace, and allowed paths (each task’s own workspace; a submodule task names its repository sandbox); open the listed contextFiles, create newFiles; run each task’s checkCommand (its verify through claude-foundation exec)
REPAIR	Apply one complete dependency-ordered repair batch, then resume
RUN_EXTERNAL	Run the one configured boundary operation
WAIT	A resource another task or change holds, or an external owner, must finish; the harness resumes and state is preserved
ASK_USER	A decision only you can make: spec approval, product meaning, acceptance, waiver, exhausted review, Land, a side effect, budget, or a cause in your environment
DONE	The requested Build target is reached

Every non-done action names the cause, responsible actor, safe alternatives, preserved state, and exact resume command. Automatic recovery stays inside the agent’s current authority; the harness never turns a stale lease or repeated execution into a pass. Before Land, nothing stops the agent except a decision that is yours: setup failures, sync conflicts, and a shared resource another change holds go to the agent or the harness, never to you. A repair that returns unchanged three times goes back to its owner with a changed strategy and the output that kept repeating.

A single task, or a chain of tasks that must run one at a time, in one repository with no cross-repository claim or shared resource runs in the current session: EDIT hands all of them at once in dependency order. Implement them all and resume once: advance reruns each task’s verify, ticks every passing task in tasks.md, and returns only failures (verificationFailures) with their dependents. The agent never edits checkboxes.

Isolation and concurrency

Product writes are allowed only in the exact workspace and paths returned by EDIT. Shell mutation must anchor itself to that workspace; on Claude Code the phase guard pins the shell’s reported directory as that anchor when it is already inside the workspace. A worktree contains tracked files only. With no setup command, the harness runs the workspace lockfile’s pinned install itself (npm ci, or the pnpm, yarn, or bun frozen-lockfile install); sandbox.installDependencies: false opts out, and sandbox.setupCommand or a per-repository setup command replaces it. A failed install never blocks Build: the agent receives its command, directory, and log to finish it. When Build changes package.json or the lockfile, the harness reruns the setup before the next check. Linking or copying the checkout’s node_modules into the workspace is refused.

The phase hook and claude-foundation exec use the same containment policy. They reject absolute outside operands, later directory escapes, and writes through symlinks outside the workspace; exec derives the phase from runtime state and starts Build children in the canonical workspace; for a multi-repository change, exec <change> --repo <id> (or --task <id>) starts them in that repository’s sandbox. This is cooperative containment, so the host still owns process isolation for indirect effects.

Parallel mode returns only independent tasks and lease instructions. The host starts every successfully leased worker before waiting, observes the writes, and resumes the same advance command. When only one task is ready, the current session runs it under the harness’s lease instead of a worker. An edit outside every task’s paths does not stop Build: Prove records it, and a control-plane, CI, or secret path or a deletion is shown to you at Land. Primitive sandbox, packet, agents plan, and agents dispatch commands remain available under help --all for operator diagnostics and host integrations.

New behavior discovered during Build

Do not edit several OpenSpec ledgers by hand. Submit one semantic amendment:

claude-foundation change amend <change> <amendment.json> --consume-amendment

The compiler preserves completed tasks and manual sections, validates the new agreement transactionally, and returns to advance. updateTasks may extend claim coverage but cannot replace an existing outcome; add a new task when that contract changes. A completed task’s verify changes only with reopen: true (--reopen), which unticks it so it must pass again, and removeTasks withdraws an unfinished task no remaining task depends on. A wrong verify command on an unfinished task is corrected directly, keeping the approval: claude-foundation change amend <change> --task <task> --verify <command>. The task is accepted only when the new command passes in the workspace, and a command that always passes is refused. reviseRequirements and removeRequirements change or drop an existing requirement in the same amendment, so a changed decision never requires abandoning the change. Permission-bound cloud, secret, Terraform, deployment, or restart work becomes a typed external operation; Build never asks for credentials.

DONE at Build is not proof. /build continues into Prove automatically, because Prove has no external side effects, and stops at proven; it never Lands the change.