Skip to main content

Harness Handoffs

A KBD phase can move between harnesses mid-flight: planned in Claude Code, executed in Kimi Code, reviewed in Codex. /kbd-handoff prepares that move. It writes one packet the operator pastes into the receiving harness.

KBD has no writer lease. Each prometheus kbd command is serialized by the append-only journal lock and validated against the expected revision, so a handoff transfers no ownership. The sending harness stops issuing commands; the receiving harness verifies state and continues.

Run it​

timeout 120 ~/.claude/skills/kbd-handoff/kbd-handoff.sh --to kimi-code </dev/null
timeout 120 ~/.claude/skills/kbd-handoff/kbd-handoff.sh --to codex --dry-run </dev/null

--to is required and must name a supported harness: claude-code, codex, kimi-code or opencode (aliases claude, kimi); anything else exits 2. --phase selects a phase other than the active one, and --repo adds a repository (for example a fork) to the report.

What it refuses​

It exits 1 on a half-closed boundary in prometheus kbd status --json: an open task obligation, or a change or phase obligation the runtime marks complete or does not know. Repair each one, then retry:

prometheus kbd guard evaluate --boundary change --edge after \
--subject <change> --json --repair-projections

Obligations on the active phase path, and on the active change while it is not complete, are expected and ignored. A change or phase outside the active position that was started and not finished is reported as carried work. A missing phase or phase directory also exits 1.

A dirty or unpushed worktree, a broken installed skill, or a missing native role definition produces a warning recorded in the packet, not a refusal.

What it writes​

.kbd-orchestrator/phases/<phase>/harness-handoffs/<harness>-<UTC>.md
.kbd-orchestrator/phases/<phase>/harness-handoffs/<harness>-<UTC>.json

Stage handoffs live in handoffs/ under a different schema; harness handoffs never touch them. The JSON sidecar follows references/schemas/harness-handoff.schema.json in the orchestrator skill.

The packet contains the position (phase, stage, implementation N of T, next change and task), repository branches with clean and pushed state, files to read in order, the plan's operator gates and decisions, task execution rules, a never-do list quoted from the project's AGENTS.md, open prerequisites, and the exact start prompt for the receiving harness.

The skill is read-only on KBD state. It never edits progress.json, the waypoint, position files or task checkboxes.

Broken installed skills​

The handoff checks every kbd-* entry in the target harness's skills directory. A symlink that points at a removed path, such as the kbd-handoff link left from the former lease skill, is reported with its target. Reinstall the pack to repair it:

./install.sh