claude-handoff-kit
A small Harness Engineering kit: a set of slash commands that coordinate a
planning agent (Opus) and an implementing agent (Codex, or a fresh
Claude session) through file-based handoffs under docs/handoff/<slug>/.
The hard part of long-running agentic work isn't writing code — it's context
that rots. A plan made at token 5k is a blurry memory by token 150k, and handing
work to another agent means re-deriving everything from scratch. This kit turns the
handoff into an explicit, on-disk contract: the planner writes the spec once, and
any implementer — even one that has never seen the conversation — reads the same
files and re-derives the truth from the code.
This README is usage-first: install it, then learn the cycle by running it.
Install
Pick one path — both end the same way (a /handoff-init to seed the contract).
Claude Code (plugin — zero files copied)
The repo is its own marketplace and its own plugin. From inside a session:
/plugin marketplace add Martin-Ferreira-O/claude-handoff-kit
/plugin install handoff-kit@claude-handoff-kit
/handoff-init
Or from the terminal (for scripting/CI):
claude plugin marketplace add Martin-Ferreira-O/claude-handoff-kit
claude plugin install handoff-kit@claude-handoff-kit
handoff-kit@claude-handoff-kit reads as <plugin>@<marketplace>. After installing,
the /plan · /clarify · /resume · /implement · /dispatch · /archive · /handoff-init
commands are available with no files copied into your project.
Codex / any agent (script — tool-agnostic)
curl -fsSL https://raw.githubusercontent.com/Martin-Ferreira-O/claude-handoff-kit/main/install.sh | sh
# or, from a clone:
./install.sh --target /path/to/project --with-hooks
The script copies .claude/commands/ (and, with --with-hooks, the enforcement
hooks) into the target, then seeds the contract. Flags: --target <dir>,
--with-hooks, --with-django, --force. It never clobbers files without
--force.
Then: /handoff-init (once per project)
/handoff-init
Seeds the shared contract into the repo as real files: AGENTS.md (the contract
Codex reads too), docs/handoff/INDEX.md (the registry), and optionally a CLAUDE.md
workflow block. It's idempotent — re-run it any time to refresh an updated
contract.
Why /handoff-init and not the plugin alone? Claude Code does not load a
plugin's AGENTS.md/CLAUDE.md as project context — plugins contribute commands,
hooks, and skills. The contract has to land as a real file so Codex and the planner
can read it; that's what the init step (and the script) do.
How to use it
The cycle
/plan → /clarify → (/resume) → /implement → /code-review
The arrows are a recommended flow, not technical dependencies — every command
re-derives its own context from the on-disk package, so you can enter at any point
and skip the steps you don't need. (/code-review is Claude Code's built-in review
skill; the kit's /implement invokes a review gate for you, so it's listed here only
to show where review sits.)
A typical run
# 1. Plan — Opus creates the task branch, drafts the spec, self-critiques,
# scores each task, and writes the whole handoff package to disk.
/plan add CSV export to the reports API
# 2. (optional) Clarify the hard edges — answers fold straight into PLAN.md.
/clarify add-csv-export
# 3. (optional) Read-only briefing before executing — rebuilds context and stops.
/resume add-csv-export
# 4. Implement — executes PLAN.md step by step, one atomic commit per verified
# step, then runs a fresh-context review gate against the plan.
/implement add-csv-export
What each step actually does:
