VladimirGutuev/cross-agent-memory / skills/cross-agent-handoff
cross-agent-handoff
VerifiedTransfer 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.8 KB |
| agents/openai.yaml | config | 222 B |
| assets/handoff-template.md | markdown | 1.2 KB |
| references/handoff-schema.md | markdown | 3.8 KB |
| scripts/close-handoff.ps1 | script | 7.4 KB |
| scripts/new-handoff.ps1 | script | 8.8 KB |
| scripts/validate-handoffs.ps1 | script | 12.4 KB |
references/handoff-schema.md
View on GitHub# Handoff schema
A handoff transfers an unfinished feature between agent systems. It is a
verified snapshot, not durable project memory and not authority for external
actions. It belongs to the optional `cross-agent-handoff` workflow, not normal
shared-memory recall. A new unrelated task must not enumerate or open handoffs.
## Location and identity
Create active handoffs at:
```text
docs/agent-memory/handoffs/active/<timestamp>-<slug>.md
```
Archive them without deleting history:
```text
docs/agent-memory/handoffs/archive/<timestamp>-<slug>.md
```
Use one file per feature or tightly coupled change. The frontmatter `id` must
match the file name.
Every active handoff must also have one pointer in the shared index:
```markdown
## Active handoffs
<!-- cross-agent-handoffs:start -->
- [20260131-142500-feature-slug](handoffs/active/20260131-142500-feature-slug.md) - unfinished outcome; target: `claude-code`; branch: `feature/branch`.
<!-- cross-agent-handoffs:end -->
```
When no handoffs are active, keep the marker block and write `- None.` between
the markers. The markers are machine-managed by the handoff scripts. Archived
handoffs are intentionally absent from this startup pointer block.
## Required metadata
```yaml
---
id: 20260131-142500-feature-slug
status: active
source_agent: codex
target_agent: claude-code
created_at: 2026-01-31T14:25:00Z
updated_at: 2026-01-31T14:25:00Z
repository: repository-name
worktree: '/absolute/path/to/exact-worktree'
branch: feature/branch
base_sha: 40-character-commit
head_sha: 40-character-commit
dirty: true
---
```
Active-directory statuses are `active`, `paused`, or `blocked`. Archive
statuses are `closed` or `superseded`.
A superseded handoff must add the replacement identity:
```yaml
superseded_by: 20260201-090000-replacement-feature
```
`base_sha` is the merge base with the explicitly chosen base ref when possible.
`head_sha` is the exact commit checked out when the handoff is prepared.
`dirty: true` means the snapshot also depends on uncommitted state.
## Required body
Use every heading from the handoff template:
- `Goal`
- `Scope and ownership`
- `Completed`
- `Changed files`
- `Verification evidence`
- `Not verified`
- `Failed attempts`
- `Decisions and assumptions`
- `External state and permissions`
- `Blockers`
- `Next safe action`
- `References`
Distinguish evidence levels. A unit test is not browser UAT, a green CI run is
not deployment, and deployment is not proof that a user workflow works.
Record failed attempts only when they save the next agent from repeating useful
but unsuccessful work. Record external state as observed, and separately state
which mutation still needs user authority.
## Transfer mechanics
For a client switch on the same machine, prefer the exact recorded worktree so
both clients see the same uncommitted files. A handoff file does not copy those
files to another worktree.
For another worktree or machine:
1. transfer committed changes through the approved Git workflow, or create an
explicitly scoped patch or bundle;
2. record the exact transferred commit or artifact;
3. verify the target worktree before continuing.
Never reset, clean, checkout, stash, push, deploy, or delete merely because the
handoff mentions those actions.
## Lifecycle
1. Create the draft and active index pointer with `new-handoff.ps1`.
2. Replace every transfer placeholder with evidence or an explicit `None`.
3. Validate with `validate-handoffs.ps1`.
4. The target agent reconciles the live worktree and updates the snapshot.
5. On completion, use `cross-agent-memory` to promote only durable lessons.
6. Run `close-handoff.ps1` to mark the handoff `closed` or `superseded`, move
it to the archive, and remove its active pointer.
The handoff validator is independent from the durable-memory validator. Run
both after a closure that also promotes shared knowledge.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |