@adamchanadam/agent-handoff-kit 0.1.3 → 0.1.5

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.3` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
3
+ 狀態:`v0.1.5` 已正式發佈到 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 Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/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,50 +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 對話使用的文字。
52
-
53
- ## 安裝後第一步
48
+ 然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
54
49
 
55
- 安裝完成後,不要在 Terminal 輸入 `Follow AGENTS.md`。
50
+ ### 三、收工
56
51
 
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 <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
55
+ 收工
69
56
  ```
70
57
 
71
- 接著再寫你的任務,例如:
58
+ 也可以輸入:
72
59
 
73
60
  ```text
74
- 整理這個專案,先告訴我目前狀態、下一步、風險,暫時不要改檔。
61
+ wrap up
62
+ handoff
75
63
  ```
76
64
 
77
- 或:
65
+ AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字放在 fenced `text` code block 內,方便完整複製。安裝後也會有一個更直覺的副本檔:
78
66
 
79
67
  ```text
80
- 更新 README,完成後檢查交接文件是否仍然準確。
68
+ START_NEXT_SESSION_PROMPT.txt
81
69
  ```
82
70
 
71
+ 這個檔案只是方便你複製下次開工提示;真正權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的 `Next Session Opening Message`。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重生副本。
72
+
83
73
  ## 檢查是否安裝完整
84
74
 
85
75
  如要檢查安裝是否完整,可在 Terminal 執行:
@@ -88,28 +78,19 @@ Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing a
88
78
  npx @adamchanadam/agent-handoff-kit doctor
89
79
  ```
90
80
 
91
- 看到 `status: passed`,代表必要文件與基本結構存在。
81
+ 看到 `status: passed`,代表必要文件、基本結構與 `START_NEXT_SESSION_PROMPT.txt` 副本一致性通過檢查。
92
82
 
93
83
  這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
94
84
 
95
- ## 版本提示
96
-
97
- CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
98
-
99
- 若你不想檢查更新,可設定:
100
-
101
- ```bash
102
- AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
103
- ```
104
-
105
85
  ## 會安裝甚麼
106
86
 
107
- 安裝工具會在你的專案中建立以下文件:
87
+ 安裝工具會在你的專案中建立:
108
88
 
109
89
  ```text
110
90
  AGENTS.md
111
91
  CLAUDE.md
112
92
  GEMINI.md
93
+ START_NEXT_SESSION_PROMPT.txt
113
94
  dev/SESSION_HANDOFF.md
114
95
  dev/SESSION_LOG.md
115
96
  dev/PROJECT_INDEX.md
@@ -118,13 +99,12 @@ dev/RULE_PACKS.md
118
99
  dev/rules/*.md
119
100
  ```
120
101
 
121
- 每個文件的用途如下:
122
-
123
102
  | 文件 | 用途 |
124
103
  |---|---|
125
104
  | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
126
105
  | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
127
106
  | `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
107
+ | `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由 handoff 產生。 |
128
108
  | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
129
109
  | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。 |
130
110
  | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
@@ -134,80 +114,59 @@ dev/rules/*.md
134
114
 
135
115
  你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
136
116
 
137
- ## 日常使用方式
138
-
139
- 每次開始新的 AI 工作階段,有兩種做法:
140
-
141
- 1. 最佳:貼上上一輪收工產生的開工文字。那段文字內容最完整、最準確。
142
- 2. 沒有那段文字時,貼上這一句就夠:
143
-
144
- ```text
145
- Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
146
- ```
117
+ ## 工作模式
147
118
 
148
- 你不需要在提示內逐一列出檔案。`AGENTS.md` 本身已包含開工讀序,AI 讀它就會自行讀入交接、紀錄與索引。
119
+ 你不需要記規則包名稱,只要描述任務。AI 會按任務切換工作模式。
149
120
 
150
- 備用(只在你的 AI 工具沒有依 `AGENTS.md` 讀時才需要):在上面那句後面加一句 `Also read dev/SESSION_HANDOFF.md and dev/SESSION_LOG.md.`。
121
+ | 你的任務 | AI 應使用的工作規則 |
122
+ |---|---|
123
+ | 寫或改代碼、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
124
+ | 查資料、比較來源、整理證據 | `research` |
125
+ | 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
126
+ | 整理 Notion、Google Drive 或知識庫 | `knowledge` |
127
+ | 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
128
+ | 改規則、改流程、整理交接 | `agent-governance`;先找既有真源,不盲目新增規則 |
151
129
 
152
- 然後直接描述任務。
130
+ 原則是只讀當前任務需要的規則,不是每次讀全部文件。
153
131
 
154
- 對簡單任務,可以這樣寫:
132
+ ## 安全護欄
155
133
 
156
- ```text
157
- 幫我檢查 README 是否清楚,先只提出問題,不要改檔。
158
- ```
134
+ 就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
159
135
 
160
- 對需要改檔的任務,可以這樣寫:
136
+ - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
137
+ - 機密保護:`.env`、API key、token 不可印出、不可 commit、不可上傳。
138
+ - 查證不猜:用第三方 API、CLI、SDK 前先查官方文件;查不到就標示未核實。
139
+ - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
140
+ - 發佈需明確批准:tag、GitHub Release、npm publish、部署或上傳都不能因「準備好了」而自動執行。
161
141
 
162
- ```text
163
- 請更新 README 的安裝後說明,完成後執行必要檢查,並告訴我改了甚麼。
164
- ```
142
+ ## 已安裝舊版,或已有 AI 記憶文件?
165
143
 
166
- 對需要收工的情況,只需輸入:
144
+ 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,先用最新版 CLI dry-run 預演會發生甚麼:
167
145
 
168
- ```text
169
- 收工
146
+ ```bash
147
+ npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
170
148
  ```
171
149
 
172
- 也可以輸入:
150
+ 確認沒有問題後,再執行:
173
151
 
174
- ```text
175
- wrap up
176
- handoff
152
+ ```bash
153
+ npx @adamchanadam/agent-handoff-kit@latest upgrade
177
154
  ```
178
155
 
179
- AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。那段文字會放在 fenced `text` code block 內,方便完整複製。
156
+ `@latest` 代表使用 npm 上最新的 Agent Handoff Kit CLI。`upgrade` 則負責把專案內已安裝的 Kit 文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會報 conflict,不會靜默覆寫。
180
157
 
181
- ## 工作規則怎樣運作
158
+ 看到 `conflict` 不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把 dry-run 輸出貼給 AI,請它幫你判斷要保留、合併,還是手動修改。
182
159
 
183
- Agent Handoff Kit 會把任務分成不同工作模式。例如:
184
-
185
- | 你的任務 | AI 應使用的工作規則 |
186
- |---|---|
187
- | 修改程式、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
188
- | 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
189
- | 查證資料、比較來源、整理證據 | `research` |
190
- | 整理 Notion、Google Drive 或知識庫 | `knowledge` |
191
- | 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
192
-
193
- 原則是只讀當前任務需要的規則,不是每次讀全部文件。
194
-
195
- ## 既有專案升級
196
-
197
- 若你的專案已經有 `AGENTS.md` 或其他 AI 記憶文件,請先預演,不要直接覆寫:
160
+ ## 版本提示
198
161
 
199
- ```bash
200
- npx @adamchanadam/agent-handoff-kit upgrade --dry-run
201
- ```
162
+ CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
202
163
 
203
- 確認計劃後再執行:
164
+ 若你不想檢查更新,可設定:
204
165
 
205
166
  ```bash
206
- npx @adamchanadam/agent-handoff-kit upgrade
167
+ AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
207
168
  ```
208
169
 
209
- 升級工具會保留既有檔案。能安全合併時才合併;不能安全合併時會報 conflict,不會靜默覆寫。
210
-
211
170
  ## 語言使用
212
171
 
213
172
  安裝後的核心指令文件預設使用英文,原因是不同 AI 工具對英文結構較穩定。這不是限制你的專案必須用英文。
@@ -238,11 +197,11 @@ npm package 只包含安裝所需內容:
238
197
  - `LICENSE`
239
198
  - `package.json`
240
199
 
241
- 原始碼倉庫中的驗收文件與腳本供維護者使用,不會安裝到你的專案。
200
+ GitHub Pages 上的新手介紹頁 `agent-handoff-kit-intro.html` 由原始碼倉庫根目錄發佈;`agent-handoff-kit-intro.html` 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
242
201
 
243
202
  ## 目前限制
244
203
 
245
- - `v0.1.3` 是 GitHub 與 npm 同步發佈版本。
204
+ - `v0.1.5` 是 GitHub 與 npm 同步發佈版本。
246
205
  - 這是早期可用版本,尚未宣稱完整穩定。
247
206
  - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
248
207
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -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
  {
@@ -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
  }
@@ -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 {
@@ -693,13 +782,13 @@ function printUpdateNotice(currentVersion, latestVersion) {
693
782
  const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
694
783
  const command = "npx @adamchanadam/agent-handoff-kit@latest <command>";
695
784
  const lines = [
696
- `✨ Update available! ${currentVersion} -> ${latestVersion}`,
697
- `Run ${command} to use the latest version.`,
785
+ `✨ 有新版可用:${currentVersion} -> ${latestVersion}`,
786
+ `如要使用最新版,執行:${command}`,
698
787
  "",
699
- "For global installs:",
788
+ "如果你是全域安裝:",
700
789
  "npm install -g @adamchanadam/agent-handoff-kit",
701
790
  "",
702
- "See full release notes:",
791
+ "完整 release notes:",
703
792
  releaseUrl
704
793
  ];
705
794
  const width = Math.max(...lines.map((line) => visibleLength(line))) + 2;
@@ -728,8 +817,9 @@ function printInstallNextSteps(root, conflictCount) {
728
817
  console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
729
818
  console.log("============================================================");
730
819
  if (conflictCount > 0) {
731
- console.log("⚠️ 狀態:有檔案需要你先處理,詳情見 migration report。");
732
- console.log("⚠️ 請不要忽略 conflict,也不要直接覆寫既有檔案。");
820
+ console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
821
+ console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
822
+ console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
733
823
  console.log("");
734
824
  }
735
825
  console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
@@ -774,6 +864,11 @@ Commands:
774
864
  upgrade Preserve existing files; merge safe core updates or report conflicts.
775
865
  doctor Check required installed files.
776
866
 
867
+ 中文速讀:
868
+ ✅ init 第一次安裝 Kit 文件。
869
+ 🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
870
+ 🩺 doctor 檢查必要文件與交接結構是否完整。
871
+
777
872
  After install:
778
873
  Do not type "Follow AGENTS.md" into Terminal.
779
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.3",
3
+ "version": "0.1.5",
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.3 | package prototype |
9
+ | Agent Handoff Kit template version | 0.1.5 | 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.