Hand off context to any AI coding agent

version
1.0.0
GitHub stars
146

Install

/plugin install handoff@handoff-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add willseltzer/claude-handoff.

Contents

Discovered from source

Skills 1

Handoff Detection

On Session Start

Check if HANDOFF.md exists in the working directory. If found:

  1. Read it silently
  2. Tell the user: "Found a handoff from a previous session: [title]. [1-sentence goal]. Resume from here?"
  3. If they agree, follow /handoff:resume flow

Trigger Words

Activate when user says: "handoff", "hand off", "pass this to", "continue later", "pick up where", "transfer context", "save state", "resume", "take over"

Creating vs Resuming

  • User wants to create: They're wrapping up or switching agents → use /handoff:create
  • User wants to resume: They're starting fresh with existing handoff → use /handoff:resume

Proactive Suggestions

Consider suggesting a handoff when:

  • User says "I need to go" or "let's stop here"
  • A significant milestone is reached
  • You've been working for a long time with lots of context

Say: "Want me to create a handoff so you (or another agent) can continue later?"

Commands

CommandUse When
/handoff:createFull handoff with all context
/handoff:quickMinimal handoff, just essentials
/handoff:resumeContinue from existing handoff

Commands 3

Create a HANDOFF.md file that enables ANY AI coding agent to continue this work seamlessly.

Gather Context First

Run these commands to understand current state:

  • git status - see uncommitted changes
  • git diff --stat - see what files changed
  • git log --oneline -5 - recent commits from this session

Review the conversation history to extract:

  • The original task/goal
  • What was completed
  • What was tried and didn't work (critical - saves hours)
  • Key decisions and their rationale
  • User preferences expressed during the session
  • Error messages encountered and how they were resolved

Write HANDOFF.md

Use this structure (omit empty sections, but NEVER omit Failed Approaches if any exist):

# Handoff: [Brief Task Title]

**Generated**: [date/time]
**Branch**: [git branch]
**Status**: [In Progress / Blocked / Ready for Review]

## Goal

[1-2 sentences: what the user wants to achieve]

## Completed

- [x] [Specific completed item]
- [x] [Another completed item]

## Not Yet Done

- [ ] [Remaining task - be specific]
- [ ] [Another remaining task]

## Failed Approaches (Don't Repeat These)

[IMPORTANT: Always include this if anything was tried and abandoned. Be specific:]
- What was attempted
- Why it failed (error message, performance issue, design flaw)
- Why the current approach is better

Example:
> Tried using passport.js for OAuth but it conflicted with existing Express middleware (req.user was undefined). Switched to oauth4webapi which works directly with fetch.

## Key Decisions

| Decision | Rationale |
|----------|-----------|
| [Choice made] | [Why this approach] |

## Current State

**Working**: [What's functional right now]

**Broken**: [What's not working, error messages if relevant]

**Uncommitted Changes**: [Summary of unstaged/staged changes]

## Files to Know

| File | Why It Matters |
|------|----------------|
| `path/to/key/file.ts` | [Brief description] |

## Code Context

[Include actual code the next agent needs. Don't describe - show:]

**Key interfaces/signatures** (so the agent knows how to call/modify them):
```typescript
// Example: hook signature
function useAuth(): { user: User | null; login: (creds: Credentials) => Promise<void> }

API request/response shapes (if backend work):

// POST /api/resource - example response
{ "id": 123, "status": "created" }

Non-obvious logic (anything tricky that isn't self-documenting)

Resume Instructions

[Be extremely specific. Not "test the feature" but step-by-step with expected outcomes:]

  1. [Setup step if needed - migrations, env vars, etc.]
  2. [First action with exact command or file to edit]
  3. [Verification step with expected outcome]
    • Expected: [what should happen]
    • If it fails: [what to check]

Example:

  1. Run alembic upgrade head to apply migrations
  2. Start server: ./start.sh
  3. Test login flow: POST to /api/login with test@example.com / testpass
    • Expected: 200 response with { token: "..." }
    • If 401: Check user exists in DB

Setup Required

[Only if there are prerequisites the next agent needs:]

  • Environment variables: API_KEY, DATABASE_URL
  • Test accounts: test@example.com / password123
  • Required services: Redis must be running on :6379

Edge Cases & Error Handling

[Document known edge cases and how they're handled - or should be:]

  • What happens if [X fails]? → [current behavior or "not handled yet"]
  • What if user does [Y]? → [expected behavior]

Warnings

[Gotchas, things that look wrong but are intentional, or traps to avoid]


## Guidelines

- **Failed approaches are mandatory** - if anything was tried and abandoned, document it
- **Show code, don't describe** - include actual signatures, interfaces, response shapes
- **Testing steps need expected outcomes** - "verify it works" is useless
- Be brutally concise - every word should earn its place
- Include error messages verbatim when relevant
- Use file paths relative to repo root
- If there's a blocker, say so prominently
- Omit empty sections (except Failed Approaches - say "None" if truly nothing failed)

Save to `HANDOFF.md` in the working directory. If `$ARGUMENTS` specifies a path, use that instead.

Create a minimal HANDOFF.md with only the essentials. Use this for simple tasks or quick context transfers.

Output this exact format (fill in the brackets):

# Handoff: [task in 5 words or less]

**Goal**: [one sentence]

**Done**: [comma-separated list of completed items, or "Nothing yet"]

**Next**: [the single most important next step]

**Watch out**: [one key warning, or "Nothing special"]

That's it. No extras. Save to HANDOFF.md or the path in $ARGUMENTS.

Resume work from a handoff created by another AI agent.

1. Find and Read the Handoff

Look for the handoff document:

  • If $ARGUMENTS is provided, read that path
  • Otherwise, check for HANDOFF.md in the current directory
  • If not found, ask the user for the path

Read the entire handoff document carefully.

2. Verify State Hasn't Drifted

Run git status and git log --oneline -3 to check:

  • Is the branch the same as documented?
  • Have there been commits since the handoff was created?
  • Are there uncommitted changes not mentioned in the handoff?

If state has drifted significantly, warn the user:

"The repo has changed since this handoff was created. [describe changes]. Should I proceed with the handoff context anyway, or would you like to describe what changed?"

3. Summarize to the User

Give a brief summary (not the whole document):

Resuming from handoff: [title]

Goal: [1 sentence]
Status: [X of Y tasks complete]
Next: [First item from Resume Instructions]

Ready to continue?

4. Heed the Warnings

Pay special attention to:

  • Failed Approaches - Don't repeat these mistakes
  • Warnings - Respect gotchas from the previous agent
  • Key Decisions - Follow established patterns unless user asks to change

5. Continue the Work

Start with the first item in "Resume Instructions" unless the user redirects.

If the handoff is unclear on something critical, ask the user rather than guessing.

Sponsors

Details

Marketplace
willseltzer/claude-handoff
Source
willseltzer/claude-handoff
Category
Community