@adamchanadam/agent-handoff-kit 0.1.3 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +70 -111
- package/bin/agent-handoff-kit.mjs +102 -7
- package/package.json +1 -1
- package/packs/agent-governance.md +2 -0
- package/runtime-core/AGENTS.core.md +5 -0
- package/runtime-core/PROJECT_INDEX.md +3 -2
- package/runtime-core/SESSION_HANDOFF.md +2 -0
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +14 -0
package/README.md
CHANGED
|
@@ -1,34 +1,31 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:`v0.1.
|
|
3
|
+
狀態:`v0.1.4` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
|
|
4
4
|
|
|
5
|
-
Agent Handoff Kit
|
|
5
|
+

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