handoff

name

handoff

description

Bidirectional session handoff system. (1) HANDOFF — generate a structured handoff doc capturing work state, tasks, decisions, blockers, and context. (2) ONBOARD — read an existing handoff doc and restore context to continue work. Use when user says "handoff", "交接", "save context", "transfer session", "switch agent", "交接文档", "onboard", "接手", "恢复上下文", "continue from handoff", or wants to preserve/restore session state.

Handoff

Two directions: handoff (交出) generates a document; onboard (接收) reads it and restores context.

Direction 1: Handoff (交出)

Collect Context

Gather from current session:

• Tasks: Run task({ operation: "list", include_terminal: true }) for full task tree
• Memory: Search project memory via memory({ operation: "search", query: "..." }) with broad terms
• Conversation: Review recent conversation for decisions, blockers, user preferences
• Files: Identify files modified or discussed in this session

Generate Document

Use the template at references/handoff-template.md. Fill each section with collected context. Output as a single markdown file.

Save

Save to project docs: docs/HANDOFF.md

If docs/ doesn't exist, save to project root.

Tell user the file location and remind them to share it with the next session.

Direction 2: Onboard (接收)

Locate Handoff

Check these locations in order:

1. docs/HANDOFF.md
2. HANDOFF.md (project root)
3. Ask user for the path

Read and Absorb

Read the full handoff document. Extract:

• Session summary — what was the previous session about
• Active tasks — what's in progress, what's blocked
• Completed work — what's done, avoid re-doing
• Pending decisions — what needs user input
• Key decisions — what was decided and why
• Blockers — what's preventing progress
• Files touched — what was modified
• Next steps — what to do immediately
• Context — non-obvious background
• User preferences — how the user likes to work

Verify State

Before claiming onboarded, verify:

1. Check git status — does working tree match the handoff's "Files Touched"?
2. Check task list — do tasks exist and match the handoff's states?
3. Read key files mentioned — confirm they exist and are as described

Report any discrepancies to user.

Confirm Readiness

Present a brief summary to user:

Handoff loaded. Current state:
- Active tasks: {N} ({list summaries})
- Blockers: {N} ({list})
- Next step: {top priority from handoff}
Ready to continue.

Ask user if anything has changed since the handoff was generated.

Section Guide (for handoff generation)

Section	Source	What to write
Session Summary	Conversation	1-2 sentence overview of what was accomplished
Active Tasks	task list	Each task with status, progress, blockers
Completed Work	task list (done)	What was finished, key outcomes
Pending Decisions	Conversation	Unresolved questions, user preferences not yet confirmed
Key Decisions Made	Conversation	Choices made and rationale
Blockers	task list (blocked)	What's preventing progress
Files Touched	Git status / conversation	List of modified files with brief description
Next Steps	Task states + conversation	Concrete next actions, in priority order
Context for Continuation	Conversation	Any non-obvious context a new agent needs
User Preferences	Conversation	Discovered preferences (language, style, workflow)

Tips

• Write for someone who has ZERO context about this session
• Include file paths, not just file names
• Reference specific line numbers when discussing code changes
• Note any temporary workarounds or hacks that need follow-up
• If there are open questions, state them explicitly
• For onboard: always verify — handoff docs can be stale