v0.3.66 source version · 60-second beginner introduction

The baton
between
AI sessions

Every new AI conversation starts from zero. It does not remember what you did together last time, the documents created along the way, or the reference material you brought in. This kit records progress, next actions, things to watch, and a file register in a few fixed documents. The next AI agent that can read and write your local project folder can pick up the baton by reading that handoff when you say Start Agent Handoff or 「開工」. Ordinary web-chat AI that cannot read or write the local folder is not a supported setting.

Version note: this page is aligned with v0.3.66. The version installed by @latest is decided by the npm registry.

See the three steps →Practical guide →GitHub
Agent Handoff Kit main visual: a Bauhaus composition of a red square, yellow circle, and blue triangle
00 / PROMO ANIMATION

Take one minute first:
see what it solves.

This video shows how Agent Handoff Kit connects progress, rules, documents, and next actions between AI conversations. If the video does not load, you can watch the promo animation on YouTube.

01 / THE ONE-SENTENCE VERSION

It handles one thing:
AI forgetting across conversations.

The job of this kit is deliberately narrow: cross-conversation forgetting. That forgetting is not only “where did we get to?” It also covers documents created along the way and reference material you introduced. The kit records progress, next actions, and the file register in fixed documents so the next session can continue automatically.

Without this kit

Every new conversation means explaining the background again, pasting old documents, naming which files are authoritative and which are reference-only, then explaining where you stopped. If that explanation is incomplete, AI has to guess: it may treat a reference as the source of truth or redo work you already finished.

With this kit

When you are ready to end this round, say 「收工」. The AI updates the handoff documents and file register, and synchronizes START_NEXT_SESSION_PROMPT.txt. Next time, in the same project, say Start Agent Handoff or 「開工」. The next AI immediately reads where things stand, the next action, which files are authoritative, and which are only references.

02 / FIVE COMMON PROBLEMS

Five things that often happen
when AI helps with a long project.

If you have spoken with AI for an hour and returned the next day to find it remembers nothing; or if you created several documents and supplied PDFs as references, but the next session cannot tell the source of truth from a draft—you have met one of the following situations.

01

A new AI does not know where you got to

A project lasts days and you may use Codex, Claude Code, Claude Cowork, and Antigravity along the way. Every new conversation needs the background again; eventually even you are unsure which version is current.

SESSION_HANDOFF remembers “current state + next action”
02

New files and supplied material become orphans

AI creates documents during the work, and you may add PDFs, Notion links, or research notes as references. The current AI remembers them, but a new conversation may not know they exist, or cannot distinguish a formal source from a draft.

Say “Bring this document into Agent Handoff Kit”; AI checks its index, synchronization responsibility, and related workflow
03

Each AI tool starts from a different entry point

Different AI tools look for different entry files. The kit places AGENTS.md, CLAUDE.md, and GEMINI.md together and directs common tools back to one startup contract. Antigravity CLI reads AGENTS.md and GEMINI.md in the working folder; AGENTS.md remains the sole source of truth, while GEMINI.md is only a bridge.

Three entry files point to the same rules, so tools do not drift apart
04

AI can change or delete things carelessly

Once AI starts acting, it may run commands such as rm -rf or git reset --hard. If you are away from the computer, you may not notice in time.

The kit includes safety rules: named destructive commands are prohibited; material changes require source checks, and high-risk actions require an impact explanation and the necessary confirmation.
05

External tools are not closed down safely

Long tasks often call MCP, a browser, automation tools, notebooks, or helper servers. If AI leaves them open, processes and caches accumulate. If it kills things simply because they look like node.exe or chrome.exe, it may interrupt you or another AI agent.

Close resources safely by ownership: this task’s resources may close; unknown or shared resources need evidence and your confirmation
03 / START AND CLOSEOUT

Start reconnects the state.
Closeout leaves the handoff.

You do not need to memorize a long command or open the handoff yourself. In a new conversation in the same project, say 「開工」 and the AI reads the previous state. When you are ready to end the round, say 「收工」 and it updates the handoff documents and writes the next handoff into the prompt copy.

開工
Chinese
Start
Start Agent Handoff
收工
Chinese closeout
WHAT AI DOES AFTER RECEIVING A START OR CLOSEOUT PHRASE: Start · Read AGENTS.md and the authoritative SESSION_HANDOFF, show the current state, risk, and recommended next action, then end the turn. It starts work only when the same message also gives a concrete task or explicit long-run instruction. Closeout 01 · Update only changed handoff state: record the overall outcome, current subtask, resume point, remaining acceptance checks, source sections read, and unresolved gaps. Handoff check · The AI reconstructs the next step from the handoff alone, then compares it with the original request and results. The card checks saved state and recorded checks, not the correctness of task conclusions. Unfinished work can be handed off when its blockers and conditions for resuming are clear. Closeout 02 · Record what was actually done this session in the work log. Closeout 03 · Synchronize START_NEXT_SESSION_PROMPT.txt, so 「開工」 can continue the next new conversation.
01Install completeThe AI has placed the handoff files
02Say “Start Agent Handoff”Read the previous state
03Give a task, then workLoad rules for the authorized task
04Say “Wrap up Agent Handoff”Save handoff and checks
05Next time say “Start Agent Handoff”A new conversation picks up the same baton
( o.o )

continuity ready

Ready to continue. The AI has read the handoff state and can proceed from the current objective.

( -.- )

handoff saved

Closeout has been saved. Next time, say Start Agent Handoff or 「開工」 in the same project.

( x.x )

handoff blocked

Not broken: something remains unsaved, uncommitted, unverified, or unresolved. Follow the Blocker line before treating the round as handed off.

04 / EIGHT COMMON TASK SETTINGS

You describe the task.
AI switches its working mode.

You do not need to remember rule names. Just describe what you want in everyday language. AI explains the way it is about to work and why. These rules are for AI to follow, not a manual you must read line by line.

CODE

Write / change code

AI reads the project index, finds the test command, and checks related files before it acts; it does not edit blindly at the start.

RESEARCH

Look things up / research

AI distinguishes sources, dates, facts, inferences, and unverified material; it does not present estimates as conclusions.

WRITING

Write copy / revise README

AI first checks audience, purpose, tone, and format; it does not produce words that look polished but are inaccurate.

KNOWLEDGE

Organize Notion / Google Drive / Obsidian

AI first decides whether an external document is an authoritative source, index, attachment, or output location. It writes to Notion, Google Drive, or Obsidian only when the current runtime’s read/write entry has been verified, the source or vault path is visible, and permission exists. An installed app alone does not grant write permission. Otherwise it produces material for manual synchronization and reads back every completed write.

COMMUNICATION

Output format / reports

AI states the conclusion first, then the background; it labels unverified material and makes instructions directly copyable.

SAFETY

Deletion / Git / external services

Specified destructive commands such as rm -rf and git reset --hard are forbidden. Force-pushing needs separate explicit permission and a check of affected refs. Before deletion, irreversible work, external writes, or source-data changes, AI names the target and impact; only destructive, irreversible, or source-data operations require a backup or original copy.

RELEASE

Prepare a release / publish

AI keeps “prepare release notes” separate from actually publishing, uploading, or creating a release, so it does not publish by mistake.

RULES

Change rules / workflow

AI checks whether existing rules can be extended first and merges before adding; it does not keep stacking new rules until they become confusing.

04 / BRIDGE INTO HANDOFF KIT

After an important document is finished,
let the next AI find it and use it correctly.

When AI creates a stock list, production guide, runbook, workflow, checklist, or research source of truth, do not leave it only in the current conversation. You can say “Bring docs/production-guide.md into Agent Handoff Kit.” AI checks whether the document is registered, when to read it, which workflow updates it, and whether a duplicate source of truth exists.

1

Two common ways to use it

Use one: name a document
Bring docs/stock-list.md into Agent Handoff Kit
or the older wording:
治理打通 docs/stock-list.md
or in English:
bridge governance for docs/stock-list.md
Use two: scan candidates
Scan for important documents not yet bridged into Agent Handoff Kit
or in English:
scan for unbridged governance documents

The first reviews the named document directly. The second names no document; it only scans the repository for important documents that may be missing their bridge.

2

Find candidates and gaps first

AI reads the document itself, PROJECT_INDEX, DOC_SYNC_REGISTRY, relevant workflows, and the handoff/log division of roles; it also looks for older documents serving the same purpose. A repository-wide scan only lists candidates; it does not treat ordinary documents as errors.

3

List gaps only; do not change things casually

If it finds a missing bridge, AI lists the suggested patch and what needs your decision. A scan does not change files automatically; deletion, renaming, or merging sources of truth still need your explicit confirmation.

05 / THREE STEPS TO START

From zero to your first successful handoff
in about five minutes.

You only need a computer with Node.js and an AI agent that can read and write your local project folder, such as Claude Code, OpenAI Codex, Gemini CLI, or Google Antigravity. Ordinary web-chat AI that cannot read and write the local project folder is not suited to this kit.

1

Install

The simplest way: open an AI agent that can read and write the local folder in your project folder, then paste:

Please read https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html and install or upgrade Agent Handoff Kit in this folder.

AI should show the current folder and ask you to confirm first; it will not install or upgrade before confirmation. Only when you want to handle it manually, run this in a terminal:

npx --yes @adamchanadam/agent-handoff-kit@latest init

The kit creates AGENTS.md, CLAUDE.md, GEMINI.md, and a set of fixed documents under dev/.

2

Start

Open an AI agent that can read and write the local project folder. If it is already in the right project, enter this in a new conversation:

Start Agent Handoff
or
開工

Only if the AI is not yet pointed at your project folder, use the path-bearing startup sentence:

Work in <your folder>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.

Following AGENTS.md, AI reads the authoritative dev/SESSION_HANDOFF.md. A plain 「開工」 reads only the minimum state, shows the current objective, risk, and recommended next action, then waits for your next instruction. When the platform can safely control the current title, AI may use already-loaded facts to replace a generic or stale title with <project name>｜<primary action>; when readback is available, it keeps a known informative and relevant title, but a tool that safely targets the current conversation does not require title readback. It skips silently when unsupported and performs no extra file or network reads. The title is display-only, not state, progress, or authority. It starts the first safe step directly only when the same message also contains a concrete task or explicit long-run instruction. The first-use welcome appears only when guidance remains eligible, the active objective is empty or TBD, and there is no concrete task in the same message; existing-project upgrades do not reset that state. START_NEXT_SESSION_PROMPT.txt is only for bringing in an AI that is not yet pointed at the folder.

「開工，繼續 <task>」, 「<project> 開工」, and Start Agent Handoff and continue <task> are all continuity commands. Adding only a project name remains status-only; a concrete task in the same message authorizes work. AI asks for confirmation only if the phrase could genuinely mean a real-world opening, shift, or unrelated event.

  1. Read only the minimum current handoff state.
  2. Show the current objective, risk, and recommended next action, then wait for your next work instruction.
  3. Show the first-use welcome only when guidance remains eligible, the objective is empty or TBD, and no task is given in the same message; show the scenario chooser only when the objective is still unclear or you ask for step-by-step guidance.
  4. Ask only for information that is genuinely missing and affects the result.
  5. For deletion, external writes, or other high-risk work, still wait for your confirmation before acting.
3

Close out

When this round is finished and you are ready to stop, enter:

收工
or
Wrap up Agent Handoff
or
wrap up
or
handoff

If you say something such as “so-and-so is closing work” with other context, AI should first confirm whether you mean an Agent Handoff Kit closeout.

AI updates the handoff documents and synchronizes START_NEXT_SESSION_PROMPT.txt. In the next round, say Start Agent Handoff or 「開工」 in the same project to continue; use the path-bearing startup sentence only when AI is not yet pointed at the folder.

🚀 First time? The shortest version

If the kit is not installed or you are unsure whether to upgrade, open an AI agent in the target folder and ask it to read agent-handoff-kit-ai-install.en.html and install or upgrade in this folder. Then enter Start Agent Handoff or 「開工」 in the same AI agent. AI reads the authoritative handoff and shows the current state and recommended next action. It adds the short first-use welcome only when guidance remains eligible, the objective is empty or TBD, and there is no task in the same message. Upgrading an existing project does not reset guidance; an ordinary startup remains status-only, while an explicit request for help follows the guidance flow. It starts the first safe step directly only when you give the goal in the same message. You do not need to read this introduction first.

06 / SAFETY GUARDRAILS FOR BEGINNERS

Before high-risk actions,
check, explain, and obtain the necessary confirmation.

The kit includes a safety working mode. Whenever a task involves deleting files, Git, cloud writes, or publishing, AI must switch to the safety approach and follow these hard boundaries:

  • Safe operating boundary: specified destructive commands such as rm -rf / git reset --hard and operations on system-root paths are always refused. Force-pushes, branch or tag deletion, and history rewriting need separate explicit permission and a check of affected refs.
  • Secret protection: sensitive values such as `.env`, API keys, and tokens are not printed, committed, or uploaded.
  • Verify; do not guess: before using a third-party service or tool, consult its official documentation. If it cannot be verified, label it “unverified” rather than writing from memory.
  • Safe closeout for external tools: after MCP, browser, automation tools, or helper servers are used, AI may automatically close only resources it can prove belong to this task. Unknown or shared resources need evidence and your confirmation.
  • Stop when permission is missing: when a file is locked or permission is missing, AI gives you a manual-action list rather than trying to force its way around the restriction.
Match checks and confirmation
to the risk of the change.

Read the relevant sources before material changes. For high-risk, external, or irreversible actions, explain scope, impact, acceptance, and required confirmation first. Simple, low-risk changes that are already authorized can be completed and checked directly without a separate full plan every time.

07 / LAYERED FILES

You do not need to remember
AI’s internal working logic.

The kit separates project material into “read every time”, “read when needed”, and “read only when tracing back”. That lets AI know what to read and when. You do not need to remember the layers—the section below simply shows how AI arranges your project material, so it knows where to look when you later ask, “Why did we do it this way?”

READ AT EVERY START

Read every time

SESSION_HANDOFF: current state, next action, risks.

AGENTS / CLAUDE / GEMINI.md: startup rules.

A bare startup reads entry rules and the authoritative handoff. From the project index it reads only the version row inside the unique Stack section for the card, without loading other index content.

READ WHEN NEEDED

Read by task

PROJECT_INDEX: file routes and authoritative sources, read as the task requires.

Working rules: guidance selected for the task.

PROJECT_DECISIONS: long-term project evolution, decisions, learning.

AI chooses the rules needed for today’s task; you do not need to decide. A long project’s decision history also lives here, so questions such as “Why did we do it this way?” have somewhere to look.

READ WHEN TRACING

Trace back later

Old SESSION_LOG entries

SESSION_LOG_archive: automatic cold archive.

These are not read in ordinary work; open them only for audit or trace-back. At closeout, AI archives old entries here automatically.

08 / AT A GLANCE

Remember three things.
That is enough.

01

Start a new conversation; say Start Agent Handoff

When AI is already in the right project, say Start Agent Handoff or 「開工」 in each new conversation. Only when it is not yet pointed at the folder, use: Work in <folder>. Read AGENTS.md first, then Start Agent Handoff.

02

Describe the task in ordinary language

AI first reads the requirements you already supplied. If there is enough information, it chooses the working mode and begins; if not, it uses a menu or short questions to clarify. Beginners do not need to remember any rule-pack names.

03

Start continues; closeout saves

In the next round, say Start Agent Handoff or 「開工」 and AI reads the authoritative dev/SESSION_HANDOFF.md to restore the state. When this round is over, say 「收工」 or Wrap up Agent Handoff; AI updates the handoff documents and START_NEXT_SESSION_PROMPT.txt.

09 / USE TOGETHER

Quality inside one conversation +
continuity between conversations.

Agent Handoff Kit primarily handles continuity between conversations; Adam-AI-Instructions primarily handles working rules within one conversation, including tone, priorities, and response structure. They can be used together optionally, with a minimum shared baseline for safety, secrets, irreversible actions, and publishing. Neither is the parent source of truth for the other, and they should not be merged into one rule set.

Adam-AI-Instructions

Within one conversation: AI working rules for tone, response structure, calculation discipline, safety guardrails, and output-layer roles.

See the prompt index →

Agent Handoff Kit

Between conversations: current state, next action, file register, closeout, and the next start.

See the three steps →

In section five, “Prompt Index”, of Adam-AI-Instructions, choose the applicable version and paste the full corresponding prompt.md into your AI tool settings. Then, in the project folder, open an AI agent that can read and write the local folder and ask it to read agent-handoff-kit-ai-install.en.html and install or upgrade this kit. For manual handling only, run npx --yes @adamchanadam/agent-handoff-kit@latest init. The former governs work inside one conversation; this kit governs project continuity between conversations.