main

name: handoff description: Write or update a handoff document so another agent or engineer can continue the work with fresh context. USE WHEN user says ‘handoff’, ‘write handoff’, ‘create handoff’, ‘pass this off’, or wants to capture context for cross-agent or cross-session continuity.

Handoff

Capture the current goal, progress, context, and next steps in a concise handoff document. Works for cross-agent handoffs (pi → claude, pi → cursor), cross-session continuity, and human-to-human knowledge transfer.

Quick Start

# Create a new handoff
python3 "<path-to-skill>/scripts/create_handoff.py" --repo "." --name "<descriptive-slug>"
# Add --json for structured output

# List active handoffs for current repo
python3 "<path-to-skill>/scripts/create_handoff.py" --repo "." --list

# Pick up a handoff (reads content, then archives it)
python3 "<path-to-skill>/scripts/create_handoff.py" --repo "." --pickup "<slug>"

Workflow

Writing a handoff

  1. Inspect current git context and choose a short kebab-case slug describing the work
  2. Run the helper script to scaffold the handoff file with git context
  3. If an existing handoff exists for this slug, read it before updating
  4. Write or update the handoff using script output and current session knowledge
  5. Tell the user where the handoff file lives

Use --new-copy-if-exists to create a fresh copy even when the slug already exists.

Picking up a handoff

When resuming work (e.g. user says “check handoffs”):

  1. Run --list to show active handoffs for the repo
  2. Read and present the relevant handoff(s) to the user
  3. Run --pickup <slug> to archive the handoff — it has served its purpose
  4. The archived file moves to .archive/ under the repo’s handoff directory

Archived handoffs can still be found in ~/.local/share/ai/handoffs/<repo>/.archive/ if needed later.

Handoff Contents

Include these sections:

Goal

One-sentence description of what the work aims to achieve.

Current Progress

What has been completed, with specific file paths and commit references.

What Worked

Approaches, tools, or patterns that proved successful.

What Didn’t Work

Dead ends, failed approaches, and why they didn’t work. This saves the next agent from repeating mistakes.

Next Steps

Concrete, ordered list of what to do next. Be specific — file paths, commands, expected outcomes.

Notes for Next Agent

Context that doesn’t fit elsewhere: environment quirks, gotchas, related issues, relevant documentation.

Storage

Handoffs are stored in ~/.local/share/ai/handoffs/<repo-name>/<slug>.md.

The script auto-detects the repository name from git remote and creates the directory structure.

Integration

  • Works alongside save_session_to_history — handoff focuses on continuing work, session summary focuses on documenting what was done
  • The handoff document can be included in a new session’s context to resume work
  • Compatible with any AI coding tool that can read markdown files
  • CORE: Session saves via save_session_to_history (documenting past work)
  • WritingPlans: For creating implementation plans (forward-looking)

Examples

Example 1: Write a handoff

User: "Write a handoff for this work"
→ Captures current state, decisions made, open items
→ Writes structured handoff doc for next session/engineer