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