@adamchanadam/agent-handoff-kit 0.3.17 → 0.3.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:目前版本為 `v0.3.17` 候選準備。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.19`,已正式發佈。這是早期可用版本,仍在持續完善中。
4
4
 
5
5
  ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
6
 
@@ -10,13 +10,21 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
10
10
 
11
11
  > 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
12
12
  >
13
- > 安裝完成後,在 AI 對話中講一句:
13
+ > 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
14
14
  >
15
+ > ```text
16
+ > Start Agent Handoff
15
17
  > ```
16
- > Work in <你的資料夾>. I just installed agent-handoff-kit. Help me get started.
18
+ >
19
+ > 中文可說「開工」。
20
+ >
21
+ > 只有當 AI 還未指向你的專案資料夾時,才使用帶路徑啟動句:
22
+ >
23
+ > ```text
24
+ > Work in <你的資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
17
25
  > ```
18
26
  >
19
- > AI 會自動引導你選擇使用情境(建構系統 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
27
+ > AI 會依 `AGENTS.md` 打開專案內的 `START_NEXT_SESSION_PROMPT.txt`。第一次安裝後,該檔會帶它載入新手引導;之後每次收工後,該檔會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
20
28
 
21
29
  想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想看實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 三個日常情境的完整流程示範。本 README 則保留安裝、日常使用與限制。
22
30
 
@@ -37,7 +45,13 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
37
45
 
38
46
  ![Agent Handoff Kit 新手流程](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-new-user-flow.png)
39
47
 
40
- 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在 AI 對話中說「教我用」或 `help me start`,完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
48
+ 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
49
+
50
+ ### 適用工具
51
+
52
+ Agent Handoff Kit 適合能讀寫本機專案資料夾的 agentic AI 工具,例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity,或其他具備本機工作區讀寫能力的工具。
53
+
54
+ 它不適合普通 web chat AI,例如沒有本機檔案讀寫能力的 ChatGPT、Claude、Gemini 網頁版。上載檔案或貼上交接內容不能取代本工具需要的本機讀寫能力;這類工具不能可靠維護專案內的交接文件。
41
55
 
42
56
  ### 一、安裝
43
57
 
@@ -49,9 +63,9 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
49
63
 
50
64
  出現確認問題時,輸入 `yes`。
51
65
 
52
- 安裝完成後,終端機會顯示一段 `Work in ...` 文字。請特別留意:那一段不是給終端機的指令,而是要貼到 AI 對話。
66
+ 安裝完成後,終端機會顯示 AI 對話的下一步。請特別留意:`Start Agent Handoff`、中文「開工」或帶路徑啟動句都不是終端機指令,而是給 AI agent 的對話內容。
53
67
 
54
- 可用的 AI 工具包括 Claude Code、Claude Cowork、OpenAI Codex、Google Antigravity,或任何能讀寫此資料夾的 AI 工具。不同工具對入口檔的支援可能不同;本工具會同時放置 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,讓常見工具能找到同一套開工路徑。Google 官方遷移文件說明,Antigravity CLI 會讀工作資料夾內的 `GEMINI.md` 和 `AGENTS.md`;因此 `AGENTS.md` 仍是唯一真源,`GEMINI.md` 只做橋接。
68
+ 可用的 AI 工具必須能讀寫此資料夾。不同工具對入口檔的支援可能不同;本工具會同時放置 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,讓常見工具能找到同一套開工路徑。Google 官方遷移文件說明,Antigravity CLI 會讀工作資料夾內的 `GEMINI.md` 和 `AGENTS.md`;因此 `AGENTS.md` 仍是唯一真源,`GEMINI.md` 只做橋接。
55
69
 
56
70
  > 補充:`--yes` 只是讓 npm 先取得這個工具,避免多問一次安裝確認。真正會建立項目文件的是 `init`;`doctor` 只檢查,不會安裝或改動你的項目文件。
57
71
 
@@ -71,22 +85,26 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
71
85
 
72
86
  ### 二、開工
73
87
 
74
- 打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。
88
+ 打開能讀寫本機專案資料夾的 AI agent。
75
89
 
76
- **第一次用(新手引導句)**:
90
+ 若 AI 已經在正確專案資料夾內,日常開工只需輸入:
77
91
 
78
92
  ```text
79
- Work in <你的專案資料夾>. I just installed agent-handoff-kit. Help me get started.
93
+ Start Agent Handoff
80
94
  ```
81
95
 
82
- AI 會自動載入新手引導,帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。
96
+ 中文可說「開工」。
83
97
 
84
- **之後熟悉 Handoff Kit 後,可改用更直接的開工句**:
98
+ 若 AI 還未指向你的專案資料夾,才使用帶路徑啟動句:
85
99
 
86
100
  ```text
87
- Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
101
+ Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
88
102
  ```
89
103
 
104
+ 第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
105
+
106
+ 若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
107
+
90
108
  然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
91
109
 
92
110
  ### 三、收工
@@ -100,17 +118,20 @@ Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing a
100
118
  也可以輸入:
101
119
 
102
120
  ```text
121
+ Wrap up Agent Handoff
103
122
  wrap up
104
123
  handoff
105
124
  ```
106
125
 
107
- AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字明確標示出來,方便完整複製。安裝後也會有一個更直覺的副本檔:
126
+ 若你說的是「某某收工」(例如餐廳收工、今天活動收工)這類帶其他上下文的話,AI 應先反問你是否要執行 Agent Handoff Kit 收工交接,而不是立即改寫交接文件。
127
+
128
+ AI 應更新交接文件,並同步更新下一次開工提示副本:
108
129
 
109
130
  ```text
110
131
  START_NEXT_SESSION_PROMPT.txt
111
132
  ```
112
133
 
113
- 這個檔案只是方便你複製下次開工提示;真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
134
+ 這個檔案保存下一次真正要讀的開工內容。你下次仍只需說 `Start Agent Handoff` 或「開工」;若 AI 尚未指向專案資料夾,才使用帶路徑啟動句。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
114
135
 
115
136
  ## 檢查是否安裝完整
116
137
 
@@ -122,7 +143,7 @@ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
122
143
 
123
144
  看到「檢查通過」代表必要文件與基本結構通過檢查。若 `START_NEXT_SESSION_PROMPT.txt` 落後於 `dev/SESSION_HANDOFF.md`,`doctor` 只會提醒;這個便利副本應在收工 closeout 時由 AI 重新生成,不需要在 session 中途手動更新。
124
145
 
125
- `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,仍應把 `Work in ...` 起步句貼到 AI 對話,讓 AI 讀入口文件並說明目前狀態。
146
+ `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,應在能讀寫本機資料夾的 AI agent 對話輸入 `Start Agent Handoff` 或「開工」;若 AI 尚未指向資料夾,才使用帶路徑啟動句。
126
147
 
127
148
  ## 會安裝甚麼
128
149
 
@@ -147,7 +168,7 @@ dev/rules/*.md
147
168
  | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
148
169
  | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
149
170
  | `GEMINI.md` | 讓 Google Antigravity CLI、Gemini CLI 遷移期或相容入口工具找到同一套入口。Antigravity CLI 會讀 `AGENTS.md` 與 `GEMINI.md`,所以此檔只做橋接,不另寫一套規則。 |
150
- | `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由交接文件自動產生。 |
171
+ | `START_NEXT_SESSION_PROMPT.txt` | 下一次開工時由 AI 讀取的提示副本;初次安裝時放新手引導,收工後由交接文件自動產生。 |
151
172
  | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
152
173
  | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。長期使用後舊條目會自動整理入封存資料夾,主檔保持簡短。日常使用不需要打開本檔,做審計或追溯時才看。 |
153
174
  | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
@@ -261,7 +282,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
261
282
 
262
283
  ## 目前限制
263
284
 
264
- - 目前版本為 `v0.3.17` 候選準備;npm 已正式發佈版本仍以 registry `latest` 為準。
285
+ - 目前版本為 `v0.3.19`,npm registry `latest` 已對齊此版本。
265
286
  - 這是早期可用版本,仍在持續完善中。
266
287
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
267
288
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -47,9 +47,11 @@ const requiredAnchors = [
47
47
  "dev/SESSION_LOG.md",
48
48
  "dev/PROJECT_INDEX.md",
49
49
  "dev/RULE_PACKS.md",
50
- "Agent Handoff Kit v<version>",
51
- "continuity ready",
52
- "Reachable is not the same as ingested",
50
+ "Agent Handoff Kit v<version>",
51
+ "continuity ready",
52
+ "Start Agent Handoff",
53
+ "Ambiguous startup phrases",
54
+ "Reachable is not the same as ingested",
53
55
  "Do not treat unread sources as absent",
54
56
  // R-030 v0.3.0+: forces managed-core merge on v0.2.x → v0.3.0 upgrade to propagate
55
57
  // startup availability probe + integrations pack reference + credential separation discipline.
@@ -63,18 +65,20 @@ const requiredAnchors = [
63
65
  label: "closeout intent and full handoff",
64
66
  snippets: [
65
67
  "Detect end-of-session or handoff intent",
66
- "收工",
67
- "wrap up",
68
+ "收工",
69
+ "Wrap up Agent Handoff",
70
+ "Ambiguous closeout phrases",
71
+ "wrap up",
68
72
  "handoff",
69
73
  "Reconcile `dev/SESSION_HANDOFF.md`",
70
- "Add a concise entry to `dev/SESSION_LOG.md`",
71
- "next-session opening message",
72
- "fenced `text` code block",
73
- "handoff saved",
74
- "📋 Next session: copy and paste the whole block below",
75
- "State Reconciliation Check",
76
- "handoff lifecycle consistency",
77
- "Do not append a new state snapshot",
74
+ "Add a concise entry to `dev/SESSION_LOG.md`",
75
+ "next-session opening message",
76
+ "fenced `text` code block",
77
+ "handoff saved",
78
+ "next-session startup entry",
79
+ "State Reconciliation Check",
80
+ "handoff lifecycle consistency",
81
+ "Do not append a new state snapshot",
78
82
  "START_NEXT_SESSION_PROMPT.txt"
79
83
  ]
80
84
  },
@@ -94,12 +98,12 @@ const requiredAnchors = [
94
98
  "ack:section:sync-status",
95
99
  "ack:section:next-task-required-reading",
96
100
  "ack:section:state-reconciliation-check",
97
- "ack:section:next-session-opening-message",
98
- "ack:field:lifecycle-conflicts-resolved",
99
- "📋 Next session: copy and paste the whole block below",
100
- "```text",
101
- "Read in order:",
102
- "dev/DOC_SYNC_REGISTRY.md"
101
+ "ack:section:next-session-opening-message",
102
+ "ack:field:lifecycle-conflicts-resolved",
103
+ "📋 Next session:",
104
+ "```text",
105
+ "Read in order:",
106
+ "dev/DOC_SYNC_REGISTRY.md"
103
107
  ]
104
108
  },
105
109
  {
@@ -110,12 +114,12 @@ const requiredAnchors = [
110
114
  "## Entry Template",
111
115
  "- **QC:**",
112
116
  "- **Sync:**",
113
- "- **Log maintenance:**",
114
- "### Next Session Opening Message",
115
- "📋 Next session: copy and paste the whole block below",
116
- "```text",
117
- "Read in order:",
118
- "dev/DOC_SYNC_REGISTRY.md"
117
+ "- **Log maintenance:**",
118
+ "### Next Session Opening Message",
119
+ "📋 Next session:",
120
+ "```text",
121
+ "Read in order:",
122
+ "dev/DOC_SYNC_REGISTRY.md"
119
123
  ]
120
124
  },
121
125
  {
@@ -250,13 +254,13 @@ const schemaChecks = [
250
254
  ]
251
255
  },
252
256
  {
253
- target: "dev/SESSION_HANDOFF.md",
254
- label: "handoff opening message structure",
255
- checks: [
256
- includes("📋 Next session: copy and paste the whole block below"),
257
- includes("```text"),
258
- includes("Work in "),
259
- includes("Read in order:"),
257
+ target: "dev/SESSION_HANDOFF.md",
258
+ label: "handoff opening message structure",
259
+ checks: [
260
+ includes("📋 Next session:"),
261
+ includes("```text"),
262
+ includes("Work in "),
263
+ includes("Read in order:"),
260
264
  includes("If this root does not match the expected project root")
261
265
  ]
262
266
  },
@@ -773,10 +777,10 @@ async function runDoctor(root, version, options = {}) {
773
777
  return overallHealthy ? "passed" : "failed";
774
778
  }
775
779
 
776
- function getFirstUseNextStep(root, lastCloseout) {
777
- if (lastCloseout.date) return null;
778
- return `檢查已通過。下一步不要再留在終端機;打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,或任何能讀寫此資料夾的 AI 工具,貼上:Work in ${root}. I just installed agent-handoff-kit. Help me get started.`;
779
- }
780
+ function getFirstUseNextStep(root, lastCloseout) {
781
+ if (lastCloseout.date) return null;
782
+ return `檢查已通過。下一步不要再留在終端機;打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,輸入 Start Agent Handoff 或「開工」;若 AI 還未指向此資料夾,才貼:${startupPathBootstrapPrompt(root)}`;
783
+ }
780
784
 
781
785
  // R-030 v0.3.0+: Credential leak prevention sweep. Scans dev/PROJECT_INDEX.md,
782
786
  // dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md for common credential prefix patterns.
@@ -1826,10 +1830,10 @@ function printInstallSummary(version, command, mode, root, counts) {
1826
1830
  console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
1827
1831
  } else if (command === "upgrade") {
1828
1832
  console.log("🚀 下一步:留意下方升級後自動檢查;若全綠即升級完成。");
1829
- } else if (mode === "partial" || counts.skipped > 0) {
1830
- console.log("🚀 下一步:先看下方提示。若你原本已有 AGENTS.md 或其他 AI 規則,請先執行 upgrade --dry-run 補入口連接,再執行 doctor。");
1831
- } else {
1832
- console.log("🚀 下一步:不用再留在終端機。打開 AI 工具,貼下方起步句。");
1833
+ } else if (mode === "partial" || counts.skipped > 0) {
1834
+ console.log("🚀 下一步:先看下方提示。若你原本已有 AGENTS.md 或其他 AI 規則,請先執行 upgrade --dry-run 補入口連接,再執行 doctor。");
1835
+ } else {
1836
+ console.log("🚀 下一步:不用再留在終端機。打開 AI 工具,啟動 Agent Handoff。");
1833
1837
  }
1834
1838
  }
1835
1839
 
@@ -2039,17 +2043,23 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
2039
2043
  console.log("============================================================");
2040
2044
  return;
2041
2045
  }
2042
- console.log("------------------------------------------------------------");
2043
- console.log("⚠️ 下面這句不是終端機指令。");
2044
- console.log("📋 請打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,");
2045
- console.log(" 或任何能讀寫此資料夾的 AI 工具,新增對話後貼上:");
2046
- console.log("------------------------------------------------------------");
2047
- console.log(`Work in ${root}. I just installed agent-handoff-kit. Help me get started.`);
2048
- console.log("------------------------------------------------------------");
2049
- console.log("");
2050
- console.log("🚀 AI 會先確認這個資料夾,然後帶你選擇第一個任務情景:建構系統 / 工具 / 平台 / 網站或應用、研究報告、知識庫整理、學寫代碼,或其他。");
2051
- console.log("============================================================");
2052
- }
2046
+ console.log("------------------------------------------------------------");
2047
+ console.log("⚠️ 下面這句不是終端機指令。");
2048
+ console.log("📋 請打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,新增對話後輸入:");
2049
+ console.log(" 例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。");
2050
+ console.log(" 普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。");
2051
+ console.log("------------------------------------------------------------");
2052
+ console.log("Start Agent Handoff");
2053
+ console.log("或:開工");
2054
+ console.log("------------------------------------------------------------");
2055
+ console.log("若 AI 還未指向此資料夾,才貼以下帶路徑啟動句:");
2056
+ console.log(startupPathBootstrapPrompt(root));
2057
+ console.log("------------------------------------------------------------");
2058
+ console.log("");
2059
+ console.log("🚀 AI 會依 AGENTS.md 讀取 START_NEXT_SESSION_PROMPT.txt。第一次安裝後,該檔案會觸發新手引導;收工後,該檔案會承載下一次接力狀態。");
2060
+ console.log(" 收工可說「Wrap up Agent Handoff」/「收工」;「某某開工 / 某某收工」會先確認是否指本工具交接。");
2061
+ console.log("============================================================");
2062
+ }
2053
2063
 
2054
2064
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
2055
2065
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
@@ -2143,14 +2153,21 @@ Commands:
2143
2153
  🔄 已裝過:先用 upgrade --dry-run 預演,再決定是否正式升級。
2144
2154
  🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2145
2155
 
2146
- 安裝之後:
2147
- 不要把顯示出來的 "Work in ..." 文字輸入終端機。
2148
- 請打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,
2149
- 或任何能讀寫此資料夾的 AI 工具,新增對話後貼上那句起步句。
2150
- 這句會啟動新手引導;AI 會先帶你選擇情境,
2151
- 再一步一步整理第一個任務。
2152
-
2153
- 終端機範例:
2156
+ 安裝之後:
2157
+ 不要把顯示出來的 Start Agent Handoff 或 "Work in ..." 文字輸入終端機。
2158
+ 請打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,新增對話後輸入:
2159
+ Start Agent Handoff
2160
+ 或:開工
2161
+ 若 AI 還未指向此資料夾,才貼帶路徑啟動句:
2162
+ Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
2163
+ 例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。
2164
+ 普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。
2165
+ AI 會依 AGENTS.md 讀取 START_NEXT_SESSION_PROMPT.txt;第一次安裝後該檔案會啟動新手引導,
2166
+ 收工後該檔案會承載下一次接力狀態。
2167
+ 用「Wrap up Agent Handoff」/「收工」保存交接;「某某開工 / 某某收工」
2168
+ 會先確認是否指本工具交接。
2169
+
2170
+ 終端機範例:
2154
2171
  npx --yes @adamchanadam/agent-handoff-kit@latest init
2155
2172
  npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2156
2173
  npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
@@ -2165,6 +2182,10 @@ Commands:
2165
2182
  "Need to install" 提示。真正會建立項目文件的是 init;doctor 只檢查。
2166
2183
  `);
2167
2184
  console.log(`📦 版本:v${version}`);
2168
- console.log(`🛠️ 模式:help ready`);
2169
- console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
2170
- }
2185
+ console.log(`🛠️ 模式:help ready`);
2186
+ console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
2187
+ }
2188
+
2189
+ function startupPathBootstrapPrompt(root) {
2190
+ return `Work in ${root}. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.`;
2191
+ }
@@ -3,7 +3,10 @@ import path from "node:path";
3
3
 
4
4
  const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
5
5
  const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
6
- const copyMarker = "📋 Next session: copy and paste the whole block below";
6
+ const openingContentMarkers = [
7
+ "📋 Next session: agent-managed startup content below",
8
+ "📋 Next session: copy and paste the whole block below"
9
+ ];
7
10
 
8
11
  export function assessPromptMirrorRoot(root) {
9
12
  const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
@@ -72,10 +75,11 @@ export function extractOpeningMessage(text) {
72
75
  if (sectionStart < 0) return null;
73
76
 
74
77
  const sectionText = text.slice(sectionStart);
75
- const markerIndex = sectionText.indexOf(copyMarker);
76
- if (markerIndex < 0) return null;
78
+ const marker = openingContentMarkers.find((candidate) => sectionText.includes(candidate));
79
+ if (!marker) return null;
77
80
 
78
- const afterMarker = sectionText.slice(markerIndex + copyMarker.length);
81
+ const markerIndex = sectionText.indexOf(marker);
82
+ const afterMarker = sectionText.slice(markerIndex + marker.length);
79
83
  const fenceMatch = /```text[^\r\n]*(?:\r\n?|\n)([\s\S]*?)(?:\r\n?|\n)```/.exec(afterMarker);
80
84
  if (!fenceMatch) return null;
81
85
  return fenceMatch[1];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.17",
3
+ "version": "0.3.19",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -15,9 +15,13 @@ Then classify the user's task and read only the required rule pack(s). State whi
15
15
 
16
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
- 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
-
20
- If a required file is missing, create the smallest useful version only after confirming the target project root.
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
+
20
+ Detect clear startup / handoff-start intent in natural language, such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff". When that intent is clear and the current project root is clear, open `START_NEXT_SESSION_PROMPT.txt` and follow the opening message inside. If `START_NEXT_SESSION_PROMPT.txt` is missing or seems stale, read `dev/SESSION_HANDOFF.md` instead. Before changing anything, tell the user the current state and your recommended next step.
21
+
22
+ Ambiguous startup phrases need one concise confirmation question before treating them as Agent Handoff Kit startup. In particular, if the user says "<something> 開工", "<something> start", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to start Agent Handoff Kit continuity for this project.
23
+
24
+ If a required file is missing, create the smallest useful version only after confirming the target project root.
21
25
 
22
26
  Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent.
23
27
 
@@ -79,7 +83,9 @@ Do not claim completion without evidence from checks, inspection, or a clear exp
79
83
 
80
84
  ## 4. Closeout And Handoff
81
85
 
82
- Detect end-of-session or handoff intent in natural language, such as "收工", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
86
+ Detect end-of-session or handoff intent in natural language, such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
87
+
88
+ Ambiguous closeout phrases need one concise confirmation question before full closeout. In particular, if the user says "<something> 收工", "<something> close", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to wrap up Agent Handoff Kit and write the project handoff.
83
89
 
84
90
  At full closeout:
85
91
 
@@ -91,8 +97,8 @@ At full closeout:
91
97
  6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, whether completed / pending / risk / opening-message lifecycle conflicts were resolved, and whether the opening message matches current state. In the same step, run the handoff lifecycle consistency check before declaring handoff ready: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.
92
98
  7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
93
99
  8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
94
- 9. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
95
- 10. Show a short closeout card, then provide the copy-paste-ready next-session opening message by pasting the read-back `START_NEXT_SESSION_PROMPT.txt` content inside a fenced `text` code block. Do not compose a separate final-response prompt; the final response is a display of the persisted prompt, not a third source of truth.
100
+ 9. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is the stateful startup prompt that the next local agent must read. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
101
+ 10. Show a short closeout card, then provide the next-session startup entry in a fenced `text` code block. Primary entry, when the next local AI agent is already opened at this project root: `Start Agent Handoff` / `開工`. Fallback entry, when the next AI agent is not yet pointed at the project root: `Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
96
102
  11. Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline). After prepending the new closeout entry, count `## YYYY-MM-DD` H2 entries in `dev/SESSION_LOG.md`. Any entry now at position N ≥ 11 (oldest end) must be moved into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved. Maintain `dev/SESSION_LOG_archive/INDEX.md` (master index of all archive batches; create on first archive). Entries at N=4–10 whose core facts are already absorbed into HANDOFF / PROJECT_INDEX / requirements / decision records collapse to a short-index line using structural anchors, not line numbers. Entries with unique narrative not yet absorbed must first be ported into the relevant durable source, then collapsed. This is mandatory; do not skip. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
97
103
 
98
104
  12. Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline. Each closeout must run the following checks with equal mechanical rigor as the SESSION_LOG N-rule (step 11):
@@ -126,11 +132,11 @@ Use this closeout card:
126
132
  ⚠️ Boundary: <important boundary or none>
127
133
  ```
128
134
 
129
- Immediately before the fenced opening message, write:
130
-
131
- ```text
132
- 📋 Next session: copy and paste the whole block below
133
- ```
135
+ In `dev/SESSION_HANDOFF.md`, immediately before the fenced `Next Session Opening Message` content, write:
136
+
137
+ ```text
138
+ 📋 Next session: agent-managed startup content below
139
+ ```
134
140
 
135
141
  Record only work actually performed in the current session. Do not copy old completed work forward as new work.
136
142
  `dev/SESSION_HANDOFF.md` carries continuity. `dev/SESSION_LOG.md` carries recent evidence. Archive old detail only when needed; do not create an archive directory by default.
@@ -21,7 +21,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
21
21
  | `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
22
22
  | `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
23
23
  | `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
24
- | `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
24
+ | `START_NEXT_SESSION_PROMPT.txt` | auto-generated stateful startup prompt for the next local-agent session; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup |
25
25
  | `src/` | application source | coding task |
26
26
  | `tests/` | tests | coding/QC |
27
27
  | `docs/` | user or product docs | doc/public behavior change |
@@ -123,7 +123,7 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
123
123
  | UI behavior | TBD | build + visual/manual check |
124
124
  | Data model | TBD | migration/checks |
125
125
  | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
126
- | Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current + prompt convenience copy regenerated from handoff at closeout |
126
+ | Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current + prompt file regenerated from handoff at closeout |
127
127
 
128
128
  ## External Services
129
129
 
@@ -133,9 +133,9 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
133
133
  <!-- ack:section:next-session-opening-message -->
134
134
  ## Next Session Opening Message
135
135
 
136
- This fenced block is the authoritative startup prompt. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy.
137
-
138
- 📋 Next session: copy and paste the whole block below
136
+ This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
137
+
138
+ 📋 Next session: agent-managed startup content below
139
139
 
140
140
  ```text
141
141
  Work in <absolute project root>.
@@ -149,7 +149,9 @@ Read in order:
149
149
 
150
150
  Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
151
151
 
152
- If this root does not match the expected project root, stop and ask for confirmation.
153
-
154
- After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.
155
- ```
152
+ If this root does not match the expected project root, stop and ask for confirmation.
153
+
154
+ This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
155
+
156
+ Before changing anything, tell me the current state and your recommended next step.
157
+ ```
@@ -27,7 +27,7 @@ Before closeout, check whether older log detail should be kept, summarized, or a
27
27
 
28
28
  ### Next Session Opening Message
29
29
 
30
- 📋 Next session: copy and paste the whole block below
30
+ 📋 Next session: agent-managed startup content below
31
31
 
32
32
  ```text
33
33
  Work in <absolute project root>.
@@ -43,6 +43,8 @@ Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
43
43
 
44
44
  If this root does not match the expected project root, stop and ask for confirmation.
45
45
 
46
- After reading, summarize current objective, confirmed decisions, pending work, risks, and the next recommended action.
46
+ This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
47
+
48
+ Before changing anything, tell me the current state and your recommended next step.
47
49
  ```
48
50
  ````
@@ -11,4 +11,6 @@ Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
11
11
 
12
12
  If this root does not match the expected project root, stop and ask for confirmation.
13
13
 
14
- After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.
14
+ This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
15
+
16
+ Before changing anything, tell me the current state and your recommended next step.