AgentMachinist · Job card · Rev 0.8.0

Machinist Job Card

One GitHub issue in, one reviewed pull request out. The machine writes the spec and the code; you approve the exact spec commit and you do the merge. Two dispatch modes, same operations.

issue + label→ spec commit→ draft PR→ approve SHA→ implement→ test gate→ ready PR→ you merge
OP 00

Prep — get the repo onto GitHub first

Machinist works against a GitHub remote: specs are pushed as branches, approvals live on pull requests. Before machinist init, commit everything and put the repository on GitHub.

git init && git add . && git commit -m "initial commit"
gh repo create my-project --private --source . --push
gh auth status                       # must be authenticated
uv tool install agentmachinist
claude --version                     # or opencode / pi / codex on PATH

Local

Your machine runs everything. spec_source: local

GitHub Actions

CI writes the spec; you approve from the GitHub UI. spec_source: github-actions

OP 01

Initialize

Local 
machinist init        # dispatch mode: local
machinist doctor
git add machinist.yaml .machinist/specs/.gitkeep .gitignore
git add -p .github/workflows
git commit -m "chore: configure AgentMachinist" && git push

The wizard asks dispatch mode, harness, test gate, and notifications — each with a safe default.

GitHub Actions 
machinist init --spec-source github-actions
gh secret set ANTHROPIC_API_KEY      # CI spec harness needs it
machinist sync-workflows
git add -p .github/workflows && git commit && git push

Workflows must be pushed before GitHub can record a SHA-bound approval. The CI spec workflow is claude-code only.

OP 02

Create the issue

Same on both tracks 
gh issue create --title "Add CSV export" --label agent-task

Write a focused issue with acceptance criteria. The agent-task label is the trigger — no label, no dispatch.

OP 03

Spec

machine
Local 
machinist spec 7      # or: machinist watch --once
machinist spec 7 --dry-run           # read-only preview

Harness reads the issue read-only in an isolated workshop, writes .machinist/specs/issue-7-spec.md, and the controller pushes agent/issue-7 as a draft PR.

GitHub Actions

Nothing to run. Applying the label triggers machinist-spec.yml, which generates the spec in CI and opens the draft PR.

Your local watch daemon leaves labeled issues alone — exactly one dispatcher owns this phase.

OP 04

Approve the spec

Human gate
Local 
machinist approve --issue 7          # or --pr 8

Read the spec in the draft PR first. Approval binds the label plus the exact 40-character head SHA.

GitHub Actions

On the draft PR, post the comment from the PR body:

/machinist-execute <full-spec-commit-sha>

Or apply the machinist:approved label. machinist-approve.yml records the SHA-bound marker — and only from owners, members, or collaborators.

OP 05

Execute

machine
Always on your machine — CI only ever owns the spec phase 
machinist run 7       # or leave `machinist watch` running to dispatch it

Harness implements against the approved spec, the test gate runs (e.g. uv run pytest), the controller commits, pushes with --force-with-lease, and flips the PR from draft to ready. Edited the spec after approving? The approval goes stale and execution refuses until you approve the new head.

OP 06

Review & merge

Human gate
Same on both tracks

A ready PR means implementation finished and the test gate passed. Review it like any teammate's PR and merge it yourself — AgentMachinist never merges. For rework: machinist amend 7 --feedback "…" after a fresh approval.

Guardrails

SHA-bound approval Approval authorizes one exact spec commit. Any new head on the branch makes it stale.
Controller owns git The harness never commits or pushes; postconditions abort the run if it tries.
Draft = machine's Never mark the draft ready yourself — that transition is the signal that tests passed.
Explicit retry A failed run blocks re-dispatch until machinist retry 7. Nothing silently reruns.