Project Handoff

Create a current snapshot that lets a new agent continue the work without the conversation. Do not clear the conversation yourself.

1. Resolve the destination

Determine the handoff target before writing:

1. Prefer an explicit directory supplied with the invocation. Normalize it and verify that it exists.
2. Otherwise, infer candidates from directories and files actually discussed, read, created, or edited in this session.
3. Treat the current working directory, Codex workspace root, version-control root, and project markers such as README.md, AGENTS.md, package.json, or pyproject.toml only as signals. None is authoritative by itself, and a project need not use Git.
4. Proceed without asking only when one candidate is clearly supported by the session evidence.
5. If the destination is missing or ambiguous, show the likely candidates and ask one concise question: HANDOFF.md 要写到哪个目录？ Do not guess.

If multiple independent projects were changed, prefer a separate HANDOFF.md for each and confirm their destinations before writing.

2. Inspect the actual state

After resolving each target directory:

• Review the relevant session work and inspect the target's structure, instructions, key documentation, implementation files, and outputs.
• If version control exists, inspect its status and relevant changes. If it does not, continue without treating that as an error.
• Use existing test or validation evidence. Run only lightweight, safe checks when useful; do not install dependencies or make unrelated project changes.
• Read an existing HANDOFF.md before updating it. Keep still-valid information, replace stale status, and move newly completed work out of the remaining-work section.

Do not rely only on conversation memory when filesystem evidence is available.

3. Write HANDOFF.md

Create or update <confirmed-target>/HANDOFF.md as a concise current-state document with these sections:

# Project Handoff

> Updated: YYYY-MM-DD
> Target: /absolute/confirmed/path

## Current state and structure

## Completed cases

## Decisions and conventions

## Remaining work and exact next step

## Pitfalls and dead ends

## Validation, risks, and open questions

Apply these rules:

• Give completed cases concrete outcomes and project-relative file or directory paths.
• Record decisions, technical choices, style or naming conventions, and their reasons. Include evidence locations when useful.
• Make remaining work actionable: priority, exact starting file or command, blockers, and the condition for completion.
• Record failed approaches and why they failed so the next agent does not repeat them.
• State tests or checks run and their results. Explicitly say what was not verified.
• Distinguish observed facts from session claims and inferences. Mark uncertainty as 待确认; never fabricate completion, decisions, or test results.
• Use absolute dates, concise prose, and paths instead of transcript-style narration.
• Never include credentials, tokens, private personal information, environment-file contents, or large raw logs.
• Keep the file as the latest handoff snapshot rather than an append-only history.

Modify only the intended HANDOFF.md unless the user explicitly requests other changes.

4. Verify and report

Re-read the finished file and confirm that:

• it is in the confirmed directory;
• every required section is present;
• the next action is specific enough for a new agent to begin immediately;
• claims, paths, dates, and validation status agree with the available evidence;
• no sensitive information was copied into the document.

Report the written path, a brief summary, and any unresolved uncertainty. Stop there so the user can review the handoff before manually running /clear.