Local workflow · Lifecycle

Local Task lifecycle

A local Task passes through three machine Phases and two decisions that belong to you. The mono line in each state is what machinist status prints. Arrows named for a command, such as APPROVE or RETRY, are steps you take.

Local Task lifecycle A local Task moves from Spec to your Approval, then through Execute and Review to your choice to integrate, amend, or publish; a stopped run waits for retry, and revise or amend return to Spec. RECOVERY MAIN PATH OUTCOMES SAVED APPROVE PASSED REVIEWED STOPPED RETRY REVISE AMEND INTEGRATE PUBLISH PHASE Spec spec running GATE Approval awaiting approval PHASE Execute execute running PHASE Review review running GATE Accept or amend ready to integrate RECOVERY Stopped run execute failed Integrated integrated OPTIONAL Published PR or MR, no reruns Spec and Review stop and retry the same way. A failing baseline stops Spec before any plan. Integration fast-forwards from where start found your base. If the base branch moved, start a new Task. LEGEND Machine Phase Your decision Stopped run Optional End state Next step Return or optional

Your two decisions

Approve one plan, then accept or amend one candidate

Approval names one exact Spec commit. Before you approve, revision replaces the plan with a new commit, and that commit needs its own Approval.

machinist approve --task T1 --spec-sha <sha>
# Or replace the plan first:
machinist revise T1 --feedback '…'

At ready to integrate, inspection shows the plan, the diff, the Gates, and the Review.

machinist inspect T1
# Then accept, amend, or share it:
machinist integrate T1
machinist amend --task T1 --feedback '…'
machinist publish T1 --provider github

When a run stops

A stopped run waits for you

  • A failed, cancelled, or interrupted Phase keeps its Evidence and blocks the Task until you retry it.
  • Retry reruns the Phase that stopped. Execute resumes retained edits unless you add --fresh.
  • A failing baseline means your own checks fail before any change. Fix them, then retry with --phase spec.
  • machinist status always prints the next command.
machinist retry --task T1 --phase execute
# Ask a running Phase to stop:
machinist cancel --task T1

Limits

Where the lifecycle refuses

  • After Approval, the plan stays fixed until a reviewed candidate exists. Revise is refused, and amend needs that candidate.
  • Integration needs a clean checkout of your base branch and fast-forwards only.
  • Integration ends the Task. Amend and revise are refused afterward, while publication stays available and reruns no Phase.