Handoff Context

Handoff Context

Generates structured context summaries for seamless thread continuation.

Quick Start

Direct invocation (most reliable):

/handoff-context

Natural language trigger phrases:

• "Handoff and [action]" → continuation workflow
• "Handoff to [agent/skill]" → targeted handoff
• "Start a new thread with this" → explicit continuation
• "Let's handoff" / "Lets handoff" / "Just handoff" → context preservation

Note: The slash command works reliably across all agents. Natural language triggers depend on each agent's semantic understanding.

Configuration

Config File Locations

The handoff-context skill looks for configuration in the following order (highest to lowest priority):

Quick Setup

Copy the example config to your preferred location:

# Cross-tool location (recommended for multi-tool users)
mkdir -p ~/.config/agents
cp ~/.claude/plugins/base/skills/handoff-context/handoff-context-config.example.yml \
   ~/.config/agents/handoff-context-config.yml

# Claude Code specific
cp ~/.claude/plugins/base/skills/handoff-context/handoff-context-config.example.yml \
   ~/.claude/handoff-context-config.yml

# Project-local
mkdir -p .agents
cp ~/.claude/plugins/base/skills/handoff-context/handoff-context-config.example.yml \
   .agents/handoff-context-config.yml

Configuration Options

Example Configuration

# ~/.config/agents/handoff-context-config.yml

# Output format
format: yaml  # yaml | markdown

# Include optional sections
include:
  learnings: true
  approaches: true
  git_state: true
  quick_start: true

# Confidence scoring thresholds
confidence:
  minimum: 0.3      # Floor score (0.3 = tentative, still some value)
  threshold: 0.7    # Warning threshold (below = add more context)

Config Metadata in Handoff

Each handoff file includes metadata about which config was used:

metadata:
  config:
    source: "/home/user/.config/agents/handoff-context-config.yml"
    format: "yaml"

Temp Directory Behavior

Handoff files respect the following temp directory priority:

Why this priority? Claude Code's sandbox denies direct /tmp/ writes but allows writes to CLAUDE_CODE_TMPDIR (default: /tmp/claude). Other tools respect the standard TMPDIR environment variable.

Typical paths by tool:

• Claude Code: /tmp/claude/handoff-a1b2c3/handoff-20260111-143022.yaml
• Amp (macOS): /var/folders/xx/.../T/handoff-d4e5f6/handoff-20260111-143022.yaml
• Droid (Linux): /tmp/handoff-g7h8i9/handoff-20260111-143022.yaml

Invocation Method Reliability

Recommendation: Use /handoff-context for consistent cross-agent behavior.

Workflow Requirements

When this skill is triggered, you MUST follow these steps exactly:

1. Execute the script first:

# Find script in plugin cache (works across different directories)
# Alternative locations: ~/.claude/plugins, ~/.agent/skills
bash $(find ~/.claude/plugins -name "capture-context.sh" 2>/dev/null | head -1)

2. Capture the HANDOFF_FILE path from script output (format: HANDOFF_FILE=/tmp/...)

3. Read that file and populate conversation context:

   • Current work (tasks, status, affected files)
   • Conversation summary (phases, outcomes, decisions)
   • Next steps (continuation action context)
   • Preserved context (key details to remember)

4. Overwrite the same file with complete context

5. Display summary to user with file path

⚠️ CRITICAL REQUIREMENTS:

• ✅ MUST create .yaml file (not .txt)
• ✅ MUST use YAML format in file (not Markdown)
• ✅ MUST execute script (not bypass with manual commands)
• ✅ MUST display file path with continuation instruction

What the script captures:

• Session tracking (unique ID, timestamps)
• Metadata (confidence score, quality indicators)
• Quick start info (project type, package manager)
• Git state (branch, staged/unstaged/untracked files)
• YAML structure with dynamic timestamps
• Secure temp directory with proper permissions

What you need to add:

• Current work, conversation summary, next steps, preserved_context
• Update confidence_score based on populated content:
  • Base: 0.5
  • +0.1 if git_state has files
  • +0.1 if conversation_summary has 1+ items
  • +0.1 if current_work has 1+ items
  • +0.1 if next_steps has 1+ items
  • +0.1 if continuation_action is not null
  • -0.1 for each empty critical section
  • Cap: 0.3 minimum, 0.95 maximum
• Populate learnings with patterns/techniques discovered (0.3-0.9 confidence)
• Populate approaches (successful, failed, not attempted)
• Fill session.started and session.duration_minutes
• Fill quick_start fields (verification_command, files_to_read_first, context_priority, estimated_time_minutes)

Result: Complete /tmp/handoff-XXX/handoff-YYYYMMDD-HHMMSS.yaml with full context.

Success Criteria

Before completing handoff, verify:

• Script was executed (find + bash, not manual commands)
• File has .yaml extension (not .txt)
• File contains valid YAML structure (not Markdown with ##)
• File path is shown to user
• Continuation instruction includes exact file path
• Human-readable summary displayed alongside file
• Confidence score ≥ 0.7 (or document reason for lower score)
• Session tracking populated (started, duration_minutes)
• Critical sections filled (current_work, conversation_summary)

If any criteria fails: Re-invoke with /handoff-context slash command.

Quality Thresholds

What Gets Captured

Example Output

🔄 Handoff ready

Context written to: /tmp/handoff-20260126-143022.yaml

To continue in a new thread:
  1. Start a new AI agent conversation
  2. Tell the agent: "Continue from /tmp/handoff-20260126-143022.yaml"

Quick Examples

Continuation: "Handoff and build an admin panel" → action extracted Preservation: "Handoff this context" → full state saved Targeted: "Handoff to code-reviewer" → specific agent

Quick reference: See examples.md - 4 concrete scenarios:

1. Continuation Handoff - "Handoff and build an admin panel"
2. Context Preservation - "Handoff this context"
3. Targeted Handoff - "Handoff to code-reviewer for security check"
4. Fresh Thread for Next Phase - "Continue in a fresh thread"

Documentation

Evaluations

Test files for validating skill behavior:

• assets/eval-continuation.json
• assets/eval-context-preservation.json
• assets/eval-targeted-handoff.json
• assets/eval-non-git-repo.json
• assets/eval-negative-cases.json - Failure scenario detection

Run evaluations to verify pattern detection, YAML generation, and failure handling.

Common Scenarios

• After implementing a feature → move to next phase in fresh thread
• Long thread → start fresh with preserved context
• Bug fix → audit similar patterns elsewhere
• Planning → implementation transition

Error Handling

See references/workflow.md for complete manual workflow and error scenarios.

Integration

Works with:

• workflow-orchestrator: Handoff detection during workflow execution
• crafting-commits: Context preservation before committing
• systematic-debugging: Preserves error context during debugging

Philosophy

Seamless continuation without losing context.

No buttons to click, no commands to remember—just say "handoff" and continue working.

Limitations

• Does not automatically create new threads (platform capability)
• Context in /tmp/ may be cleared on system reboot
• Git state is captured at handoff time, not live-synced

Use when transitioning to a fresh thread. Skip when the conversation is still manageable.