@adamchanadam/agent-handoff-kit 0.3.67 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +230 -197
- package/README.md +222 -189
- package/bin/agent-handoff-kit.mjs +85 -12
- package/bin/commands.mjs +86 -0
- package/bin/handoff-read.mjs +88 -0
- package/bin/migration-baselines/official-origin-catalog.json +196 -1
- package/bin/progress/ICON-LICENSE.txt +21 -0
- package/bin/progress/agent-handoff-kit-logo2-256.png +0 -0
- package/bin/progress/dashboard-hero.png +0 -0
- package/bin/progress/dashboard.mjs +134 -0
- package/bin/progress/icons.svg +36 -0
- package/bin/progress/index.html +28 -0
- package/bin/progress/open.mjs +42 -0
- package/bin/progress/projection.mjs +144 -0
- package/bin/progress/renderer.js +151 -0
- package/bin/progress/server.mjs +76 -0
- package/bin/progress/styles.css +31 -0
- package/docs/commands.md +59 -0
- package/docs/progress.md +67 -0
- package/package.json +3 -1
- package/packs/closeout.md +71 -66
- package/runtime-core/AGENTS.core.md +112 -101
- package/runtime-core/PROJECT_INDEX.md +8 -1
- package/runtime-core/SESSION_HANDOFF.md +157 -147
- package/runtime-core/SESSION_LOG.md +2 -0
package/README.en.md
CHANGED
|
@@ -1,213 +1,246 @@
|
|
|
1
|
-
# Agent Handoff Kit
|
|
2
|
-
|
|
3
|
-
[繁體中文](README.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
|
|
4
|
-
|
|
5
|
-
Source package version: `v0.
|
|
6
|
-
|
|
7
|
-
<p align="center">
|
|
8
|
-
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit overview animation" width="720">
|
|
9
|
-
</p>
|
|
10
|
-
|
|
11
|
-
Agent Handoff Kit is a **handoff baton between AI conversations**.
|
|
12
|
-
|
|
13
|
-
It solves one narrow but important problem: AI conversations forget. A new conversation may not know where the last one stopped, which new files or reference sources matter, what is safe to change, or which document is authoritative. The kit keeps the current state, next action, risks, file routes, and the next-session prompt in the project so the next local AI can continue honestly.
|
|
14
|
-
|
|
15
|
-
📌 You describe the outcome you want. An AI that can read and write the local folder confirms the folder, decides whether to install or upgrade, runs the technical checks, and explains the result. You do not need to learn npm commands or diagnose file conflicts.
|
|
16
|
-
|
|
17
|
-
## 🚀 Start in three steps
|
|
18
|
-
|
|
19
|
-
For a first use, do not start by reading every technical detail. Do these three things:
|
|
20
|
-
|
|
21
|
-
1. Open a local AI agent in the folder where you want to use Agent Handoff Kit and send:
|
|
22
|
-
|
|
23
|
-
```text
|
|
24
|
-
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.
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
You can also open the [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html) first to see the procedure the AI must follow.
|
|
28
|
-
|
|
29
|
-
2. When installation finishes, say `Start Agent Handoff` or `開工` to the AI.
|
|
30
|
-
3. When you are genuinely ending this work session, say `wrap up` or `收工`.
|
|
31
|
-
|
|
32
|
-
You do not decide whether the folder needs an install, upgrade, health check, or a safe stop. The AI must show the folder it sees, explain risk and the next action, and ask when your confirmation is needed.
|
|
33
|
-
|
|
34
|
-
If the folder already contains older Kit files or AI memory files such as `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`, use the same request. The AI inspects first; it must not silently overwrite them.
|
|
35
|
-
|
|
36
|
-
For a non-technical introduction, open the [English introduction](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html). For complete walkthroughs, open the [English practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html).
|
|
37
|
-
To see how Agent Handoff Kit sits in a local agentic AI workflow, open [`local-agentic-ai-workflow-case-study.en.html`](https://adamchanadam.github.io/agent-handoff-kit/local-agentic-ai-workflow-case-study.en.html).
|
|
38
|
-
|
|
39
|
-
## 🐱 How to read the status card
|
|
40
|
-
|
|
41
|
-
| Status | Meaning |
|
|
42
|
-
|---|---|
|
|
43
|
-
| `( o.o ) continuity ready` |
|
|
44
|
-
| `(
|
|
1
|
+
# Agent Handoff Kit
|
|
2
|
+
|
|
3
|
+
[繁體中文](README.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
|
|
4
|
+
|
|
5
|
+
Source package version: `v0.4.0`. npm `@latest` and GitHub Release are verified by post-publish readback.
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit overview animation" width="720">
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
Agent Handoff Kit is a **handoff baton between AI conversations**.
|
|
12
|
+
|
|
13
|
+
It solves one narrow but important problem: AI conversations forget. A new conversation may not know where the last one stopped, which new files or reference sources matter, what is safe to change, or which document is authoritative. The kit keeps the current state, next action, risks, file routes, and the next-session prompt in the project so the next local AI can continue honestly.
|
|
14
|
+
|
|
15
|
+
📌 You describe the outcome you want. An AI that can read and write the local folder confirms the folder, decides whether to install or upgrade, runs the technical checks, and explains the result. You do not need to learn npm commands or diagnose file conflicts.
|
|
16
|
+
|
|
17
|
+
## 🚀 Start in three steps
|
|
18
|
+
|
|
19
|
+
For a first use, do not start by reading every technical detail. Do these three things:
|
|
20
|
+
|
|
21
|
+
1. Open a local AI agent in the folder where you want to use Agent Handoff Kit and send:
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
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.
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
You can also open the [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html) first to see the procedure the AI must follow.
|
|
28
|
+
|
|
29
|
+
2. When installation finishes, say `Start Agent Handoff` or `開工` to the AI.
|
|
30
|
+
3. When you are genuinely ending this work session, say `wrap up` or `收工`.
|
|
31
|
+
|
|
32
|
+
You do not decide whether the folder needs an install, upgrade, health check, or a safe stop. The AI must show the folder it sees, explain risk and the next action, and ask when your confirmation is needed.
|
|
33
|
+
|
|
34
|
+
If the folder already contains older Kit files or AI memory files such as `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`, use the same request. The AI inspects first; it must not silently overwrite them.
|
|
35
|
+
|
|
36
|
+
For a non-technical introduction, open the [English introduction](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html). For complete walkthroughs, open the [English practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html).
|
|
37
|
+
To see how Agent Handoff Kit sits in a local agentic AI workflow, open [`local-agentic-ai-workflow-case-study.en.html`](https://adamchanadam.github.io/agent-handoff-kit/local-agentic-ai-workflow-case-study.en.html).
|
|
38
|
+
|
|
39
|
+
## 🐱 How to read the status card
|
|
40
|
+
|
|
41
|
+
| Status | Meaning |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `( o.o ) continuity ready` | The AI has received the complete handoff and reconciled the work context; it continues only on your explicit task. |
|
|
44
|
+
| `( o.o ) installation verified` | Installation checked; startup must still receive the handoff. |
|
|
45
|
+
| `continuity incomplete` | Content is missing or critically contradictory; the AI must resolve the gap first. |
|
|
46
|
+
| `( -.- ) handoff saved` | Closeout has been saved; next time you can say `Start Agent Handoff` or `開工`. |
|
|
45
47
|
| `( x.x ) handoff blocked` | Not broken; something still needs to be saved, committed, verified, or handled. Follow the Blocker line first and do not treat this session as handed off. |
|
|
46
48
|
|
|
47
49
|
The closeout card checks saved handoff state, required fields, and recorded check results; it does not automatically prove that task conclusions are correct. Blocked work can still be handed off when its cause, impact, and conditions for resuming are clearly saved. “Saved” does not mean the overall task is complete.
|
|
48
|
-
|
|
49
|
-
## 🧭 How to read this repository
|
|
50
|
-
|
|
51
|
-
If you only want to use the kit, start from these four pages:
|
|
52
|
-
|
|
53
|
-
| Entry | Purpose |
|
|
54
|
-
|---|---|
|
|
55
|
-
| [This README](README.en.md) | Product purpose, safe use, and boundaries. |
|
|
56
|
-
| [60-second introduction](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) | A non-technical overview. |
|
|
57
|
-
| [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) | Three detailed scenarios: everyday local work, research with external tools, and a long-lived project. |
|
|
58
|
-
| [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html) | The instructions an AI follows to install, upgrade, check, or stop safely. |
|
|
59
|
-
|
|
60
|
-
This public repository keeps the material needed for use, installation, GitHub Pages, and the npm runtime. Normal users only need the four entries above.
|
|
61
|
-
|
|
62
|
-
## 🔎 What problem does it solve?
|
|
63
|
-
|
|
64
|
-
Long-running work with AI commonly has five problems:
|
|
65
|
-
|
|
66
|
-
| Problem | What Agent Handoff Kit does |
|
|
67
|
-
|---|---|
|
|
68
|
-
| A new AI does not know the current state | Keeps `dev/SESSION_HANDOFF.md` with the current objective, risks, validation, and next action. |
|
|
69
|
-
| New files or reference sources become disconnected | Lets you ask the AI to connect a document to the Kit, recording what it is for, which source is authoritative, and when it must be refreshed. |
|
|
70
|
-
| Different local AI tools start differently | Installs `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` as routes into one startup flow. Antigravity CLI reads the work folder’s `AGENTS.md` and `GEMINI.md`. |
|
|
71
|
-
| An AI could overwrite, delete, or publish carelessly | Requires an explanation and confirmation for high-risk work; destructive commands and unapproved release actions are prohibited. |
|
|
72
|
-
| External tools leave resources behind or clear shared resources | Applies ownership: resources demonstrably created for this task may be closed; shared, user-owned, or unclear resources are reported with evidence and kept until confirmed. |
|
|
73
|
-
|
|
74
|
-
It is not a chatbot and not a development framework. Think of it as a durable project handoff book.
|
|
75
|
-
|
|
76
|
-
## 🧰 Supported tools
|
|
77
|
-
|
|
78
|
-
Agent Handoff Kit is for agentic AI tools that can read and write a local project folder, such as Claude Code, OpenAI Codex, Gemini CLI, Google Antigravity, or another local-workspace agent. Antigravity CLI uses the work folder’s `AGENTS.md` and `GEMINI.md` routes to reach the same startup flow.
|
|
79
|
-
|
|
80
|
-
It is not for ordinary web-chat AI that cannot access your local folder. Uploading a file or pasting a handoff into a web chat does not give that chat the ability to maintain the project’s handoff files safely.
|
|
81
|
-
|
|
82
|
-
##
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
50
|
+
|
|
51
|
+
## 🧭 How to read this repository
|
|
52
|
+
|
|
53
|
+
If you only want to use the kit, start from these four pages:
|
|
54
|
+
|
|
55
|
+
| Entry | Purpose |
|
|
56
|
+
|---|---|
|
|
57
|
+
| [This README](README.en.md) | Product purpose, safe use, and boundaries. |
|
|
58
|
+
| [60-second introduction](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) | A non-technical overview. |
|
|
59
|
+
| [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) | Three detailed scenarios: everyday local work, research with external tools, and a long-lived project. |
|
|
60
|
+
| [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html) | The instructions an AI follows to install, upgrade, check, or stop safely. |
|
|
61
|
+
|
|
62
|
+
This public repository keeps the material needed for use, installation, GitHub Pages, and the npm runtime. Normal users only need the four entries above.
|
|
63
|
+
|
|
64
|
+
## 🔎 What problem does it solve?
|
|
65
|
+
|
|
66
|
+
Long-running work with AI commonly has five problems:
|
|
67
|
+
|
|
68
|
+
| Problem | What Agent Handoff Kit does |
|
|
69
|
+
|---|---|
|
|
70
|
+
| A new AI does not know the current state | Keeps `dev/SESSION_HANDOFF.md` with the current objective, risks, validation, and next action. |
|
|
71
|
+
| New files or reference sources become disconnected | Lets you ask the AI to connect a document to the Kit, recording what it is for, which source is authoritative, and when it must be refreshed. |
|
|
72
|
+
| Different local AI tools start differently | Installs `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` as routes into one startup flow. Antigravity CLI reads the work folder’s `AGENTS.md` and `GEMINI.md`. |
|
|
73
|
+
| An AI could overwrite, delete, or publish carelessly | Requires an explanation and confirmation for high-risk work; destructive commands and unapproved release actions are prohibited. |
|
|
74
|
+
| External tools leave resources behind or clear shared resources | Applies ownership: resources demonstrably created for this task may be closed; shared, user-owned, or unclear resources are reported with evidence and kept until confirmed. |
|
|
75
|
+
|
|
76
|
+
It is not a chatbot and not a development framework. Think of it as a durable project handoff book.
|
|
77
|
+
|
|
78
|
+
## 🧰 Supported tools
|
|
79
|
+
|
|
80
|
+
Agent Handoff Kit is for agentic AI tools that can read and write a local project folder, such as Claude Code, OpenAI Codex, Gemini CLI, Google Antigravity, or another local-workspace agent. Antigravity CLI uses the work folder’s `AGENTS.md` and `GEMINI.md` routes to reach the same startup flow.
|
|
81
|
+
|
|
82
|
+
It is not for ordinary web-chat AI that cannot access your local folder. Uploading a file or pasting a handoff into a web chat does not give that chat the ability to maintain the project’s handoff files safely.
|
|
83
|
+
|
|
84
|
+
## ⌨️ Common shortcuts
|
|
85
|
+
|
|
86
|
+
Enable shortcuts once in each project: ask the AI to “Enable Kit shortcuts in this project.” The AI installation guide includes this step. Claude Code, Gemini CLI and Antigravity CLI use <code>/handoff-kit-help</code>; Codex uses <code>$handoff-kit-help</code> or the <code>/skills</code> picker.
|
|
87
|
+
|
|
88
|
+
The menu covers start, closeout, the live progress page, document alignment, onboarding, future working rules and installation checks. For example, <code>/handoff-kit-progress</code> opens or reuses the local overview automatically. See [all eight entries and setup](docs/commands.md). Natural-language requests still work.
|
|
89
|
+
|
|
90
|
+
## 🟢 Start work
|
|
91
|
+
|
|
92
|
+
Open a local AI agent in the correct project folder.
|
|
93
|
+
|
|
94
|
+
If the AI is already in that folder, ordinary continuity startup is simply:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
Start Agent Handoff
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
You may also say `開工`.
|
|
101
|
+
|
|
94
102
|
When the active platform can safely control the current conversation title, a plain start may replace a generic or stale title with a concise `<project name>|<primary action>` title. The title is generated from the startup card's already-finalized current objective or recommended next action; generic triggers such as `Start Agent Handoff`, `開工`, or "start handoff" cannot be the primary action. It performs no extra file or network reads, keeps an informative title, and skips silently when title control is unavailable. The title is display-only: it is not project state, progress, completion evidence, or additional authority.
|
|
95
|
-
|
|
96
|
-
If the AI is not yet pointed at the project folder, use the path-bearing startup sentence:
|
|
97
|
-
|
|
98
|
-
```text
|
|
99
|
-
Work in <your project folder>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
|
|
100
|
-
```
|
|
101
|
-
|
|
103
|
+
|
|
104
|
+
If the AI is not yet pointed at the project folder, use the path-bearing startup sentence:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
Work in <your project folder>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
|
|
108
|
+
```
|
|
109
|
+
|
|
102
110
|
A first installation marks onboarding as pending. The AI enters a short first-use welcome after the startup card only when that state is still `eligible`, the active objective is empty or `TBD`, and there is no concrete task in the same message. Upgrades of existing projects do not reset the state. When you clearly describe the goal and available facts, the AI may begin the first safe step without going through onboarding first.
|
|
103
|
-
|
|
104
|
-
For ordinary daily startup, the AI reads `dev/SESSION_HANDOFF.md` first. Inside the same folder it does not reread `START_NEXT_SESSION_PROMPT.txt` or `dev/SESSION_LOG.md` during normal startup. The prompt copy is only for an AI that has not yet been pointed at the project folder.
|
|
105
|
-
|
|
106
|
-
`開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are all continuity commands. The AI asks one short confirmation only when the phrase could genuinely refer to a real-world opening, shift, or unrelated event. A bare startup or one that adds only the project name restores the
|
|
107
|
-
|
|
108
|
-
Then describe your task in ordinary language. The AI should explain the current state, next action, and risk before it starts the requested work.
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
111
|
+
|
|
112
|
+
For ordinary daily startup, the AI reads `dev/SESSION_HANDOFF.md` first. Inside the same folder it does not reread `START_NEXT_SESSION_PROMPT.txt` or `dev/SESSION_LOG.md` during normal startup. The prompt copy is only for an AI that has not yet been pointed at the project folder.
|
|
113
|
+
|
|
114
|
+
`開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are all continuity commands. The AI asks one short confirmation only when the phrase could genuinely refer to a real-world opening, shift, or unrelated event. A bare startup or one that adds only the project name reads the complete handoff and restores the necessary state, shows the startup card and recommended next action, then waits; it does not authorize research, planning, QA, file writes, network use, or sub-agents. Only a concrete task or explicit long-run instruction in the same message authorizes work. The first-use guidance exception described above still applies.
|
|
115
|
+
|
|
116
|
+
Then describe your task in ordinary language. The AI should explain the current state, next action, and risk before it starts the requested work.
|
|
117
|
+
|
|
118
|
+
At startup, the AI must receive the complete handoff from one unchanged version, then reconcile the goal, completed work, your corrections, remaining obligations and permission boundaries. Truncated output requires smaller follow-up reads. Missing content or a critical contradiction displays continuity incomplete instead of a recovery claim. Successful installation or saved closeout does not prove that the next AI has received the handoff.
|
|
119
|
+
|
|
120
|
+
## 💾 Wrap up
|
|
121
|
+
|
|
122
|
+
When the work session is really ending, say:
|
|
123
|
+
|
|
124
|
+
```text
|
|
125
|
+
wrap up
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
You can also say `收工`, `Wrap up Agent Handoff`, or `handoff`.
|
|
129
|
+
|
|
130
|
+
If the phrase could instead mean a real-world closing event, such as a restaurant closing, the AI should ask one short question rather than immediately changing the project handoff.
|
|
131
|
+
|
|
122
132
|
The AI should record the overall outcome, current subtask, exact resume point, and remaining acceptance checks, together with the necessary source versions, sections read, reading depth, and unresolved gaps. Simple tasks need only the relevant facts, not a multi-level task table. Before closeout, the AI reconstructs the next step using only the handoff, then compares it with your original request and actual results so a completed small step is not mistaken for the overall outcome. When resuming, the AI must still read the sources needed for the task; a predecessor's “read” record is not its own verification.
|
|
123
133
|
|
|
124
134
|
The AI should update only changed handoff state and compare the next-session prompt copy, regenerating it only when it differs:
|
|
125
|
-
|
|
126
|
-
```text
|
|
127
|
-
START_NEXT_SESSION_PROMPT.txt
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
That file is a portable convenience copy for an AI that is not yet in the project folder. The authority remains the next-session opening message in `dev/SESSION_HANDOFF.md`; if the two differ, the AI rebuilds the copy from the handoff.
|
|
131
|
-
|
|
132
|
-
## 🩺 When you are unsure about the state
|
|
133
|
-
|
|
134
|
-
If you are unsure whether the folder is installed correctly, needs an upgrade, or is healthy after an upgrade, ask the AI:
|
|
135
|
-
|
|
136
|
-
```text
|
|
137
|
-
Read the AI install page and check the Agent Handoff Kit state of this folder.
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
The AI performs the check. A successful check does not mean it has understood your project task; when you want continuity work, still say `Start Agent Handoff` or `開工`.
|
|
141
|
-
|
|
142
|
-
##
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
START_NEXT_SESSION_PROMPT.txt
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
That file is a portable convenience copy for an AI that is not yet in the project folder. The authority remains the next-session opening message in `dev/SESSION_HANDOFF.md`; if the two differ, the AI rebuilds the copy from the handoff.
|
|
141
|
+
|
|
142
|
+
## 🩺 When you are unsure about the state
|
|
143
|
+
|
|
144
|
+
If you are unsure whether the folder is installed correctly, needs an upgrade, or is healthy after an upgrade, ask the AI:
|
|
145
|
+
|
|
146
|
+
```text
|
|
147
|
+
Read the AI install page and check the Agent Handoff Kit state of this folder.
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The AI performs the check. A successful check does not mean it has understood your project task; when you want continuity work, still say `Start Agent Handoff` or `開工`.
|
|
151
|
+
|
|
152
|
+
## 📖 Dynamic Dashboard: find your project at a glance
|
|
153
|
+
|
|
154
|
+
Ask your AI to “Open the project progress page”, or use an enabled `/handoff-kit-progress` entry (Codex: `$handoff-kit-progress`). The AI starts or reuses this project's local Dashboard.
|
|
155
|
+
|
|
156
|
+

|
|
157
|
+
|
|
158
|
+
*Actual interface capture with fictional Atlas example data. The same template reads each project's own records. Open the image to enlarge it.*
|
|
159
|
+
|
|
160
|
+
<details>
|
|
161
|
+
<summary>View the Traditional Chinese interface</summary>
|
|
162
|
+
|
|
163
|
+

|
|
164
|
+
|
|
165
|
+
</details>
|
|
166
|
+
|
|
167
|
+
- **Overview:** current work, completed items, waiting, review and outstanding work, with access to results.
|
|
168
|
+
- **History:** find important changes by date, keyword and workstream; long logs and archives are read in bounded batches.
|
|
169
|
+
- **Document map:** see the roles, relationships and sources of core Kit files and registered project documents.
|
|
170
|
+
|
|
171
|
+
At normal saves, the AI maintains only changed records. The program reads the existing index, handoff and logs and updates the page without refreshes, a second report or model calls. Switch the interface between Traditional Chinese and English; untranslated source content stays in its original language. Unsaved work is not shown, and the view does not replace handoff reception or result acceptance.
|
|
172
|
+
|
|
173
|
+
It uses Node.js and your browser, without a database or API key. After all pages close, the service stays available for eight hours. If it stops or the computer restarts, use the same entry again. See the [Dashboard guide](docs/progress.md).
|
|
174
|
+
|
|
175
|
+
## 🗂️ What the AI maintains for you
|
|
176
|
+
|
|
177
|
+
After installation, the Kit places a small set of handoff files in the project. You do not need to read or maintain each one manually.
|
|
178
|
+
|
|
179
|
+
- **Startup entries:** `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `START_NEXT_SESSION_PROMPT.txt` route local AI tools into the same startup flow.
|
|
180
|
+
- **Current state:** `dev/SESSION_HANDOFF.md` records progress, next action, risks, and validation.
|
|
181
|
+
- **Trace record:** recent work remains available for trace-back; long-running use is compacted so the record does not grow without limit.
|
|
182
|
+
- **Project index and decisions:** important files, external sources, synchronization responsibilities, and durable decisions remain findable when you later ask “why did we choose this?”
|
|
183
|
+
- **Routed work rules:** the AI loads the rules needed for the task; you do not have to memorize rule-file names.
|
|
184
|
+
|
|
185
|
+
## 🧭 How work rules operate
|
|
186
|
+
|
|
187
|
+
You do not need to remember rule file names. The Kit lets the AI classify what you need and load only the relevant work rules.
|
|
188
|
+
|
|
189
|
+
| What you want to do | What the AI does |
|
|
190
|
+
|---|---|
|
|
191
|
+
| Write code or fix a bug | Reads the project index and relevant files, then changes and tests only what is needed. |
|
|
192
|
+
| Write an article, README, or public copy | Clarifies audience, purpose, tone, and publication surface. |
|
|
193
|
+
| Research or compare tools | Separates verified facts, source summaries, and the AI’s judgement. |
|
|
161
194
|
| Delete files, use Git, publish, or use npm | For high-risk operations, explains impact first and waits for your confirmation. |
|
|
162
|
-
| Use Notion, Google Drive, or another external tool | Checks the current tool guidance, handles resources by ownership, and keeps secrets out of project files. |
|
|
163
|
-
|
|
164
|
-
You can simply say what you want, for example: “Help me revise the README”, “Research whether this tool is suitable”, or “Connect this document to Agent Handoff Kit.” The AI chooses the needed rules.
|
|
165
|
-
|
|
166
|
-
For a durable preference, tell the AI rather than editing rule files blindly:
|
|
167
|
-
|
|
168
|
-
```text
|
|
195
|
+
| Use Notion, Google Drive, or another external tool | Checks the current tool guidance, handles resources by ownership, and keeps secrets out of project files. |
|
|
196
|
+
|
|
197
|
+
You can simply say what you want, for example: “Help me revise the README”, “Research whether this tool is suitable”, or “Connect this document to Agent Handoff Kit.” The AI chooses the needed rules.
|
|
198
|
+
|
|
199
|
+
For a durable preference, tell the AI rather than editing rule files blindly:
|
|
200
|
+
|
|
201
|
+
```text
|
|
169
202
|
For future public Chinese documents, use written Traditional Chinese and avoid mixing Chinese and English fragments. Connect this rule to Agent Handoff Kit.
|
|
170
|
-
```
|
|
171
|
-
|
|
203
|
+
```
|
|
204
|
+
|
|
172
205
|
The AI should distinguish a current request from a durable rule, then read the existing categories, relevant rule pack, and project supplements; when a suitable home exists, it should merge the change there. Project rules belong in a writable supplement or registered reference, preserving the Kit's official body. On the next relevant task, the AI should read and apply the rule through the existing route, respecting your objective and instruction priority without inventing a new goal or acceptance threshold.
|
|
173
206
|
|
|
174
207
|
These requirements guide the AI and check the result; they cannot intercept arbitrary editor writes. If older local rules are already mixed into official prose, the AI still needs to verify their sources and preserve and reconcile them after receiving merge authorization. Upgrades will not guess what to delete.
|
|
175
|
-
|
|
176
|
-
## 💬 Things you can ask an AI to do
|
|
177
|
-
|
|
178
|
-
State the goal in natural language. The AI decides which handoff files, rules, or indexes it needs to read.
|
|
179
|
-
|
|
180
|
-
| What you want | Example |
|
|
181
|
-
|---|---|
|
|
182
|
-
| Continue the last session | `Start Agent Handoff` or `開工` |
|
|
183
|
-
| End this session | `wrap up` or `收工` |
|
|
184
|
-
| Keep a new document from becoming disconnected | “Connect this document to Agent Handoff Kit so the next AI knows when to read and update it.” |
|
|
185
|
-
| Find important unconnected documents | “Scan for important documents not yet connected to Agent Handoff Kit.” |
|
|
186
|
-
| Avoid the same mistake in future work | “Turn this mistake into a durable work rule for future sessions.” |
|
|
187
|
-
| Keep an API or tool practice usable | “Use this API approach in future sessions too.” |
|
|
188
|
-
| Use Notion, Google Drive, GitHub, or another external tool | “This project uses these tools. Record what can be used directly and keep secrets out of project files.” |
|
|
189
|
-
| Finish a long task that used MCP, browser, or automation tools | “At wrap up, show the external-tool resource closeout: which task-owned resources were closed and which uncertain resources were retained with evidence.” |
|
|
190
|
-
|
|
191
|
-
When scanning for important documents, the AI first lists candidates and reasons. It does not automatically modify, merge, or retire them. For deletion, rename, authority changes, publication, upload, or permission changes, it must explain the impact and wait for confirmation.
|
|
192
|
-
|
|
193
|
-
Rules that must persist across future sessions should be written into the appropriate project file, not left only in the current chat summary.
|
|
194
|
-
|
|
195
|
-
## 🛡️ Safety boundaries
|
|
196
|
-
|
|
197
|
-
Even if you do not write code, the Kit requires an AI to stop and explain high-risk actions.
|
|
198
|
-
|
|
208
|
+
|
|
209
|
+
## 💬 Things you can ask an AI to do
|
|
210
|
+
|
|
211
|
+
State the goal in natural language. The AI decides which handoff files, rules, or indexes it needs to read.
|
|
212
|
+
|
|
213
|
+
| What you want | Example |
|
|
214
|
+
|---|---|
|
|
215
|
+
| Continue the last session | `Start Agent Handoff` or `開工` |
|
|
216
|
+
| End this session | `wrap up` or `收工` |
|
|
217
|
+
| Keep a new document from becoming disconnected | “Connect this document to Agent Handoff Kit so the next AI knows when to read and update it.” |
|
|
218
|
+
| Find important unconnected documents | “Scan for important documents not yet connected to Agent Handoff Kit.” |
|
|
219
|
+
| Avoid the same mistake in future work | “Turn this mistake into a durable work rule for future sessions.” |
|
|
220
|
+
| Keep an API or tool practice usable | “Use this API approach in future sessions too.” |
|
|
221
|
+
| Use Notion, Google Drive, GitHub, or another external tool | “This project uses these tools. Record what can be used directly and keep secrets out of project files.” |
|
|
222
|
+
| Finish a long task that used MCP, browser, or automation tools | “At wrap up, show the external-tool resource closeout: which task-owned resources were closed and which uncertain resources were retained with evidence.” |
|
|
223
|
+
|
|
224
|
+
When scanning for important documents, the AI first lists candidates and reasons. It does not automatically modify, merge, or retire them. For deletion, rename, authority changes, publication, upload, or permission changes, it must explain the impact and wait for confirmation.
|
|
225
|
+
|
|
226
|
+
Rules that must persist across future sessions should be written into the appropriate project file, not left only in the current chat summary.
|
|
227
|
+
|
|
228
|
+
## 🛡️ Safety boundaries
|
|
229
|
+
|
|
230
|
+
Even if you do not write code, the Kit requires an AI to stop and explain high-risk actions.
|
|
231
|
+
|
|
199
232
|
- **Destructive operations:** commands such as `rm -rf`, `git reset --hard`, and operations against system root paths are prohibited. Force-push, branch or tag deletion, and history rewriting need explicit scope, explicit approval, and readback of the affected refs.
|
|
200
|
-
- **Secrets:** do not print, commit, or upload `.env` values, API keys, or tokens.
|
|
201
|
-
- **Verify; do not guess:** before using a third-party service, connector, MCP, CLI, API, or plugin, check current official or already verified local guidance. If it cannot be verified, say so.
|
|
202
|
-
- **External-tool closeout:** an AI may close only resources it can show were created for the current task. Shared, user-owned, other-agent-owned, or unclear resources must be reported and left alone until you confirm.
|
|
203
|
-
- **Permission failures:** if a file is locked or permission is missing, stop and provide safe manual steps; do not bypass the protection.
|
|
204
|
-
- **Publishing:** tags, GitHub Releases, npm publication, deployment, and upload always require explicit approval. “Ready” is never approval.
|
|
205
|
-
|
|
206
|
-
## 🔗 Optional companion: Adam-AI-Instructions
|
|
207
|
-
|
|
208
|
-
Agent Handoff Kit can work alongside [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions). They are complementary, not competing authorities. They deliberately keep a minimum shared baseline for safety, secrets, irreversible operations, and release boundaries; neither is the parent source of truth for the other, and they should not be merged into one rule set:
|
|
209
|
-
|
|
233
|
+
- **Secrets:** do not print, commit, or upload `.env` values, API keys, or tokens.
|
|
234
|
+
- **Verify; do not guess:** before using a third-party service, connector, MCP, CLI, API, or plugin, check current official or already verified local guidance. If it cannot be verified, say so.
|
|
235
|
+
- **External-tool closeout:** an AI may close only resources it can show were created for the current task. Shared, user-owned, other-agent-owned, or unclear resources must be reported and left alone until you confirm.
|
|
236
|
+
- **Permission failures:** if a file is locked or permission is missing, stop and provide safe manual steps; do not bypass the protection.
|
|
237
|
+
- **Publishing:** tags, GitHub Releases, npm publication, deployment, and upload always require explicit approval. “Ready” is never approval.
|
|
238
|
+
|
|
239
|
+
## 🔗 Optional companion: Adam-AI-Instructions
|
|
240
|
+
|
|
241
|
+
Agent Handoff Kit can work alongside [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions). They are complementary, not competing authorities. They deliberately keep a minimum shared baseline for safety, secrets, irreversible operations, and release boundaries; neither is the parent source of truth for the other, and they should not be merged into one rule set:
|
|
242
|
+
|
|
210
243
|
- **Adam-AI-Instructions** governs how an AI works within one conversation: tone, priorities, response structure, calculation discipline, language discipline, safety boundaries, and output-layer roles.
|
|
211
|
-
- **Agent Handoff Kit** governs continuity between conversations: current state, next action, file routes, real closeout, and the next startup.
|
|
212
|
-
|
|
244
|
+
- **Agent Handoff Kit** governs continuity between conversations: current state, next action, file routes, real closeout, and the next startup.
|
|
245
|
+
|
|
213
246
|
This pairing is optional. It does not change installation or everyday use of Agent Handoff Kit. To use it, choose the version for your AI tool in that repository and paste it into the AI tool's settings.
|