Let the AI handle setup.
Choose the right project folder, then paste one sentence.
This guide includes updates that have not been released yet. Features available to download depend on the published version.
Copy this into your AI conversation.
Open your project folder in your AI tool and paste the sentence below. The AI confirms the folder, installs or upgrades, then checks the result. You do not choose the installation commands.
Read https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html and install or upgrade Agent Handoff Kit in this project folder.
You need an AI tool with read and write access to your project folder, plus Node.js 18 or later. Web chat without folder access is not supported; ask the AI to check if unsure. Use the same sentence for older versions or existing AI work files.
After setup, start with a shortcut.
Installation and upgrades include all available commands, with no extra activation. Use handoff-kit-onboard to learn, or handoff-kit-start to resume existing work.
Command guide →The following section is for the AI.
AI installation steps and checks
These steps are for the AI. The user confirms the target folder without choosing installation commands.
Before running: the completion reply
Briefly report in English whether installation or upgrade completed, the confirmed folder, checks and warnings, shortcut status and one next step. If doctor fails, list the failures without reinstalling over them. If the only warning is a stale START_NEXT_SESSION_PROMPT.txt convenience copy, explain it will be updated at formal wrap-up; do not reinstall for this.
After setup, direct the user to handoff-kit-onboard (first-time guidance) or handoff-kit-start (resume work) in the project’s AI conversation, not the terminal. Claude Code, Gemini CLI and Antigravity CLI use /; Codex uses $ or /skills. If menus are missing, reopen the project conversation; Gemini also supports /commands reload. Installed files do not prove native menus and invocation were verified; report the distinction honestly. Finishing setup does not authorize starting the saved task.
1. Confirm the folder
Show the absolute path of the current folder and ask the user to confirm installation or upgrade there. Before confirmation, do not run init, upgrade or doctor. Once confirmed, first check for an unfinished upgrade, then existing handoff tool or AI work files.
Work only in this project, not shared settings. Do not delete files, overwrite conflicts or access login credentials. Do not run git commit, git push, git tag or npm publish, or create a GitHub Release.
2. Install, upgrade or recover
If none of AGENTS.md, CLAUDE.md, GEMINI.md, START_NEXT_SESSION_PROMPT.txt or dev/ exists, run:
npx --yes @adamchanadam/agent-handoff-kit@latest init --yes --root .
If any handoff tool or AI work files already exist, preview first:
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run --root .
Only if the preview has no conflicts, run:
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --yes --root .
For a conflict, stop with zero writes from the new plan. Read the conflicting file and the official version, propose a merge preserving user content, and obtain specific authorization before editing. Unknown content is not permission to overwrite; hashes show whether bytes changed, not whether content can be discarded. After merging, preview again, complete the applicable upgrade, then check and read back. Do not bypass conflicts by reinstalling or replacing whole files. If an unchanged old official file was misclassified, report its version, source and hash evidence to the maintainer.
For an unfinished upgrade, follow the tool’s instructions and recover with upgrade --yes --root . Do not delete locks manually or substitute standalone doctor for recovery. Rerun an interrupted fresh installation to fill missing files. Partial success is not full completion.
3. Verify the result
Read back the same operation’s root, CLI version, full final state and health result. Reuse its doctor result only when the process exited successfully, installation finished or upgrade committed (or was confirmed unnecessary), no transaction remains unfinished, health explicitly passed, and no relevant file changed or became uncertain afterward. Keep all warnings. A version number or the word “success” alone is insufficient.
Failure, interruption, incomplete output or later relevant file changes invalidate the old result. Recover unfinished upgrades first. If none remains but a valid health result is missing, or the user separately requests a check, run:
npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .
A health result does not recheck the latest npm release. To claim “up to date”, verify the npm registry, actual CLI and installed versions. A successful preview is not a completed installation. Separate closeout and independent acceptance requirements still apply.
init and upgrade install and check all project shortcuts in the same operation, including short bilingual Codex labels. No separate activation is needed. Missing entries cannot pass; a same-version upgrade can fill them. Identical files stay unchanged; only confirmed unmodified old official entries update safely. Customized or unrecognized same-name content must stop the operation and remain preserved.
Do not invent work progress during an upgrade. Preserve the handoff and reconcile it under installed rules at the next formal wrap-up. For new long-term requirements, follow Governance Write Boundary in installed dev/rules/agent-governance.md to find a suitable location and protect official bodies. Existing custom content mixed into them still needs conflict handling and an authorized merge.