handoff · diff
git:20260918.d7ddcd9 to git:20260922.fcebf63
7 added, 0 removed. Audit A to A.
---
name: handoff
description: Use when work agreed in this session should be handed to Kraft instead of
done here - after a spec and plan are settled, when the task is too big for this
session, or when the current repo needs connecting to Kraft first.
---
Kraft's tools come from the `kraft` MCP server. If `kraft` is not on PATH, this
plugin has been installed without the program it drives: say so and point at
https://github.com/itsOmidKarami/kraft#install rather than reporting a
connection error.
# Handing work to Kraft
Kraft runs semi-autonomous work items as chains, with human gates. Hand work off
rather than doing it inline when it is large enough to want that structure.
1. `ensure_repo()` - connects the current repo if Kraft has not seen it.
Idempotent, so call it every time rather than checking first.
2. `create_work_item(title, description=...)` - files the work. The title is a
label; the description is the brief, and it is what the spec node writes its
design from. Put the intent in the description rather than packing it into
the title.
**`create_work_item` does not start anything.** The item lands paused and a
person starts it from the board. When you report back, say the work is *filed*,
not that it is underway - telling someone their work is running when nothing is
running is the one failure this whole surface is built to avoid.
## When the spec and plan already exist
If documents were written in this session or already live in the repo, attach
them at intake instead of letting Kraft re-run those phases:
create_work_item(title, description=..., attachments=[
{"kind": "spec", "path": ".engineering/specs/x.md"},
{"kind": "plan", "path": ".engineering/plans/x.md"},
])
Kind is `spec` or `plan`, at most one of each. A path is resolved against the
repo and against the working tree you are standing in, so a document written in
a worktree can be attached exactly as you wrote it — relative to that tree, or
absolute.
Attaching a spec or plan trims the node whose gate it satisfies, so the person
is not asked to re-approve what they just agreed with you, and the implementing
agent is told to follow the documents rather than guess.
+ Kraft copies an attached document at intake, so editing your file afterwards
+ changes nothing. If the spec or plan changes before the item starts, revise it
+ in place with `set_attachments(spec=..., work_item_id=...)` (or `kraft item
+ set-attachments`) instead of filing the item again. If `create_work_item`
+ answers with a `duplicate_warning`, an open item already has that title or
+ implements that bead: tell the user, and don't file a third.
+
Before attaching a plan, skim it for a full-test-suite step (e.g. "run the
full test suite" / "run all tests" as a task, not a task's own targeted test).
The chain's `verify` node already runs the suite after every task with its own
fix loop, so a plan step doing the same is redundant. If you see one, mention
to the user that it's not advised and offer to strip it before attaching.