Skip to content

Accountability infrastructure for autonomous engineering

DoneState documentation

Guides, concepts, complete references, security boundaries, and operating help.

Hosted liveSource

DoneState docs / Overview

Governed autonomous coding that stays reviewable

DoneState turns a bounded repository outcome into durable work, explicit consequence authority, reviewable GitHub changes, and a separate independent-verification step.

Hosted MCP 0.3.0CLI 0.2.0 published

Choose the interface that matches your job

DoneState has two public usage surfaces. They share the same core ideas but they are not interchangeable command syntaxes.

Remote

Hosted MCP

Connect a compatible remote HTTP MCP client to the owned Proof & State service. GitHub OAuth identifies you; your own OpenAI API key funds execution.

Local

Installable CLI

Run DoneState inside a repository from a terminal or coding agent with durable SQLite state, explicit authority, optional branch/PR publication, maintenance workflows, and v2 independent verification.

Hosted MCP endpoint
https://donestate.proofandstate.com/mcp
CLI install
npm install --global donestate

The five-part mental model

  1. 01

    Describe an outcome

    State what should become true in a repository and define observable acceptance criteria.
  2. 02

    Grant bounded authority

    DoneState receives only the consequence classes needed for the objective instead of treating access as unlimited permission.
  3. 03

    Execute durably

    Work advances through recorded states so interruption is a recovery problem, not an excuse to blindly repeat consequential actions.
  4. 04

    Publish for review

    When remote publication is authorised, DoneState prepares a branch or pull request. Final merge authority stays outside DoneState.
  5. 05

    Verify independently

    Execution success is not terminal proof. A trusted independent verifier such as OpsTruth must observe the sealed subject before a new hosted objective can reach VERIFIED.

What DoneState promises — and what it deliberately does not

DoneState does not merge its own pull requests.
DoneState does not silently expand repository access.
DoneState does not treat successful execution as independent proof.
A failing GitHub workflow is evidence, not automatic repair authority.
Private repository execution requires a selected GitHub App installation.
Secrets are connected outside MCP tool arguments and are not returned by status tools.
New hosted objectives use the complete v2 verifier response, not the legacy attestation-only path.

Documentation map

The docs are organised by job rather than by repository folder. Start with a working path, then move into concepts or reference only when you need deeper detail.

Start

Get started

Reach a first hosted or local result with prerequisites, setup, and expected outcomes.

Guides

Cookbook

Follow practical recipes for PR creation, maintenance, verification retry, recovery, and deletion.

Understand

Architecture

See the control plane, durable state, execution sandbox, GitHub, credential, and verifier boundaries.

Reference

MCP tool index

Search all 20 hosted tools by name, purpose, input, or effect class.

Reference

CLI command index

Look up every local command, syntax, flag, output expectation, and state behaviour.

Operate

Troubleshooting

Diagnose blocked, failed, or ambiguous runs without unsafe blind retries.

How deep the public docs go

DoneState documentation is intended to cover every public interface and behaviour a developer or operator needs: setup, tool and command syntax, objective design, maintenance policy, authority classes, run states, recovery, independent verification, integration boundaries, public architecture, security, data lifecycle, contracts, versions, limitations, and troubleshooting.

What stays private is operational secret material rather than useful product knowledge: live credentials, private keys, reviewer passwords, recovery tokens, customer secrets, and exploit-sensitive incident artefacts.