Machinist

Machinist turns one open GitHub issue into a planned, implemented, independently reviewed, and checked pull request. It never merges the pull request.

Core model

• A task is one open GitHub issue in the target repository.
• Assigning a task means starting machinist run or queuing machinist submit.
• Labels report workflow state. They do not assign or start work.
• Reassign the same issue to resume existing work. The foreman recovers its branch, worktree, pull request, checks, and repair count.
• When MACHINIST_RUN_ID is set, the agent is already inside a Machinist run. Follow the assigned role and do not start or submit another run.

Create a task

Reuse a supplied issue when it is open and belongs to the current repository. Otherwise create one issue with gh issue create. Keep it focused on one observable outcome and preserve the user's constraints. Do not invent implementation details that the request does not decide.

gh issue create --title "<short outcome>" --body "<problem, outcome, constraints, and acceptance evidence>"

Use the issue URL returned by GitHub for every later command.

Assign a task

Use direct mode for immediate local work. Pass an absolute Git worktree path:

machinist run \
  --agent=foreman \
  --repo=/absolute/path/to/repository \
  --prompt="Complete https://github.com/owner/repository/issues/123"

Use managed mode when the control plane and worker are already running. Pass the logical repository name from worker.toml:

machinist submit \
  --agent=foreman \
  --repo=repository-name \
  --prompt="Complete https://github.com/owner/repository/issues/123"

submit prints a job ID. Follow managed work in the local control-plane UI. Do not treat adding a label as submission. Label-based delegation is not implemented.

Lifecycle labels

Keep exactly one lifecycle or exception label on the issue:

The foreman creates and transitions these labels. If a label is missing during manual recovery, create it with GitHub CLI, then add it to the issue:

gh label create "machinist:planning" --color 1d76db --description "Machinist is planning this task"
gh issue edit https://github.com/owner/repository/issues/123 --add-label "machinist:planning"

Use the same pattern for the label named in the table. Remove the previous lifecycle label before adding another. Do not change a label merely to make progress appear further along.

Manage and resume work

Inspect the issue labels, the <!-- machinist:foreman-state --> issue comment, the linked pull request, and current checks. Verify the recorded branch, worktree, SHAs, pull request, checks, and repair count against current Git and GitHub state before using them.

• For machinist:needs-human, answer the issue question and reassign the same issue.
• For machinist:blocked, fix the reported external cause and reassign the same issue.
• For interrupted or stale work, reassign the same issue. Do not create a second branch or pull request.
• For machinist:ready-for-review, hand the pull request to a person. Never merge unless that person explicitly decides to do so outside the shipped foreman workflow.

When reporting status, include the issue URL, job ID when managed, pull request URL when created, current label, checks, review verdict, and blocker or next human action.