PRODUCT · HOW IT WORKS

How Kraft runs a work item.

A work item is one unit of work that ends in one merge request. Kraft runs it through a chain, retries within bounds when a step fails, and hands it to you when a decision is yours.
A walkthrough of the chain and its gates, sending work back, a fix loop, the caps, parallel worktrees and the board.

01 · CHAINS

A process the agent can't skip.

Each work item follows a chain, a YAML file you can read and diff.

Its nodes are steps such as write the spec, implement, verify and open the merge request. Some run your agent, some run a command and some stop for you.

Docs: The real chain
chains/default.yaml · its 19 nodes, in order
  1. 01spec
  2. 02spec_approvalYOU
  3. 03plan
  4. 04plan_approvalYOU
  5. 05chain_revision
  6. 06chain_revision_approval
  7. 07implementation
  8. 08verification
  9. 09work_brief
  10. 10local_reviewYOU
  11. 11describe_merge_request
  12. 12draft_merge_request
  13. 13merge_request_feedback
  14. 14work_item_summary
  15. 15final_reviewYOU
  16. 16mark_ready
  17. 17external_approval
  18. 18merge
  19. 19post_merge_ci
Four gates wait for you. The fifth, on the chain revision, passes on its own when the revision proposes no change.

02 · GATES

A person at the decisions.

A gate is a node where the chain stops for you. Read what the agent wrote, then approve it, or request changes with a note that re-runs the node that wrote it.

The default chain waits for you at the spec, at the plan, before it opens a draft merge request, and before it marks it ready.

Docs: Reviewing a change
A gate's review page: the brief an agent wrote, the files on the branch and the two decisions.

03 · INDEPENDENT CHECKS

Checks it doesn't grade itself on.

Kraft runs your tests in a node of its own, waits for your CI and has a separate reviewer decide whether a fix is done.

When verification fails, an agent repairs the change and Kraft measures the whole node again. After the first repair, a judge rules whether another attempt is worth it.

Docs: Fix loop and judge
VERIFICATION NODETESTSCODE REVIEWPASSESNEXT NODEFAILSREPAIRMEASURED AGAINVERIFICATION NODETESTSCODE REVIEWPASSESNEXT NODEFAILSREPAIRMEASURED AGAIN
In the default chain, this fix loop is limited to two attempts.

04 · CAPS AND BUDGETS

Capped retries and spend.

Loops limit how often a node repeats. Caps limit the time, tokens and dollars a scope may use.

Whichever runs out first stops the item and hands it to you, with the full trace, instead of failing it.

Docs: Caps and budgets
  • A DAYdollars · $50 as shipped
    • A WORK ITEMtime, tokens, dollars · $10 as shipped
      • A NODEtime, tokens, dollars
        • ITS FIX LOOPverification: 2 attempts, 1 hour
        • A STEPtime, tokens, dollars
          • A TASKtime, tokens, dollars
Scopes nest. The first bound to run out, at any scope, stops the item for you.

05 · WORKTREE ISOLATION

Your checkout stays as you left it.

Each item runs on its own branch in its own git worktree, so items run in parallel.

Archiving an item removes its worktree, and its branch once its commits exist somewhere else.

Docs: How a work item runs
YOUR CHECKOUTLEFT AS IT WASWORK ITEM 1WORK ITEM 2WORK ITEM 3YOUR CHECKOUTLEFT AS IT WASWORK ITEM 1WORK ITEM 2WORK ITEM 3
Each work item has a branch and a worktree of its own. Three run at once by default, and a start past that limit is queued.

06 · WAYS IN

File work from wherever you are.

You file a work item, and it waits paused until you start it.

Gates clear from the same places: the board, a phone, VS Code or the command line.

Docs: File a work item
Web UI
File, start and review on the board.
Phone
The same UI, reached over a tunnel.
Command line
kraft item create
Agent session
Slash commands and MCP tools, from the Kraft plugin.
VS Code
Clear gates beside your code.
Trigger
A schedule or an API call files the item, paused.

07 · SANDBOX

A container for the agent, when you want one.

Without a sandbox, workers run directly on your machine, as your user. None is set by default.

A sandbox runs a repository's workers in a container, with resource limits and a list of hosts they may reach. Only a sandbox with a network policy keeps an agent from deciding its own gates.

Docs: Sandboxed workers
config/repos.yaml · an example from the docsfrom the docs
repos:  - path: /home/you/code/my-service    sandbox:      kind: docker      image: ghcr.io/acme/agent@sha256:...      resources: {cpu: 2, memory: 4g, pids: 512}      network:        install: {allow: [registry.npmjs.org]}        runtime: {allow: [api.github.com]}
The highlighted lines are the network policy: the hosts a task may reach.

Install Kraft.

uv tool install kraft-sdlc