[{"data":1,"prerenderedAt":783},["ShallowReactive",2],{"navigation_docs":3,"-concepts-vocabulary":270,"-concepts-vocabulary-surround":778},[4,28,51,110,243],{"title":5,"path":6,"stem":7,"children":8},"Get started","\u002Fget-started","1.get-started",[9,12,16,20,24],{"title":10,"path":6,"stem":11},"Overview","1.get-started\u002Findex",{"title":13,"path":14,"stem":15},"Why Kraft","\u002Fget-started\u002Fwhy-kraft","1.get-started\u002F0.why-kraft",{"title":17,"path":18,"stem":19},"Install","\u002Fget-started\u002Finstall","1.get-started\u002F1.install",{"title":21,"path":22,"stem":23},"Your first work item","\u002Fget-started\u002Ffirst-work-item","1.get-started\u002F2.first-work-item",{"title":25,"path":26,"stem":27},"Troubleshooting and FAQ","\u002Fget-started\u002Ftroubleshooting","1.get-started\u002F3.troubleshooting",{"title":29,"path":30,"stem":31,"children":32},"Concepts","\u002Fconcepts","2.concepts",[33,35,39,43,47],{"title":10,"path":30,"stem":34},"2.concepts\u002Findex",{"title":36,"path":37,"stem":38},"Vocabulary","\u002Fconcepts\u002Fvocabulary","2.concepts\u002F1.vocabulary",{"title":40,"path":41,"stem":42},"How a work item runs","\u002Fconcepts\u002Fhow-a-work-item-runs","2.concepts\u002F2.how-a-work-item-runs",{"title":44,"path":45,"stem":46},"Caps and budgets","\u002Fconcepts\u002Fcaps-and-budgets","2.concepts\u002F3.caps-and-budgets",{"title":48,"path":49,"stem":50},"Why a permission gate","\u002Fconcepts\u002Fpermission-gate","2.concepts\u002F4.permission-gate",{"title":52,"path":53,"stem":54,"children":55},"Guides","\u002Fguides","3.guides",[56,58,62,66,70,74,78,82,86,90,94,98,102,106],{"title":10,"path":53,"stem":57},"3.guides\u002Findex",{"title":59,"path":60,"stem":61},"Use Kraft from your agent","\u002Fguides\u002Fagent-integration","3.guides\u002F01.agent-integration",{"title":63,"path":64,"stem":65},"Kraft Lite","\u002Fguides\u002Fkraft-lite","3.guides\u002F02.kraft-lite",{"title":67,"path":68,"stem":69},"Remote access","\u002Fguides\u002Fremote-access","3.guides\u002F03.remote-access",{"title":71,"path":72,"stem":73},"Add or override a harness","\u002Fguides\u002Fadding-a-harness","3.guides\u002F04.adding-a-harness",{"title":75,"path":76,"stem":77},"Schedule or webhook work","\u002Fguides\u002Fschedule-and-webhook-work","3.guides\u002F05.schedule-and-webhook-work",{"title":79,"path":80,"stem":81},"Add a security review or a gate reviewer","\u002Fguides\u002Fadd-review-agents","3.guides\u002F06.add-review-agents",{"title":83,"path":84,"stem":85},"Kraft for VS Code","\u002Fguides\u002Fvscode","3.guides\u002F07.vscode",{"title":87,"path":88,"stem":89},"Reviewing a change","\u002Fguides\u002Freview-a-change","3.guides\u002F08.review-a-change",{"title":91,"path":92,"stem":93},"Write your own chain","\u002Fguides\u002Fwrite-your-own-chain","3.guides\u002F09.write-your-own-chain",{"title":95,"path":96,"stem":97},"Switch a harness","\u002Fguides\u002Fswitch-harness","3.guides\u002F10.switch-harness",{"title":99,"path":100,"stem":101},"Upgrade your templates","\u002Fguides\u002Fupgrading-templates","3.guides\u002F11.upgrading-templates",{"title":103,"path":104,"stem":105},"Operations","\u002Fguides\u002Foperations","3.guides\u002F12.operations",{"title":107,"path":108,"stem":109},"Worker Kit","\u002Fguides\u002Fworker-kit","3.guides\u002F13.worker-kit",{"title":111,"path":112,"stem":113,"children":114},"Reference","\u002Freference","4.reference",[115,117,139,183,201,205,227,231,235,239],{"title":10,"path":112,"stem":116},"4.reference\u002Findex",{"title":118,"path":119,"stem":120,"children":121},"CLI","\u002Freference\u002Fcli","4.reference\u002F1.cli\u002Findex",[122,123,127,131,135],{"title":10,"path":119,"stem":120},{"title":124,"path":125,"stem":126},"Item verbs","\u002Freference\u002Fcli\u002Fitem","4.reference\u002F1.cli\u002F2.item",{"title":128,"path":129,"stem":130},"View verbs","\u002Freference\u002Fcli\u002Fview","4.reference\u002F1.cli\u002F3.view",{"title":132,"path":133,"stem":134},"Repo verbs","\u002Freference\u002Fcli\u002Frepo","4.reference\u002F1.cli\u002F4.repo",{"title":136,"path":137,"stem":138},"Admin verbs","\u002Freference\u002Fcli\u002Fadmin","4.reference\u002F1.cli\u002F5.admin",{"title":140,"path":141,"stem":142,"children":143},"Configuration","\u002Freference\u002Fconfiguration","4.reference\u002F2.configuration\u002Findex",[144,145,155,159,163,167,171,175,179],{"title":10,"path":141,"stem":142},{"title":146,"path":147,"stem":148,"children":149},"Repos","\u002Freference\u002Fconfiguration\u002Frepos","4.reference\u002F2.configuration\u002F2.repos\u002Findex",[150,151],{"title":10,"path":147,"stem":148},{"title":152,"path":153,"stem":154},"Workspaces","\u002Freference\u002Fconfiguration\u002Frepos\u002Fworkspaces","4.reference\u002F2.configuration\u002F2.repos\u002F3.workspaces",{"title":156,"path":157,"stem":158},"Policy","\u002Freference\u002Fconfiguration\u002Fpolicy","4.reference\u002F2.configuration\u002F3.policy",{"title":160,"path":161,"stem":162},"Library and chains","\u002Freference\u002Fconfiguration\u002Flibrary-and-chains","4.reference\u002F2.configuration\u002F4.library-and-chains",{"title":164,"path":165,"stem":166},"Harnesses file","\u002Freference\u002Fconfiguration\u002Fharnesses-file","4.reference\u002F2.configuration\u002F5.harnesses-file",{"title":168,"path":169,"stem":170},"Access","\u002Freference\u002Fconfiguration\u002Faccess","4.reference\u002F2.configuration\u002F6.access",{"title":172,"path":173,"stem":174},"Intake","\u002Freference\u002Fconfiguration\u002Fintake","4.reference\u002F2.configuration\u002F7.intake",{"title":176,"path":177,"stem":178},"Sandbox host","\u002Freference\u002Fconfiguration\u002Fsandbox","4.reference\u002F2.configuration\u002F8.sandbox",{"title":180,"path":181,"stem":182},"Environment variables","\u002Freference\u002Fconfiguration\u002Fenvironment-variables","4.reference\u002F2.configuration\u002F9.environment-variables",{"title":184,"path":185,"stem":186,"children":187},"Chain nodes","\u002Freference\u002Fchain-nodes","4.reference\u002F3.chain-nodes\u002Findex",[188,189,193,197],{"title":10,"path":185,"stem":186},{"title":190,"path":191,"stem":192},"Subprocess tasks","\u002Freference\u002Fchain-nodes\u002Fsubprocess-tasks","4.reference\u002F3.chain-nodes\u002F2.subprocess-tasks",{"title":194,"path":195,"stem":196},"Fix loop and judge","\u002Freference\u002Fchain-nodes\u002Ffix-loop","4.reference\u002F3.chain-nodes\u002F3.fix-loop",{"title":198,"path":199,"stem":200},"Result file","\u002Freference\u002Fchain-nodes\u002Fresult-file","4.reference\u002F3.chain-nodes\u002F4.result-file",{"title":202,"path":203,"stem":204},"Permission gate","\u002Freference\u002Fpermissions","4.reference\u002F4.permissions",{"title":206,"path":207,"stem":208,"children":209},"Agent harnesses","\u002Freference\u002Fharnesses","4.reference\u002F5.harnesses\u002Findex",[210,211,215,219,223],{"title":10,"path":207,"stem":208},{"title":212,"path":213,"stem":214},"Unattended runs","\u002Freference\u002Fharnesses\u002Funattended-runs","4.reference\u002F5.harnesses\u002F2.unattended-runs",{"title":216,"path":217,"stem":218},"Agent profiles","\u002Freference\u002Fharnesses\u002Fagent-profiles","4.reference\u002F5.harnesses\u002F3.agent-profiles",{"title":220,"path":221,"stem":222},"Harness files","\u002Freference\u002Fharnesses\u002Fharness-files","4.reference\u002F5.harnesses\u002F4.harness-files",{"title":224,"path":225,"stem":226},"Fallback and escalation","\u002Freference\u002Fharnesses\u002Ffallback-and-escalation","4.reference\u002F5.harnesses\u002F5.fallback-and-escalation",{"title":228,"path":229,"stem":230},"Inbound triggers","\u002Freference\u002Ftriggers","4.reference\u002F6.triggers",{"title":232,"path":233,"stem":234},"HTTP API","\u002Freference\u002Fhttp-api","4.reference\u002F7.http-api",{"title":236,"path":237,"stem":238},"MCP tools","\u002Freference\u002Fmcp-tools","4.reference\u002F8.mcp-tools",{"title":240,"path":241,"stem":242},"Events","\u002Freference\u002Fevents","4.reference\u002F9.events",{"title":244,"path":245,"stem":246,"children":247},"Project","\u002Fproject","5.project",[248,250,254,258,262,266],{"title":10,"path":245,"stem":249},"5.project\u002Findex",{"title":251,"path":252,"stem":253},"Architecture","\u002Fproject\u002Farchitecture","5.project\u002F1.architecture",{"title":255,"path":256,"stem":257},"Contributing","\u002Fproject\u002Fcontributing","5.project\u002F2.contributing",{"title":259,"path":260,"stem":261},"Security","\u002Fproject\u002Fsecurity","5.project\u002F3.security",{"title":263,"path":264,"stem":265},"Data and privacy","\u002Fproject\u002Fdata-and-privacy","5.project\u002F4.data-and-privacy",{"title":267,"path":268,"stem":269},"Status and support","\u002Fproject\u002Fstatus-and-support","5.project\u002F5.status-and-support",{"id":271,"title":36,"body":272,"description":771,"extension":772,"links":773,"meta":774,"navigation":775,"path":37,"seo":776,"stem":38,"__hash__":777},"docs\u002F2.concepts\u002F1.vocabulary.md",{"type":273,"value":274,"toc":756},"minimark",[275,286,291,320,327,340,344,390,393,421,427,460,466,484,504,508,521,528,549,553,558,599,603,617,620,634,652,659,672,679,683,686,695,698,703,707,720,724,740,744],[276,277,278,279,282,283,285],"p",{},"Kraft's core vocabulary is six words: work item, chain, node, task, gate, and\ncap. Three more terms, intake, beads and steer, are defined at the end. This\npage explains what each means and why it exists. For the exact keys a chain\nfile accepts, see ",[280,281,184],"a",{"href":185},". To see the words at\nwork, follow one item through ",[280,284,40],{"href":41},".",[287,288,290],"h2",{"id":289},"work-item","Work item",[276,292,293,294,298,299,303,304,307,308,311,312,315,316,319],{},"A ",[295,296,297],"strong",{},"work item"," is one unit of work and produces one merge request. You create\none from the web UI, the CLI (",[300,301,302],"code",{},"kraft item create","), or an agent. It always\nlands ",[295,305,306],{},"paused",", so nothing spends a token until a person starts it. A person\ncan skip the pause with ",[300,309,310],{},"kraft item create --autostart","; an agent cannot. See\n",[280,313,314],{"href":60},"Agent integration",". A ",[280,317,318],{"href":229},"trigger"," that files an item is held to the\nsame rule.",[276,321,322,323,326],{},"The item's repo must already be connected (",[300,324,325],{},"kraft repo connect","). Kraft refuses\none that is not, and names that command.",[276,328,329,330,333,334,337,338,285],{},"Work starts from the repository's default branch, and the merge request targets\nit, unless the item names a ",[295,331,332],{},"base branch"," (",[300,335,336],{},"--base-branch","). Then that branch\nis where the worktree is cut from, what every rebase replays onto, and what the\nmerge request and post-merge CI use. The branch must already exist on the\nrepository's origin, or Kraft refuses the item. It is fixed when the item is\nfiled. For an item that spans several repositories, see\n",[280,339,152],{"href":153},[287,341,343],{"id":342},"chain","Chain",[276,345,346,347,349,350,353,354,333,357,360,361,364,365,368,369,372,373,375,376,379,380,383,384,387,388,285],{},"A work item runs as a ",[295,348,342],{},": an ordered list of ",[295,351,352],{},"nodes",". A chain is\nstored on disk as a ",[295,355,356],{},"chain template",[300,358,359],{},"chains\u002F*.yaml","), which is why the CLI\nand config call it a template (",[300,362,363],{},"default_chain_template","). Kraft copies the\nchain onto the item when you file it, so editing the chain file later changes\nnothing for an item already filed. You pick the chain with ",[300,366,367],{},"--chain","\n(",[300,370,371],{},"kraft item create \"...\" --chain quick-task","). Without one, the item gets\nthe repo's ",[300,374,363],{}," from ",[300,377,378],{},"repos.yaml",", or ",[300,381,382],{},"default"," if the\nrepo sets none. That holds for every way of filing work, including\n",[280,385,386],{"href":173},"auto-intake",". To build a chain\nof your own, see ",[280,389,91],{"href":92},[276,391,392],{},"The chain exists so that the stages of your process are written down once, in a\nfile you can read and diff, instead of being decided fresh by an agent each time.",[276,394,395,396,399,400,403,404,407,408,410,411,414,415,375,418,420],{},"The simplest shipped chain, ",[300,397,398],{},"quick-task",", is two nodes with no gates:\n",[300,401,402],{},"implementation",", then ",[300,405,406],{},"verify",". ",[300,409,406],{}," runs the repo's own ",[300,412,413],{},"test_scopes"," or\n",[300,416,417],{},"test_command",[300,419,378],{},". On a repo that declares neither, the item\nstops for a person with a config error rather than a guessed command.",[276,422,423,424,426],{},"The shipped ",[300,425,382],{}," chain is the real one:",[428,429,430,434,437,440,447,450,457],"ol",{},[431,432,433],"li",{},"A spec, then a plan, each with its own approval gate.",[431,435,436],{},"A chain revision (below).",[431,438,439],{},"Implementation, then verification (the changed test scopes, then a code\nreview) inside a fix loop.",[431,441,442,443,446],{},"A work brief and a ",[300,444,445],{},"local_review"," gate before any merge request exists.",[431,448,449],{},"A draft merge request, with CI and automated review, and its own fix loop.",[431,451,452,453,456],{},"A summary and the ",[300,454,455],{},"final_review"," gate.",[431,458,459],{},"Ready, external approval, merge, and the post-merge pipeline.",[276,461,462,465],{},[300,463,464],{},"kraft admin templates show default --resolved"," prints it with every library\ncomponent expanded.",[276,467,468,471,472,475,476,479,480,483],{},[295,469,470],{},"Chain revision."," A chain is picked before its spec and plan exist. Once the\nplan is approved, the ",[300,473,474],{},"chain_revision"," node has an agent read both against the\nnodes still to run and propose changes: skip a node, add one built from library\ncomponents, or adjust a task's ",[300,477,478],{},"model"," or ",[300,481,482],{},"effort",", or an operational limit,\nwithin the administrator's maxima. Only nodes after its gate may change. A gate\nnever does. Nodes that open, describe, sync, ready, or merge the merge request,\nor wait on its checks, cannot be skipped.",[276,485,486,487,490,491,493,494,499,500,503],{},"Usually it proposes nothing, and the ",[300,488,489],{},"chain_revision_approval"," gate passes\nwithout asking anyone. When it does propose something, the gate shows the\nrationale, each change with the line of the spec or plan behind it, and the\ndiff. Approving replaces the item's chain with exactly the revision you were\nshown. Kraft ties your approval to what you read: if the revision changed since,\nthe approval is refused until you look again. A proposal that would not\nvalidate cannot be approved; reject it back to ",[300,492,474],{}," instead. The\n",[280,495,496],{"href":125},[300,497,498],{},"item approve"," reference has the ",[300,501,502],{},"--digest"," command.",[287,505,507],{"id":506},"node","Node",[276,509,293,510,512,513,516,517,520],{},[295,511,506],{}," is one stage of a chain. It is either an ",[295,514,515],{},"exec"," node, which runs\nwork, or a ",[295,518,519],{},"gate"," node, which waits for a person.",[276,522,523,524,527],{},"An exec node runs one or more ",[295,525,526],{},"steps",", each a group of tasks. Tasks in one\nstep run in parallel. Steps run in order, so a later step sees what an earlier one\nleft behind and is skipped if the earlier one fails. Around that, a node can\ncarry recovery, a fix loop, and an escalation, all bounded by caps (below).",[276,529,530,531,534,535,538,539,542,543,546,547,285],{},"Every task, step, and node also has a ",[295,532,533],{},"canonical path",", such as\n",[300,536,537],{},"spec.main.author",". That is how you point Kraft at one piece of work, for example\nwith ",[300,540,541],{},"kraft item retry --path",". The full key list, the ",[300,544,545],{},"read_only"," check, and\nthe path format are in ",[280,548,184],{"href":185},[287,550,552],{"id":551},"task","Task",[276,554,293,555,557],{},[295,556,551],{}," is one unit of execution. There are four kinds, and the split exists\nso that Kraft can treat an agent's judgment differently from its own\nbookkeeping:",[559,560,561,575,581,587],"ul",{},[431,562,563,566,567,570,571,574],{},[295,564,565],{},"agent"," runs a headless coding agent in the item's worktree, on a\n",[280,568,569],{"href":207},"harness profile",". Its model comes from an\n",[280,572,573],{"href":217},"agent profile"," or from its own\nsettings.",[431,576,577,580],{},[295,578,579],{},"subprocess"," runs a literal command.",[431,582,583,586],{},[295,584,585],{},"builtin"," is work Kraft does itself, such as running the repo's tests or\nrebasing onto the item's base branch before a draft merge request opens.",[431,588,589,592,593,595,596,598],{},[295,590,591],{},"forge"," is a merge-request action on GitHub or GitLab (open a draft, watch\nCI, merge), resolved from the ",[300,594,591],{}," recorded in the repo's ",[300,597,378],{},"\nentry.",[287,600,602],{"id":601},"the-library-and-reuse","The library and reuse",[276,604,605,606,609,610,612,613,616],{},"A chain does not restate everything. Kraft ships a library of reusable tasks,\nsteps, and nodes, and a chain component reuses one with ",[300,607,608],{},"extends",". This keeps a\nfix to a shared piece in one place. See ",[280,611,184],{"href":185},"\nfor the rules, and run ",[300,614,615],{},"kraft admin templates lint"," to check every chain.",[287,618,619],{"id":519},"Gate",[276,621,293,622,624,625,628,629,633],{},[295,623,519],{}," is where a human decision belongs. When the chain reaches a gate\nnode it stops. The work item's status becomes ",[300,626,627],{},"needs_human",", and the board shows\nit under ",[630,631,632],"em",{},"Needs you",". From there you can:",[559,635,636,642],{},[431,637,638,641],{},[295,639,640],{},"Approve."," The chain continues to the node after the gate.",[431,643,644,647,648,651],{},[295,645,646],{},"Reject",", with a note. The chain re-enters at the gate's ",[300,649,650],{},"reject_to"," node,\ncarrying the note as a steer, so the node that produced the document tries\nagain with your feedback.",[276,653,654,655,658],{},"To redirect an item that is paused mid-flight rather than waiting at a gate,\nresume it with a steer instead (",[300,656,657],{},"kraft item resume ID --steer \"...\"",").",[276,660,661,662,665,666,669,670,285],{},"Line-by-line feedback goes in ",[295,663,664],{},"review threads"," rather than one note. You can\nleave them at any point, gate or not: every agent that runs next reads the ones\nstill waiting on an answer, and working agents reply in the thread. A\n",[300,667,668],{},"must-fix"," thread blocks every approval until you resolve it, and a gate\nreached with one still unanswered sends the work back instead of asking you\nagain. See ",[280,671,87],{"href":88},[276,673,674,675,678],{},"An item filed with an attached spec or plan starts without the nodes that\ndocument covers: the gate that decides it and the node that would have written\nit. Kraft keeps its own copy of the document when you file the item, and that\ncopy is what the item's worktree gets, so editing your original afterwards\nchanges nothing. Until the item starts, ",[300,676,677],{},"kraft item set-attachments"," replaces a\ndocument (copied again) or drops one, which puts its gate and node back. Once the\nitem starts, its documents are fixed.",[287,680,682],{"id":681},"cap-and-wait","Cap and wait",[276,684,685],{},"Every retry loop is bounded, so a defect the agent cannot fix ends with a person\nseeing the full trace instead of a loop that never finishes. A fix loop stops at\nits own attempt limit and wall clock. An external wait (CI, an automated review,\nan approval, a merge landing) has its own time limit. Hitting either stops the\nchain and escalates.",[276,687,688,689,691,692,694],{},"Time, tokens, and dollars are capped per scope too: the work item, a node, a\nstep, or a task. Running out stops the item for a person and names the scope.\n",[280,690,44],{"href":45}," explains how the bounds combine,\nand ",[280,693,140],{"href":157}," lists the values.",[287,696,172],{"id":697},"intake",[276,699,700,702],{},[295,701,172],{}," is the moment Kraft accepts a filed work item: it checks the repo,\nbase branch, chain, and policy, freezes the chain and policy onto the item, and\nsnapshots any attached spec or plan. A problem found at intake is refused then,\nnot hours into a run.",[287,704,706],{"id":705},"beads","Beads",[276,708,709,711,712,715,716,719],{},[295,710,706],{}," are an optional issue tracker (",[300,713,714],{},"bd",") that Kraft can link a work item\nto. ",[300,717,718],{},"kraft item create --implements BEAD"," records the bead an item implements\nand closes it when the item completes. Kraft works without beads.",[287,721,723],{"id":722},"steer","Steer",[276,725,293,726,728,729,731,732,735,736,285],{},[295,727,722],{}," is a note to the next agent Kraft launches for an item. It is read\nonce, by the first agent task that runs, and then dropped. A running agent has\nno input channel, so to redirect one you pause the item and resume it with a\nsteer (",[300,730,657],{},"). ",[300,733,734],{},"kraft item retry --steer"," and a\ngate rejection's note are steers too. Kraft refuses a steer that no agent task\nahead would read. See ",[280,737,739],{"href":738},"\u002Fconcepts\u002Fhow-a-work-item-runs#steering","Steering",[287,741,743],{"id":742},"where-to-go-next","Where to go next",[276,745,746,747,749,750,752,753,755],{},"See ",[280,748,40],{"href":41}," for the lifecycle\nand statuses, ",[280,751,44],{"href":45}," for how limits work, or\n",[280,754,140],{"href":141}," to change what Kraft does.",{"title":757,"searchDepth":758,"depth":758,"links":759},"",2,[760,761,762,763,764,765,766,767,768,769,770],{"id":289,"depth":758,"text":290},{"id":342,"depth":758,"text":343},{"id":506,"depth":758,"text":507},{"id":551,"depth":758,"text":552},{"id":601,"depth":758,"text":602},{"id":519,"depth":758,"text":619},{"id":681,"depth":758,"text":682},{"id":697,"depth":758,"text":172},{"id":705,"depth":758,"text":706},{"id":722,"depth":758,"text":723},{"id":742,"depth":758,"text":743},"The core words: work item, chain, node, task, gate, cap, plus intake, beads and steer.","md",null,{},true,{"title":36,"description":771},"rQGkej95hanIUxUnWWIqf9gMQdTwogxz-aJCVvl9QhA",[779,781],{"title":10,"path":30,"stem":34,"description":780,"children":-1},"The vocabulary, lifecycle, limits, and permission model behind Kraft.",{"title":40,"path":41,"stem":42,"description":782,"children":-1},"A work item's path from filing to merge, the seven statuses it can hold, and where a steer, a fix loop and an escalation fit.",1790824505526]