Kraft Lite reference
Look up how the Kraft Lite plugin resolves a chain, runs a node and keeps its state. The skills run the kl.py verbs named here. You rarely type one yourself, but the skills' output names them, and this page says what each does and refuses.
Chain sources
Lite reads the files Kraft reads, a library.yaml and its chains/*.yaml, and expands extends as Kraft does: library components first, then a chain that extends another chain. A chain comes from one of four places:
--chain PATH. A chain file, told by its.yamlor.ymlending or a/in the name. Itsextendsresolve against your library, else the bundled one. A file in.kraft/chains/is the exception: it is a repo chain, run as itsrepo:<id>.- The repo library. The
.kraft/folder at the repo root, addressed asrepo:<id>, for examplerepo:ship. Lite has no repo ID of its own, sorepo:stands for this repo. Inside that library a bare name means its own entry, as in Kraft. - Your library. The directory Kraft reads its configuration from:
$KRAFT_CONFIG_DIRwhen set (or its 1.x name$KRAFT_TEMPLATES_DIR), else$KRAFT_HOME/config, else~/.kraft/config. The first one set is the one, even without alibrary.yamlin it: Lite then reads the bundled one, as in step 4. Your library replaces the bundled library wholesale, with no layering, as it does in Kraft. A bare name such asdefaultmeans an entry here, andkraft-default:<name>means the bundled entry. - The bundled library. A copy of Kraft's packaged
config/library.yamlandconfig/chains/, shipped with the plugin and kept identical by a test. It is Kraft's built-in add-on,kraft-default. Kraft seeds a new home with achains/default.yamlthat is onlyextends: kraft-default:default(and the same forquick-task), so a stock home runs the bundled chains.
A repo library differs from Kraft's in two ways. Lite reads the working tree, not the default branch's commit, and there is no acceptance step, because you are already running in that checkout. An edit to .kraft/chains/ship.yaml counts at your next start, committed or not. See repo libraries for what the folder holds.
With no --chain, start runs repo:default when the repo library has a chains/default.yaml, and default otherwise. kl.py chains --available lists every chain ID Lite can see, with the library it came from and its file. A reference to any other add-on, such as acme:ship, is refused by name: Lite loads no add-ons. A repo library can't name kraft-default: either, since Kraft's lists the add-ons it builds on and Lite reads no such list.
Reading the YAML
Lite needs nothing installed. When PyYAML is importable it reads with yaml.safe_load, the reader Kraft uses. Otherwise it uses a built-in reader for the subset Kraft's own files are written in: block and flow collections, plain and quoted scalars, | and > block scalars, and comments.
The built-in reader refuses what it can't be sure to read as PyYAML would, and names the file and line:
- anchors, aliases and tags
- merge keys (
<<) - more than one document
- complex keys
- multi-line quoted scalars
- plain scalars PyYAML would read as a timestamp
Quote the value, or install PyYAML. The reader also refuses what PyYAML itself rejects: a tab outside a quoted or block scalar's text or a comment, and a plain scalar that starts with an indicator such as %, ,, ] or ? .
Bindings
Lite supplies the order, the gates and the caps, and calls whatever you already use for each task. A task with nothing of yours to run follows Kraft's own method for it, the spec writer and the planner included: see Kraft's methods.
A task runs on its default unless .kraft-lite/bindings.yaml binds it to something else. The file is optional, so is every entry in it, and a chain runs with no file at all. /kraft-lite:init writes one from what it finds in the repo, listing only the entries that differ from the defaults.
The file has three sections, plus a fourth for children:
tasks: by the library component's name (spec_author), or by canonical path,node.step.task(implementation.main.implement), the paths Kraft's overrides use.builtins: by ref, such askraft.verify_changed_test_scopesorkraft.mr_rebase.forge: by target, such asmr.open_draft,mr.ciormr.merge.slice: the same three sections, read only in a child walking a slice, ahead of everything else.
tasks:
spec_author:
kind: skill
skill: superpowers:brainstorming
prompt: Agree requirements and write a spec before any code.
verification.review.code_review:
kind: skip
why: the merge request review covers it
builtins:
kraft.verify_changed_test_scopes:
kind: subprocess
command: [just, test]
forge:
mr.ci:
kind: subprocess
command: [gh, pr, checks]
slice:
tasks:
implementer:
kind: prompt
prompt: Implement the slice's tasks test first, one at a time.
An entry has a kind:
skill: invokeskill. It needs aprompttoo, which runs instead if the skill isn't installed, so a renamed skill degrades to an instruction.prompt: follow theprompt.subprocess: runcommand, a list of arguments, with no shell.skip: run nothing. It needs awhy, which is shown when the task is skipped.
Which binding wins
The first match wins: the task's canonical path, then each library component it extends, nearest first, then its ref (a builtin task) or target (a forge task). A child walking a slice looks in slice: first, then in its built-in slice defaults, then in the top-level sections.
With no match, the task runs on its default:
- An agent task runs its
skillif that is installed in this harness. Else, when the skill is one of Kraft's methods, it runs itspromptand that method, and otherwise itspromptalone. - A subprocess task runs its
command, split like a shell and run without one, as Kraft runs it. A command Lite can't split, such as one with an unclosed quote, stopsstart. - A builtin or forge task runs an instruction Lite carries for every ref and target Kraft allows, written for this repo's forge. The verify task's
suite: fullasks for the full suite, as Kraft runs it.
Every task that runs a skill or a prompt, bound or default, gets the task's steering text appended. Its profile, model and effort reach the session as hints for choosing a sub-agent's model.
start works out the instruction for every task before it writes anything. A bindings file Lite can't use, or a task with no instruction, stops start and names the entry. The file is read again on every dispatch.
A tasks key that names no task of the chain, by path or component, doesn't stop start, since it may be meant for another chain. start lists it under unused_bindings instead, as tasks.<key>, or slice.tasks.<key> for a slice: key that names no task a slice runs. A misspelt key would otherwise leave its task on the default without a word.
Kraft's methods
Added in 2.6
Lite ships the methods a Kraft worker follows, in methods/: one file per kraft:<name> skill the library names (kraft:spec, kraft:plan, kraft:code-review, kraft:fix-loop-judge and the rest), copied unchanged from Kraft. A task whose skill is kraft:<name>, or a bare <name>, that isn't installed here gets its prompt, its steering, then a ## Method section telling the agent to read that method's file and follow it. Its source ends (shipped method).
A binding for the task still wins. A kind: skill binding gets the method only when its own skill is a Kraft method that isn't installed. kraft:review-feedback is the exception: it reads a file Kraft's forge adapter writes, so Lite skips it by default, since Lite's review step already reports what the review bots said. Bind it to run something else.
The method text names things only a Kraft worker has. The ## Method section tells the agent how to read them here:
- A result file (
$KRAFT_RESULT_PATH) and itsstatus: the agent reports the same fields in its reply. A review'sfindingsare what a step fails on. - A review package (
$KRAFT_REVIEW_PACKAGE): the branch's diff against its base. Lite gives no fingerprints, sosame_astags and the judge's fingerprint trend are absent. kraft viewandkraft itemcommands (events, merged merge requests, labels, pipelines, job logs,mr-label): git and the forge's own CLI instead. Lite keeps no event log, sokraft:work-briefandkraft:review-briefwork from git history and the chain's state.needs_context: the agent stops and asks you.kraft:chain-reviewlists components withkraft admin templates library, which needs Kraft installed, and Lite can't apply a revision anyway (see Gates).
What Lite reads past, and what it refuses
Lite runs inside one session, so it can't enforce a budget, a time cap, an allowed-tools list, a sandbox or a harness choice. It reads past these keys, so a chain that sets them still runs:
policy, all but a node'smax_attempts, which caps its fix loop.wait,scope,execution,harness,inputs,skippable,icon,timeout,fallback,runner,reviewersandpipeline.escalation. An escalation is you, as for a fix loop past its cap.- A gate's
auto_review, unless itsauto_review_modeischecks_first.
Lite does read read_only, on an exec node and on its steps, and state reports it. The next skill tells the agent that a read_only scope changes nothing: no writes, no commits, no tests, no files left behind. Lite doesn't check that afterwards, as Kraft does, so the rule is the agent's to keep.
A gate whose reviewer checks first (auto_review_mode: checks_first) runs that reviewer before the gate reaches you, in a sub-agent that may not change files. On a reject it sends the work back with the reviewer's note. Otherwise you get the gate with that note first. The reviewer never approves. A reviewer that decides (the default) is read past: in Lite it would be your own session approving its own gate.
Lite stops, naming the file and the key, at what it can't walk without changing what the chain means: a reference to an add-on other than kraft-default, a step's or a task's own on_failure, and on_conflict under on_base_changed. It also refuses the cases Kraft refuses, such as an unknown builtin ref or forge target, or a key on_base_changed or on_merge_rejected doesn't have.
Lite checks what it needs to walk a chain, not everything Kraft would. Before relying on a chain you wrote, run kraft admin templates lint --dir on its folder: that is the full check.
How a node runs
A chain is nodes, and a node is either an exec node or a gate. An exec node holds steps, each of tasks. Lite runs the steps in order, and the tasks inside one step in any order or in parallel. A step fails when a task in it fails or reports findings of critical or important severity, and no later step runs after that. A verb that meets a node missing from the frozen chain fails rather than guessing.
When a task has produces, Lite records the file it wrote with kl.py produced --kind <kind> --path <file>. A gate whose artifact names that kind then presents the newest such file.
Fix-loop order
A node that fails goes through its fix loop, in Kraft's order:
- If the node has an
on_failureand a task failed, that runs once, then the node runs again from its first step. - A builtin or forge task that fails with no findings, such as missing credentials, stops for you. It spends no attempt.
- Each cycle spends an attempt. From the second, the loop's judge, if it has one, rules first: continue, stop for you, or finish with the findings left.
- Past the cap, the chain stops and shows you every attempt's output. The cap is the loop's
max_attempts, else the node policy'smax_attempts, else 3. - The loop's repair steps run, then the whole node again from its first step.
A step that moved the branch's base, such as a rebase or sync that did work, hasn't failed. If the node has on_base_changed, kl.py restart reopens the walk at its restart_from node and every node through this one, with their attempts reset. A node restarts at most three times.
The merge task can report that the forge's merge train or merge queue dropped the merge request. If the node has on_merge_rejected, as the bundled default's merge does, its repair steps run. Then kl.py restart --merge-rejected reopens the walk at its restart_from node through this one, so the merge request's checks and the final gate are answered again. A node is sent back this way at most three times. Without on_merge_rejected, a drop stops for you.
Gates
A gate is a node of its own, with a message, an artifact, and where a rejection goes. You approve it or reject it. close is refused on a gate, and approve on an exec node. A rejection reopens the node the gate's reject_to names, else the nearest exec node before it, and every node after that, carrying your note. reject --from-node lands the rejection on another node.
The chain_finalized gate, and any gate with artifact_required, needs its document, as in Kraft: approve is refused while no file of its artifact kind is recorded and on disk. Reject it --from-node the node that writes the document, so that node runs again.
A gate on a chain_revision artifact is the one case Lite can't finish: it can't apply a change set to a running chain. If the proposal changes anything, Lite says so and offers two ways on: approve without the change, or stop and start again on an edited copy of the chain's file.
A proposal that changes nothing passes without asking, as in Kraft: gate closes it and prints passed_unchanged with the proposal's rationale. That takes the change set Kraft's chain review writes: one fenced JSON block with a rationale and no skip, add or overrides, and no slicing proposal waiting at the gate. Anything else comes to you.
That file is the frozen chain's source when it is a path, else the one kl.py chains --available lists for its ID. A repo: chain's copy goes in .kraft/chains/ under a new ID. The new run passes the approved spec and plan with --spec and --plan, so it starts at the chain revision.
State fields
kl.py state is all a session needs to carry on, so a cleared context loses nothing. It reports:
| Field | Holds |
|---|---|
chain_id, node, kind, status, note | The chain's ID, the live node, exec or gate, its status and its note. |
attempt, cap | Fix attempts spent and the cap. |
read_only | For an exec node, whether the node is read_only. Each step in steps carries its own read_only. |
backend, sliced | Where state lives, and the slice state once a run is sliced. |
produced | Each document kind the run recorded, mapped to its newest file, so a later task finds it, as opening the merge request finds mr_meta. |
steps | For an exec node, its tasks, as dispatch records (below). |
on_failure, on_failure_ran, fix_loop, on_base_changed, on_merge_rejected | For an exec node, the recovery blocks and whether on_failure has run. |
gate | For a gate: the message, the artifact and its artifact_path, the reject_to node, whether it is the chain_finalized or the slice gate, and whether it has artifact_required. |
Each task in steps is one dispatch record:
| Field | Holds |
|---|---|
path | The task's canonical path. |
kind | How it runs: skill, prompt, subprocess or skip, with skill, prompt, command or why. |
produces, hints | The document kind it writes, and the model hints. |
source | The rule that chose the binding. |
task_kind, ref, target | From the chain, whatever binding ran it: agent, builtin, forge or subprocess. |
Start with a spec or a plan
start --spec PATH and start --plan PATH hand over documents you already have. For each kind, Lite drops the gate that approves it, never the chain_finalized gate, and the exec node whose tasks all produce it. A surviving gate whose reject_to named a dropped node falls back to the nearest exec node before it. A surviving on_base_changed.restart_from that named a dropped node moves to the nearest kept exec node before it, else the first one kept.
That last rule is Lite's own: Kraft drops such an on_base_changed, and Lite keeps the restart, as a slice's child chain keeps it.
Lite records the path, relative to the repo when the file is inside it, and doesn't copy the file. The gates that remain present it as that kind's artifact. With neither flag, the chain writes both documents itself.
State storage
State is in bd when the repo has it, otherwise in .kraft-lite/chain.jsonl. The bd export format is the same either way, so adopting bd later is bd import, not a migration.
/kraft-lite:status lists what is in the directory, and kl.py chains is the verb behind it. kl.py summary reports one run back: per-node times split into work and waiting at a gate, attempts against their caps, gates answered and rejection notes.
To make that possible, every write also records the wall-clock time it happened, the seconds already spent waiting at a gate, and the attempts already spent, because a later write would otherwise overwrite each one. It counts no tokens and no money, because Lite runs inside your session and never sees them.
A directory can hold several chains. Every kl.py verb that reads or writes a chain takes --chain-id <id>. With one unfinished chain the flag is optional, and with two or more it is required: Lite refuses to guess which run a gate belongs to. Each run's frozen chain lives in .kraft-lite/chains/<chain-id>.json, one per run, so two runs can walk different chains side by side.
Slices
Slices split a plan across sessions, so its parts run in parallel. The session that walks the feature chain becomes the controller. Each slice is a part of the plan that stands alone, built by its own child session.
When to slice
Slice only what stands alone: a part that uses no other part's work, and is coherent enough for its own tests and its own build, verify and review loop. A slice of one or two tasks almost never qualifies, and six slices are plenty. Smaller independent tasks run as sub-agents in one session, which is the default. A plan that strains one context is a reason to look for such parts, not a reason to slice.
The plan says how it splits in a ## Slices section, in Kraft's grammar, so the same plan slices the same way in Kraft:
## Slices
- **Slice 1: CSV writer.** Tasks 2-3.
- **Slice 2: Import validator.** Tasks 4, 5.
Task numbers name the plan's ### Task N headings. Every task sits in exactly one slice. A task in no slice, task 1 here, is groundwork, which Lite builds as a first slice, groundwork, that the others come after.
kl.py plan-slices reads the section and prints the proposal's slices, or refuses it with the reason. A plan without the section gets a proposed grouping by the same rule. plan-slices --check FILE refuses a proposal that leaves a plan task out. approve --slices runs the same check and refuses the same way. Either way the proposal shows which slices run in parallel, and gives each helper or fixture that two slices would create one owner.
Independent slices are the default, and the form Kraft shares. Lite also lets a slice come after another, for one built on another's merged work, as the bullet's last sentence: - **Slice 3: Export command.** Task 6. Comes after slice 1. That is Lite's own extension, and it costs early starts and rebases (below).
A plan that uses Comes after slice N. can't be sliced by Kraft: Kraft refuses its ## Slices section and runs the plan unsliced, as one work item.
The proposal is shown at the slice gate, and your answer is the approval. A plan whose parts don't stand alone isn't sliced: the controller says so, and the chain continues as one. Slicing is accepted only at that gate. A rejection leaves no slice behind.
Sending the chain back with reject --from-node keeps the slices only when the plan stands. A rewind to the slice gate or earlier retires them: slices lists none, and the chain is sliced again, from a new proposal, at the slice gate.
A rewind to the first build node is refused while every slice is done, because it would close again at once with nothing redone. Reopen the slices to redo first, with slice-set --slice KEY --status running. A rewind to a node after the first build node leaves the slices as they are.
Where a chain slices
Lite finds the places from the chain's shape, never from node names, so a chain you wrote slices as the default does. state marks the slice gate, and slices reports the shape it found.
- The first build node is the first exec node none of whose tasks produces a document. When a node produces the
plan, or a gate presents it, it is the first such node after the last of them, so a check node before the plan, or between the plan and its gate, isn't it. In the default chain,implementation. - The slice gate is the last gate before the first build node, and is never the
chain_finalizedgate. In the default chain,chain_revision_approval. In a chain with a plan gate and then the build, the plan gate. - The MR node is the first node with a forge task that targets
mr.open_draft. It must come after the first build node. In the default chain,draft_merge_request. - The child chain is the nodes after the slice gate and before the first gate after the MR node, less every gate and every exec node that produces a document some gate presents. In the default chain:
implementation,verification,describe_merge_request,draft_merge_requestandmerge_request_feedback.
A chain without that shape is walked unsliced. approve --slices refuses on it and names the missing piece, such as "no gate before the first build node", which is what Kraft's quick-task chain lacks.
Controller and children
The controller starts a child for each slice whose "comes after" slices are merged, so independent slices run in parallel. A slice that comes after exactly one slice may start early, from that slice's branch, once that slice is in review or ready to merge. The controller logs that choice. A slice that comes after two or more waits until all of them are merged.
A child walks the child chain (above), cut from the controller's frozen chain. It starts with kl.py start --slice-of <state checkout>/chain.json --title "<slice>", so it never resolves a library itself and walks exactly what the controller froze. A kept node's on_base_changed.restart_from that names a dropped node moves to the nearest kept exec node before it, else to the child chain's first node.
The child's slice: bindings win over everything else. Without them, the agent tasks of the first build node run the subagent-driven-development skill, whatever component they extend. The changed-scope tests run only the paths the slice touches, and the merge request's automated review is skipped, because the controller's review is that review. CI runs the full suite.
Where Lite would stop for you, the child asks the controller, never you. The controller answers, reviews each child's merge request, merges, archives the finished child, and keeps the run's state. Every sub-agent and child gets a model set on purpose: the cheapest for reading and relaying, the middle for implementation and child sessions, the strongest for reviews and judgement calls.
The controller doesn't start a child until you have finished giving instructions for the run. Say "go" when you have.
Two merge request modes
The default is the feature mode. Each slice opens its merge request into a feature branch, and the controller reviews it and merges it there on green CI. When every slice is in, the controller opens the merge request from the feature branch to main, and its review covers how the slices fit together. You approve and merge that one.
Before the MR node, an exec node that produces nothing, such as verification in the default chain, runs only its changed-scope tests over the feature branch's diff, where CI can't cover it. Every other node runs as in an unsliced chain, and you answer its gates.
In the main mode, each slice opens its own merge request to main. The controller reviews it and reports, and you merge it. The feature mode is the nearest thing to Kraft's slices, which end in one merge request. The main mode is like filing the slices as separate Kraft work items.
A slice is merged only once you merge it. A slice after exactly one other need not wait for that: while that slice is in review or ready to merge, it can start early from its branch, and it moves onto main when you merge that slice. A slice that comes after two or more waits until you have merged them all, then starts from main.
In the main mode, every node after the first build node closes with nothing to do, as there is no single merge to watch. Two kinds wait until you have merged every slice merge request: the chain_finalized gate, and a node that merges a merge request (final_review and merge in the default chain).
Set the mode in .kraft-lite/slices.json, or say so when the run starts.
Who decides what
These are the defaults:
| Decision | Setting | Default |
|---|---|---|
| A plan question a child raises | plan_question | controller |
| Its review verdict on a slice | slice_review | controller |
| Approving and merging a slice merge request into the feature branch | merge_slice | controller |
The merge request from the feature branch to main | merge_main | user |
| A push outside the child's own slice branch | push_outside_branch | user |
Change any of them for one run by saying so when it starts, or as a standing rule in .kraft-lite/slices.json, which you commit beside bindings.yaml:
{
"mode": "main",
"rights": { "merge_slice": "user" }
}
A right you leave out keeps its default. An unknown key or value is refused, naming it. kl.py settings prints what is in effect.
The controller writes down every call it makes on its own: the question, the answer and why. It shows you the log when you next check in, and again before the work wraps up, while a call is still cheap to overturn. The log is .kraft-lite/decisions/<chain-id>.jsonl.
The controller may hold a critical question, or one that is costly to undo, for you. The child keeps working on whatever doesn't depend on it. Silence is never an answer: a held question stays at the top of every status until you answer it. A decision that is only yours, such as a push the child wasn't given, is passed up to you with the words to type and the session to type them in.
The state branch
.kraft-lite/ isn't in git, and a cloud container comes back as a fresh clone. After every change the controller exports the run to a branch of its own and pushes it. The export is the feature chain's and the slices' records, its frozen chain (chain.json) and the decisions log. A resumed controller imports it before it writes anything. An export made by an older Kraft Lite has no chain.json, and import refuses it.
In a cloud session the state branch is the controller's own session branch. Locally it is the feature branch's name plus -state. It holds state only, never product code, specs or plans, and is never merged. Specs and plans reach the children as messages. At the end the controller lists the branches that are safe for you to delete.
Add .kraft-lite/decisions/, .kraft-lite/messages/, .kraft-lite/proposals/ and .kraft-lite/reviews/ to .gitignore, and .kraft-lite/registry.yaml.migrated if migrate left one. /kraft-lite:init tells you to. Commit .kraft-lite/harnesses/: it holds what a run learned about your harness.
Harness support
Slices need four abilities from the harness: start a child session, message it, be messaged by it, and archive it. The controller also needs a way to check in later. The guides in skills/run-slices/references/ map them to the tools of Claude Code, Codex, Cursor, Gemini CLI, Antigravity, Amp and OpenCode, and mark the ones they couldn't confirm.
Where a harness lacks an ability, there is a fallback. A child on the same machine writes to a file under .kraft-lite/messages/. A child on another machine comments on its own draft merge request. A controller that can't be woken says so, and you run /kraft-lite:run-slices to continue the run.
On a harness with no guide, or for an ability its guide marks unconfirmed, the controller looks before it falls back. It checks its own tools, Kraft's harness profile, the CLI's help and the official docs, running only read-only commands. It writes what it confirmed, with the source and version, to .kraft-lite/harnesses/<harness>.md, which is meant to be committed.
The next run reads that file first, as claims to check: it runs only the harness's own commands from it, and lists them to you before you say "go". It tells you what it found, and offers the file as a guide to ship.
If the harness can't start a session at all, the controller walks the slices itself, one after another, and the run goes on. A cloud child can't message a controller on another machine. For a local controller with cloud children, merge request comments are the channel.
Slice verbs
The skills run these. kl.py state also reports sliced once a run is sliced. slices reports shape, the slice gate, first build node and MR node it found, or why the chain can't be sliced.
| Verb | What it does |
|---|---|
approve --slices FILE | Approves the slice gate and creates the slices. It refuses a bad proposal (below) and writes nothing. |
start --slice-of FILE | Starts a child on the child chain cut from the exported chain.json at FILE, with the slice: bindings. It takes no --chain, --spec or --plan. |
plan-slices [--plan FILE] | Prints a proposal's slices from the ## Slices section of the chain's plan, or of FILE, groundwork first. It refuses a section out of grammar. --check PROPOSAL refuses a proposal that leaves a plan task out. Added in 2.6 |
slices | Lists the slices, and which may start or must rebase (below). |
slice-set --slice KEY | Sets --status, --session, --branch or --fork. Statuses: waiting, starting, running, in_review, ready_to_merge, merged. The last slice merged closes the run. A call that changes nothing writes nothing. |
settings | Prints the mode and the rights in effect. |
decide | Logs a decision, under a slice with --slice KEY, which must name one of the run's slices. With --held, holds the question for you. |
answer --decision ID --answer TEXT | Records your answer to a held question. A decision that isn't held is refused. |
decisions | Lists the log. --held shows held questions, --unreported what is new or newly answered since the last report, and --mark marks those reported. |
export --to DIR, import --from DIR | Copy a run to the state branch's checkout, and back. An import never overwrites a newer local record or decision: it keeps the copy written more times, so a clock that runs behind can't keep a stale one. |
approve --slices refuses a plan with a cycle, an unknown after, a duplicate key, an empty task list, a task in two slices, a plan task in no slice or a bad branch. Nothing is written.
slices gives each slice's status, what it comes after, its session and branch, and cut_from, the slice it was cut early from. ready lists those whose "comes after" slices are all merged. early lists those that come after exactly one slice, which is in review or ready to merge.
base_moved lists the slices that need a rebase. A slice is listed when it was cut early from a slice whose branch has since moved, or from a slice already listed. Each one rebases onto the new tip of the slice its cut_from names.
slice-set starts a waiting slice only from ready or early, and moves one never started no further than running. It records a slice merged only once every slice it comes after is merged, so a slice cut early from another's branch merges after that one.
A slice that goes back from review to work, or records a new --fork, puts each slice cut early from it in base_moved, then each slice cut early from those. A slice leaves the list when it records the fork of its rebase with --fork.
slice-set refuses three inputs:
- a
--forkthat isn't 4 to 64 hex digits - a
--branchthat isn't a good branch name (below) - a
--sessionthat is empty or holds whitespace
close refuses to close a sliced run's first build node until every slice is done: merged, or in main mode merged or ready to merge. In main mode, close on an exec node and approve on a gate refuse to close a node that waits for your merges until every slice is merged. The refusal names the slices that aren't.
import refuses a directory with no records.jsonl, naming the path, and a chain ID that start wouldn't mint (kl- and 8 of 0-9a-f), before it reads or writes a file. It also refuses an export holding a record that isn't its chain's epic, node, run or slice under the ID it was minted with (naming each), or a line it can't read (naming the file and line). It writes nothing.
import ranks decisions as it ranks records: it keeps the copy written more times, and compares stamps as times. A copy that is still held can't take back an answer given on a machine whose clock runs behind.
approve --slices also refuses a task listed twice in one slice, a slice named twice in one after, and a key that isn't 1 to 40 lowercase letters, digits, - and _, starting with a letter or digit. It refuses a key the plan or a slice doesn't take, naming it, so a misspelt after isn't dropped.
A bad branch is one that isn't a string, holds whitespace, starts with -, or is one git refuses (.., a part starting with ., an ending of /, . or .lock, or any of ~^:?*[\). A feature branch that is also the state branch is bad, and so is any feature branch in main mode, which has none.
Move an older directory
Before Kraft Lite walked Kraft's own chains, a repo bound hooks in .kraft-lite/registry.yaml, and a run froze one of the plugin's JSON chains. A directory in that state is carried over, not stranded:
python3 "$CLAUDE_PLUGIN_ROOT/kl.py" migrate
Until then, a verb that meets a legacy registry, or an unfinished run in the old format, refuses with one line telling you to run migrate. Only chains, detect and migrate run beside a registry that has no bindings file.
migrate does two things:
- The registry becomes
bindings.yaml. Each hook maps to the task, ref or target that now does its job (the table below). A binding that says what the default already says is dropped, and so is a hook V1 has no task for. The command lists what it dropped. Comments aren't carried. The old file is renamedregistry.yaml.migrated: add it to.gitignore, or delete it. - Each unfinished run moves to a new ID on Kraft's bundled
default, not adefaultfrom your library or the repo's. Closed nodes stay closed, and the node the run was at keeps its attempts and note. The old run is closed and labelledkraft-migrated-to:<new id>.
| Old hook | Binding it becomes |
|---|---|
on.spec.requested, on.plan.requested, on.chain.review_ready | tasks: spec_author, plan_author, revise_chain |
on.implementation.start, on.review.local.run | tasks: implementer, code_review |
on.mr.describe | tasks: describe_mr |
on.test.run, on.mr.rebase | builtins: kraft.verify_changed_test_scopes, kraft.mr_rebase |
on.mr.open | forge: mr.open_draft |
on.ci.poll, on.review.mr.run | forge: mr.ci, mr.automated_review |
on.merge, on.merge.watch | forge: mr.merge, mr.post_merge_ci |
on.slice.implementation.start, on.slice.test.run | slice: tasks.implementer, builtins.kraft.verify_changed_test_scopes |
on.env.prepare, on.repos.scan | dropped: Kraft's worktree setup has no such task |
on.mr.sync | dropped: it pulled the merge request into the branch, and V1's mr.sync pushes the branch |
on.human_review.requested | dropped: presenting the work for sign-off is the final_review gate's job; write_summary only writes the brief it shows |
A legacy node becomes one or more V1 nodes, so a run lands on the same work:
| Legacy node | V1 nodes |
|---|---|
spec, plan | Each becomes the node and its approval gate. |
chain_review | chain_revision and chain_revision_approval |
verify | verification |
open_mr | work_brief, local_review, describe_merge_request and draft_merge_request |
mr_checks | merge_request_feedback |
human_review | work_item_summary and final_review |
merge | mark_ready, external_approval and merge |
post_merge_watch | post_merge_ci |
migrate refuses, and migrates nothing, when it finds:
- a run that is sliced, or a slice's child run;
- a run on a custom chain, or on one with nodes the old default lacked;
- a run whose chain record is missing;
- a registry binding a hook outside the table. Take it out, run
migrate, then add its binding tobindings.yamlby hand, keyed by task name; - a registry entry that would make a bindings file Lite refuses, such as a
skillwith noprompt. Correct it in the registry; - both
bindings.yamlandregistry.yaml, because it would overwrite the bindings. Move yours aside, runmigrate, and merge the two by hand.
For a run it refuses, finish it on the previous Kraft Lite version, or abandon it, then run migrate again:
python3 "$CLAUDE_PLUGIN_ROOT/kl.py" migrate --abandon <chain-id>
--abandon closes the run's open records, each labelled kraft-abandoned, and deletes nothing: the records and the frozen chain stay. It refuses an ID that isn't an unfinished run in the old format.
A run that finished in the old format has nothing to move, and blocks nothing. state reports it done and chains lists it. Every other verb that reads its chain, summary and export among them, refuses, because its reports need the previous Kraft Lite.
migrate is safe to run twice: it renames the registry last, so a run interrupted halfway finishes when you run it again. With nothing left to move, it reports nothing moved. A state export written before Lite carried chain.json is refused by import, which says it came from an older Kraft Lite.