Skip to content

Accountability infrastructure for autonomous engineering

DoneState documentation

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

Hosted liveSource

DoneState docs / Get started

Reach a first useful result

Start with one reproducible repository problem. Connect, set the boundary, then review the result and its independent evidence.

Choose a first job you can judge

Use a public repository you can push to and one small problem: a reproducible regression, missing input validation, or an incorrect documented example. Supply the failing steps or test and say what correct behaviour looks like. Save broad rewrites, production migrations and changes requiring private data for a separately agreed scope.

Choose hosted MCP for remote execution from a compatible client. Choose the CLI below for repository-local files and terminal control. A maintenance repository selection is not required for a one-off public-repository objective.

Hosted MCP quickstart

The shortest currently proven path uses a compatible remote HTTP MCP client, GitHub OAuth, your own OpenAI API key, and a public GitHub repository where your authenticated identity can push.

Remote MCP endpoint
https://donestate.proofandstate.com/mcp
  1. 01

    Add the remote MCP endpoint

    Configure the endpoint in a compatible MCP client. Complete the OAuth flow with your GitHub identity when prompted.
  2. 02

    Check execution-credential state

    Ask the client to call get_openai_credential_status. DoneState reports connection metadata, never the secret.
  3. 03

    Connect your OpenAI execution credential

    Call create_openai_credential_setup, open the short-lived HTTPS setup URL, and enter the API key there. Do not paste it into the chat.
  4. 04

    Create one bounded objective

    State the exact repository and base branch, observable goal, acceptance tests, changed-file and duration limits, and only the authorities needed. Use pull_request publication. create_objective starts execution by default; set autoStart to false if you want to inspect the admitted objective before calling start_objective.
  5. 05

    Observe durable state

    Use get_objective with the returned run ID. Treat blocked or ambiguous states as evidence to investigate, not a reason to blindly repeat the run.
  6. 06

    Verify independently

    When the run reaches AWAITING_VERIFICATION, use the configured OpsTruth path or create a sealed handoff. Only a matching trusted verifier response can move a new hosted objective to VERIFIED.
Example natural-language objective
Fix [one reproducible regression] in [owner/repository] from [base branch].
Reproduction: [failing steps or test].
Acceptance criteria:
- [Observable correct behaviour].
- The relevant existing tests pass.
- Keep the public API stable; no unrelated files change.
Boundary: [agreed file limit and duration], pull_request publication; do not merge.
Before starting, show me the scope and confirm the verifier can inspect this repository. Use autoStart: false until I approve that objective.

Know when your first job is complete

Keep the returned run ID. Review the changed files and test evidence, then compare the result with your original problem. AWAITING_VERIFICATION means execution is sealed and independent proof is still pending. A matching trusted verifier response establishes VERIFIED; you still decide whether the result is useful and whether to merge it.

If setup or execution stops, inspect that same run before creating another. The first-attempt recovery guide distinguishes funding, access, safe failure, ambiguity and verification delays. Do not send API keys, callback URLs, setup tickets, prompts containing private data or raw provider logs in a public support report.

CLI quickstart

The CLI requires Node.js 22.5 or newer. The published npm package is version 0.2.0 and stores local durable state in .donestate/state unless you choose another state directory.

Install
npm install --global donestate
Create objective and policy starters
cd your-repository\ndonestate init
Shortest local path
donestate go "Add the missing validation and keep the existing public API stable"
  1. 01

    Inspect the generated contract

    For the explicit path, edit .donestate/objective.json and .donestate/policy.json before running them.
  2. 02

    Execute under policy

    Use donestate run --objective ... --policy ... when you want the full objective/policy boundary instead of the convenience go command.
  3. 03

    Inspect, pause or recover

    Use list and status to inspect durable state. Use resume only for the same recoverable run ID; cancel and delete are explicit lifecycle operations rather than hidden cleanup.
  4. 04

    Publish only when intended

    Add --publish branch or --publish pull_request to the prose-first path when a clean local Git worktree should produce reviewable remote work. Publication is off by default.
  5. 05

    Verify independently

    Use handoff, verify-response, or verify-opstruth for the sealed subject. New published local subjects use the same v2 verification contract boundary.

Next steps

Hosted MCP guide

Authentication, tool groups, repository access, and recommended sequences.

Objectives

Design goals, acceptance criteria, authority, validation, and budgets.

Troubleshooting

Understand blocked, ambiguous, failed-safe, and verification-wait states.

Complete references

Jump directly to the MCP or CLI indexes when you already know the task.