Vocabulary

This page defines the words Kraft's docs use. Each entry is a short definition and a link to the page that explains the term in full. For the keys a chain file accepts, see Chain file keys. To see the words at work, follow one item through How a work item runs.

Find a term

The terms are not in the "On this page" list. Use this table or the site search to find one.

Work items and chains

Work item

A work item is one unit of work, and it produces one merge request. You file one from the web UI, the CLI (kraft item create), or an agent. It always lands paused, so nothing spends a token until you start it. See Starting an item for the one way to skip the pause.

When every max_concurrent slot is busy, a start request is not refused: the item becomes queued, and Kraft starts it when a slot frees. See Work item statuses.

A work item can come after others, named with kraft item create --after. Started while one of them is unfinished, it becomes blocked, and Kraft starts it when they have all completed. A dependency is met when the item it names is completed, post-merge nodes included; it can be dropped with kraft item unblock, never added after filing.

The item's repo must already be connected (kraft repo connect). Kraft refuses one that is not, and names that command. For an item that spans several repositories, see Workspaces.

Base branch

The base branch is the branch an item starts from and merges into. It is the repository's default branch unless the item names another with --base-branch.

That branch is where the worktree is cut from, what every rebase is applied onto, and what the merge request and post-merge CI use. It must already exist on the repository's origin, or Kraft refuses the item. It is fixed when you file the item.

Attachment

An attachment is a spec or plan you file with an item (--spec, --plan). The item starts without the node that would write that document and the gate that approves it.

Kraft stores its own copy when you file the item, and the item's worktree gets that copy, so editing your original changes nothing. Until the item starts, kraft item set-attachments replaces a document, or drops one, which puts its node and gate back. After the item starts, its documents are fixed.

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 stores a copy of any attachment. Intake refuses a problem it finds, so you see it then and not hours into a run.

Auto-intake

Auto-intake is Kraft filing work for you from the ready issues of your beads tracker, polled from bd ready, when enabled is true in intake.yaml (off by default). It starts each item it files, but only on a chain with at least one gate, so the item still stops for you at its first one. See intake.yaml.

Trigger

A trigger files a work item from an event instead of from kraft item create: a schedule in intake.yaml, or a POST /api/triggers call. A trigger always files the item paused, and cannot start it. See Inbound triggers.

Beads

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

Forge

A forge is the code host a repo's merge requests live on: GitHub or GitLab. Kraft reaches it through gh or glab, signed in as the user the server runs as. A repo's forge field says which; kraft repo connect sets it from the remote's host. See repos.yaml.

Workspace

A workspace is a root repository with other repositories mounted in it as submodules, its members, declared under workspaces: in repos.yaml. A work item filed against it changes the root and the members you choose, each cut, when its repository is connected, as a worktree of it. See Workspaces.

Chain

A chain is the ordered list of nodes a work item runs. It writes the stages of your process down once, in a file you can read and diff, so an agent does not decide them afresh each time.

You pick the chain with --chain (kraft item create "..." --chain quick-task). Without one, the item gets the repo's default_chain, or default if the repo sets none, however the item is filed. To build a chain of your own, see Write your own chain. The two chains Kraft ships, node by node, are under The shipped chains.

Chain revision

A chain revision is the change an agent proposes to the rest of a chain once its spec and plan are approved: skip a node, add one, or adjust a limit. It runs in the chain_revision node. See Chain revision for how it is proposed and approved.

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 you. An exec node can carry recovery, a fix loop, and an escalation, all bounded by caps.

Step

A step is a group of tasks inside an exec node. 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.

Task

A task is one unit of execution. There are four kinds, and the split lets Kraft 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.

Worker session

A worker session is one run of a task, recorded with its status, log, result file, tokens, and cost. See Inside a node.

Canonical path

Every task, step, and node has a canonical path, such as spec.main.author. It is how you point Kraft at one piece of work, for example with kraft item retry --path. The path format is in Chain file keys.

Library

The library is the set of reusable tasks, steps, nodes, and steering profiles Kraft ships in library.yaml. A chain component reuses one with extends, which keeps a fix to a shared piece in one place. See Library and chains, and run kraft admin templates lint to check every chain.

Templates

In these docs, templates means library.yaml and the files in chains/, and nothing else. Kraft copies a chain onto each item when you file it, so editing a template changes no item already filed. The directory that holds them and the rest of Kraft's configuration is the config directory. See Configuration.

Add-on

A Kraft add-on, or add-on, is a directory of chains, library components, skills and agent profiles that an instance installs from a collection. Everything it ships is read-only and is named <namespace>:<name>, such as release:ship. An instance pins each installed add-on to a commit and changes it only through a reviewed update. An add-on can set limits and never permissions.

See Share chains with add-ons and Add-ons and collections.

Collection

A collection is a git repository, or a directory, that lists add-ons in .kraft/collection.json. You add a collection to an instance, then install add-ons from it. An add-on's id is <addon>@<collection>, such as release@acme. See Add-ons and collections.

Repo library

A repo library is the chains, library components, skills and agent profiles a connected repository keeps in .kraft/ on its default branch. A person accepts it with kraft repo library, and it then loads under the repository's id, such as my-repo:hotfix. It holds what an add-on holds, with no manifest and no collection. See Repo libraries.

Steering profile

A steering profile is a named block of standing guidance, {instructions: "..."}, in the steering section of library.yaml. A task's steering: and a repository's steering: in repos.yaml select profiles, and Kraft adds their text to the agent's system prompt, 8 KB at most together. It is not a steer, which is a one-time note, and not a harness profile or an agent profile. See Repository steering.

Decisions, notes, and limits

Gate

A gate is where your 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. On the review page the same decision is Request changes: it rejects the gate with your summary and review threads as the note.

Review thread

A review thread is a line-level comment on the change. You can leave one 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. A gate reached with one still unanswered sends the work back instead of asking you again. See Reviewing a change.

Steer

A steer is a note to the next agent Kraft launches for an item. The first agent task that runs reads it once, and then Kraft drops it. See Steering for the four ways to give one. A steer is not a steering profile.

Cap

A cap is a limit on a scope's time, tokens, or dollars. A scope is the work item, a node, a step, or a task. A wait, such as CI, an automated review, an approval, or a merge landing, has its own time limit. A fix loop stops at its attempt limit and wall clock.

Hitting any of these stops the chain and hands the item to you, naming the scope, so a defect the agent cannot fix ends with you seeing the full trace and not a loop that never finishes. See Caps and budgets for how the bounds combine, and policy.yaml for the values.

Policy

A policy is the limits and permissions an item runs under: caps, budget, tool lists, grants, and the harnesses a task may use. policy.yaml holds the instance's, and a repository, a chain, a node, a step, a task, and the item's own override each add a layer. Kraft freezes the result onto the item at intake. See How a policy resolves and policy.yaml.

Recovery

Recovery (on_failure) is a node's optional repair steps, run once per entry into the node when a task fails, before the whole node runs again. See Inside a node.

Fix loop

A fix loop (fix_loop) is a node's optional repair cycle: an agent fixes the failure, then Kraft measures the whole node again, until it passes or the loop runs out of attempts or time. See Fix loop and judge.

Pass

A pass is one time the chain runs a node. A gate rejection, a retry or a base-change restart sends the chain back, and every node it runs again starts a new pass. A fix loop's rounds are counted inside a pass, and a task's attempts inside a round. See Picking a pass.

Judge

A judge is the task a fix loop runs before each repair cycle after the first, to rule whether another attempt is worth it. Its verdict is continue, stop_needs_human or stop_downgrade. See Fix loop and judge.

Stuck

A node is stuck when its fix loop cannot go on: the attempts or the wall clock ran out, the same findings came back, or the judge stopped it. Kraft then tries an escalation, and the item stops and waits for you if that does not clear it. See Fix loop and judge.

Escalation

Escalation (escalation) is the third thing a node can try when a task fails. It 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 and waits for you. A node with none of its own gets a generic one, which runs as an escalation turn.

Apply chip

The apply chip is the button in the web UI's header that appears while saved configuration is not running yet. It offers a reload for files Kraft can reread, and a restart where a service manager started the server. See Saved but not applied.

Agents and where they run

Worker

A worker is an agent session Kraft starts for an agent task, such as an author, an implementer, or a gate's review agent. It runs headless in the item's worktree and identifies itself to Kraft, which refuses it some actions a person can take. An escalation turn is not a worker. See Who may call what, and worker session for one run of a task.

Worktree

A worktree is the work item's own git checkout, cut from its base branch onto a branch of its own. Agents edit it, and archiving the item removes it. See Starting an item.

Harness

A harness is one agent CLI that Kraft can run a task on, described as data and not code. Kraft ships seven. See Agent harnesses.

Harness profile

A harness profile is an entry in harnesses.yaml that names a harness (its provider) and the options to start it with. An agent task's harness: field names one. It is not an agent profile. See harnesses.yaml.

Agent profile

An agent profile is a named model tier (deep, strong, fast) that a task selects with profile: instead of spelling out model: and effort:. A tier means the same on every harness. It is not a harness profile. See Agent profiles.

Sandbox

A sandbox is the container a repository's workers run in, set by sandbox: in repos.yaml or a policy. Without one, workers run directly on your machine, as your user. See Sandboxed workers.

Kit

A Kit is an image that carries a descriptor of what its workload may reach and hold. As a repository's sandbox, it is the whole sandbox. See Kits.

Provider

A provider is one of the seven agent runtimes Kraft knows, named by the provider: key of a harness profile: claude, codex, cursor, opencode, gemini, antigravity or amp. An agent profile spells its model and effort once per provider. It is the agent CLI, not the vendor whose API the CLI calls: that is the model provider. See harnesses.yaml.

Ref store

A ref store is the private copy of a repository's branches and tags that a sandboxed worker's container sees in place of the real ones. Kraft moves only the item's own branch back to your repository when the session ends. See Repository refs.

Sentinel

A sentinel is the stand-in value a sandboxed worker holds for a credential. Kraft's egress proxy swaps the real value in on requests to the host that credential is for, so the container never holds it. See Credentials.

Grant

A grant is a named git operation, git-commit, git-rebase or git-push, that the permission gate allows a task even outside its allowed_tools. It matches one plain git call and nothing else. A grant is only the gate's allow, so a harness that does not reach the gate takes no grant. See Grants for what deny_tools still denies, what git-push reaches, and where a grant takes effect.

How a run proceeds

Walk

A walk is one pass of Kraft's executor through an item's chain, from the node it enters until the item finishes or stops at a gate, a wait, or a stop. Starting the item again begins a new walk. See From filing to archive.

Span

A span is the stretch of a chain that runs again: from the node, step, or task a retry names, or from a node's restart_from when the base branch moves. A retry you ask for starts the fix-loop counts inside its span afresh. See Caps and budgets.

Escalation turn

An escalation turn is an agent session Kraft opens on a stopped item to help. It reads the stop and may retry the item. Kraft starts one itself on a stuck stop, or you start one with kraft item escalate. See Fallback and escalation.

Related

• How a work item runs: the lifecycle and where steers, fix loops, and escalation fit.
• Caps and budgets: how the limits work.
• Configuration: change what Kraft does.