handoff

name	handoff
description	Create rigorous AI coding handoff briefs and, when supported, start or hand off to a fresh session/thread. Use when an agent session is too long, context is overloaded, performance has degraded, work must move to another AI coding tool, or the user asks for handoff, transfer, resume prompt, new session, context reset, continuation notes, or project handover.
license	MIT
compatibility	Designed for Codex, Claude Code, and generic AI coding agents. Optional session-management tools may be used when available.
metadata	{"version":"0.1.0","generated_on":"2026-06-30","source_mode":"manual"}

Handoff

Purpose

Use this skill to prepare a receiving agent that has no prior project context, no memory of the current conversation, and no reliable knowledge of task progress.

The handoff must let the next agent resume work without rediscovering the project from scratch, while making uncertainty explicit.

When To Use

Use this skill when:

• The current AI coding session has run too long, context is near the limit, or response quality/performance has degraded.
• The user asks to move work to a new session, another AI coding tool, another agent, or a teammate.
• A task is partially complete and needs a precise continuation prompt.
• You need to archive, summarize, or checkpoint implementation state before pausing.

Do not use it for ordinary short summaries, commit messages, release notes, or PR descriptions unless the user explicitly asks for transfer/resume context.

Required Inputs And Assumptions

Gather what is available from local context before writing the handoff:

• User objective and latest instruction, prioritizing the newest user message.
• Workspace path, repo identity, branch, dirty state, and relevant uncommitted changes.
• Important files read or edited, with absolute paths when possible.
• Commands run, test/build/lint results, servers started, and active long-running sessions.
• Current implementation status, blockers, risks, and immediate next steps.
• Any constraints from system/developer/user instructions that the next agent must preserve.

If information is unavailable, say so directly instead of inventing it.

Workflow

1. Stabilize the current state. Stop or account for long-running commands if they matter, inspect basic repo state, and avoid destructive cleanup.
2. Build a zero-knowledge project brief: what the project is, where it lives, how it is structured, and how to run or test the relevant parts.
3. Build a task-progress brief: original goal, latest user request, completed work, in-progress work, remaining work, and acceptance criteria.
4. Separate facts from assumptions. Label unverifiable claims, stale context, and decisions that need user confirmation.
5. Include exact restart instructions. The next agent should know the first 3-7 commands or files to inspect.
6. Choose delivery mode:
   • If the current client exposes session/thread tools and the user wants a new session, use them to create or hand off to a fresh session when allowed.
   • If no session-management tools are available, produce a copy-ready handoff prompt.
   • If the receiving target is another AI coding tool, adapt the prompt to generic wording and avoid client-specific directives.
7. Verify the handoff against the quality gates before sending or posting it.

Read references/handoff-protocol.md for detailed checklists, session-management behavior, and edge cases.

Output Contract

Return one of these outputs:

• Direct session handoff: a new thread/session link or identifier plus the exact message posted there.
• Copy-ready handoff prompt: a complete prompt the user can paste into another agent.
• Checkpoint note: a concise but complete handoff summary when no new session is requested.

Use assets/templates/handoff.md as the default structure unless the target tool requires a different format.

Quality Gates

Before finishing, confirm that the handoff:

• Assumes the receiver knows nothing about the project or conversation.
• Names the workspace/repo, current branch, relevant files, and current task state.
• Distinguishes completed, partial, and not-started work.
• Includes validation already run and validation still needed.
• Lists blockers, risks, assumptions, and user constraints.
• Provides concrete next actions in order.
• Avoids secrets, private tokens, credentials, and unnecessary sensitive content.
• Does not claim tests passed unless the current session actually observed that result.