Plugin Reference
This page shows the internal instructions Claude follows when you invoke /kli:handoff in Claude Code.
auto-generated from kli/plugin/commands/handoff.md

Handoff

Create handoff document for transferring work to another session

You are tasked with writing a handoff document to hand off your work to another agent in a new session.

You will create a handoff document that is thorough, but also concise. The goal is to compact and summarize your context without losing any of the key details of what you're working on.

Process

1. Generate Scaffold via MCP Tool

Call the handoff MCP tool to generate the path, create the directory, emit the :handoff.create event, and write minimal placeholder content:

mcp__task__handoff(summary="brief-description-of-handoff")

This returns structured metadata: - path: the full handoff file path (already created with minimal content) - task: the current task ID - task_dir: the task directory path (use for playbook-export-state) - timestamp: ISO 8601 timestamp - session: session ID

The MCP tool requires a current task. If no task is set, it will error - use task_bootstrap or task_create first.

Parse the returned path and task_dir - you will overwrite the file with rich content.

2. Write Handoff Document

Use the Write tool to write rich content to the path returned by the MCP tool. Use the following template structure with YAML frontmatter:

Important: Before writing the handoff document you need to read the handoff document that was auto-generated by using the mcp__task__handoff tool so as to avoid getting a Write error.

---
date: [ISO 8601 timestamp from MCP response]
timestamp: [YYYY-MM-DD]
git_branch: [from git]
git_commit: [from git]
repository: [repository name]
task: "YYYY-MM-DD-description"
type: handoff
status: active
---

# Handoff: [Task Name] - [Brief Description]

**Created**: [ISO timestamp]
**Task Directory**: `[task_dir from MCP response]`

## Task(s)

[Description of the task(s) that you were working on, along with the status of each (completed, work in progress, planned/discussed). If working on an implementation plan, call out which phase you are on.]

## Critical References

[List 2-3 most important file paths that must be consulted:]
- `[task_dir]/research.md` - [Brief description]
- `[task_dir]/plan.md` - [Brief description]
- [Other critical files]

## Recent Changes

[Describe recent changes made to the codebase in file:line syntax:]
- `path/to/file.ext:line` - [Description of change]
- `another/file.ext:line-range` - [Description of change]

## Learnings

[Describe important things learned - patterns, root causes, key information for next session:]
- [Learning 1] - Evidence at `file.ext:line`
- [Learning 2] - Pattern found in `file.ext:line`
- [Important discovery with specific references]

## Artifacts

[Exhaustive list of artifacts produced or updated as filepaths/file:line references:]
- `[task_dir]/research.md` - [What it contains]
- `[task_dir]/plan.md` - [Current phase status]
- `.claude/commands/newcommand.md:1-50` - [What was created]

## Task Graph State

[If task has phases, capture current graph state:]
- **Current Phase**: [from task_graph(query="plan")]
- **Completed Phases**: [list of completed phases]
- **Pending Phases**: [list of pending/active phases]
- **Blocked By**: [any blocking tasks]
- **Related Tasks**: [any related-to edges]

[For complex tasks with many phases, optionally spawn graph-analyst to capture comprehensive state:]

Task( subagent_type="graph-analyst", prompt='{"question": "What is the complete state of task <task_id>? Include all phases, their status, and any related tasks."}', description="Capture task graph state for handoff" ) ```

Action Items & Next Steps

[List of action items for next agent to accomplish:] 1. [Next action based on current state] 2. [Following priority action] 3. [Additional tasks identified]

Other Notes

[Other notes, references, useful information:] - [Relevant codebase sections] - [Related documentation] - [Important context not captured above] ```

3. Present to User

After creating the document, respond:

Handoff created at: [path from MCP tool]

To commit this handoff:
  git add [task_dir]/handoffs/
  git commit -m "docs: add handoff for [description]"

To resume from this handoff in a new session:
  /kli:resume_handoff [path from MCP tool]

Important Guidelines

  • Be thorough and precise: Include both top-level objectives and lower-level details
  • More information, not less: This defines minimum content - add more if needed
  • Avoid excessive code snippets: Prefer file:line references over large blocks
  • Cross-reference KLI artifacts: Always link to research.md and plan.md if they exist
  • Specific file references: Use file.ext:line format consistently
  • Concise but complete: Compact context without losing key details
←Create TaskImplement→