@adamchanadam/agent-handoff-kit 0.3.9 → 0.3.11
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 +35 -26
- package/bin/agent-handoff-kit.mjs +267 -170
- package/docs/whatsnew/v0.3.1.md +5 -5
- package/docs/whatsnew/v0.3.10.md +19 -0
- package/docs/whatsnew/v0.3.11.md +19 -0
- package/docs/whatsnew/v0.3.2.md +5 -5
- package/docs/whatsnew/v0.3.3.md +5 -5
- package/docs/whatsnew/v0.3.4.md +2 -2
- package/package.json +1 -1
- package/packs/integrations.md +7 -7
- package/packs/onboarding.md +125 -121
- package/packs/safety.md +1 -1
- package/packs/writing.md +2 -0
- package/runtime-core/AGENTS.core.md +15 -15
- package/runtime-core/CLAUDE.md +8 -8
- package/runtime-core/GEMINI.md +7 -3
- package/runtime-core/PROJECT_INDEX.md +4 -4
- package/runtime-core/RULE_PACKS.md +3 -3
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# v0.3.10
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
改善第一次安裝後的實際使用流程。終端機完成安裝後,提示會更清楚地把「終端機動作」與「AI 對話下一步」分開;新手引導會用 5 步幫用戶選情境、問背景、收斂第一個小任務,再等用戶確認後才開始正式工作。
|
|
6
|
+
|
|
7
|
+
## 對你已有檔案的影響
|
|
8
|
+
|
|
9
|
+
本版會保留既有項目內容。升級時若發現 `CLAUDE.md` 被 AI 改成一份很長的規則文件,工具會把它恢復為短橋接檔,避免 Claude Code 把橋接檔當成第二套規則來源。`GEMINI.md` 也同步說明 Antigravity CLI 與 Gemini CLI 遷移期的入口關係。
|
|
10
|
+
|
|
11
|
+
## 建議下一步
|
|
12
|
+
|
|
13
|
+
升級前可先預演:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
確認沒有衝突後再升級。升級完成後,如你是第一次使用這個項目,請把工具顯示的完整起步句貼到 AI 對話,而不是留在終端機繼續操作;舊項目升級用戶則照原本開工方式繼續即可。
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# v0.3.11
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
本版把 v0.3.10 發佈後留下的用戶旅程檢查補成長期守門。重點不是增加新功能,而是把已驗證的首次安裝、升級、衝突停手與公開文件一致性,轉成每次發佈前都會跑的檢查。
|
|
6
|
+
|
|
7
|
+
## 對你已有檔案的影響
|
|
8
|
+
|
|
9
|
+
既有項目不用重裝。升級時若沒有需要合併的內容,工具不會假裝完成一件大事;若遇到不能安全判斷的衝突,會清楚停手並提示先處理衝突。舊版本升上來時,工具也會保留既有資料與本地規則。
|
|
10
|
+
|
|
11
|
+
## 建議下一步
|
|
12
|
+
|
|
13
|
+
升級前可先預演:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
如果預演沒有 conflict,再執行正式升級。升級後可用 `doctor` 檢查項目是否完整;第一次使用的新項目,仍按安裝後顯示的起步句進入 AI 對話。
|
package/docs/whatsnew/v0.3.2.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# v0.3.2
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 本版新加了甚麼
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`doctor` 和 `init` 會顯示「項目狀態速覽」,包括工具版本、項目記錄版本、npm 最新版本、上次收工時間,以及項目首次安裝距今多久。`upgrade` 完成後也會直接顯示本版重點,讓使用者不必再另外查找更新說明。
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 對你已有檔案的影響
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
本版只改善工具提示與狀態顯示,不會改動既有項目內容,也不會改變已安裝的 Kit 文件結構。
|
|
10
10
|
|
|
11
11
|
## 建議下一步
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
執行 `doctor` 檢查項目健康,並留意輸出中的「項目狀態速覽」。
|
package/docs/whatsnew/v0.3.3.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# v0.3.3
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 本版新加了甚麼
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
修正升級後的版本提示矛盾。完成 `upgrade` 後,`doctor` 不應再說項目版本落後於目前工具版本。若使用者從較舊版本直接升級到本版,工具也會提示這次跨度較大,並引導使用者查看 GitHub Release 的完整歷史說明。
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 對你已有檔案的影響
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
本版不會改動使用者填寫的項目內容。`upgrade` 後,`dev/PROJECT_INDEX.md` 內的「Agent Handoff Kit template version」資料列會更新為目前版本;其他由使用者填寫的資料列會保留。
|
|
10
10
|
|
|
11
11
|
## 建議下一步
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
執行 `doctor` 檢查項目健康即可。
|
package/docs/whatsnew/v0.3.4.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# v0.3.4
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 本版新加了甚麼
|
|
4
4
|
|
|
5
5
|
本版修補升級後版本敘事不一致的問題。既有專案執行 `upgrade` 後,`dev/PROJECT_INDEX.md` 內的「Agent Handoff Kit template version」資料列會在合併完成後再更新為目前 CLI 版本,避免先更新、後又被舊合併結果覆蓋。
|
|
6
6
|
|
|
7
7
|
升級工具也會辨認「只有版本資料列過期」的情況。即使沒有新增檔案、沒有合併檔案、沒有衝突,只要這一列仍是舊版本,就不會誤報「已經是最新版本,沒有檔案需要建立或合併」。
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## 對你已有檔案的影響
|
|
10
10
|
|
|
11
11
|
本版只會更新 `dev/PROJECT_INDEX.md` 的 template version metadata。這一列屬工具維護的模板資料,不是你填寫的項目內容。你在 External Sources、Fact Base、Workspace Identity 等表格中填過的內容仍會保留。
|
|
12
12
|
|
package/package.json
CHANGED
package/packs/integrations.md
CHANGED
|
@@ -10,11 +10,11 @@
|
|
|
10
10
|
|
|
11
11
|
## Load When
|
|
12
12
|
|
|
13
|
-
- 任務描述提到 Notion / Drive / Slack / Linear / Dropbox / HubSpot / GitHub / 其他外部工具
|
|
14
|
-
- 用戶問「我可以叫 AI 直接讀 / 寫 Notion / Drive / 等嗎?」
|
|
13
|
+
- 任務描述提到 Notion / Google Drive / Slack / Linear / Dropbox / HubSpot / GitHub / 其他外部工具
|
|
14
|
+
- 用戶問「我可以叫 AI 直接讀 / 寫 Notion / Google Drive / 等嗎?」
|
|
15
15
|
- 項目 `dev/PROJECT_INDEX.md` `## Installed Integrations` section 非空
|
|
16
16
|
- 第一次安裝後 onboarding 階段(與 `dev/rules/onboarding.md` 配合,新手 declare 已裝工具)
|
|
17
|
-
- 後續任務涉及多源 governance(譬如 Notion DB Index + 本機真源 + Drive 參考檔三層持久化組合)
|
|
17
|
+
- 後續任務涉及多源 governance(譬如 Notion DB Index + 本機真源 + Google Drive 參考檔三層持久化組合)
|
|
18
18
|
|
|
19
19
|
## Discipline
|
|
20
20
|
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
|
|
25
25
|
| 儲存層 | 例子 | 加密方式 |
|
|
26
26
|
|--------|------|----------|
|
|
27
|
-
| Claude Desktop Extensions(one-click install) | Notion / Slack / Linear / Drive / Atlassian 等 | OS Keychain (macOS) / Credential Manager (Windows) auto-encrypt |
|
|
27
|
+
| Claude Desktop Extensions(one-click install) | Notion / Slack / Linear / Google Drive / Atlassian 等 | OS Keychain (macOS) / Credential Manager (Windows) auto-encrypt |
|
|
28
28
|
| Claude Code MCP config | `~/.config/claude-code/mcp.json` 等(manual setup) | 用戶自管(env var / OS secure storage) |
|
|
29
29
|
| 其他 AI tool(Codex / Gemini CLI 等)自身 config | tool-specific 路徑 | tool-specific 加密 |
|
|
30
30
|
|
|
@@ -38,7 +38,7 @@ Kit 嘅 `dev/` folder **任何檔都不 touch credential value**。三條硬性
|
|
|
38
38
|
|
|
39
39
|
#### 2.1 Connectors(Anthropic 官方 vetted)
|
|
40
40
|
|
|
41
|
-
Anthropic 官方 directory 嘅 ready-to-use MCP server(譬如 Notion / Slack / Linear / Drive / Atlassian / HubSpot / 等)。用戶經 Claude Desktop Settings → Extensions → Browse 一鍵安裝,credential 自動加密儲存喺 OS Keychain / Credential Manager。
|
|
41
|
+
Anthropic 官方 directory 嘅 ready-to-use MCP server(譬如 Notion / Slack / Linear / Google Drive / Atlassian / HubSpot / 等)。用戶經 Claude Desktop Settings → Extensions → Browse 一鍵安裝,credential 自動加密儲存喺 OS Keychain / Credential Manager。
|
|
42
42
|
|
|
43
43
|
紀律:
|
|
44
44
|
- AI 可使用 `mcp__<connector_name>__*` tool 直接 read / write
|
|
@@ -74,7 +74,7 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
74
74
|
|
|
75
75
|
### 3. Source-of-truth Architecture(多層持久化組合)
|
|
76
76
|
|
|
77
|
-
當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Drive 參考檔),AI 必先讀 `dev/PROJECT_INDEX.md` `## Installed Integrations` `### Source-of-truth Architecture` sub-table,識別每層分工:
|
|
77
|
+
當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Google Drive 參考檔),AI 必先讀 `dev/PROJECT_INDEX.md` `## Installed Integrations` `### Source-of-truth Architecture` sub-table,識別每層分工:
|
|
78
78
|
|
|
79
79
|
| Layer | 角色 | Write Direction |
|
|
80
80
|
|-------|------|-----------------|
|
|
@@ -162,7 +162,7 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
162
162
|
|
|
163
163
|
| Anti-pattern | 點解唔做 | 正確做法 |
|
|
164
164
|
|---|---|---|
|
|
165
|
-
| 用戶提到 Notion / Drive 即假設冇 Connector,直接列 paste packet | 違反 2026-05 reality:Connector ecosystem 已成熟,paste-only fallback 不應係 default | 先 read PROJECT_INDEX Installed Integrations;無 declaration 即 ask user about Integration status |
|
|
165
|
+
| 用戶提到 Notion / Google Drive 即假設冇 Connector,直接列 paste packet | 違反 2026-05 reality:Connector ecosystem 已成熟,paste-only fallback 不應係 default | 先 read PROJECT_INDEX Installed Integrations;無 declaration 即 ask user about Integration status |
|
|
166
166
|
| 將 credential value 寫入 PROJECT_INDEX / SESSION_HANDOFF / SESSION_LOG | 違反機密分離原則 + git history 永久保留泄露 | Credential location 只記指向(譬如「Claude Desktop Extensions」),永不記 value |
|
|
167
167
|
| 用戶喺對話貼 credential value,AI 直接 用 / 紀錄 | 違反 enforcement Rule 1 + 用戶可能誤泄露 | 即時 redact + warn 用戶 rotate token + 解釋機密分離原則 |
|
|
168
168
|
| Auth 失靈即嘗試自動 fix / re-auth flow | 越界(屬 AI tool + 用戶範圍)+ 可能引入 credential exposure | Surface 失敗 + 指向 AI 工具設定界面 + 唔自動 fix |
|
package/packs/onboarding.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
當用戶第一次使用 Agent Handoff Kit、沒有預設 expectation 或 prior context 時,本 pack 引導 AI 主動帶用戶完成第一個任務,不要求用戶先讀任何文檔。
|
|
8
8
|
|
|
9
|
-
本 pack 屬 transient pack —— 完成 onboarding session 後,AI 自動 unload 並由 regular scenario pack(coding / research / writing / knowledge / ...)接手。
|
|
9
|
+
本 pack 屬 transient pack —— 完成 onboarding session 後,AI 自動 unload 並由 regular scenario pack(coding / research / writing / knowledge / ...)接手。
|
|
10
10
|
|
|
11
11
|
## Load When
|
|
12
12
|
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
- 「教我用」/「teach me」/「教我點用」
|
|
17
17
|
- 「help me start」/「help me get started」
|
|
18
18
|
- 「first time」/「first-time」
|
|
19
|
-
-
|
|
19
|
+
- 「我剛安裝」/「I just installed」
|
|
20
20
|
- 「點開始」/「how do I start」
|
|
21
21
|
- 「show me how」
|
|
22
22
|
- 「getting started」
|
|
@@ -35,164 +35,168 @@
|
|
|
35
35
|
|
|
36
36
|
### 1. 不假設用戶已讀任何文檔
|
|
37
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
|
-
|
|
45
|
-
|
|
46
|
-
>
|
|
47
|
-
>
|
|
48
|
-
>
|
|
49
|
-
>
|
|
50
|
-
> **
|
|
51
|
-
> **
|
|
52
|
-
>
|
|
53
|
-
>
|
|
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),我會一步一步帶你做第一個任務。」
|
|
54
58
|
|
|
55
59
|
### 3. 5-step walk-through pattern
|
|
56
60
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
1.
|
|
60
|
-
2.
|
|
61
|
-
3.
|
|
62
|
-
4.
|
|
63
|
-
5.
|
|
61
|
+
用戶選定情境後,AI 用 5 步引導完成第一個小任務(全部情境共用同一節奏,內容按情境調整):
|
|
62
|
+
|
|
63
|
+
1. **確認項目背景**(資料夾 / 已有資料 / 是否已有版本紀錄 / 使用工具)
|
|
64
|
+
2. **用三點解釋這套工具如何幫到當前情境**
|
|
65
|
+
3. **詢問第一個具體任務範圍**(提供 4-6 個選項)
|
|
66
|
+
4. **建議一個 10-15 分鐘可完成的小任務**(先預演或先產出短內容)
|
|
67
|
+
5. **等用戶確認,再進入正式工作**
|
|
64
68
|
|
|
65
69
|
### 4. 每 step 解釋 + 等用戶 confirm
|
|
66
70
|
|
|
67
|
-
|
|
68
|
-
- 解釋緊做甚麼
|
|
69
|
-
- 等用戶「OK,下一步」/「我有問題」/「我想 skip 這 step」
|
|
70
|
-
- 若用戶有問題,先解答再繼續
|
|
71
|
+
不可以一次過跑完全部 5 步。每一步:
|
|
72
|
+
- 解釋緊做甚麼
|
|
73
|
+
- 等用戶「OK,下一步」/「我有問題」/「我想 skip 這 step」
|
|
74
|
+
- 若用戶有問題,先解答再繼續
|
|
71
75
|
|
|
72
76
|
### 5. 進入 actual task 前先 verify minimum context
|
|
73
77
|
|
|
74
|
-
|
|
78
|
+
用戶第一個任務應該很小:先預演、先產出短內容,或先做 10-15 分鐘可完成的範圍。先讓用戶感覺到節奏,再擴大。**不要**第一個任務就做大範圍改動或提交。
|
|
75
79
|
|
|
76
80
|
### 6. 完成 onboarding 後 transition
|
|
77
81
|
|
|
78
82
|
5-step walk-through 完成後:
|
|
79
|
-
-
|
|
80
|
-
- Unload onboarding pack(transient pack,不長期駐留)
|
|
81
|
-
- 進入 PLAN → READ → CHANGE → QC → PERSIST
|
|
82
|
-
- SESSION_HANDOFF Active Objective 記錄 first-task scope
|
|
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
|
|
83
87
|
|
|
84
88
|
## Application Scenario Library
|
|
85
89
|
|
|
86
|
-
每個 scenario 提供 5 step walk-through
|
|
87
|
-
|
|
88
|
-
### Scenario A. 寫 / 改代碼項目
|
|
89
|
-
|
|
90
|
-
**對應 guide.html Case A**(整理電腦下載目錄 + 公開發佈為 Git project)
|
|
91
|
-
|
|
92
|
-
#### Step A.1 — 確認 project context
|
|
90
|
+
每個 scenario 提供 5 step walk-through 的紀律 wording 加 1 句 AI sample wording 作為 anchor。AI 模型可 adapt 具體 wording,但必須保留 intent 與 tone。
|
|
93
91
|
|
|
94
|
-
|
|
95
|
-
- AI sample wording:
|
|
96
|
-
> 「請告訴我你的 project 在哪個目錄?如果還未建立,可以在電腦開新 folder 然後告訴我路徑。我會檢查 git status、讀 README / package.json 識別你的 stack(譬如 Python / Node.js / Rust 等),再為下一步建議方向。
|
|
97
|
-
>
|
|
98
|
-
> 順便:你 Claude Code / Claude Cowork 已裝邊啲 Connector / MCP / Plugin / Skill 我可以用?譬如 GitHub / Linear / Slack / Notion 之類嘅整合(適用於代碼項目嘅 issue tracking / collaboration)。如果未裝 / 唔確定,講「冇」/「未確認」即可,我會留位之後再加。」
|
|
92
|
+
### Scenario A. 建構系統 / 工具 / 平台 / 網站或應用
|
|
99
93
|
|
|
100
|
-
|
|
94
|
+
**對應 guide.html Case A**(整理電腦下載目錄 + 公開發佈為 Git project)
|
|
101
95
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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 或其他外部工具?如果已連接,我可以把用途記入項目索引;如果未連接或不確定,直接說「未確認」即可,之後仍可補上。」
|
|
105
103
|
|
|
106
|
-
#### Step A.
|
|
104
|
+
#### Step A.2 — 解釋這套工具如何配合
|
|
105
|
+
|
|
106
|
+
- 任務:AI 用 3 點解釋 Agent Handoff Kit 對建構系統 / 工具 / 平台 / 網站或應用的核心價值
|
|
107
|
+
- AI sample wording:
|
|
108
|
+
> 「Agent Handoff Kit 對建構系統、工具、平台、網站或應用有三個用處:(1) AI 跨對話記得項目的語言、規則、進度,下次開新對話仍接得回;(2) 危險指令(例如刪檔、重設 Git、強制推送)必須先講計劃,不會靜默執行;(3) 收工時自動寫下做過甚麼,方便日後追溯。」
|
|
107
109
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
110
|
+
#### Step A.3 — 詢問第一個任務範圍
|
|
111
|
+
|
|
112
|
+
- 任務:AI 提供 4-6 個具體任務選項讓用戶選
|
|
113
|
+
- AI sample wording:
|
|
114
|
+
> 「你的項目現在最想處理的是哪一類?(a) 修錯誤 / (b) 加新功能 / (c) 整理既有代碼 / (d) 加測試 / (e) 寫 README / (f) 做第一個 Git 提交?如果你想做的不在這幾項,直接告訴我即可。」
|
|
111
115
|
|
|
112
|
-
#### Step A.4 —
|
|
116
|
+
#### Step A.4 — 建議第一個小任務
|
|
117
|
+
|
|
118
|
+
- 任務:AI 將用戶選擇收窄至 10-15 分鐘可完成的小任務
|
|
119
|
+
- AI sample wording:
|
|
120
|
+
> 「你選『寫 README』。我建議第一個任務先做小:寫一個約 100 字的 README.md,包含一句項目簡介加三點功能。寫好後你核對、補自己的修改,最後再決定是否做 Git 提交。整個過程約 10 分鐘。可以嗎?」
|
|
113
121
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
- 任務:AI 確認用戶同意 + 載入對應 regular pack + 開始 work loop
|
|
121
|
-
- AI sample wording:
|
|
122
|
-
> 「Confirm 之後,我會載入 coding 模式 + writing 模式(README 屬 writing),開始 PLAN → READ → CHANGE → QC → PERSIST 五階段。準備好嗎?」
|
|
122
|
+
#### Step A.5 — 等用戶確認,再進入正式工作
|
|
123
|
+
|
|
124
|
+
- 任務:AI 確認用戶同意 + 載入對應日常工作規則 + 開始正式工作
|
|
125
|
+
- AI sample wording:
|
|
126
|
+
> 「你確認後,我會使用寫代碼與寫作兩套工作規則,先列計劃,再讀相關檔案,然後才改動。準備好嗎?」
|
|
123
127
|
|
|
124
128
|
### Scenario B. 整理研究資料 / 寫報告
|
|
125
129
|
|
|
126
130
|
**對應 guide.html Case B**(開咖啡店市場調查 + 寫完成報告)
|
|
127
131
|
|
|
128
|
-
#### Step B.1 —
|
|
132
|
+
#### Step B.1 — 確認項目背景
|
|
129
133
|
|
|
130
134
|
- AI sample wording:
|
|
131
135
|
> 「請告訴我三點:(1) 你的報告主題;(2) 已有資料在哪裡(Notion / Google Drive / 本地檔案);(3) 報告的讀者是誰(自己 / 客戶 / 合作伙伴 / 公開)。我會根據這三點建議分工。
|
|
132
136
|
>
|
|
133
|
-
>
|
|
137
|
+
> 順便:你是否已連接 Notion 或 Google Drive?如果有,我可以直接讀寫對應資料庫或資料夾;如果未連接,我會改為列出需要你手動同步的內容。如果不確定,說「未確認」即可。」
|
|
134
138
|
|
|
135
139
|
#### Step B.2 — 解釋 v2 如何 fit
|
|
136
140
|
|
|
137
141
|
- AI sample wording:
|
|
138
|
-
> 「
|
|
142
|
+
> 「Agent Handoff Kit 對研究類項目的核心價值有三點:(1) 真源紀律 —— 每條主張必須引用,事實與推論分開寫,AI 不會憑印象寫;(2) 外部來源治理 —— 如果你已連接 Notion / Google Drive 或其他外部工具,AI 可直接讀寫對應資料;未連接時,AI 會列出需要你手動同步的內容;(3) 跨對話接力 —— 你寫到一半收工,下次仍能接得上,包括引用紀律和項目登記表中的外部工具紀錄。」
|
|
139
143
|
|
|
140
144
|
#### Step B.3 — Ask user about 第一個 task scope
|
|
141
145
|
|
|
142
146
|
- AI sample wording:
|
|
143
147
|
> 「你想 first session 處理:(a) 列章節結構 / (b) 整理已有 reference 入 PROJECT_INDEX / (c) 寫摘要段 / (d) 寫第一個 sub-section / (e) 整體 review 已有 draft?」
|
|
144
148
|
|
|
145
|
-
#### Step B.4 —
|
|
149
|
+
#### Step B.4 — 建議第一個小任務
|
|
146
150
|
|
|
147
151
|
- AI sample wording:
|
|
148
|
-
>
|
|
152
|
+
> 「你選『列章節結構』。我建議第一個任務先做小:列 5-7 個章節標題,並為每章寫一句目標。寫好後你核對、調整。約 15 分鐘可以完成。可以嗎?」
|
|
149
153
|
|
|
150
154
|
#### Step B.5 — Ask user about confirm + 進入 work loop
|
|
151
155
|
|
|
152
156
|
- AI sample wording:
|
|
153
|
-
>
|
|
157
|
+
> 「你確認後,我會使用研究、寫作與知識整理規則。先列計劃,再讀資料,然後才寫內容。」
|
|
154
158
|
|
|
155
|
-
### Scenario C. 整理電腦檔案 / Notion / Drive 知識庫
|
|
159
|
+
### Scenario C. 整理電腦檔案 / Notion / Google Drive 知識庫
|
|
156
160
|
|
|
157
161
|
**對應 guide.html Case A 的檔案整理部分 + Case B 的 Notion reference 部分**
|
|
158
162
|
|
|
159
|
-
#### Step C.1 —
|
|
163
|
+
#### Step C.1 — 確認項目背景
|
|
160
164
|
|
|
161
165
|
- AI sample wording:
|
|
162
|
-
> 「請告訴我你想整理的是:(a)
|
|
166
|
+
> 「請告訴我你想整理的是:(a) 電腦資料夾(哪個位置)/ (b) Notion 資料庫(大概有哪些欄位)/ (c) Google Drive(哪個資料夾)/ (d) 多個來源混合(請描述)。
|
|
163
167
|
>
|
|
164
|
-
> 順便:如果涉及 Notion
|
|
168
|
+
> 順便:如果涉及 Notion、Google Drive、Dropbox 等外部來源,你是否已連接對應外部工具?如果有,我可以直接讀寫;如果沒有,我會列出手動同步步驟。如果不確定,說「未確認」即可。」
|
|
165
169
|
|
|
166
170
|
#### Step C.2 — 解釋 v2 如何 fit
|
|
167
171
|
|
|
168
172
|
- AI sample wording:
|
|
169
|
-
> 「
|
|
173
|
+
> 「Agent Handoff Kit 對知識庫整理有三個用處:(1) 分清正式來源、參考資料與草稿,避免 AI 把參考檔當成真源;(2) 如果你已連接 Notion / Google Drive 等外部工具,AI 可直接讀寫對應資料;未連接時,AI 會列出需要你手動同步的步驟;(3) 涉及大量檔案移動、重命名或刪除時,必須先列預演清單,等你確認才實際執行。」
|
|
170
174
|
|
|
171
175
|
#### Step C.3 — Ask user about 第一個 task scope
|
|
172
176
|
|
|
173
177
|
- AI sample wording:
|
|
174
178
|
> 「你想 first session 處理:(a) 掃描 + 分類已有檔案 / (b) 建立 Notion DB schema / (c) 設計 folder 結構 / (d) 寫整理 script + dry-run / (e) 對齊 Notion 與本地 reference?」
|
|
175
179
|
|
|
176
|
-
#### Step C.4 —
|
|
180
|
+
#### Step C.4 — 建議第一個小任務
|
|
177
181
|
|
|
178
182
|
- AI sample wording:
|
|
179
|
-
> 「你選『掃描 +
|
|
183
|
+
> 「你選『掃描 + 分類已有檔案』。我建議第一步先預演 100 個檔案,只列分類建議,由你確認,暫時不做實際移動。約 15 分鐘可完成。可以嗎?」
|
|
180
184
|
|
|
181
185
|
#### Step C.5 — Ask user about confirm + 進入 work loop
|
|
182
186
|
|
|
183
187
|
- AI sample wording:
|
|
184
|
-
>
|
|
188
|
+
> 「你確認後,我會使用知識整理與安全規則;凡涉及移動或重命名檔案,都先預演、再等你確認。」
|
|
185
189
|
|
|
186
190
|
### Scenario D. 學寫代碼(技術新手)
|
|
187
191
|
|
|
188
192
|
**不對應 specific guide case,屬 onboarding-only scenario**
|
|
189
193
|
|
|
190
|
-
#### Step D.1 —
|
|
194
|
+
#### Step D.1 — 確認學習背景
|
|
191
195
|
|
|
192
196
|
- AI sample wording:
|
|
193
|
-
>
|
|
197
|
+
> 「你想先學哪一類?(a) 簡單自動化小工具(例如整理檔案)/ (b) 一個網頁(HTML/CSS/JS)/ (c) 一個 Python 小工具 / (d) Git / GitHub 基本概念?告訴我你的興趣方向,我會安排第一個練習。
|
|
194
198
|
>
|
|
195
|
-
>
|
|
199
|
+
> 順便:你使用的 AI 工具是否已安裝任何 Plugin 或 Skill?初學階段不需要太多,但有 GitHub Connector 會方便日後操作。未安裝或不確定時,說「未確認」即可。」
|
|
196
200
|
|
|
197
201
|
#### Step D.2 — 解釋 v2 如何 fit
|
|
198
202
|
|
|
@@ -204,108 +208,108 @@
|
|
|
204
208
|
- AI sample wording:
|
|
205
209
|
> 「你選『簡單 script』?我建議第一個 script:『重命名 Downloads 目錄裡面所有 screenshot 加日期』—— 涉及 file system basics 加 Python basic syntax。你想試嗎?或者選其他方向。」
|
|
206
210
|
|
|
207
|
-
#### Step D.4 —
|
|
211
|
+
#### Step D.4 — 建議第一個小練習
|
|
208
212
|
|
|
209
213
|
- AI sample wording:
|
|
210
|
-
>
|
|
214
|
+
> 「第一個練習先做很小:寫一個約 5 行的 Python 小工具,先只顯示它準備怎樣重新命名檔案,不做實際改動。你核對後,才決定是否真的改名。整個過程我會逐句解釋每一行做甚麼。約 15 分鐘。可以嗎?」
|
|
211
215
|
|
|
212
216
|
#### Step D.5 — Ask user about confirm + 進入 work loop
|
|
213
217
|
|
|
214
218
|
- AI sample wording:
|
|
215
|
-
>
|
|
219
|
+
> 「你確認後,我會使用寫代碼與安全規則。我會用最簡單的說法解釋每個概念,不假設你已懂技術詞。」
|
|
216
220
|
|
|
217
221
|
### Scenario E. 其他 / 用戶自定義情景
|
|
218
222
|
|
|
219
|
-
|
|
223
|
+
如果用戶的情境不屬 A-D,AI 先詢問更多細節,再安排 5 步引導。
|
|
220
224
|
|
|
221
|
-
#### Step E.1 —
|
|
225
|
+
#### Step E.1 — 確認自訂情境
|
|
222
226
|
|
|
223
227
|
- AI sample wording:
|
|
224
|
-
> 「請告訴我四點:(1) 你想完成的目標(一句講完);(2) 已有資料 / 工具 / 限制;(3) 你的技術水平(零基礎 / 略有經驗 / 熟練);(4)
|
|
228
|
+
> 「請告訴我四點:(1) 你想完成的目標(一句講完);(2) 已有資料 / 工具 / 限制;(3) 你的技術水平(零基礎 / 略有經驗 / 熟練);(4) 第一輪對話想完成甚麼小成果。我會根據這四點安排第一個可落地的小任務。
|
|
225
229
|
>
|
|
226
|
-
>
|
|
230
|
+
> 順便:你使用的 AI 工具是否已連接任何 Connector、MCP、Plugin 或 Skill?任何已連接的工具都可以說;未連接或不確定時,說「未確認」即可。」
|
|
227
231
|
|
|
228
232
|
#### Step E.2 — 解釋 v2 如何 fit(custom)
|
|
229
233
|
|
|
230
|
-
- AI
|
|
234
|
+
- AI 根據用戶提供的四點,解釋 Agent Handoff Kit 如何幫到這個情境(保留「跨對話接力 + 安全護欄 + 自動維護」三項核心價值)
|
|
231
235
|
|
|
232
236
|
#### Step E.3 — Ask user about 第一個 task scope(custom)
|
|
233
237
|
|
|
234
|
-
- AI
|
|
238
|
+
- AI 提供對應用戶情境的選項
|
|
235
239
|
|
|
236
|
-
#### Step E.4 —
|
|
240
|
+
#### Step E.4 — 建議第一個小任務
|
|
237
241
|
|
|
238
|
-
- AI
|
|
242
|
+
- AI 將範圍收窄至 10-15 分鐘可完成的小任務
|
|
239
243
|
|
|
240
244
|
#### Step E.5 — Ask user about confirm + 進入 work loop(custom)
|
|
241
245
|
|
|
242
|
-
- AI
|
|
246
|
+
- AI 載入適合該情境的日常工作規則(可能組合多個規則)
|
|
243
247
|
|
|
244
248
|
### Scenario F. 審視已裝外部工具 + 設計治理
|
|
245
249
|
|
|
246
|
-
**對應 v0.3.0
|
|
250
|
+
**對應 v0.3.0 引入的 Integration governance 紀律**(不教 install,只教 declare + plan governance)
|
|
247
251
|
|
|
248
|
-
#### Step F.1 — Intake
|
|
252
|
+
#### Step F.1 — Intake:列你已安裝的外部工具
|
|
249
253
|
|
|
250
|
-
- 任務:AI
|
|
254
|
+
- 任務:AI 收集用戶已安裝的 Connector / MCP / Plugin / Skill,按四類分類
|
|
251
255
|
- AI sample wording:
|
|
252
|
-
>
|
|
256
|
+
> 「請告訴我你已安裝的外部工具,盡量分四類列:
|
|
253
257
|
>
|
|
254
|
-
> **(a) Anthropic 官方 Connector**(經 Claude Desktop Settings → Extensions 一鍵安裝)—— 譬如 Notion / Drive / Slack / Linear / Atlassian / HubSpot 等
|
|
255
|
-
> **(b) Community / Custom MCP server**(用戶自建或第三方提供)——
|
|
258
|
+
> **(a) Anthropic 官方 Connector**(經 Claude Desktop Settings → Extensions 一鍵安裝)—— 譬如 Notion / Google Drive / Slack / Linear / Atlassian / HubSpot 等
|
|
259
|
+
> **(b) Community / Custom MCP server**(用戶自建或第三方提供)—— 譬如從 GitHub repo 安裝的 server
|
|
256
260
|
> **(c) Claude Code Plugin**(經 `/plugin` command 安裝)—— 譬如 Anthropic-managed marketplace bundle
|
|
257
261
|
> **(d) Skill**(SKILL.md 直接安裝或 plugin 攜帶)—— 譬如 superpowers skill / 自製 skill
|
|
258
262
|
>
|
|
259
|
-
>
|
|
263
|
+
> 不記得類別時,只列名稱即可,我會幫你分類。如果未安裝任何外部工具,說『目前只用本機檔』即可。」
|
|
260
264
|
|
|
261
265
|
#### Step F.2 — 機密分離 brief
|
|
262
266
|
|
|
263
|
-
- 任務:AI 解釋 credential
|
|
267
|
+
- 任務:AI 解釋 credential 如何儲存 + Kit 不記 credential 值
|
|
264
268
|
- AI sample wording:
|
|
265
|
-
>
|
|
269
|
+
> 「我會幫你登記已安裝工具,但 **任何 API key / OAuth token / credential 都不會記錄在項目登記表**。
|
|
266
270
|
>
|
|
267
|
-
> Notion / Drive
|
|
271
|
+
> Notion / Google Drive 等 credential 通常在你安裝 Connector 時,已由 AI 工具加密儲存在系統安全儲存層(例如 macOS Keychain / Windows Credential Manager)—— 項目登記表只會記錄三件事:(1) 你用了哪個工具、(2) 用它做甚麼(例如 Notion 做資料索引)、(3) credential 由哪個工具管理(例如『Claude Desktop Extensions』),但不記錄 credential 值本身。
|
|
268
272
|
>
|
|
269
|
-
>
|
|
273
|
+
> 你不需要在對話貼出 token。如果不小心貼出,我會立即要求遮蔽並建議你更換 token。」
|
|
270
274
|
|
|
271
275
|
#### Step F.3 — Source-of-truth Architecture mapping
|
|
272
276
|
|
|
273
277
|
- 任務:AI 引導用戶設計多層持久化分工
|
|
274
278
|
- AI sample wording:
|
|
275
|
-
>
|
|
279
|
+
> 「對於每個工具,告訴我它在項目中的角色:
|
|
276
280
|
>
|
|
277
|
-
> - **真源(source of truth
|
|
278
|
-
> - **Index
|
|
279
|
-
> - **持久化參考檔(mirror)**:防本機 disk failure / 跨裝置 access(譬如 Drive folder 同步本機)
|
|
281
|
+
> - **真源(source of truth)**:原始可審計的 reference 內容(例如本機 `~/project/reference/` 存 PDF)
|
|
282
|
+
> - **Index**:登記每份真源檔的 metadata + 摘要 + tag(例如 Notion DB「Project Index」)
|
|
283
|
+
> - **持久化參考檔(mirror)**:防本機 disk failure / 跨裝置 access(譬如 Google Drive folder 同步本機)
|
|
280
284
|
> - **Working draft**:AI 寫 task output(譬如本機 `~/project/output/`)
|
|
281
285
|
>
|
|
282
|
-
>
|
|
286
|
+
> 一個工具可以承擔一個或多個角色。如果你第一次設計這套分工,我建議典型做法是:本機 = 真源 + 工作草稿、Notion = 索引、Google Drive = 備份鏡像。可以採用,也可以描述你自己的分工方式。」
|
|
283
287
|
|
|
284
288
|
#### Step F.4 — 寫入項目登記表
|
|
285
289
|
|
|
286
290
|
- 任務:AI 將用戶 declaration 寫入 PROJECT_INDEX `## Installed Integrations` + External Sources `via` column
|
|
287
291
|
- AI sample wording:
|
|
288
|
-
>
|
|
292
|
+
> 「我會將你已聲明的工具寫入項目登記表:
|
|
289
293
|
>
|
|
290
|
-
> - `## Installed Integrations` `### Connectors` 表填 Notion / Drive 等 entries(每個含 Project Usage / Access Scope / Specific Instance / Credential Location / Declared / Last Verified)
|
|
294
|
+
> - `## Installed Integrations` `### Connectors` 表填 Notion / Google Drive 等 entries(每個含 Project Usage / Access Scope / Specific Instance / Credential Location / Declared / Last Verified)
|
|
291
295
|
> - `## Installed Integrations` `### Source-of-truth Architecture` sub-table 填多層分工
|
|
292
|
-
> - 既有 `## External Sources`
|
|
296
|
+
> - 既有 `## External Sources` 表的 `via` column 引用對應 Connector entry
|
|
293
297
|
>
|
|
294
|
-
>
|
|
298
|
+
> 寫好之後我會給你核對。有錯可以即時修改。」
|
|
295
299
|
|
|
296
300
|
#### Step F.5 — Verify availability + 進入 actual task 或 standby
|
|
297
301
|
|
|
298
|
-
- 任務:AI
|
|
299
|
-
- AI sample wording:
|
|
300
|
-
>
|
|
302
|
+
- 任務:AI 做能力檢查,確認已聲明的外部工具在本次對話可用,然後接力下一個任務
|
|
303
|
+
- AI sample wording:
|
|
304
|
+
> 「聲明已寫好。我會檢查每個外部工具在本次對話是否可用:
|
|
301
305
|
>
|
|
302
306
|
> - Notion:試 `mcp__notion__search` 確認 DB accessible
|
|
303
|
-
> - Drive:試 `mcp__google-drive__list` 確認 folder accessible
|
|
307
|
+
> - Google Drive:試 `mcp__google-drive__list` 確認 folder accessible
|
|
304
308
|
> - 其他類似
|
|
305
309
|
>
|
|
306
|
-
>
|
|
310
|
+
> 檢查結果會寫入每行 `Last Verified` 欄位。如果任何外部工具不可用(例如目前 AI 工具未配對應 MCP),我會直接說明,讓你決定如何處理。
|
|
307
311
|
>
|
|
308
|
-
>
|
|
312
|
+
> 之後你想進入實際任務,就描述你想做甚麼(例如『開始整理參考資料』),我會使用對應的日常工作規則接力。如果未準備好,說『暫停』即可。」
|
|
309
313
|
|
|
310
314
|
## Cross-reference to guide.html
|
|
311
315
|
|
|
@@ -313,8 +317,8 @@
|
|
|
313
317
|
|
|
314
318
|
> 「如果想看完整 narrative example,可以開新 tab 看 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html 的 Case A/B/C:
|
|
315
319
|
>
|
|
316
|
-
> - Case A 對應 onboarding scenario A
|
|
317
|
-
> - Case B 對應 onboarding scenario B(整理研究資料 / 寫報告)加 scenario F 的多源 governance 設計(Notion DB Index + 本機真源 + Drive 持久化參考檔 三層 architecture)
|
|
320
|
+
> - Case A 對應 onboarding scenario A(建構系統 / 工具 / 平台 / 網站或應用)加 scenario C 的檔案整理部分
|
|
321
|
+
> - Case B 對應 onboarding scenario B(整理研究資料 / 寫報告)加 scenario F 的多源 governance 設計(Notion DB Index + 本機真源 + Google Drive 持久化參考檔 三層 architecture)
|
|
318
322
|
> - Case C 對應長期項目演進(適用於你項目運行到後期,跨多月時間軸;Day 30+ narrative 含 Integration declaration 演進)
|
|
319
323
|
>
|
|
320
324
|
> 本指南是參考對照,不需要先讀。」
|
package/packs/safety.md
CHANGED
|
@@ -16,7 +16,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
16
16
|
8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
|
|
17
17
|
9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
|
|
18
18
|
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks. Differentiate three layers of external access (R-030 Integration governance; see `dev/rules/integrations.md`):
|
|
19
|
-
(a) Anthropic-vetted Connectors (e.g. Notion / Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server behavior; still verify destructive write parameters before invocation.
|
|
19
|
+
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server behavior; still verify destructive write parameters before invocation.
|
|
20
20
|
(b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against project-local runbook if available.
|
|
21
21
|
(c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
|
|
22
22
|
11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
|