The change loop

Audience: project users. This guide explains what to review and decide; the agent handles routine system operations.

Change Loop’s workflow is five commands, one of them optional:

Investigate? → Change → Build → Prove → Land

Recommended reading order

New here? See One change, start to finish for the picture. For a first change, read the Quickstart and run the single-repository path before opening the reference pages below. Configure foundation.json only when the project needs a different model, reviewer, setup command, or policy.

If one test or change needs several repositories, read the multi-repository workflow next. Understand it before assigning parallel workers or wiring cross-repository evidence. Read the Evidence section when defining claims/providers or diagnosing stale receipts; users do not need protocol details to operate the loop.

Why this shape

An earlier design encoded quality as a long sequence of agent roles and phases — PM, lead, engineer, QA, retro. That preserved quality, but the orchestration itself came to dominate cost and latency. Every handoff meant re-establishing context that a previous persona already had.

The current shape separates three concerns instead:

• OpenSpec stores the agreement.
• The native coding agent implements the agreement.
• Deterministic providers prove the agreement.

Nothing in that split needs a persona relay, so there isn’t one.

It is not a waterfall

The arrows describe what must be true before what, not a one-way schedule. Change, Build, and Prove move backward freely:

Change ⇄ Build ⇄ Prove

When requirements shift, you revise the same change rather than opening a new one. Change Loop syncs the sandbox and invalidates any proof the revision made stale. Only Land is a boundary you cross once, deliberately.

How every gate converges

The command stays the same; the harness handles the loop behind it. At each gate it collects all independent findings once and groups them into one ordered repair plan. The agent applies safe in-contract repairs; the harness reruns only checks whose inputs changed. It continues while the work makes progress—there is no fixed product-repair limit.

Before Land, the loop stops only for a decision that is yours: approving the spec, product meaning or a trade-off, an acceptance verdict or waiver, exhausted review, Land, a commit, push, or other external side effect, budget, or a cause only you can clear (a login, the network, a full disk). Everything else goes to its owner: setup, sync conflicts, and repeated repair return to the agent or the harness with a changed strategy, and a resource another change holds is a harness wait. Land is the single hard gate: it lands only a passing proof of the current workspace. State is preserved and every stop carries its choices and an exact resume route. Repeating an unchanged wait does not poll or spend another model request.

The slash commands call one model-facing coordinator. /build, /prove, and /land use advance <change> --through build|proven|archived; /dev composes the same targets. The coordinator returns exactly one of WORKING, EDIT, RUN_EXTERNAL, REPAIR, WAIT, ASK_USER, or DONE, with an exact resume route whenever it stops. Primitive commands remain under help --all for operators and host integrations.

The steps

Step	Command	What it owns
00	/investigate	Read-only exploration. Optional — use only when direction is genuinely unclear
01	/change	The agreement: intent, delta specs, tasks, claims, risk, evidence contract
02	/build	Implementation, inside an isolated worktree
03	/prove	Executable evidence, reusing valid receipts
04	/land	The explicit completion transaction

Two more commands sit outside the loop. /changes lists active work and the next useful action for each, mutating nothing. /dev is a compatibility composition of Change → Build → Prove. It includes Land only when the invocation already carries explicit Land authority; success in that lane means archived.

Rigor comes from risk, not size

/change resolves a handful of properties and those decide how much process applies:

• impact — low, medium, or high
• coupling — isolated or coupled
• security triggers — matched as whole words against the intent, so access no longer fires on “accessibility” while “sign in with a passkey” does fire
• evidence capabilities — what would actually demonstrate the claims
• size — used for budget and slicing only

That last line is the important one. Size never downgrades quality. A one-line change across a trust boundary gets the treatment its risk deserves.

Where state lives

Durable intent belongs in OpenSpec; machine state belongs in .foundation/. Nothing important lives in the conversation, which is what lets a fresh session resume from files.

openspec/changes/add-profile-auth/
├── proposal.md
├── tasks.md          # sole task ledger
├── evidence.yaml     # stable claims + capabilities
├── specs/             # standard lane
├── design.md          # conditional: decisions/diagrams/integrations/prototype
├── grounding.yaml     # conditional: material decisions
├── execution.yaml     # conditional: custom provider + service wiring
├── repositories.yaml  # conditional: explicit multi-repository scope
└── handoffs.yaml       # conditional: permission-bound operations

.foundation/
├── runtime/          # lifecycle + resolver
├── receipts/         # content-bound evidence
├── authority/        # review + acceptance requests
├── transactions/     # recoverable Land journals
├── logs/             # provider output + events
├── recovery/         # abandoned change records
└── sandboxes/        # isolated worktrees

Runtime records under .foundation/ are machine-maintained and ignored by Git; drafts and declared sandbox code have agent write routes. Project agreements in openspec/ are yours to review, while openspec/schemas/ is installed product. See files and ownership before editing or cleaning up files. The compiled OpenSpec packet is the source of truth. The semantic input draft and coordinator actions are compiler/runtime inputs, not parallel requirement ledgers.