@adamchanadam/agent-handoff-kit 0.1.2 → 0.1.4

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.md CHANGED
@@ -1,34 +1,31 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:`v0.1.2` 已正式發佈。這是早期可用版本,尚未宣稱所有需求已完成。
3
+ 狀態:`v0.1.4` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
4
4
 
5
- Agent Handoff Kit 是一套給 AI 專案使用的交接工具。它會在你的專案中放入一組固定文件,讓 AI 在下一次工作時知道:目前做到哪裡、哪些資料要先讀、哪些檔案不可亂動、收工時要留下甚麼。
5
+ ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
6
 
7
- 它不是聊天機器人,也不是另一個開發框架。它的作用比較像一本固定放在專案內的交接簿,讓不同 AI 工具和不同工作階段都能接上同一條線。
7
+ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
8
8
 
9
- ## 它解決甚麼問題
10
-
11
- AI 很容易在新工作階段失去前文。它可能不知道上次改了甚麼、哪些文件才是最新、哪些資料只是參考、哪些操作需要先問你。
9
+ 它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
12
10
 
13
- Agent Handoff Kit 把這些事情寫進專案文件:開工先讀哪裡、任務前要確認哪些必讀資料、收工要留下哪些交接內容、下次要貼哪段文字重新開始。
11
+ 想先看非技術版介紹,可打開 GitHub repo 內的 [`agent-handoff-kit-intro.html`](agent-handoff-kit-intro.html)。那一頁是新手 60 秒入門,README 則保留安裝、日常使用與限制。
14
12
 
15
- ## 適合誰使用
13
+ ## 它解決甚麼問題
16
14
 
17
- 適合以下情況:
15
+ 用 AI 做長期項目,常見四個問題:
18
16
 
19
- - 你會隔幾天才回到同一個 AI 專案。
20
- - 你會在 Codex、Claude Code、Gemini CLI 等工具之間切換。
21
- - 你希望 AI 每次開始前先讀專案狀態,而不是重新猜背景。
22
- - 你希望收工時留下下一次可直接貼上的開工文字。
23
- - 你不是開發人員,但想讓 AI 在長期專案中穩定接力。
17
+ | 問題 | Agent Handoff Kit 怎樣處理 |
18
+ |---|---|
19
+ | 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
20
+ | 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
21
+ | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程。 |
22
+ | AI 可能亂改、亂刪或誤發佈 | 內置 safety 工作模式;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
24
23
 
25
- 不適合以下情況:
24
+ 它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
26
25
 
27
- - 只問一次性問題,不需要保存專案狀態。
28
- - 不想在專案內新增任何交接文件。
29
- - 需要已完全成熟的穩定版安裝工具。
26
+ ## 三步上手
30
27
 
31
- ## 安裝
28
+ ### 一、安裝
32
29
 
33
30
  在你的專案資料夾打開 Terminal,執行:
34
31
 
@@ -36,51 +33,43 @@ Agent Handoff Kit 把這些事情寫進專案文件:開工先讀哪裡、任
36
33
  npx @adamchanadam/agent-handoff-kit init
37
34
  ```
38
35
 
39
- 出現確認問題時,輸入:
36
+ 出現確認問題時,輸入 `yes`。
40
37
 
41
- ```text
42
- y
43
- ```
38
+ 安裝完成後,你會看到一段 `Work in ...` 文字。請特別留意:那一段不是給 Terminal 的指令,而是要貼到 AI 對話。
39
+
40
+ ### 二、開工
44
41
 
45
- 若工具列出即將建立的文件,並詢問是否寫入,請輸入:
42
+ 打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。沒有那段文字時,可貼這句:
46
43
 
47
44
  ```text
48
- yes
45
+ Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
49
46
  ```
50
47
 
51
- 安裝完成後,你會看到一個「下一步」區塊。請特別留意:那一段不是給 Terminal 的指令,而是給 AI 對話使用的文字。
48
+ 然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
52
49
 
53
- ## 安裝後第一步
50
+ ### 三、收工
54
51
 
55
- 安裝完成後,不要在 Terminal 輸入 `Follow AGENTS.md`。
56
-
57
- 正確做法是:
58
-
59
- 1. 打開你要使用的 AI 工具。
60
- 2. 新增一段對話。
61
- 3. 貼上安裝工具顯示的 `Work in ...` 文字。
62
- 4. 要求 AI 先讀 `AGENTS.md`,並在改檔前說明它讀到的目前狀態。
63
- 5. 然後直接描述你要完成的任務。
64
-
65
- 你可以貼上類似以下文字:
52
+ 工作完成想結束時,只需輸入:
66
53
 
67
54
  ```text
68
- Work in <你的專案資料夾>.
69
- Read AGENTS.md first. Tell me what you understand before changing files.
55
+ 收工
70
56
  ```
71
57
 
72
- 接著再寫你的任務,例如:
58
+ 也可以輸入:
73
59
 
74
60
  ```text
75
- 整理這個專案,先告訴我目前狀態、下一步、風險,暫時不要改檔。
61
+ wrap up
62
+ handoff
76
63
  ```
77
64
 
78
- 或:
65
+ AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字放在 fenced `text` code block 內,方便完整複製。安裝後也會有一個更直覺的副本檔:
79
66
 
80
67
  ```text
81
- 更新 README,完成後檢查交接文件是否仍然準確。
68
+ START_NEXT_SESSION_PROMPT.txt
82
69
  ```
83
70
 
71
+ 這個檔案只是方便你複製下次開工提示;真正權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的 `Next Session Opening Message`。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重生副本。
72
+
84
73
  ## 檢查是否安裝完整
85
74
 
86
75
  如要檢查安裝是否完整,可在 Terminal 執行:
@@ -89,18 +78,19 @@ Read AGENTS.md first. Tell me what you understand before changing files.
89
78
  npx @adamchanadam/agent-handoff-kit doctor
90
79
  ```
91
80
 
92
- 看到 `status: passed`,代表必要文件與基本結構存在。
81
+ 看到 `status: passed`,代表必要文件、基本結構與 `START_NEXT_SESSION_PROMPT.txt` 副本一致性通過檢查。
93
82
 
94
83
  這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
95
84
 
96
85
  ## 會安裝甚麼
97
86
 
98
- 安裝工具會在你的專案中建立以下文件:
87
+ 安裝工具會在你的專案中建立:
99
88
 
100
89
  ```text
101
90
  AGENTS.md
102
91
  CLAUDE.md
103
92
  GEMINI.md
93
+ START_NEXT_SESSION_PROMPT.txt
104
94
  dev/SESSION_HANDOFF.md
105
95
  dev/SESSION_LOG.md
106
96
  dev/PROJECT_INDEX.md
@@ -109,13 +99,12 @@ dev/RULE_PACKS.md
109
99
  dev/rules/*.md
110
100
  ```
111
101
 
112
- 每個文件的用途如下:
113
-
114
102
  | 文件 | 用途 |
115
103
  |---|---|
116
104
  | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
117
105
  | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
118
106
  | `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
107
+ | `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由 handoff 產生。 |
119
108
  | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
120
109
  | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。 |
121
110
  | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
@@ -125,75 +114,59 @@ dev/rules/*.md
125
114
 
126
115
  你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
127
116
 
128
- ## 日常使用方式
117
+ ## 工作模式
129
118
 
130
- 每次開始新的 AI 工作階段時,建議先貼上上一輪收工產生的開工文字。若沒有那段文字,可以貼:
119
+ 你不需要記規則包名稱,只要描述任務。AI 會按任務切換工作模式。
131
120
 
132
- ```text
133
- Work in <你的專案資料夾>.
134
- Read AGENTS.md, dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md, dev/PROJECT_INDEX.md, and dev/RULE_PACKS.md.
135
- Tell me the current objective, pending work, risks, and your recommended next action before changing files.
136
- ```
121
+ | 你的任務 | AI 應使用的工作規則 |
122
+ |---|---|
123
+ | 寫或改代碼、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
124
+ | 查資料、比較來源、整理證據 | `research` |
125
+ | 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
126
+ | 整理 Notion、Google Drive 或知識庫 | `knowledge` |
127
+ | 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
128
+ | 改規則、改流程、整理交接 | `agent-governance`;先找既有真源,不盲目新增規則 |
137
129
 
138
- 然後直接描述任務。
130
+ 原則是只讀當前任務需要的規則,不是每次讀全部文件。
139
131
 
140
- 對簡單任務,可以這樣寫:
132
+ ## 安全護欄
141
133
 
142
- ```text
143
- 幫我檢查 README 是否清楚,先只提出問題,不要改檔。
144
- ```
134
+ 就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
145
135
 
146
- 對需要改檔的任務,可以這樣寫:
136
+ - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
137
+ - 機密保護:`.env`、API key、token 不可印出、不可 commit、不可上傳。
138
+ - 查證不猜:用第三方 API、CLI、SDK 前先查官方文件;查不到就標示未核實。
139
+ - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
140
+ - 發佈需明確批准:tag、GitHub Release、npm publish、部署或上傳都不能因「準備好了」而自動執行。
147
141
 
148
- ```text
149
- 請更新 README 的安裝後說明,完成後執行必要檢查,並告訴我改了甚麼。
150
- ```
142
+ ## 已安裝舊版,或已有 AI 記憶文件?
151
143
 
152
- 對需要收工的情況,只需輸入:
144
+ 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,先用最新版 CLI dry-run 預演會發生甚麼:
153
145
 
154
- ```text
155
- 收工
146
+ ```bash
147
+ npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
156
148
  ```
157
149
 
158
- 也可以輸入:
150
+ 確認沒有問題後,再執行:
159
151
 
160
- ```text
161
- wrap up
162
- handoff
152
+ ```bash
153
+ npx @adamchanadam/agent-handoff-kit@latest upgrade
163
154
  ```
164
155
 
165
- AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。那段文字會放在 fenced `text` code block 內,方便完整複製。
166
-
167
- ## 工作規則怎樣運作
156
+ `@latest` 代表使用 npm 上最新的 Agent Handoff Kit CLI。`upgrade` 則負責把專案內已安裝的 Kit 文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會報 conflict,不會靜默覆寫。
168
157
 
169
- Agent Handoff Kit 會把任務分成不同工作模式。例如:
158
+ 看到 `conflict` 不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把 dry-run 輸出貼給 AI,請它幫你判斷要保留、合併,還是手動修改。
170
159
 
171
- | 你的任務 | AI 應使用的工作規則 |
172
- |---|---|
173
- | 修改程式、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
174
- | 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
175
- | 查證資料、比較來源、整理證據 | `research` |
176
- | 整理 Notion、Google Drive 或知識庫 | `knowledge` |
177
- | 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
178
-
179
- 原則是只讀當前任務需要的規則,不是每次讀全部文件。
180
-
181
- ## 既有專案升級
182
-
183
- 若你的專案已經有 `AGENTS.md` 或其他 AI 記憶文件,請先預演,不要直接覆寫:
160
+ ## 版本提示
184
161
 
185
- ```bash
186
- npx @adamchanadam/agent-handoff-kit upgrade --dry-run
187
- ```
162
+ CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
188
163
 
189
- 確認計劃後再執行:
164
+ 若你不想檢查更新,可設定:
190
165
 
191
166
  ```bash
192
- npx @adamchanadam/agent-handoff-kit upgrade
167
+ AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
193
168
  ```
194
169
 
195
- 升級工具會保留既有檔案。能安全合併時才合併;不能安全合併時會報 conflict,不會靜默覆寫。
196
-
197
170
  ## 語言使用
198
171
 
199
172
  安裝後的核心指令文件預設使用英文,原因是不同 AI 工具對英文結構較穩定。這不是限制你的專案必須用英文。
@@ -224,12 +197,12 @@ npm package 只包含安裝所需內容:
224
197
  - `LICENSE`
225
198
  - `package.json`
226
199
 
227
- 原始碼倉庫中的驗收文件與腳本供維護者使用,不會安裝到你的專案。
200
+ GitHub repo 內的新手介紹頁 `agent-handoff-kit-intro.html` 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
228
201
 
229
202
  ## 目前限制
230
203
 
231
- - `v0.1.2` 是早期可用版本,尚未宣稱完整穩定。
232
- - 這仍是早期可用版本,尚未宣稱完整穩定。
204
+ - `v0.1.4` 是 GitHub 與 npm 同步發佈版本。
205
+ - 這是早期可用版本,尚未宣稱完整穩定。
233
206
  - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
234
207
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
235
208
  - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
@@ -13,6 +13,7 @@ const mappings = [
13
13
  ["runtime-core/AGENTS.core.md", "AGENTS.md"],
14
14
  ["runtime-core/CLAUDE.md", "CLAUDE.md"],
15
15
  ["runtime-core/GEMINI.md", "GEMINI.md"],
16
+ ["runtime-core/START_NEXT_SESSION_PROMPT.txt", "START_NEXT_SESSION_PROMPT.txt"],
16
17
  ["runtime-core/SESSION_HANDOFF.md", "dev/SESSION_HANDOFF.md"],
17
18
  ["runtime-core/SESSION_LOG.md", "dev/SESSION_LOG.md"],
18
19
  ["runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md"],
@@ -63,7 +64,18 @@ const requiredAnchors = [
63
64
  "handoff saved",
64
65
  "📋 Next session: copy and paste the whole block below",
65
66
  "State Reconciliation Check",
66
- "Do not append a new state snapshot"
67
+ "Do not append a new state snapshot",
68
+ "START_NEXT_SESSION_PROMPT.txt"
69
+ ]
70
+ },
71
+ {
72
+ target: "START_NEXT_SESSION_PROMPT.txt",
73
+ label: "next-session prompt convenience copy",
74
+ snippets: [
75
+ "Work in ",
76
+ "Read in order:",
77
+ "dev/PROJECT_INDEX.md",
78
+ "If this root does not match the expected project root"
67
79
  ]
68
80
  },
69
81
  {
@@ -132,8 +144,7 @@ const requiredAnchors = [
132
144
  target: "dev/PROJECT_INDEX.md",
133
145
  label: "template version metadata",
134
146
  snippets: [
135
- "Agent Handoff Kit template version",
136
- "0.1.2"
147
+ "Agent Handoff Kit template version"
137
148
  ]
138
149
  },
139
150
  {
@@ -259,6 +270,7 @@ main().catch((error) => {
259
270
 
260
271
  async function main() {
261
272
  const version = await readPackageVersion();
273
+ await maybePrintUpdateNotice(version);
262
274
  const { command, options } = parseArgs(process.argv.slice(2));
263
275
  if (!command || options.help) {
264
276
  printHelp(version);
@@ -307,6 +319,7 @@ async function runInstall(command, root, options, version) {
307
319
 
308
320
  if (options.dryRun) {
309
321
  console.log("\ndry-run: no files written");
322
+ printDryRunExplanation(plan);
310
323
  if (plan.some((item) => item.action === "conflict")) process.exitCode = 1;
311
324
  return;
312
325
  }
@@ -343,12 +356,12 @@ async function runInstall(command, root, options, version) {
343
356
  }
344
357
 
345
358
  const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
346
- console.log(`\ncreated: ${created.length}`);
347
- console.log(`merged: ${merged.length}`);
348
- console.log(`skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
349
- console.log(`conflict: ${conflicts.length}`);
350
- if (merged.length > 0) console.log(`backup: ${path.relative(root, backupDir)}`);
351
- console.log(`migration report: ${path.relative(root, report)}`);
359
+ console.log(`\n✅ created: ${created.length}`);
360
+ console.log(`🔀 merged: ${merged.length}`);
361
+ console.log(`⏭️ skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
362
+ console.log(`${conflicts.length > 0 ? "⚠️ " : "✅ "}conflict: ${conflicts.length}`);
363
+ if (merged.length > 0) console.log(`💾 backup: ${path.relative(root, backupDir)}`);
364
+ console.log(`📄 migration report: ${path.relative(root, report)}`);
352
365
  printInstallNextSteps(root, conflicts.length);
353
366
  if (conflicts.length > 0) process.exitCode = 1;
354
367
  }
@@ -369,6 +382,8 @@ async function runDoctor(root, version) {
369
382
 
370
383
  if (missing.length > 0) {
371
384
  console.log(`\nstatus: failed (${missing.length} missing)`);
385
+ console.log("⚠️ 檢查未通過:有必要檔案不存在。");
386
+ console.log("下一步:先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。");
372
387
  process.exitCode = 1;
373
388
  return;
374
389
  }
@@ -382,6 +397,8 @@ async function runDoctor(root, version) {
382
397
 
383
398
  if (anchorFailures.length > 0) {
384
399
  console.log(`\nstatus: failed (${anchorFailures.length} anchor checks failed)`);
400
+ console.log("⚠️ 檢查未通過:有檔案存在,但內容缺少必要段落。");
401
+ console.log("下一步:執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。");
385
402
  process.exitCode = 1;
386
403
  return;
387
404
  }
@@ -398,11 +415,69 @@ async function runDoctor(root, version) {
398
415
 
399
416
  if (schemaFailures.length > 0) {
400
417
  console.log(`\nstatus: failed (${schemaFailures.length} schema checks failed)`);
418
+ console.log("⚠️ 檢查未通過:交接或索引文件結構不完整。");
419
+ console.log("下一步:把這段 doctor 輸出貼給 AI,請它先修交接結構,不要直接重裝覆蓋。");
420
+ process.exitCode = 1;
421
+ return;
422
+ }
423
+
424
+ const mirrorRows = await checkPromptMirror(root);
425
+ const mirrorFailures = mirrorRows.filter((row) => !row.ok);
426
+ console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
427
+ for (const row of mirrorRows) {
428
+ console.log(`${row.ok ? "ok" : "missing"} ${row.target} (${row.label})`);
429
+ if (!row.ok && row.reason) console.log(` reason: ${row.reason}`);
430
+ }
431
+
432
+ if (mirrorFailures.length > 0) {
433
+ console.log(`\nstatus: failed (${mirrorFailures.length} prompt mirror checks failed)`);
434
+ console.log("⚠️ 檢查未通過:下次開工提示副本與 handoff 真源不同。");
435
+ console.log("下一步:以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。");
401
436
  process.exitCode = 1;
402
437
  return;
403
438
  }
404
439
 
405
440
  console.log("\nstatus: passed");
441
+ console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本也與 handoff 一致。");
442
+ }
443
+
444
+ async function checkPromptMirror(root) {
445
+ const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
446
+ const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
447
+ let handoffText = "";
448
+ let promptText = "";
449
+ try {
450
+ handoffText = await readFile(handoffPath, "utf8");
451
+ } catch {
452
+ return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "handoff unreadable" }];
453
+ }
454
+ try {
455
+ promptText = await readFile(promptPath, "utf8");
456
+ } catch {
457
+ return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "prompt copy unreadable" }];
458
+ }
459
+ const openingMessage = extractOpeningMessage(handoffText);
460
+ if (!openingMessage) {
461
+ return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "handoff opening message missing" }];
462
+ }
463
+ const ok = normalizePrompt(promptText) === normalizePrompt(openingMessage);
464
+ return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok, reason: ok ? "" : "convenience copy differs from dev/SESSION_HANDOFF.md" }];
465
+ }
466
+
467
+ function extractOpeningMessage(text) {
468
+ const marker = "📋 Next session: copy and paste the whole block below";
469
+ const markerIndex = text.indexOf(marker);
470
+ if (markerIndex < 0) return null;
471
+ const fenceStart = text.indexOf("```text", markerIndex);
472
+ if (fenceStart < 0) return null;
473
+ const contentStart = text.indexOf("\n", fenceStart);
474
+ const fenceEnd = text.indexOf("```", contentStart + 1);
475
+ if (contentStart < 0 || fenceEnd < 0) return null;
476
+ return text.slice(contentStart + 1, fenceEnd).trim();
477
+ }
478
+
479
+ function normalizePrompt(text) {
480
+ return text.replace(/\r\n/g, "\n").trim();
406
481
  }
407
482
 
408
483
  async function checkRequiredAnchors(root) {
@@ -566,6 +641,8 @@ function printPlan(command, root, mode, plan, version) {
566
641
  console.log(`selected root: ${root}`);
567
642
  console.log(`mode: ${mode}`);
568
643
  console.log("");
644
+ console.log("📋 人話解讀:下面只是計劃。create 會新增缺少檔案,merge 會在備份後安全合併,skip 會保留既有檔案,conflict 代表工具停手等你確認。");
645
+ console.log("");
569
646
  for (const action of ["create", "merge", "skip", "conflict"]) {
570
647
  const items = plan.filter((item) => item.action === action);
571
648
  console.log(`${action}: ${items.length}`);
@@ -574,6 +651,18 @@ function printPlan(command, root, mode, plan, version) {
574
651
  console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
575
652
  }
576
653
 
654
+ function printDryRunExplanation(plan) {
655
+ const conflicts = plan.filter((item) => item.action === "conflict");
656
+ console.log("✅ 這次沒有改動任何檔案。");
657
+ if (conflicts.length === 0) {
658
+ console.log("✅ 沒有發現 conflict。你仍應先看清楚 create / merge / skip 清單,再決定是否執行正式 upgrade。");
659
+ return;
660
+ }
661
+ console.log(`⚠️ 需要人工確認:有 ${conflicts.length} 個既有檔案,工具不能安全判斷怎樣合併。`);
662
+ console.log("⚠️ 這不是檔案壞掉,也沒有覆寫你的檔案。");
663
+ console.log("📋 下一步:把這段輸出貼給 AI,叫它幫你判斷要保留、合併,還是手動修改。");
664
+ }
665
+
577
666
  async function confirmWrite() {
578
667
  const rl = createInterface({ input, output });
579
668
  try {
@@ -632,6 +721,89 @@ async function readPackageVersion() {
632
721
  }
633
722
  }
634
723
 
724
+ async function maybePrintUpdateNotice(currentVersion) {
725
+ if (shouldSkipUpdateCheck()) return;
726
+ if (!isStableSemver(currentVersion)) return;
727
+
728
+ const latestVersion = await fetchLatestVersion();
729
+ if (!latestVersion || !isStableSemver(latestVersion)) return;
730
+ if (compareSemver(latestVersion, currentVersion) <= 0) return;
731
+
732
+ printUpdateNotice(currentVersion, latestVersion);
733
+ }
734
+
735
+ function shouldSkipUpdateCheck() {
736
+ if (process.env.AGENT_HANDOFF_KIT_NO_UPDATE_CHECK === "1") return true;
737
+ if (process.env.AGENT_HANDOFF_KIT_UPDATE_CHECK_FORCE === "1") return false;
738
+ if (process.env.CI) return true;
739
+ if ((process.env.npm_lifecycle_event ?? "").startsWith("qa:")) return true;
740
+ return false;
741
+ }
742
+
743
+ async function fetchLatestVersion() {
744
+ if (process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST) {
745
+ return process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST;
746
+ }
747
+ const url = process.env.AGENT_HANDOFF_KIT_UPDATE_REGISTRY_URL
748
+ ?? "https://registry.npmjs.org/@adamchanadam%2Fagent-handoff-kit/latest";
749
+ const timeoutMs = Number.parseInt(process.env.AGENT_HANDOFF_KIT_UPDATE_TIMEOUT_MS ?? "1200", 10);
750
+ const controller = new AbortController();
751
+ const timer = setTimeout(() => controller.abort(), Number.isFinite(timeoutMs) ? timeoutMs : 1200);
752
+ try {
753
+ const response = await fetch(url, {
754
+ headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
755
+ signal: controller.signal
756
+ });
757
+ if (!response.ok) return null;
758
+ const data = await response.json();
759
+ return typeof data.version === "string" ? data.version : null;
760
+ } catch {
761
+ return null;
762
+ } finally {
763
+ clearTimeout(timer);
764
+ }
765
+ }
766
+
767
+ function isStableSemver(version) {
768
+ return /^\d+\.\d+\.\d+$/.test(version);
769
+ }
770
+
771
+ function compareSemver(left, right) {
772
+ const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
773
+ const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
774
+ for (let i = 0; i < 3; i += 1) {
775
+ if (leftParts[i] > rightParts[i]) return 1;
776
+ if (leftParts[i] < rightParts[i]) return -1;
777
+ }
778
+ return 0;
779
+ }
780
+
781
+ function printUpdateNotice(currentVersion, latestVersion) {
782
+ const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
783
+ const command = "npx @adamchanadam/agent-handoff-kit@latest <command>";
784
+ const lines = [
785
+ `✨ 有新版可用:${currentVersion} -> ${latestVersion}`,
786
+ `如要使用最新版,執行:${command}`,
787
+ "",
788
+ "如果你是全域安裝:",
789
+ "npm install -g @adamchanadam/agent-handoff-kit",
790
+ "",
791
+ "完整 release notes:",
792
+ releaseUrl
793
+ ];
794
+ const width = Math.max(...lines.map((line) => visibleLength(line))) + 2;
795
+ console.log(`╭${"─".repeat(width)}╮`);
796
+ for (const line of lines) {
797
+ console.log(`│ ${line}${" ".repeat(width - visibleLength(line) - 1)}│`);
798
+ }
799
+ console.log(`╰${"─".repeat(width)}╯`);
800
+ console.log("");
801
+ }
802
+
803
+ function visibleLength(text) {
804
+ return [...text].length;
805
+ }
806
+
635
807
  function printCard(version, status, eyes) {
636
808
  console.log(` /\\_/\\ Agent Handoff Kit v${version}`);
637
809
  console.log(` ( ${eyes} ) ${status}`);
@@ -642,25 +814,25 @@ function printCard(version, status, eyes) {
642
814
  function printInstallNextSteps(root, conflictCount) {
643
815
  console.log("");
644
816
  console.log("============================================================");
645
- console.log("安裝完成:下一步請在 AI 對話中操作");
817
+ console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
646
818
  console.log("============================================================");
647
819
  if (conflictCount > 0) {
648
- console.log("狀態:有檔案需要你先處理,詳情見 migration report。");
649
- console.log("請不要忽略 conflict,也不要直接覆寫既有檔案。");
820
+ console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
821
+ console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
822
+ console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
650
823
  console.log("");
651
824
  }
652
- console.log("請注意:下面文字不是 Terminal 指令。");
653
- console.log("請打開你要使用的 AI 工具,新增一段對話,貼上:");
825
+ console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
826
+ console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
654
827
  console.log("------------------------------------------------------------");
655
- console.log(`Work in ${root}.`);
656
- console.log("Read AGENTS.md first. Tell me what you understand before changing files.");
828
+ console.log(`Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
657
829
  console.log("------------------------------------------------------------");
658
830
  console.log("");
659
- console.log("然後直接描述你的任務,例如:");
660
- console.log("整理這個專案,先告訴我你讀到的目前狀態與下一步。");
831
+ console.log("🚀 然後直接描述你的任務,例如:");
832
+ console.log(" 整理這個專案,先告訴我你讀到的目前狀態與下一步。");
661
833
  console.log("");
662
- console.log("如要檢查安裝是否完整,可在 Terminal 執行:");
663
- console.log("npx @adamchanadam/agent-handoff-kit doctor");
834
+ console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
835
+ console.log(" npx @adamchanadam/agent-handoff-kit doctor");
664
836
  console.log("============================================================");
665
837
  }
666
838
 
@@ -692,6 +864,11 @@ Commands:
692
864
  upgrade Preserve existing files; merge safe core updates or report conflicts.
693
865
  doctor Check required installed files.
694
866
 
867
+ 中文速讀:
868
+ ✅ init 第一次安裝 Kit 文件。
869
+ 🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
870
+ 🩺 doctor 檢查必要文件與交接結構是否完整。
871
+
695
872
  After install:
696
873
  Do not type "Follow AGENTS.md" into Terminal.
697
874
  Open your AI tool, start a new chat, paste the shown Work in ... message,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -17,6 +17,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
17
17
  4. Do not let development-only workspace rules enter public runtime.
18
18
  5. Check complexity budget before adding default-core behavior.
19
19
  6. Before creating durable workflow, runbook, or instruction files, first verify whether `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, `dev/DOC_SYNC_REGISTRY.md`, or existing rule packs can carry the need without a new file.
20
+ 7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs its own handoff/log/index/registry persistence.
20
21
 
21
22
  ## Checks
22
23
 
@@ -24,6 +25,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
24
25
  - Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
25
26
  - Confirm old overlapping wording was retired or marked legacy.
26
27
  - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
28
+ - Before claiming completion, inspect the active root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`; do not assume child or demo workspaces cover the parent/root workspace.
27
29
 
28
30
  ## Closeout
29
31
 
@@ -44,6 +44,8 @@ Use this loop for every task:
44
44
  4. QC: run available checks or state why they cannot run.
45
45
  5. PERSIST: update handoff/log and any affected project index or sync registry.
46
46
 
47
+ External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence step for the active project root, and completion cannot be claimed until that root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md` have been inspected and updated or explicitly marked not applicable.
48
+
47
49
  For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
48
50
 
49
51
  ## 3. Safety Boundaries
@@ -71,6 +73,7 @@ At full closeout:
71
73
  7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
72
74
  8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
73
75
  9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
76
+ 10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup.
74
77
 
75
78
  Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
76
79
 
@@ -105,6 +108,8 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
105
108
 
106
109
  After the task, persist durable facts into handoff/log/index/registry. Do not assume the next session remembers pack context unless it is recorded.
107
110
 
111
+ If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs Agent Handoff Kit persistence before the task is complete.
112
+
108
113
  ## Core Complexity Rule
109
114
 
110
115
  New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.1.2 | package prototype |
9
+ | Agent Handoff Kit template version | 0.1.4 | package prototype |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |
@@ -21,6 +21,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
21
21
  | `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
22
22
  | `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
23
23
  | `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini CLI startup |
24
+ | `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
24
25
  | `src/` | application source | coding task |
25
26
  | `tests/` | tests | coding/QC |
26
27
  | `docs/` | user or product docs | doc/public behavior change |
@@ -79,7 +80,7 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
79
80
  | UI behavior | TBD | build + visual/manual check |
80
81
  | Data model | TBD | migration/checks |
81
82
  | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
82
- | Closeout/startup contract | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current |
83
+ | Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + prompt convenience copy matches handoff + workspace identity current |
83
84
 
84
85
  ## External Services
85
86
 
@@ -128,6 +128,8 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
128
128
  <!-- ack:section:next-session-opening-message -->
129
129
  ## Next Session Opening Message
130
130
 
131
+ This fenced block is the authoritative startup prompt. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy.
132
+
131
133
  📋 Next session: copy and paste the whole block below
132
134
 
133
135
  ```text
@@ -0,0 +1,14 @@
1
+ Work in <absolute project root>.
2
+
3
+ Read in order:
4
+ 1. AGENTS.md
5
+ 2. dev/SESSION_HANDOFF.md
6
+ 3. dev/SESSION_LOG.md
7
+ 4. dev/PROJECT_INDEX.md
8
+ 5. dev/RULE_PACKS.md
9
+
10
+ Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
11
+
12
+ If this root does not match the expected project root, stop and ask for confirmation.
13
+
14
+ After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.