@adamchanadam/agent-handoff-kit 0.3.34 → 0.3.35

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.
@@ -1,393 +1,201 @@
1
- # Onboarding Pack
2
-
3
- ## Scope
4
-
5
- 新手用戶 day-1 walk-through 與 application scenario routing。
6
-
7
- 當用戶第一次使用 Agent Handoff Kit、沒有預設 expectation 或 prior context 時,本 pack 引導 AI 主動帶用戶完成第一個任務,不要求用戶先讀任何文檔。
8
-
9
- 本 pack 屬 transient pack —— 完成 onboarding session 後,AI 自動 unload 並由 regular scenario pack(coding / research / writing / knowledge / ...)接手。
10
-
11
- ## Load When
12
-
13
- ### 明確 onboarding signal keywords(用戶 message 含任一即可)
14
-
15
- - 「新手」/「I'm new」
16
- - 「教我用」/「teach me」/「教我點用」
17
- - 「help me start」/「help me get started」
18
- - 「first time」/「first-time」
19
- - 「我剛安裝」/「I just installed」
20
- - 「點開始」/「how do I start」
21
- - 「show me how」
22
- - 「getting started」
23
- - 「agent handoff kit 可幫我做什麼」/「what can agent handoff kit do」
24
- - 「我想做 [類型] project」/「I want to do a [type] project」(vague project intent)
25
- - 「點用」/「點 leverage」/「能力」/「能做甚麼」/「what can it do」
26
-
27
- ### Implicit signals(任一即可)
28
-
29
- - 用戶首段 message ≤ 30 字 + 任務描述 vague
30
- - HANDOFF Active Objective 空白 + Session count 1(fresh installation context)
31
- - 用戶 message 屬 generic capability question 而非 specific task description
32
- - 用戶語氣 unfamiliar with v2 workflow(譬如問 AI 自己應該做甚麼,而非告訴 AI 做甚麼)
33
-
34
- ## Discipline
35
-
36
- ### 1. 不假設用戶已讀任何文檔
37
-
38
- 用戶可能直接從 AI 對話開始,沒讀過 README、`agent-handoff-kit-intro.html`、`agent-handoff-kit-guide.html` 或 `AGENTS.md`。AI 只解釋當前引導需要的最小範圍,不灌輸內部規則。
39
-
40
- ### 2. 主動 offer 而非被動 wait
41
-
42
- 用戶首段 message vague 或含 onboarding signal 時,AI 不立即 dive into task,而要主動 ask user about scenario。Sample opening wording:
43
-
44
- Onboarding 第一個可見回覆只能有一張完整啟動卡,然後直接接 A-F 情境選擇。不可先輸出半張卡、再輸出第二張完整卡;不可重複貓圖、交接狀態、目前目標、注意事項或下一步。
45
-
46
- > 「我看到你是第一次使用 Agent Handoff Kit。它的作用很簡單:幫 AI 在不同對話之間記住項目進度、下一步與安全界線。
47
- >
48
- > 為了最快上手,請選一個最接近你現在想做的情境:
49
- >
50
- > **A. 建構系統 / 工具 / 平台 / 網站或應用** —— 你想由 AI 協助建立或長期維護一個可運作的項目
51
- > **B. 整理研究資料 / 寫報告** —— 市場調查、論文、文章、簡報都可以
52
- > **C. 整理電腦檔案 / Notion / Google Drive 知識庫** —— 把多個來源的資料整理清楚
53
- > **D. 學寫代碼(我是技術新手)** —— 你想由零開始學寫小工具
54
- > **E. 其他** —— 描述你的情境,我會按你的目標引導
55
- > **F. 我已連接外部工具(例如 Notion / Google Drive / Slack),想規劃如何有系統地使用** —— 我會帶你登記用途、界線與安全注意事項
56
- >
57
- > 選擇其中一個(A/B/C/D/E/F),我會一步一步帶你做第一個任務。」
58
-
59
- ### 3. 5-step walk-through pattern
60
-
61
- 用戶選定情境後,AI 用 5 步引導完成第一個小任務(全部情境共用同一節奏,內容按情境調整):
62
-
63
- 1. **確認項目背景**(資料夾 / 已有資料 / 是否已有版本紀錄 / 使用工具)
64
- 2. **用三點解釋這套工具如何幫到當前情境**
65
- 3. **詢問第一個具體任務範圍**(提供 4-6 個選項)
66
- 4. **建議一個 10-15 分鐘可完成的小任務**(先預演或先產出短內容)
67
- 5. **等用戶確認,再進入正式工作**
68
-
69
- ### 4. 每 step 解釋 + 等用戶 confirm
70
-
71
- 不可以一次過跑完全部 5 步。每一步:
72
- - 解釋緊做甚麼
73
- - 等用戶「OK,下一步」/「我有問題」/「我想 skip 這 step」
74
- - 若用戶有問題,先解答再繼續
75
-
76
- ### 5. 進入 actual task 前先 verify minimum context
77
-
78
- 用戶第一個任務應該很小:先預演、先產出短內容,或先做 10-15 分鐘可完成的範圍。先讓用戶感覺到節奏,再擴大。**不要**第一個任務就做大範圍改動或提交。
79
-
80
- ### 6. 完成 onboarding 後 transition
81
-
82
- 5-step walk-through 完成後:
83
- - 載入用戶情境對應的日常工作規則(coding / research / writing / knowledge / ...)
84
- - Unload onboarding pack(transient pack,不長期駐留)
85
- - 進入 PLAN → READ → CHANGE → QC → PERSIST 的 regular work loop
86
- - SESSION_HANDOFF Active Objective 記錄 first-task scope
87
-
88
- ## Application Scenario Library
89
-
90
- 每個 scenario 提供 5 step walk-through 的紀律 wording 加 1 句 AI sample wording 作為 anchor。AI 模型可 adapt 具體 wording,但必須保留 intent 與 tone。
91
-
92
- ### Scenario A. 建構系統 / 工具 / 平台 / 網站或應用
93
-
94
- **對應 guide.html Case A**(整理電腦下載目錄 + 公開發佈為 Git project)
95
-
96
- #### Step A.1 — 確認項目背景
97
-
98
- - 任務:AI 確認項目資料夾存在 + 識別使用語言 / 框架 + 檢查是否已有 Git 紀錄
99
- - AI sample wording:
100
- > 「請告訴我你的項目在哪個資料夾?如果還未建立,可以先在電腦開一個新資料夾,然後告訴我路徑。我會確認資料夾、檢查是否已有 Git 紀錄,並查看 README / package.json 等常見檔案,判斷下一步應怎樣開始。
101
- >
102
- > 順便問一句:你現在使用的 AI 工具是否已連接 GitHub、Linear、Slack、Notion、Google Drive 或其他外部工具?如果已連接,我可以把用途記入項目索引;如果未連接或不確定,直接說「未確認」即可,之後仍可補上。」
103
-
104
- #### Step A.2 — 解釋這套工具如何配合
105
-
106
- - 任務:AI 用 3 點解釋 Agent Handoff Kit 對建構系統 / 工具 / 平台 / 網站或應用的核心價值
107
- - AI sample wording:
108
- > 「Agent Handoff Kit 對建構系統、工具、平台、網站或應用有三個用處:(1) AI 跨對話記得項目的語言、規則、進度,下次開新對話仍接得回;(2) 危險指令(例如刪檔、重設 Git、強制推送)必須先講計劃,不會靜默執行;(3) 收工時自動寫下做過甚麼,方便日後追溯。」
109
-
110
- #### Step A.3 — 詢問第一個任務範圍
111
-
112
- - 任務:AI 提供 4-6 個具體任務選項讓用戶選
113
- - AI sample wording:
114
- > 「你的項目現在最想處理的是哪一類?(a) 修錯誤 / (b) 加新功能 / (c) 整理既有代碼 / (d) 加測試 / (e) 寫 README / (f) 做第一個 Git 提交?如果你想做的不在這幾項,直接告訴我即可。」
115
-
116
- #### Step A.4 — 建議第一個小任務
117
-
118
- - 任務:AI 將用戶選擇收窄至 10-15 分鐘可完成的小任務
119
- - AI sample wording:
120
- > 「你選『寫 README』。我建議第一個任務先做小:寫一個約 100 字的 README.md,包含一句項目簡介加三點功能。寫好後你核對、補自己的修改,最後再決定是否做 Git 提交。整個過程約 10 分鐘。可以嗎?」
121
-
122
- #### Step A.5 — 等用戶確認,再進入正式工作
123
-
124
- - 任務:AI 確認用戶同意 + 載入對應日常工作規則 + 開始正式工作
125
- - AI sample wording:
126
- > 「你確認後,我會使用寫代碼與寫作兩套工作規則,先列計劃,再讀相關檔案,然後才改動。準備好嗎?」
127
-
128
- ### Scenario B. 整理研究資料 / 寫報告
129
-
130
- **對應 guide.html Case B**(開咖啡店市場調查 + 寫完成報告)
131
-
132
- #### Step B.1 — 確認項目背景
133
-
134
- - AI sample wording:
135
- > 「請告訴我三點:(1) 你的報告主題;(2) 已有資料在哪裡(Notion / Google Drive / 本地檔案);(3) 報告的讀者是誰(自己 / 客戶 / 合作伙伴 / 公開)。我會根據這三點建議分工。
136
- >
137
- > 順便:你是否已連接 Notion 或 Google Drive?如果有,我可以直接讀寫對應資料庫或資料夾;如果未連接,我會改為列出需要你手動同步的內容。如果不確定,說「未確認」即可。」
138
-
139
- #### Step B.2 — 解釋 v2 如何 fit
140
-
141
- - AI sample wording:
142
- > 「Agent Handoff Kit 對研究類項目的核心價值有三點:(1) 真源紀律 —— 每條主張必須引用,事實與推論分開寫,AI 不會憑印象寫;(2) 外部來源治理 —— 如果你已連接 Notion / Google Drive 或其他外部工具,AI 可直接讀寫對應資料;未連接時,AI 會列出需要你手動同步的內容;(3) 跨對話接力 —— 你寫到一半收工,下次仍能接得上,包括引用紀律和項目登記表中的外部工具紀錄。」
143
-
144
- #### Step B.3 — Ask user about 第一個 task scope
145
-
146
- - AI sample wording:
147
- > 「你想 first session 處理:(a) 列章節結構 / (b) 整理已有 reference 入 PROJECT_INDEX / (c) 寫摘要段 / (d) 寫第一個 sub-section / (e) 整體 review 已有 draft?」
148
-
149
- #### Step B.4 — 建議第一個小任務
150
-
151
- - AI sample wording:
152
- > 「你選『列章節結構』。我建議第一個任務先做小:列 5-7 個章節標題,並為每章寫一句目標。寫好後你核對、調整。約 15 分鐘可以完成。可以嗎?」
153
-
154
- #### Step B.5 — Ask user about confirm + 進入 work loop
155
-
156
- - AI sample wording:
157
- > 「你確認後,我會使用研究、寫作與知識整理規則。先列計劃,再讀資料,然後才寫內容。」
158
-
159
- ### Scenario C. 整理電腦檔案 / Notion / Google Drive 知識庫
160
-
161
- **對應 guide.html Case A 的檔案整理部分 + Case B 的 Notion reference 部分**
162
-
163
- #### Step C.1 — 確認項目背景
164
-
165
- - AI sample wording:
166
- > 「請告訴我你想整理的是:(a) 電腦資料夾(哪個位置)/ (b) Notion 資料庫(大概有哪些欄位)/ (c) Google Drive(哪個資料夾)/ (d) 多個來源混合(請描述)。
167
- >
168
- > 順便:如果涉及 Notion、Google Drive、Dropbox 等外部來源,你是否已連接對應外部工具?如果有,我可以直接讀寫;如果沒有,我會列出手動同步步驟。如果不確定,說「未確認」即可。」
169
-
170
- #### Step C.2 — 解釋 v2 如何 fit
171
-
172
- - AI sample wording:
173
- > 「Agent Handoff Kit 對知識庫整理有三個用處:(1) 分清正式來源、參考資料與草稿,避免 AI 把參考檔當成真源;(2) 如果你已連接 Notion / Google Drive 等外部工具,AI 可直接讀寫對應資料;未連接時,AI 會列出需要你手動同步的步驟;(3) 涉及大量檔案移動、重命名或刪除時,必須先列預演清單,等你確認才實際執行。」
174
-
175
- #### Step C.3 — Ask user about 第一個 task scope
176
-
177
- - AI sample wording:
178
- > 「你想 first session 處理:(a) 掃描 + 分類已有檔案 / (b) 建立 Notion DB schema / (c) 設計 folder 結構 / (d) 寫整理 script + dry-run / (e) 對齊 Notion 與本地 reference?」
179
-
180
- #### Step C.4 — 建議第一個小任務
181
-
182
- - AI sample wording:
183
- > 「你選『掃描 + 分類已有檔案』。我建議第一步先預演 100 個檔案,只列分類建議,由你確認,暫時不做實際移動。約 15 分鐘可完成。可以嗎?」
184
-
185
- #### Step C.5 — Ask user about confirm + 進入 work loop
186
-
187
- - AI sample wording:
188
- > 「你確認後,我會使用知識整理與安全規則;凡涉及移動或重命名檔案,都先預演、再等你確認。」
189
-
190
- ### Scenario D. 學寫代碼(技術新手)
191
-
192
- **不對應 specific guide case,屬 onboarding-only scenario**
193
-
194
- #### Step D.1 — 確認學習背景
195
-
196
- - AI sample wording:
197
- > 「你想先學哪一類?(a) 簡單自動化小工具(例如整理檔案)/ (b) 一個網頁(HTML/CSS/JS)/ (c) 一個 Python 小工具 / (d) Git / GitHub 基本概念?告訴我你的興趣方向,我會安排第一個練習。
198
- >
199
- > 順便:你使用的 AI 工具是否已安裝任何 Plugin 或 Skill?初學階段不需要太多,但有 GitHub Connector 會方便日後操作。未安裝或不確定時,說「未確認」即可。」
200
-
201
- #### Step D.2 — 解釋 v2 如何 fit
202
-
203
- - AI sample wording:
204
- > 「v2 對學寫代碼的核心 value 有三點:(1) AI 幫你寫,但不會默默改你的檔案 —— 每改一步等你 review;(2) 危險指令 AI 自己拒絕,你可以在 sandbox 安全試;(3) 跨 session 記住你學到哪裡,下次接得返,包括之前學過的概念。」
205
-
206
- #### Step D.3 — Ask user about 第一個 task scope
207
-
208
- - AI sample wording:
209
- > 「你選『簡單 script』?我建議第一個 script:『重命名 Downloads 目錄裡面所有 screenshot 加日期』—— 涉及 file system basics 加 Python basic syntax。你想試嗎?或者選其他方向。」
210
-
211
- #### Step D.4 — 建議第一個小練習
212
-
213
- - AI sample wording:
214
- > 「第一個練習先做很小:寫一個約 5 行的 Python 小工具,先只顯示它準備怎樣重新命名檔案,不做實際改動。你核對後,才決定是否真的改名。整個過程我會逐句解釋每一行做甚麼。約 15 分鐘。可以嗎?」
215
-
216
- #### Step D.5 — Ask user about confirm + 進入 work loop
217
-
218
- - AI sample wording:
219
- > 「你確認後,我會使用寫代碼與安全規則。我會用最簡單的說法解釋每個概念,不假設你已懂技術詞。」
220
-
221
- ### Scenario E. 其他 / 用戶自定義情景
222
-
223
- 如果用戶的情境不屬 A-D,AI 先詢問更多細節,再安排 5 步引導。
224
-
225
- #### Step E.1 — 確認自訂情境
226
-
227
- - AI sample wording:
228
- > 「請告訴我四點:(1) 你想完成的目標(一句講完);(2) 已有資料 / 工具 / 限制;(3) 你的技術水平(零基礎 / 略有經驗 / 熟練);(4) 第一輪對話想完成甚麼小成果。我會根據這四點安排第一個可落地的小任務。
229
- >
230
- > 順便:你使用的 AI 工具是否已連接任何 Connector、MCP、Plugin 或 Skill?任何已連接的工具都可以說;未連接或不確定時,說「未確認」即可。」
231
-
232
- #### Step E.2 — 解釋 v2 如何 fit(custom)
233
-
234
- - AI 根據用戶提供的四點,解釋 Agent Handoff Kit 如何幫到這個情境(保留「跨對話接力 + 安全護欄 + 自動維護」三項核心價值)
235
-
236
- #### Step E.3 — Ask user about 第一個 task scope(custom)
237
-
238
- - AI 提供對應用戶情境的選項
239
-
240
- #### Step E.4 — 建議第一個小任務
241
-
242
- - AI 將範圍收窄至 10-15 分鐘可完成的小任務
243
-
244
- #### Step E.5 — Ask user about confirm + 進入 work loop(custom)
245
-
246
- - AI 載入適合該情境的日常工作規則(可能組合多個規則)
247
-
248
- ### Scenario F. 審視已裝外部工具 + 設計治理
249
-
250
- **對應 v0.3.0 引入的 Integration governance 紀律**(不教 install,只教 declare + plan governance)
251
-
252
- #### Step F.1 — Intake:列你已安裝的外部工具
253
-
254
- - 任務:AI 收集用戶已安裝的 Connector / MCP / Plugin / Skill,按四類分類
255
- - AI sample wording:
256
- > 「請告訴我你已安裝的外部工具,盡量分四類列:
257
- >
258
- > **(a) Anthropic 官方 Connector**(經 Claude Desktop Settings → Extensions 一鍵安裝)—— 譬如 Notion / Google Drive / Slack / Linear / Atlassian / HubSpot 等
259
- > **(b) Community / Custom MCP server**(用戶自建或第三方提供)—— 譬如從 GitHub repo 安裝的 server
260
- > **(c) Claude Code Plugin**(經 `/plugin` command 安裝)—— 譬如 Anthropic-managed marketplace bundle
261
- > **(d) Skill**(SKILL.md 直接安裝或 plugin 攜帶)—— 譬如 superpowers skill / 自製 skill
262
- >
263
- > 不記得類別時,只列名稱即可,我會幫你分類。如果未安裝任何外部工具,說『目前只用本機檔』即可。」
264
-
265
- #### Step F.2 — 機密分離 brief
266
-
267
- - 任務:AI 解釋 credential 如何儲存 + Kit 不記 credential 值
268
- - AI sample wording:
269
- > 「我會幫你登記已安裝工具,但 **任何 API key / OAuth token / credential 都不會記錄在項目登記表**。
270
- >
271
- > Notion / Google Drive 等 credential 通常在你安裝 Connector 時,已由 AI 工具加密儲存在系統安全儲存層(例如 macOS Keychain / Windows Credential Manager)—— 項目登記表只會記錄三件事:(1) 你用了哪個工具、(2) 用它做甚麼(例如 Notion 做資料索引)、(3) credential 由哪個工具管理(例如『Claude Desktop Extensions』),但不記錄 credential 值本身。
272
- >
273
- > 你不需要在對話貼出 token。如果不小心貼出,我會立即要求遮蔽並建議你更換 token。」
274
-
275
- #### Step F.3 — Source-of-truth Architecture mapping
276
-
277
- - 任務:AI 引導用戶設計多層持久化分工
278
- - AI sample wording:
279
- > 「對於每個工具,告訴我它在項目中的角色:
280
- >
281
- > - **真源(source of truth)**:原始可審計的 reference 內容(例如本機 `~/project/reference/` 存 PDF)
282
- > - **Index**:登記每份真源檔的 metadata + 摘要 + tag(例如 Notion DB「Project Index」)
283
- > - **持久化參考檔(mirror)**:防本機 disk failure / 跨裝置 access(譬如 Google Drive folder 同步本機)
284
- > - **Working draft**:AI 寫 task output(譬如本機 `~/project/output/`)
285
- >
286
- > 一個工具可以承擔一個或多個角色。如果你第一次設計這套分工,我建議典型做法是:本機 = 真源 + 工作草稿、Notion = 索引、Google Drive = 備份鏡像。可以採用,也可以描述你自己的分工方式。」
287
-
288
- #### Step F.4 — 寫入項目登記表
289
-
290
- - 任務:AI 將用戶 declaration 寫入 PROJECT_INDEX `## Installed Integrations` + External Sources `via` column
291
- - AI sample wording:
292
- > 「我會將你已聲明的工具寫入項目登記表:
293
- >
294
- > - `## Installed Integrations` `### Connectors` 表填 Notion / Google Drive 等 entries(每個含 Project Usage / Access Scope / Specific Instance / Credential Reference(no value)/ Declared / Last Verified)
295
- > - `## Installed Integrations` `### Source-of-truth Architecture` sub-table 填多層分工
296
- > - 既有 `## External Sources` 表的 `via` column 引用對應 Connector entry
297
- >
298
- > 寫好之後我會給你核對。有錯可以即時修改。」
299
-
300
- #### Step F.5 — Verify availability + 進入 actual task 或 standby
301
-
302
- - 任務:AI 做能力檢查,確認已聲明的外部工具在本次對話可用,然後接力下一個任務
303
- - AI sample wording:
304
- > 「聲明已寫好。我會檢查每個外部工具在本次對話是否可用:
305
- >
306
- > - Connector / MCP:先讀本次 runtime 暴露的工具名稱、描述與輸入 schema,再做最小 probe
307
- > - API / SDK / CLI / URI / plugin API:先查官方文件、官方型別 / sample,或有版本日期的本地 runbook
308
- > - 不能核實的工具:標記 blocked / unverified,不憑記憶試錯
309
- >
310
- > 檢查結果會寫入每行 `Last Verified` 欄位。如果任何外部工具不可用(例如目前 AI 工具未配對應 MCP),我會直接說明,讓你決定如何處理。
311
- >
312
- > 之後你想進入實際任務,就描述你想做甚麼(例如『開始整理參考資料』),我會使用對應的日常工作規則接力。如果未準備好,說『暫停』即可。」
313
-
314
- ## Cross-reference to guide.html
315
-
316
- 每個 scenario walk-through 完成後(或者用戶問「我想睇完整 example」),AI 可以 mention:
317
-
318
- > 「如果想看完整 narrative example,可以開新 tab 看 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html 的 Case A/B/C:
319
- >
320
- > - Case A 對應 onboarding scenario A(建構系統 / 工具 / 平台 / 網站或應用)加 scenario C 的檔案整理部分
321
- > - Case B 對應 onboarding scenario B(整理研究資料 / 寫報告)加 scenario F 的多源 governance 設計(Notion DB Index + 本機真源 + Google Drive 持久化參考檔 三層 architecture)
322
- > - Case C 對應長期項目演進(適用於你項目運行到後期,跨多月時間軸;Day 30+ narrative 含 Integration declaration 演進)
323
- >
324
- > 本指南是參考對照,不需要先讀。」
325
-
326
- ## Tone Discipline
327
-
328
- ### 1. 書面語為主
329
-
330
- 使用繁體中文書面語表達。避免廣東口語字符(嘅 / 咁 / 喺 / 揀 / 唔 / 乜 / 啱 / 嚟 / 咗 / 嗰)出現在 AI 對用戶 surface 的 sample wording。Pack 內部 governance instructions(rules / discipline 等 maintainer-facing wording)允許 mixed style。
331
-
332
- ### 2. 講人話
333
-
334
- 紀律邊界要清楚劃分:
335
-
336
- - **要過濾嘅 internal jargon**(用戶不需要知 Kit 內部運作):R-XXX / PROJECT_INDEX / closeout step / managed core / SESSION_LOG N-rule / startup contract / handoff sufficiency 等
337
- - **要教嘅 user-facing 概念**(2026-05 用戶普遍認知,需要正確命名):Connector / MCP / Plugin / Skill / Claude Desktop Extensions / 一鍵安裝 等
338
-
339
- 對 internal jargon 改用日常解釋:
340
-
341
- - 「項目登記表」而非「PROJECT_INDEX」
342
- - 「收工」而非「closeout」
343
- - 「下次開工提示」而非「next-session opening message」
344
- - 「AI 工作模式」而非「rule pack」
345
- - 「危險指令」而非「destructive operation」
346
-
347
- 對 user-facing 概念保留原英文 / 已 mainstream 嘅中文譯名:
348
-
349
- - 「Connector」/「Anthropic 官方整合」
350
- - 「MCP」/「外部工具協議」
351
- - 「Plugin」/「插件」(Claude Code plugin)
352
- - 「Skill」/「技能」(SKILL.md instruction)
353
- - 「Claude Desktop Extensions」/「一鍵安裝」
354
-
355
- ### 3. 敍事 + 解釋
356
-
357
- 每個解釋句要 self-contained,用戶讀完即知道意義。不留 unexplained acronym 或 inside-reference。
358
-
359
- ### 4. 不過度解釋 internals
360
-
361
- 用戶不需要知 AGENTS.md 結構、`dev/*` folder 含甚麼、closeout step 11/12 紀律細節。只解釋 surface impact:「AI 會記住你 project」而非「AGENTS.md startup contract 加 SESSION_HANDOFF 對賬式紀律」。
362
-
363
- ### 5. 鼓勵性而非考試
364
-
365
- 用「我會帶你做第一個任務」而非「請描述任務」。用「可以嗎?」而非「請確認」。
366
-
367
- 每 step 標明角色分工:「我(AI)做 X,你做 Y」。避免讓用戶覺得自己被考核。
368
-
369
- ## Closeout
370
-
371
- 完成 onboarding session 後,AI 必執行:
372
-
373
- 1. **確認用戶下一步**:用戶接下來知道如何使用 v2,包括下次如何開新對話、如何描述任務、如何收工。
374
- 2. **更新 SESSION_HANDOFF Active Objective**:寫入用戶嘅第一個 task scope,方便下次接力。
375
- 3. **更新 SESSION_HANDOFF Next Priorities**:列下次 session 嘅 next concrete action(譬如「完成 README,然後 git commit」)。
376
- 4. **提供 standard handoff opening message**:「下一輪開新對話時貼以下一句⋯⋯」嘅 fenced text block。
377
- 5. **Unload onboarding pack**:由 regular scenario pack(coding / research / writing / knowledge / ...)接手。
378
-
379
- 下次 session 開新對話時:
380
- - 如果用戶仍 vague:可以 re-trigger onboarding pack(用戶可能想重新 onboard)
381
- - 如果用戶已熟悉:AI 直接進入 regular work loop,跳過 onboarding pack
382
-
383
- ## Anti-pattern(不要做的事)
384
-
385
- | Anti-pattern | 點解唔做 | 正確做法 |
386
- |---|---|---|
387
- | 收到 user vague message 立即 dive into 一個猜測嘅 task | 用戶可能根本未準備好 / 想其他嘢 / 想了解工具能力 | 主動 ask scenario A-E |
388
- | 第一個 task suggest 大 scope(譬如「我幫你重構整個 codebase」) | 用戶感到 overwhelmed + 唔知 v2 嘅 rhythm | Suggest 10-15 分鐘 minimum viable task |
389
- | 用 jargon 解釋 v2(R-XXX / PROJECT_INDEX / etc) | 新手 cognitive load 高,唔知 jargon 對應乜 | 用日常 wording 解釋 surface impact |
390
- | 假設用戶讀過 README / intro / guide | 用戶可能跳過文檔直接從 AI 對話開始 | 主動 surface 必要 concept,但不灌輸 |
391
- | 完成 onboarding 後唔 unload pack | Onboarding pack 屬 transient,長期駐留會 noise | Closeout 時 explicit unload + 載入 regular pack |
392
- | 一次過跑 5 step 唔等用戶 confirm | 用戶 cognitive load 爆 + 失去 walk-through 精神 | 每 step 等用戶 confirm 才繼續 |
393
- | 假設用戶冇裝任何 Connector / MCP,預設 paste-only flow | 違反 2026-05 reality —— Connector ecosystem 已成熟,paste-only 不應係 default;錯誤心智模型會持續影響後續 session | Scenarios A-E Step 1 加 micro-question 問已裝整合;或者用戶選 Scenario F dedicated declaration path |
1
+ # Onboarding Pack
2
+
3
+ ## Scope
4
+
5
+ Use this transient pack for first-time Agent Handoff Kit users, vague first messages, or fresh-install sessions where the user has not yet chosen a working scenario.
6
+
7
+ The goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.
8
+
9
+ ## Load When
10
+
11
+ ### Explicit onboarding signal keywords
12
+
13
+ Load this pack when the user message contains an onboarding signal such as:
14
+
15
+ - "I'm new" / "new user"
16
+ - "teach me" / "help me start" / "help me get started"
17
+ - "first time" / "first-time" / "I just installed"
18
+ - "how do I start" / "show me how" / "getting started"
19
+ - "what can agent handoff kit do"
20
+ - vague project intent such as "I want to do a project"
21
+ - equivalent Chinese user phrases such as "新手", "教我用", "我剛安裝", "點開始", "開工", "能力", or "能做甚麼"
22
+
23
+ ### Implicit signals
24
+
25
+ - The first user message is short and vague.
26
+ - `SESSION_HANDOFF` Active Objective is empty and Session count is 1.
27
+ - The user asks a generic capability question instead of giving a concrete task.
28
+ - The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
29
+
30
+ ## Discipline
31
+
32
+ ### 1. Do not assume prior reading
33
+
34
+ The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
35
+
36
+ ### 2. Offer scenario choice before task execution
37
+
38
+ When onboarding applies, the first visible response must combine the startup card and scenario chooser into one complete response. Do not print a partial startup card first. Do not repeat the status card, current objective, warnings, or next step.
39
+
40
+ Offer six scenarios:
41
+
42
+ - **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.
43
+ - **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.
44
+ - **C. Organize local files, Notion, Google Drive, or a knowledge base**: the user wants source, reference, mirror, and draft material kept clear.
45
+ - **D. Learn to code**: the user is a technical beginner and wants a small guided exercise.
46
+ - **E. Custom scenario**: the user has another goal.
47
+ - **F. Review installed external tools and design governance**: the user already has Connectors, MCPs, Plugins, Skills, or browser / notebook / crawler tools and wants a safe operating model.
48
+
49
+ ### 3. 5-step walk-through pattern
50
+
51
+ After the user picks a scenario, guide one small first task through five steps:
52
+
53
+ 1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.
54
+ 2. Explain in three plain points how Agent Handoff Kit helps this scenario.
55
+ 3. Ask for the first concrete task scope, offering four to six practical options.
56
+ 4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.
57
+ 5. Wait for user confirmation, then transition to the regular work loop.
58
+
59
+ ### 4. Advance one step at a time
60
+
61
+ Do not run all five steps in one message. At each step:
62
+
63
+ - state what the AI will do,
64
+ - state what the user needs to answer or confirm,
65
+ - answer questions before continuing,
66
+ - let the user skip or change the step.
67
+
68
+ ### 5. Keep the first task small
69
+
70
+ The first task should be a preview, a short draft, a small classification sample, a dry-run, or another bounded result. Do not begin with broad refactors, bulk file moves, publishing, deployment, or destructive operations.
71
+
72
+ ### 6. Transition after onboarding
73
+
74
+ After the walk-through:
75
+
76
+ - load the regular pack(s) for the chosen task,
77
+ - unload this transient onboarding pack,
78
+ - enter the PLAN -> READ -> CHANGE -> QC -> PERSIST work loop,
79
+ - record the first-task scope in `SESSION_HANDOFF` when the persistence gate requires it.
80
+
81
+ ## Application Scenario Library
82
+
83
+ Each scenario keeps the same five-step rhythm. The model may adapt wording, but must preserve the intent, tone, and safety boundaries.
84
+
85
+ ### Scenario A. Build systems, tools, platforms, websites, or apps
86
+
87
+ Step A.1: ask for the project folder, current stack if known, whether git exists, and whether GitHub, Linear, Slack, Notion, Google Drive, or other external tools are connected.
88
+
89
+ Step A.2: explain that Kit helps the AI remember project state across sessions, avoid silent risky commands, and record what changed at closeout.
90
+
91
+ Step A.3: offer task choices such as fix a bug, add a feature, organize code, add tests, write README, or prepare a first commit.
92
+
93
+ Step A.4: suggest a small first task, such as a short README section, one failing test investigation, or a dry-run plan.
94
+
95
+ Step A.5: after confirmation, load the relevant coding / writing / safety packs and begin the normal work loop.
96
+
97
+ ### Scenario B. Organize research or write a report
98
+
99
+ Step B.1: ask for the topic, existing source locations, intended reader, and whether Notion, Google Drive, or another source tool is connected.
100
+
101
+ Step B.2: explain that Kit separates source evidence from inference, records source locations, and preserves progress across sessions.
102
+
103
+ Step B.3: offer task choices such as outline sections, register sources, summarize one source, draft a subsection, or review an existing draft.
104
+
105
+ Step B.4: suggest a small first task, such as a 5-7 heading outline with one sentence per section.
106
+
107
+ Step B.5: after confirmation, load research / writing / knowledge packs and begin the normal work loop.
108
+
109
+ ### Scenario C. Organize local files, Notion, Google Drive, or a knowledge base
110
+
111
+ Step C.1: ask what needs organizing: local folder, Notion database, Google Drive folder, or mixed sources. Ask which external tools are connected or unknown.
112
+
113
+ Step C.2: explain that Kit separates source of truth, references, mirrors, and drafts, and that risky file operations require dry-run and confirmation.
114
+
115
+ Step C.3: offer task choices such as scan and classify files, design a folder structure, draft a Notion schema, write a dry-run script, or align local references with an external index.
116
+
117
+ Step C.4: suggest a small first task, such as classifying a bounded sample without moving files.
118
+
119
+ Step C.5: after confirmation, load knowledge / safety / integrations packs as needed.
120
+
121
+ ### Scenario D. Learn to code
122
+
123
+ Step D.1: ask which direction the user wants: small automation, web page, Python tool, Git / GitHub basics, or another beginner task. Ask whether any relevant tools are already installed.
124
+
125
+ Step D.2: explain that Kit keeps learning progress across sessions, keeps risky operations explicit, and lets the user review each small change.
126
+
127
+ Step D.3: offer one small exercise, such as a dry-run file renamer, a one-page HTML example, or a tiny Python script.
128
+
129
+ Step D.4: keep the exercise small enough to explain line by line.
130
+
131
+ Step D.5: after confirmation, load coding / safety packs and begin the normal work loop.
132
+
133
+ ### Scenario E. Custom scenario
134
+
135
+ Step E.1: ask for four facts: objective, existing material or tools, technical comfort level, and the first small result the user wants.
136
+
137
+ Step E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.
138
+
139
+ Step E.3: offer task choices tailored to the user's answer.
140
+
141
+ Step E.4: suggest one minimum viable first task.
142
+
143
+ Step E.5: after confirmation, load the appropriate regular pack combination.
144
+
145
+ ### Scenario F. External-tool governance
146
+
147
+ Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
148
+
149
+ Step F.1: collect installed external tools by category: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. If the user does not know the category, ask for names only and classify them.
150
+
151
+ Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
152
+
153
+ Step F.3: map source-of-truth architecture: source of truth, index, persistent mirror, and working draft. Make each layer's write boundary explicit.
154
+
155
+ Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
156
+
157
+ Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. Mark unavailable tools as blocked / unverified instead of guessing.
158
+
159
+ ## Cross-reference to guide.html
160
+
161
+ When the user asks for a fuller example, mention `agent-handoff-kit-guide.html` as an optional reference. The guide is not required reading.
162
+
163
+ - Case A aligns with Scenario A plus parts of Scenario C.
164
+ - Case B aligns with Scenario B plus Scenario F.
165
+ - Case C aligns with long-running project evolution.
166
+
167
+ ## Tone Discipline
168
+
169
+ Use plain user-facing language. Avoid internal jargon in onboarding replies unless the user asks for implementation details.
170
+
171
+ - Say "project registry" before exposing `PROJECT_INDEX`.
172
+ - Say "wrap up" or the user's own closeout phrase before exposing closeout internals.
173
+ - Say "next-session startup message" only when discussing the persisted handoff file.
174
+ - Say "working mode" before exposing "rule pack".
175
+ - Say "risky command" before exposing "destructive operation".
176
+
177
+ Keep user-facing explanations self-contained. For the public product's Chinese surfaces, use steady written Traditional Chinese and avoid Cantonese spoken characters. Inside this AI-facing pack, keep instructions in English and use Chinese only as quoted user phrases that the runtime must recognize.
178
+
179
+ ## Closeout
180
+
181
+ After onboarding finishes:
182
+
183
+ 1. Confirm that the user knows the next practical action, how to start a later session, and how to request closeout.
184
+ 2. Update `SESSION_HANDOFF` only when the persistence gate says the first-task scope or next action is durable.
185
+ 3. Record next priorities only when they affect a later session.
186
+ 4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.
187
+ 5. Unload this pack and continue with the relevant regular pack(s).
188
+
189
+ In a later session, reload onboarding only when the user gives a fresh onboarding signal or asks to restart the walk-through. Otherwise enter the normal work loop.
190
+
191
+ ## Anti-patterns
192
+
193
+ | Anti-pattern | Why it is wrong | Correct approach |
194
+ |---|---|---|
195
+ | Treating a vague first message as a specific task | The user may be trying to learn the workflow or choose a scenario. | Offer the A-F scenario chooser first. |
196
+ | Making the first task broad | A first-time user needs rhythm and confidence before large changes. | Suggest one 10-15 minute minimum viable task. |
197
+ | Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |
198
+ | Assuming the user read README or guide pages | Many users start directly in an AI chat. | Surface only the concepts needed for the next step. |
199
+ | Keeping onboarding loaded after the first task starts | Onboarding is transient and will distract from normal task work. | Unload onboarding and load the regular pack(s). |
200
+ | Running all five steps without waiting | The user loses control of the walk-through. | Pause for confirmation at each step. |
201
+ | Assuming no Connector, MCP, Plugin, or Skill exists | Paste-only fallback creates the wrong operating model for users who already connected tools. | Ask a lightweight external-tool question in step 1, or use Scenario F. |