Local workflow · Swimlane

How AgentMachinist works

You describe a Task and make two decisions. AgentMachinist runs the coding Harness, checks its work, and makes every commit.

How AgentMachinist works Swimlane showing who acts at each step of a local Task: Spec, exact Approval, verified commit, Review, integration, and an optional PR or MR. $ machinist start SPEC approve EXECUTE + REVIEW integrate publish OPTIONAL YOU intent and decisions AGENTMACHINIST makes every commit HARNESS works in a Workshop FORGE optional SPEC SHA CANDIDATE REPORT 01 Describe the Task Task T1 02 Draft the Spec read-only 03 Save the Spec git commit 04 Approve the Spec --spec-sha <sha> 05 Implement edits files 06 Verify and commit gates · custody 07 Review candidate read-only · advisory 08 Integrate fast-forward only 09 Open a PR or MR gh · glab LEGEND Your decision Your input AgentMachinist step Harness step Optional step Handoff Forge call

In the terminal

One Task from start to a reviewed local candidate

machinist start "Reject unknown timezone names in parse_timezone with a ValueError"
# Read the saved Spec, then approve its exact commit:
machinist approve --task T1 --spec-sha <full-spec-commit-sha>
# Execute, Verification Gates, and independent Review run in the foreground.
# Findings are advisory. Inspect the report and candidate diff, then:
machinist integrate T1
# Optional: publish a PR or MR instead of, or after, integrating.
machinist publish T1 --provider github

Your two decisions

Approval and integration stay with you

Approval names one exact Spec commit. If the Spec changes, you approve the new commit before anything runs.

Integration moves your branch to the reviewed candidate by fast-forward only. A dirty checkout or a moved base stops it.

Custody

AgentMachinist makes every commit

  • The Harness drafts, edits, and reviews. AgentMachinist commits.
  • After each Harness run, AgentMachinist checks HEAD, local refs, and protected Git metadata for changes.
  • Required verification gates must pass before AgentMachinist commits a candidate.
  • This is detection plus reduced credentials, not a sandbox.

When plans change

Amend, retry, or publish

  • machinist amend turns feedback on a reviewed candidate into a new Spec, which needs a fresh Approval.
  • Failed runs retain Evidence and need an explicit retry. Local machinist retry defaults to resuming validated retained Execute edits. Add --fresh to start in a new Workshop.
  • machinist publish pushes the candidate and opens a GitHub PR or GitLab MR without rerunning any Phase.

Optional bounded repair, added in 0.18.0, defaults off and can repeat implementation once after an eligible required Gate failure, before rerunning all Gates. It stays inside Execute and the approved Spec. Failed or interrupted repair needs explicit retry --fresh.