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

```markdown
# 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

```python
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:

```yaml
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

```python
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

```markdown
## 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

```markdown
## 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