@adamchanadam/agent-handoff-kit 0.3.18 → 0.3.20

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,6 +1,6 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:目前版本為 `v0.3.18` 候選準備。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.20`,已正式發佈。這是早期可用版本,仍在持續完善中。
4
4
 
5
5
  ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
6
 
@@ -10,13 +10,21 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
10
10
 
11
11
  > 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
12
12
  >
13
- > 安裝完成後,在能讀寫本機專案資料夾的 AI agent 對話中貼上:
13
+ > 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
14
14
  >
15
+ > ```text
16
+ > Start Agent Handoff
15
17
  > ```
16
- > Work in <你的資料夾>. Read AGENTS.md first. Then open START_NEXT_SESSION_PROMPT.txt and follow the opening message inside. If START_NEXT_SESSION_PROMPT.txt is missing or seems stale, read dev/SESSION_HANDOFF.md instead. Before changing anything, tell me the current state and your recommended next step.
18
+ >
19
+ > 中文可說「開工」。
20
+ >
21
+ > 只有當 AI 還未指向你的專案資料夾時,才使用帶路徑啟動句:
22
+ >
23
+ > ```text
24
+ > Work in <你的資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
17
25
  > ```
18
26
  >
19
- > AI 會打開專案內的開工提示。第一次安裝後,提示會帶它載入新手引導;之後每次收工後,提示會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
27
+ > AI 會依 `AGENTS.md` 打開專案內的 `START_NEXT_SESSION_PROMPT.txt`。第一次安裝後,該檔會帶它載入新手引導;之後每次收工後,該檔會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
20
28
 
21
29
  想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想看實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 三個日常情境的完整流程示範。本 README 則保留安裝、日常使用與限制。
22
30
 
@@ -37,7 +45,7 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
37
45
 
38
46
  ![Agent Handoff Kit 新手流程](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-new-user-flow.png)
39
47
 
40
- 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話貼固定開工句;AI 會打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
48
+ 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
41
49
 
42
50
  ### 適用工具
43
51
 
@@ -55,7 +63,7 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
55
63
 
56
64
  出現確認問題時,輸入 `yes`。
57
65
 
58
- 安裝完成後,終端機會顯示一段 `Work in ...` 文字。請特別留意:那一段不是給終端機的指令,而是要貼到 AI 對話。
66
+ 安裝完成後,終端機會顯示 AI 對話的下一步。請特別留意:`Start Agent Handoff`、中文「開工」或帶路徑啟動句都不是終端機指令,而是給 AI agent 的對話內容。
59
67
 
60
68
  可用的 AI 工具必須能讀寫此資料夾。不同工具對入口檔的支援可能不同;本工具會同時放置 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,讓常見工具能找到同一套開工路徑。Google 官方遷移文件說明,Antigravity CLI 會讀工作資料夾內的 `GEMINI.md` 和 `AGENTS.md`;因此 `AGENTS.md` 仍是唯一真源,`GEMINI.md` 只做橋接。
61
69
 
@@ -68,32 +76,52 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
68
76
  | 你現在的狀態 | 建議指令 |
69
77
  |---|---|
70
78
  | 第一次在新資料夾使用 | `npx --yes @adamchanadam/agent-handoff-kit@latest init` |
71
- | 不確定是否安裝完整 | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor` |
72
- | 已裝過舊版,想先看升級會改甚麼 | `npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run` |
79
+ | 已安裝舊版,或已有 AI 記憶文件 | `npx --yes @adamchanadam/agent-handoff-kit@latest upgrade` |
80
+ | 不確定是否安裝完整,或升級後想檢查 | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor` |
81
+
82
+ ### 已安裝舊版,或已有 AI 記憶文件?
83
+
84
+ 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,不要重新 `init`,改用 `upgrade`。
85
+
86
+ 你可以先預演:
87
+
88
+ ```bash
89
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
90
+ ```
73
91
 
74
- 舊資料夾若原本已有 `AGENTS.md` 或其他 AI 記憶檔,`init` 會保留既有檔案。這時請先用 `upgrade --dry-run` 看清工具準備怎樣合併,不要手動覆寫。
92
+ `dry-run` 只會預覽,不會完成升級,也不會寫入檔案。確認沒有問題後,才執行正式升級:
93
+
94
+ ```bash
95
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
96
+ ```
97
+
98
+ `@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
99
+
100
+ 看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
75
101
 
76
102
  即使目前資料夾已安裝舊版 Kit 文件,電腦也未必已經有可直接執行的 npm 工具。判斷點不是資料夾有沒有 `AGENTS.md` 或 `dev/`,而是你是否用上方 `npx --yes ... @latest` 路徑取得最新工具。裸寫不帶 `--yes` / `@latest` 的 `npx ... doctor` 不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
77
103
 
78
104
  ### 二、開工
79
105
 
80
- 打開能讀寫本機專案資料夾的 AI agent,在新對話貼上安裝工具顯示的文字。
106
+ 打開能讀寫本機專案資料夾的 AI agent。
81
107
 
82
- **日常開工句(第一次安裝後與之後每次接力都用同一句)**:
108
+ 若 AI 已經在正確專案資料夾內,日常開工只需輸入:
83
109
 
84
110
  ```text
85
- Work in <你的專案資料夾>. Read AGENTS.md first. Then open START_NEXT_SESSION_PROMPT.txt and follow the opening message inside. If START_NEXT_SESSION_PROMPT.txt is missing or seems stale, read dev/SESSION_HANDOFF.md instead. Before changing anything, tell me the current state and your recommended next step.
111
+ Start Agent Handoff
86
112
  ```
87
113
 
88
- 第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
114
+ 中文可說「開工」。
89
115
 
90
- 如果 AI 工具已經在正確專案資料夾內,而且會讀 `AGENTS.md`,日常也可以只說:
116
+ 若 AI 還未指向你的專案資料夾,才使用帶路徑啟動句:
91
117
 
92
118
  ```text
93
- Start Agent Handoff
119
+ Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
94
120
  ```
95
121
 
96
- 中文可說「開工」。若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
122
+ 第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
123
+
124
+ 若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
97
125
 
98
126
  然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
99
127
 
@@ -121,7 +149,7 @@ AI 應更新交接文件,並同步更新下一次開工提示副本:
121
149
  START_NEXT_SESSION_PROMPT.txt
122
150
  ```
123
151
 
124
- 這個檔案保存下一次真正要讀的開工內容。你下次仍只需貼同一條日常開工句,讓 AI 自己打開這個檔案。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
152
+ 這個檔案保存下一次真正要讀的開工內容。你下次仍只需說 `Start Agent Handoff` 或「開工」;若 AI 尚未指向專案資料夾,才使用帶路徑啟動句。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
125
153
 
126
154
  ## 檢查是否安裝完整
127
155
 
@@ -133,7 +161,7 @@ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
133
161
 
134
162
  看到「檢查通過」代表必要文件與基本結構通過檢查。若 `START_NEXT_SESSION_PROMPT.txt` 落後於 `dev/SESSION_HANDOFF.md`,`doctor` 只會提醒;這個便利副本應在收工 closeout 時由 AI 重新生成,不需要在 session 中途手動更新。
135
163
 
136
- `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,仍應把 `Work in ...` 起步句貼到能讀寫本機資料夾的 AI agent 對話,讓 AI 讀入口文件並說明目前狀態。
164
+ `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,應在能讀寫本機資料夾的 AI agent 對話輸入 `Start Agent Handoff` 或「開工」;若 AI 尚未指向資料夾,才使用帶路徑啟動句。
137
165
 
138
166
  ## 會安裝甚麼
139
167
 
@@ -233,24 +261,6 @@ dev/rules/*.md
233
261
  - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
234
262
  - 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
235
263
 
236
- ## 已安裝舊版,或已有 AI 記憶文件?
237
-
238
- 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,可先用最新版安裝工具預演會發生甚麼:
239
-
240
- ```bash
241
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
242
- ```
243
-
244
- 確認沒有問題後,再執行:
245
-
246
- ```bash
247
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
248
- ```
249
-
250
- `@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
251
-
252
- 看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
253
-
254
264
  ## 版本提示
255
265
 
256
266
  安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與版本說明連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
@@ -272,7 +282,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
272
282
 
273
283
  ## 目前限制
274
284
 
275
- - 目前版本為 `v0.3.18` 候選準備;npm registry `latest` 在正式發布前仍以已發布版本為準。
285
+ - 目前版本為 `v0.3.20`,npm registry `latest` 已對齊此版本。
276
286
  - 這是早期可用版本,仍在持續完善中。
277
287
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
278
288
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -71,14 +71,14 @@ const requiredAnchors = [
71
71
  "wrap up",
72
72
  "handoff",
73
73
  "Reconcile `dev/SESSION_HANDOFF.md`",
74
- "Add a concise entry to `dev/SESSION_LOG.md`",
75
- "next-session opening message",
76
- "fenced `text` code block",
77
- "handoff saved",
78
- "📋 Next session: copy and paste the whole block below",
79
- "State Reconciliation Check",
80
- "handoff lifecycle consistency",
81
- "Do not append a new state snapshot",
74
+ "Add a concise entry to `dev/SESSION_LOG.md`",
75
+ "next-session opening message",
76
+ "fenced `text` code block",
77
+ "handoff saved",
78
+ "next-session startup entry",
79
+ "State Reconciliation Check",
80
+ "handoff lifecycle consistency",
81
+ "Do not append a new state snapshot",
82
82
  "START_NEXT_SESSION_PROMPT.txt"
83
83
  ]
84
84
  },
@@ -98,12 +98,12 @@ const requiredAnchors = [
98
98
  "ack:section:sync-status",
99
99
  "ack:section:next-task-required-reading",
100
100
  "ack:section:state-reconciliation-check",
101
- "ack:section:next-session-opening-message",
102
- "ack:field:lifecycle-conflicts-resolved",
103
- "📋 Next session: copy and paste the whole block below",
104
- "```text",
105
- "Read in order:",
106
- "dev/DOC_SYNC_REGISTRY.md"
101
+ "ack:section:next-session-opening-message",
102
+ "ack:field:lifecycle-conflicts-resolved",
103
+ "📋 Next session:",
104
+ "```text",
105
+ "Read in order:",
106
+ "dev/DOC_SYNC_REGISTRY.md"
107
107
  ]
108
108
  },
109
109
  {
@@ -114,12 +114,12 @@ const requiredAnchors = [
114
114
  "## Entry Template",
115
115
  "- **QC:**",
116
116
  "- **Sync:**",
117
- "- **Log maintenance:**",
118
- "### Next Session Opening Message",
119
- "📋 Next session: copy and paste the whole block below",
120
- "```text",
121
- "Read in order:",
122
- "dev/DOC_SYNC_REGISTRY.md"
117
+ "- **Log maintenance:**",
118
+ "### Next Session Opening Message",
119
+ "📋 Next session:",
120
+ "```text",
121
+ "Read in order:",
122
+ "dev/DOC_SYNC_REGISTRY.md"
123
123
  ]
124
124
  },
125
125
  {
@@ -254,13 +254,13 @@ const schemaChecks = [
254
254
  ]
255
255
  },
256
256
  {
257
- target: "dev/SESSION_HANDOFF.md",
258
- label: "handoff opening message structure",
259
- checks: [
260
- includes("📋 Next session: copy and paste the whole block below"),
261
- includes("```text"),
262
- includes("Work in "),
263
- includes("Read in order:"),
257
+ target: "dev/SESSION_HANDOFF.md",
258
+ label: "handoff opening message structure",
259
+ checks: [
260
+ includes("📋 Next session:"),
261
+ includes("```text"),
262
+ includes("Work in "),
263
+ includes("Read in order:"),
264
264
  includes("If this root does not match the expected project root")
265
265
  ]
266
266
  },
@@ -779,7 +779,7 @@ async function runDoctor(root, version, options = {}) {
779
779
 
780
780
  function getFirstUseNextStep(root, lastCloseout) {
781
781
  if (lastCloseout.date) return null;
782
- return `檢查已通過。下一步不要再留在終端機;打開能讀寫此資料夾的 AI agent,貼上:${startupBootstrapPrompt(root)}`;
782
+ return `檢查已通過。下一步不要再留在終端機;打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,輸入 Start Agent Handoff 或「開工」;若 AI 還未指向此資料夾,才貼:${startupPathBootstrapPrompt(root)}`;
783
783
  }
784
784
 
785
785
  // R-030 v0.3.0+: Credential leak prevention sweep. Scans dev/PROJECT_INDEX.md,
@@ -1830,10 +1830,10 @@ function printInstallSummary(version, command, mode, root, counts) {
1830
1830
  console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
1831
1831
  } else if (command === "upgrade") {
1832
1832
  console.log("🚀 下一步:留意下方升級後自動檢查;若全綠即升級完成。");
1833
- } else if (mode === "partial" || counts.skipped > 0) {
1834
- console.log("🚀 下一步:先看下方提示。若你原本已有 AGENTS.md 或其他 AI 規則,請先執行 upgrade --dry-run 補入口連接,再執行 doctor。");
1835
- } else {
1836
- console.log("🚀 下一步:不用再留在終端機。打開 AI 工具,貼下方起步句。");
1833
+ } else if (mode === "partial" || counts.skipped > 0) {
1834
+ console.log("🚀 下一步:先看下方提示。若你原本已有 AGENTS.md 或其他 AI 規則,請先執行 upgrade --dry-run 補入口連接,再執行 doctor。");
1835
+ } else {
1836
+ console.log("🚀 下一步:不用再留在終端機。打開 AI 工具,啟動 Agent Handoff。");
1837
1837
  }
1838
1838
  }
1839
1839
 
@@ -2043,17 +2043,21 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
2043
2043
  console.log("============================================================");
2044
2044
  return;
2045
2045
  }
2046
- console.log("------------------------------------------------------------");
2047
- console.log("⚠️ 下面這句不是終端機指令。");
2048
- console.log("📋 請打開能讀寫此資料夾的 AI agent,新增對話後貼上:");
2046
+ console.log("------------------------------------------------------------");
2047
+ console.log("⚠️ 下面這句不是終端機指令。");
2048
+ console.log("📋 請打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,新增對話後輸入:");
2049
2049
  console.log(" 例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。");
2050
2050
  console.log(" 普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。");
2051
2051
  console.log("------------------------------------------------------------");
2052
- console.log(startupBootstrapPrompt(root));
2052
+ console.log("Start Agent Handoff");
2053
+ console.log("或:開工");
2054
+ console.log("------------------------------------------------------------");
2055
+ console.log("若 AI 還未指向此資料夾,才貼以下帶路徑啟動句:");
2056
+ console.log(startupPathBootstrapPrompt(root));
2053
2057
  console.log("------------------------------------------------------------");
2054
2058
  console.log("");
2055
- console.log("🚀 AI 會先確認這個資料夾,讀取 START_NEXT_SESSION_PROMPT.txt。第一次安裝後,該檔案會觸發新手引導;收工後,該檔案會承載下一次接力狀態。");
2056
- console.log(" 之後若 AI 已在正確專案內,可說「Start Agent Handoff」/「開工」或「Wrap up Agent Handoff」/「收工」;「某某開工 / 某某收工」會先確認是否指本工具交接。");
2059
+ console.log("🚀 AI 會依 AGENTS.md 讀取 START_NEXT_SESSION_PROMPT.txt。第一次安裝後,該檔案會觸發新手引導;收工後,該檔案會承載下一次接力狀態。");
2060
+ console.log(" 收工可說「Wrap up Agent Handoff」/「收工」;「某某開工 / 某某收工」會先確認是否指本工具交接。");
2057
2061
  console.log("============================================================");
2058
2062
  }
2059
2063
 
@@ -2144,41 +2148,48 @@ Commands:
2144
2148
  upgrade Preserve existing files; merge safe core updates or report conflicts.
2145
2149
  doctor Check required installed files.
2146
2150
 
2147
- 中文速讀:
2148
- ✅ 第一次用:先在項目資料夾執行 init。
2149
- 🔄 已裝過:先用 upgrade --dry-run 預演,再決定是否正式升級。
2150
- 🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2151
+ 中文速讀:
2152
+ ✅ 第一次用:先在項目資料夾執行 init。
2153
+ 🔄 已裝過:執行 upgrade;若想先預覽,才加 --dry-run。
2154
+ 🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2151
2155
 
2152
2156
  安裝之後:
2153
- 不要把顯示出來的 "Work in ..." 文字輸入終端機。
2154
- 請打開能讀寫此資料夾的 AI agent,新增對話後貼上那句起步句。
2157
+ 不要把顯示出來的 Start Agent Handoff 或 "Work in ..." 文字輸入終端機。
2158
+ 請打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,新增對話後輸入:
2159
+ Start Agent Handoff
2160
+ 或:開工
2161
+ 若 AI 還未指向此資料夾,才貼帶路徑啟動句:
2162
+ Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
2155
2163
  例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。
2156
2164
  普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。
2157
- AI 會讀取 START_NEXT_SESSION_PROMPT.txt;第一次安裝後該檔案會啟動新手引導,
2165
+ AI 會依 AGENTS.md 讀取 START_NEXT_SESSION_PROMPT.txt;第一次安裝後該檔案會啟動新手引導,
2158
2166
  收工後該檔案會承載下一次接力狀態。
2159
- AI 已在正確專案內時,可用「Start Agent Handoff」/「開工」開始接力,
2160
2167
  用「Wrap up Agent Handoff」/「收工」保存交接;「某某開工 / 某某收工」
2161
2168
  會先確認是否指本工具交接。
2162
2169
 
2163
2170
  終端機範例:
2164
- npx --yes @adamchanadam/agent-handoff-kit@latest init
2165
- npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2166
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
2171
+ npx --yes @adamchanadam/agent-handoff-kit@latest init
2172
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
2173
+ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2174
+
2175
+ 升級前如想先看會改甚麼,才用預演:
2176
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
2177
+ --dry-run 只預覽、不寫入;它不是正式升級完成。
2167
2178
 
2168
2179
  以上才是建議的 npx 用戶路徑。裸寫不帶 --yes / @latest 的 npx doctor
2169
2180
  不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
2170
2181
 
2171
2182
  即使資料夾已有 AGENTS.md 或 dev/,電腦也未必已經有可直接執行的工具;
2172
- npx --yes 只是先取得工具,然後才執行你指定的 init / doctor / upgrade。
2183
+ npx --yes 只是先取得工具,然後才執行你指定的 init / upgrade / doctor。
2173
2184
 
2174
2185
  放在 package 名稱前的 --yes 只讓 npm 先取得執行工具,避免額外出現
2175
2186
  "Need to install" 提示。真正會建立項目文件的是 init;doctor 只檢查。
2176
2187
  `);
2177
2188
  console.log(`📦 版本:v${version}`);
2178
2189
  console.log(`🛠️ 模式:help ready`);
2179
- console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
2190
+ console.log(`🚀 下一步:新項目先執行 init;舊項目執行 upgrade;只想檢查才執行 doctor。`);
2180
2191
  }
2181
2192
 
2182
- function startupBootstrapPrompt(root) {
2183
- return `Work in ${root}. Read AGENTS.md first. Then open START_NEXT_SESSION_PROMPT.txt and follow the opening message inside. If START_NEXT_SESSION_PROMPT.txt is missing or seems stale, read dev/SESSION_HANDOFF.md instead. Before changing anything, tell me the current state and your recommended next step.`;
2193
+ function startupPathBootstrapPrompt(root) {
2194
+ return `Work in ${root}. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.`;
2184
2195
  }
@@ -3,7 +3,10 @@ import path from "node:path";
3
3
 
4
4
  const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
5
5
  const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
6
- const copyMarker = "📋 Next session: copy and paste the whole block below";
6
+ const openingContentMarkers = [
7
+ "📋 Next session: agent-managed startup content below",
8
+ "📋 Next session: copy and paste the whole block below"
9
+ ];
7
10
 
8
11
  export function assessPromptMirrorRoot(root) {
9
12
  const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
@@ -72,10 +75,11 @@ export function extractOpeningMessage(text) {
72
75
  if (sectionStart < 0) return null;
73
76
 
74
77
  const sectionText = text.slice(sectionStart);
75
- const markerIndex = sectionText.indexOf(copyMarker);
76
- if (markerIndex < 0) return null;
78
+ const marker = openingContentMarkers.find((candidate) => sectionText.includes(candidate));
79
+ if (!marker) return null;
77
80
 
78
- const afterMarker = sectionText.slice(markerIndex + copyMarker.length);
81
+ const markerIndex = sectionText.indexOf(marker);
82
+ const afterMarker = sectionText.slice(markerIndex + marker.length);
79
83
  const fenceMatch = /```text[^\r\n]*(?:\r\n?|\n)([\s\S]*?)(?:\r\n?|\n)```/.exec(afterMarker);
80
84
  if (!fenceMatch) return null;
81
85
  return fenceMatch[1];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.18",
3
+ "version": "0.3.20",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -98,7 +98,7 @@ At full closeout:
98
98
  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.
99
99
  8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
100
100
  9. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is the stateful startup prompt that the next local agent must read. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
101
- 10. Show a short closeout card, then provide the stable bootstrap sentence for the next local-agent session in a fenced `text` code block: `Work in <project root>. Read AGENTS.md first. Then open START_NEXT_SESSION_PROMPT.txt and follow the opening message inside. If START_NEXT_SESSION_PROMPT.txt is missing or seems stale, read dev/SESSION_HANDOFF.md instead. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
101
+ 10. Show a short closeout card, then provide the next-session startup entry in a fenced `text` code block. Primary entry, when the next local AI agent is already opened at this project root: `Start Agent Handoff` / `開工`. Fallback entry, when the next AI agent is not yet pointed at the project root: `Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
102
102
  11. Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline). After prepending the new closeout entry, count `## YYYY-MM-DD` H2 entries in `dev/SESSION_LOG.md`. Any entry now at position N ≥ 11 (oldest end) must be moved into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved. Maintain `dev/SESSION_LOG_archive/INDEX.md` (master index of all archive batches; create on first archive). Entries at N=4–10 whose core facts are already absorbed into HANDOFF / PROJECT_INDEX / requirements / decision records collapse to a short-index line using structural anchors, not line numbers. Entries with unique narrative not yet absorbed must first be ported into the relevant durable source, then collapsed. This is mandatory; do not skip. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
103
103
 
104
104
  12. Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline. Each closeout must run the following checks with equal mechanical rigor as the SESSION_LOG N-rule (step 11):
@@ -132,11 +132,11 @@ Use this closeout card:
132
132
  ⚠️ Boundary: <important boundary or none>
133
133
  ```
134
134
 
135
- Immediately before the fenced opening message, write:
136
-
137
- ```text
138
- 📋 Next session: copy and paste the whole block below
139
- ```
135
+ In `dev/SESSION_HANDOFF.md`, immediately before the fenced `Next Session Opening Message` content, write:
136
+
137
+ ```text
138
+ 📋 Next session: agent-managed startup content below
139
+ ```
140
140
 
141
141
  Record only work actually performed in the current session. Do not copy old completed work forward as new work.
142
142
  `dev/SESSION_HANDOFF.md` carries continuity. `dev/SESSION_LOG.md` carries recent evidence. Archive old detail only when needed; do not create an archive directory by default.
@@ -133,9 +133,9 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
133
133
  <!-- ack:section:next-session-opening-message -->
134
134
  ## Next Session Opening Message
135
135
 
136
- 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. User-facing closeout output may show the stable bootstrap sentence that tells the next agent to read this file; do not hand-write a separate stateful prompt in the final response.
137
-
138
- 📋 Next session: copy and paste the whole block below
136
+ This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
137
+
138
+ 📋 Next session: agent-managed startup content below
139
139
 
140
140
  ```text
141
141
  Work in <absolute project root>.
@@ -27,7 +27,7 @@ Before closeout, check whether older log detail should be kept, summarized, or a
27
27
 
28
28
  ### Next Session Opening Message
29
29
 
30
- 📋 Next session: copy and paste the whole block below
30
+ 📋 Next session: agent-managed startup content below
31
31
 
32
32
  ```text
33
33
  Work in <absolute project root>.