handoff-receiver

grandinh's avatarfrom grandinh

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

⭐1stars🔀0forks📁View on GitHub🕐Updated Nov 17, 2025
[Developer Tools]

When & Why to Use This Skill

The Handoff Receiver skill facilitates a seamless multi-agent development workflow by enabling Claude to parse, validate, and execute tasks handed off from Cursor. It ensures continuity in coding projects by processing standardized handoff schemas, maintaining context across different AI environments, and automating the transition from task analysis to implementation.

Use Cases

  • Resuming development work: Automatically pick up where Cursor left off by parsing the latest handoff entry to understand completed tasks and pending requirements.
  • Multi-agent collaboration: Synchronize state between different AI coding assistants using a normalized schema to ensure no context is lost during tool switching.
  • Automated task validation: Verify acceptance criteria and repository state (branch, dirty files) before executing code changes to ensure safety and consistency.
  • Project tracking: Maintain an automated audit trail of AI-driven changes by updating handoff logs with specific file paths and completion statuses.
namehandoff-receiver
descriptionParse and execute incoming handoffs from Cursor following the normalized handoff schema with mixed-capability phases (analysis and write-capable)
schema_version1.0

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)

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

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

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

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

  1. Update the handoff entry's completed field with:
    • Tasks completed from original next list
    • File paths touched
    • Any caveats or partial completions
  2. 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.