Vocabulary

Kraft's core vocabulary is six words: work item, chain, node, task, gate, and cap. Three more terms, intake, beads and steer, are defined at the end. This page explains what each means and why it exists. For the exact keys a chain file accepts, see Chain nodes. To see the words at work, follow one item through How a work item runs.

Work item

A work item is one unit of work and produces one merge request. You create one from the web UI, the CLI (kraft item create), or an agent. It always lands paused, so nothing spends a token until a person starts it. A person can skip the pause with kraft item create --autostart; an agent cannot. See Agent integration. A trigger that files an item is held to the same rule.

The item's repo must already be connected (kraft repo connect). Kraft refuses one that is not, and names that command.

Work starts from the repository's default branch, and the merge request targets it, unless the item names a base branch (--base-branch). Then that branch is where the worktree is cut from, what every rebase replays onto, and what the merge request and post-merge CI use. The branch must already exist on the repository's origin, or Kraft refuses the item. It is fixed when the item is filed. For an item that spans several repositories, see Workspaces.

Chain

A work item runs as a chain: an ordered list of nodes. A chain is stored on disk as a chain template (chains/*.yaml), which is why the CLI and config call it a template (default_chain_template). Kraft copies the chain onto the item when you file it, so editing the chain file later changes nothing for an item already filed. You pick the chain with --chain (kraft item create "..." --chain quick-task). Without one, the item gets the repo's default_chain_template from repos.yaml, or default if the repo sets none. That holds for every way of filing work, including auto-intake. To build a chain of your own, see Write your own chain.

The chain exists so that the stages of your process are written down once, in a file you can read and diff, instead of being decided fresh by an agent each time.

The simplest shipped chain, quick-task, is two nodes with no gates: implementation, then verify. verify runs the repo's own test_scopes or test_command from repos.yaml. On a repo that declares neither, the item stops for a person with a config error rather than a guessed command.

The shipped default chain is the real one:

1. A spec, then a plan, each with its own approval gate.
2. A chain revision (below).
3. Implementation, then verification (the changed test scopes, then a code review) inside a fix loop.
4. A work brief and a local_review gate before any merge request exists.
5. A draft merge request, with CI and automated review, and its own fix loop.
6. A summary and the final_review gate.
7. Ready, external approval, merge, and the post-merge pipeline.

kraft admin templates show default --resolved prints it with every library component expanded.

Chain revision. A chain is picked before its spec and plan exist. Once the plan is approved, the chain_revision node has an agent read both against the nodes still to run and propose changes: skip a node, add one built from library components, or adjust a task's model or effort, or an operational limit, within the administrator's maxima. Only nodes after its gate may change. A gate never does. Nodes that open, describe, sync, ready, or merge the merge request, or wait on its checks, cannot be skipped.

Usually it proposes nothing, and the chain_revision_approval gate passes without asking anyone. When it does propose something, the gate shows the rationale, each change with the line of the spec or plan behind it, and the diff. Approving replaces the item's chain with exactly the revision you were shown. Kraft ties your approval to what you read: if the revision changed since, the approval is refused until you look again. A proposal that would not validate cannot be approved; reject it back to chain_revision instead. The item approve reference has the --digest command.

Node

A node is one stage of a chain. It is either an exec node, which runs work, or a gate node, which waits for a person.

An exec node runs one or more steps, each a group of tasks. Tasks in one step run in parallel. Steps run in order, so a later step sees what an earlier one left behind and is skipped if the earlier one fails. Around that, a node can carry recovery, a fix loop, and an escalation, all bounded by caps (below).

Every task, step, and node also has a canonical path, such as spec.main.author. That is how you point Kraft at one piece of work, for example with kraft item retry --path. The full key list, the read_only check, and the path format are in Chain nodes.

Task

A task is one unit of execution. There are four kinds, and the split exists so that Kraft can treat an agent's judgment differently from its own bookkeeping:

• agent runs a headless coding agent in the item's worktree, on a harness profile. Its model comes from an agent profile or from its own settings.
• subprocess runs a literal command.
• builtin is work Kraft does itself, such as running the repo's tests or rebasing onto the item's base branch before a draft merge request opens.
• forge is a merge-request action on GitHub or GitLab (open a draft, watch CI, merge), resolved from the forge recorded in the repo's repos.yaml entry.

The library and reuse

A chain does not restate everything. Kraft ships a library of reusable tasks, steps, and nodes, and a chain component reuses one with extends. This keeps a fix to a shared piece in one place. See Chain nodes for the rules, and run kraft admin templates lint to check every chain.

Gate

A gate is where a human decision belongs. When the chain reaches a gate node it stops. The work item's status becomes needs_human, and the board shows it under Needs you. From there you can:

• Approve. The chain continues to the node after the gate.
• Reject, with a note. The chain re-enters at the gate's reject_to node, carrying the note as a steer, so the node that produced the document tries again with your feedback.

To redirect an item that is paused mid-flight rather than waiting at a gate, resume it with a steer instead (kraft item resume ID --steer "...").

Line-by-line feedback goes in review threads rather than one note. You can leave them at any point, gate or not: every agent that runs next reads the ones still waiting on an answer, and working agents reply in the thread. A must-fix thread blocks every approval until you resolve it, and a gate reached with one still unanswered sends the work back instead of asking you again. See Reviewing a change.

An item filed with an attached spec or plan starts without the nodes that document covers: the gate that decides it and the node that would have written it. Kraft keeps its own copy of the document when you file the item, and that copy is what the item's worktree gets, so editing your original afterwards changes nothing. Until the item starts, kraft item set-attachments replaces a document (copied again) or drops one, which puts its gate and node back. Once the item starts, its documents are fixed.

Cap and wait

Every retry loop is bounded, so a defect the agent cannot fix ends with a person seeing the full trace instead of a loop that never finishes. A fix loop stops at its own attempt limit and wall clock. An external wait (CI, an automated review, an approval, a merge landing) has its own time limit. Hitting either stops the chain and escalates.

Time, tokens, and dollars are capped per scope too: the work item, a node, a step, or a task. Running out stops the item for a person and names the scope. Caps and budgets explains how the bounds combine, and Configuration lists the values.

Intake

Intake is the moment Kraft accepts a filed work item: it checks the repo, base branch, chain, and policy, freezes the chain and policy onto the item, and snapshots any attached spec or plan. A problem found at intake is refused then, not hours into a run.

Beads

Beads are an optional issue tracker (bd) that Kraft can link a work item to. kraft item create --implements BEAD records the bead an item implements and closes it when the item completes. Kraft works without beads.

Steer

A steer is a note to the next agent Kraft launches for an item. It is read once, by the first agent task that runs, and then dropped. A running agent has no input channel, so to redirect one you pause the item and resume it with a steer (kraft item resume ID --steer "..."). kraft item retry --steer and a gate rejection's note are steers too. Kraft refuses a steer that no agent task ahead would read. See Steering.

Where to go next

See How a work item runs for the lifecycle and statuses, Caps and budgets for how limits work, or Configuration to change what Kraft does.