How a work item runs

This page follows one work item from the moment you file it to the moment it is archived. It uses the words defined in Vocabulary.

From filing to archive

1. Filing. You file an item from the web UI, kraft item create, or an agent over MCP. A trigger files one too, and so does auto-intake, which picks up ready beads when you turn it on.
2. Intake. Kraft checks the repo, the base branch, the chain and the policy, then freezes the chain and policy onto the item and copies any attached spec or plan. A later edit to a chain file changes nothing for this item.
3. Paused. A filed item waits, paused, until a person starts it. Nothing has run and nothing has been spent. --autostart from a person starts it at once. Auto-intake starts what it files, but only on a chain with at least one gate.
4. Start. kraft item resume (the Start button) claims the item. Before the first node runs, Kraft cuts a git worktree for it from the base branch, on its own branch, copies the attached documents in, and runs the repo's setup_command. If a linked bead is still blocked by another bead, the item goes back to paused instead. A workspace item's members are cut the same way, each as a worktree of its own connected repository, on a branch of the same name.
5. The chain. Kraft walks the nodes in order. An exec node runs its tasks. A gate node stops the item until a person decides. In the shipped default chain that means a spec, a plan and a chain revision, each with its gate; implementation and verification in a fix loop; the local_review gate; a draft merge request with CI and automated review; and the final_review gate.
6. Landing. The chain's last nodes mark the merge request ready, wait for an approving review if the forge requires one, merge it, and wait for the post-merge pipeline.
7. Completed. When the last node finishes, the item is completed and Kraft closes the beads it implements.
8. Archived. Archiving removes the worktree and the branch and takes the item off the board. You archive by hand, or set archive.after_days in policy.yaml to archive ended items automatically. The record of what happened stays. For a workspace item it removes each member's worktree and branch from its connected repository too.

Statuses

A work item always holds one of seven statuses. Five are open and two are ended. An ended item never runs again.

The diagram shows the usual paths. complete and cancel can end an item from any open status, and abandon from any status but active; the second table below lists every move.

What moves an item between them:

kraft item retry is the only way back onto an item that a failure stopped, and it only works from needs_human. resume only works from paused, apart from answering a question. A reject that has already hit its gate's reject limit leaves the item in needs_human.

Displayed status

The stored status set above is unchanged. On top of it, GET /work-items and GET /work-items/{id} report display_status, computed when read from the stored status, the item's stop_kind, a pending gate and whether an escalation has run since the item stopped. It is exactly one of nine values:

The rows are checked top to bottom. A stop recorded before stop_kind existed has no kind and reads needs_you. A stuck stop that automatic escalation is counting down to reads needs_you until the escalation starts, then escalated.

infra reads as failed rather than needs_you because nothing will change it on its own: no handler applies, and no timer or escalation will make a different answer come back. A daemon restart that lost a session, a worktree refresh that git refused, CI infrastructure that ran out of retries and a forge that refused the merge request three times are all infra stops. The way out is a person fixing the cause and retrying.

MR closed externally

An item parked waiting or needs_human at a merge-request node can have its merge request closed on the forge by someone, or something, other than Kraft -- closed, not merged. A poller checks every such item against the forge on a fixed interval (policy.forge_poll_s, default 300s) and, when it finds the merge request closed, stops the item with stop.kind: "mr_closed" and facts: {ref, url} naming it.

There are three ways out, and no fourth: reopen the same merge request (POST /work-items/{id}/reopen-mr), which reopens it on the forge and retries the stopped node, exactly as POST /retry with no path would; retry from the MR node with its path, which opens a fresh merge request instead of reusing the closed one; or cancel the item, which leaves the closed merge request and the worktree as they are.

Inside a node

A chain is a list of nodes. A gate node waits for a person. An exec node runs steps in order, and the tasks in one step in parallel. Each run of a task is a worker session: a row with its status, log, result file, tokens and cost. An agent or subprocess task launches a process for it. A builtin or forge task runs inside Kraft. kraft view logs reads a session's log.

When a task fails, a node can try three things, in this order. Each is optional, and each is declared on the node in its chain file (see Chain nodes).

1. Recovery (on_failure) runs repair steps once per entry into the node, then runs the whole node again. It is for a problem outside the code, such as a label to fix on the merge request.
2. The fix loop (fix_loop) hands the failure to a repair agent, then measures the whole node again, from its first step. From the second attempt on, a judge agent decides whether the attempts are still converging. The loop ends at its attempt limit or its wall clock, or when the judge stops it. See Fix loop and judge.
3. Escalation (escalation) runs once the node is stuck. If it succeeds, the node gets a fresh entry from its first step. If it does not, the item stops for a person.

Some stops skip all three and go straight to a person: a config error, a budget or time cap, an infrastructure failure, a wait timeout, and an agent's question. No repair task can fix those. A rate limit does not stop for a person at all; it parks the item as rate_limited.

A node with no escalation of its own gets a generic one instead. When it stops stuck, and auto_escalate_stuck is on in policy.yaml (the default), Kraft starts an escalation turn: an agent that reads the stopped item and may retry it. It answers only stuck stops, never the ones listed above, and at most auto_escalate_stuck_cap times. You can also start or continue one yourself with kraft item escalate. The Security page lists what an escalation turn is allowed to do.

Steering

A steer is a note to the next agent Kraft launches for this item. It is used once, by the first agent task that runs, and then dropped. There is no channel into an agent that is already running, so a steer never reaches one. To redirect running work, pause it and resume it with a steer.

You give a steer in four ways:

• kraft item resume ID --steer "..." reaches every paused agent task. --steer-task PATH=TEXT addresses one task by its canonical path.
• kraft item retry ID --steer "..." goes into the prompt of the retried node.
• Rejecting a gate with --note sends the note, as a steer, to the node the gate sends the item back to.
• Answering an agent's question: kraft item resume ID --steer "..." on an item that stopped with one.

Kraft refuses a steer that no agent task would read, for example on a node that only runs a subprocess or waits on CI. It tells you so rather than dropping the text.

Review threads are the other way to give feedback. They carry line-level comments and stay until resolved. See Reviewing a change.

Where to go next

• Caps and budgets: the limits behind the needs_human stops above.
• Chain nodes: the keys that declare steps, recovery, fix loops and escalation.
• Architecture: the process and modules that do all of this.