a-organvm/cross-agent-handoff

Cross-Agent Handoff

Transfer work between agent sessions without losing context, decisions, or progress.

The Handoff Problem

When an agent session ends (context limit, task change, timeout), work must continue. Without a structured handoff, the next agent:

• Re-explores already-understood code
• Re-makes already-decided decisions
• Contradicts previous agent's approach
• Misses critical constraints discovered earlier

Handoff Document Structure

# Agent Handoff: {task-name}

**From:** Session {id} | **Date:** {date} | **Phase:** {current-phase}

## Current State
{What exists right now — files created, branches, test status}

## Completed Work
{What was accomplished, with evidence}
- [x] Created skills/development/python-packaging-patterns/SKILL.md
- [x] Created skills/development/cli-tool-design/SKILL.md
- [ ] Wave 1 skills (not started)

## Key Decisions
{Decisions made and WHY — so next agent doesn't re-litigate}
| Decision | Rationale |
|----------|-----------|
| Used governance_norm_group: repo-hygiene for packaging skills | Packaging is infrastructure hygiene, not quality-gate |
| Put data-backup-patterns in development/ not security/ | It's an engineering pattern, security-baseline applies via norm_group |

## Critical Context
{Non-obvious information the next agent needs}
- The ecosystem.yaml shows 130+ skills target, currently at 101
- Governance metadata format: governance_phases, governance_norm_group, organ_affinity, triggers, complements
- Bundle skills use `includes:` field listing constituent skill names

## Next Actions
{Exactly what to do next, no ambiguity}
1. Create Wave 1 skills: fastapi-patterns, database-migration-patterns, ...
2. After all waves: run refresh_skill_collections.py
3. Then validate with validate_skills.py --collection example --unique

## Risks & Warnings
{Things that could go wrong}
- Skill name must match directory name exactly
- .build/ artifacts must be refreshed after skill changes
- 16GB RAM constraint: max 4-6 concurrent agents

Context Compression

Summarization Levels

| Level | Token Budget | Content | |-------|-------------|---------| | Full | Unlimited | Complete handoff document | | Standard | ~2000 tokens | State + Decisions + Next Actions | | Minimal | ~500 tokens | Current state + Next action only | | Emergency | ~100 tokens | "Continue from step X of plan Y" |

Compression Strategy

def compress_handoff(handoff: dict, target_tokens: int) -> str:
    if target_tokens > 2000:
        return format_full_handoff(handoff)
    elif target_tokens > 500:
        return format_standard_handoff(handoff)
    elif target_tokens > 100:
        return f"""
Continue {handoff['task']}. Phase: {handoff['phase']}.
Completed: {', '.join(handoff['completed'][:5])}.
Next: {handoff['next_actions'][0]}.
Key constraint: {handoff['constraints'][0]}.
"""
    else:
        return f"Continue {handoff['task']} from step {handoff['next_step']}. Plan: {handoff['plan_path']}"

Multi-Agent Coordination

Parallel Agent Handoff

When multiple agents work simultaneously:

coordination:
  task: "Skill Fortification Campaign"
  agents:
    - id: agent-a
      scope: "Stream A: Engineering Infrastructure"
      owns: [skills/development/*-patterns/]
      status: in_progress

    - id: agent-b
      scope: "Stream B: Governance & Process"
      owns: [skills/tools/*, skills/documentation/*]
      status: in_progress

  shared_state:
    completed_skills: ["A1", "A2", "A3"]
    pending_skills: ["A4", "A5", "A6"]

  conflict_zones:
    - path: .build/skills-registry.json
      rule: "Only one agent refreshes at a time"
    - path: ecosystem.yaml
      rule: "Coordinate updates"

Conflict Prevention

OWNERSHIP_RULES = {
    "exclusive": "Only one agent modifies this path",
    "append_only": "Multiple agents can add, none can modify existing",
    "coordinator_only": "Only the coordinator agent modifies this",
}

def check_conflict(agent_id: str, file_path: str, agents: list[dict]) -> bool:
    for agent in agents:
        if agent["id"] != agent_id and file_path in agent.get("owns", []):
            return True  # Conflict
    return False

Handoff Triggers

| Trigger | Action | |---------|--------| | Context window 80% full | Start compression, prepare handoff | | Task phase complete | Write handoff document at phase boundary | | Error threshold exceeded | Handoff with error log and attempted fixes | | Time limit approaching | Save state and produce next-actions list | | Explicit user request | Full handoff with all context |

Recovery Patterns

From Incomplete Handoff

## Recovery Protocol

1. Read the last handoff document
2. Verify current file system state matches "Current State"
3. If mismatch: investigate git log for changes since handoff
4. Re-verify key decisions still hold
5. Continue from "Next Actions"

From Missing Handoff

## Cold Start Protocol

1. Read the plan file (.claude/plans/*)
2. Check git log for recent session activity
3. Inventory what exists vs what the plan requires
4. Infer current progress from file existence
5. Ask user to confirm before continuing

Anti-Patterns

• No handoff document — Every session that might continue must produce one
• Handoff without decisions — Raw state is useless without rationale
• Over-compressed context — Better to have a verbose handoff than lose critical context
• Handoff to file only — Also summarize in conversation so user has visibility
• No conflict zones — Parallel agents will corrupt shared state without coordination
• Assuming continuous context — Always verify state at session start