[{"data":1,"prerenderedAt":1526},["ShallowReactive",2],{"navigation_docs":3,"-get-started-first-work-item":270,"-get-started-first-work-item-surround":1521},[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":21,"body":272,"description":1514,"extension":1515,"links":1516,"meta":1517,"navigation":1518,"path":22,"seo":1519,"stem":23,"__hash__":1520},"docs\u002F1.get-started\u002F2.first-work-item.md",{"type":273,"value":274,"toc":1499},"minimark",[275,288,295,442,466,471,488,495,501,505,508,513,516,568,571,579,582,590,594,597,633,662,665,682,686,692,740,747,753,759,772,791,795,802,835,842,871,876,880,885,932,938,942,968,992,1001,1034,1052,1058,1091,1098,1108,1112,1123,1157,1166,1195,1202,1208,1212,1218,1263,1273,1300,1328,1350,1363,1386,1406,1420,1424,1429,1443,1447,1495],[276,277,278,279,283,284,287],"p",{},"This walks through starting Kraft, connecting a repo, running a work item end\nto end, and approving the gates that stand in its way. Steps 1 to 5, on the\n",[280,281,282],"code",{},"quick-task"," chain, take about fifteen minutes, most of it spent waiting on an\nagent. Steps 6 and 7 run the ",[280,285,286],{},"default"," chain to a merged pull request, which\ntakes longer in wall-clock time: it waits on your approvals, on CI, and on the\nforge.",[276,289,290,294],{},[291,292,293],"strong",{},"Before you start",", you need:",[296,297,298,306,361,379,386,397],"ul",{},[299,300,301,302,305],"li",{},"Kraft installed. See ",[303,304,17],"a",{"href":18},".",[299,307,308,309,312,313,316,317,320,321,324,325,328,329,324,332,320,335,324,338,341,342,324,345,348,349,352,353,356,357,360],{},"A git repo to work on, with a test command Kraft can find. Kraft looks at\nthe repo root for, in order: a ",[280,310,311],{},"justfile"," with a ",[280,314,315],{},"test"," recipe (",[280,318,319],{},"just test","),\n",[280,322,323],{},"pyproject.toml"," (",[280,326,327],{},"uv run pytest -q","), ",[280,330,331],{},"package.json",[280,333,334],{},"npm test",[280,336,337],{},"Cargo.toml",[280,339,340],{},"cargo test","), or ",[280,343,344],{},"go.mod",[280,346,347],{},"go test .\u002F...","). A repo with none\nof these connects ",[291,350,351],{},"disabled",", and no work item runs on it until you set\n",[280,354,355],{},"test_command"," in its ",[280,358,359],{},"repos.yaml"," entry and enable it.",[299,362,363,364,367,368,371,372,371,375,378],{},"A committed ",[280,365,366],{},".gitignore"," in that repo covering build output and caches\n(",[280,369,370],{},"__pycache__\u002F",", ",[280,373,374],{},"node_modules\u002F",[280,376,377],{},"target\u002F"," and the like). After each agent\ntask, Kraft commits every file the agent left in the worktree that git does\nnot ignore, so without one, running the tests is enough to put their\nbyproducts on the item's branch.",[299,380,381,382,385],{},"Claude Code, installed and logged in: the shipped chains run on it. See\n",[303,383,384],{"href":207},"Harnesses"," for the other agents Kraft can drive.",[299,387,388,389,392,393,305],{},"Kraft registered with Claude Code: the plugin, or ",[280,390,391],{},"kraft admin init",". See\n",[303,394,396],{"href":395},"\u002Fget-started\u002Finstall#connect-your-agent","Connect your agent",[299,398,399,400,403,404,407,408,410,411],{},"For steps 6 and 7: a GitHub or GitLab remote on the repo, with ",[280,401,402],{},"gh"," or ",[280,405,406],{},"glab","\nlogged in. Kraft opens and merges the merge request through it. Steps 1 to 5\nwork without one. The ",[280,409,286],{}," chain also expects:\n",[296,412,413,432],{},[299,414,415,418,419,422,423,426,427,431],{},[291,416,417],{},"CI that runs on pull requests."," Kraft waits for the merge request's\nchecks to pass. On GitHub, a pull request with no checks at all reads as\n\"no checks yet\" and stays pending, so ",[280,420,421],{},"merge_request_feedback"," waits until\nits 90-minute cap and then stops for you. A repo with no CI can set\n",[280,424,425],{},"ci_checks: false"," on its entry in\n",[303,428,429],{"href":147},[280,430,359],{}," to skip both CI waits,\nbefore and after the merge.",[299,433,434,437,438,441],{},[291,435,436],{},"A review rule only if you can meet it."," ",[280,439,440],{},"external_approval"," waits while\na branch rule requires an approving review. GitHub does not let you\napprove your own pull request, so on a solo repo with such a rule it waits\nuntil you remove the rule or someone else approves. With no such rule it\npasses straight away, so a solo developer needs nothing here.",[443,444,446,447,450,451,454,455,458,459,462,463,305],"note",{"title":445},"Doing this from Claude Code instead","Step 2 recommends ",[280,448,449],{},"\u002Fkraft:onboard",". Steps 3 to 7 have slash commands as well:\n",[280,452,453],{},"\u002Fkraft:handoff"," to file work, ",[280,456,457],{},"\u002Fkraft:board"," to see it, ",[280,460,461],{},"\u002Fkraft:gates"," to\napprove. See ",[303,464,465],{"href":60},"Agent integration",[467,468,470],"h2",{"id":469},"_1-start-the-server","1. Start the server",[472,473,478],"pre",{"className":474,"code":475,"language":476,"meta":477,"style":477},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","kraft\n","bash","",[280,479,480],{"__ignoreMap":477},[481,482,485],"span",{"class":483,"line":484},"line",1,[481,486,475],{"class":487},"sBMFI",[276,489,490,491,494],{},"Leave that running. It is the server, in the foreground, on\n",[280,492,493],{},"http:\u002F\u002F127.0.0.1:8765",". Open that URL; you should see an empty board.",[276,496,497,500],{},[291,498,499],{},"Open a second terminal"," for everything that follows.",[467,502,504],{"id":503},"_2-connect-a-repo","2. Connect a repo",[276,506,507],{},"Connect it from your coding agent, or from a terminal.",[509,510,512],"h3",{"id":511},"from-your-agent-recommended","From your agent (recommended)",[276,514,515],{},"In Claude Code, install the Kraft plugin and open a session in the repo you want\nKraft to work on:",[472,517,519],{"className":474,"code":518,"language":476,"meta":477,"style":477},"claude plugin marketplace add itsOmidKarami\u002Fkraft\nclaude plugin install kraft@kraft\ncd ~\u002Fcode\u002Fmy-project\nclaude\n",[280,520,521,539,552,562],{"__ignoreMap":477},[481,522,523,526,530,533,536],{"class":483,"line":484},[481,524,525],{"class":487},"claude",[481,527,529],{"class":528},"sfazB"," plugin",[481,531,532],{"class":528}," marketplace",[481,534,535],{"class":528}," add",[481,537,538],{"class":528}," itsOmidKarami\u002Fkraft\n",[481,540,542,544,546,549],{"class":483,"line":541},2,[481,543,525],{"class":487},[481,545,529],{"class":528},[481,547,548],{"class":528}," install",[481,550,551],{"class":528}," kraft@kraft\n",[481,553,555,559],{"class":483,"line":554},3,[481,556,558],{"class":557},"s2Zo4","cd",[481,560,561],{"class":528}," ~\u002Fcode\u002Fmy-project\n",[481,563,565],{"class":483,"line":564},4,[481,566,567],{"class":487},"claude\n",[276,569,570],{},"Then, in the session:",[472,572,577],{"className":573,"code":575,"language":576,"meta":477},[574],"language-text","\u002Fkraft:onboard\n","text",[280,578,575],{"__ignoreMap":477},[276,580,581],{},"Follow what it asks. It connects the repo and makes sure Kraft knows how to set\nit up and run its tests, so your first work item doesn't stop on a wrong guess.",[276,583,584,585,587,588,305],{},"The plugin also registers Kraft's MCP server with Claude Code, so there is no\n",[280,586,391],{}," step on this path. For other agents, or to set it up without\nthe plugin, see ",[303,589,396],{"href":395},[509,591,593],{"id":592},"from-a-terminal","From a terminal",[276,595,596],{},"Without the plugin, register Kraft with Claude Code once, then connect the repo\nfrom inside it:",[472,598,600],{"className":474,"code":599,"language":476,"meta":477,"style":477},"kraft admin init   # once per machine; required without the plugin\ncd ~\u002Fcode\u002Fmy-project\nkraft repo connect\n",[280,601,602,617,623],{"__ignoreMap":477},[481,603,604,607,610,613],{"class":483,"line":484},[481,605,606],{"class":487},"kraft",[481,608,609],{"class":528}," admin",[481,611,612],{"class":528}," init",[481,614,616],{"class":615},"sHwdD","   # once per machine; required without the plugin\n",[481,618,619,621],{"class":483,"line":541},[481,620,558],{"class":557},[481,622,561],{"class":528},[481,624,625,627,630],{"class":483,"line":554},[481,626,606],{"class":487},[481,628,629],{"class":528}," repo",[481,631,632],{"class":528}," connect\n",[276,634,635,636,638,639,641,642,644,645,648,649,651,652,655,656,392,659,661],{},"Kraft reads the repo's files (a ",[280,637,311],{},", a ",[280,640,331],{},", a\n",[280,643,323],{},") to guess two commands: how to prepare a fresh checkout\n(",[280,646,647],{},"setup_command",") and how to run the tests (",[280,650,355],{},"). It prints the test\nand setup commands it found, and says so when it saved the repo disabled\nbecause it found no test command. Check both in Settings, then Repos (or in\n",[280,653,654],{},"~\u002F.kraft\u002Ftemplates\u002Frepos.yaml",") before you trust them. If the repo needs no\npreparation, set ",[280,657,658],{},"setup_command: \"\"",[303,660,146],{"href":147}," for every field.",[276,663,664],{},"Confirm the repo is connected:",[472,666,668],{"className":474,"code":667,"language":476,"meta":477,"style":477},"kraft repo list    # a * marks the repo you are in\n",[280,669,670],{"__ignoreMap":477},[481,671,672,674,676,679],{"class":483,"line":484},[481,673,606],{"class":487},[481,675,629],{"class":528},[481,677,678],{"class":528}," list",[481,680,681],{"class":615},"    # a * marks the repo you are in\n",[467,683,685],{"id":684},"_3-file-your-first-work-item","3. File your first work item",[276,687,688,689,691],{},"The ",[280,690,282],{}," chain has no gates, which makes it good for confirming the\npipes are connected:",[472,693,695],{"className":474,"code":694,"language":476,"meta":477,"style":477},"kraft item create \"fix the flaky import test\" --chain quick-task \\\n  --description \"It's the datetime import, not the fixture.\"\n",[280,696,697,727],{"__ignoreMap":477},[481,698,699,701,704,707,711,714,717,720,723],{"class":483,"line":484},[481,700,606],{"class":487},[481,702,703],{"class":528}," item",[481,705,706],{"class":528}," create",[481,708,710],{"class":709},"sMK4o"," \"",[481,712,713],{"class":528},"fix the flaky import test",[481,715,716],{"class":709},"\"",[481,718,719],{"class":528}," --chain",[481,721,722],{"class":528}," quick-task",[481,724,726],{"class":725},"sTEyZ"," \\\n",[481,728,729,732,734,737],{"class":483,"line":541},[481,730,731],{"class":528},"  --description",[481,733,710],{"class":709},[481,735,736],{"class":528},"It's the datetime import, not the fixture.",[481,738,739],{"class":709},"\"\n",[276,741,742,743,746],{},"It prints the new item. Copy its ",[280,744,745],{},"id",":",[472,748,751],{"className":749,"code":750,"language":576,"meta":477},[574],"id            9d0ab38ff3c9439b90506df0f6966660   \u003C- the ID\nstatus        paused\ntitle         fix the flaky import test\nbead_warning  bd is not installed: [Errno 2] No such file or directory: 'bd'\n",[280,752,750],{"__ignoreMap":477},[276,754,755,756,305],{},"You can list IDs again any time with ",[280,757,758],{},"kraft view list",[276,760,761,764,765,771],{},[280,762,763],{},"bead_warning: bd is not installed"," means Kraft could not file a matching\n",[303,766,770],{"href":767,"rel":768},"https:\u002F\u002Fgithub.com\u002Fgastownhall\u002Fbeads",[769],"nofollow","beads"," issue. Beads is optional; the work\nitem is filed and runs the same without it, so you can ignore the line.",[276,773,774,775,778,779,782,783,786,787,305],{},"The item lands ",[291,776,777],{},"paused",", because ",[280,780,781],{},"item create"," starts nothing unless you add\n",[280,784,785],{},"--autostart",". Nothing has spent a token yet. See ",[303,788,790],{"href":789},"\u002Fconcepts\u002Fvocabulary#work-item","Work item",[467,792,794],{"id":793},"_4-start-it-and-watch","4. Start it, and watch",[276,796,797,798,801],{},"Every command below takes the item's ID. Replace ",[280,799,800],{},"ID"," with the one you copied.\nYou can leave the ID off only when you run the command inside that item's\nworktree.",[472,803,805],{"className":474,"code":804,"language":476,"meta":477,"style":477},"kraft item resume ID   # the CLI twin of clicking Start on the board\nkraft view watch       # a live board, redrawn on every event\n",[280,806,807,822],{"__ignoreMap":477},[481,808,809,811,813,816,819],{"class":483,"line":484},[481,810,606],{"class":487},[481,812,703],{"class":528},[481,814,815],{"class":528}," resume",[481,817,818],{"class":528}," ID",[481,820,821],{"class":615},"   # the CLI twin of clicking Start on the board\n",[481,823,824,826,829,832],{"class":483,"line":541},[481,825,606],{"class":487},[481,827,828],{"class":528}," view",[481,830,831],{"class":528}," watch",[481,833,834],{"class":615},"       # a live board, redrawn on every event\n",[276,836,837],{},[838,839],"img",{"alt":840,"src":841},"The Kraft board: work items grouped by Needs you, Running, Not started, and Done","\u002Fassets\u002Fboard.png",[276,843,844,846,847,850,851,854,855,858,859,861,862,403,865,867,868,870],{},[280,845,282],{}," runs ",[280,848,849],{},"implementation",", then ",[280,852,853],{},"verify",", with no gate. If the agent's\nfix is good, the item reaches ",[291,856,857],{},"Done"," on its own. ",[280,860,853],{}," runs the repo's own\n",[280,863,864],{},"test_scopes",[280,866,355],{}," from ",[280,869,359],{},". If it fails, the item stops\nfor you with the failing scope named.",[276,872,873,874,305],{},"You know it worked when the board shows the item under ",[291,875,857],{},[467,877,879],{"id":878},"_5-where-is-my-change","5. Where is my change?",[276,881,882,884],{},[280,883,282],{}," opens no pull request: the change stays on the item's own branch,\nin its worktree. To see it:",[472,886,888],{"className":474,"code":887,"language":476,"meta":477,"style":477},"kraft view diff ID     # the change, against the base branch\nkraft repo path ID     # the worktree's path; cd \"$(kraft repo path ID)\" to go there\nkraft repo open ID     # open the worktree in your editor\n",[280,889,890,904,918],{"__ignoreMap":477},[481,891,892,894,896,899,901],{"class":483,"line":484},[481,893,606],{"class":487},[481,895,828],{"class":528},[481,897,898],{"class":528}," diff",[481,900,818],{"class":528},[481,902,903],{"class":615},"     # the change, against the base branch\n",[481,905,906,908,910,913,915],{"class":483,"line":541},[481,907,606],{"class":487},[481,909,629],{"class":528},[481,911,912],{"class":528}," path",[481,914,818],{"class":528},[481,916,917],{"class":615},"     # the worktree's path; cd \"$(kraft repo path ID)\" to go there\n",[481,919,920,922,924,927,929],{"class":483,"line":554},[481,921,606],{"class":487},[481,923,629],{"class":528},[481,925,926],{"class":528}," open",[481,928,818],{"class":528},[481,930,931],{"class":615},"     # open the worktree in your editor\n",[276,933,934,935,937],{},"Merge the branch yourself, or run the next piece of work on ",[280,936,286],{},", which\nopens and merges a pull request for you.",[467,939,941],{"id":940},"_6-try-the-real-chain-and-its-gates","6. Try the real chain, and its gates",[276,943,944,946,947,950,951,954,955,403,957,959,960,963,964,967],{},[280,945,286],{}," opens and merges a pull request, so check the forge first.\n",[280,948,949],{},"kraft admin doctor"," fails its ",[280,952,953],{},"forge"," row if ",[280,956,402],{},[280,958,406],{}," is missing, and\n",[280,961,962],{},"gh auth status"," (or ",[280,965,966],{},"glab auth status",") confirms you are logged in:",[472,969,971],{"className":474,"code":970,"language":476,"meta":477,"style":477},"kraft admin doctor\ngh auth status\n",[280,972,973,982],{"__ignoreMap":477},[481,974,975,977,979],{"class":483,"line":484},[481,976,606],{"class":487},[481,978,609],{"class":528},[481,980,981],{"class":528}," doctor\n",[481,983,984,986,989],{"class":483,"line":541},[481,985,402],{"class":487},[481,987,988],{"class":528}," auth",[481,990,991],{"class":528}," status\n",[276,993,994,996,997,1000],{},[280,995,286],{}," is the chain most work runs on, and the default for ",[280,998,999],{},"--chain",", so you\ncan leave the flag off:",[472,1002,1004],{"className":474,"code":1003,"language":476,"meta":477,"style":477},"kraft item create \"add a --dry-run flag to the sync command\"\nkraft item resume ID   # use the new item's ID, not the first one\n",[280,1005,1006,1021],{"__ignoreMap":477},[481,1007,1008,1010,1012,1014,1016,1019],{"class":483,"line":484},[481,1009,606],{"class":487},[481,1011,703],{"class":528},[481,1013,706],{"class":528},[481,1015,710],{"class":709},[481,1017,1018],{"class":528},"add a --dry-run flag to the sync command",[481,1020,739],{"class":709},[481,1022,1023,1025,1027,1029,1031],{"class":483,"line":541},[481,1024,606],{"class":487},[481,1026,703],{"class":528},[481,1028,815],{"class":528},[481,1030,818],{"class":528},[481,1032,1033],{"class":615},"   # use the new item's ID, not the first one\n",[276,1035,1036,1037,850,1040,850,1043,1046,1047,1051],{},"Before any code is written it stops at three gates, one after another:\n",[280,1038,1039],{},"spec_approval",[280,1041,1042],{},"plan_approval",[280,1044,1045],{},"chain_revision_approval",". The last\nis about the chain itself: an agent checks the approved spec and plan against\nthe nodes still to run and proposes changes to them, and when it proposes none,\nwhich is usual, the gate passes without asking you. Each gate shows up under\n",[1048,1049,1050],"em",{},"Needs you"," on the board:",[276,1053,1054],{},[838,1055],{"alt":1056,"src":1057},"A spec an agent wrote, waiting for your approval in the item's detail view","\u002Fassets\u002Fgate.png",[472,1059,1061],{"className":474,"code":1060,"language":476,"meta":477,"style":477},"kraft view artifact ID     # read the document the gate is about\nkraft item approve ID      # or Approve on the board\n",[280,1062,1063,1077],{"__ignoreMap":477},[481,1064,1065,1067,1069,1072,1074],{"class":483,"line":484},[481,1066,606],{"class":487},[481,1068,828],{"class":528},[481,1070,1071],{"class":528}," artifact",[481,1073,818],{"class":528},[481,1075,1076],{"class":615},"     # read the document the gate is about\n",[481,1078,1079,1081,1083,1086,1088],{"class":483,"line":541},[481,1080,606],{"class":487},[481,1082,703],{"class":528},[481,1084,1085],{"class":528}," approve",[481,1087,818],{"class":528},[481,1089,1090],{"class":615},"      # or Approve on the board\n",[276,1092,1093,1094,1097],{},"To send it back instead, run ",[280,1095,1096],{},"kraft item reject ID --note \"...\"",". The node that\nwrote the document runs again with your note.",[276,1099,1100,1101,1103,1104,1107],{},"You know it worked when, after your last approval, the item moves out of\n",[1048,1102,1050],{}," and into ",[1048,1105,1106],{},"Running",", and the board shows implementation started.",[467,1109,1111],{"id":1110},"_7-review-before-it-merges","7. Review before it merges",[276,1113,1114,1115,1118,1119,1122],{},"After implementation and verification, the item stops at ",[280,1116,1117],{},"local_review",", and\nlater at ",[280,1120,1121],{},"final_review",". Each comes with a diff to read first:",[472,1124,1126],{"className":474,"code":1125,"language":476,"meta":477,"style":477},"kraft view diff ID --stat   # how big it is\nkraft view diff ID          # the full diff\n",[280,1127,1128,1144],{"__ignoreMap":477},[481,1129,1130,1132,1134,1136,1138,1141],{"class":483,"line":484},[481,1131,606],{"class":487},[481,1133,828],{"class":528},[481,1135,898],{"class":528},[481,1137,818],{"class":528},[481,1139,1140],{"class":528}," --stat",[481,1142,1143],{"class":615},"   # how big it is\n",[481,1145,1146,1148,1150,1152,1154],{"class":483,"line":541},[481,1147,606],{"class":487},[481,1149,828],{"class":528},[481,1151,898],{"class":528},[481,1153,818],{"class":528},[481,1155,1156],{"class":615},"          # the full diff\n",[276,1158,1159,1160,1162,1163,1165],{},"Approve ",[280,1161,1117],{}," and Kraft opens a draft merge request and runs CI and\nautomated review on it. Approve ",[280,1164,1121],{}," and it marks the request ready,\nwaits for the merge request's external approval on your forge, then merges.",[472,1167,1169],{"className":474,"code":1168,"language":476,"meta":477,"style":477},"kraft item approve ID   # at each gate, once you have read the diff\nkraft view list         # shows the item's status\n",[280,1170,1171,1184],{"__ignoreMap":477},[481,1172,1173,1175,1177,1179,1181],{"class":483,"line":484},[481,1174,606],{"class":487},[481,1176,703],{"class":528},[481,1178,1085],{"class":528},[481,1180,818],{"class":528},[481,1182,1183],{"class":615},"   # at each gate, once you have read the diff\n",[481,1185,1186,1188,1190,1192],{"class":483,"line":541},[481,1187,606],{"class":487},[481,1189,828],{"class":528},[481,1191,678],{"class":528},[481,1193,1194],{"class":615},"         # shows the item's status\n",[276,1196,1197,1198,1201],{},"You know it worked when the item's status is ",[280,1199,1200],{},"completed"," and the merge request\nshows as merged on your forge.",[276,1203,1204,1205,305],{},"What each gate does, and how caps and waits bound the chain, is in\n",[303,1206,29],{"href":1207},"\u002Fconcepts\u002Fvocabulary#gate",[467,1209,1211],{"id":1210},"troubleshooting","Troubleshooting",[276,1213,1214,1217],{},[291,1215,1216],{},"An item stopped and you don't know why."," Start with the item, then its\nagent's log, then the install:",[472,1219,1221],{"className":474,"code":1220,"language":476,"meta":477,"style":477},"kraft view show ID     # status, the node it stopped at, and the reason\nkraft view logs ID     # the agent session's own log\nkraft admin doctor     # every install check at once\n",[280,1222,1223,1237,1251],{"__ignoreMap":477},[481,1224,1225,1227,1229,1232,1234],{"class":483,"line":484},[481,1226,606],{"class":487},[481,1228,828],{"class":528},[481,1230,1231],{"class":528}," show",[481,1233,818],{"class":528},[481,1235,1236],{"class":615},"     # status, the node it stopped at, and the reason\n",[481,1238,1239,1241,1243,1246,1248],{"class":483,"line":541},[481,1240,606],{"class":487},[481,1242,828],{"class":528},[481,1244,1245],{"class":528}," logs",[481,1247,818],{"class":528},[481,1249,1250],{"class":615},"     # the agent session's own log\n",[481,1252,1253,1255,1257,1260],{"class":483,"line":554},[481,1254,606],{"class":487},[481,1256,609],{"class":528},[481,1258,1259],{"class":528}," doctor",[481,1261,1262],{"class":615},"     # every install check at once\n",[276,1264,1265,1266,1269,1270,1272],{},"In Claude Code, ",[280,1267,1268],{},"\u002Fkraft:triage"," does this for you and offers to retry, raise a\ncap, or hand the item back to you. ",[303,1271,1211],{"href":26},"\nmaps every stop reason to its fix. The rest of this section covers what a first\nrun most often hits.",[276,1274,1275,1281,1282,1285,1286,1288,1289,1292,1293,1295,1296,1299],{},[291,1276,1277,1278,1280],{},"It stops at ",[280,1279,849],{}," having spent 0 tokens."," Nothing registers\nKraft's MCP server with Claude Code, so Kraft refused to launch the worker.\n",[280,1283,1284],{},"kraft view logs ID"," says so and names the fix: install the Kraft plugin, or\nrun ",[280,1287,391],{},". Then run ",[280,1290,1291],{},"kraft item retry ID",". ",[280,1294,949],{},"'s\n",[280,1297,1298],{},"mcp server"," row checks the same thing.",[276,1301,1302,437,1310,950,1312,1315,1316,1318,1319,1321,1322,1324,1325,305],{},[291,1303,1304,1306,1307,305],{},[280,1305,525],{}," is not on ",[280,1308,1309],{},"PATH",[280,1311,949],{},[280,1313,1314],{},"agent: claude","\nrow. The server looks the command up on its own ",[280,1317,1309],{},", which under a service\ncan differ from your shell's. Install Claude Code, make sure ",[280,1320,525],{}," runs from\nthe shell that starts ",[280,1323,606],{},", then restart it with ",[280,1326,1327],{},"kraft admin restart",[276,1329,1330,1333,1334,1337,1338,403,1341,1344,1345,1347,1348,305],{},[291,1331,1332],{},"It stops at a forge node: no forge is recorded."," The repo had no GitHub or\nGitLab ",[280,1335,1336],{},"origin"," when you connected it. Set ",[280,1339,1340],{},"forge: github",[280,1342,1343],{},"forge: gitlab"," on\nit in Settings, then Repos (or in ",[280,1346,359],{},"), then ",[280,1349,1291],{},[276,1351,1352,1358,1359,305],{},[291,1353,1354,1355,1357],{},"It waits on \"no checks yet\", or ",[280,1356,440],{}," keeps waiting."," See\n",[303,1360,1362],{"href":1361},"\u002Fget-started\u002Ftroubleshooting#waiting-on-ci-or-a-review","Waiting on CI or a review",[276,1364,1365,1368,1369,1372,1373,1376,1377,1380,1381,1383,1384,305],{},[291,1366,1367],{},"It stops with \"budget cap reached\"."," The item, or the day's work across\nevery item, spent its budget: ",[280,1370,1371],{},"budget.work_item_usd"," and ",[280,1374,1375],{},"budget.daily_usd"," in\n",[280,1378,1379],{},"policy.yaml",", $10 and $50 by default. Raise the cap, then\n",[280,1382,1291],{},". See ",[303,1385,44],{"href":45},[276,1387,1388,1394,1395,1397,1398,1400,1401,1403,1404,305],{},[291,1389,1390,1391,1393],{},"The first item stops at ",[280,1392,853],{}," with a config error."," The repo declares\nneither ",[280,1396,864],{}," nor ",[280,1399,355],{}," in ",[280,1402,359],{},", and Kraft will not\nguess a test command. Set one, then run ",[280,1405,1291],{},[276,1407,1408,1411,1412,1414,1415,1417,1418,305],{},[291,1409,1410],{},"The first item stops before it starts."," A repo with no ",[280,1413,647],{}," stops\nits first work item rather than guessing what to run in a fresh worktree. Set it\nin ",[280,1416,359],{},", then run ",[280,1419,1291],{},[467,1421,1423],{"id":1422},"next-run-it-as-a-service","Next: run it as a service",[276,1425,1426,1428],{},[280,1427,606],{}," in a terminal stops when you close it. To keep the server running in\nthe background and start it at login:",[472,1430,1432],{"className":474,"code":1431,"language":476,"meta":477,"style":477},"kraft admin install-service\n",[280,1433,1434],{"__ignoreMap":477},[481,1435,1436,1438,1440],{"class":483,"line":484},[481,1437,606],{"class":487},[481,1439,609],{"class":528},[481,1441,1442],{"class":528}," install-service\n",[467,1444,1446],{"id":1445},"where-to-go-from-here","Where to go from here",[296,1448,1449,1456,1463,1481,1488],{},[299,1450,1451,1455],{},[291,1452,1453],{},[303,1454,29],{"href":37},": the vocabulary this walkthrough used: work\nitem, chain, node, task, gate, cap.",[299,1457,1458,1462],{},[291,1459,1460],{},[303,1461,40],{"href":41},": what happened\nbetween filing and merge, and every status an item can hold.",[299,1464,1465,1469,1470,1473,1474,371,1476,371,1478,305],{},[291,1466,1467],{},[303,1468,140],{"href":141},": every field in ",[280,1471,1472],{},"library.yaml",",\n",[280,1475,359],{},[280,1477,1379],{},[280,1479,1480],{},"access.yaml",[299,1482,1483,1487],{},[291,1484,1485],{},[303,1486,465],{"href":60},": doing all of the above\nfrom inside a coding-agent session instead of this shell.",[299,1489,1490,1494],{},[291,1491,1492],{},[303,1493,67],{"href":68},": approving a gate from your\nphone.",[1496,1497,1498],"style",{},"html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html pre.shiki code .s2Zo4, html code.shiki .s2Zo4{--shiki-light:#6182B8;--shiki-default:#82AAFF;--shiki-dark:#82AAFF}html pre.shiki code .sHwdD, html code.shiki .sHwdD{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}",{"title":477,"searchDepth":541,"depth":541,"links":1500},[1501,1502,1506,1507,1508,1509,1510,1511,1512,1513],{"id":469,"depth":541,"text":470},{"id":503,"depth":541,"text":504,"children":1503},[1504,1505],{"id":511,"depth":554,"text":512},{"id":592,"depth":554,"text":593},{"id":684,"depth":541,"text":685},{"id":793,"depth":541,"text":794},{"id":878,"depth":541,"text":879},{"id":940,"depth":541,"text":941},{"id":1110,"depth":541,"text":1111},{"id":1210,"depth":541,"text":1211},{"id":1422,"depth":541,"text":1423},{"id":1445,"depth":541,"text":1446},"Start Kraft, connect a repo, run a work item end to end, and approve its gates.","md",null,{},true,{"title":21,"description":1514},"uK4FGXUkp0oL0nNm9KDya10FQfNCxJc6PmiQbPQvUVo",[1522,1524],{"title":17,"path":18,"stem":19,"description":1523,"children":-1},"Install, verify, upgrade, and uninstall Kraft with uv, Homebrew, the install script, or from source.",{"title":25,"path":26,"stem":27,"description":1525,"children":-1},"Why a work item stopped and how to get it going again, common doctor failures, known issues, and common questions.",1790824540605]