handoff-create

Generate a structured handoff document from our current conversation and save it to claudedocs/handoffs/handoff_YYYYMMDD_HHMMSS.md (or use the filename provided as $ARGUMENTS[0] if given).

Create the claudedocs/handoffs/ directory if it does not exist.

Document structure

Include exactly these sections:

# Handoff: [Task Name] - [YYYY-MM-DD HH:MM]

## Task

[One sentence: what is being accomplished]

## Scope

[In-scope behavior and exclusions. Include the contract revision, base commit and relevant working-tree state, acceptance criteria, applicable ADRs, blockers, permitted actions, and next owner. Mark unknowns explicitly.]

## Files

[All relevant files touched or needed. Format: `path/to/file:line` when a specific line matters]

- `src/auth/middleware.ts:45` - token validation logic
- `tests/auth.spec.ts` - test suite for this change
- `docs/api.md` - needs update after implementation

## Discoveries

[Key findings and insights from the work so far. Things the next agent needs to know that are not obvious from the code]

- [Discovery 1]
- [Discovery 2]

## Work Done

[Historical completion claims. Append-only: never remove prior entries. Include revisions, checks actually run, and evidence links when available.]

- [x] Task A completed (commit: abc1234)
- [x] Task B completed

## Status

[Last observed state and observation time: what is done, what remains, checks and their scope, blockers. Distinguish ticket state, run state, and acceptance.]

## Next Steps

[Actionable checklist of remaining tasks, in order]

1. [ ] Step 1
2. [ ] Step 2
3. [ ] Step 3

## Code

[Relevant code snippets with context. Focus on the parts a resuming agent needs to understand immediately]

\`\`\`typescript
// Key implementation detail
\`\`\`

Rules

• Keep it under 600 words total. A resuming agent should be able to load this and proceed within 30 seconds of reading.
• Use real paths and symbols; add :line only when verified at the recorded revision.
• Make the handoff self-contained without copying the exploratory transcript. Preserve source links and distinguish observation from interpretation.
• A handoff records authorization; it does not grant new permissions.
• "Work Done" is append-only. Never remove previous entries.
• Do not include the full git diff or full file contents. Include only the code snippets that are non-obvious.

After saving, confirm the file path.