@adamchanadam/agent-handoff-kit 0.3.25 → 0.3.27
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 +300 -271
- package/bin/agent-handoff-kit.mjs +180 -63
- package/package.json +11 -11
- package/packs/agent-governance.md +27 -0
- package/runtime-core/RULE_PACKS.md +2 -1
package/README.md
CHANGED
|
@@ -1,292 +1,321 @@
|
|
|
1
|
-
# Agent Handoff Kit
|
|
2
|
-
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
4
|
-
|
|
5
|
-

|
|
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
|
-
| 新建檔案、參考資料變孤兒 |
|
|
39
|
-
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
|
|
40
|
-
| AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
41
|
-
|
|
42
|
-
它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
|
|
43
|
-
|
|
44
|
-
## 三步上手
|
|
45
|
-
|
|
46
|
-

|
|
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 接力,而不是立即啟動交接流程。
|
|
1
|
+
# Agent Handoff Kit
|
|
2
|
+
|
|
3
|
+
狀態:目前版本為 `v0.3.27`。這是早期可用版本,仍在持續完善中。
|
|
4
|
+
|
|
5
|
+

|
|
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
|
+
| 新建檔案、參考資料變孤兒 | 你可以叫 AI 做「治理打通」,用 `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
|
+

|
|
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 自動處理。
|
|
127
229
|
|
|
128
|
-
|
|
230
|
+
## 治理打通:讓重要文件不要變孤兒
|
|
129
231
|
|
|
130
|
-
|
|
232
|
+
長期項目常會產生新文件,例如 stock list、production guide、runbook、workflow、checklist、研究真源或操作清單。文件本身做完,不代表下一個 AI 一定知道它存在,也不代表 AI 知道何時要讀、何時要更新、是否有另一份舊版真源。
|
|
131
233
|
|
|
132
|
-
|
|
234
|
+
這時可以在 AI 對話中直接說:
|
|
133
235
|
|
|
134
236
|
```text
|
|
135
|
-
|
|
237
|
+
治理打通 docs/production-guide.md
|
|
136
238
|
```
|
|
137
239
|
|
|
138
|
-
|
|
240
|
+
英文也可以說:
|
|
139
241
|
|
|
140
242
|
```text
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
handoff
|
|
243
|
+
bridge governance for docs/production-guide.md
|
|
244
|
+
connect this document to governance
|
|
144
245
|
```
|
|
145
246
|
|
|
146
|
-
|
|
247
|
+
AI 會檢查這份文件是否已接入項目記憶:文件本身是否講清楚用途與更新時機、`dev/PROJECT_INDEX.md` 是否登記它、`dev/DOC_SYNC_REGISTRY.md` 是否記下同類變更要同步哪裡、相關 workflow 是否會提醒更新它,以及 handoff / log 是否各自放在正確角色。
|
|
147
248
|
|
|
148
|
-
|
|
249
|
+
如果你不確定整個 repo 有沒有漏接的文件,可以說:
|
|
149
250
|
|
|
150
251
|
```text
|
|
151
|
-
|
|
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
|
|
252
|
+
掃描 repo 有沒有未接合文件
|
|
253
|
+
scan for unbridged governance documents
|
|
162
254
|
```
|
|
163
255
|
|
|
164
|
-
|
|
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 自動處理。
|
|
256
|
+
這個掃描只列出候選與缺口,不會自動刪除、改名或合併文件。若發現兩份文件像是同一個真源,AI 只會列出合併、引用或退役建議,等你確認。
|
|
229
257
|
|
|
230
258
|
## 外部工具治理
|
|
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、寫說明、整理文案 | 寫作規則,通常再加溝通規則 |
|
|
259
|
+
|
|
260
|
+
如你的項目涉及外部工具(例如 Notion、Google Drive、Slack、Linear、GitHub 等),Agent Handoff Kit 提供跨對話的治理紀律,確保 AI 在不同對話之間能穩定使用這些工具。
|
|
261
|
+
|
|
262
|
+
**登記表**:`dev/PROJECT_INDEX.md` 內設有「已裝外部工具」段,記錄項目已連接哪些外部工具。AI 在新對話開工時會自動讀取,了解能直接讀寫哪些資料來源。
|
|
263
|
+
|
|
264
|
+
**機密分離原則**:API key、token、密碼等任何敏感資料**永不寫入** `dev/` 內任何檔案。這類機密由你的 AI 工具或系統安全儲存管理,與本工具完全分離。`doctor` 會自動掃描,若發現任何疑似敏感資料寫入,會立即報錯。
|
|
265
|
+
|
|
266
|
+
**已裝才用**:如你已透過 Claude Desktop 等工具連接好外部服務,AI 會直接使用對應功能讀寫資料。如未連接,AI 會改為產生需要你手動同步的內容,並提示你下一步。
|
|
267
|
+
|
|
268
|
+
**失靈不亂修**:如外部工具中途認證失效,AI 會立即說明,不會嘗試自動修復;同時將狀況記錄入交接文件,方便你或下一個對話判斷處理。
|
|
269
|
+
|
|
270
|
+
## 工作模式
|
|
271
|
+
|
|
272
|
+
你不需要記規則名稱,只要描述任務。AI 會按任務切換工作模式。
|
|
273
|
+
|
|
274
|
+
| 你的任務 | AI 應使用的工作規則 |
|
|
275
|
+
|---|---|
|
|
276
|
+
| 寫或改代碼、檢查錯誤、執行測試 | 寫代碼規則;涉及刪除、覆寫、Git、套件管理或外部服務時,再讀安全規則 |
|
|
277
|
+
| 查資料、比較來源、整理證據 | 研究規則 |
|
|
278
|
+
| 改 README、寫說明、整理文案 | 寫作規則,通常再加溝通規則 |
|
|
251
279
|
| 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
|
|
252
280
|
| 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
|
|
253
281
|
| 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
-
|
|
263
|
-
-
|
|
264
|
-
-
|
|
265
|
-
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
- **
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
-
|
|
290
|
-
-
|
|
291
|
-
-
|
|
292
|
-
-
|
|
282
|
+
| 新建重要文件後想避免變孤兒 | AI 治理規則;說「治理打通 <檔案>」,讓 AI 檢查索引、同步責任、相關流程與重複真源風險 |
|
|
283
|
+
|
|
284
|
+
原則是只讀當前任務需要的規則,不是每次讀全部文件。
|
|
285
|
+
|
|
286
|
+
## 安全護欄
|
|
287
|
+
|
|
288
|
+
就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
|
|
289
|
+
|
|
290
|
+
- 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
|
|
291
|
+
- 機密保護:`.env`、API key、token 不可印出、不可提交、不可上傳。
|
|
292
|
+
- 查證不猜:使用第三方服務或工具前先查官方文件;查不到就標示未核實。
|
|
293
|
+
- 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
|
|
294
|
+
- 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
|
|
295
|
+
|
|
296
|
+
## 版本提示
|
|
297
|
+
|
|
298
|
+
安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與版本說明連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
|
|
299
|
+
|
|
300
|
+
若你不想檢查更新,可設定環境變數:
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
## 配合 Adam-AI-Instructions 使用
|
|
307
|
+
|
|
308
|
+
Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions) 配合使用。兩者分工互補,不重疊:
|
|
309
|
+
|
|
310
|
+
- **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
|
|
311
|
+
- **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
|
|
312
|
+
|
|
313
|
+
到該倉庫的「五、提示詞索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具設定。然後再在項目資料夾執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init` 安裝本工具。兩者配合,就能同時照顧單次對話的做事規矩,以及不同對話之間的項目接力。
|
|
314
|
+
|
|
315
|
+
## 目前限制
|
|
316
|
+
|
|
317
|
+
- 目前版本為 `v0.3.27`;正式安裝請以 npm registry `latest` 顯示為準。
|
|
318
|
+
- 這是早期可用版本,仍在持續完善中。
|
|
319
|
+
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
320
|
+
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
321
|
+
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|
|
@@ -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
|
|
|
@@ -360,11 +363,11 @@ const schemaChecks = [
|
|
|
360
363
|
tableHeader("Change type", "Also check/update", "Verification")
|
|
361
364
|
]
|
|
362
365
|
},
|
|
363
|
-
{
|
|
364
|
-
target: "dev/RULE_PACKS.md",
|
|
365
|
-
label: "rule pack router coverage",
|
|
366
|
-
checks: [
|
|
367
|
-
heading("Routing Rule"),
|
|
366
|
+
{
|
|
367
|
+
target: "dev/RULE_PACKS.md",
|
|
368
|
+
label: "rule pack router coverage",
|
|
369
|
+
checks: [
|
|
370
|
+
heading("Routing Rule"),
|
|
368
371
|
includes("Load the minimum set"),
|
|
369
372
|
includes("cannot weaken core safety"),
|
|
370
373
|
includes("dev/rules/safety.md"),
|
|
@@ -376,10 +379,27 @@ const schemaChecks = [
|
|
|
376
379
|
// stale routing table that does not route onboarding signals.
|
|
377
380
|
includes("First-time user signals"),
|
|
378
381
|
includes("dev/rules/onboarding.md"),
|
|
379
|
-
// R-030 v0.3.0+: routing table must include integrations pack row.
|
|
380
|
-
includes("dev/rules/integrations.md")
|
|
381
|
-
|
|
382
|
-
|
|
382
|
+
// R-030 v0.3.0+: routing table must include integrations pack row.
|
|
383
|
+
includes("dev/rules/integrations.md"),
|
|
384
|
+
includes("Governance bridge / 治理打通"),
|
|
385
|
+
includes("scan for unbridged governance documents")
|
|
386
|
+
]
|
|
387
|
+
},
|
|
388
|
+
{
|
|
389
|
+
target: "dev/rules/agent-governance.md",
|
|
390
|
+
label: "agent governance pack structure",
|
|
391
|
+
checks: [
|
|
392
|
+
heading("Scope"),
|
|
393
|
+
heading("Load When"),
|
|
394
|
+
heading("Rules"),
|
|
395
|
+
heading("Governance Bridge Workflow"),
|
|
396
|
+
heading("Checks"),
|
|
397
|
+
heading("Closeout"),
|
|
398
|
+
includes("Governance bridge is a triggered review"),
|
|
399
|
+
includes("Status: bridged / partially bridged / unbridged / blocked"),
|
|
400
|
+
includes("duplicate source-of-truth risk")
|
|
401
|
+
]
|
|
402
|
+
},
|
|
383
403
|
{
|
|
384
404
|
target: "dev/PROJECT_DECISIONS.md",
|
|
385
405
|
label: "project decisions log structure",
|
|
@@ -555,11 +575,16 @@ async function runInstall(command, root, options, version) {
|
|
|
555
575
|
const migrationDir = path.join(root, "dev/governance_migrations", stamp);
|
|
556
576
|
const backupDir = path.join(migrationDir, "backup");
|
|
557
577
|
|
|
558
|
-
for (const item of plan) {
|
|
559
|
-
if (item.action !== "create") continue;
|
|
560
|
-
await mkdir(path.dirname(item.targetAbs), { recursive: true });
|
|
561
|
-
|
|
562
|
-
|
|
578
|
+
for (const item of plan) {
|
|
579
|
+
if (item.action !== "create") continue;
|
|
580
|
+
await mkdir(path.dirname(item.targetAbs), { recursive: true });
|
|
581
|
+
if (item.targetRel === "AGENTS.md") {
|
|
582
|
+
const sourceText = await readFile(item.sourceAbs, "utf8");
|
|
583
|
+
await writeFile(item.targetAbs, mergeManagedBlock("", sourceText), "utf8");
|
|
584
|
+
} else {
|
|
585
|
+
await copyFile(item.sourceAbs, item.targetAbs);
|
|
586
|
+
}
|
|
587
|
+
created.push(item.targetRel);
|
|
563
588
|
}
|
|
564
589
|
|
|
565
590
|
await hydrateInitialOpeningPrompt(root, created);
|
|
@@ -683,17 +708,21 @@ async function runDoctor(root, version, options = {}) {
|
|
|
683
708
|
console.log(`required files: ${rows.length}`);
|
|
684
709
|
for (const row of rows) {
|
|
685
710
|
console.log(`${row.ok ? "ok" : "missing"} ${row.target}`);
|
|
686
|
-
}
|
|
687
|
-
|
|
688
|
-
if (missing.length > 0) {
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
711
|
+
}
|
|
712
|
+
|
|
713
|
+
if (missing.length > 0) {
|
|
714
|
+
const misplacedRulePacks = await findMisplacedRulePacks(root, missing);
|
|
715
|
+
printMisplacedRulePackWarnings(misplacedRulePacks);
|
|
716
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
717
|
+
checked: rows.length,
|
|
718
|
+
failedKind: "missing files",
|
|
719
|
+
failedCount: missing.length,
|
|
720
|
+
nextStep: misplacedRulePacks.length > 0
|
|
721
|
+
? "同名 rules 檔疑似放錯層。先不要刪除或搬移;請執行 upgrade --dry-run,再正式 upgrade 補回 dev/rules/ 內的正確檔案。"
|
|
722
|
+
: missing.length === rows.length
|
|
723
|
+
? "這個資料夾未安裝 Kit。若這就是你的項目資料夾,請執行:npx --yes @adamchanadam/agent-handoff-kit@latest init"
|
|
724
|
+
: "這個資料夾只裝了一部分 Kit 檔案。請先確認路徑;如路徑正確,執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run"
|
|
725
|
+
});
|
|
697
726
|
process.exitCode = 1;
|
|
698
727
|
return "failed";
|
|
699
728
|
}
|
|
@@ -1252,13 +1281,21 @@ function isAffirmativeLifecycleFieldValue(value) {
|
|
|
1252
1281
|
return /^(yes|resolved|confirmed|complete|completed|ok|passed|all clear)\b|^(是|已|完成|已完成|已解決|已核對|已確認|通過)\b/i.test(trimmed);
|
|
1253
1282
|
}
|
|
1254
1283
|
|
|
1255
|
-
function isUnresolvedLifecycleFieldValue(value) {
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1284
|
+
function isUnresolvedLifecycleFieldValue(value) {
|
|
1285
|
+
const trimmed = normalizeLifecycleFieldValue(value);
|
|
1286
|
+
return /^(no|blocked|uncertain)\b|^(否|阻擋|不確定)\b/i.test(trimmed)
|
|
1287
|
+
|| /\b(still unresolved|not resolved)\b|仍未解決|尚未解決/i.test(trimmed);
|
|
1288
|
+
}
|
|
1289
|
+
|
|
1290
|
+
function isPlaceholderLifecycleFieldValue(value) {
|
|
1291
|
+
const trimmed = normalizeLifecycleFieldValue(value);
|
|
1292
|
+
return !trimmed
|
|
1293
|
+
|| /^(TBD|todo|pending|unverified|unknown|needs-review)\b|^(待核對|待確認|未核對|未確認)\b/i.test(trimmed);
|
|
1294
|
+
}
|
|
1295
|
+
|
|
1296
|
+
function normalizeLifecycleFieldValue(value) {
|
|
1297
|
+
return (value || "").trim().replace(/^[-*]\s*/, "");
|
|
1298
|
+
}
|
|
1262
1299
|
|
|
1263
1300
|
function hasSubstantiveHandoffState(text) {
|
|
1264
1301
|
const sections = [
|
|
@@ -1290,10 +1327,10 @@ function fieldValueAfterMarker(text, fieldId) {
|
|
|
1290
1327
|
return fallback ? fallback[1].trim() : "";
|
|
1291
1328
|
}
|
|
1292
1329
|
|
|
1293
|
-
function extractSectionText(text, markerId, headingTitle) {
|
|
1294
|
-
const markerText = `ack:section:${markerId}`;
|
|
1295
|
-
const markerIndex = text.indexOf(markerText);
|
|
1296
|
-
if (markerIndex >= 0) {
|
|
1330
|
+
function extractSectionText(text, markerId, headingTitle) {
|
|
1331
|
+
const markerText = `ack:section:${markerId}`;
|
|
1332
|
+
const markerIndex = text.indexOf(markerText);
|
|
1333
|
+
if (markerIndex >= 0) {
|
|
1297
1334
|
const start = text.indexOf("\n", markerIndex);
|
|
1298
1335
|
if (start < 0) return "";
|
|
1299
1336
|
const nextMarker = text.indexOf("<!-- ack:section:", start + 1);
|
|
@@ -1303,10 +1340,34 @@ function extractSectionText(text, markerId, headingTitle) {
|
|
|
1303
1340
|
const headingMatch = new RegExp(`^## ${escapeRegExp(headingTitle)}\\s*$`, "m").exec(text);
|
|
1304
1341
|
if (!headingMatch) return "";
|
|
1305
1342
|
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
|
-
|
|
1343
|
+
const nextHeading = /\n##\s+/.exec(text.slice(start));
|
|
1344
|
+
return text.slice(start, nextHeading ? start + nextHeading.index : text.length);
|
|
1345
|
+
}
|
|
1346
|
+
|
|
1347
|
+
async function findMisplacedRulePacks(root, missingRows) {
|
|
1348
|
+
const missingTargets = new Set(missingRows.map((row) => row.target));
|
|
1349
|
+
const findings = [];
|
|
1350
|
+
for (const target of rulePackTargets) {
|
|
1351
|
+
if (!missingTargets.has(target)) continue;
|
|
1352
|
+
const fileName = path.basename(target);
|
|
1353
|
+
const misplacedRel = path.join("dev", fileName).replaceAll(path.sep, "/");
|
|
1354
|
+
if (await exists(path.join(root, misplacedRel))) {
|
|
1355
|
+
findings.push({ expected: target, misplaced: misplacedRel });
|
|
1356
|
+
}
|
|
1357
|
+
}
|
|
1358
|
+
return findings;
|
|
1359
|
+
}
|
|
1360
|
+
|
|
1361
|
+
function printMisplacedRulePackWarnings(findings) {
|
|
1362
|
+
if (findings.length === 0) return;
|
|
1363
|
+
console.log("");
|
|
1364
|
+
console.log("misplaced rule pack hints:");
|
|
1365
|
+
for (const finding of findings) {
|
|
1366
|
+
console.log(`warning ${finding.expected} missing, but ${finding.misplaced} exists`);
|
|
1367
|
+
}
|
|
1368
|
+
console.log(" 同名 rules 檔疑似放錯層;upgrade 會補回 dev/rules/ 內的正確檔案,但不會自動刪除或搬移 dev/ 根層副本。");
|
|
1369
|
+
}
|
|
1370
|
+
|
|
1310
1371
|
async function checkRequiredAnchors(root) {
|
|
1311
1372
|
const rows = [];
|
|
1312
1373
|
for (const rule of requiredAnchors) {
|
|
@@ -1412,13 +1473,20 @@ async function buildPlan(root, command, version = null) {
|
|
|
1412
1473
|
plan.push(classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context));
|
|
1413
1474
|
continue;
|
|
1414
1475
|
}
|
|
1415
|
-
|
|
1416
|
-
|
|
1417
|
-
|
|
1418
|
-
|
|
1419
|
-
|
|
1420
|
-
|
|
1421
|
-
|
|
1476
|
+
const misplacedRel = targetRel.startsWith("dev/rules/")
|
|
1477
|
+
? path.join("dev", path.basename(targetRel)).replaceAll(path.sep, "/")
|
|
1478
|
+
: null;
|
|
1479
|
+
const reason = misplacedRel && await exists(path.join(root, misplacedRel))
|
|
1480
|
+
? `same-named rules file appears one level up at ${misplacedRel}; create correct dev/rules/ copy without deleting or moving the misplaced file`
|
|
1481
|
+
: undefined;
|
|
1482
|
+
plan.push({
|
|
1483
|
+
sourceRel,
|
|
1484
|
+
targetRel,
|
|
1485
|
+
sourceAbs,
|
|
1486
|
+
targetAbs,
|
|
1487
|
+
action: "create",
|
|
1488
|
+
...(reason ? { reason } : {})
|
|
1489
|
+
});
|
|
1422
1490
|
}
|
|
1423
1491
|
return plan;
|
|
1424
1492
|
}
|
|
@@ -1436,7 +1504,7 @@ async function readRootTemplateVersion(root) {
|
|
|
1436
1504
|
|
|
1437
1505
|
function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context = {}) {
|
|
1438
1506
|
const base = { sourceRel, targetRel, sourceAbs, targetAbs };
|
|
1439
|
-
if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
|
|
1507
|
+
if (targetText === sourceText && targetRel !== "AGENTS.md") return { ...base, action: "skip", reason: "already current" };
|
|
1440
1508
|
if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
|
|
1441
1509
|
if (targetRel === "AGENTS.md") {
|
|
1442
1510
|
const health = assessAgentsMdHealth(targetText);
|
|
@@ -1494,18 +1562,46 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1494
1562
|
};
|
|
1495
1563
|
}
|
|
1496
1564
|
// R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
|
|
1497
|
-
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
|
|
1498
|
-
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1499
|
-
if (!mergedRulePacks) {
|
|
1500
|
-
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1565
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
|
|
1566
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1567
|
+
if (!mergedRulePacks) {
|
|
1568
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1501
1569
|
}
|
|
1502
1570
|
return {
|
|
1503
1571
|
...base,
|
|
1504
1572
|
action: "merge",
|
|
1505
1573
|
reason: "merge missing v0.3.0+ routing rows while preserving existing custom rows (Integration governance routing)",
|
|
1506
|
-
mergedText: mergedRulePacks
|
|
1507
|
-
};
|
|
1508
|
-
}
|
|
1574
|
+
mergedText: mergedRulePacks
|
|
1575
|
+
};
|
|
1576
|
+
}
|
|
1577
|
+
// Governance bridge v0.3.27+: route durable document bridging requests to
|
|
1578
|
+
// agent-governance without replacing user-added routing rows.
|
|
1579
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("Governance bridge / 治理打通")) {
|
|
1580
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1581
|
+
if (!mergedRulePacks) {
|
|
1582
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1583
|
+
}
|
|
1584
|
+
return {
|
|
1585
|
+
...base,
|
|
1586
|
+
action: "merge",
|
|
1587
|
+
reason: "merge missing governance bridge routing row while preserving existing custom rows",
|
|
1588
|
+
mergedText: mergedRulePacks
|
|
1589
|
+
};
|
|
1590
|
+
}
|
|
1591
|
+
// Governance bridge v0.3.27+: add the triggered review workflow to the
|
|
1592
|
+
// agent-governance pack only when the pack still has a trusted Checks section.
|
|
1593
|
+
if (targetRel === "dev/rules/agent-governance.md" && command === "upgrade" && !targetText.includes("## Governance Bridge Workflow")) {
|
|
1594
|
+
const mergedGovernancePack = mergeAgentGovernanceBridgeWorkflow(targetText, sourceText);
|
|
1595
|
+
if (!mergedGovernancePack) {
|
|
1596
|
+
return { ...base, action: "conflict", reason: "agent-governance pack structure was changed; manual merge required to add governance bridge workflow" };
|
|
1597
|
+
}
|
|
1598
|
+
return {
|
|
1599
|
+
...base,
|
|
1600
|
+
action: "merge",
|
|
1601
|
+
reason: "insert governance bridge workflow into agent-governance pack without replacing local additions",
|
|
1602
|
+
mergedText: mergedGovernancePack
|
|
1603
|
+
};
|
|
1604
|
+
}
|
|
1509
1605
|
// R-030 v0.3.0+: dev/PROJECT_INDEX.md gets ## Installed Integrations section auto-inserted before
|
|
1510
1606
|
// ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
|
|
1511
1607
|
// is fully preserved (including any user-filled rows). User can later manually add the `via` column
|
|
@@ -1678,7 +1774,7 @@ function isUpgradeFromOlderTemplate(context) {
|
|
|
1678
1774
|
&& compareSemver(rootTemplateVersion, currentVersion) < 0;
|
|
1679
1775
|
}
|
|
1680
1776
|
|
|
1681
|
-
function looksLikeExpandedKitBridge(targetRel, text) {
|
|
1777
|
+
function looksLikeExpandedKitBridge(targetRel, text) {
|
|
1682
1778
|
if (text.includes("This file is a bridge only")) return false;
|
|
1683
1779
|
if (targetRel === "CLAUDE.md") {
|
|
1684
1780
|
return (text.includes("This file provides guidance to Claude Code") && text.includes("## Session Startup"))
|
|
@@ -1707,6 +1803,25 @@ function mergeOnboardingScenarioALabel(targetText) {
|
|
|
1707
1803
|
return merged;
|
|
1708
1804
|
}
|
|
1709
1805
|
|
|
1806
|
+
function mergeAgentGovernanceBridgeWorkflow(targetText, sourceText) {
|
|
1807
|
+
const sourceMatch = sourceText.match(/9\. Governance bridge[\s\S]*?(?=\n## Checks)/);
|
|
1808
|
+
const workflowMatch = sourceText.match(/\n## Governance Bridge Workflow[\s\S]*?(?=\n## Checks)/);
|
|
1809
|
+
if (!sourceMatch || !workflowMatch || !targetText.includes("\n## Checks")) return null;
|
|
1810
|
+
|
|
1811
|
+
let merged = targetText;
|
|
1812
|
+
if (!merged.includes("Governance bridge is a triggered review")) {
|
|
1813
|
+
const rulePrefix = sourceMatch[0].trimEnd();
|
|
1814
|
+
merged = merged.replace(/\n## Checks/, `\n${rulePrefix}\n${workflowMatch[0]}\n## Checks`);
|
|
1815
|
+
}
|
|
1816
|
+
if (!merged.includes("For governance bridge work, confirm the target file")) {
|
|
1817
|
+
merged = merged.replace(
|
|
1818
|
+
"- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.",
|
|
1819
|
+
"- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.\n- For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable."
|
|
1820
|
+
);
|
|
1821
|
+
}
|
|
1822
|
+
return merged;
|
|
1823
|
+
}
|
|
1824
|
+
|
|
1710
1825
|
function hasTrustedOnboardingScenarioLibrary(text) {
|
|
1711
1826
|
const bounds = textSectionBounds(text, "## Application Scenario Library", "## Cross-reference to guide.html");
|
|
1712
1827
|
if (!bounds) return false;
|
|
@@ -2320,8 +2435,9 @@ function mergeHandoffArchiveContinuityRule(targetText, sourceText) {
|
|
|
2320
2435
|
function mergeRulePacksRows(targetText, sourceText) {
|
|
2321
2436
|
const requiredPacks = [
|
|
2322
2437
|
"dev/rules/onboarding.md",
|
|
2323
|
-
"dev/rules/integrations.md"
|
|
2324
|
-
|
|
2438
|
+
"dev/rules/integrations.md",
|
|
2439
|
+
"dev/rules/agent-governance.md"
|
|
2440
|
+
];
|
|
2325
2441
|
const sourceRows = sourceText
|
|
2326
2442
|
.split(/\r?\n/)
|
|
2327
2443
|
.filter((line) => line.startsWith("|") && requiredPacks.some((pack) => line.includes(pack)));
|
|
@@ -2338,10 +2454,11 @@ function mergeRulePacksRows(targetText, sourceText) {
|
|
|
2338
2454
|
const table = lines.slice(tableStart, tableEnd);
|
|
2339
2455
|
const after = lines.slice(tableEnd);
|
|
2340
2456
|
const sourceRowsToApply = sourceRows.filter((row) => {
|
|
2341
|
-
if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
|
|
2342
|
-
if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
|
|
2343
|
-
return
|
|
2344
|
-
|
|
2457
|
+
if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
|
|
2458
|
+
if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
|
|
2459
|
+
if (row.includes("Governance bridge / 治理打通")) return !targetText.includes("Governance bridge / 治理打通");
|
|
2460
|
+
return false;
|
|
2461
|
+
});
|
|
2345
2462
|
if (sourceRowsToApply.length === 0) return targetText;
|
|
2346
2463
|
|
|
2347
2464
|
const merged = [
|
package/package.json
CHANGED
|
@@ -1,30 +1,30 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.27",
|
|
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
|
+
}
|
|
@@ -8,6 +8,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
8
8
|
|
|
9
9
|
- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
|
|
10
10
|
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
|
+
- User asks to "治理打通", "bridge governance", "connect this document to governance", or scan for unbridged governance documents.
|
|
11
12
|
|
|
12
13
|
## Rules
|
|
13
14
|
|
|
@@ -19,6 +20,31 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
19
20
|
6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
|
|
20
21
|
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 the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
|
|
21
22
|
8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
|
|
23
|
+
9. Governance bridge is a triggered review, not a default startup scan. Use it when an important file, source-of-truth document, runbook, production guide, workflow, checklist, stock list, or similar durable document may need to be connected to project governance.
|
|
24
|
+
|
|
25
|
+
## Governance Bridge Workflow
|
|
26
|
+
|
|
27
|
+
Use this workflow when the user asks for governance bridge / 治理打通 / connect this document to governance, or asks to scan for unbridged governance documents.
|
|
28
|
+
|
|
29
|
+
1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.
|
|
30
|
+
2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.
|
|
31
|
+
3. Check `dev/PROJECT_INDEX.md`: the file should be discoverable with its role and "read when" condition. Source-of-truth or reference files should appear in Fact Base, External Sources, Directory Map, Entry Points, or another existing indexed home that fits the project.
|
|
32
|
+
4. Check `dev/DOC_SYNC_REGISTRY.md`: future same-type changes should have a matching change type or an explicit reason no durable sync rule is needed.
|
|
33
|
+
5. Check related workflows, guides, runbooks, or rule packs: if a process creates or updates the file, that process should say when to update the file or its index row.
|
|
34
|
+
6. Check `dev/SESSION_HANDOFF.md`: only current state, next action, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
|
|
35
|
+
7. Check `dev/SESSION_LOG.md`: this session's bridge review, validation, and evidence can be logged when it affects future action, but log entries must not become current state.
|
|
36
|
+
8. Search for duplicate source-of-truth risk. If another file has the same durable role, recommend merge, reference, or retire options; do not delete, rename, or move files without explicit approval.
|
|
37
|
+
|
|
38
|
+
For repo-wide scans, report candidates as candidates. Do not fail ordinary docs merely because they are not indexed; only durable files that future agents need to discover, update, or distinguish from drafts should be bridged.
|
|
39
|
+
|
|
40
|
+
Output format:
|
|
41
|
+
|
|
42
|
+
- Status: bridged / partially bridged / unbridged / blocked.
|
|
43
|
+
- Already bridged: list the governance links that are present.
|
|
44
|
+
- Gaps: list missing links and why they matter for the next agent.
|
|
45
|
+
- Suggested patches: list exact files and sections to update.
|
|
46
|
+
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
47
|
+
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
22
48
|
|
|
23
49
|
## Checks
|
|
24
50
|
|
|
@@ -27,6 +53,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
27
53
|
- Confirm old overlapping wording was retired or marked legacy.
|
|
28
54
|
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
29
55
|
- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
|
|
56
|
+
- For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.
|
|
30
57
|
- Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
|
|
31
58
|
- For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
|
|
32
59
|
|
|
@@ -9,7 +9,8 @@ Read only the packs needed for the current task.
|
|
|
9
9
|
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
10
10
|
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
11
11
|
| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
|
|
12
|
-
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
12
|
+
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
13
|
+
| Governance bridge / 治理打通 / bridge governance / connect this document to governance / scan for unbridged governance documents | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
13
14
|
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
14
15
|
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
15
16
|
| External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Google Drive / Slack / Linear / Dropbox / HubSpot / GitHub / etc. external read-write | `dev/rules/integrations.md` | Connector-first default + credential separation + multi-layer source-of-truth + cross-session resilience |
|