Handoff

Handoff

You are invoked via /handoff. Your job is to capture the current session state into HANDOFF.md so the next session can pick up without losing any context.

Pass --team to produce a richer handoff suitable for sharing with teammates.

Step 1 — Gather Git Context

Run the following to understand the actual state of the working tree:

# Current branch and latest commit
git branch --show-current 2>/dev/null || echo "(not a git repo)"
git log -1 --format="%h %s" 2>/dev/null || true

# What changed since the last commit (staged + unstaged)
git diff --name-only HEAD 2>/dev/null || true
git status --short 2>/dev/null || true

# Untracked files
git ls-files --others --exclude-standard 2>/dev/null || true

Use the output to build the Files Changed section. Do not rely on conversation memory alone — git is the source of truth.

Step 2 — Extract Session Context from Conversation

From the conversation history, extract:

• Goal — what the user set out to accomplish (first message / stated intent)
• Current State — where things stand now (what's done, what's in progress, blockers)
• Progress — rough percentage if inferable
• Key Decisions — any architectural, design, or approach decisions made this session (even if not reflected in code yet)
• Failed Attempts — approaches tried and abandoned, with reasons
• Open Questions — unresolved choices or unknowns the next session should be aware of
• Next Step — the single most important thing to do next, specific enough to act on immediately

Step 3 — Check for an Existing Handoff

ls -la HANDOFF.md 2>/dev/null || echo "none"
ls -la handoff-archive/ 2>/dev/null | head -5 || echo "no archive"

Step 4 — Archive the Previous Handoff (if it exists)

if [ -f HANDOFF.md ]; then
  mkdir -p handoff-archive
  ts=$(date +"%Y%m%dT%H%M%S")
  cp HANDOFF.md "handoff-archive/HANDOFF-${ts}.md"
fi

Step 5 — Write HANDOFF.md

Create HANDOFF.md in the project root using this template:

# Handoff — [Date Time]

## Goal
[One or two sentences. What are we building or fixing, and why does it matter?]

## Current State

**Status**: [In Progress | Blocked | Ready for Review | Complete]
**Progress**: [X% — brief explanation]

[Two to four sentences describing where the work stands. What's done, what's half-done, what's untouched.]

## Branch & Commits

**Branch**: `[branch name]`
**Latest commit**: `[short hash] [subject]`

## Files in Flight

Files that are modified but not yet in a committed, stable state:

| File | Status | Notes |
|------|--------|-------|
| `path/to/file.ts` | modified | [what's incomplete or needs attention] |
| `path/to/new-file.py` | new | [purpose, current state] |

## Changed This Session

All files touched (from `git diff --name-only HEAD` + `git status`):

- `path/to/file.ts` — [one-line description of what changed]
- `path/to/file.py` — [one-line description]

New dependencies or config changes:
- [package/config change, or "None"]

## Key Decisions

Decisions made this session that affect future work:

- **[Decision area]**: [What was decided and why. Include tradeoffs if relevant.]
- [Or "No significant decisions this session"]

## Failed Attempts

Approaches tried that didn't work — read these before trying a new approach:

### [Approach Name]
**What we tried**: [Brief description]
**Why it failed**: [Root cause or error]
**Lesson**: [What to avoid or do differently]

[Or "None this session"]

## Open Questions

Unresolved choices the next session needs to address:

- [ ] [Question or decision that needs input]
- [ ] [Dependency or prerequisite that must be resolved first]

[Or "None — clear to proceed"]

## Next Step

**Do this first**: [Specific, actionable instruction. One thing, not a list.]

**Context**:
- [Any background needed to start]
- [Relevant file to read first]
- [Command to run]

**Done when**: [What success looks like for this next step]

---
*Generated: [ISO 8601 timestamp]*
*Session duration: [Approximate — e.g. "~45 min"]*

Step 6 — .gitignore Check

if [ -f .gitignore ]; then
  grep -q "HANDOFF.md" .gitignore && echo "already ignored" || echo "not ignored"
fi

If HANDOFF.md is not in .gitignore, ask the user:

> HANDOFF.md contains personal session notes. Add it to .gitignore? (yes / no / team — "team" keeps it tracked for shared handoffs)

If they say yes, append:

# Session handoff (personal notes — not for commit)
HANDOFF.md
handoff-archive/

If they say team, append only:

# Archive old handoffs but keep the current one tracked
handoff-archive/

If no, do nothing.

Step 7 — Confirm

Show a summary to the user:

Handoff saved: HANDOFF.md

  Goal:     [Brief goal]
  Status:   [Status]
  Branch:   [branch name]
  Next:     [Next step, one line]

Start your next session and I'll pick this up automatically.

---

Handling Edge Cases

No git repo: Skip git steps entirely. Note (no git) in the Branch section.

Nothing done this session: Write the handoff with current state as-is. Note "No changes made this session." in Current State.

Blocked: Lead the Current State with BLOCKED: and make the Next Step "Unblock by: [specific action]".

Passing --team: Expand the Key Decisions and Open Questions sections. Add a For Reviewers section with context about the approach chosen and what review is needed.

---

Important Notes

• Do not hallucinate file paths — only list files that appear in git status or that you created/edited in this conversation.
• Keep Next Step singular. A list of next steps is a todo list, not a handoff — it creates decision fatigue at session start.
• Be honest about failed attempts. This section saves the next session from repeating wasted work.
• Timestamps in ISO 8601 format: 2024-01-15T14:30:00+05:30 (include local offset).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thatcatfromspace
• Source: thatcatfromspace/claude-handoff-skill
• License: MIT

Install and usage instructions live in the source repository linked above.