Summarize the current coding session into a handoff markdown file for another agent, with precise code references.
Create a session handoff summary for another coding agent. The summary must be precise and actionable — pointing to exact files, function names, and code locations so the next agent can orient itself quickly.
Run these commands in parallel to understand what was worked on:
git diff --name-only HEAD~10..HEAD 2>/dev/null || git diff --name-only --cached — recently changed filesgit log --oneline -15 — recent commit messages for contextgit diff --stat HEAD~10..HEAD 2>/dev/null || git diff --stat --cached — scope of changesgit rev-parse --show-toplevel — repo root (for resolving paths)pwd — current working directory (file will be written here)If the git history is shallow or unavailable, fall back to git status and git diff.
Also review the conversation history for context about what was discussed, decided, and implemented during this session.
For each area of the codebase that was touched or discussed, identify and read the relevant files to extract precise references. Categorize findings into these sections (skip any section that has no relevant entries):
file_path — TypeName, queryName, mutationNamefile_path — resolverFunctionName()file_path — functionName()file_path — functionName()file_path — <ComponentName>file_path — description of what changedfile_path — description of coverageWrite a file called HANDOFF.md in the current working directory (pwd, NOT the repo root — this supports worktrees).
The file must follow this structure:
# Session Handoff
## Overview
<!-- 2-3 sentence summary of what was accomplished and what the feature/change is about -->
## Files to Browse First
<!-- Ordered list of the most important files the next agent should read to understand the work. Start with the highest-context files (e.g., schema, main service, primary component). Limit to 10-15 files max. -->
1. `path/to/file` — why to read this first
2. ...
## Code References
### GraphQL Schemas
- `path/to/schema.graphql` — `TypeName`, `mutationName`
### Resolvers
- `path/to/resolver.ts` — `resolveMyQuery()`
### Services / Repositories
- `path/to/service.ts` — `createThing()`, `updateThing()`
### Helpers / Utils
- `path/to/utils.ts` — `formatDate()`, `validateInput()`
### Components
- `path/to/Component.tsx` — `<MyComponent>`
### Configuration
- `path/to/config.ts` — added new feature flag
### Tests
- `path/to/test.spec.ts` — covers creation and validation flows
## Key Decisions & Context
<!-- Non-obvious decisions made during the session that the next agent needs to know. Trade-offs, workarounds, "we chose X over Y because Z". -->
## Open Items
<!-- Anything left unfinished, known issues, or next steps -->
Use relative paths from the repo root in all file references. Only include sections that have content.
After writing HANDOFF.md, present a detailed summary to the user:
file_path:line_number references where possibleBe thorough in this report. The user should be able to glance at it and confirm the handoff captures everything important.