-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathagent-handoff-kit-guide.en.html
More file actions
97 lines (97 loc) · 69.1 KB
/
Copy pathagent-handoff-kit-guide.en.html
File metadata and controls
97 lines (97 loc) · 69.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Agent Handoff Kit — Practical Guide</title>
<meta name="description" content="Three complete Agent Handoff Kit journeys, from the first instruction to the next handoff.">
<link rel="canonical" href="https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;700&family=JetBrains+Mono:wght@400;700&display=swap" rel="stylesheet">
<style>
:root{--red:#e63946;--yellow:#ffd60a;--blue:#2e5bff;--ink:#0a0a0a;--paper:#f7f4ee;--paper2:#efeae0;--green:#06a77d;--rule:3px solid var(--ink);--max:1120px}
*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--paper);color:var(--ink);font:17px/1.62 "Space Grotesk",Arial,sans-serif}code,pre,.mono{font-family:"JetBrains Mono",Consolas,monospace}code{background:#fff4a8;padding:.08em .28em}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#111;color:#f7f4ee;padding:16px;margin:10px 0;border:2px solid var(--ink);font-size:13px;line-height:1.55}.wrap{max-width:var(--max);margin:auto;padding:0 24px}
.banner{display:grid;grid-template-columns:2fr 1fr 1.5fr;height:14px;border-bottom:var(--rule)}.banner i:nth-child(1){background:var(--red)}.banner i:nth-child(2){background:var(--yellow)}.banner i:nth-child(3){background:var(--blue)}nav{position:sticky;top:0;z-index:4;background:var(--paper);border-bottom:var(--rule)}nav .wrap{min-height:66px;display:flex;justify-content:space-between;align-items:center;gap:20px}.brand{font-weight:700}.brand img{width:32px;height:32px;vertical-align:middle;margin-right:8px}.lang{font:700 13px "JetBrains Mono",monospace;color:var(--ink)}a{color:inherit}
.hero{border-bottom:var(--rule);padding:64px 0 48px;background:linear-gradient(135deg,#f7f4ee 0%,#fff8c9 100%)}.kicker,.badge,.label{font:700 12px "JetBrains Mono",monospace;letter-spacing:.06em;text-transform:uppercase}.kicker{background:var(--ink);color:var(--paper);padding:6px 10px;display:inline-block}.hero h1{font-size:clamp(42px,7vw,82px);line-height:.92;margin:20px 0}.accent{color:var(--red)}.accent2{color:var(--blue)}.lede{font-size:20px;max-width:780px}.notice{border-bottom:var(--rule);padding:26px 0;background:var(--ink);color:var(--paper)}.notice .first{display:inline-block;background:var(--yellow);color:var(--ink);padding:8px 12px;margin-bottom:10px;font:700 14px "JetBrains Mono",monospace}.notice code{color:var(--ink)}.plain{border-bottom:var(--rule);background:var(--paper2);padding:20px 0}
.section{border-bottom:var(--rule);padding:54px 0}.section h2{font-size:clamp(28px,4vw,46px);line-height:1.08;margin:12px 0 18px}.narrative{font-size:18px;max-width:820px}.badge{display:inline-block;padding:6px 9px;background:var(--red);color:#fff}.block,.callout{margin:22px 0;border:var(--rule);background:#fff}.block-head{padding:8px 12px;border-bottom:var(--rule);background:var(--yellow);display:flex;justify-content:space-between;gap:12px}.block-body,.callout{padding:16px}.callout{border-left:12px solid var(--blue)}.chat{margin:24px 0}.bubble{padding:16px 18px;border:var(--rule);max-width:920px;margin:12px 0}.user{background:#dff4ee;margin-left:auto}.ai{background:#fff}.who{display:block;font:700 12px "JetBrains Mono",monospace;margin-bottom:8px}.pills span{display:inline-block;margin:3px;padding:3px 7px;border:2px solid var(--ink);font:700 12px "JetBrains Mono",monospace}.coding{background:#bfe0ff}.safety{background:#ffc8cf}.research{background:#e5d5ff}.knowledge{background:#c9f1df}.writing{background:#ffe5ab}.release{background:#ffd60a}
.quick-cycle{background:var(--paper);border-bottom:var(--rule);padding:30px 0}.cycle-grid{display:grid;grid-template-columns:repeat(5,1fr);border:var(--rule);margin-bottom:18px}.cycle-step{min-height:108px;padding:16px 14px;border-right:2px solid var(--ink);display:flex;flex-direction:column;justify-content:space-between;gap:10px}.cycle-step:last-child{border-right:none}.cycle-step .num{font:700 12px "JetBrains Mono",monospace;letter-spacing:.08em}.cycle-step strong{font-size:17px;line-height:1.2}.cycle-step span{font:12px/1.35 "JetBrains Mono",monospace}.cycle-step.c1{background:var(--yellow)}.cycle-step.c2{background:var(--red);color:var(--paper)}.cycle-step.c3{background:var(--paper2)}.cycle-step.c4{background:var(--blue);color:var(--paper)}.cycle-step.c5{background:var(--green)}.status-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:14px}.status-tile{border:var(--rule);padding:16px;background:var(--paper2);min-height:140px}.status-tile .face{font:700 21px "JetBrains Mono",monospace;margin-bottom:8px}.status-tile h2{font-size:18px;margin:0 0 8px;line-height:1.2}.status-tile p{margin:0;font-size:14px;line-height:1.5}.tabs{border-bottom:var(--rule);background:var(--paper2)}.tabs .wrap{display:flex;gap:8px;flex-wrap:wrap;padding-top:14px}.tab{font:700 14px "Space Grotesk",sans-serif;padding:12px;border:var(--rule);border-bottom:0;background:var(--paper);cursor:pointer}.tab[aria-selected="true"]{background:var(--blue);color:#fff}.case[hidden]{display:none}.rail{display:flex;gap:7px;overflow:auto;padding:18px 0}.rail a{white-space:nowrap;border:2px solid var(--ink);padding:6px 8px;text-decoration:none;font-size:13px;background:#fff}.rail b{color:var(--red);margin-right:5px}.facts{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:10px}.fact{border:2px solid var(--ink);padding:12px;background:#fff}.fact b{display:block;font-size:20px;color:var(--blue)}.outro{padding:58px 0;background:var(--ink);color:var(--paper)}.outro a{display:inline-block;margin:4px;padding:9px 12px;border:2px solid var(--paper);text-decoration:none}.outro a:first-of-type{background:var(--yellow);color:var(--ink);border-color:var(--yellow)}footer{padding:30px 0;background:var(--paper2);border-top:var(--rule);font-size:14px}.case-tabs{border-bottom:var(--rule);background:var(--paper2)}.case-tabs .wrap{display:flex;gap:8px;flex-wrap:wrap;padding-top:14px}.case-tab{font:700 14px "Space Grotesk",sans-serif;padding:12px;border:var(--rule);border-bottom:0;background:var(--paper);cursor:pointer}.case-tab:hover{background:var(--paper2)}.case-tab[aria-selected="true"],.tab[aria-selected="true"],.case-tab.active{background:var(--blue);color:#fff}.case-tab.active{font-weight:700}.case-content[hidden]{display:none}@media(max-width:650px){body{font-size:16px}.hero{padding:42px 0}.block-head{display:block}.section{padding:38px 0}.cycle-grid,.status-grid{grid-template-columns:1fr}.cycle-step{border-right:none;border-bottom:2px solid var(--ink);min-height:88px}.cycle-step:last-child{border-bottom:none}}
</style>
</head>
<body>
<div class="banner"><i></i><i></i><i></i></div>
<nav><div class="wrap"><div class="brand"><img src="images/agent-handoff-kit-logo2-256.png" alt="Agent Handoff Kit logo">Agent Handoff Kit · Practical Guide</div><a class="lang" href="agent-handoff-kit-guide.html" lang="zh-Hant">繁體中文</a></div></nav>
<header class="hero"><div class="wrap"><span class="kicker">v0.3.64 source version · three everyday journeys · from the first instruction to long-term continuity</span><h1>From the <span class="accent">first instruction</span><br>to the <span class="accent2">next handoff</span></h1><p class="lede">Three complete everyday journeys—tidying a Downloads folder, researching a café business, and evolving a long-running AI project—show Agent Handoff Kit from installation through handoff. At each stage the AI says which working mode it loaded, how it will plan, how it will verify the result, and when it will synchronise the next-session prompt.</p><p><strong>Version note:</strong> this page is aligned with v0.3.64. The version actually obtained through <code>@latest</code> is determined by the npm registry. Terminal output below is a v0.3.64 example.</p></div></header>
<div class="notice"><div class="wrap"><span class="first">🚀 First time here?</span><p><strong>You do not need to read this guide first.</strong> In the folder you want to work in, open an AI agent that can read and write local folders. Ask it to read <code>agent-handoff-kit-ai-install.en.html</code> and install or upgrade there. After installation, if the AI is already in the correct project, type:</p><pre>Start Agent Handoff<br>or: 開工</pre><p>Only if the AI is not yet pointed at the folder, use: <code>Work in <your folder>. Read AGENTS.md first, then Start Agent Handoff.</code> The AI follows <code>AGENTS.md</code> to the authoritative <code>SESSION_HANDOFF</code>. After a fresh install, a plain start shows the current state, risks and recommended next step, enters the short first-use welcome, then waits for your next message. On an existing upgraded project, a plain start remains status-only; a same-message task starts work directly. <code>START_NEXT_SESSION_PROMPT.txt</code> is only for an AI that has not yet been pointed at the folder. To finish a session, say <code>Wrap up Agent Handoff</code>.</p><p>Ordinary web-chat AI that cannot read and write your local folder is not suitable for this tool. This guide demonstrates long-running local-agent work.</p></div></div>
<section class="quick-cycle" aria-label="Start and closeout cycle with cat status legend"><div class="wrap"><div class="cycle-grid"><div class="cycle-step c1"><span class="num">01</span><strong>Install complete</strong><span>The AI has placed the handoff files</span></div><div class="cycle-step c2"><span class="num">02</span><strong>Say “Start”</strong><span>Read the previous state</span></div><div class="cycle-step c3"><span class="num">03</span><strong>AI continues work</strong><span>Load rules for the task</span></div><div class="cycle-step c4"><span class="num">04</span><strong>Say “Closeout”</strong><span>Save handoff and checks</span></div><div class="cycle-step c5"><span class="num">05</span><strong>Next time say “Start”</strong><span>A new conversation picks up the same baton</span></div></div><div class="status-grid"><div class="status-tile"><div class="face">( o.o )</div><h2>continuity ready</h2><p>Ready to continue. The AI has read the handoff state and can proceed from the current objective.</p></div><div class="status-tile"><div class="face">( -.- )</div><h2>handoff saved</h2><p>Closeout has been saved. Next time, say Start Agent Handoff or 「開工」 in the same project.</p></div><div class="status-tile"><div class="face">( x.x )</div><h2>handoff blocked</h2><p>Not broken: something remains unsaved, uncommitted, unverified, or unresolved. Follow the Blocker line before treating the round as handed off.</p></div></div></div></section>
<div class="plain"><div class="wrap"><p>⚙️ <strong>These three journeys assume the relevant external tools are already connected in the AI tool</strong> (GitHub, Notion, Google Drive, and so on). If they are not connected, the AI pauses at that step and asks you to set them up, or produces material you can synchronise manually.</p><p>After a long task uses MCPs, a browser, automation, notebooks, or helper servers, the AI closes only resources it can prove belong to this task. For an unknown, shared, user-owned, or other-agent-owned resource, it records the evidence and waits for your confirmation.</p></div></div>
<section class="section" id="work-rules-overview"><div class="wrap"><span class="badge">AI working rules</span><h2>The AI does more than read a handoff: it changes working mode for the task</h2><p class="narrative">The point of Agent Handoff Kit is not merely to remember where work stopped. After startup it helps the AI select task-appropriate rules. A new user needs one simple idea: you state the goal; the AI chooses the working rules; a high-risk operation stops for your approval.</p><div class="block"><div class="block-head"><span class="label">What happens after startup</span><span class="mono">automatic sequence</span></div><div class="block-body">1. Start: read the authoritative handoff for current state, next action and risks; read the project index only when the task needs it.<br>2. Classify the task: writing, development, research, knowledge organisation, or external tools.<br>3. Load rules: only relevant packs, not every internal file at once.<br>4. Work and verify: plan first, read facts, make changes, then check them in a verifiable way.<br>5. Wrap up: durable state returns to the handoff; one-off output does not pollute long-term rules.</div></div><div class="chat"><div class="bubble user"><span class="who">You</span>When we write public Chinese documents in future, use formal Traditional Chinese and avoid half-Chinese, half-English wording. Connect this rule to Agent Handoff Kit.</div><div class="bubble ai"><span class="who">AI</span>I will first decide whether this is a one-off preference, next-handoff state, a project-index fact, or a long-term working rule. For a durable rule I will find the existing source of truth instead of putting everything into one file.</div></div><div class="callout"><span class="label">Adding your own rule</span><p>Do not begin by editing rule files yourself. Say: “Connect this lesson to Agent Handoff Kit”, “Connect this document to Agent Handoff Kit”, or “Turn this mistake into a future mechanism.” The AI should decide whether it belongs in handoff state, the project index, a sync register, a durable decision, or a working rule.</p></div><div class="block"><div class="block-head"><span class="label">Advanced map</span><span class="mono">only when you want the internal structure</span></div><div class="block-body"><code>dev/RULE_PACKS.md</code> routes rules to tasks. <code>onboarding.md</code> is marked pending by first install; a fresh plain startup with no same-message task enters a short first-use welcome. Existing-project upgrades do not reset that flow. A clear goal starts directly, while no goal yet leads to guidance or short questions. <code>safety.md</code> covers deletion, Git, releases, external APIs and secrets; <code>writing.md</code> covers public writing; <code>research.md</code> covers source comparison and uncertainty; <code>coding.md</code> covers code and tests; <code>agent-governance.md</code> covers handoff and long-term governance; <code>release.md</code> covers versions, tags, releases, deployment and npm publishing; <code>knowledge.md</code> covers Notion, Drive and source-of-truth boundaries; <code>integrations.md</code> covers connectors, MCPs, plugins, skills, credentials and resource closeout; <code>communication.md</code> covers language and user-facing reporting.</div></div></div></section>
<div class="tabs case-tabs" id="case-tabs"><div class="wrap"><button class="tab case-tab active" data-case="a" aria-selected="true"><b>CASE A</b> · Tidy a Downloads folder, then publish it</button><button class="tab case-tab" data-case="b" aria-selected="false"><b>CASE B</b> · Research a café market and write the report</button><button class="tab case-tab" data-case="c" aria-selected="false"><b>CASE C</b> · A project evolving across months</button></div></div>
<main>
<div class="case case-content" data-case="a">
<div class="wrap rail"><a href="#a-step-1"><b>01</b>Install</a><a href="#a-step-2"><b>02</b>Start</a><a href="#a-step-3"><b>03</b>First response</a><a href="#a-step-4"><b>04</b>Confirm and build</a><a href="#a-step-5"><b>05</b>Safety preview</a><a href="#a-step-6"><b>06</b>Wrap up</a><a href="#a-step-7"><b>07</b>Handoff and release</a></div>
<section class="section" id="a-step-1"><div class="wrap"><span class="badge">Step 01 · Case A</span><h2>Install — one instruction creates the handoff files in the folder</h2><p class="narrative">You can give this first step to an AI agent that can read and write the local folder. Create an empty folder such as <code>~/Downloads-tidy</code>, open the AI there, and ask it to read the AI install page. It confirms the current folder, then decides whether to install, upgrade, or stop. Use the terminal route only if you want to do it yourself.</p><div class="block"><div class="block-head"><span class="label">AI conversation</span><span class="mono">~/Downloads-tidy</span></div><div class="block-body">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.</div></div><div class="block"><div class="block-head"><span class="label">Manual terminal route</span><span class="mono">~/Downloads-tidy</span></div><div class="block-body"><pre>$ npx --yes @adamchanadam/agent-handoff-kit@latest init<br><br>📋 Before writing: no Kit files are present. The tool will create handoff files, AI entry files and working rules. No existing files will be overwritten.<br><br>create: 21<br> AGENTS.md · CLAUDE.md · GEMINI.md · START_NEXT_SESSION_PROMPT.txt<br> dev/SESSION_HANDOFF.md · dev/SESSION_LOG.md · dev/PROJECT_INDEX.md<br> dev/DOC_SYNC_REGISTRY.md · dev/RULE_PACKS.md · dev/PROJECT_DECISIONS.md<br> dev/rules/safety.md · dev/rules/coding.md · dev/rules/onboarding.md · dev/rules/integrations.md · ...<br><br>Continue? (yes/no): yes<br><br>✅ created: 21 · 🔀 merged: 0 · ⏭️ skipped existing: 0<br>📦 Version: v0.3.64 · 🛠️ Mode: first-install<br>🔎 Just finished: init; create 21 / merge 0 / skip 0 / conflict 0.<br>🚀 Next: leave the terminal and open your AI tool to start Agent Handoff.<br><br>⚠️ This is not a terminal command. In an AI conversation in this folder, type:<br>Start Agent Handoff<br>or: 開工<br><br>Only if the AI is not pointed at this folder:<br>Work in ~/Downloads-tidy. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.</pre></div></div><div class="callout"><span class="label">What was created</span><h3>One set of rules, three AI entry points</h3><ul><li><strong>Three entries, one rule set:</strong> <code>AGENTS.md</code>, <code>CLAUDE.md</code> and <code>GEMINI.md</code> are created together. Antigravity reads the folder’s <code>AGENTS.md</code> and <code>GEMINI.md</code>; <code>GEMINI.md</code> is a bridge, not a second rule set.</li><li><strong>The AI install page confirms the folder first:</strong> before confirmation it should not run <code>init</code>, <code>upgrade</code> or <code>doctor</code>.</li><li><strong>The next line belongs in AI chat:</strong> newcomers often paste <code>Start Agent Handoff</code> into a terminal. The warning marks that it belongs in the AI conversation instead.</li><li><strong>Important documents can be connected:</strong> after an AI creates a stock list, production guide, workflow or checklist, say <code>Connect docs/example.md to Agent Handoff Kit</code>.</li><li><strong>Run doctor only when uncertain:</strong> normally start the AI directly. If you later doubt the files, run <code>npx --yes @adamchanadam/agent-handoff-kit@latest doctor</code>. A temporarily lagging next-session prompt is a reminder to synchronise at closeout, not an excuse to overwrite work.</li></ul></div></div></section>
<section class="section" id="a-step-2"><div class="wrap"><span class="badge">Step 02 · Case A</span><h2>Start the handoff — first start can onboard; a task starts work</h2><p class="narrative">Open a new conversation in an AI agent that can read and write the local project folder. If it is already in the right project, you may type <code>Start Agent Handoff</code> or <code>開工</code>. On a fresh install with no same-message task, that recovers the minimum state, shows the current objective, risks and recommended next step, enters the short first-use welcome, then waits for your next message. On an existing upgraded project, the same plain start remains status-only. When the platform can safely read and control the current title, the AI may use already-loaded facts to replace a generic or stale title with <code><project name>｜<primary action></code>; 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. If you include the goal in the same message, or explicitly say to continue to the next blocker or finish the current objective, the AI may begin under the normal task rules.</p><div class="chat"><div class="bubble user"><span class="who">You</span><pre>Start Agent Handoff</pre></div></div><div class="callout"><span class="label">What actually happens</span><h3>The start phrase is not automatic execution authority</h3><ul><li><strong>A plain fresh start can include onboarding:</strong> the AI reads only the minimum handoff state, shows the startup card, risks and recommended next step, and may add the first-use welcome, but it does not search, plan or start a task.</li><li><strong>A same-message task can start:</strong> you can write “Start Agent Handoff, tidy my Downloads”; when facts are sufficient, the AI chooses the closest working situation without making you choose A–F.</li><li><strong>Later guidance needs a real signal:</strong> after the first-use welcome is consumed, phrases such as “teach me”, “I’m new” or “help me start”, or a task that still needs clarification, are what load newcomer guidance.</li></ul></div></div></section>
<section class="section" id="a-step-3"><div class="wrap"><span class="badge">Step 03 · Case A</span><h2>When you enter only the start phrase — fresh install welcomes, then waits</h2><p class="narrative">In this example the user entered only <code>Start Agent Handoff</code> and the fresh project’s handoff had no goal. The new behaviour is not a menu, a plan or a task protocol. The AI shows the current state and recommended next step, adds the short first-use welcome, ends the turn, and waits for the user to provide a task. To begin work, the user sends the task in the next message or includes it in the original startup message.</p>
<h3>This response adds the first-use welcome after the startup card</h3><div class="chat"><div class="bubble ai"><span class="who">AI (started from AGENTS.md)</span><pre> /\_/\ Agent Handoff Kit vX.Y.Z<br> ( o.o ) continuity ready<br> > ^ <<br><br>🔎 Handoff state: fresh install<br>📌 Current objective: not set<br>⚠️ Risks: none<br>🚀 Recommended next step: tell me what you want to do, for example “tidy Downloads and show me a preview first”.</pre><p>I have read that this is a fresh install and no task objective is set yet, so I will give a short first-use welcome before work begins. Tell me one concrete first goal; I will choose the needed rules and still ask before any risky action.</p></div><div class="bubble user"><span class="who">You</span>I want to tidy <code>~/Downloads</code>. It has one or two years of mixed files—more than a thousand. Sort by documents, images, installers, archives and others; then by year. Make a small reusable tool. I must see a preview list before any real move.</div><div class="bubble ai"><span class="who">AI · narrowed task</span><p>You have now provided a clear task, folder, sorting direction and safety limit. The first small task is: <strong>build a reusable Downloads organiser, but produce only the preview list; do not move files yet.</strong></p><p>That is safest for a large file move. After you accept the preview, the next step can perform the real move.</p><p class="pills"><span class="coding">Coding</span> write the organiser <span class="safety">Safety</span> protect a large file move</p><p>After you confirm this first scope, the work follows five visible stages: <strong>plan → read → change → check → approved execution.</strong> I will plan the rules, read the folder facts, write the reusable tool, show the preview, and wait for your separate approval before any real move.</div></div><div class="callout"><span class="label">What actually happens</span><h3>Status, first-use welcome and work start are separate</h3><ul><li><strong>A plain fresh start can include onboarding:</strong> the AI may add a short first-use welcome, but it does not turn an empty handoff into a task plan.</li><li><strong>The next task message starts work:</strong> in this example the Downloads request is what lets the AI enter Coding and Safety.</li><li><strong>High-risk work still stops:</strong> moving many files is irreversible, so the AI must stop at the planning stage and wait for confirmation.</li></ul></div></div></section>
<section class="section" id="a-step-4"><div class="wrap"><span class="badge">Step 04 · Case A</span><h2>You confirm; the AI plans, reads, then changes code</h2><p class="narrative">After you approve the first small task, the AI loads Coding and Safety. It writes a plan before it writes code, scans real facts before it designs the script, and writes a dry-run option before it proposes a real file move.</p><div class="chat"><div class="bubble ai"><span class="who">AI · plan, then read</span><p><strong>Plan:</strong> sort <code>.pdf</code>, <code>.docx</code>, <code>.doc</code>, <code>.txt</code>, <code>.md</code>, <code>.rtf</code> and <code>.pages</code> as documents; <code>.jpg</code>, <code>.jpeg</code>, <code>.png</code>, <code>.gif</code>, <code>.webp</code>, <code>.heic</code> and <code>.svg</code> as images; <code>.dmg</code>, <code>.pkg</code>, <code>.exe</code>, <code>.msi</code>, <code>.deb</code> and <code>.rpm</code> as installers; <code>.zip</code>, <code>.tar</code>, <code>.gz</code>, <code>.7z</code> and <code>.rar</code> as archives; and unknown types as others. Put each under a year. Exclude shortcuts, hidden files and directories. Preserve collisions by adding <code>_1</code>, <code>_2</code>. Do not touch files outside <code>~/Downloads</code>.</p><p><strong>Before scanning:</strong> I will show this plan and wait for your “yes, continue” before I inspect the folder. The later approval for the preview is separate from this read-stage confirmation.</p><p><strong>Read:</strong> scan the actual folder for extensions, dates and a sample—not guesses. The sample contains a HEIC image, a PDF bank statement, a DMG installer, a ZIP archive and a screenshot. The scan finds 1,043 files.</p><p><strong>Change:</strong> write <code>~/Downloads-tidy/sort_downloads.py</code> with <code>--dry-run</code>. It prints where each file would go and moves nothing until a separate confirmation.</p><pre>~/Downloads/IMG_2837.HEIC (2025-04, image)<br>~/Downloads/bank-statement-2024-11.pdf (2024-11, document)<br>~/Downloads/Notion-2.0.41.dmg (2024-08, installer)<br>~/Downloads/design-backup.zip (2025-01, archive)<br>~/Downloads/Screenshot 2025-03-15.png (2025-03, image)</pre><p><strong>Ready to run the preview?</strong></p></div></div><div class="callout"><span class="label">Five stages</span><h3>Plan → read → change → check → approved execution</h3><ul><li><strong>Plan</strong> lists the goal, scope, acceptance checks and what is excluded. It is not “write code immediately”.</li><li><strong>Read</strong> collects facts from the real folder; the AI does not build a script from assumptions.</li><li><strong>Change</strong> writes the script and dry-run flag, but stops before the irreversible action.</li><li><strong>Check</strong> presents the preview and consequences.</li><li><strong>Approved execution</strong> happens only after your explicit acceptance.</li></ul></div></div></section>
<section class="section" id="a-step-5"><div class="wrap"><span class="badge">Step 05 · Case A</span><h2>Safety mode adds guardrails — a preview lists the move; you confirm the real action</h2><p class="narrative">Safety mode was loaded when the large move became clear. Irreversible actions—moving, deleting or overwriting files, Git reset, publication—must first state a plan. A large file move requires a preview list and explicit user confirmation. The AI may not do it quietly.</p>
<h3>What safety mode does in this step</h3><div class="chat"><div class="bubble user"><span class="who">You</span>OK, run the preview.</div><div class="bubble ai"><span class="who">AI · preview</span><pre>$ python sort_downloads.py --dry-run<br><br>==== Dry-run summary ====<br>Total scanned: 1,043 files<br>documents/2025/ 234 · documents/2024/ 178 · documents/2023/ 62<br>images/2025/ 198 · images/2024/ 134<br>installers/2025/ 48 · installers/2024/ 39<br>archives/2025/ 26 · archives/2024/ 21 · others/ 103<br><br>⚠️ 5 filename collisions will receive _1 / _2 suffixes.<br>⚠️ 0 files cross a disk partition.<br><br>Preview complete. No files moved. Type yes only if you accept the allocation.</pre><p>You may also ask to keep recent files—for example, files from the last seven days—in <code>~/Downloads</code> instead of moving them.</p></div><div class="bubble user"><span class="who">You</span>The list is fine. I accept it; perform the real action.</div><div class="bubble ai"><span class="who">AI · real action</span><pre>Moving 1,043 files...<br>[████████████████████████████████] 100% (1043/1043)<br><br>Moved: 1,043 · Renamed collisions: 5 · Failed: 0</pre><p>The Downloads folder now has five main categories with year subfolders. You can inspect it in your file manager.</p></div></div><div class="callout"><span class="label">Safety mode did three things</span><ul><li><strong>Preview is compulsory:</strong> moving more than 1,000 files cannot be a one-line action; first preview, list and explicit approval.</li><li><strong>The list is transparent:</strong> category counts, year distribution and collision handling are visible and adjustable.</li><li><strong>Secrets and destructive boundaries remain protected:</strong> commands such as <code>rm -rf</code> and <code>git reset --hard</code>, system-root paths, and force pushes have separate hard guards. A force push requires distinct approval and affected-ref checking.</li></ul></div></div></section>
<section class="section" id="bridge-step"><div class="wrap"><span class="badge">Practical · Governance Bridge</span><h2>After creating an important document — connect it so it does not become an orphan</h2><p class="narrative">Some documents are not ordinary drafts: a stock list, production guide, runbook, workflow, checklist or source of truth. A future AI needs to know their purpose, when to read and update them, and whether an older document already has the same role. You can nominate one document, or scan a repository for likely unconnected important documents.</p><div class="chat"><div class="bubble user"><span class="who">You</span>I just created <code>docs/production-guide.md</code>. Connect this document to Agent Handoff Kit.</div><div class="bubble ai"><span class="who">AI</span><p>I will first perform a read-only connection audit:</p><ol><li>Does the document state its purpose, scope and update timing?</li><li>Does <code>dev/PROJECT_INDEX.md</code> register it and say when to read it?</li><li>Does <code>dev/DOC_SYNC_REGISTRY.md</code> carry a matching sync obligation?</li><li>Do relevant workflows remind us to update this guide?</li><li>Does the handoff contain only current state and the log only this-session evidence?</li><li>Is there another production guide or an older source of truth?</li></ol><p>I will report connected items, gaps, proposed patches and decisions you must make. A repository scan produces candidates and gaps first; it does not silently repair, delete, rename or merge documents.</p></div></div><div class="callout"><span class="label">Two entry points</span><p>Say <code>Connect docs/production-guide.md to Agent Handoff Kit</code> or legacy form: <code>bridge governance docs/production-guide.md</code>. For discovery, say <code>Scan for important documents not connected to Agent Handoff Kit</code> or <code>scan for unbridged governance documents</code>. Scan results are candidates; only after you agree may the AI update an index, sync register or workflow.</p></div></div></section>
<section class="section" id="a-step-6"><div class="wrap"><span class="badge">Step 06 · Case A</span><h2>Wrap up — one phrase updates the handoff and prepares the next-session prompt</h2><p class="narrative">When you are ending the session, you do not need to remember which files to update. Say “收工”, “Wrap up Agent Handoff”, “wrap up”, or “handoff”. The AI detects closeout intent, reconciles the handoff, writes this session’s log evidence, and synchronises the next-session text into <code>START_NEXT_SESSION_PROMPT.txt</code>.</p>
<h3>Closeout triggers the full handoff sequence</h3><div class="chat"><div class="bubble user"><span class="who">You</span>Wrap up.</div><div class="bubble ai"><span class="who">AI · closeout</span><pre> /\_/\ Agent Handoff Kit vX.Y.Z<br> ( -.- ) handoff saved<br> > ^ <<br><br>✅ Completed: Downloads organiser finished; 1,043 files are in five categories with year subfolders<br>🔎 Checked: preview + real run + 0 failures<br>📌 Handoff: next-session prompt prepared<br>⚠️ Boundary: not yet published (README, version tag, GitHub push remain)</pre><p>I updated the handoff to “<code>sort_downloads.py</code> completed and executed”, recorded preview and execution evidence in the session log, and added the tool’s role to the project index. At the next session, a plain <code>Start Agent Handoff</code> shows this state; to continue immediately, include the next task in the same message or the next message. The next handoff prompt is synchronised; the handoff itself remains authoritative.</p><pre>Work in ~/Downloads-tidy. Read AGENTS.md first, then Start Agent Handoff.<br>Before changing anything, tell me the current state and your recommended next step.</pre></div></div><div class="callout"><span class="label">What closeout guarantees</span><ul><li><strong>Natural trigger phrases:</strong> “收工”, “Wrap up Agent Handoff”, “wrap up”, “handoff”, “end session” and “done for today” use the same closeout flow.</li><li><strong>Reconcile, do not append:</strong> current handoff state is rewritten against facts; new text is not simply added beneath old state.</li><li><strong>Prompt mirror:</strong> the next-session text is written to <code>START_NEXT_SESSION_PROMPT.txt</code> for convenience. It is not a second authority.</li><li><strong>Log maintenance:</strong> old log entries compact into an index and later archive, so ordinary startup need not read a growing log.</li></ul></div></div></section>
<section class="section" id="a-step-7"><div class="wrap"><span class="badge">Step 07 · Case A</span><h2>Next handoff and public release — the new conversation resumes state; work starts only with a task</h2><p class="narrative">A day later, you want a README, version tag and GitHub publication. Open a new AI conversation—perhaps a different tool such as Codex or Antigravity. A plain <code>Start Agent Handoff</code> first shows the state; if you want the AI to begin immediately, include the release task in the same message or the next message. The new AI reads the entry rules and authoritative handoff, so you do not repeat the background. A connected GitHub integration still does not authorise pushing, tagging or creating a release: each needs explicit approval.</p>
<h3>Handoff and public-release safeguards</h3><div class="chat"><div class="bubble user"><span class="who">You · next day</span><pre>Start Agent Handoff. Continue the release work: add a README, create the version tag, and prepare the GitHub push; wait for my step-by-step confirmation before any external write.</pre></div><div class="bubble ai"><span class="who">AI · continuation</span><pre>🔎 Handoff: loaded<br>📌 Current state: sort_downloads.py completed and executed (1,043 files moved)<br>✅ Verified: GitHub integration is connected<br>⚠️ Boundary: tag, push and release are irreversible and each require explicit approval<br>🚀 Recommended next step: load Release + Safety and plan</pre><p class="pills"><span class="release">Release</span> approve before a real tag or push <span class="safety">Safety</span> protect remote Git writes</p><p>The plan is to write <code>README.md</code>, initialise local Git and commit, create local <code>git tag v0.1.0</code>, then—with your separate confirmation—create a public or private <code>downloads-tidy</code> repository, push code and tag, create a release, and read the GitHub result back.</p></div><div class="bubble user"><span class="who">You</span>The plan is fine. Use a public repository named <code>downloads-tidy</code>.</div><div class="bubble ai"><span class="who">AI</span><p>The README, first local commit and local v0.1.0 tag are complete. Before I create the GitHub repository, push, and create the release, please confirm that separate irreversible operation.</p><p>After confirmation, the AI reports each result—repository creation, remote, main push, tag push and release—then reads back the GitHub page to confirm the commit, tag and release link agree.</p></div></div><div class="callout"><span class="label">Release safeguards</span><ul><li><strong>A new AI does not need your whole history:</strong> entry files and the handoff state tell it what happened, what is next and what risk remains.</li><li><strong>Cross-tool continuity:</strong> Claude today and Codex or Antigravity tomorrow can use the same handoff data; actual entry support follows the tool’s documentation and local verification.</li><li><strong>Connected integration plus readback:</strong> if GitHub is connected, the AI can execute and then read back the result; if it is not, it gives detailed manual steps.</li><li><strong>Two approvals:</strong> a plan approval is not a publication approval. A tag, push and release each require your clear go-ahead.</li><li><strong>Credentials stay separate:</strong> integration credentials live in the AI tool’s secure store, never in <code>dev/</code> governance files.</li></ul></div></div></section>
</div>
<div class="case case-content" data-case="b" hidden>
<div class="wrap rail"><a href="#b-step-1"><b>01</b>Prepare</a><a href="#b-step-2"><b>02</b>Start</a><a href="#b-step-3"><b>03</b>First response</a><a href="#b-step-4"><b>04</b>Align sources</a><a href="#b-step-5"><b>05</b>Write and share</a><a href="#b-step-6"><b>06</b>Wrap up</a><a href="#b-step-7"><b>07</b>Continue</a></div>
<section class="section" id="b-step-1"><div class="wrap"><span class="badge">Step 01 · Case B</span><h2>Prepare the data split and install</h2><p class="narrative">Unlike Case A, this research task has several sources. Before installing, decide which tool owns which kind of fact: Notion is the index, the local folder keeps original content, and Google Drive holds the final shareable deliverable. This example assumes Notion and Google Drive are connected, so the AI can read and write the Notion database, upload to Drive and set sharing permissions.</p>
<h3>Three tools, three roles</h3><div class="block"><div class="block-head"><span class="label">Three tools, three roles</span><span class="mono">source-of-truth boundary</span></div><div class="block-body"><pre>Notion (index database)<br>├── Title · Type (government report / competitor screenshot / interview audio / note)<br>├── Source (text or URL) · Date · Tags · one-sentence summary<br>└── Local path (points to a file under reference/)<br><br>Local ~/cafe-research/<br>├── AGENTS.md / CLAUDE.md / GEMINI.md (after install)<br>├── dev/ (handoff and governance)<br>├── reference/ (original PDFs, screenshots, recordings and notes)<br>└── report/ (draft and final report)<br><br>Google Drive<br>└── final .docx / .pdf and the share link for partners</pre></div></div><div class="callout"><span class="label">Why this matters</span><p>Notion does not replace the original local source; Drive does not replace current working evidence. The AI must name the source and destination before it writes to an external service.</p></div></div></section>
<section class="section" id="b-step-2"><div class="wrap"><span class="badge">Step 02 · Case B</span><h2>Start the handoff — state the tool split so the AI can begin research</h2><p class="narrative">If this is the first use, a plain <code>Start Agent Handoff</code> shows status, gives the short first-use welcome, and recommends the next step, but it still does not begin this report journey by itself. To begin this report journey, state the report goal and tool split in the same message or the next message. For example: research the local café market, use Notion as the index, compare local source files, write the report, and put the final shareable file in Drive.</p>
<h3>The task description explains the three-tool split</h3><div class="chat"><div class="bubble user"><span class="who">You</span><pre>Start Agent Handoff. I need a market-research report for a café. Notion is our source index, <code>~/cafe-research/reference/</code> holds originals, and Google Drive is the partner-facing destination.</pre></div><div class="bubble ai"><span class="who">AI · task routing</span><p>The goal and tool split are clear, so I will not make you choose a beginner menu. I will load Research, Knowledge and later Writing rules, and first list the read scope and external-write boundaries.</p></div><div class="bubble user"><span class="who">You</span><p>I want to research whether my own neighbourhood can support a café. Please write a ten-page market-research report whose conclusion answers “is this worth doing, and what should the next actions be?” The audience is me and my wife, and I also want to discuss it with an industry friend.</p><p>Data split: Notion has an index database with more than 30 reference items—government statistics, industry reports, competitor menu screenshots and interview notes. Each row has a “local path” pointing to the corresponding file under <code>~/cafe-research/reference/</code>. The local <code>reference/</code> folder already contains the matching PDFs, screenshots and notes. Please write the report draft into <code>~/cafe-research/report/</code>. When it is finished, please upload it to Google Drive, set sharing permissions for my partner, my wife and industry friend Mr Cheung—I can give you their email addresses later—and save the share link. I have already connected Notion and Google Drive, so you can read and write them directly.</p></div></div><div class="callout"><span class="label">What actually happens</span><h3>Why the task description names all three tools</h3><ul><li><strong>Plain start and task start are separate:</strong> on a fresh install, saying only start reads handoff state, shows status and gives the first-use welcome; once you state the report goal and data split, it can classify the scenario directly instead of asking again.</li><li><strong>External sources are not automatically visible:</strong> the AI does not know how your Notion database is designed or which field stores the local path. You state this in the task so it can read correctly.</li><li><strong>You explicitly ask the AI to act for you:</strong> saying “please upload to Google Drive and set sharing permissions” tells the AI that you expect it to perform the connected-tool action, not merely list manual steps.</li><li><strong>The report goal is clear:</strong> length, conclusion direction and readers—yourself, your wife and an industry friend—are stated, so the AI can adjust depth and tone.</li></ul></div></div></section>
<section class="section" id="b-step-3"><div class="wrap"><span class="badge">Step 03 · Case B</span><h2>First AI response — load Research and Knowledge; plan to read both Notion and the local folder</h2><p class="narrative">The startup card is the same as Case A: version text and the Handoff loaded marker. This time the work-mode combination is different. A research task loads <strong>Research</strong> mode for source discipline and separation of fact from inference, plus <strong>Knowledge</strong> mode for source-of-truth and external-write readback. The AI also confirms that Notion and Google Drive are connected, so it can directly read and write the relevant data.</p>
<h3>Startup is the same, but the mode combination reflects the task</h3><div class="chat"><div class="bubble ai"><span class="who">AI (started from AGENTS.md)</span><pre> /\_/\ Agent Handoff Kit vX.Y.Z<br> ( o.o ) continuity ready<br> > ^ <<br><br>🔎 Handoff: loaded<br>📌 Current state: new project; the handoff has no previous session record yet<br>✅ Verified: your AI tool has Notion and Google Drive connected, so I can read and write directly<br>🚀 Next step: load working modes and enter planning; first align the Notion index with local references</pre><p>I have read the entry files, the empty handoff, the project-index template and the rule-pack router. Based on the task, I will load these working modes:</p><p class="pills"><span class="research">Research</span> source dates, facts and inferences stay separate <span class="knowledge">Knowledge</span> external sources: reachable is not the same as read; unread sources must be marked pending</p><p>The workflow I will use next is heavier than Case A because it spans several sources:</p><p class="loop">Plan (list which sources must be aligned and which sections will be written)<br>→ Read (row by row, match Notion index entries to local reference files and identify gaps)<br>→ Change (write the report draft into <code>report/</code>)<br>→ Check (each claim has a citation; subjective inference is labelled)<br>→ Output the report and check results</p><p>I will first enter the planning stage and do two things:</p><ol><li>List how I will align the Notion index with local references, and how I will handle “Notion has a record but no local file” or “local file exists but Notion has no record”.</li><li>List the ten-page report structure and wait for your confirmation before writing.</li></ol><p><strong>Do you confirm that I should enter planning?</strong></p></div></div><div class="callout"><span class="label">What actually happens</span><h3>Startup is the same, but the mode combination reflects the task</h3><ul><li><strong>Research and Knowledge load together:</strong> the source, research-question and cross-tool-sync signals are all present, so both modes load automatically.</li><li><strong>External integrations are verified before use:</strong> the AI says Notion and Google Drive are connected and can be read/written before acting; it does not assume this silently.</li><li><strong>The reading stage becomes heavier:</strong> with multiple sources, reading is not a quick sample scan. The AI aligns each item and lists any unread reference as pending instead of skipping it.</li></ul></div></div></section>
<section class="section" id="b-step-4"><div class="wrap"><span class="badge">Step 04 · Case B</span><h2>You confirm; the AI aligns Notion and local sources and exposes gaps</h2><p class="narrative">The AI reads the actual index and local tree. In this example it finds 32 indexed rows: 24 Notion records match readable local originals, five indexed files are missing locally, and three local files are not registered in Notion—so 27 local source files are available once those three are considered. It reports the mismatch instead of silently treating all 32 as reliable evidence.</p>
<h3>Reachable does not mean read and aligned</h3><div class="facts"><div class="fact"><b>32</b>Notion index rows</div><div class="fact"><b>27</b>local source files available (24 matched + 3 unregistered)</div><div class="fact"><b>5</b>indexed files missing locally</div><div class="fact"><b>3</b>local files not registered in Notion</div></div><div class="chat"><div class="bubble ai"><span class="who">AI · source-alignment result</span><p>For the <strong>five indexed records whose local originals are missing</strong>, you choose one of three dispositions: (1) <strong>mark them pending</strong> in the project index, and label the affected report conclusions tentative; (2) <strong>pause and wait</strong> while you recover and place the five files in <code>reference/</code>; or (3) <strong>draft from the existing 27 available sources first</strong>, then revise the affected sections when the files arrive. I do not choose for you.</p><p>The <strong>three local files that Notion has not registered</strong> are a separate issue, not a fourth way to handle the missing five. In this case, you choose option 1 for the five missing originals: I record them as pending in the project index and mark the affected report conclusions tentative. You then authorise me to write the three unregistered local sources directly into the Notion “Cafe Research Index”. I write all three rows, then read each row back to confirm its fields and local path. After that, I prepare the ten-page outline: one-page summary; 1.5 pages of industry context; 1.5 pages of community demand; two pages of five nearby competitors; one page of site analysis; 1.5 pages of costs; and 1.5 pages of conclusion and next action.</p></div></div><div class="callout"><span class="label">Reachable is not ingested</span><p>An integration listing, search hit or path is not proof that this task read and understood the source. This step is what prevents sources quietly falling out of the report.</p></div></div></section>
<section class="section" id="b-step-5"><div class="wrap"><span class="badge">Step 05 · Case B</span><h2>Write the report — Writing mode adds discipline; Drive upload is an explicit AI action</h2><p class="narrative">After the source set and outline are accepted, the AI adds Writing mode. It drafts from verified sources, labels tentative conclusions, creates the requested formats, and treats the Drive upload as an external write with a destination and readback.</p>
<h3>Writing mode and external-write discipline</h3><div class="chat"><div class="bubble ai"><span class="who">AI · writing and delivery</span><p class="pills"><span class="writing">Writing</span> structure, citations and plain conclusions</p><p>The draft is <code>report/report-draft.md</code>: 10.3 pages, 2,847 words, four tables and 24 citations. Its conclusion is “worth doing, but begin with a six-month pop-up/shared-kitchen trial rather than immediately renting an independent shop”: community purchasing power is sufficient, competitor density is moderate, and initial capital risk is controllable. The five unavailable sources affect two sub-sections, each marked <strong>tentative pending review when the material is recovered</strong>.</p><p>I then ask which format you want: <code>.docx</code> for Microsoft Word/Google Docs, <code>.pdf</code> for printing or a direct share link, or <code>.html</code> for browser reading. You choose <code>.docx</code>, so I create <code>report/report-final.docx</code>.</p><p>After that confirmation, I upload this DOCX to the agreed Drive folder, grant <strong>viewer</strong> access to the three named recipients—partner <code>partner@example.com</code>, spouse <code>wife@example.com</code>, and industry friend Mr Cheung <code>cheung@example.com</code>—and read back both the file information and permissions, including the viewer link: <code>https://drive.google.com/file/d/.../view</code>.</p><ul><li>Local final: <code>~/cafe-research/report/report-final.docx</code></li><li>External result: Drive upload and share link are read back, not assumed.</li><li>Credential boundary: no Drive credential is copied into <code>dev/</code>.</li></ul></div></div><div class="callout"><span class="label">Writing and external-write discipline</span><ul><li><strong>Writing mode</strong> does not make uncertain evidence certain.</li><li><strong>Format checks</strong> let you inspect DOCX, PDF and HTML before external sharing.</li><li><strong>Readback</strong> proves the file and viewer link correspond to the intended final report.</li><li><strong>Unconnected fallback</strong> is a local final file and manual upload instructions—not a false claim that Drive was updated.</li></ul></div></div></section>
<section class="section" id="b-step-6"><div class="wrap"><span class="badge">Step 06 · Case B</span><h2>Wrap up — the same closeout flow as Case A, with the shared link recorded</h2><p class="narrative">Closeout is the same mechanism, but its state is specific to this external deliverable: the final report path, Drive viewer link, source gaps, five pending items and the date by which they need verification. The handoff does not pretend a missing integration was completed.</p>
<h3>Closeout is the same flow, with concrete external state</h3><div class="chat"><div class="bubble ai"><span class="who">AI · closeout summary</span><p>Completed: source reconciliation, the 10.3-page draft and final DOCX, a verified Drive upload and viewer link. The reconciled handoff records <code>report/report-final.docx</code>, the link shared with the partner, spouse and Mr Cheung, and “wait for partner feedback” as the next step. The session log records the three Notion rows written and read back, five pending sources, the outline, 24 citations, and the Drive upload/share result. The project index records 32 ingested references, five pending references, the report location, Drive folder, and that the connected Notion and Google Drive integrations were successfully verified <strong>today</strong>. At the next session, a plain <code>Start Agent Handoff</code> shows this state; to continue immediately, include the next task in the same message or the next message. The next-session prompt preserves the same facts.</p></div></div><div class="callout"><span class="label">Same closeout, concrete external state</span><p>The current handoff, session log, index and prompt mirror still reconcile as in Case A. What changes is the verifiable fact recorded: local deliverable, external destination, readback, unresolved sources and fallback if an integration was not connected.</p></div></div></section>
<section class="section" id="b-step-7"><div class="wrap"><span class="badge">Step 07 · Case B</span><h2>Next handoff — revise the report after partner feedback</h2><p class="narrative">A few days later, you have shared the report link with your partner. They feel the six-month trial’s startup-capital estimate is still too high and want to see a lighter three-month version. You open a new AI conversation, type <code>Start Agent Handoff</code> plus the new request, and the new AI resumes the previous state, reloads Research and Writing, and plans the report revision.</p>
<div class="chat"><div class="bubble user"><span class="who">You · new conversation a few days later</span><pre>Start Agent Handoff<br>Also make a lighter three-month “pop-up + shared kitchen” version.</pre></div><div class="bubble ai"><span class="who">AI · handoff</span><pre> /\_/\ Agent Handoff Kit vX.Y.Z<br> ( o.o ) continuity ready<br> > ^ <<br><br>🔎 Handoff: loaded<br>📌 Current state: the 10.3-page final report has been delivered to the partner; the share link is recorded<br>🎯 New request: add a three-month pop-up + shared-kitchen alternative<br>⚠️ Boundary: five references are still pending and affect two sub-sections; they do not directly block this new alternative<br>🚀 Next step: reload Research and Writing modes, then enter planning</pre><p>I first read the authoritative handoff. I read the session log only if this trace is needed, and load the project index only for this task. I now know:</p><ul><li>the capital-expenditure structure and assumptions of the original six-month plan;</li><li>the scope of the five pending references, which affect two sub-sections and do not overlap with this new request;</li><li>the partner’s main feedback: capital expenditure must be lower.</li></ul><p>I will reload the same working modes as last time:</p><p class="pills"><span class="research">Research</span> <span class="knowledge">Knowledge</span> <span class="writing">Writing</span></p><p>Plan:</p><ol><li>Select three to four references related to “pop-up shop / shared kitchen” from <code>reference/</code>; I will use tags in the Notion index to find them.</li><li>Calculate the three-month capital expenditure: mainly market-stall rent or shared-kitchen monthly fees, plus equipment and initial stock, instead of renting a shop.</li><li>Add a sub-section in the report’s “Conclusion and next action” chapter: “Alternative B: three-month pop-up plus shared kitchen”.</li><li>Add one summary sentence comparing the trade-off between the main six-month plan and Alternative B’s three-month path.</li></ol><p><strong>Is this plan OK?</strong></p></div><div class="bubble user"><span class="who">You</span>Yes, do it.</div><div class="bubble ai"><span class="who">AI · write and complete</span><p>Done. The new sub-section is added to the conclusion chapter, 1.4 pages in total. I have exported <code>report/report-v2.docx</code>. I can upload it to Google Drive to replace the original file, or create a new version file—which do you prefer?</p><p>Difference summary compared with the first version:</p><ul><li>Added 1.4 pages for the new alternative-plan sub-section.</li><li>Added one conclusion paragraph comparing the two paths.</li><li>Added four new reference footnotes from the original 27 ingested references, without using the five pending references.</li></ul><p>When you are ready, you can wrap up; I will update the handoff to record that version two exists and that the same five references remain pending.</p></div></div><div class="callout"><span class="label">What actually happens</span><h3>The value of multi-turn handoff</h3><ul><li><strong>No need to repeat the background:</strong> the new AI reads the entry files and handoff, then knows where the report stands, what the conclusion is, which references are pending, and what the partner’s feedback is. You only state the new request.</li><li><strong>Consistent across tools:</strong> today may be Claude; next time may be Codex or Antigravity. The same handoff data still applies.</li><li><strong>Citation discipline continues:</strong> the new section still follows Research mode: every claim has a citation, and facts are separated from inference.</li><li><strong>Missing items stay visible:</strong> the five pending references remain in the project index across conversations; they do not quietly disappear. A third future handoff will still see them.</li></ul></div></div></section>
</div>
<div class="case case-content" data-case="c" hidden>
<div class="wrap rail"><a href="#c-phase-1"><b>Day 1</b>first project</a><a href="#c-phase-2"><b>Day 30</b>evolves</a><a href="#c-phase-3"><b>Day 60</b>decisions</a><a href="#c-phase-4"><b>Day 90</b>look back</a></div>
<section class="section" id="c-disclaimer"><div class="wrap"><span class="badge">Case C · time line</span><h2>This case spans months, not a daily ritual</h2><p class="narrative">The first two cases show a bounded task. This case shows how the same project survives multiple conversations, changing requirements and accumulated decisions. The user supplies goals and feedback; the AI handles research, technical work, verification and delivery. It does not mean every day requires a ceremony.</p></div></section>
<section class="section" id="c-phase-1"><div class="wrap"><span class="badge">Day 1</span><h2>Start a new project — the first task description enters the handoff</h2><p class="narrative">In an AI editing-assistant project, the user asks for the simplest usable version: proofread Markdown text and offer style suggestions, taking text as input and returning suggested edits. Coding and Research are relevant, so the AI reads only the routed rules, records this exact task and first evidence, and leaves the decision log empty. This is still a short-term signal set: conversation count is 1, the current objective is simple and clear, and accumulated confirmed decisions are 0. The long-term structure already exists from installation; when the project later evolves, the AI can begin recording it without rebuilding files.</p>
<h3>Why the decision log is empty on day one</h3><div class="chat"><div class="bubble user"><span class="who">You</span>Start Agent Handoff. I want to develop an AI editing assistant: start with the simplest usable version, supporting Markdown only. It should take text as input and return proofreading and style suggestions.</div><div class="bubble ai"><span class="who">AI</span>I will record the current objective, load Coding and Research for this task, inspect the existing project before changing it, and keep the decision log empty unless a durable choice is actually confirmed.</div></div><div class="callout"><span class="label">Why the decision log is empty on Day 1</span><p>A task description is not automatically a long-term decision. The handoff records active state; a durable decision needs alternatives, a selection and a reason someone may need later.</p></div></div></section>
<section class="section" id="c-phase-2"><div class="wrap"><span class="badge">Day 30</span><h2>The requirement evolves — the AI detects a substantive turn and adds a long-term record</h2><p class="narrative">After five to six turns, the requirement evolves from Markdown proofreading into Markdown + LaTeX + code-comment proofreading, then adds collaborative editing. During the same period the team connects a Slack channel for internal feedback and Linear for task tracking; the AI registers those two tools in the project index, but they are not the product’s new purpose. The current objective now differs materially from Day 1, so the AI records a concrete long-term-evolution entry: Day 1’s Markdown-only objective; LaTeX in turn 2; code-comment proofreading in turn 4; collaborative editing in turn 6; the driver (Markdown alone proved insufficient for technical writing); and the impact (the backend model’s handling of multi-syntax context must be reassessed). It sees six conversations and four accumulated decisions. A minor extension such as one extra syntax alone is not the trigger; a change in the project’s core positioning is. Long-term records also become more proactive when at least one signal appears: four or more conversations, current-objective drift, ten or more accumulated decisions, or a user asking “why did we do this before?”</p>
<h3>What qualifies as substantive evolution</h3><div class="callout"><span class="label">What counts as substantive evolution</span><ul><li>The goal, users, ownership, external boundary or architecture changed.</li><li>There were at least two meaningful options and a selected path with a reason.</li><li>A future AI or teammate would otherwise have to rediscover why the decision was made.</li></ul></div></div></section>
<section class="section" id="c-phase-3"><div class="wrap"><span class="badge">Day 60</span><h2>Decisions accumulate — at 30 confirmed decisions, older entries are archived</h2><p class="narrative">The confirmed-decision threshold reaches 30. This is a hard maintenance boundary: at 30 or more confirmed decisions the AI must archive, while keeping 8–22 related active decisions in the handoff according to content continuity. In this instance it keeps the newest 12 decisions (#21–#32) in current state and moves #1–#20 into the decision archive, newest archived entry first, retaining a short index so the past remains retrievable. In the same period it records a real backend A/B/C trade-off: A costs less but has shorter context; B costs more but retains longer context; C is faster but has weaker format control. It selects B because proofreading code comments needs longer context and B is more stable on this project’s test samples. The impact is a backend API rewrite and prompt-template changes—not a vague record buried in chat. This architecture record is created only when all three conditions exist: the plan lists two or more viable paths, one is selected, and the reason is recorded. A bare “I choose A or B” without rationale does not trigger it.</p>
<h3>Archive without losing traceability</h3><div class="facts"><div class="fact"><b>32 → 12</b>active decisions retained in the hot tier</div><div class="fact"><b>20</b>older decisions archived with an index</div><div class="fact"><b>A / B / C</b>options, selection, rationale and consequences recorded</div></div><div class="callout"><span class="label">Archive without erasing</span><p>The current state stays small enough to use, but the reasons remain retrievable. Archiving is maintenance, not a license to delete the history that explains a later choice.</p></div></div></section>
<section class="section" id="c-phase-4"><div class="wrap"><span class="badge">Day 90</span><h2>Look back — you ask “why did we choose option B?” and the AI traces the history</h2><p class="narrative">The AI follows the three layers in order: current handoff state, the decision log and then the session-log archive. It answers why B was selected, what A and C would have changed, and which evidence or constraint still matters. It does not invent a retrospective answer from a summary.</p>
<h3>Complete retrospective path</h3><div class="chat"><div class="bubble user"><span class="who">You</span>Why did we choose option B earlier?</div><div class="bubble ai"><span class="who">AI</span>I found the current boundary in the handoff, then the confirmed A/B/C decision, then the source session evidence. Option B was selected because code-comment proofreading needs longer context and B was more stable on this project’s test samples. A was cheaper but had shorter context; C was faster but had weaker format control. The change required a backend API rewrite and prompt-template updates. I will show the record and any uncertainty instead of presenting a guess as history.</div></div><div class="callout"><span class="label">Complete retrospective path</span><p>Current state tells the AI what matters now. The decision log tells it why durable choices were made. The session-log archive supplies older evidence when the answer cannot be supported by current summaries alone.</p></div></div></section>
</div>
</main>
<section class="outro"><div class="wrap"><h2>After all three cases, the same <span class="accent">flow</span> works for different tasks</h2><p>The AI reads the install page to decide whether to install or upgrade, or you install manually in the terminal — you open a new AI conversation to start the handoff — a fresh first start recovers state, gives the short first-use welcome and recommends the next step, while an existing-project start stays status-only — work begins only when there is a task — the planning stage stops for your confirmation — Safety, Knowledge and Writing rules load when the task needs them — when you are ending the session, one wrap-up phrase writes the next-session prompt — a later conversation can recover the state with “start”. Case A and Case B each have seven steps, while Case C evolves across months, but the backbone is the same across cases, tools and days.</p><p>For your third or fourth task — a newsletter, stock-market observation, or invoices across several projects — the flow is still the same. The working mode changes with the task, but your habit stays consistent: <strong>start to recover state and any first-use welcome, state the task, confirm the plan; wrap up when you are ending the session</strong>.</p><p>One more recommendation: if you want durable baseline rules for how an AI behaves <strong>inside a single conversation</strong>—tone, priority, response structure, safety guardrails and output-layer split—use <a href="https://github.com/prompt-templates/Adam-AI-Instructions" target="_blank" rel="noopener">Adam-AI-Instructions</a> alongside this kit. In that repository, choose the suitable version from “五、提示詞索引”, copy the matching <code style="font-family:var(--font-mono);">prompt.md</code>, and paste it into your AI tool settings. Agent Handoff Kit manages continuity <strong>between conversations</strong>; Adam-AI-Instructions manages <strong>single-conversation quality</strong>. They do not overlap.</p><a href="agent-handoff-kit-intro.en.html">Back to the 60-second beginner intro →</a><a class="alt" href="local-agentic-ai-workflow-case-study.en.html">See the local Agentic AI workflow case study →</a><a class="alt" href="https://github.com/Adamchanadam/agent-handoff-kit#readme">Read README on GitHub →</a><a class="alt" href="https://github.com/prompt-templates/Adam-AI-Instructions">Read Adam-AI-Instructions →</a></div></section>
<footer><div class="wrap"><div><strong>Agent Handoff Kit · Practical Guide</strong><p>This page combines the Agent Handoff Kit flow with three everyday scenarios so a non-technical beginner can recognise how it feels in real work. The official README and 60-second intro page remain the source for exact product details.</p></div><div><strong>Main documents</strong><p><a href="agent-handoff-kit-intro.en.html">Beginner introduction</a><br><a href="local-agentic-ai-workflow-case-study.en.html">Local Agentic AI workflow case study</a><br><a href="https://github.com/Adamchanadam/agent-handoff-kit">README on GitHub</a><br><a href="https://github.com/prompt-templates/Adam-AI-Instructions">Adam-AI-Instructions</a></p></div><div><strong>Version</strong><p>v0.3.64 · MIT License</p></div><div><strong>Author</strong><p>Adam Chan<br><a href="https://www.facebook.com/chan.adam" target="_blank" rel="noopener">Facebook</a></p></div></div></footer>
<script>
const tabs = document.querySelectorAll('.tab, .case-tab');
const showCase = (targetCase) => {
for (const btn of tabs) {
const active = btn.dataset.case === targetCase;
btn.setAttribute('aria-selected', String(active));
btn.classList.toggle('active', active);
}
for (const panel of document.querySelectorAll('.case, .case-content')) {
panel.hidden = panel.dataset.case !== targetCase;
}
};
for (const btn of tabs) {
btn.addEventListener('click', () => showCase(btn.dataset.case));
}
const init = document.querySelector('.tab[aria-selected="true"], .case-tab[aria-selected="true"]');
if (init) showCase(init.dataset.case);
</script>
</body>
</html>