handoff— agent skill

Generate a comprehensive handoff document capturing the current state of work for seamless continuation by another agent or developer.

Workflow

Step 1: Gather Context

Run these commands in parallel to understand the current state:

• git status — see all tracked/untracked files and staging state
• git diff — see unstaged changes
• git log --oneline -10 — recent commits to understand work trajectory
• git branch --show-current — current branch name
• git remote get-url origin — repository name (if available)

Also check for active todos in the todo system.

Step 2: Confirm Save Location

1. List all folders in .specs/
2. Match the current branch name, modified files, or recent commit messages to spec folder names
3. Use AskUserQuestion to confirm the save location with the user:

• If a likely match is found, suggest it as the recommended option
• Always include other spec folders as alternatives
• Always allow the user to specify a custom path

1. Only proceed after the user confirms the location

Step 3: Analyze Work State

1. Work Completed — analyze recent git commits, review completed todos, identify patterns in changes made
2. Work In Progress — active todo items, uncommitted changes, files currently being modified
3. Work Remaining — pending todo items, blockers, dependencies, priorities
4. Context — branch strategy, important decisions, known issues, relevant file paths with line numbers

Step 4: Write the Handoff Document

Save the file as handoff--{YYYY-MM-DD-HH-mm}--{brief-work-summary}.md in the confirmed location.

• Use date +"%Y-%m-%d-%H-%M" to get the correct local timestamp
• {brief-work-summary} is a short kebab-case description of the work (e.g., add-cart-api, fix-auth-redirect, refactor-review-section)

Use this structure:

# Handoff Context - {Date Time}

## Project
- Repository: {repo name if available}
- Branch: {current branch}
- Spec: {spec folder path if found}
- Last Updated: {timestamp}

## Current Status

### What's Been Done
{List completed work, recent commits, changes made}

### What's In Progress
{Current todo items, ongoing work}

### What's Next
{Pending tasks, blockers, priorities}

## Technical Context

### Modified Files
{List files changed with brief description}

### Key Decisions
{Important architectural or implementation decisions}

### Known Issues
{Bugs, blockers, or things to watch out for}

## Dependencies & Prerequisites
{External dependencies, required setup, environment notes}

## Additional Notes
{Any other relevant context for continuation}

Step 5: Report

After saving, display:

• The full file path where the handoff was saved
• A brief summary of the current state

User Arguments

$ARGUMENTS

Important Notes

• Be concise but comprehensive — focus on actionable information
• Include specific file paths with line numbers where relevant
• Do NOT commit the handoff file automatically
• If the user provided notes via arguments, include them in the "Additional Notes" section