v0.3.56 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.56. 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.

Built-in safety rules forbid dangerous commands; the plan must be explained before files change
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 · Reconcile the handoff section by section: update “current state”, “next action”, “risks”, and “validation”. 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”Read the previous state
03AI continues workLoad rules for the task
04Say “Closeout”Save handoff and checks
05Next time say “Start”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 read and control the current title, AI may use already-loaded facts to replace a generic or stale title with <project name>｜<primary action>; it keeps an informative title, 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. A fresh install only makes onboarding available. START_NEXT_SESSION_PROMPT.txt is only for bringing in an AI that is not yet pointed at the folder.

「開工,繼續 <task>」 and 「<project> 開工」 continue directly. 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 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. When entered alone, AI reads the authoritative handoff and shows the current state and recommended next action. It starts the first safe step directly only when you give the goal in the same message. It loads onboarding only when the goal is unclear or you ask for guidance. You do not need to read this introduction first.

06 / SAFETY GUARDRAILS FOR BEGINNERS

Even if you do not know code,
AI will not wreck the project.

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.
Before changing files,
explain the plan.

For high-risk work—many files, external systems, deletion, or renaming—AI must explain the complete plan and wait for your confirmation. It does not make silent changes.

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.

PROJECT_INDEX: file register, sources of truth.

AGENTS / CLAUDE / GEMINI.md: startup rules.

At startup, AI reads only entry rules and the authoritative handoff. It loads the index, sync table, and rule packs as the task needs them.

READ WHEN NEEDED

Read by task

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

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 latest prompt itself. 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.

This kit handles the handoff between conversations. It does not include the rules for how AI works within one conversation—tone, priorities, response structure, safety guardrails, and output-layer roles. Use it together with Adam-AI-Instructions to cover both dimensions.

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.