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 · ...
Continue? (yes/no): yes
✅ created: 21 · 🔀 merged: 0 · ⏭️ skipped existing: 0
📦 Version: v0.3.56 · 🛠️ 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.
⚠️ This is not a terminal command. In an AI conversation in this folder, type:
Start Agent Handoff
or: 開工
Only if the AI is not 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.
One set of rules, three AI entry points
- Three entries, one rule set:
AGENTS.md,CLAUDE.mdandGEMINI.mdare created together. Antigravity reads the folder’sAGENTS.mdandGEMINI.md;GEMINI.mdis a bridge, not a second rule set. - The AI install page confirms the folder first: before confirmation it should not run
init,upgradeordoctor. - The next line belongs in AI chat: newcomers often paste
Start Agent Handoffinto a terminal. The warning marks that it belongs in the AI conversation instead. - 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 Kit. - Run doctor only when uncertain: normally start the AI directly. If you later doubt the files, run
npx --yes @adamchanadam/agent-handoff-kit@latest doctor. A temporarily lagging next-session prompt is a reminder to synchronise at closeout, not an excuse to overwrite work.
Start the handoff — plain start shows status; 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 開工; that only recovers the minimum state, shows the current objective, risks and recommended next step, then waits for your next message. 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 <project name>｜<primary action>; it keeps an informative title, skips silently when unsupported, and performs no extra file or network reads. The title is display-only, not state, progress, or authority. 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 start stops after status: the AI reads only the minimum handoff state, shows the startup card, risks and recommended next step, and 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.
- Guidance needs a real signal: 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 — show status, recommend the next step, then wait
In this example the user entered only Start Agent Handoff 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, 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.
This response stops after the startup card
/\_/\ Agent Handoff Kit vX.Y.Z
( o.o ) continuity ready
> ^ <
🔎 Handoff state: fresh install
📌 Current objective: not set
⚠️ Risks: none
🚀 Recommended next step: tell me what you want to do, for example “tidy Downloads and show me a preview first”.
I have read that this is a fresh install and no task objective is set yet. Tell me what you want to do next; if you want guided onboarding, say “teach me how to start”.
~/Downloads. 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.You have now provided a clear task, folder, sorting direction and safety limit. The first small task is: build a reusable Downloads organiser, but produce only the preview list; do not move files yet.
That is safest for a large file move. After you accept the preview, the next step can perform the real move.
Coding write the organiser Safety protect a large file move
After you confirm this first scope, the work follows five visible stages: plan → read → change → check → approved execution. 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.
Status and work start are separate
- A plain start returns only status: the AI does not turn an empty handoff into a task plan.
- The next task message starts work: in this example the Downloads request is what lets the AI enter Coding and Safety.
- High-risk work still stops: moving many files is irreversible, so the AI must stop at the planning stage and wait for confirmation.
You confirm; the AI plans, reads, then changes code
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.
Plan: sort .pdf, .docx, .doc, .txt, .md, .rtf and .pages as documents; .jpg, .jpeg, .png, .gif, .webp, .heic and .svg as images; .dmg, .pkg, .exe, .msi, .deb and .rpm as installers; .zip, .tar, .gz, .7z and .rar as archives; and unknown types as others. Put each under a year. Exclude shortcuts, hidden files and directories. Preserve collisions by adding _1, _2. Do not touch files outside ~/Downloads.
Before scanning: 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.
Read: 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.
Change: write ~/Downloads-tidy/sort_downloads.py with --dry-run. It prints where each file would go and moves nothing until a separate confirmation.
~/Downloads/IMG_2837.HEIC (2025-04, image)
~/Downloads/bank-statement-2024-11.pdf (2024-11, document)
~/Downloads/Notion-2.0.41.dmg (2024-08, installer)
~/Downloads/design-backup.zip (2025-01, archive)
~/Downloads/Screenshot 2025-03-15.png (2025-03, image)
Ready to run the preview?
Plan → read → change → check → approved execution
- Plan lists the goal, scope, acceptance checks and what is excluded. It is not “write code immediately”.
- Read collects facts from the real folder; the AI does not build a script from assumptions.
- Change writes the script and dry-run flag, but stops before the irreversible action.
- Check presents the preview and consequences.
- Approved execution happens only after your explicit acceptance.
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.
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: commands such as
rm -rfandgit reset --hard, system-root paths, and force pushes have separate hard guards. A force push requires distinct approval and affected-ref checking.
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 updates the handoff and prepares the next-session prompt
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 START_NEXT_SESSION_PROMPT.txt.
Closeout triggers the full handoff sequence
/\_/\ Agent Handoff Kit vX.Y.Z
( -.- ) handoff saved
> ^ <
✅ Completed: Downloads organiser finished; 1,043 files are in five categories with year subfolders
🔎 Checked: preview + real run + 0 failures
📌 Handoff: next-session prompt prepared
⚠️ Boundary: not yet published (README, version tag, GitHub push remain)
I updated the handoff to “sort_downloads.py 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 Start Agent Handoff 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.
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.
- Natural trigger phrases: “收工”, “Wrap up Agent Handoff”, “wrap up”, “handoff”, “end session” and “done for today” use the same closeout flow.
- Reconcile, do not append: current handoff state is rewritten against facts; new text is not simply added beneath old state.
- Prompt mirror: the next-session text is written to
START_NEXT_SESSION_PROMPT.txtfor convenience. It is not a second authority. - Log maintenance: old log entries compact into an index and later archive, so ordinary startup need not read a growing log.
Next handoff and public release — the new conversation resumes state; work starts only with a task
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 Start Agent Handoff 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.
Handoff and public-release safeguards
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.
🔎 Handoff: loaded
📌 Current state: sort_downloads.py completed and executed (1,043 files moved)
✅ Verified: GitHub integration is connected
⚠️ Boundary: tag, push and release are irreversible and each require explicit approval
🚀 Recommended next step: load Release + Safety and plan
Release approve before a real tag or push Safety protect remote Git writes
The plan is to write README.md, initialise local Git and commit, create local git tag v0.1.0, then—with your separate confirmation—create a public or private downloads-tidy repository, push code and tag, create a release, and read the GitHub result back.
downloads-tidy.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.
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.
- A new AI does not need your whole history: entry files and the handoff state tell it what happened, what is next and what risk remains.
- Cross-tool continuity: Claude today and Codex or Antigravity tomorrow can use the same handoff data; actual entry support follows the tool’s documentation and local verification.
- Connected integration plus readback: if GitHub is connected, the AI can execute and then read back the result; if it is not, it gives detailed manual steps.
- Two approvals: a plan approval is not a publication approval. A tag, push and release each require your clear go-ahead.
- Credentials stay separate: integration credentials live in the AI tool’s secure store, never in
dev/governance files.
Prepare the data split and install
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.
Three tools, three roles
Notion (index database)
├── Title · Type (government report / competitor screenshot / interview audio / note)
├── Source (text or URL) · Date · Tags · one-sentence summary
└── Local path (points to a file under reference/)
Local ~/cafe-research/
├── AGENTS.md / CLAUDE.md / GEMINI.md (after install)
├── dev/ (handoff and governance)
├── reference/ (original PDFs, screenshots, recordings and notes)
└── report/ (draft and final report)
Google Drive
└── final .docx / .pdf and the share link for partners
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.
Start the handoff — state the tool split so the AI can begin research
If this is the first use, a plain Start Agent Handoff only shows status and a recommended next step. 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 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 ~/cafe-research/reference/. The local reference/ folder already contains the matching PDFs, screenshots and notes. 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: if you only say start, the AI only reads handoff state and shows status; 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.
Do you confirm that I should enter planning?
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.
You confirm; the AI aligns Notion and local sources and exposes gaps
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.
Reachable does not mean read and aligned
For the five indexed records whose local originals are missing, you choose one of three dispositions: (1) mark them pending in the project index, and label the affected report conclusions tentative; (2) pause and wait while you recover and place the five files in reference/; or (3) draft from the existing 27 available sources first, then revise the affected sections when the files arrive. I do not choose for you.
The three local files that Notion has not registered 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.
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.
Write the report — Writing mode adds discipline; Drive upload is an explicit AI action
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.
Writing mode and external-write discipline
Writing structure, citations and plain conclusions
The draft is report/report-draft.md: 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 tentative pending review when the material is recovered.
I then ask which format you want: .docx for Microsoft Word/Google Docs, .pdf for printing or a direct share link, or .html for browser reading. You choose .docx, so I create report/report-final.docx.
After that confirmation, I upload this DOCX to the agreed Drive folder, grant viewer access to the three named recipients—partner partner@example.com, spouse wife@example.com, and industry friend Mr Cheung cheung@example.com—and read back both the file information and permissions, including the viewer link: https://drive.google.com/file/d/.../view.
- Local final:
~/cafe-research/report/report-final.docx - External result: Drive upload and share link are read back, not assumed.
- Credential boundary: no Drive credential is copied into
dev/.
- Writing mode does not make uncertain evidence certain.
- Format checks let you inspect DOCX, PDF and HTML before external sharing.
- Readback proves the file and viewer link correspond to the intended final report.
- Unconnected fallback is a local final file and manual upload instructions—not a false claim that Drive was updated.
Wrap up — the same closeout flow as Case A, with the shared link recorded
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.
Closeout is the same flow, with concrete external state
Completed: source reconciliation, the 10.3-page draft and final DOCX, a verified Drive upload and viewer link. The reconciled handoff records report/report-final.docx, 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 today. At the next session, a plain Start Agent Handoff 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.
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.
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. - 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 months, not a daily ritual
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.
Start a new project — the first task description enters the handoff
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.
Why the decision log is empty on day one
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.
The requirement evolves — the AI detects a substantive turn and adds a long-term record
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?”
What qualifies as substantive evolution
- The goal, users, ownership, external boundary or architecture changed.
- There were at least two meaningful options and a selected path with a reason.
- A future AI or teammate would otherwise have to rediscover why the decision was made.
Decisions accumulate — at 30 confirmed decisions, older entries are archived
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.
Archive without losing traceability
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.
Look back — you ask “why did we choose option B?” and the AI traces the history
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.
Complete retrospective path
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.