---
name: cross-agent-handoff
description: Transfer unfinished feature work between Claude Code, Codex, Kimi Code, Antigravity, or another coding-agent harness with a verified worktree snapshot. Use only when the user asks to hand off, continue, resume, pause, close, or supersede work in progress, or when the shared-memory index contains an active handoff that clearly matches the current task. Do not invoke for a new unrelated task or ordinary shared-memory recall.
---

# Cross-Agent Handoff

Transfer unfinished work without turning temporary state into durable project
memory. A handoff carries context, not files and not authority.

## Gate the workflow

Use this skill only when at least one condition is true:

- the user asks to transfer, continue, resume, pause, close, or supersede WIP;
- the user names an existing handoff;
- the shared-memory index contains an active handoff whose goal clearly matches
  the current task.

Otherwise stop this workflow. Use `cross-agent-memory` for durable project
context. Do not list or open handoff files for a new unrelated task.

## Resolve the active pointer

1. Read repository agent instructions.
2. Resolve the shared-memory root, normally `docs/agent-memory/`.
3. Read only the `Active handoffs` section of `MEMORY.md`.
4. Open one matching active handoff completely.
5. If no pointer matches, do not guess from archived or unrelated handoffs.

## Prepare

Read [references/handoff-schema.md](references/handoff-schema.md), then run:

```powershell
pwsh -NoProfile -File `
  .agents/skills/cross-agent-handoff/scripts/new-handoff.ps1 `
  -Slug feature-slug `
  -Goal "Concrete unfinished outcome" `
  -SourceAgent codex `
  -TargetAgent claude-code `
  -OwnedPath path/owned/by/this/feature
```

The script creates a draft and adds its pointer to the shared index. Replace
every `FILL BEFORE TRANSFER` marker before declaring it ready.

Capture exact repository, worktree, branch, base and HEAD SHAs, dirty state,
owned paths, completed work, verification evidence, skipped checks, useful
failed attempts, blockers, external state, required authority, and one next
safe action.

## Resume

1. Open the recorded worktree when it still exists.
2. Compare live branch, HEAD, base, upstream, dirty state, and owned paths with
   the snapshot.
3. Inspect changes; never reset, clean, checkout, or stash them automatically.
4. Read only shared-memory topics referenced by the handoff.
5. Re-verify volatile and external claims.
6. Update the handoff before continuing if reality diverged.

If the snapshot no longer matches, state the divergence and establish a new
verified baseline before editing.

## Close or supersede

1. Verify the outcome at the level claimed.
2. Use `cross-agent-memory` to promote only durable decisions and lessons.
3. Add closure evidence and remove all unresolved placeholders.
4. Run the close script:

```powershell
pwsh -NoProfile -File `
  .agents/skills/cross-agent-handoff/scripts/close-handoff.ps1 `
  -Id 20260131-142500-feature-slug `
  -Status closed
```

The script updates metadata, moves the file to `handoffs/archive/`, and removes
the active pointer. Use `superseded` only when the replacement is identified in
the handoff.

## Validate

Run:

```powershell
pwsh -NoProfile -File `
  .agents/skills/cross-agent-handoff/scripts/validate-handoffs.ps1
```

Run the `cross-agent-memory` validator as well after promoting durable lessons.
On Windows PowerShell 5.1, replace `pwsh -NoProfile` with
`powershell -ExecutionPolicy Bypass`.

## Safety

- A handoff does not copy uncommitted files to another worktree or machine.
- Transfer commits, patches, or bundles only through the approved workflow.
- A handoff never grants permission to push, deploy, delete, pay, call, message,
  change roles, or mutate external systems.
- Preserve unrelated user and agent changes.
- Use one handoff per feature or tightly coupled change.