flake-update-20260505

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

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

Workflow

  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.

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