@adamchanadam/agent-handoff-kit 0.1.0 → 0.1.2

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,176 +1,235 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:`v0.1.0` 已正式發佈。這是早期可用版本,仍未達 requirements-complete。
3
+ 狀態:`v0.1.2` 已正式發佈。這是早期可用版本,尚未宣稱所有需求已完成。
4
4
 
5
- Agent Handoff Kit 是一套輕量 AI 專案延續工具。它幫助 AI 在多個 session 之間保留專案狀態、交接訊息、檔案地圖與工作邊界,避免下一次開工時重新猜測背景。
5
+ Agent Handoff Kit 是一套給 AI 專案使用的交接工具。它會在你的專案中放入一組固定文件,讓 AI 在下一次工作時知道:目前做到哪裡、哪些資料要先讀、哪些檔案不可亂動、收工時要留下甚麼。
6
+
7
+ 它不是聊天機器人,也不是另一個開發框架。它的作用比較像一本固定放在專案內的交接簿,讓不同 AI 工具和不同工作階段都能接上同一條線。
6
8
 
7
9
  ## 它解決甚麼問題
8
10
 
9
- Agent Handoff Kit 讓 AI 有一套固定、可重複的專案記憶流程:
11
+ AI 很容易在新工作階段失去前文。它可能不知道上次改了甚麼、哪些文件才是最新、哪些資料只是參考、哪些操作需要先問你。
12
+
13
+ Agent Handoff Kit 把這些事情寫進專案文件:開工先讀哪裡、任務前要確認哪些必讀資料、收工要留下哪些交接內容、下次要貼哪段文字重新開始。
14
+
15
+ ## 適合誰使用
16
+
17
+ 適合以下情況:
18
+
19
+ - 你會隔幾天才回到同一個 AI 專案。
20
+ - 你會在 Codex、Claude Code、Gemini CLI 等工具之間切換。
21
+ - 你希望 AI 每次開始前先讀專案狀態,而不是重新猜背景。
22
+ - 你希望收工時留下下一次可直接貼上的開工文字。
23
+ - 你不是開發人員,但想讓 AI 在長期專案中穩定接力。
10
24
 
11
- - 開工時,AI 讀同一組入口檔,不靠聊天記憶猜測現況。
12
- - 工作時,AI 只載入當前任務需要的規則包,例如 coding、writing、research、knowledge sync、release 或 safety。
13
- - 複雜任務開始前,AI 先確認本次必讀事實來源;找得到資料不等於已讀入,未讀來源不能當成沒有資料。
14
- - 收工時,AI 不是只追加紀錄;它要對賬 handoff 內的當前狀態,確認沒有過時快照,再輸出下一次 session 可直接貼上的 opening message。
15
- - 下一次 session 即使換了 AI,也能從專案檔案接續,而不是依賴上一段對話。
25
+ 不適合以下情況:
16
26
 
17
- 適合用於長期專案、跨 session AI 協作、需要穩定交接的 coding / writing / research / knowledge 管理工作。
27
+ - 只問一次性問題,不需要保存專案狀態。
28
+ - 不想在專案內新增任何交接文件。
29
+ - 需要已完全成熟的穩定版安裝工具。
18
30
 
19
31
  ## 安裝
20
32
 
21
- 目前正式公開版本為 `0.1.0`。npm package 名稱是 `@adamchanadam/agent-handoff-kit`,安裝後提供的 CLI 指令仍是 `agent-handoff-kit`。新專案可使用:
33
+ 在你的專案資料夾打開 Terminal,執行:
22
34
 
23
35
  ```bash
24
36
  npx @adamchanadam/agent-handoff-kit init
25
37
  ```
26
38
 
27
- 既有專案升級會使用:
39
+ 出現確認問題時,輸入:
28
40
 
29
- ```bash
30
- npx @adamchanadam/agent-handoff-kit upgrade
41
+ ```text
42
+ y
31
43
  ```
32
44
 
33
- 健康檢查:
45
+ 若工具列出即將建立的文件,並詢問是否寫入,請輸入:
34
46
 
35
- ```bash
36
- npx @adamchanadam/agent-handoff-kit doctor
47
+ ```text
48
+ yes
37
49
  ```
38
50
 
39
- 如要從原始碼倉庫本機測試,可使用:
51
+ 安裝完成後,你會看到一個「下一步」區塊。請特別留意:那一段不是給 Terminal 的指令,而是給 AI 對話使用的文字。
40
52
 
41
- ```bash
42
- node bin/agent-handoff-kit.mjs init --yes --root <your-project>
43
- node bin/agent-handoff-kit.mjs doctor --root <your-project>
53
+ ## 安裝後第一步
54
+
55
+ 安裝完成後,不要在 Terminal 輸入 `Follow AGENTS.md`。
56
+
57
+ 正確做法是:
58
+
59
+ 1. 打開你要使用的 AI 工具。
60
+ 2. 新增一段對話。
61
+ 3. 貼上安裝工具顯示的 `Work in ...` 文字。
62
+ 4. 要求 AI 先讀 `AGENTS.md`,並在改檔前說明它讀到的目前狀態。
63
+ 5. 然後直接描述你要完成的任務。
64
+
65
+ 你可以貼上類似以下文字:
66
+
67
+ ```text
68
+ Work in <你的專案資料夾>.
69
+ Read AGENTS.md first. Tell me what you understand before changing files.
44
70
  ```
45
71
 
46
- 既有專案請先預演:
72
+ 接著再寫你的任務,例如:
73
+
74
+ ```text
75
+ 整理這個專案,先告訴我目前狀態、下一步、風險,暫時不要改檔。
76
+ ```
77
+
78
+ 或:
79
+
80
+ ```text
81
+ 更新 README,完成後檢查交接文件是否仍然準確。
82
+ ```
83
+
84
+ ## 檢查是否安裝完整
85
+
86
+ 如要檢查安裝是否完整,可在 Terminal 執行:
47
87
 
48
88
  ```bash
49
- node bin/agent-handoff-kit.mjs upgrade --dry-run --root <your-project>
50
- node bin/agent-handoff-kit.mjs upgrade --yes --root <your-project>
89
+ npx @adamchanadam/agent-handoff-kit doctor
51
90
  ```
52
91
 
53
- installer 預設保留既有檔案;不能安全合併時會報 conflict,不會靜默覆寫。
92
+ 看到 `status: passed`,代表必要文件與基本結構存在。
93
+
94
+ 這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
54
95
 
55
96
  ## 會安裝甚麼
56
97
 
57
- installer 會在你的專案中建立:
98
+ 安裝工具會在你的專案中建立以下文件:
58
99
 
59
- - `AGENTS.md`:主要 AI 入口。
60
- - `CLAUDE.md`、`GEMINI.md`:給 Claude Code 與 Gemini CLI 的薄橋接入口。
61
- - `dev/SESSION_HANDOFF.md`:保存耐久錨點、每次收尾必對賬的當前狀態、任務理解摘要、下一步、風險、驗收與工作區身份。
62
- - `dev/SESSION_LOG.md`:保存近期實際發生過的工作證據。
63
- - `dev/PROJECT_INDEX.md`:記錄專案檔案、必讀事實來源、外部來源、指令、入口與變更熱點。
64
- - `dev/DOC_SYNC_REGISTRY.md`:記錄文件或外部索引需要同步的情況。
65
- - `dev/RULE_PACKS.md`:告訴 AI 不同任務應載入哪些規則包。
66
- - `dev/rules/*.md`:按需載入的工作模式規則包。
100
+ ```text
101
+ AGENTS.md
102
+ CLAUDE.md
103
+ GEMINI.md
104
+ dev/SESSION_HANDOFF.md
105
+ dev/SESSION_LOG.md
106
+ dev/PROJECT_INDEX.md
107
+ dev/DOC_SYNC_REGISTRY.md
108
+ dev/RULE_PACKS.md
109
+ dev/rules/*.md
110
+ ```
67
111
 
68
- 你不需要每次自己讀完所有檔案。AI 應讀啟動檔,判斷任務,載入需要的規則包,並告訴你目前使用甚麼工作模式。
112
+ 每個文件的用途如下:
69
113
 
70
- ## 日常使用
114
+ | 文件 | 用途 |
115
+ |---|---|
116
+ | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
117
+ | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
118
+ | `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
119
+ | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
120
+ | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。 |
121
+ | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
122
+ | `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
123
+ | `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
124
+ | `dev/rules/*.md` | 按任務載入的細分工作規則。 |
71
125
 
72
- 開新 session 時,貼上 `dev/SESSION_HANDOFF.md` 內的 opening message。也可以對 AI 說:
126
+ 你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
127
+
128
+ ## 日常使用方式
129
+
130
+ 每次開始新的 AI 工作階段時,建議先貼上上一輪收工產生的開工文字。若沒有那段文字,可以貼:
73
131
 
74
132
  ```text
75
- Work in <your-project>.
133
+ Work in <你的專案資料夾>.
76
134
  Read AGENTS.md, dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md, dev/PROJECT_INDEX.md, and dev/RULE_PACKS.md.
135
+ Tell me the current objective, pending work, risks, and your recommended next action before changing files.
77
136
  ```
78
137
 
79
- 然後直接描述任務:
138
+ 然後直接描述任務。
139
+
140
+ 對簡單任務,可以這樣寫:
80
141
 
81
142
  ```text
82
- 更新 README,並確認 handoff 仍然準確。
143
+ 幫我檢查 README 是否清楚,先只提出問題,不要改檔。
83
144
  ```
84
145
 
85
- AI 應該:
146
+ 對需要改檔的任務,可以這樣寫:
86
147
 
87
- 1. 確認目前目標與工作區。
88
- 2. 說明本次會使用哪些規則包。
89
- 3. 對非簡單任務,先列出本次必讀事實來源,讀取或標記 blocked。
90
- 4. 完成任務並執行必要檢查。
91
- 5. 收工時對賬 handoff 的當前狀態,更新 handoff / log。
148
+ ```text
149
+ 請更新 README 的安裝後說明,完成後執行必要檢查,並告訴我改了甚麼。
150
+ ```
92
151
 
93
- 要結束 session,只需輸入:
152
+ 對需要收工的情況,只需輸入:
94
153
 
95
154
  ```text
96
155
  收工
97
156
  ```
98
157
 
99
- 或:
158
+ 也可以輸入:
100
159
 
101
160
  ```text
102
161
  wrap up
103
162
  handoff
104
163
  ```
105
164
 
106
- AI 會更新交接檔,並輸出下一次 session 可直接貼上的 fenced `text` code block。
165
+ AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。那段文字會放在 fenced `text` code block 內,方便完整複製。
107
166
 
108
- ## 工作模式與規則包
167
+ ## 工作規則怎樣運作
109
168
 
110
- 規則包是 AI 的工作模式守則,不是要求用戶閱讀的額外說明書。
169
+ Agent Handoff Kit 會把任務分成不同工作模式。例如:
111
170
 
112
- | 你的任務 | 預期使用的 packs |
171
+ | 你的任務 | AI 應使用的工作規則 |
113
172
  |---|---|
114
- | 修 code、跑 tests、處理 build | `coding`;涉及檔案、Git、package manager、API、deploy 風險時加 `safety` |
115
- | 寫作、改 README、整理文案 | `writing`,通常再加 `communication` |
116
- | 查證資料、比較來源 | `research` |
117
- | 整理 Notion、Drive、知識庫 | `knowledge` |
118
- | 準備 release note | `release`;真正 tag、publish、upload、deploy 前加 `safety` |
173
+ | 修改程式、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
174
+ | 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
175
+ | 查證資料、比較來源、整理證據 | `research` |
176
+ | 整理 Notion、Google Drive 或知識庫 | `knowledge` |
177
+ | 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
119
178
 
120
- 原則是載入最少必要 packs,不是每次讀全部規則。
179
+ 原則是只讀當前任務需要的規則,不是每次讀全部文件。
121
180
 
122
- ## 原始碼 repo 驗收
181
+ ## 既有專案升級
123
182
 
124
- 本倉庫有原始碼專用驗收;這些指令用來驗證 prototype,不會安裝到使用者專案:
183
+ 若你的專案已經有 `AGENTS.md` 或其他 AI 記憶文件,請先預演,不要直接覆寫:
125
184
 
126
185
  ```bash
127
- npm run qa:prototype
128
- npm run qa:packs
129
- npm run qa:upgrade
130
- npm run qa:release
186
+ npx @adamchanadam/agent-handoff-kit upgrade --dry-run
131
187
  ```
132
188
 
133
- 這些檢查涵蓋安裝、`doctor`、套件預演、過時字串、公開輸出污染標記、規則包路由、升級安全、發佈前準備度,以及從安裝到收工再到接力開工的用戶流程模擬。
189
+ 確認計劃後再執行:
190
+
191
+ ```bash
192
+ npx @adamchanadam/agent-handoff-kit upgrade
193
+ ```
134
194
 
135
- ## 安裝後形態
195
+ 升級工具會保留既有檔案。能安全合併時才合併;不能安全合併時會報 conflict,不會靜默覆寫。
136
196
 
137
- 安裝後的核心結構如下:
197
+ ## 語言使用
138
198
 
139
- ```text
140
- AGENTS.md
141
- CLAUDE.md
142
- GEMINI.md
143
- dev/SESSION_HANDOFF.md
144
- dev/SESSION_LOG.md
145
- dev/PROJECT_INDEX.md
146
- dev/DOC_SYNC_REGISTRY.md
147
- dev/RULE_PACKS.md
148
- dev/rules/*.md
149
- ```
199
+ 安裝後的核心指令文件預設使用英文,原因是不同 AI 工具對英文結構較穩定。這不是限制你的專案必須用英文。
150
200
 
151
- `AGENTS.md` 是主要入口。`CLAUDE.md` 與 `GEMINI.md` 只做橋接,導向同一套啟動流程,不複製完整規則。
201
+ 你的交接筆記、任務說明和文件內容可以使用中文或其他語言。需要機器檢查的結構,會由模板內的 `ack:section:*` 與 `ack:field:*` 標記承擔。
152
202
 
153
- ## 跨語言項目
203
+ ## 原始碼倉庫驗收
154
204
 
155
- Agent Handoff Kit 的 runtime instruction 預設使用英文,是為了跨工具穩定與降低 token 成本,不是限制用戶項目的工作語言。你的專案可以用中文、日文或其他語言撰寫 `dev/SESSION_HANDOFF.md` 的段落標題與可見欄位名稱。
205
+ 以下指令供維護者檢查原始碼倉庫,不是一般用戶日常必須執行的步驟:
156
206
 
157
- 做法是保留模板內的 `ack:section:*` 與 `ack:field:*` 語義標記,然後翻譯標題與欄位文字。`doctor` 會驗這些語義標記,而不是要求每個交接段名必須維持英文。
207
+ ```bash
208
+ npm run qa:prototype
209
+ npm run qa:packs
210
+ npm run qa:upgrade
211
+ npm run qa:release
212
+ ```
158
213
 
159
- ## 倉庫與套件邊界
214
+ 這些檢查涵蓋安裝、`doctor`、套件預演、過時字串、公開輸出污染標記、工作規則路由、升級安全,以及從安裝到收工再到下一次開工的流程模擬。
160
215
 
161
- npm package 只保留安裝所需 runtime:
216
+ ## 套件邊界
162
217
 
163
- - `bin/`:prototype CLI。
164
- - `runtime-core/`:安裝到專案內的核心模板。
165
- - `packs/`:安裝到 `dev/rules/*.md` 的規則包。
166
- - `README.md`、`LICENSE`、`package.json`。
218
+ npm package 只包含安裝所需內容:
167
219
 
168
- 原始碼倉庫另外包含設計與驗收文件,供維護者審核,不會進入安裝後的 runtime:
220
+ - `bin/`
221
+ - `runtime-core/`
222
+ - `packs/`
223
+ - `README.md`
224
+ - `LICENSE`
225
+ - `package.json`
169
226
 
170
- - `docs/qa/`:發佈級驗收計劃。
171
- - `scripts/`:原始碼倉庫專用驗收腳本。
172
- - root 層設計文件:問題定義、架構、遷移、保留價值、複雜度與停止規則等。
227
+ 原始碼倉庫中的驗收文件與腳本供維護者使用,不會安裝到你的專案。
173
228
 
174
- ## 非破壞性原則
229
+ ## 目前限制
175
230
 
176
- 本公開草案不修改舊版 `ai-session-governance` repo。`INIT.md` 不是 Agent Handoff Kit 的主要安裝路徑。
231
+ - `v0.1.2` 是早期可用版本,尚未宣稱完整穩定。
232
+ - 這仍是早期可用版本,尚未宣稱完整穩定。
233
+ - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
234
+ - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
235
+ - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
@@ -133,7 +133,7 @@ const requiredAnchors = [
133
133
  label: "template version metadata",
134
134
  snippets: [
135
135
  "Agent Handoff Kit template version",
136
- "0.1.0"
136
+ "0.1.2"
137
137
  ]
138
138
  },
139
139
  {
@@ -349,8 +349,7 @@ async function runInstall(command, root, options, version) {
349
349
  console.log(`conflict: ${conflicts.length}`);
350
350
  if (merged.length > 0) console.log(`backup: ${path.relative(root, backupDir)}`);
351
351
  console.log(`migration report: ${path.relative(root, report)}`);
352
- console.log("next: Follow AGENTS.md");
353
- console.log("tip: Describe your task directly; the AI will choose the working mode and relevant rule packs.");
352
+ printInstallNextSteps(root, conflicts.length);
354
353
  if (conflicts.length > 0) process.exitCode = 1;
355
354
  }
356
355
 
@@ -640,6 +639,31 @@ function printCard(version, status, eyes) {
640
639
  console.log("");
641
640
  }
642
641
 
642
+ function printInstallNextSteps(root, conflictCount) {
643
+ console.log("");
644
+ console.log("============================================================");
645
+ console.log("安裝完成:下一步請在 AI 對話中操作");
646
+ console.log("============================================================");
647
+ if (conflictCount > 0) {
648
+ console.log("狀態:有檔案需要你先處理,詳情見 migration report。");
649
+ console.log("請不要忽略 conflict,也不要直接覆寫既有檔案。");
650
+ console.log("");
651
+ }
652
+ console.log("請注意:下面文字不是 Terminal 指令。");
653
+ console.log("請打開你要使用的 AI 工具,新增一段對話,貼上:");
654
+ console.log("------------------------------------------------------------");
655
+ console.log(`Work in ${root}.`);
656
+ console.log("Read AGENTS.md first. Tell me what you understand before changing files.");
657
+ console.log("------------------------------------------------------------");
658
+ console.log("");
659
+ console.log("然後直接描述你的任務,例如:");
660
+ console.log("整理這個專案,先告訴我你讀到的目前狀態與下一步。");
661
+ console.log("");
662
+ console.log("如要檢查安裝是否完整,可在 Terminal 執行:");
663
+ console.log("npx @adamchanadam/agent-handoff-kit doctor");
664
+ console.log("============================================================");
665
+ }
666
+
643
667
  function listOrNone(items) {
644
668
  if (items.length === 0) return ["- none"];
645
669
  return items.map((item) => `- ${item}`);
@@ -668,8 +692,9 @@ Commands:
668
692
  upgrade Preserve existing files; merge safe core updates or report conflicts.
669
693
  doctor Check required installed files.
670
694
 
671
- Working modes:
672
- Describe your task directly. The AI chooses relevant rule packs for coding,
673
- research, writing, knowledge sync, release, or mixed tasks.
695
+ After install:
696
+ Do not type "Follow AGENTS.md" into Terminal.
697
+ Open your AI tool, start a new chat, paste the shown Work in ... message,
698
+ then describe your task in normal language.
674
699
  `);
675
700
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -25,4 +25,4 @@
25
25
  "node": ">=18"
26
26
  },
27
27
  "license": "MIT"
28
- }
28
+ }
@@ -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.0 | package prototype |
9
+ | Agent Handoff Kit template version | 0.1.2 | package prototype |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |