Handoff

---
name: handoff
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://kraft-sdlc.dev/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. 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. 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 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.