handoff

name

handoff

description

Project continuity handoff skill for Codex, Claude, the same agent after reset, or another collaborator. Triggers when the user writes "交班", "/handoff", or "handoff" as a standalone message or invocation, or asks for handover, 接力, resumption after context loss, role switch, or a persistent status package with project background, goals, environment, file locations, solved and unsolved issues, error history, and next actions.

Handoff

Purpose

Use this as the persistence layer beside live collaboration: handoff writes the compact project state a continuing agent needs after a break, context reset, role switch, or explicit transfer. The receiver may be Claude, Codex, the same agent after reset, or another collaborator named by the user.

Treat the handoff as current working state for the next agent, not a diary: merge new facts into the sections they change, replace stale facts, and remove details that no longer help execution.

交班 primarily reads, verifies, and writes durable state. If verification exposes a blocking live decision or split boundary, point to 朋友, 兄弟们, or 帮手 instead of burying the issue in the handoff; record only concluded decisions and clear next actions here.

For local tool, shell, path, or inter-agent runtime issues, read ${BUDDYS_SHARED_ENV:-${XIONGDIMEN_SHARED_ENV:-${CODEX_HOME:-$HOME/.codex}/../.shared/env/ENVIRONMENT.md}} if present. Update that file in place for stable environment facts; keep project/task continuity in handoff files, not in environment memory.

Resolve the shared friend root as ${CODEX_HOME:-$HOME/.codex}/../.shared/friend; use BUDDYS_SHARED_FRIEND or XIONGDIMEN_SHARED_FRIEND only when an active environment explicitly overrides it.

If a collaboration report was requested before handoff, record only the resulting decision deltas and visible rationale in decisions_and_changes; do not copy raw transcripts or full reports into the handoff.

Workflow

1. Align the shared channel before writing:

   • Read the local 朋友 skill and the counterpart skill if present: ${CODEX_HOME:-$HOME/.codex}/skills/friend/SKILL.md ${CODEX_HOME:-$HOME/.codex}/../.claude/skills/friend/SKILL.md
   • Use mailbox root ${CODEX_HOME:-$HOME/.codex}/../.shared/friend unless the active 朋友 skill says otherwise.
   • If CURRENT.md exists, treat canonical only as a pointer; enter that path and verify pwd, git branch/head/dirty state, and relevant files with live commands. CURRENT.md canonical pointer protocol follows the local 朋友 skill.
   • If .bridge.pending or .bridge_state.json shows pending work for this agent, resolve it according to 朋友 before overwriting any mailbox file.

2. Choose a project key before every handoff:

   • Prefer a stable ASCII slug, for example kb-runtime-maintenance or endovl-release-v1.
   • Include the human project title inside the handoff file.

3. Create or locate the handoff:

   • Default path: ${CODEX_HOME:-$HOME/.codex}/../.shared/friend/handoffs/<project-key>.md.
   • Use a repo-local .handoff/<project-key>.md only when the user explicitly asks or the project requires versioned handoff files.
   • Set --target-agent to the receiver when known (claude, codex, the same value as --agent for self-handoff, or a user-named collaborator if the script supports it).
   • To create a skeleton, run:

     python3 ${CODEX_HOME:-$HOME/.codex}/skills/handoff/scripts/new_handoff.py --project-key <slug> --title "<project title>" --agent <codex|claude> --target-agent <codex|claude>
     

   • Add --project-root <absolute-path> when the current shell is not already in the project root.
   • Add --project-local only for repo-local handoffs.

4. Update the existing file by editing, merging, and replacing stale facts. Do not append a diary. Keep each section concise and useful for the receiver's first read. After material changes, refresh the sections they invalidate first, especially current_objective, next_actions, environment_commands, file_map, and failure-related error_ledger. If a collaboration shaped the work, record the chosen decision in decisions_and_changes, unresolved disagreement in open_issues, and only collaboration nuance in agent_notes.

5. Before sharing or claiming the handoff is ready, run the read-only gate: python3 ${CODEX_HOME:-$HOME/.codex}/../.shared/friend/friend_gate.py check-handoff <handoff-path> Secret-pattern hits are hard failures; structure issues are warnings to fix when they affect continuity.

Required Content

Fill the canonical template at assets/handoff-template.md; new_handoff.py syncs a readable copy to ${CODEX_HOME:-$HOME/.codex}/../.shared/friend/handoffs/handoff-template.md. Keep these nine sections current:

• current_objective: background, plan, target outcome, and current stopping point.
• environment_commands: exact paths, shell/OS, virtual env/container, run/build/test/lint commands; Last verified (command + result) and Unverified (known gaps).
• file_map: important paths, each with why it matters.
• open_issues: blockers, new questions, risky assumptions, unresolved collaboration disagreements, and who should decide.
• decisions_and_changes: recent decisions or changes, including concluded collaboration decisions; write the reason, not a log transcript.
• error_ledger: major mistakes, high-frequency errors, symptoms, root cause, fix, and prevention.
• next_actions: ordered, testable next steps for the receiver.
• agent_notes: what the continuing agent should emphasize, what a peer should review, collaboration nuance, and External refs for URLs/papers/specs; do not duplicate decisions already recorded in decisions_and_changes.
• owner_review: user annotations — see tag table below.

Language Adaptation

Detect the output language from an explicit owner request first, then the handoff trigger phrase or first message in the session. Default to English if ambiguous. Write free-form prose, summaries, decisions, issue descriptions, and action descriptions in the detected language. Keep the handoff protocol surface in English: frontmatter keys, Markdown section headers, fixed template field labels (Background:, Goal:, Last verified:, For Codex:, etc.), table headers, owner_review tags, agent names, paths, commands, and N/A. Do not localize or restructure the canonical template anchors.

owner_review tags

Tag	Meaning	AI behavior
[TODO]	Needs an AI to act	Surface to user, then execute
[SUPPLEMENT]	Handoff info gap	Ask user or fill from context
[DONE]	User completed it	Do not redo unless asked
[USER-ACTION]	Easier for the user	Remind user explicitly

On reading a handoff, surface all [TODO] and [USER-ACTION] items to the user before continuing. AI may add [USER-ACTION] items (GUI login, billing, signing, approval) but must not rewrite the user's existing annotations.

Quality Rules

• Use absolute paths and one-line executable commands.
• Write N/A for unknowns; do not invent facts from stale context.
• Do not include secrets, tokens, .env contents, private query strings, personal data, or long raw logs.
• Verify project root, git status, and key files with live commands before acting; skip expensive/destructive/login commands and list them under Unverified.
• For ordinary project handoffs, share the handoff path with the receiver. For skill/protocol changes, prefer direct install or realtime reload request; use [NOTIFY] only as a last resort when direct install is out of scope and realtime contact is unavailable.