handoff-receiver

name	handoff-receiver
description	Parse and execute incoming handoffs from Cursor following the normalized handoff schema with mixed-capability phases (analysis and write-capable)
schema_version	1

Handoff Receiver Skill

Purpose

Parse and execute incoming handoffs from Cursor following the normalized handoff schema.

Capability

MIXED CAPABILITY:

• Phases 1-2 (Parse & Validate): ANALYSIS-ONLY - Can run in any DAIC mode
• Phases 3-4 (Execute & Update): WRITE-CAPABLE - Requires IMPLEMENT mode

Note: The skill is configured in skill-rules.json as WRITE-CAPABLE with allowedModes: ["IMPLEMENT"] to ensure proper gating. When invoked outside IMPLEMENT mode, it will only execute phases 1-2 (read-only operations).

When to Use

• User says "check handoffs", "what did Cursor hand off", or "execute handoff"
• Starting work on a branch that has a recent handoff entry
• After Cursor creates a task and hands it to Claude

Workflow

Phase 1: Parse & Present (ANALYSIS-ONLY)

1. Read docs/ai_handoffs.md
2. Parse YAML entries using normalized schema (schema_version 1.0)
3. Find latest entry where to: claude
4. Display to user:
   • from: who sent it
   • timestamp: when
   • issue_id and branch: context
   • completed: what Cursor did
   • next: what Claude should do
   • context_files: relevant docs to read

Phase 2: Validate (ANALYSIS-ONLY)

5. Check for clear acceptance criteria in next tasks
6. If missing, propose concrete criteria and ask user to confirm
7. Verify context_files paths exist
8. Check repo_state if present (validate branch, warn about dirty_files)

Phase 3: Execute (WRITE-CAPABLE - requires IMPLEMENT mode)

9. User must approve execution (say "yert" or similar)
10. Read any context_files referenced in the handoff
11. Execute next tasks in logical order following DAIC workflow
12. Track what was completed with file paths

Phase 4: Update Handoff (WRITE-CAPABLE - requires IMPLEMENT mode)

13. Update the handoff entry's completed field with:
    • Tasks completed from original next list
    • File paths touched
    • Any caveats or partial completions
14. Preserve all original handoff data (don't delete/reformat)

Schema Compatibility

Supports both schemas for backward compatibility:

• Read: Accepts from_agent/to_agent/needed OR from/to/next
• Write: Always uses normalized schema (from/to/next + schema_version)

Example Invocation

User: "Check if Cursor handed anything off"
Assistant: [Reads docs/ai_handoffs.md, finds latest to:claude entry, displays]

User: "Execute it"
Assistant: [Requires IMPLEMENT mode] "I need to be in IMPLEMENT mode to execute handoff tasks. Say 'yert' to approve."

User: "yert"
Assistant: [Executes tasks, updates completed field]

Safety Rules

• Never execute handoff tasks outside IMPLEMENT mode
• Always validate repo_state before writes if present
• Preserve historical handoff entries (append, never delete)
• Log any issues in context/gotchas.md if handoff is malformed

Integration with cc-sessions

This skill respects cc-sessions DAIC workflow:

• DISCUSS/ALIGN: Can parse and display handoffs (Phase 1-2)
• IMPLEMENT: Can execute tasks and update completed field (Phase 3-4)
• CHECK: Should not modify handoffs

When in IMPLEMENT mode, this skill follows approved todos from the task manifest.