# Codex Session Handoff

> Maintain a resume-ready transition file for active software projects. Use when the user asks to prepare a handoff, refresh HANDOFF.md, capture current engineering state before switching chats, preserve progress before a major refactor, or leave a clean restart point for another Codex session or coding agent. Reconcile any existing HANDOFF.md with the latest repo state, verification results, constraints, and next move. Do not use for generic summaries or non-development topics.

- Skill: `hyeon-kang/codex-session-handoff` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hyeon-kang/codex-session-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hyeon-kang/codex-session-handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Hyeon-Kang (https://skillmd.com/u/hyeon-kang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hyeon-kang/codex-session-handoff

---


# Codex Session Handoff

## Purpose

Keep a project-local restart document current so a fresh coding agent can resume work without replaying the full conversation.
Treat the handoff as an engineering checkpoint, not as a narrative recap.

## When To Use

- `handoff 만들어줘`
- `HANDOFF.md 갱신해줘`
- `새 채팅으로 넘길 개발 요약 작성해줘`
- `continue in a new Codex chat`
- `leave a restart note for the next agent`
- `prepare a transfer artifact for this coding task`

Do not use this skill for resumes, career documents, investing discussions, or casual conversation summaries.

## Operating Model

1. Confirm the request is about preserving development context.
2. Choose the handoff location.
3. Read the current handoff file first if it already exists.
4. Rebuild the current state from the thread and the local repo.
5. Replace stale notes with current facts.
6. Write the refreshed handoff file.
7. Tell the user what file was created or updated and what still needs verification.

## Target File Policy

- Default target: project root `HANDOFF.md`
- If `docs/HANDOFF.md` already exists, update that file instead of creating a second document
- If the user explicitly asks for a different location, use the requested path
- Never create both `HANDOFF.md` and `docs/HANDOFF.md` unless the user explicitly asks for duplicate copies

## Source Material

Prefer confirmed local state over memory. Pull from:

- the latest user goal and scope changes
- files changed, inspected, or still pending
- repo status and recent command results
- test, build, lint, or runtime verification already performed
- blockers, rejected approaches, assumptions, and constraints
- currently relevant services, ports, and environment details

If local repo state is available, these checks are usually enough:

- `git status --short --branch`
- `git diff --stat`
- targeted reads of touched files
- fast verification commands only when they are already known, cheap, or necessary to avoid writing something false

Do not inflate the handoff with speculative details or expensive reconnaissance.

## Writing Rules

- Prefer concrete facts over prose.
- If something is unknown, write `unknown`.
- Remove outdated next steps when they no longer match reality.
- Preserve decisions that matter for future work.
- Call out anything the next agent should avoid repeating.
- Never include secrets, tokens, passwords, or credential values.

## Handoff Template

Write the handoff file in Markdown using these sections and this order.

### OBJECTIVE

- Original user goal
- Latest user instruction or scope change

### SESSION SNAPSHOT

- One of `complete`, `in_progress`, `blocked`, `iterating`
- One sentence on current progress

### WORK COMPLETED

- Concrete completed work
- Important findings and conclusions
- Work explicitly ruled out
- Work that must not be redone

### PROJECT SURFACE

- `changed`: path and what changed
- `inspected`: path and why it mattered
- `pending`: path and what still needs work
- Include line references when useful

### REPO CHECKPOINT

- Current branch
- Staged changes
- Unstaged changes
- Recent commits if relevant
- Conflict, merge, or rebase state if relevant

### VALIDATION

- Important commands run
- Build, test, lint, and runtime checks
- Separate `verified` from `not_verified`
- Include error text only when it affects continuation

### DECISIONS

- Key technical decisions and rationale
- Rejected approaches that should not be retried without new evidence
- Constraints, assumptions, blockers, and risks

### OPERATING CONTEXT

- Running dev servers, ports, background processes, and required services
- Local environment assumptions
- Never include credentials

### RESUME HERE

- The exact first thing the next Codex turn should do
- Mention what remains unverified

## Response To The User

After writing the file:

- Report the exact path written.
- Summarize whether this was a create or update.
- Mention any important unknowns or unverified areas.
- Do not dump the entire handoff file into chat unless the user asks.

## Style

- Use short bullets, not long paragraphs.
- Prefer exact paths, commands, branch names, statuses, and ports.
- Be concise and operational.
- Preserve momentum and avoid reopening settled decisions.
- If code changed, explicitly state what changed, what was verified, and what still needs verification.