AI-readable install page · v0.3.56

Instructions for an AI
to install or upgrade safely.

This page is for an agentic AI that can read and write the local folder and run terminal commands. The user should not have to choose an npm command or diagnose a conflict. Read this page before acting in the folder.

Version note: this page is aligned with v0.3.56. @latest means the version currently available from the npm registry.

The user only needs to paste this

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.

The AI must give this report when it finishes

Before running any npx command, remember this section. After installation or upgrade, the AI must not say only “completed” or paste only terminal output. It must explain the result and next step to the user in the following format.

Completion-report template: ✅ Installation completed. 📁 Current folder: <absolute path>. 🩺 doctor passed. ⚠️ The next step is not a terminal command; in an AI conversation that can read and write this folder, enter Start Agent Handoff or “開工”. Only if the AI has not yet been pointed at this folder, use: Work in <absolute path>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.

The AI must confirm the current folder first

Show the absolute path of the current working folder.
Ask: “Is this the folder where you want Agent Handoff Kit installed or upgraded?”
If the user cannot confirm, stop with zero writes. Do not run init, upgrade, or doctor.
Only after confirmation, inspect whether the folder already has AGENTS.md, CLAUDE.md, GEMINI.md, START_NEXT_SESSION_PROMPT.txt, or dev/.

Safety boundary: do not delete files, overwrite conflicts, handle credentials, run git commit, run git push, run git tag, run npm publish, or create a GitHub Release.

Decide how to install

Case 1: nothing is installed

If none of AGENTS.md, CLAUDE.md, GEMINI.md, START_NEXT_SESSION_PROMPT.txt, or dev/ exists, use a fresh install.

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

Case 2: Kit or AI memory files already exist

If any Kit file or existing AI memory file exists, preview the upgrade first. Do not overwrite directly.

npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run --root .

Only when the preview reports no conflict: run the confirmed upgrade.

npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --yes --root .

If the preview reports a conflict: stop and keep zero writes. The user does not need to judge technical differences or choose an npm command. The AI that can read and write this folder must read the CLI output, the conflicting files, and the formal sources, ask the user before making repair writes, then merge the project-specific content with the new Kit requirements. An unknown local hash is only evidence that the content exists and was not swapped; it is not permission for Kit to understand or overwrite it. After the merge, rerun upgrade --dry-run, then validate with doctor and hash/readback evidence. Report to the Kit maintainer only if the evidence shows Kit misclassified an unchanged formal old file. Do not reinstall or replace whole files to bypass the conflict.

Verify after completion

Run the health check:

npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .

If doctor passes, read AGENTS.md, then follow the Start Agent Handoff startup flow to connect this folder.
If doctor fails, stop and explain the failed items. Do not reinstall over the project.
If doctor only reports that the convenience copy START_NEXT_SESSION_PROMPT.txt is behind, explain that it will be regenerated at formal closeout; do not reinstall because of this.

AI response format

This section is the checklist for the completion-report contract at the top of the page. After acting, the AI must not say only “completed” or paste only terminal output. It must explain the result and next step to the user in short, plain language.

✅ Result: installation completed, upgrade completed, or stopped because of a conflict.
📁 Current folder: show the confirmed absolute path.
🩺 Health check: say whether doctor passed, failed, or only noted that the convenience copy is behind.
⚠️ The next step is not a terminal command: Start Agent Handoff / “開工” must be entered in an AI conversation that can read and write this folder.
🚀 Next step: if the AI is already in this folder, ask the user to enter Start Agent Handoff or “開工”; only if the AI has not yet been pointed at the folder, give the path-bearing startup sentence.

Completion-report template:

✅ Installation completed. 📁 Current folder: <absolute path>. 🩺 doctor passed. Do not remain in the terminal for the next step; in an AI conversation that can read and write this folder, enter Start Agent Handoff or “開工”. Only if the AI has not yet been pointed at the folder, use: Work in <absolute path>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.