Skip to content

README.md

Latest commit

 

History

History
72 lines (47 loc) · 2.8 KB

README.md

File metadata and controls

72 lines (47 loc) · 2.8 KB
Raw

handoff Slash Command

Generate a structured work handoff for the next coding agent picking up your task — Codex, Cursor, another Claude Code session, or a human.

Why

When you stop working on a task mid-stream and need someone (or some other agent) to continue, the usual options leak signal: a quick paragraph misses decisions, dumping the full chat history is noisy and overflows context. This command produces an 8-section structured brief that captures goal, decisions, dead-ends, and open work in one paste-able chunk.

Output Format

The command always produces these 8 sections, in order:

  1. Goal — what the task is and why
  2. Current State — what's done, what's working
  3. Decisions Made — key choices and why, including rejected alternatives
  4. Failed Approaches — what was tried that didn't work, so the next agent doesn't repeat
  5. Evidence — test output, commits, repro steps
  6. Open Questions — pending decisions
  7. Next Steps — what's left (described as "X is not yet done", not "do X")
  8. Relevant Files — paths + line numbers to read first

No preamble, no closing remarks — output is paste-ready.

Install

User-level (recommended)

Available in all Claude Code projects:

mkdir -p ~/.claude/commands
cp commands/handoff/handoff.md ~/.claude/commands/handoff.md

Project-level

Only in the current project:

mkdir -p .claude/commands
cp commands/handoff/handoff.md .claude/commands/handoff.md

Restart Claude Code to pick up the new command.

Usage

In a Claude Code session:

/handoff

Or with an optional focus hint:

/handoff focus on the auth refactor in src/auth/

Then copy the output and paste it into the next agent (Codex, another session, etc.) as the first message.

Cross-Platform Notes

  • Claude Code: native slash command support; install as above
  • Codex / Cursor / Windsurf: no native slash command for this. Typically you receive a handoff in these tools rather than generate one. If you do want to generate from there, ask the agent directly: "produce a handoff with these 8 sections: Goal / Current State / Decisions Made / Failed Approaches / Evidence / Open Questions / Next Steps / Relevant Files"

Design Notes

  • One-shot, not chained: each handoff is a complete snapshot. No seq-1 / seq-2 references to prior handoffs — keeps the surface small
  • No file output: output goes to chat. The user copies it (or pipes to /copy). No .handoffs/ directory, no git noise
  • Tone is left to the generating agent: section headings are fixed, but writing style is not enforced — keeps the prompt short
  • Receiver protocol is not embedded: cross-tool, the receiver may be Codex or a human. The 8 sections are self-explanatory enough not to need a "how to read this" preamble