git:20260923.eb1afa7 to git:20261004.8097c6f

10 added, 7 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.

+ description: "Files work with Kraft as a paused work item, with any agreed spec and plan attached. Use when work settled in this session should be handed to Kraft instead of done here, or the task is too big for this session. It connects a repo Kraft has not seen; verifying that repo's test and setup commands belongs to kraft:onboard, the inline-or-Kraft decision to kraft:prepare."

---

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://itsomidkarami.github.io/kraft/get-started/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.

+ Idempotent, so call it every time rather than checking first. If it newly

+ connected the repo, say so and run `kraft:onboard` before the item is

+ started: the test and setup commands it proposed are saved unconfirmed, and

+ an item run against wrong ones stops.

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 the same bead (an issue in the optional beads tracker): tell the user, and don't file a third.

+ implements the same bead (an issue in the optional beads tracker): tell the

+ user, and don't file a third. A `repo_warning` in the answer means the repo

+ will stop the item once started: pass it on to the user.

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

+ The chain's verification node already runs the suite after implementation,

+ 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.

## Confirm it landed

Run `kraft view list --status=paused` (or `get_work_item()` on the new id) and

check the item is there with the title you gave and, if you attached documents,

that `kraft view docs ID` lists them.