Glossary
The docs capitalize these terms because each one names a specific part of the workflow. Here's what each one means in AgentMachinist.
- Approval
- Your decision to let Execute start on one exact Spec commit. Local Approval records the repository, Task, Spec SHA, who approved, and when. If the Spec changes, you approve the new commit. A review's Approve button on GitHub or GitLab isn't Approval.
- Claim
- Exclusive local ownership of one Task's Phase while it runs. A Claim stops two local workers that share a runtime from spending Harness time on the same Task. It doesn't coordinate separate checkouts or machines.
- Custody
- AgentMachinist's ownership of Git during a Task: it makes every commit and keeps the Task records. The Harness must not commit, push, or edit
.machinist/. After each Harness run, AgentMachinist checks HEAD, local refs, and protected Git metadata. These checks catch violations after the fact, and they can't undo a side effect outside Git. - Evidence
- The durable facts a Task Run leaves behind: the approved Spec commit, verification results, the implementation commit, the independent Review report, and error details. Integration and publication also record what they intended and what happened, so an interrupted command can recover.
- Forge
- A code-hosting service such as GitHub or GitLab. Local Tasks don't need one. You can import an issue from a forge as a Task, or publish a reviewed candidate to one as a pull request or merge request. AgentMachinist never merges on a forge; a person does.
- Gate
- A point where work waits for durable Evidence before it continues. Approval is the first Gate. The last is your review and explicit integration, or a person's merge on a forge. Verification Gates run your configured checks, such as your test command, and required ones must pass before AgentMachinist keeps a candidate.
- Harness
- The coding-agent CLI that reads and edits your code: Claude Code, Codex, OpenCode, Pi, or Goose. Installed plugins can add others. AgentMachinist runs it under the login you already have.
- Phase
- One kind of machine work on a Task: Spec, Execute, or Review. Approval is a human Gate between Spec and Execute. Integration and publication come after Review, and neither is a Phase.
- Spec
- The written implementation plan for a Task. AgentMachinist commits it to the Task branch, and its exact commit SHA identifies it. Approval names that SHA.
- Task
- One bounded objective, such as adding CSV export for filtered rows. AgentMachinist owns each Task and gives local Tasks IDs like
T1. An imported GitHub or GitLab issue is kept as provenance. Legacy GitHub Tasks keep their numeric issue IDs. - Task Run
- The durable record of one Phase attempt for a Task: its Claim, result, Evidence, and any failure. A failed Task Run stays failed until you retry it explicitly, and earlier attempts stay on record.
- Workshop
- The isolated Git worktree or clone where the Harness reads and edits files for a Task. Your own checkout stays unchanged until you integrate. Code and configuration call it a workspace, as in
workspace.strategy.