Install — one instruction creates the handoff files in the folder
You can give this first step to an AI agent that can read and write the local folder. Create an empty folder such as ~/Downloads-tidy, 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.
$ npx --yes @adamchanadam/agent-handoff-kit@latest init 📋 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. create: 21 AGENTS.md CLAUDE.md GEMINI.md START_NEXT_SESSION_PROMPT.txt dev/SESSION_HANDOFF.md dev/SESSION_LOG.md dev/PROJECT_INDEX.md dev/DOC_SYNC_REGISTRY.md dev/RULE_PACKS.md dev/PROJECT_DECISIONS.md dev/rules/safety.md dev/rules/coding.md dev/rules/onboarding.md dev/rules/integrations.md ... (the remaining working-rule files) Continue? (yes/no): yes ✅ created: 21 🔀 merged: 0 ⏭️ skipped existing: 0 📦 Version: v0.3.66 🛠️ Mode: first-install 🔎 Just finished: init; create 21 / merge 0 / skip 0 / conflict 0. 🚀 Next: leave the terminal and open your AI tool to start Agent Handoff. ============================================================ ✅ Installation complete: the next step belongs in AI chat ============================================================ ⚠️ The following phrase is not a terminal command. 📋 Open an AI agent that can read and write this folder. If it is already in this folder, start a new conversation and enter: Examples: Claude Code, OpenAI Codex, Gemini CLI, Google Antigravity. Ordinary web-chat AI without local-folder access is not suitable. ------------------------------------------------------------ Start Agent Handoff or: 開工 ------------------------------------------------------------ Only if the AI is not yet pointed at this folder: 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. ------------------------------------------------------------ 🚀 The AI follows AGENTS.md to verify this folder. A plain start after a fresh install shows state, risks and a recommended next step, then gives a short first-use welcome. A plain start after an existing-project upgrade remains status-only. Only when the same message states a concrete task may it classify the task and begin the first safe step. ============================================================
This creates the complete handoff file set
- Three entries, one rule set:
AGENTS.md,CLAUDE.mdandGEMINI.mdare created together so common AI tools return to the same rules. Antigravity CLI readsAGENTS.mdandGEMINI.mdin the working folder;GEMINI.mdis a bridge, not a separate rule set. - The AI install page confirms the folder first: when the AI installs for you, it must display the current folder and ask you to confirm. Before confirmation it should not run
init,upgradeordoctor. - The next line is not a terminal command: the output marks this with ⚠️. A common beginner mistake is entering
Start Agent Handoffor the path-bearing startup phrase in the terminal instead of AI chat. - Important documents can be connected: after an AI creates a stock list, production guide, workflow or checklist, say
Connect docs/example.md to Agent Handoff Kitso it checks the index, sync responsibilities and relevant workflow. - Check only when uncertain: normally open AI chat directly after installation. If you later doubt file completeness, run
npx --yes @adamchanadam/agent-handoff-kit@latest doctor. A temporarily laggingSTART_NEXT_SESSION_PROMPT.txtproduces a reminder; synchronise it when ending the session.
Start the handoff — first start can onboard; a task starts work
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 Start Agent Handoff or 開工. 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 control the calling conversation’s title, the AI may use already-loaded facts to replace a generic or stale title with <project name>｜<primary action>; readback helps preserve an informative title when available, but is not required if the tool safely targets the calling conversation. Unsupported control is skipped silently; no extra file or network reads are made. 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.
Start Agent Handoff
The start phrase is not automatic execution authority
- A plain fresh start can include onboarding: 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.
- A same-message task can start: 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.
- Later guidance needs a real signal: 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.
When you enter only the start phrase — first use welcomes, then waits
Here the user entered only Start Agent Handoff and the fresh handoff has no objective. The response is not a menu or a plan: it shows state and a recommended next step, adds a short first-use welcome, and ends the turn. The user must provide a task in the next message or include it in the original startup message.
/\_/\ Agent Handoff Kit vX.Y.Z ( o.o ) continuity ready > ^ < 🔎 Handoff state: fresh install 📌 Current objective: not set ⚠️ Boundary: none 🚀 Next: tell me what you want to do; for example, “tidy Downloads and show me a preview list first”.
I have read that this is a fresh install with no task objective, so here is a short first-use welcome. Tell me a concrete goal in your next message. I will choose the working rules; high-risk actions still need your approval.
I want to tidy ~/Downloads. It has one or two years of mixed files, more than a thousand. Sort them into documents, images, installers, archives and others, with a year subfolder in each category. Ideally make a small reusable tool. I must see the preview list before any real move.
You have supplied a clear task, folder, sorting direction and safety boundary. If durable state must survive another conversation, I will use the smallest appropriate home under the persistence rules; receiving a task does not itself update every handoff file. The first bounded task is:
Build a reusable Downloads organiser and produce the preview list only; do not move files yet.
Reason: a large file move needs a reviewable preview. Real execution follows only after you approve its result.
You already requested this safe, reversible tool and preview, so I will load the working modes directly:
Coding write the Downloads tool
Safety list the bulk-move preview for your approval before execution; no silent moves or overwrites
The workflow is:
Plan (sorting rules, folder structure and preview scope)
→ Read (scan folder samples)
→ Change (write the script and preview mode)
→ Check (you inspect the preview list)
→ Real execution (move only according to the list you approve)
First scope check: this step ends with the tool and preview list; the real move needs separate approval. That matches your request, so I will begin. I ask a scope question only if something remains unclear.
Three default behaviours
- A plain first start can include a welcome: the AI does not load every rule or turn empty state into a task plan; it adds a short welcome after the status card.
- The next task message starts work: the Downloads request is what routes this example into Coding and Safety.
- High-risk work still stops: before a bulk move, list real paths and impact and obtain explicit approval. A requested read-only preview needs no repeated permission.
The scope is clear; the AI plans, reads and writes the tool
This example separates real movement from safe preview. You already requested the tool and preview, so the AI can read, write code and check it. The additional replies below are illustrative conversation, not mandatory approvals at every step. The real move of more than a thousand files still needs separate explicit authorisation against the preview list.
Agreed. Build the reusable tool and preview list first; do not move files.
Sorting rules (five categories):
- documents/ — .pdf .docx .doc .txt .md .rtf .pages
- images/ — .jpg .jpeg .png .gif .webp .heic .svg
- installers/ — .dmg .pkg .exe .msi .deb .rpm
- archives/ — .zip .tar .gz .7z .rar
- others/ — anything not classified above
Subfolders: use the file’s last-modified year within each category, for example documents/2025/ and documents/2024/.
Names: preserve original filenames; add numerical suffixes (_1, _2) for collisions.
Preview scope: scan the entire ~/Downloads folder; do not follow shortcuts or process hidden files.
I will now scan within your authorised scope, write the script and run a preview for you. The real move still waits for your explicit approval after inspection.
Yes, continue.
The scan found 1,043 files in ~/Downloads. Five random samples:
~/Downloads/IMG_2837.HEIC (2025-04, image) ~/Downloads/銀行月結單_2024-11.pdf (2024-11, document) ~/Downloads/Notion-2.0.41.dmg (2024-08, installer) ~/Downloads/設計稿備份.zip (2025-01, archive) ~/Downloads/Screenshot 2025-03-15.png (2025-03, image)
I wrote ~/Downloads-tidy/sort_downloads.py with a --dry-run option. The preview prints where each file would go and moves nothing.
You already requested the preview, so I will run it now and show the list next.
Plan → read → change → check → approved execution
- Planning: state the goal, scope, acceptance and exclusions. Proceed with a clear authorised preview; ask separately only for a real choice or a high-risk action.
- Reading: collect facts by scanning the actual folder and samples, not by guessing before writing the script.
- Changing: write the script, add and run safe preview mode; pause before the real move for explicit approval.
Safety mode adds guardrails — a preview lists the move; you confirm the real action
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.
What safety mode does in this step
$ python sort_downloads.py --dry-run
==== Dry-run summary ====
Total scanned: 1,043 files
documents/2025/ 234 · documents/2024/ 178 · documents/2023/ 62
images/2025/ 198 · images/2024/ 134
installers/2025/ 48 · installers/2024/ 39
archives/2025/ 26 · archives/2024/ 21 · others/ 103
⚠️ 5 filename collisions will receive _1 / _2 suffixes.
⚠️ 0 files cross a disk partition.
Preview complete. No files moved. Type yes only if you accept the allocation.
You may also ask to keep recent files—for example, files from the last seven days—in ~/Downloads instead of moving them.
$ python sort_downloads.py
Moving 1,043 files...
[████████████████████████████████] 100% (1043/1043)
Moved: 1,043 · Renamed collisions: 5 · Failed: 0
The Downloads folder now has five main categories with year subfolders. You can inspect it in your file manager.
- Preview is compulsory: moving more than 1,000 files cannot be a one-line action; first preview, list and explicit approval.
- The list is transparent: category counts, year distribution and collision handling are visible and adjustable.
- Secrets and destructive boundaries remain protected:
rm -rf,git reset --hardand system-root operations are prohibited. A force push requires separate explicit authorisation and verification of the affected refs.
After creating an important document — connect it so it does not become an orphan
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.
docs/production-guide.md. Connect this document to Agent Handoff Kit.I will first perform a read-only connection audit:
- Does the document state its purpose, scope and update timing?
- Does
dev/PROJECT_INDEX.mdregister it and say when to read it? - Does
dev/DOC_SYNC_REGISTRY.mdcarry a matching sync obligation? - Do relevant workflows remind us to update this guide?
- Does the handoff contain only current state and the log only this-session evidence?
- Is there another production guide or an older source of truth?
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.
Say Connect docs/production-guide.md to Agent Handoff Kit or legacy form: bridge governance docs/production-guide.md. For discovery, say Scan for important documents not connected to Agent Handoff Kit or scan for unbridged governance documents. Scan results are candidates; only after you agree may the AI update an index, sync register or workflow.
Wrap up — one phrase reconciles the handoff and prepares the next-session prompt
When ending the session, you do not need to remember the files. Say “收工”, “Wrap up Agent Handoff”, “wrap up” or “handoff”. The AI detects closeout intent, reconciles the handoff, records this session in the log, and compares the opening message with START_NEXT_SESSION_PROMPT.txt. It regenerates that mirror only when the content differs.
Wrap up.
I first reconstructed the parent outcome, current child task, resume point, remaining acceptance and source-reading coverage from the packet alone, then compared that reconstruction with the original request and sources actually read this session. The existing Reconstruction evidence cites the supporting sections. The tool and sorting are complete; publication has not started. Workspace, required persistence and the prompt mirror are checked.
I then actually run this command and copy its card. The following is a successful-output illustration; if a real run reports blocked, report that result faithfully instead of pasting the success card.
$ npx --yes @adamchanadam/agent-handoff-kit@latest closeout-status --root ~/Downloads-tidy
/\_/\ Agent Handoff Kit vX.Y.Z ( -.- ) handoff saved > ^ < status: complete ✅ Completed: Downloads organiser complete; 1,043 files sorted into five categories and year folders 🔎 Checks: preview + real run + zero failures 📌 Handoff: next-session opening message ready ⚠️ Boundary: publication pending (README, version tag and GitHub push)
This means the handoff is saved, not that every follow-up task or publication is complete. I have:
- Updated the handoff state to “
sort_downloads.pycompleted and executed”, with README, version tag and GitHub publication listed as the next task. - Added a session-log entry with the preview summary, actual execution result and local version evidence.
- Registered the role of
sort_downloads.pyin the project index.
Next time, say Start Agent Handoff or “開工” in the same project to recover state. To work immediately, state the next task in the same or following message. The actual opening message is synchronised with START_NEXT_SESSION_PROMPT.txt.
Only when the next AI is not pointed at this folder, use the path-bearing fallback:
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.
Closeout triggers the full handoff sequence
- Natural closeout: “收工”, “Wrap up Agent Handoff”, “wrap up”, “handoff”, “end session” and “done for today” route to the same procedure; no long command to remember.
- Reconciled state: do not append new state below old state. Reconcile each affected section against current facts instead of putting a new date on an old snapshot.
- Prompt mirror: the convenience copy carries the opening message; a new conversation does not require manually pasting the whole file. The handoff remains authoritative.
- Threshold-based log maintenance: check maintenance triggers at closeout. Organise or archive only when a threshold applies; otherwise record no maintenance needed. Ordinary startup does not read the log.
Next handoff and public release — recover state, then start the explicit task
A day later you want a README, a version tag and GitHub publication. Open a new AI conversation, perhaps with Claude again or with Codex or Antigravity. Start Agent Handoff or “開工” alone recovers state; to begin, state the release task in the same or following message. The new AI reads entry rules and the authoritative handoff instead of requiring the background again. Even with GitHub connected, commits, tags and external publication require explicit scoped authorisation.
Start Agent Handoff. Continue release work: add a README, create a version tag and prepare a GitHub push; wait for my step-by-step confirmation before external writes.
/\_/\ Agent Handoff Kit vX.Y.Z ( o.o ) continuity ready > ^ < 🔎 Handoff: loaded 📌 Current state: sort_downloads.py complete and executed (1,043 files moved) ✅ Verified: this AI tool has a connected GitHub integration for repo creation and push ⚠️ Boundary: tags, pushes and releases require explicit scoped approval 🚀 Next: load Release and Safety and prepare the plan
I have read the previous handoff. Today’s objective is a README, version tag v0.1.0 and GitHub publication. I load:
Release explicit approval before a tag or push
Safety protection for remote Git writes
Plan:
- Write
README.md: introduction, installation, usage, options and limitations. - Initialise local Git, stage the named files and create the first commit.
- Create the local version tag
git tag v0.1.0. - With the connected integration and separate authorisation, create a
downloads-tidyrepository (public or private as you choose), push code and tag, and create a release.
Is the plan acceptable, and should the repository be public or private?
The plan is acceptable. Use a public repository named downloads-tidy. Prepare the README first; list the impacts of local commits/tags separately from external publication so I can authorise each scope.
The README is written in three parts—purpose, installation and usage/options—and read back. Plan approval does not authorise a commit or tag. I checked the files and Git state under ~/Downloads-tidy. The local scope is Git initialisation, staging only README.md and sort_downloads.py, the first commit and local tag v0.1.0. It excludes downloaded originals, credentials and governance state, and makes no remote write. Confirm this local scope?
I authorise that local scope: initialise Git in ~/Downloads-tidy, commit only README.md and sort_downloads.py, and create local tag v0.1.0. Do not create a remote repository or push yet.
The authorised local actions are complete; commit and tag were read back:
$ git init -b main $ git add README.md sort_downloads.py $ git commit -m "Initial release: sort_downloads.py" $ git tag v0.1.0 $ git log --oneline 8e3a2f1 (HEAD -> main, tag: v0.1.0) Initial release: sort_downloads.py
Next I would create the GitHub repository, push and create the release. Those external actions need your separate approval. I will report every result and stop on anything unexpected. Confirm this publication scope?
I authorise creating the public GitHub repository yourname/downloads-tidy, adding that remote, pushing main and v0.1.0, creating its GitHub Release and reading everything back. Publish only the tool and README just reviewed.
- ✅ Created public GitHub repository
downloads-tidy, description “Downloads organiser”. - ✅ Added local remote:
git remote add origin https://github.com/yourname/downloads-tidy.git. - ✅ Pushed code:
git push -u origin main. - ✅ Pushed tag:
git push origin v0.1.0. - ✅ Created GitHub Release v0.1.0 with generated release notes.
- ✅ Read back GitHub page data; confirmed the commit, tag and release link agree.
Publication is complete. Repository: https://github.com/yourname/downloads-tidy. Release: https://github.com/yourname/downloads-tidy/releases/tag/v0.1.0. Friends can download or clone the tool and use it.
When ending this session, say “wrap up”. I will record the commit, tag, repository URL and release URL in the appropriate handoff/log fields and synchronise the next opening message.
Handoff and release safeguards
- A new AI need not ask for the whole background: entry files and handoff state locate prior progress, next work and risks for a new conversation, tool or day.
- Cross-tool consistency: Claude, Codex and Antigravity can use the same handoff data; actual entry support follows official tool documentation and local verification.
- Connected execution plus readback: with GitHub connected and the action authorised, the AI creates, pushes and releases, then reads back the result. Without the integration it provides detailed manual steps.
- Explicit approval for consequential actions: plan approval excludes commits and tags. Local commit/tag scope and remote repository/push/release scope each need clear authorisation; connectivity does not weaken this rule.
- Credentials stay separate: the AI tool’s secure store manages GitHub credentials; no credential is written into
dev/governance files.
Prepare the source responsibilities and install
Unlike Case A, this research task has several sources, so decide the tool responsibilities before installation. Notion holds the index, local files hold original content, and Google Drive holds the final deliverable for partners. This example assumes Notion and Drive are connected in the AI tool, giving it the capability to read/write the database, upload files and set permissions; concrete external writes still follow the authorisation shown below.
Notion (index database)
├── Title (text)
├── Type (government report / competitor screenshot / interview audio / own note)
├── Source (text or URL)
├── Date (date)
├── Tags (multi-select)
├── Summary (text, one sentence)
└── Local path (text, points into reference/)
Local ~/cafe-research/
├── AGENTS.md / CLAUDE.md / GEMINI.md (created during installation)
├── dev/ (handoff and governance files)
├── reference/ (prepared by you)
│ ├── 政府統計-人口分佈-2024.pdf
│ ├── 行業協會-餐飲業趨勢-2024.pdf
│ ├── 競品-A 咖啡店-menu截圖.png
│ ├── 訪談-業界朋友張生-2025-04-12.md
│ └── ...
└── report/ (prepared by you)
└── (the AI will write report-draft.md later)
Google Drive
└── After the report is written, the AI uploads it and sets partner sharing permissions.After preparing the database and local folders, open a local-file-capable AI in ~/cafe-research/ and ask it to read the install page and install or upgrade there. Use the terminal route only if you prefer manual installation.
$ npx --yes @adamchanadam/agent-handoff-kit@latest init ✅ created: 21 📦 Version: v0.3.66 🛠️ Mode: first-install 🚀 Next: open a new AI conversation. In this folder say Start Agent Handoff or 開工; only if not pointed here, use the path-bearing startup phrase.
The three tools have distinct responsibilities
- The Kit owns handoff and working discipline: Notion is the index, local files hold originals, and Drive carries the final deliverable. The project index records this split and routes source use.
- Source-of-truth discipline: each Notion row has a local-path field. The row is an index and summary; the actual content is in the local file. External writes must be read back.
- Use integrations only when connected: connected Notion and Drive can carry authorised actions directly; otherwise the AI gives detailed manual steps.
Start the handoff — state the tool split so the AI can begin research
If this is the first use, a plain Start Agent Handoff 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.
The task description explains the three-tool split
Start Agent Handoff. I need a market-research report for a café. Notion is our source index, ~/cafe-research/reference/ holds originals, and Google Drive is the partner-facing destination.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.
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.
Data split: Notion has an index database with roughly 30 reference items by my estimate—government statistics, industry reports, competitor menu screenshots and interview notes. Please verify the actual count. Each row has a “local path” pointing to the corresponding file under ~/cafe-research/reference/. The local reference/ folder contains PDFs, screenshots and notes; please verify whether they are complete. Please write the report draft into ~/cafe-research/report/. 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.
Why the task description names all three tools
- Plain start and task start are separate: 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.
- External sources are not automatically visible: 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.
- You explicitly ask the AI to act for you: 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.
- The report goal is clear: length, conclusion direction and readers—yourself, your wife and an industry friend—are stated, so the AI can adjust depth and tone.
First AI response — load Research and Knowledge; plan to read both Notion and the local folder
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 Research mode for source discipline and separation of fact from inference, plus Knowledge 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.
Startup is the same, but the mode combination reflects the task
/\_/\ Agent Handoff Kit vX.Y.Z
( o.o ) continuity ready
> ^ <
🔎 Handoff: loaded
📌 Current state: new project; the handoff has no previous session record yet
✅ Verified: your AI tool has Notion and Google Drive connected, so I can read and write directly
🚀 Next step: load working modes and enter planning; first align the Notion index with local references
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:
Research source dates, facts and inferences stay separate Knowledge external sources: reachable is not the same as read; unread sources must be marked pending
The workflow I will use next is heavier than Case A because it spans several sources:
Plan (list which sources must be aligned and which sections will be written)
→ Read (row by row, match Notion index entries to local reference files and identify gaps)
→ Change (write the report draft into report/)
→ Check (each claim has a citation; subjective inference is labelled)
→ Output the report and check results
I will first enter the planning stage and do two things:
- 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”.
- List the ten-page report structure and wait for your confirmation before writing.
I will perform the requested read-only alignment and outline preparation now. The resulting source trade-offs and concrete external writes will be presented for your decision.
Startup is the same, but the mode combination reflects the task
- Research and Knowledge load together: the source, research-question and cross-tool-sync signals are all present, so both modes load automatically.
- External integrations are verified before use: the AI says Notion and Google Drive are connected and can be read/written before acting; it does not assume this silently.
- The reading stage becomes heavier: 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.
Align Notion and local originals, and expose the gaps
With the Notion integration connected, the AI reads the actual database and matches each row to reference/. Missing items are reported. Without that integration, it identifies the limitation and asks whether to connect it, use an exported-file fallback, or pause.
OK, proceed with the plan.
I read “Cafe Research Index”: initially 29 records. I matched them against local reference/. Three additional local files are unregistered and are not included in those 29:
== Alignment result == ✅ Notion and local original both exist; path matches: 24 ⚠️ Registered in Notion; local original missing: 5 ⚠️ Local original exists; unregistered in Notion: 3 ❌ Notion path points to an unreadable local file: 0
Five registered records have no local original:
- “Industry Association 2023 Half-Year Report” — path
reference/行業協會-2023-H1.pdfdoes not exist locally. - “Interview — industry friend Mr Chan — 2025-04” — path
reference/訪談-陳生.mddoes not exist locally. - (Three other records have the same type of gap.)
Choose one of these three dispositions:
- Mark pending: record the five missing sources in the project index and label affected conclusions “material not obtained; conclusion tentative”.
- Pause for recovery: you place the five recovered originals in
reference/before report work continues. - Draft using the 27 available local sources: revise the affected sections when the five originals arrive.
The three local files not registered in Notion are:
reference/競品-D 咖啡店-2025-05.pngreference/筆記-選址初探-2025-03.mdreference/政府數據-社區人口-2024.xlsx
I recommend registering those three. The connected integration can write the rows, then immediately read each one back to verify the fields and local path.
Choose option 1: mark the five missing sources pending. Write the three unregistered local sources into Notion for me.
Completed:
- The five missing sources are listed in the project index’s pending-source section; affected report sections will explicitly remain tentative.
- The three local sources were added to “Cafe Research Index”. Each row was read back and its fields and path verified. The registered total rose from 29 to 32: 27 have readable local originals; five remain pending.
I then read the report-relevant ranges in those 27 available originals and recorded each revision, read scope and gap. The other five have not been obtained and do not count as read. Availability and actual ingestion are separate checks.
Here is the proposed ten-page outline; writing starts after you accept it:
- Summary (1 page): conclusion and three main reasons.
- Industry context (1.5 pages): association data and food-service trends.
- Community data (1.5 pages): population, spending power and footfall.
- Competitor analysis (2 pages): menus, prices and observations from five nearby competitors.
- Location analysis (1 page): initial site recommendations.
- Cost estimate (1.5 pages): startup capital and monthly operating expenses.
- Conclusion and next actions (1.5 pages): whether it is worth doing and what comes next.
Reachable does not mean ingested
- No silent mismatch: the AI reports five missing originals and three unregistered local files instead of skipping them.
- The user chooses the disposition: source gaps affect the judgement and scope; the AI lays out three routes rather than deciding silently.
- External-write readback: after authorisation, it writes through Notion and reads every row back. Without a connection, it provides the content for manual entry.
- Missing-source record: the project index lists the five gaps so the next agent can find them and identify affected report sections.
Write the report, then use the authorised Drive upload
After the outline is accepted, the AI writes the draft and loads Writing rules for audience, purpose and tone. Each claim traces to its reference; facts and inferences stay distinct. The requested output can then be uploaded, shared and read back through the connected Drive integration under the explicit authorisation below. Without the integration, the AI provides manual upload steps. If the AI tool cannot produce DOCX directly, it first creates Markdown or Google Docs-ready content and converts according to available capability.
The outline is fine; start writing. My partner is partner@example.com, my wife is wife@example.com, and industry friend Mr Cheung is cheung@example.com.
Loading:
Writing audience, purpose and tone
The readers are you, your wife and an industry friend, so the tone is a personal business plan rather than an investor pitch. I will write report/report-draft.md, placing footnote citations at each paragraph’s end with the Notion record and local source path. You can inspect the ten-page draft when ready.
The draft is complete: 10.3 pages, 2,847 Chinese characters and four tables, at report/report-draft.md. Main findings in this fictional example:
- Conclusion: worth pursuing, but try a six-month pop-up/shared-kitchen phase before renting an independent shop. Reasons: sufficient community spending power, moderate competitive density and manageable initial capital risk.
- Five missing sources: the two affected subsections say “tentative; reassess when the material is available”.
- Citations: paragraph footnotes identify the Notion record and local source path, with chapter-end reference lists containing 24 cited sources for traceability.
Which output format would you like?
.docx— Microsoft Word / Google Docs..pdf— printing or sharing a link..html— browser reading.
DOCX. Upload it to Google Drive for me and share it with my partner, wife and Mr Cheung.
Created report/report-final.docx. Through the Drive integration:
- ✅ Uploaded
~/cafe-research/report/report-final.docxto the “Cafe Research” folder. - ✅ Added the three named email addresses as viewers; only you retain editing permission to avoid accidental changes.
- ✅ Read back file information and permissions to verify upload and all three recipients.
- ✅ Saved the share link
https://drive.google.com/file/d/.../view.
💡 Credentials remain in the AI tool’s secure store, never in dev/. Governance records contain the share-link reference, not access credentials.
When ending the session, say “wrap up”. I will record the work, five missing sources, report location and share link in the handoff and prepare the next opening message.
Writing and external-write discipline
- Three modes remain active: Research owns source discipline, Knowledge owns source-of-truth responsibilities, and Writing owns audience and tone.
- Paragraph citations: each claim carries a reference, with facts separate from inference. The AI must not invent uncited claims.
- Tentative conclusions are explicit: five missing sources affect two subsections. Using the 27 available sources does not make the entire ten-page report fully verified.
- Upload plus readback: connected and authorised Drive actions include upload, permission setting and verification. Without the connection, provide detailed manual steps; credentials never enter governance files.
Wrap up — the same closeout flow, with the verified share link recorded
The command is the same as Case A: “wrap up” or “收工”. The Drive upload and share link were actually read back in the prior step; that proves only that external write. There are 32 registered sources: 27 with report-relevant ranges read and five still missing. Completed synchronisation does not mean the research is complete.
Wrap up.
I first reconstructed the parent report goal, completed draft, feedback-dependent resume point, remaining source acceptance, 27 read-source ranges and five unavailable originals from the packet alone. I compared this against the request and actual sources, citing the owning handoff sections in Reconstruction evidence. Local/external results, persistence requirements and prompt mirror are checked.
I then run closeout-status and copy its result. The following successful output is illustrative; this guide has not operated on your data. If the real command blocks, show its actual blocked card.
$ npx --yes @adamchanadam/agent-handoff-kit@latest closeout-status --root ~/cafe-research
/\_/\ Agent Handoff Kit vX.Y.Z ( -.- ) handoff saved > ^ < status: complete ✅ Completed: 10.3-page market-report draft, DOCX export, Drive upload and sharing 🔎 Checks: 24 cited sources traced; five missing sources marked pending; three Notion rows and Drive share link read back 📌 Handoff: next-session opening message ready ⚠️ Boundary: five references remain pending, affecting two subsections
The handoff is saved, but unresolved sources remain; this is not full research acceptance. Reconciled state:
- The handoff records the draft and final-format DOCX at
report/report-final.docx, the Drive linkhttps://drive.google.com/file/d/.../viewshared with the partner, wife and Mr Cheung, and revision after partner feedback as the next step. - The session log records source alignment, three Notion writes and readbacks, five pending sources, outline, citation count, and Drive upload/sharing.
- The project index records 32 registered sources (27 read in the relevant ranges, five pending), report location and Drive folder. Notion and Drive verification timestamps reflect only successful probes actually performed this session; unprobed integrations receive no new verification date.
Next time, say Start Agent Handoff or “開工” in the same project to recover state. State the next task in the same or following message to begin work. The real opening message is synchronised with START_NEXT_SESSION_PROMPT.txt.
Only if the next AI is not pointed at the folder, use:
Work in ~/cafe-research. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
The same closeout across cases
- Reconcile instead of append: update changed current fields against facts, rather than adding a new snapshot below the old one.
- Save actual external state: verify Notion writes and Drive links before recording success. Connectivity does not make all sources read or complete; these five remain missing. A missing connection or failed write is recorded with feasible manual steps, never as verified success.
- Verification dates: record only successful probes performed this session. Recheck when an integration is next needed; past success is not permanent availability, and closeout does not probe every integration automatically.
- Consistent across cases: Downloads tidying and research differ, but both use the same handoff process. Later tasks follow the same proportionate procedure.
Next handoff — revise the report after partner feedback
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 Start Agent Handoff plus the new request, and the new AI resumes the previous state, reloads Research and Writing, and plans the report revision.
Start Agent Handoff
Also make a lighter three-month “pop-up + shared kitchen” version.
/\_/\ Agent Handoff Kit vX.Y.Z
( o.o ) continuity ready
> ^ <
🔎 Handoff: loaded
📌 Current state: the 10.3-page final report has been delivered to the partner; the share link is recorded
🎯 New request: add a three-month pop-up + shared-kitchen alternative
⚠️ Boundary: five references are still pending and affect two sub-sections; they do not directly block this new alternative
🚀 Next step: reload Research and Writing modes, then enter planning
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:
- the capital-expenditure structure and assumptions of the original six-month plan;
- the scope of the five pending references, which affect two sub-sections and do not overlap with this new request;
- the partner’s main feedback: capital expenditure must be lower.
I will reload the same working modes as last time:
Research Knowledge Writing
Plan:
- Select three to four references related to “pop-up shop / shared kitchen” from
reference/; I will use tags in the Notion index to find them. Before calculating, read the original-source ranges needed for this revision again and verify their versions, assumptions and the impact of source gaps. A previous session’s read claim is not verification in this session. - 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.
- Add a sub-section in the report’s “Conclusion and next action” chapter: “Alternative B: three-month pop-up plus shared kitchen”.
- Add one summary sentence comparing the trade-off between the main six-month plan and Alternative B’s three-month path.
Is this plan OK?
Done. The new sub-section is added to the conclusion chapter, 1.4 pages in total. I have exported report/report-v2.docx. I can upload it to Google Drive to replace the original file, or create a new version file—which do you prefer?
Difference summary compared with the first version:
- Added 1.4 pages for the new alternative-plan sub-section.
- Added one conclusion paragraph comparing the two paths.
- Added four new reference footnotes from the original 27 ingested references, without using the five pending references.
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.
The value of multi-turn handoff
- No need to repeat the background: 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.
- Consistent across tools: today may be Claude; next time may be Codex or Antigravity. The same handoff data still applies.
- Citation discipline continues: the new section still follows Research mode: every claim has a citation, and facts are separated from inference.
- Missing items stay visible: the five pending references remain in the project index across conversations; they do not quietly disappear. A third future handoff will still see them.
This case spans several months and uses a timeline.
Cases A and B show seven-step task journeys. Case C shows a long-running project across multiple conversations and months. The emphasis is not each daily action, but how the AI maintains durable records: requirement evolution, accumulated decisions, historical architectural choices and recurring lessons.
This does not happen through a single instruction. Say “wrap up” when ending each session so the AI can reconcile state and maintain long-term records when triggered. Your role remains setting requirements, providing references and accepting results. The AI reads the current state and the long-term records required by the task, then preserves material evolution. You do not have to edit the files or memorise the internal file structure.
Start a new project — preserve the first task when continuity needs it
Install using the earlier flow, then open a new AI conversation and send Start Agent Handoff together with the first task: “I want to develop an AI editing assistant.” The AI reads the entry rules and classifies this as a system-building task without an A–F menu. When continuity needs a checkpoint and the handoff is the smallest suitable home, it records the task there. The decision log initially stays empty: there is one conversation, a simple objective, no accumulated decisions and no observed task evolution.
Start Agent Handoff I want to develop an AI editing assistant for proofreading and style suggestions. Start with the simplest usable version: Markdown only, taking text as input and returning suggested edits.
I have read the entry files, empty handoff, project-index template and rule-pack router. I will load Coding and Research, because the task requires learning the characteristics of existing AI editing tools.
This example has an established objective extending across multiple conversations, and the handoff is the smallest current-state home. I record “AI editing-assistant usable version — Markdown proofreading and style suggestions”, then enter planning.
The decision log stays empty: this is currently a single task with no long-term decision or evolution to record.
Why is the decision log empty on Day 1?
- Short-term versus long-term: one conversation, a simple clear objective and zero accumulated decisions are short-term signals. There is no long-term maintenance to perform yet.
- No user ceremony: you do not need to open the decision log or know it exists. With no long-term entry to save, closeout need not dwell on it.
- The structure already exists: installation created its internal sections. If the project develops long-term needs later, the AI can begin recording them without rebuilding the file.
Requirements evolve — detect a material turn and preserve the history
After a month and five or six conversations, the requirement evolves from Markdown proofreading to Markdown + LaTeX + code-comment proofreading, then collaborative editing. Meanwhile the team adds a Slack feedback channel and Linear for task tracking. In turn 4, you told the AI those integrations were connected; it registered them in the project index. The current objective now differs materially from Day 1. The AI detects that evolution and records it in the long-term evolution section, while the integration registry reflects the two added tools.
Wrap up.
During closeout I reconciled the handoff sections and found:
- The objective evolved from a Markdown MVP to Markdown + LaTeX + code + collaborative editing.
- There have been six conversations and four accumulated decisions.
- Long-term signals are now present, so requirement evolution, architectural choices and recurring learning receive closer attention.
This is a material requirement change, so I add the following to the decision log’s Evolution Timeline:
### 2026-XX-XX: Markdown MVP evolves into multi-syntax and collaboration Original Day 1 objective: Markdown proofreading and style suggestions. Evolution across six conversations: LaTeX support (turn 2), code-comment proofreading (turn 4), collaborative editing (turn 6). Driver: trial use showed Markdown-only support was insufficient for technical writing. Impact: reassess how the backend model handles multi-syntax context.
The entry is saved. A future question about the original project can be answered from this history rather than only the newest current objective.
What qualifies as material evolution?
- A material change in the task: not every small adjustment creates an entry. Compare the current objective with earlier recorded versions. One added syntax alone is a local extension; a change in the project’s core positioning is material.
- Accumulating long-term signals: at least four conversations, objective drift, at least ten accumulated decisions, or a question such as “why did we do this earlier?” increases attention to long-term records.
- No separate history-management request: the closeout procedure maintains the necessary history. If a required entry was missed, repair it at the next closeout rather than silently skipping it.
Decisions accumulate — archive older entries at the threshold
Another month passes. There have been 15 conversations, and the handoff’s confirmed decisions reach 32. The maintenance trigger fires: move the oldest decisions to the decision log’s archive and keep the newest 12 available in current handoff state.
Wrap up.
During closeout I found:
- The handoff contains 32 confirmed decisions, exceeding the 30-entry archive threshold.
- The archive trigger applies.
Archive result:
Retained in handoff (newest 12): #21 through #32 Moved to the decision archive (oldest 20): #1 through #20 Order: newest archived entry first (#20 at the top; #1 at the bottom)
The handoff now carries 12 active decisions instead of 32, while the archive retains every older entry for later tracing.
This session also made a three-option architectural choice with reasons, so I add this Architecture Choices entry:
### 2026-XX-XX: Backend switches from option A to option B Options: (1) A: lower cost, shorter context / (2) B: longer context, higher cost / (3) C: faster, weaker format control Selection: B Reason: code-comment proofreading needs longer context; B was more stable on this project's test samples. Impact: rewrite backend API calls and adjust prompt templates.
Archive and architecture triggers can apply together
- The threshold is mandatory: at 30 or more decisions, archive older entries and keep 8–22 in the hot tier. Choose the exact retained number for content continuity, avoiding a split through a related group.
- Architecture recording has a specific trigger: the plan lists at least two candidates, selects one and records why. All three conditions are required; a bare “A or B” without reasons does not meet it.
- The handoff remains the continuity source: it still carries active decisions after archival. Normal startup uses the handoff and the index when needed, not the whole decision archive. Historical questions or other routed tasks read the relevant long-term records.
A historical question — trace why option B was selected
Another month later the project is in trial use. A partner asks why option B was selected instead of lower-cost option A. You cannot recall the details, but the project has a record. Open a new conversation and ask. The AI uses the handoff and project index as needed to locate the decision log.
Why did we previously choose option B instead of cheaper option A for backend processing? My partner is asking.
The current handoff names option B, but the detailed reason is not in current state. I read the Architecture Choices section of the decision log:
### 2026-XX-XX: Backend switches from option A to option B Options: (1) A: lower cost, shorter context / (2) B: longer context, higher cost / (3) C: faster, weaker format control Selection: B Reason: code-comment proofreading needs longer context; B was more stable on this project's test samples. Impact: rewrite backend API calls and adjust prompt templates.
The recorded reasons were (1) longer context was needed for this task and (2) option B was more stable on this project’s test samples. The Day 60 session log contains the full trace. If more detail is needed, I can read the corresponding archive; I have not read it for this answer.
You can use these recorded reasons to answer your partner.
The complete historical lookup path
- Read long-term records when current state is insufficient: questions such as “why before?”, “what was the original design?” or “which conversation changed this?” route to the relevant decision record.
- No filename to memorise: ask the question; the AI locates the appropriate file and record.
- Three trace layers: current state → decision log → session-log archive. Read the relevant archive batch only when the decision record does not provide enough detail.
- Accessible history without manual file management: you do not need to open or memorise the archive structure. Preserved records can be retrieved when needed; unread records must not be described as already checked.