@adamchanadam/agent-handoff-kit 0.3.25 → 0.3.26

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,292 +1,292 @@
1
- # Agent Handoff Kit
2
-
3
- 狀態:目前版本為 `v0.3.25`。這是早期可用版本,仍在持續完善中。
4
-
5
- ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
-
7
- Agent Handoff Kit 是 **AI 對話之間的接力棒**。
8
-
9
- 它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
10
-
11
- > 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
12
- >
13
- > 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
14
- >
15
- > ```text
16
- > Start Agent Handoff
17
- > ```
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.
25
- > ```
26
- >
27
- > AI 會依 `AGENTS.md` 打開專案內的 `START_NEXT_SESSION_PROMPT.txt`。第一次安裝後,該檔會帶它載入新手引導;之後每次收工後,該檔會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
28
-
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 則保留安裝、日常使用與限制。
30
-
31
- ## 它解決甚麼問題
32
-
33
- 用 AI 做長期項目,常見四個問題:
34
-
35
- | 問題 | Agent Handoff Kit 怎樣處理 |
36
- |---|---|
37
- | 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
38
- | 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
39
- | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
40
- | AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
41
-
42
- 它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
43
-
44
- ## 三步上手
45
-
46
- ![Agent Handoff Kit 新手流程](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-new-user-flow.png)
47
-
48
- 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。準備結束本輪工作時說「收工」,讓 AI 留下下一次能接上的交接。
49
-
50
- ### 適用工具
51
-
52
- Agent Handoff Kit 適合能讀寫本機專案資料夾的 agentic AI 工具,例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity,或其他具備本機工作區讀寫能力的工具。
53
-
54
- 它不適合普通 web chat AI,例如沒有本機檔案讀寫能力的 ChatGPT、Claude、Gemini 網頁版。上載檔案或貼上交接內容不能取代本工具需要的本機讀寫能力;這類工具不能可靠維護專案內的交接文件。
55
-
56
- ### 一、安裝
57
-
58
- 在你的專案資料夾打開終端機,執行:
59
-
60
- ```bash
61
- npx --yes @adamchanadam/agent-handoff-kit@latest init
62
- ```
63
-
64
- 出現確認問題時,輸入 `yes`。
65
-
66
- 安裝完成後,終端機會顯示 AI 對話的下一步。請特別留意:`Start Agent Handoff`、中文「開工」或帶路徑啟動句都不是終端機指令,而是給 AI agent 的對話內容。
67
-
68
- 可用的 AI 工具必須能讀寫此資料夾。不同工具對入口檔的支援可能不同;本工具會同時放置 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,讓常見工具能找到同一套開工路徑。Google 官方遷移文件說明,Antigravity CLI 會讀工作資料夾內的 `GEMINI.md` 和 `AGENTS.md`;因此 `AGENTS.md` 仍是唯一真源,`GEMINI.md` 只做橋接。
69
-
70
- > 補充:`--yes` 只是讓 npm 先取得這個工具,避免多問一次安裝確認。真正會建立項目文件的是 `init`;`doctor` 只檢查,不會安裝或改動你的項目文件。
71
-
72
- 安裝成功後,先做 AI 對話,不必立刻跑 `doctor`。`doctor` 是之後不確定狀態、升級後驗收,或 AI 要排錯時才需要用的檢查工具。
73
-
74
- ### 常見入口
75
-
76
- | 你現在的狀態 | 建議指令 |
77
- |---|---|
78
- | 第一次在新資料夾使用 | `npx --yes @adamchanadam/agent-handoff-kit@latest init` |
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
- ```
91
-
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
- 正式升級最後會自動做一次 `doctor` 健康檢查。若檔案已是最新版本,但交接狀態仍需要處理,工具會列出需要修正的位置;若屬於工具可安全判斷的 Kit 結構或提示副本問題,會先自動修復再檢查。
101
-
102
- 看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
103
-
104
- 即使目前資料夾已安裝舊版 Kit 文件,電腦也未必已經有可直接執行的 npm 工具。判斷點不是資料夾有沒有 `AGENTS.md` 或 `dev/`,而是你是否用上方 `npx --yes ... @latest` 路徑取得最新工具。裸寫不帶 `--yes` / `@latest` 的 `npx ... doctor` 不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
105
-
106
- ### 二、開工
107
-
108
- 打開能讀寫本機專案資料夾的 AI agent。
109
-
110
- 若 AI 已經在正確專案資料夾內,日常開工只需輸入:
111
-
112
- ```text
113
- Start Agent Handoff
114
- ```
115
-
116
- 中文可說「開工」。
117
-
118
- 若 AI 還未指向你的專案資料夾,才使用帶路徑啟動句:
119
-
120
- ```text
121
- Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
122
- ```
123
-
124
- 第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
125
-
126
- 若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
127
-
128
- 然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
129
-
130
- ### 三、收工
131
-
132
- 本輪工作完成、準備結束時,只需輸入:
133
-
134
- ```text
135
- 收工
136
- ```
137
-
138
- 也可以輸入:
139
-
140
- ```text
141
- Wrap up Agent Handoff
142
- wrap up
143
- handoff
144
- ```
145
-
146
- 若你說的是「某某收工」(例如餐廳收工、今天活動收工)這類帶其他上下文的話,AI 應先反問你是否要執行 Agent Handoff Kit 收工交接,而不是立即改寫交接文件。
147
-
148
- AI 應更新交接文件,並同步更新下一次開工提示副本:
149
-
150
- ```text
151
- START_NEXT_SESSION_PROMPT.txt
152
- ```
153
-
154
- 這個檔案保存下一次真正要讀的開工內容。你下次仍只需說 `Start Agent Handoff` 或「開工」;若 AI 尚未指向專案資料夾,才使用帶路徑啟動句。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
155
-
156
- ## 檢查是否安裝完整
157
-
158
- 如你不確定目前資料夾是否安裝完整,或剛做完升級,可在終端機執行:
159
-
160
- ```bash
161
- npx --yes @adamchanadam/agent-handoff-kit@latest doctor
162
- ```
163
-
164
- 看到「檢查通過」代表必要文件與基本結構通過檢查。若 `START_NEXT_SESSION_PROMPT.txt` 落後於 `dev/SESSION_HANDOFF.md`,`doctor` 只會提醒;這個便利副本應在收工 closeout 時由 AI 重新生成,不需要在 session 中途手動更新。
165
-
166
- `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,應在能讀寫本機資料夾的 AI agent 對話輸入 `Start Agent Handoff` 或「開工」;若 AI 尚未指向資料夾,才使用帶路徑啟動句。
167
-
168
- ## 會安裝甚麼
169
-
170
- 安裝工具會在你的專案中建立:
171
-
172
- ```text
173
- AGENTS.md
174
- CLAUDE.md
175
- GEMINI.md
176
- START_NEXT_SESSION_PROMPT.txt
177
- dev/SESSION_HANDOFF.md
178
- dev/SESSION_LOG.md
179
- dev/PROJECT_INDEX.md
180
- dev/PROJECT_DECISIONS.md
181
- dev/DOC_SYNC_REGISTRY.md
182
- dev/RULE_PACKS.md
183
- dev/rules/*.md
184
- ```
185
-
186
- | 文件 | 用途 |
187
- |---|---|
188
- | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
189
- | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
190
- | `GEMINI.md` | 讓 Google Antigravity CLI、Gemini CLI 遷移期或相容入口工具找到同一套入口。Antigravity CLI 會讀 `AGENTS.md` 與 `GEMINI.md`,所以此檔只做橋接,不另寫一套規則。 |
191
- | `START_NEXT_SESSION_PROMPT.txt` | 下一次開工時由 AI 讀取的提示副本;初次安裝時放新手引導,收工後由交接文件自動產生。 |
192
- | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
193
- | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。每次收工會先做維護觸發檢查;長期使用後,命中條件時舊條目會整理入封存資料夾,主檔保持簡短。日常使用不需要打開本檔,做審計或追溯時才看。 |
194
- | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
195
- | `dev/PROJECT_DECISIONS.md` | 保存項目的長期演進、決策、架構取捨與學習觀察。AI 在每次收工時檢查是否需要維護,重大決策可即時寫入;日常開工不需要讀。當你問「之前為何這樣做」時,AI 會自己從這裡找答案。 |
196
- | `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
197
- | `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
198
- | `dev/rules/*.md` | 按任務載入的工作規則,共十份:安全、寫代碼、寫作、研究、AI 治理、發佈、知識整理、溝通、新手引導、外部工具治理。 |
199
-
200
- 你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
201
-
202
- ## SESSION_LOG 的自動整理機制
203
-
204
- 長期使用後,`dev/SESSION_LOG.md` 不會無止境膨脹。每次你講「收工」,AI 會先做一次很短的維護觸發檢查;命中條件時才完整整理:
205
-
206
- - 最新三條對話紀錄保留完整內容,作為意外時的後備。
207
- - 之後的條目,如核心內容已被交接文件吸收,會在需要整理時縮成一行短索引(日期 + 標題 + 對應資料來源)。
208
- - 累積到第十一條開始,會封存到 `dev/SESSION_LOG_archive/` 資料夾;主檔末尾留一份封存索引,方便日後追溯。
209
- - 即使沒有明顯觸發,AI 也會每十次收工做一次完整維護兜底,避免長期使用後慢慢漏記。
210
-
211
- 接力責任由 `dev/SESSION_HANDOFF.md` 承擔;`dev/SESSION_LOG.md` 主要用來日後追溯。**新對話開工不需要讀完整紀錄**,只需要讀 `AGENTS.md`、`dev/SESSION_HANDOFF.md` 和索引文件,就足夠接力。
212
-
213
- 所以你的電腦中的 `dev/` 資料夾不會被對話紀錄不停撐大,也不需要你手動清理。如主檔意外膨脹,`doctor` 會在輸出顯示提醒,請 AI 下次收工時整理;這只是提醒,不會令 `doctor` 失敗,也不阻擋安裝。
214
-
215
- ## 項目決策日誌
216
-
217
- `dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察。AI 每次收工都會檢查是否需要維護;遇到重大決策、方向轉變、架構取捨或重複出現的模式時才寫入,並且每十次收工做一次完整兜底。日常開工不需要讀本檔;當你問「之前為何這樣做」時,AI 會自己從這裡找答案。
218
-
219
- 短期單一任務的項目,本檔幾乎保持空白,你不需要維護。長期持續演進的項目,AI 會自動累積以下四類紀錄:
220
-
221
- - **長期演進** —— 任務需求隨時間的變化
222
- - **決策封存** —— 累積決策的歷史紀錄
223
- - **架構取捨** —— 主要設計選擇與原因
224
- - **學習觀察** —— 多次對話累積的觀察與心得
225
-
226
- 當交接文件中的決策清單累積到三十條以上,AI 會自動把較舊的條目搬入本檔,保持交接文件簡潔。
227
-
228
- 新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
229
-
230
- ## 外部工具治理
231
-
232
- 如你的項目涉及外部工具(例如 Notion、Google Drive、Slack、Linear、GitHub 等),Agent Handoff Kit 提供跨對話的治理紀律,確保 AI 在不同對話之間能穩定使用這些工具。
233
-
234
- **登記表**:`dev/PROJECT_INDEX.md` 內設有「已裝外部工具」段,記錄項目已連接哪些外部工具。AI 在新對話開工時會自動讀取,了解能直接讀寫哪些資料來源。
235
-
236
- **機密分離原則**:API key、token、密碼等任何敏感資料**永不寫入** `dev/` 內任何檔案。這類機密由你的 AI 工具或系統安全儲存管理,與本工具完全分離。`doctor` 會自動掃描,若發現任何疑似敏感資料寫入,會立即報錯。
237
-
238
- **已裝才用**:如你已透過 Claude Desktop 等工具連接好外部服務,AI 會直接使用對應功能讀寫資料。如未連接,AI 會改為產生需要你手動同步的內容,並提示你下一步。
239
-
240
- **失靈不亂修**:如外部工具中途認證失效,AI 會立即說明,不會嘗試自動修復;同時將狀況記錄入交接文件,方便你或下一個對話判斷處理。
241
-
242
- ## 工作模式
243
-
244
- 你不需要記規則名稱,只要描述任務。AI 會按任務切換工作模式。
245
-
246
- | 你的任務 | AI 應使用的工作規則 |
247
- |---|---|
248
- | 寫或改代碼、檢查錯誤、執行測試 | 寫代碼規則;涉及刪除、覆寫、Git、套件管理或外部服務時,再讀安全規則 |
249
- | 查資料、比較來源、整理證據 | 研究規則 |
250
- | 改 README、寫說明、整理文案 | 寫作規則,通常再加溝通規則 |
251
- | 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
252
- | 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
253
- | 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
254
-
255
- 原則是只讀當前任務需要的規則,不是每次讀全部文件。
256
-
257
- ## 安全護欄
258
-
259
- 就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
260
-
261
- - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
262
- - 機密保護:`.env`、API key、token 不可印出、不可提交、不可上傳。
263
- - 查證不猜:使用第三方服務或工具前先查官方文件;查不到就標示未核實。
264
- - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
265
- - 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
266
-
267
- ## 版本提示
268
-
269
- 安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與版本說明連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
270
-
271
- 若你不想檢查更新,可設定環境變數:
272
-
273
- ```bash
274
- AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
275
- ```
276
-
277
- ## 配合 Adam-AI-Instructions 使用
278
-
279
- Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions) 配合使用。兩者分工互補,不重疊:
280
-
281
- - **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
282
- - **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
283
-
284
- 到該倉庫的「五、提示詞索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具設定。然後再在項目資料夾執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init` 安裝本工具。兩者配合,就能同時照顧單次對話的做事規矩,以及不同對話之間的項目接力。
285
-
286
- ## 目前限制
287
-
288
- - 目前版本為 `v0.3.25`;正式安裝請以 npm registry `latest` 顯示為準。
289
- - 這是早期可用版本,仍在持續完善中。
290
- - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
291
- - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
292
- - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
1
+ # Agent Handoff Kit
2
+
3
+ 狀態:目前版本為 `v0.3.26`。這是早期可用版本,仍在持續完善中。
4
+
5
+ ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
+
7
+ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
8
+
9
+ 它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
10
+
11
+ > 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
12
+ >
13
+ > 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
14
+ >
15
+ > ```text
16
+ > Start Agent Handoff
17
+ > ```
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.
25
+ > ```
26
+ >
27
+ > AI 會依 `AGENTS.md` 打開專案內的 `START_NEXT_SESSION_PROMPT.txt`。第一次安裝後,該檔會帶它載入新手引導;之後每次收工後,該檔會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
28
+
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 則保留安裝、日常使用與限制。
30
+
31
+ ## 它解決甚麼問題
32
+
33
+ 用 AI 做長期項目,常見四個問題:
34
+
35
+ | 問題 | Agent Handoff Kit 怎樣處理 |
36
+ |---|---|
37
+ | 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
38
+ | 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
39
+ | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
40
+ | AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
41
+
42
+ 它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
43
+
44
+ ## 三步上手
45
+
46
+ ![Agent Handoff Kit 新手流程](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-new-user-flow.png)
47
+
48
+ 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。準備結束本輪工作時說「收工」,讓 AI 留下下一次能接上的交接。
49
+
50
+ ### 適用工具
51
+
52
+ Agent Handoff Kit 適合能讀寫本機專案資料夾的 agentic AI 工具,例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity,或其他具備本機工作區讀寫能力的工具。
53
+
54
+ 它不適合普通 web chat AI,例如沒有本機檔案讀寫能力的 ChatGPT、Claude、Gemini 網頁版。上載檔案或貼上交接內容不能取代本工具需要的本機讀寫能力;這類工具不能可靠維護專案內的交接文件。
55
+
56
+ ### 一、安裝
57
+
58
+ 在你的專案資料夾打開終端機,執行:
59
+
60
+ ```bash
61
+ npx --yes @adamchanadam/agent-handoff-kit@latest init
62
+ ```
63
+
64
+ 出現確認問題時,輸入 `yes`。
65
+
66
+ 安裝完成後,終端機會顯示 AI 對話的下一步。請特別留意:`Start Agent Handoff`、中文「開工」或帶路徑啟動句都不是終端機指令,而是給 AI agent 的對話內容。
67
+
68
+ 可用的 AI 工具必須能讀寫此資料夾。不同工具對入口檔的支援可能不同;本工具會同時放置 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,讓常見工具能找到同一套開工路徑。Google 官方遷移文件說明,Antigravity CLI 會讀工作資料夾內的 `GEMINI.md` 和 `AGENTS.md`;因此 `AGENTS.md` 仍是唯一真源,`GEMINI.md` 只做橋接。
69
+
70
+ > 補充:`--yes` 只是讓 npm 先取得這個工具,避免多問一次安裝確認。真正會建立項目文件的是 `init`;`doctor` 只檢查,不會安裝或改動你的項目文件。
71
+
72
+ 安裝成功後,先做 AI 對話,不必立刻跑 `doctor`。`doctor` 是之後不確定狀態、升級後驗收,或 AI 要排錯時才需要用的檢查工具。
73
+
74
+ ### 常見入口
75
+
76
+ | 你現在的狀態 | 建議指令 |
77
+ |---|---|
78
+ | 第一次在新資料夾使用 | `npx --yes @adamchanadam/agent-handoff-kit@latest init` |
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
+ ```
91
+
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
+ 正式升級最後會自動做一次 `doctor` 健康檢查。若檔案已是最新版本,但交接狀態仍需要處理,工具會列出需要修正的位置;若屬於工具可安全判斷的 Kit 結構或提示副本問題,會先自動修復再檢查。
101
+
102
+ 看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
103
+
104
+ 即使目前資料夾已安裝舊版 Kit 文件,電腦也未必已經有可直接執行的 npm 工具。判斷點不是資料夾有沒有 `AGENTS.md` 或 `dev/`,而是你是否用上方 `npx --yes ... @latest` 路徑取得最新工具。裸寫不帶 `--yes` / `@latest` 的 `npx ... doctor` 不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
105
+
106
+ ### 二、開工
107
+
108
+ 打開能讀寫本機專案資料夾的 AI agent。
109
+
110
+ 若 AI 已經在正確專案資料夾內,日常開工只需輸入:
111
+
112
+ ```text
113
+ Start Agent Handoff
114
+ ```
115
+
116
+ 中文可說「開工」。
117
+
118
+ 若 AI 還未指向你的專案資料夾,才使用帶路徑啟動句:
119
+
120
+ ```text
121
+ Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
122
+ ```
123
+
124
+ 第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
125
+
126
+ 若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
127
+
128
+ 然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
129
+
130
+ ### 三、收工
131
+
132
+ 本輪工作完成、準備結束時,只需輸入:
133
+
134
+ ```text
135
+ 收工
136
+ ```
137
+
138
+ 也可以輸入:
139
+
140
+ ```text
141
+ Wrap up Agent Handoff
142
+ wrap up
143
+ handoff
144
+ ```
145
+
146
+ 若你說的是「某某收工」(例如餐廳收工、今天活動收工)這類帶其他上下文的話,AI 應先反問你是否要執行 Agent Handoff Kit 收工交接,而不是立即改寫交接文件。
147
+
148
+ AI 應更新交接文件,並同步更新下一次開工提示副本:
149
+
150
+ ```text
151
+ START_NEXT_SESSION_PROMPT.txt
152
+ ```
153
+
154
+ 這個檔案保存下一次真正要讀的開工內容。你下次仍只需說 `Start Agent Handoff` 或「開工」;若 AI 尚未指向專案資料夾,才使用帶路徑啟動句。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
155
+
156
+ ## 檢查是否安裝完整
157
+
158
+ 如你不確定目前資料夾是否安裝完整,或剛做完升級,可在終端機執行:
159
+
160
+ ```bash
161
+ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
162
+ ```
163
+
164
+ 看到「檢查通過」代表必要文件與基本結構通過檢查。若 `START_NEXT_SESSION_PROMPT.txt` 落後於 `dev/SESSION_HANDOFF.md`,`doctor` 只會提醒;這個便利副本應在收工 closeout 時由 AI 重新生成,不需要在 session 中途手動更新。
165
+
166
+ `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,應在能讀寫本機資料夾的 AI agent 對話輸入 `Start Agent Handoff` 或「開工」;若 AI 尚未指向資料夾,才使用帶路徑啟動句。
167
+
168
+ ## 會安裝甚麼
169
+
170
+ 安裝工具會在你的專案中建立:
171
+
172
+ ```text
173
+ AGENTS.md
174
+ CLAUDE.md
175
+ GEMINI.md
176
+ START_NEXT_SESSION_PROMPT.txt
177
+ dev/SESSION_HANDOFF.md
178
+ dev/SESSION_LOG.md
179
+ dev/PROJECT_INDEX.md
180
+ dev/PROJECT_DECISIONS.md
181
+ dev/DOC_SYNC_REGISTRY.md
182
+ dev/RULE_PACKS.md
183
+ dev/rules/*.md
184
+ ```
185
+
186
+ | 文件 | 用途 |
187
+ |---|---|
188
+ | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
189
+ | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
190
+ | `GEMINI.md` | 讓 Google Antigravity CLI、Gemini CLI 遷移期或相容入口工具找到同一套入口。Antigravity CLI 會讀 `AGENTS.md` 與 `GEMINI.md`,所以此檔只做橋接,不另寫一套規則。 |
191
+ | `START_NEXT_SESSION_PROMPT.txt` | 下一次開工時由 AI 讀取的提示副本;初次安裝時放新手引導,收工後由交接文件自動產生。 |
192
+ | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
193
+ | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。每次收工會先做維護觸發檢查;長期使用後,命中條件時舊條目會整理入封存資料夾,主檔保持簡短。日常使用不需要打開本檔,做審計或追溯時才看。 |
194
+ | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
195
+ | `dev/PROJECT_DECISIONS.md` | 保存項目的長期演進、決策、架構取捨與學習觀察。AI 在每次收工時檢查是否需要維護,重大決策可即時寫入;日常開工不需要讀。當你問「之前為何這樣做」時,AI 會自己從這裡找答案。 |
196
+ | `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
197
+ | `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
198
+ | `dev/rules/*.md` | 按任務載入的工作規則,共十份:安全、寫代碼、寫作、研究、AI 治理、發佈、知識整理、溝通、新手引導、外部工具治理。 |
199
+
200
+ 你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
201
+
202
+ ## SESSION_LOG 的自動整理機制
203
+
204
+ 長期使用後,`dev/SESSION_LOG.md` 不會無止境膨脹。每次你講「收工」,AI 會先做一次很短的維護觸發檢查;命中條件時才完整整理:
205
+
206
+ - 最新三條對話紀錄保留完整內容,作為意外時的後備。
207
+ - 之後的條目,如核心內容已被交接文件吸收,會在需要整理時縮成一行短索引(日期 + 標題 + 對應資料來源)。
208
+ - 累積到第十一條開始,會封存到 `dev/SESSION_LOG_archive/` 資料夾;主檔末尾留一份封存索引,方便日後追溯。
209
+ - 即使沒有明顯觸發,AI 也會每十次收工做一次完整維護兜底,避免長期使用後慢慢漏記。
210
+
211
+ 接力責任由 `dev/SESSION_HANDOFF.md` 承擔;`dev/SESSION_LOG.md` 主要用來日後追溯。**新對話開工不需要讀完整紀錄**,只需要讀 `AGENTS.md`、`dev/SESSION_HANDOFF.md` 和索引文件,就足夠接力。
212
+
213
+ 所以你的電腦中的 `dev/` 資料夾不會被對話紀錄不停撐大,也不需要你手動清理。如主檔意外膨脹,`doctor` 會在輸出顯示提醒,請 AI 下次收工時整理;這只是提醒,不會令 `doctor` 失敗,也不阻擋安裝。
214
+
215
+ ## 項目決策日誌
216
+
217
+ `dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察。AI 每次收工都會檢查是否需要維護;遇到重大決策、方向轉變、架構取捨或重複出現的模式時才寫入,並且每十次收工做一次完整兜底。日常開工不需要讀本檔;當你問「之前為何這樣做」時,AI 會自己從這裡找答案。
218
+
219
+ 短期單一任務的項目,本檔幾乎保持空白,你不需要維護。長期持續演進的項目,AI 會自動累積以下四類紀錄:
220
+
221
+ - **長期演進** —— 任務需求隨時間的變化
222
+ - **決策封存** —— 累積決策的歷史紀錄
223
+ - **架構取捨** —— 主要設計選擇與原因
224
+ - **學習觀察** —— 多次對話累積的觀察與心得
225
+
226
+ 當交接文件中的決策清單累積到三十條以上,AI 會自動把較舊的條目搬入本檔,保持交接文件簡潔。
227
+
228
+ 新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
229
+
230
+ ## 外部工具治理
231
+
232
+ 如你的項目涉及外部工具(例如 Notion、Google Drive、Slack、Linear、GitHub 等),Agent Handoff Kit 提供跨對話的治理紀律,確保 AI 在不同對話之間能穩定使用這些工具。
233
+
234
+ **登記表**:`dev/PROJECT_INDEX.md` 內設有「已裝外部工具」段,記錄項目已連接哪些外部工具。AI 在新對話開工時會自動讀取,了解能直接讀寫哪些資料來源。
235
+
236
+ **機密分離原則**:API key、token、密碼等任何敏感資料**永不寫入** `dev/` 內任何檔案。這類機密由你的 AI 工具或系統安全儲存管理,與本工具完全分離。`doctor` 會自動掃描,若發現任何疑似敏感資料寫入,會立即報錯。
237
+
238
+ **已裝才用**:如你已透過 Claude Desktop 等工具連接好外部服務,AI 會直接使用對應功能讀寫資料。如未連接,AI 會改為產生需要你手動同步的內容,並提示你下一步。
239
+
240
+ **失靈不亂修**:如外部工具中途認證失效,AI 會立即說明,不會嘗試自動修復;同時將狀況記錄入交接文件,方便你或下一個對話判斷處理。
241
+
242
+ ## 工作模式
243
+
244
+ 你不需要記規則名稱,只要描述任務。AI 會按任務切換工作模式。
245
+
246
+ | 你的任務 | AI 應使用的工作規則 |
247
+ |---|---|
248
+ | 寫或改代碼、檢查錯誤、執行測試 | 寫代碼規則;涉及刪除、覆寫、Git、套件管理或外部服務時,再讀安全規則 |
249
+ | 查資料、比較來源、整理證據 | 研究規則 |
250
+ | 改 README、寫說明、整理文案 | 寫作規則,通常再加溝通規則 |
251
+ | 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
252
+ | 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
253
+ | 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
254
+
255
+ 原則是只讀當前任務需要的規則,不是每次讀全部文件。
256
+
257
+ ## 安全護欄
258
+
259
+ 就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
260
+
261
+ - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
262
+ - 機密保護:`.env`、API key、token 不可印出、不可提交、不可上傳。
263
+ - 查證不猜:使用第三方服務或工具前先查官方文件;查不到就標示未核實。
264
+ - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
265
+ - 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
266
+
267
+ ## 版本提示
268
+
269
+ 安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與版本說明連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
270
+
271
+ 若你不想檢查更新,可設定環境變數:
272
+
273
+ ```bash
274
+ AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
275
+ ```
276
+
277
+ ## 配合 Adam-AI-Instructions 使用
278
+
279
+ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions) 配合使用。兩者分工互補,不重疊:
280
+
281
+ - **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
282
+ - **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
283
+
284
+ 到該倉庫的「五、提示詞索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具設定。然後再在項目資料夾執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init` 安裝本工具。兩者配合,就能同時照顧單次對話的做事規矩,以及不同對話之間的項目接力。
285
+
286
+ ## 目前限制
287
+
288
+ - 目前版本為 `v0.3.26`;正式安裝請以 npm registry `latest` 顯示為準。
289
+ - 這是早期可用版本,仍在持續完善中。
290
+ - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
291
+ - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
292
+ - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
@@ -33,7 +33,10 @@ const mappings = [
33
33
  ["packs/integrations.md", "dev/rules/integrations.md"]
34
34
  ];
35
35
 
36
- const requiredTargets = mappings.map(([, target]) => target);
36
+ const requiredTargets = mappings.map(([, target]) => target);
37
+ const rulePackTargets = mappings
38
+ .map(([, target]) => target)
39
+ .filter((target) => target.startsWith("dev/rules/"));
37
40
  const managedCoreStart = "<!-- BEGIN Agent Handoff Kit managed core -->";
38
41
  const managedCoreEnd = "<!-- END Agent Handoff Kit managed core -->";
39
42
 
@@ -555,11 +558,16 @@ async function runInstall(command, root, options, version) {
555
558
  const migrationDir = path.join(root, "dev/governance_migrations", stamp);
556
559
  const backupDir = path.join(migrationDir, "backup");
557
560
 
558
- for (const item of plan) {
559
- if (item.action !== "create") continue;
560
- await mkdir(path.dirname(item.targetAbs), { recursive: true });
561
- await copyFile(item.sourceAbs, item.targetAbs);
562
- created.push(item.targetRel);
561
+ for (const item of plan) {
562
+ if (item.action !== "create") continue;
563
+ await mkdir(path.dirname(item.targetAbs), { recursive: true });
564
+ if (item.targetRel === "AGENTS.md") {
565
+ const sourceText = await readFile(item.sourceAbs, "utf8");
566
+ await writeFile(item.targetAbs, mergeManagedBlock("", sourceText), "utf8");
567
+ } else {
568
+ await copyFile(item.sourceAbs, item.targetAbs);
569
+ }
570
+ created.push(item.targetRel);
563
571
  }
564
572
 
565
573
  await hydrateInitialOpeningPrompt(root, created);
@@ -683,17 +691,21 @@ async function runDoctor(root, version, options = {}) {
683
691
  console.log(`required files: ${rows.length}`);
684
692
  for (const row of rows) {
685
693
  console.log(`${row.ok ? "ok" : "missing"} ${row.target}`);
686
- }
687
-
688
- if (missing.length > 0) {
689
- printDoctorSummary(version, root, "needs-fix", {
690
- checked: rows.length,
691
- failedKind: "missing files",
692
- failedCount: missing.length,
693
- nextStep: missing.length === rows.length
694
- ? "這個資料夾未安裝 Kit。若這就是你的項目資料夾,請執行:npx --yes @adamchanadam/agent-handoff-kit@latest init"
695
- : "這個資料夾只裝了一部分 Kit 檔案。請先確認路徑;如路徑正確,執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run"
696
- });
694
+ }
695
+
696
+ if (missing.length > 0) {
697
+ const misplacedRulePacks = await findMisplacedRulePacks(root, missing);
698
+ printMisplacedRulePackWarnings(misplacedRulePacks);
699
+ printDoctorSummary(version, root, "needs-fix", {
700
+ checked: rows.length,
701
+ failedKind: "missing files",
702
+ failedCount: missing.length,
703
+ nextStep: misplacedRulePacks.length > 0
704
+ ? "同名 rules 檔疑似放錯層。先不要刪除或搬移;請執行 upgrade --dry-run,再正式 upgrade 補回 dev/rules/ 內的正確檔案。"
705
+ : missing.length === rows.length
706
+ ? "這個資料夾未安裝 Kit。若這就是你的項目資料夾,請執行:npx --yes @adamchanadam/agent-handoff-kit@latest init"
707
+ : "這個資料夾只裝了一部分 Kit 檔案。請先確認路徑;如路徑正確,執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run"
708
+ });
697
709
  process.exitCode = 1;
698
710
  return "failed";
699
711
  }
@@ -1252,13 +1264,21 @@ function isAffirmativeLifecycleFieldValue(value) {
1252
1264
  return /^(yes|resolved|confirmed|complete|completed|ok|passed|all clear)\b|^(是|已|完成|已完成|已解決|已核對|已確認|通過)\b/i.test(trimmed);
1253
1265
  }
1254
1266
 
1255
- function isUnresolvedLifecycleFieldValue(value) {
1256
- return /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(value || "");
1257
- }
1258
-
1259
- function isPlaceholderLifecycleFieldValue(value) {
1260
- return !value || /\b(TBD|todo|pending|unverified|unknown|needs-review)\b|待核對|待確認|未核對|未確認/i.test(value);
1261
- }
1267
+ function isUnresolvedLifecycleFieldValue(value) {
1268
+ const trimmed = normalizeLifecycleFieldValue(value);
1269
+ return /^(no|blocked|uncertain)\b|^(否|阻擋|不確定)\b/i.test(trimmed)
1270
+ || /\b(still unresolved|not resolved)\b|仍未解決|尚未解決/i.test(trimmed);
1271
+ }
1272
+
1273
+ function isPlaceholderLifecycleFieldValue(value) {
1274
+ const trimmed = normalizeLifecycleFieldValue(value);
1275
+ return !trimmed
1276
+ || /^(TBD|todo|pending|unverified|unknown|needs-review)\b|^(待核對|待確認|未核對|未確認)\b/i.test(trimmed);
1277
+ }
1278
+
1279
+ function normalizeLifecycleFieldValue(value) {
1280
+ return (value || "").trim().replace(/^[-*]\s*/, "");
1281
+ }
1262
1282
 
1263
1283
  function hasSubstantiveHandoffState(text) {
1264
1284
  const sections = [
@@ -1290,10 +1310,10 @@ function fieldValueAfterMarker(text, fieldId) {
1290
1310
  return fallback ? fallback[1].trim() : "";
1291
1311
  }
1292
1312
 
1293
- function extractSectionText(text, markerId, headingTitle) {
1294
- const markerText = `ack:section:${markerId}`;
1295
- const markerIndex = text.indexOf(markerText);
1296
- if (markerIndex >= 0) {
1313
+ function extractSectionText(text, markerId, headingTitle) {
1314
+ const markerText = `ack:section:${markerId}`;
1315
+ const markerIndex = text.indexOf(markerText);
1316
+ if (markerIndex >= 0) {
1297
1317
  const start = text.indexOf("\n", markerIndex);
1298
1318
  if (start < 0) return "";
1299
1319
  const nextMarker = text.indexOf("<!-- ack:section:", start + 1);
@@ -1303,10 +1323,34 @@ function extractSectionText(text, markerId, headingTitle) {
1303
1323
  const headingMatch = new RegExp(`^## ${escapeRegExp(headingTitle)}\\s*$`, "m").exec(text);
1304
1324
  if (!headingMatch) return "";
1305
1325
  const start = headingMatch.index + headingMatch[0].length;
1306
- const nextHeading = /\n##\s+/.exec(text.slice(start));
1307
- return text.slice(start, nextHeading ? start + nextHeading.index : text.length);
1308
- }
1309
-
1326
+ const nextHeading = /\n##\s+/.exec(text.slice(start));
1327
+ return text.slice(start, nextHeading ? start + nextHeading.index : text.length);
1328
+ }
1329
+
1330
+ async function findMisplacedRulePacks(root, missingRows) {
1331
+ const missingTargets = new Set(missingRows.map((row) => row.target));
1332
+ const findings = [];
1333
+ for (const target of rulePackTargets) {
1334
+ if (!missingTargets.has(target)) continue;
1335
+ const fileName = path.basename(target);
1336
+ const misplacedRel = path.join("dev", fileName).replaceAll(path.sep, "/");
1337
+ if (await exists(path.join(root, misplacedRel))) {
1338
+ findings.push({ expected: target, misplaced: misplacedRel });
1339
+ }
1340
+ }
1341
+ return findings;
1342
+ }
1343
+
1344
+ function printMisplacedRulePackWarnings(findings) {
1345
+ if (findings.length === 0) return;
1346
+ console.log("");
1347
+ console.log("misplaced rule pack hints:");
1348
+ for (const finding of findings) {
1349
+ console.log(`warning ${finding.expected} missing, but ${finding.misplaced} exists`);
1350
+ }
1351
+ console.log(" 同名 rules 檔疑似放錯層;upgrade 會補回 dev/rules/ 內的正確檔案,但不會自動刪除或搬移 dev/ 根層副本。");
1352
+ }
1353
+
1310
1354
  async function checkRequiredAnchors(root) {
1311
1355
  const rows = [];
1312
1356
  for (const rule of requiredAnchors) {
@@ -1412,13 +1456,20 @@ async function buildPlan(root, command, version = null) {
1412
1456
  plan.push(classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context));
1413
1457
  continue;
1414
1458
  }
1415
- plan.push({
1416
- sourceRel,
1417
- targetRel,
1418
- sourceAbs,
1419
- targetAbs,
1420
- action: "create"
1421
- });
1459
+ const misplacedRel = targetRel.startsWith("dev/rules/")
1460
+ ? path.join("dev", path.basename(targetRel)).replaceAll(path.sep, "/")
1461
+ : null;
1462
+ const reason = misplacedRel && await exists(path.join(root, misplacedRel))
1463
+ ? `same-named rules file appears one level up at ${misplacedRel}; create correct dev/rules/ copy without deleting or moving the misplaced file`
1464
+ : undefined;
1465
+ plan.push({
1466
+ sourceRel,
1467
+ targetRel,
1468
+ sourceAbs,
1469
+ targetAbs,
1470
+ action: "create",
1471
+ ...(reason ? { reason } : {})
1472
+ });
1422
1473
  }
1423
1474
  return plan;
1424
1475
  }
@@ -1436,7 +1487,7 @@ async function readRootTemplateVersion(root) {
1436
1487
 
1437
1488
  function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context = {}) {
1438
1489
  const base = { sourceRel, targetRel, sourceAbs, targetAbs };
1439
- if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
1490
+ if (targetText === sourceText && targetRel !== "AGENTS.md") return { ...base, action: "skip", reason: "already current" };
1440
1491
  if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
1441
1492
  if (targetRel === "AGENTS.md") {
1442
1493
  const health = assessAgentsMdHealth(targetText);
package/package.json CHANGED
@@ -1,30 +1,30 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.25",
3
+ "version": "0.3.26",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "agent-handoff-kit": "bin/agent-handoff-kit.mjs"
8
8
  },
9
9
  "files": [
10
- "bin/",
11
- "runtime-core/",
12
- "packs/",
13
- "README.md",
10
+ "bin/",
11
+ "runtime-core/",
12
+ "packs/",
13
+ "README.md",
14
14
  "LICENSE"
15
15
  ],
16
16
  "scripts": {
17
17
  "doctor": "node bin/agent-handoff-kit.mjs doctor --root .",
18
18
  "dry-run": "node bin/agent-handoff-kit.mjs init --dry-run --root .",
19
19
  "qa:prototype": "node scripts/check-public-prototype.mjs",
20
- "qa:packs": "node scripts/check-pack-scenarios.mjs",
21
- "qa:upgrade": "node scripts/check-upgrade-safety.mjs",
22
- "qa:release": "node scripts/check-release-readiness.mjs",
23
- "qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
24
- "qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
20
+ "qa:packs": "node scripts/check-pack-scenarios.mjs",
21
+ "qa:upgrade": "node scripts/check-upgrade-safety.mjs",
22
+ "qa:release": "node scripts/check-release-readiness.mjs",
23
+ "qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
24
+ "qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
25
25
  },
26
26
  "engines": {
27
27
  "node": ">=18"
28
28
  },
29
29
  "license": "MIT"
30
- }
30
+ }