@adamchanadam/agent-handoff-kit 0.3.8 → 0.3.10

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.
@@ -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 |
@@ -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
- - 「我啱啱安裝」/「I just installed」
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 主動解釋必要 concept,但只解釋當前 walk-through 需要的最小範圍,不灌輸全部 v2 governance。
39
-
40
- ### 2. 主動 offer 而非被動 wait
41
-
42
- 用戶首段 message vague 或含 onboarding signal 時,AI 不立即 dive into task,而要主動 ask user about scenario。Sample opening wording:
43
-
44
- > 「我看到你是第一次使用 Agent Handoff Kit(或者想了解它如何幫你)。為了帶你最快上手,可以選擇以下其中一個情景,告訴我你最近想做的事:
45
- >
46
- > **A. 寫 / 改代碼項目** —— 你有一個 project 的 codebase 想長期維護
47
- > **B. 整理研究資料 / 寫報告** —— 你想做市場調查、寫 thesis、寫 newsletter
48
- > **C. 整理電腦檔案 / Notion / Drive 知識庫** —— 你想 organize 多個來源的資料
49
- > **D. 學寫代碼(我是技術新手)** —— 你想由零開始學寫小工具
50
- > **E. 其他** —— 描述你的情景,我會 customize 引導
51
- > **F. 我已裝咗一堆外部工具(Notion / Drive / Slack 等 Connector / MCP / Plugin),想 plan 點 systematically 用** —— 我帶你 declare + 設計治理
52
- >
53
- > 選擇其中一個(A/B/C/D/E/F),我會引導你做第一個任務。如果你想看完整 narrative example,可以開新 tab 看 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html 的 Case A/B/C。本指南是參考對照,不需要先讀。」
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
- 用戶選定 scenario 後,AI 跑 5 step walk-through(全部 scenario 共用同一 pattern,內容 customize per scenario):
58
-
59
- 1. **AI 確認 project context**(root / 已有資料 / git status / 工具 stack)
60
- 2. **AI 解釋 v2 如何 fit 這個 scenario**(高層 value statement,3 點 max)
61
- 3. **AI ask user about 第一個 concrete task scope**(提供 4-6 個 option)
62
- 4. **AI suggest minimum viable first task**(dry-run / minimal output,10-15 分鐘可完成)
63
- 5. **AI ask user about confirm + 進入 actual work loop**(載入對應 regular scenario pack)
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
- 不可以一次過跑全部 5 step。每 step:
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
- 用戶第一個任務應該 minimal scope(dry-run / 短輸出 / 10-15 分鐘可完成),讓用戶感覺到 v2 的 rhythm 才擴大 scope。**不要**第一個 task 就 commit 大改動。
78
+ 用戶第一個任務應該很小:先預演、先產出短內容,或先做 10-15 分鐘可完成的範圍。先讓用戶感覺到節奏,再擴大。**不要**第一個任務就做大範圍改動或提交。
75
79
 
76
80
  ### 6. 完成 onboarding 後 transition
77
81
 
78
82
  5-step walk-through 完成後:
79
- - 載入用戶 scenario 對應的 regular pack(coding / research / writing / knowledge / ...)
80
- - Unload onboarding pack(transient pack,不長期駐留)
81
- - 進入 PLAN → READ → CHANGE → QC → PERSIST 嘅 regular work loop
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 嘅紀律 wording 加 1 句 AI sample wording 作為 anchor。AI 模型可 adapt 具體 wording 但保留 intent 與 tone。
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
- - 任務:AI 確認 project root 存在 + 識別 stack + 檢查 git status
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
- #### Step A.2 — 解釋 v2 如何 fit
94
+ **對應 guide.html Case A**(整理電腦下載目錄 + 公開發佈為 Git project)
101
95
 
102
- - 任務:AI 用 3 點解釋 v2 對 coding 項目的核心 value
103
- - AI sample wording:
104
- > 「v2 對 coding 項目的核心 value 有三點:(1) AI 跨對話記得你 project 的 stack、規則、進度,下次任何 AI 工具開新對話都接得返;(2) 危險指令(rm -rf、git reset --hard、強制推送)必須先講計劃,不會 silent 執行;(3) 收工時自動寫低你做過甚麼,連 commit hash 都記錄,方便日後追溯。」
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.3 — Ask user about 第一個 task scope
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
- - 任務:AI 提供 4-6 個 concrete task option 讓用戶選
109
- - AI sample wording:
110
- > 「你的 project 現在最想處理的是:(a) bug fix / (b) 新功能 / (c) 重構既有代碼 / (d) 加測試 / (e) 寫 README / (f) Git initial commit?如果你想做的不在這幾項,告訴我即可,我會 customize。」
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 — Suggest minimum viable first task
116
+ #### Step A.4 — 建議第一個小任務
117
+
118
+ - 任務:AI 將用戶選擇收窄至 10-15 分鐘可完成的小任務
119
+ - AI sample wording:
120
+ > 「你選『寫 README』。我建議第一個任務先做小:寫一個約 100 字的 README.md,包含一句項目簡介加三點功能。寫好後你核對、補自己的修改,最後再決定是否做 Git 提交。整個過程約 10 分鐘。可以嗎?」
113
121
 
114
- - 任務:AI 將用戶選擇 narrow scope 至 10-15 分鐘可完成的 minimum viable task
115
- - AI sample wording:
116
- > 「你選『寫 README』。我建議第一個任務最 minimal scope:寫一個約 100 字的 README.md,含一句項目簡介加三點功能。寫好後你 review、加自己的修改,最後 git commit。整個過程約 10 分鐘。可以嗎?」
117
-
118
- #### Step A.5 — Ask user about confirm + 進入 work loop
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 — 確認 project context
132
+ #### Step B.1 — 確認項目背景
129
133
 
130
134
  - AI sample wording:
131
135
  > 「請告訴我三點:(1) 你的報告主題;(2) 已有資料在哪裡(Notion / Google Drive / 本地檔案);(3) 報告的讀者是誰(自己 / 客戶 / 合作伙伴 / 公開)。我會根據這三點建議分工。
132
136
  >
133
- > 順便:你已裝 Notion Connector / Drive Connector 嗎?如果有,我可以直接讀寫對應 DB / folder(譬如 Notion DB Index 記每份 reference 嘅 path + 摘要、Drive folder 儲持久化參考檔);未裝就 fallback 列 paste packet 由你親手做。如果未裝 / 唔確定,講「冇」/「未確認」即可。」
137
+ > 順便:你是否已連接 Notion 或 Google Drive?如果有,我可以直接讀寫對應資料庫或資料夾;如果未連接,我會改為列出需要你手動同步的內容。如果不確定,說「未確認」即可。」
134
138
 
135
139
  #### Step B.2 — 解釋 v2 如何 fit
136
140
 
137
141
  - AI sample wording:
138
- > 「v2 對研究類項目的核心 value 有三點:(1) 真源紀律 —— 每條 claim 必須引用,事實與推論分開寫,AI 不會憑印象寫;(2) 外部來源治理 —— 如果你已裝 Notion / Drive Connector(或者其他 MCP server),AI 直接讀寫對應 DB / folder;未裝就 fallback 列 paste packet 由你親手做,兩條路都受跨 session 紀律保護;(3) 跨 session 接力 —— 你寫到 50% 收工,下次接得返,包括引用紀律加項目登記表記低嘅 Integration 紀錄。」
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 — Suggest minimum viable first task
149
+ #### Step B.4 — 建議第一個小任務
146
150
 
147
151
  - AI sample wording:
148
- > 「你選『列章節結構』。我建議第一個任務 minimal scope:列 5-7 個 H2 chapter heading 加每章一句目標。寫好後你 review、調整。約 15 分鐘可以完成。可以嗎?」
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
- > 「Confirm 之後,我會載入 research 模式 + writing 模式 + knowledge 模式(涉外部來源時 trigger)。開始五階段 work loop。」
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 — 確認 project context
163
+ #### Step C.1 — 確認項目背景
160
164
 
161
165
  - AI sample wording:
162
- > 「請告訴我你想整理的是:(a) 電腦目錄(哪個 folder)/ (b) Notion DB(請描述 schema)/ (c) Google Drive(哪個 folder)/ (d) 多個來源混合(請描述)。
166
+ > 「請告訴我你想整理的是:(a) 電腦資料夾(哪個位置)/ (b) Notion 資料庫(大概有哪些欄位)/ (c) Google Drive(哪個資料夾)/ (d) 多個來源混合(請描述)。
163
167
  >
164
- > 順便:如果涉及 Notion / Drive / Dropbox 等外部來源,你已裝對應 Connector / MCP 嗎?如果有,我直接讀寫;未裝就 fallback paste packet。如果未裝 / 唔確定,講「冇」/「未確認」即可。」
168
+ > 順便:如果涉及 Notion、Google Drive、Dropbox 等外部來源,你是否已連接對應外部工具?如果有,我可以直接讀寫;如果沒有,我會列出手動同步步驟。如果不確定,說「未確認」即可。」
165
169
 
166
170
  #### Step C.2 — 解釋 v2 如何 fit
167
171
 
168
172
  - AI sample wording:
169
- > 「v2 對知識庫整理的核心 value 有三點:(1) 識別真源 vs reference vs draft —— PROJECT_INDEX 登記每份檔案的角色,避免 AI 將參考檔當真源;(2) Integration-aware 治理 —— 如果你已裝 Notion / Drive Connector,AI 直接讀寫對應 surface;未裝就 fallback 列 paste packet 步驟由你親手做;(3) 危險動作(大量檔案移動 / 重命名 / 刪除)必須 dry-run 列清單,等你 confirm 才實際執行。」
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 — Suggest minimum viable first task
180
+ #### Step C.4 — 建議第一個小任務
177
181
 
178
182
  - AI sample wording:
179
- > 「你選『掃描 + 分類已有檔案』。Minimal scope:先 dry-run 100 個檔案,列分類建議由你 confirm,先不做實際移動。約 15 分鐘可完成。可以嗎?」
183
+ > 「你選『掃描 + 分類已有檔案』。我建議第一步先預演 100 個檔案,只列分類建議,由你確認,暫時不做實際移動。約 15 分鐘可完成。可以嗎?」
180
184
 
181
185
  #### Step C.5 — Ask user about confirm + 進入 work loop
182
186
 
183
187
  - AI sample wording:
184
- > 「Confirm 之後,我會載入 knowledge 模式 + safety 模式(涉檔案移動)。」
188
+ > 「你確認後,我會使用知識整理與安全規則;凡涉及移動或重命名檔案,都先預演、再等你確認。」
185
189
 
186
190
  ### Scenario D. 學寫代碼(技術新手)
187
191
 
188
192
  **不對應 specific guide case,屬 onboarding-only scenario**
189
193
 
190
- #### Step D.1 — 確認 project context
194
+ #### Step D.1 — 確認學習背景
191
195
 
192
196
  - AI sample wording:
193
- > 「你想學寫的是:(a) 簡單 script(譬如自動 organize 檔案)/ (b) 一個 web page(HTML/CSS/JS)/ (c) 一個 Python 小工具 / (d) 學 git/GitHub 基本概念?告訴我你的興趣方向,我會 customize 第一個練習。
197
+ > 「你想先學哪一類?(a) 簡單自動化小工具(例如整理檔案)/ (b) 一個網頁(HTML/CSS/JS)/ (c) 一個 Python 小工具 / (d) Git / GitHub 基本概念?告訴我你的興趣方向,我會安排第一個練習。
194
198
  >
195
- > 順便:你 Claude Code 已裝邊啲 Plugin / Skill 我可以用?(初學階段唔需要太多,但有 GitHub Connector 之類會方便 git 操作。)未裝就講「冇」即可。」
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 — Suggest minimum viable first task
211
+ #### Step D.4 — 建議第一個小練習
208
212
 
209
213
  - AI sample wording:
210
- > 「First minimal scope:我寫一個 5 行 Python script,先做 dry-run(只 print 想做的 rename),你 review 後再做 actual rename。整個過程我會逐句解釋每一行做甚麼。約 15 分鐘。可以嗎?」
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
- > 「Confirm 之後,我會載入 coding 模式 + safety 模式。我會用最簡單的 wording 解釋每個概念,不假設你知道任何 jargon。」
219
+ > 「你確認後,我會使用寫代碼與安全規則。我會用最簡單的說法解釋每個概念,不假設你已懂技術詞。」
216
220
 
217
221
  ### Scenario E. 其他 / 用戶自定義情景
218
222
 
219
- 如果用戶的 use case 不屬 A-D,AI ask user about 更多細節後 customize 5-step walk-through。
223
+ 如果用戶的情境不屬 A-D,AI 先詢問更多細節,再安排 5 步引導。
220
224
 
221
- #### Step E.1 — 確認 project context(custom intake)
225
+ #### Step E.1 — 確認自訂情境
222
226
 
223
227
  - AI sample wording:
224
- > 「請告訴我四點:(1) 你想完成的目標(一句講完);(2) 已有資料 / 工具 / 限制;(3) 你的技術水平(零基礎 / 略有經驗 / 熟練);(4) 想 first session 達成的 minimal output。我會根據這四點 customize 一個 5-step walk-through,對應 v2 適合你的工作模式。
228
+ > 「請告訴我四點:(1) 你想完成的目標(一句講完);(2) 已有資料 / 工具 / 限制;(3) 你的技術水平(零基礎 / 略有經驗 / 熟練);(4) 第一輪對話想完成甚麼小成果。我會根據這四點安排第一個可落地的小任務。
225
229
  >
226
- > 順便:你 Claude Code / Claude Cowork 已裝邊啲 Connector / MCP / Plugin / Skill 我可以用?任何已裝整合都可以講;未裝 / 唔確定就講「冇」/「未確認」。」
230
+ > 順便:你使用的 AI 工具是否已連接任何 Connector、MCP、Plugin 或 Skill?任何已連接的工具都可以說;未連接或不確定時,說「未確認」即可。」
227
231
 
228
232
  #### Step E.2 — 解釋 v2 如何 fit(custom)
229
233
 
230
- - AI 根據用戶 intake 嘅四點,customize 解釋 v2 嘅 value statement(保留「跨對話接力 + 安全護欄 + 自動 maintain」三項 universal value)
234
+ - AI 根據用戶提供的四點,解釋 Agent Handoff Kit 如何幫到這個情境(保留「跨對話接力 + 安全護欄 + 自動維護」三項核心價值)
231
235
 
232
236
  #### Step E.3 — Ask user about 第一個 task scope(custom)
233
237
 
234
- - AI 提供 customized options 對應用戶嘅 use case
238
+ - AI 提供對應用戶情境的選項
235
239
 
236
- #### Step E.4 — Suggest minimum viable first task(custom)
240
+ #### Step E.4 — 建議第一個小任務
237
241
 
238
- - AI narrow scope 至 10-15 分鐘可完成 minimum viable task
242
+ - AI 將範圍收窄至 10-15 分鐘可完成的小任務
239
243
 
240
244
  #### Step E.5 — Ask user about confirm + 進入 work loop(custom)
241
245
 
242
- - AI 載入適合 user use case 嘅 regular pack(可能組合多個 pack)
246
+ - AI 載入適合該情境的日常工作規則(可能組合多個規則)
243
247
 
244
248
  ### Scenario F. 審視已裝外部工具 + 設計治理
245
249
 
246
- **對應 v0.3.0 引入嘅 Integration governance 紀律**(不教 install,只教 declare + plan governance)
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 收集用戶已裝嘅 Connector / MCP / Plugin / Skill,按四類分類
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**(用戶自建或第三方提供)—— 譬如 GitHub repo install 嘅 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
- > 唔記得邊類就只列名稱即可,我會幫你 categorize。如果未裝任何外部工具,講『目前只用本機檔』即可。」
263
+ > 不記得類別時,只列名稱即可,我會幫你分類。如果未安裝任何外部工具,說『目前只用本機檔』即可。」
260
264
 
261
265
  #### Step F.2 — 機密分離 brief
262
266
 
263
- - 任務:AI 解釋 credential 點儲存 + Kit 唔記 credential 值
267
+ - 任務:AI 解釋 credential 如何儲存 + Kit 不記 credential 值
264
268
  - AI sample wording:
265
- > 「我會幫你 declare 你已裝嘅工具,但 **任何 API key / OAuth token / credential 都不會喺項目登記表紀錄**。
269
+ > 「我會幫你登記已安裝工具,但 **任何 API key / OAuth token / credential 都不會記錄在項目登記表**。
266
270
  >
267
- > Notion / Drive 等嘅 credential 通常喺你裝 Connector 時已經自動加密儲存喺 OS 層 secure storage(譬如 Claude Desktop 嘅 macOS Keychain / Windows Credential Manager)—— 項目登記表只會記低三件事:(1) 你用咗邊個工具、(2) 用佢做乜(譬如 Notion 做 DB Index)、(3) credential 由邊個工具管(譬如『Claude Desktop Extensions』),但不記錄 credential 值本身。
271
+ > Notion / Google Drive 等 credential 通常在你安裝 Connector 時,已由 AI 工具加密儲存在系統安全儲存層(例如 macOS Keychain / Windows Credential Manager)—— 項目登記表只會記錄三件事:(1) 你用了哪個工具、(2) 用它做甚麼(例如 Notion 做資料索引)、(3) credential 由哪個工具管理(例如『Claude Desktop Extensions』),但不記錄 credential 值本身。
268
272
  >
269
- > 你都不需要喺對話貼出 token。貼咗我會即時提示你 redacted 同 rotate token 防再用。」
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)**:原始可審計嘅 reference 內容(譬如本機 `~/project/reference/` 存 PDF)
278
- > - **Index**:登記每份真源檔嘅 metadata + 摘要 + tag(譬如 Notion DB「Project 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
- > 一個工具可以承擔一個或多個角色。如果你 first time 設計呢套,我建議典型分工:本機 = 真源 + Working draft、Notion = Index、Drive = Mirror。可以採用,或者你描述自己想點分工。」
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
- > 「我會將你 declare 嘅工具寫入項目登記表:
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` 表嘅 `via` column 引用對應 Connector entry
296
+ > - 既有 `## External Sources` 表的 `via` column 引用對應 Connector entry
293
297
  >
294
- > 寫好之後我會 show 你 review。有錯隨時改。」
298
+ > 寫好之後我會給你核對。有錯可以即時修改。」
295
299
 
296
300
  #### Step F.5 — Verify availability + 進入 actual task 或 standby
297
301
 
298
- - 任務:AI 跑 capability probe,確認 declared Integration 喺本 session 可用,然後接力下一個任務
299
- - AI sample wording:
300
- > 「Declaration 寫好。我會 verify 每個 declared Integration 喺本 session 嘅可用性:
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
- > Probe 結果寫入每行 `Last Verified` cell。如果任何 Integration 唔可用(譬如 current AI tool 未配對應 MCP),我會 surface 出嚟由你決定點處理。
310
+ > 檢查結果會寫入每行 `Last Verified` 欄位。如果任何外部工具不可用(例如目前 AI 工具未配對應 MCP),我會直接說明,讓你決定如何處理。
307
311
  >
308
- > 之後你想入 actual task 就講你想做乜(譬如『開始整理 reference』),我會載入對應 regular pack 加 integrations pack 接力。如果未準備好,講『暫停』我就 standby。」
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(寫 / 改代碼項目)加 scenario C 的檔案整理部分
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.
@@ -13,7 +13,7 @@ After this core is loaded, read in order:
13
13
 
14
14
  Then classify the user's task and read only the required rule pack(s). State which pack(s) you loaded and why, using plain language so the user understands the working mode without needing to know pack names.
15
15
 
16
- Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, or contains onboarding signal keywords (e.g. "新手", "I'm new", "教我用", "help me start", "first time", "我啱啱安裝", "點開始", "show me how", "agent handoff kit 可幫我做甚麼", "我想做 [type] project", "點用", "能力"), or if the session is a fresh installation (HANDOFF Active Objective empty + Session count 1), load `dev/rules/onboarding.md` proactively BEFORE doing the regular task loop. The onboarding pack surfaces the AI's role and offers Scenario A-E selection (instead of immediately diving into task execution). Onboarding is a transient pack: after the user completes their first-task walk-through, unload it and load the regular scenario pack (coding / research / writing / knowledge / etc) for ongoing work.
16
+ Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, or contains onboarding signal keywords (e.g. "新手", "I'm new", "教我用", "help me start", "first time", "我剛安裝", "點開始", "show me how", "agent handoff kit 可幫我做甚麼", "我想做 [type] project", "點用", "能力"), or if the session is a fresh installation (HANDOFF Active Objective empty + Session count 1), load `dev/rules/onboarding.md` proactively BEFORE doing the regular task loop. The onboarding pack surfaces the AI's role and offers Scenario A-F selection (instead of immediately diving into task execution). Onboarding is a transient pack: after the user completes their first-task walk-through, unload it and load the regular scenario pack (coding / research / writing / knowledge / etc) for ongoing work.
17
17
 
18
18
  If the user did not paste the previous opening message but the current project root is clear, read `AGENTS.md` first as fallback entry, then use this read order. If the root is unclear or mismatched, stop and ask for the intended project root before reading or editing project state.
19
19
 
@@ -28,20 +28,20 @@ After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empt
28
28
  - If probe fails (current AI tool lacks the Connector / auth expired / network issue): print warning in the startup card (`⚠️ Boundary` line) noting which Integration is declared-but-unavailable + that this session will fallback to paste flow when that external surface is touched. Do not attempt to auto-fix auth or credential issues; surface to the user to handle via the AI tool's own settings interface.
29
29
  - Credential separation: AI must never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens). Credentials live in OS-level secure storage or AI-tool-specific config, never in `dev/*` files. Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) and redact + warn the user to rotate the token if accidentally pasted.
30
30
 
31
- After startup reads are complete, show a short startup card:
32
-
33
- ```text
34
- /\_/\ Agent Handoff Kit v<version>
35
- ( o.o ) continuity ready
36
- > ^ <
37
-
38
- 🔎 Handoff: loaded
39
- 📌 Objective: <current objective>
40
- ⚠️ Boundary: <important boundary or none>
41
- 🚀 Next: <next action>
42
- ```
43
-
44
- Keep the card short. Use the full product name, not an abbreviation. If the installed template or CLI version is unknown, write `version unverified` instead of guessing.
31
+ After startup reads are complete, show one short startup card. If onboarding is loaded, combine this card and the onboarding choice list into one first response. Do not print any standalone startup card before the onboarding rule has been read. Do not print a partial card. Do not print the cat banner twice. If you started drafting a card and then discovered onboarding applies, discard the draft and output only the final combined response.
32
+
33
+ ```text
34
+ /\_/\ Agent Handoff Kit v<version>
35
+ ( o.o ) continuity ready
36
+ > ^ <
37
+
38
+ 🔎 交接狀態:<loaded / new install / resumed>
39
+ 📌 目前目標:<current objective>
40
+ ⚠️ 注意事項:<important boundary or none>
41
+ 🚀 下一步:<next action>
42
+ ```
43
+
44
+ Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation. If the installed template or CLI version is unknown, write `version unverified` instead of guessing.
45
45
 
46
46
  ## 2. Work Loop
47
47
 
@@ -1,13 +1,13 @@
1
- # Claude Entry Bridge
1
+ # Claude Code Entry Bridge
2
2
 
3
- This file exists so Claude Code can find the Agent Handoff Kit startup path.
3
+ @AGENTS.md
4
4
 
5
- Authoritative operating rules remain in `AGENTS.md`. Do not duplicate or fork the rules here.
5
+ This file is a bridge only. Claude Code reads `CLAUDE.md` automatically, so this bridge imports `AGENTS.md`, which remains the single authoritative startup file for Agent Handoff Kit.
6
6
 
7
- At session startup:
7
+ Do not expand, summarize, replace, or "improve" this file during onboarding, setup, `/init`, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
8
 
9
- 1. Confirm the current root is the intended project root.
10
- 2. Read `AGENTS.md`.
11
- 3. Follow the startup read order in `AGENTS.md`.
9
+ If the user says `I just installed agent-handoff-kit`, `help me get started`, or similar first-use wording, do not run Claude Code `/init` and do not load an `init` skill. Agent Handoff Kit is already installed. Read `AGENTS.md`, load the onboarding rule when appropriate, and guide the user through the first task.
12
10
 
13
- If the current root does not match the intended project root, stop and ask the user to confirm the workspace before reading or editing project state.
11
+ Only edit this file when the user explicitly asks to edit `CLAUDE.md` itself, or when `agent-handoff-kit upgrade` reports a bridge conflict and asks for manual repair.
12
+
13
+ After loading this bridge, follow `AGENTS.md` and the startup read order defined there.
@@ -1,8 +1,12 @@
1
- # Gemini Entry Bridge
1
+ # Antigravity / Gemini Entry Bridge
2
2
 
3
- This file exists so Gemini CLI can find the Agent Handoff Kit startup path.
3
+ This file is a bridge only. It exists for Google Antigravity CLI, Gemini CLI during migration, and compatible tools that still read `GEMINI.md`.
4
4
 
5
- Authoritative operating rules remain in `AGENTS.md`. Do not duplicate or fork the rules here.
5
+ Authoritative operating rules remain in `AGENTS.md`.
6
+
7
+ Do not expand, summarize, replace, or "improve" this file during onboarding, setup, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
+
9
+ Antigravity CLI may read both `AGENTS.md` and `GEMINI.md` from the active workspace. If `AGENTS.md` has already been loaded, do not treat this bridge as a second rule source and do not repeat the same instructions.
6
10
 
7
11
  At session startup:
8
12