Cross agent handoff

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, then run:

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:

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:

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.