@adamchanadam/agent-handoff-kit 0.3.33 → 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.
- package/README.md +3 -3
- package/bin/agent-handoff-kit.mjs +352 -171
- package/package.json +1 -1
- package/packs/agent-governance.md +13 -13
- package/packs/integrations.md +142 -120
- package/packs/onboarding.md +201 -393
- package/packs/safety.md +17 -15
- package/runtime-core/AGENTS.core.md +2 -2
- package/runtime-core/PROJECT_DECISIONS.md +7 -8
- package/runtime-core/PROJECT_INDEX.md +39 -39
- package/runtime-core/RULE_PACKS.md +5 -4
package/packs/onboarding.md
CHANGED
|
@@ -1,393 +1,201 @@
|
|
|
1
|
-
# Onboarding Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
###
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
###
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
- AI
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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. |
|