scafld. 0state

scafld is built to get better code from the model. You work with a plan you can read, question and change. The CLI carries that plan through execution with explicit phase dependencies, acceptance checks and recorded results.

Before implementation, adversarial hardening questions the plan’s right to exist. Does the proposed work solve the underlying problem? Could a smaller change solve it? Does the behaviour belong in an existing layer? Rejecting or reframing the plan is a valid result.

The agent then uses its normal editing and testing tools. A separate review examines the implementation, challenges its assumptions and looks for failures the author missed. Completion requires recorded acceptance evidence and an accepted review. The agent saying “done” does not move the task through that gate.

The native Go CLI keeps the plan, execution history and review available across sessions. A different agent can pick up the work with the failed checks and unresolved findings still in view.

Use it where a local fix can break the system

A persistence change has to work with existing data. A shared interface has more callers than the one open in the editor. Moving an execution boundary can change who has authority to act.

Those changes justify writing down the contract and testing its failure cases. A copy edit or CSS adjustment can use normal editing and focused checks.

Install

# native Go install
go install github.com/nilstate/scafld/v2/cmd/scafld@latest

# native binary via npm wrapper
npm install -g scafld

# native binary via pipx wrapper
pipx install scafld

# direct download
curl -fsSL https://0state.com/scafld/install | sh

The Go binary is the product. The npm and PyPI packages are distribution shims that fetch the matching native binary from GitHub releases. Go package documentation is indexed at pkg.go.dev.

Human-readable plans

The plan is Markdown. You should be able to read it and understand what will change, why it is needed, where the behaviour belongs and how the result will be checked.

The agent inspects the repository before proposing that change. The plan names the existing contracts, the constraints that must hold and the evidence needed for acceptance. It leaves room for implementation judgment without leaving the objective open to reinterpretation.

Hardening challenges the proposal before human approval admits the scope. The approved plan and session then give the next agent, or a human, the same recorded state, next allowed step and review gate.

A spec declares:

Task definition - objectives, scope boundaries (in/out), assumptions, size, risk level
Context - packages affected, files impacted, architectural invariants that must be preserved
Touchpoints - every system, module, or adapter the change will touch
Risks - what could go wrong, impact level, mitigation plan
Phases - ordered execution steps, each with file-level change declarations and acceptance criteria
Rollback - the per-phase rollback or repair plan, including state that cannot simply be undone
Definition of done - explicit checklist items that get checked off during execution

Planning mode

Planning is a structured exploration cycle that the agent runs conversationally with the developer:

THOUGHT - interpret the request in repo terms, identify unknowns
ACTION - search the codebase, read files, check diffs to answer those unknowns
OBSERVATION - capture what was learned: files, invariants, risks, dependencies
THOUGHT - update the spec, ask clarifying questions when information is missing
REPEAT until all required fields are filled and assumptions are explicit

The agent is in read-only mode during planning. It can explore anything but change nothing outside .scafld/specs/. If planning gets blocked on missing information, the spec saves with planning notes and the agent tells you exactly what it needs.

The planning loop records the reasoning another session needs to continue. Unresolved assumptions stay visible instead of becoming instructions that only make sense to the agent that wrote them.

Deterministic execution

draft --harden / validate--> approved --build evidence--> active
                              |                           |
                         scope approval                review
                                                          |
                                          blockers -> fix + review
                                                          |
                                               passing review
                                                          |
                                                       finalize
                                                          |
                                               receipt + archive
                                                          |
                                             CI verifies target

The filesystem is the state machine. Specs physically move between directories as they progress:

.scafld/specs/
  drafts/          planning in progress
  approved/        approved and ready to execute
  active/          execution or review in progress
  archive/YYYY-MM/ completed, failed, or cancelled

Each transition is enforced by the CLI. You can’t skip the approval gate. You can’t execute a draft.

Work is organised into phases with dependencies and explicit acceptance criteria. The agent uses its normal tools to implement and test the change. scafld evaluates declared criteria, records attempts and enforces the rules for advancing the task.

The execution state follows those rules and recorded results. The model still chooses how to implement the change; it cannot turn a failed criterion into a pass by describing the work as complete. Failed checks remain visible for repair or rollback under the task’s plan.

The spec’s status is rebuilt from the session ledger. Rollback or repair remains an implementation responsibility; scafld does not automatically undo arbitrary repository or external changes.

Completion needs evidence

The session ledger is the durable evidence layer. Every meaningful event during a build appends a typed entry to .scafld/runs/<task>/session.json: criterion attempts, phase transitions, provider invocations, review verdicts, override decisions. The Markdown spec re-renders from the session; the session is never read from the spec.

This inversion matters. When the agent says “phase 2 passed,” the spec says nothing until the session has a corresponding criterion_attempt entry with the recorded exit code and evidence. The agent’s account can be checked against what was recorded in the ledger.

Resume from the failed check

If a migration failed against an existing database, the next session needs that command, result and failure context. “Nearly done” does not tell it whether to repair the migration or write another test against an empty database.

scafld status <task> --json and scafld handoff <task> expose the contract, recorded attempts and next allowed step. The next agent can work from the failed edge instead of reconstructing it from the previous agent’s summary.

Challenge the plan’s right to exist

scafld harden <task-id> treats the draft as a proposal to challenge. It goes back to the repository and the underlying problem before accepting the proposed design.

The hardening contract requires consideration of four outcomes:

Reject — the work is unnecessary, or existing behaviour already solves the problem.
Shrink — the goal is sound, but a smaller change will do it.
Reframe — the goal is sound, but the architecture or owner is wrong.
Keep — the proposed approach survives those challenges.

A plan to add separate retry state to three adapters may be perfectly readable and testable. Hardening should still ask whether retry state already belongs to a shared execution layer. If it does, the plan needs to change before anyone implements the three copies.

After the design and scope, hardening checks paths, commands, acceptance timing and the rollback or repair plan. Findings must point to a spec gap, verified code or archived precedent. Each round is tied to the draft revision; a changed design needs fresh evidence.

Required edits and decisions to reject, shrink or reframe keep the round in needs_revision. The operator can revise the plan or record a reason for overriding a finding. A reviewer’s suggestion can also be wrong; it must stand up to the same repository evidence.

Validation

Not all changes deserve the same level of verification. scafld scales validation proportionate to risk:

Light (micro/small, low risk) - compile check + acceptance criteria only
Standard (medium risk) - add targeted tests per phase, full test suite + linter + typecheck + security scan before commit
Strict (high risk) - everything in standard, plus boundary checks per phase to catch cross-module side effects

These profiles guide the agent’s choice of checks. Runtime acceptance comes from the explicit criteria in the specification and the recorded review; selecting a profile does not silently add every check in this list.

Scope discipline

Scope is part of the deterministic contract. The spec declares the files, packages, boundaries, and invariants the agent is allowed to touch. Build evidence records what actually ran. Review challenges whether the diff stayed inside the approved shape.

That makes scope drift visible at the gate that matters: the task cannot complete just because the implementation agent says it stayed on course. The next accepted state must be derivable from the spec, the session, and a passing adversarial review.

Adversarial review

A shared API changes. The agent updates the caller it was looking at, writes a test for that caller and reports success. Another consumer is still using the old contract.

scafld review examines the implementation against the task contract and repository evidence, and records the reviewer’s provenance. Following the plan and passing the author’s tests still leave design assumptions, affected callers and failure cases to challenge. The review examines the diff through three lenses:

Regression hunt - for each modified file, check all callers and importers. What breaks?
Convention violations - read the project’s documented rules. What did you violate?
Defect scan - hardcoded values, off-by-one errors, missing boundary checks, race conditions, copy-paste bugs, unhandled error paths.

Every finding cites a file and line number. Findings are blocking (must fix) or non-blocking (should fix). The review produces a verdict.

The review provider runs in a sandboxed read-only environment with a workspace mutation guard; if the provider tries to modify files mid-review, the result is discarded and the review fails closed. The structured-output schema is enforced at the provider boundary so packets must be well-formed before they reach the gate.

After a passing review, scafld finalize consumes the accepted evidence, runs deterministic acceptance checks, signs an Ed25519 receipt, and archives the specification. It does not call a model or repeat the provider review. scafld verify <receipt> --target <commit-ish> checks the receipt against the target revision in CI.

The receipt distinguishes cross-vendor review from isolation-only review. Both remain local tooling unless another operator or CI trust domain verifies the evidence. The signature identifies the signer and protects the record’s integrity; it is not proof that the implementation has no defects.

Guardrails

Projects supply their own acceptance criteria, approval requirements, and architectural invariants. Those can cover public API compatibility, database changes, dependency boundaries, or deployment requirements. Build evidence records the checks that ran; review considers whether the implementation satisfies the task beyond those checks.

The criteria need to match the risk of the change. A passing receipt only establishes acceptance against the recorded contract and evidence. CI enforcement is what makes receipt verification a condition of merging.

The reasoning behind this workflow is in Before You Let the Agent Build It: what a plan needs to establish before an agent earns permission to execute it.

Workspace support

For projects with multiple codebases; an API, a frontend, an SDK, an MCP server; the workspace pattern gives the agent visibility across all of them from a single root. Create a root repo, add your codebases as git submodules, run scafld init. The root holds the orchestration layer and the agent sees the whole picture.

scafld init                  Scaffold workspace (extract bundled core, create directories)
scafld plan <task>           Create a spec (scaffold in drafts/)
scafld harden <task>         Challenge the draft with grounded observations
scafld validate <task>       Check spec against the contract
scafld approve <task>        Approve scope (drafts/ -> approved/)
scafld build <task>          Open phases and record acceptance evidence
scafld exec <task>           Run a specific criterion or phase
scafld review <task>         Obtain and record independent review evidence
scafld finalize <task>       Check acceptance, consume review, sign receipt, archive spec
scafld verify <receipt>      Re-check a signed receipt in CI (tree, acceptance, signature, coverage)
scafld review <task> --human-reviewed --reason "manual audit"
                              Exceptional audited override when the review gate is blocked
scafld complete <task>       Legacy: read review, record verdict, archive (superseded by finalize)
scafld fail <task>           Archive as failed
scafld cancel <task>         Archive as cancelled
scafld status <task>         Review spec details and progress
scafld list [filter]         List specs by state
scafld report                Aggregate stats across all specs
scafld handoff <task>        Render compact context for the next model voice
scafld update                Refresh managed core files from the embedded bundle

scafld report aggregates task state, pass rates, size/risk distributions, and monthly activity across your spec history. Completed specs archive to .scafld/specs/archive/ with the session ledger and diagnostics that produced the final state. When something breaks in production six months from now, you trace back to the deterministic contract that approved it and the evidence that moved it through the gate.