DoneState docs / Guides
Cookbook: common jobs end to end
Use these recipes as starting points. Each one shows the intent, public DoneState operations, expected boundary, and what to inspect before moving on.
Create a bounded change and open a pull request
Use this when you know the repository outcome you want and want DoneState to implement it, validate it, and publish a reviewable pull request.
Example request to your MCP client
Use DoneState on acme/widgets. Add a health-check endpoint. Acceptance criteria: the endpoint returns 200, existing tests still pass, and no more than 8 files change. Open a pull request but do not merge it.- 01
Check execution funding
Call get_openai_credential_status. If no user-funded key is connected, use create_openai_credential_setup and complete the HTTPS flow. - 02
Create the objective
Call create_objective with the repository, observable acceptance criteria, only the required authority classes, pull_request publication, and a bounded changed-file budget. - 03
Observe progress
Use get_objective. Do not assume a client-side timeout means the run should be recreated. - 04
Review publication
When the run publishes, inspect the exact branch, pull request, head SHA, changed files, and CI state in GitHub. - 05
Verify independently
For a verifier-bound run, allow the sealed handoff and OpsTruth response to complete before treating the result as VERIFIED.
Observe a repository without granting repair authority
Example request
Select acme/widgets for DoneState maintenance in observe mode. Do not schedule work and do not enable auto-repair. Then discover current maintenance findings.- 01
Select
Use select_maintenance_repository with mode=observe, scheduleEnabled=false, and autoRepair=false. - 02
Discover
Use discover_maintenance_work to inspect supported issue and GitHub Actions evidence. - 03
Inspect
Use list_maintenance_findings. A failed workflow remains evidence only; it does not silently become repair authority.
Repair an explicitly admitted maintenance issue
Maintenance repair is narrower than arbitrary autonomous coding. The repository must be selected in pr_only mode, the GitHub App must be installed, required checks must be configured, and the finding must be repair-eligible.
Example request
Find the donestate:repair issue in acme/widgets, show me the finding first, then start one PR-only repair. Do not merge anything.- 01
List or discover findings
Get the exact finding ID rather than trying to infer it from issue text. - 02
Start one repair
Call start_maintenance_repair with that finding ID. The issue body is treated as untrusted evidence, not as a new authority source. - 03
Wait for CI and verification
Required checks and the independent verifier are part of the acceptance boundary for automatic maintenance repair.
Retry independent verification without repeating implementation
Use this when implementation and publication already completed but the run remains AWAITING_VERIFICATION because the verifier was temporarily unavailable or returned an uncertain result.
Example request
For run 11111111-1111-4111-8111-111111111111, show the current objective first. If it is still awaiting verification, ask OpsTruth to re-observe the sealed subject. Do not re-run implementation.- 01
Read the run
Call get_objective and confirm the state and exact published subject. - 02
Retry observation
Call request_opstruth_verification for the existing run. This asks the independent verifier to observe the sealed subject again. - 03
Inspect the decision
Read the new run state and verifier summary. An uncertain or failed decision must not be described as VERIFIED.
Recover a local CLI run after interruption
Inspect first
donestate status RUN_ID
donestate verify-log RUN_IDResume only the recorded run
donestate resume RUN_IDRun the explicit local CLI workflow
Prepare starter documents
donestate init
# edit .donestate/objective.json and .donestate/policy.jsonExecute
donestate run --objective .donestate/objective.json --policy .donestate/policy.jsonInspect and hand off
donestate status RUN_ID
donestate handoff RUN_ID --out handoff.jsonThe explicit workflow is useful when you want objective and execution policy documents reviewed or committed separately from the run itself.
Remove user-controlled DoneState state
Hosted credential
delete_openai_credential({ "confirm": true })Hosted objective
delete_objective({ "runId": "RUN_UUID" })Maintenance selection
remove_maintenance_repository({ "repository": "owner/name", "confirm": true })