@adamchanadam/agent-handoff-kit 0.3.18 → 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.18` 候選準備。這是早期可用版本,仍在持續完善中。
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 agent 對話中貼上:
13
+ > 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
14
14
  >
15
+ > ```text
16
+ > Start Agent Handoff
15
17
  > ```
16
- > Work in <你的資料夾>. Read AGENTS.md first. Then 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 me the current state and your recommended next step.
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,7 @@ 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 對話貼固定開工句;AI 會打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
48
+ 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
41
49
 
42
50
  ### 適用工具
43
51
 
@@ -55,7 +63,7 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
55
63
 
56
64
  出現確認問題時,輸入 `yes`。
57
65
 
58
- 安裝完成後,終端機會顯示一段 `Work in ...` 文字。請特別留意:那一段不是給終端機的指令,而是要貼到 AI 對話。
66
+ 安裝完成後,終端機會顯示 AI 對話的下一步。請特別留意:`Start Agent Handoff`、中文「開工」或帶路徑啟動句都不是終端機指令,而是給 AI agent 的對話內容。
59
67
 
60
68
  可用的 AI 工具必須能讀寫此資料夾。不同工具對入口檔的支援可能不同;本工具會同時放置 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,讓常見工具能找到同一套開工路徑。Google 官方遷移文件說明,Antigravity CLI 會讀工作資料夾內的 `GEMINI.md` 和 `AGENTS.md`;因此 `AGENTS.md` 仍是唯一真源,`GEMINI.md` 只做橋接。
61
69
 
@@ -77,23 +85,25 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
77
85
 
78
86
  ### 二、開工
79
87
 
80
- 打開能讀寫本機專案資料夾的 AI agent,在新對話貼上安裝工具顯示的文字。
88
+ 打開能讀寫本機專案資料夾的 AI agent。
81
89
 
82
- **日常開工句(第一次安裝後與之後每次接力都用同一句)**:
90
+ 若 AI 已經在正確專案資料夾內,日常開工只需輸入:
83
91
 
84
92
  ```text
85
- Work in <你的專案資料夾>. Read AGENTS.md first. Then 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 me the current state and your recommended next step.
93
+ Start Agent Handoff
86
94
  ```
87
95
 
88
- 第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
96
+ 中文可說「開工」。
89
97
 
90
- 如果 AI 工具已經在正確專案資料夾內,而且會讀 `AGENTS.md`,日常也可以只說:
98
+ 若 AI 還未指向你的專案資料夾,才使用帶路徑啟動句:
91
99
 
92
100
  ```text
93
- Start Agent Handoff
101
+ Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
94
102
  ```
95
103
 
96
- 中文可說「開工」。若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
104
+ 第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
105
+
106
+ 若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
97
107
 
98
108
  然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
99
109
 
@@ -121,7 +131,7 @@ AI 應更新交接文件,並同步更新下一次開工提示副本:
121
131
  START_NEXT_SESSION_PROMPT.txt
122
132
  ```
123
133
 
124
- 這個檔案保存下一次真正要讀的開工內容。你下次仍只需貼同一條日常開工句,讓 AI 自己打開這個檔案。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
134
+ 這個檔案保存下一次真正要讀的開工內容。你下次仍只需說 `Start Agent Handoff` 或「開工」;若 AI 尚未指向專案資料夾,才使用帶路徑啟動句。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
125
135
 
126
136
  ## 檢查是否安裝完整
127
137
 
@@ -133,7 +143,7 @@ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
133
143
 
134
144
  看到「檢查通過」代表必要文件與基本結構通過檢查。若 `START_NEXT_SESSION_PROMPT.txt` 落後於 `dev/SESSION_HANDOFF.md`,`doctor` 只會提醒;這個便利副本應在收工 closeout 時由 AI 重新生成,不需要在 session 中途手動更新。
135
145
 
136
- `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,仍應把 `Work in ...` 起步句貼到能讀寫本機資料夾的 AI agent 對話,讓 AI 讀入口文件並說明目前狀態。
146
+ `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,應在能讀寫本機資料夾的 AI agent 對話輸入 `Start Agent Handoff` 或「開工」;若 AI 尚未指向資料夾,才使用帶路徑啟動句。
137
147
 
138
148
  ## 會安裝甚麼
139
149
 
@@ -272,7 +282,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
272
282
 
273
283
  ## 目前限制
274
284
 
275
- - 目前版本為 `v0.3.18` 候選準備;npm registry `latest` 在正式發布前仍以已發布版本為準。
285
+ - 目前版本為 `v0.3.19`,npm registry `latest` 已對齊此版本。
276
286
  - 這是早期可用版本,仍在持續完善中。
277
287
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
278
288
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -71,14 +71,14 @@ const requiredAnchors = [
71
71
  "wrap up",
72
72
  "handoff",
73
73
  "Reconcile `dev/SESSION_HANDOFF.md`",
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: copy and paste the whole block below",
79
- "State Reconciliation Check",
80
- "handoff lifecycle consistency",
81
- "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",
82
82
  "START_NEXT_SESSION_PROMPT.txt"
83
83
  ]
84
84
  },
@@ -98,12 +98,12 @@ const requiredAnchors = [
98
98
  "ack:section:sync-status",
99
99
  "ack:section:next-task-required-reading",
100
100
  "ack:section:state-reconciliation-check",
101
- "ack:section:next-session-opening-message",
102
- "ack:field:lifecycle-conflicts-resolved",
103
- "📋 Next session: copy and paste the whole block below",
104
- "```text",
105
- "Read in order:",
106
- "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"
107
107
  ]
108
108
  },
109
109
  {
@@ -114,12 +114,12 @@ const requiredAnchors = [
114
114
  "## Entry Template",
115
115
  "- **QC:**",
116
116
  "- **Sync:**",
117
- "- **Log maintenance:**",
118
- "### Next Session Opening Message",
119
- "📋 Next session: copy and paste the whole block below",
120
- "```text",
121
- "Read in order:",
122
- "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"
123
123
  ]
124
124
  },
125
125
  {
@@ -254,13 +254,13 @@ const schemaChecks = [
254
254
  ]
255
255
  },
256
256
  {
257
- target: "dev/SESSION_HANDOFF.md",
258
- label: "handoff opening message structure",
259
- checks: [
260
- includes("📋 Next session: copy and paste the whole block below"),
261
- includes("```text"),
262
- includes("Work in "),
263
- 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:"),
264
264
  includes("If this root does not match the expected project root")
265
265
  ]
266
266
  },
@@ -779,7 +779,7 @@ async function runDoctor(root, version, options = {}) {
779
779
 
780
780
  function getFirstUseNextStep(root, lastCloseout) {
781
781
  if (lastCloseout.date) return null;
782
- return `檢查已通過。下一步不要再留在終端機;打開能讀寫此資料夾的 AI agent,貼上:${startupBootstrapPrompt(root)}`;
782
+ return `檢查已通過。下一步不要再留在終端機;打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,輸入 Start Agent Handoff 或「開工」;若 AI 還未指向此資料夾,才貼:${startupPathBootstrapPrompt(root)}`;
783
783
  }
784
784
 
785
785
  // R-030 v0.3.0+: Credential leak prevention sweep. Scans dev/PROJECT_INDEX.md,
@@ -1830,10 +1830,10 @@ function printInstallSummary(version, command, mode, root, counts) {
1830
1830
  console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
1831
1831
  } else if (command === "upgrade") {
1832
1832
  console.log("🚀 下一步:留意下方升級後自動檢查;若全綠即升級完成。");
1833
- } else if (mode === "partial" || counts.skipped > 0) {
1834
- console.log("🚀 下一步:先看下方提示。若你原本已有 AGENTS.md 或其他 AI 規則,請先執行 upgrade --dry-run 補入口連接,再執行 doctor。");
1835
- } else {
1836
- 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。");
1837
1837
  }
1838
1838
  }
1839
1839
 
@@ -2043,17 +2043,21 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
2043
2043
  console.log("============================================================");
2044
2044
  return;
2045
2045
  }
2046
- console.log("------------------------------------------------------------");
2047
- console.log("⚠️ 下面這句不是終端機指令。");
2048
- console.log("📋 請打開能讀寫此資料夾的 AI agent,新增對話後貼上:");
2046
+ console.log("------------------------------------------------------------");
2047
+ console.log("⚠️ 下面這句不是終端機指令。");
2048
+ console.log("📋 請打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,新增對話後輸入:");
2049
2049
  console.log(" 例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。");
2050
2050
  console.log(" 普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。");
2051
2051
  console.log("------------------------------------------------------------");
2052
- console.log(startupBootstrapPrompt(root));
2052
+ console.log("Start Agent Handoff");
2053
+ console.log("或:開工");
2054
+ console.log("------------------------------------------------------------");
2055
+ console.log("若 AI 還未指向此資料夾,才貼以下帶路徑啟動句:");
2056
+ console.log(startupPathBootstrapPrompt(root));
2053
2057
  console.log("------------------------------------------------------------");
2054
2058
  console.log("");
2055
- console.log("🚀 AI 會先確認這個資料夾,讀取 START_NEXT_SESSION_PROMPT.txt。第一次安裝後,該檔案會觸發新手引導;收工後,該檔案會承載下一次接力狀態。");
2056
- console.log(" 之後若 AI 已在正確專案內,可說「Start Agent Handoff」/「開工」或「Wrap up Agent Handoff」/「收工」;「某某開工 / 某某收工」會先確認是否指本工具交接。");
2059
+ console.log("🚀 AI 會依 AGENTS.md 讀取 START_NEXT_SESSION_PROMPT.txt。第一次安裝後,該檔案會觸發新手引導;收工後,該檔案會承載下一次接力狀態。");
2060
+ console.log(" 收工可說「Wrap up Agent Handoff」/「收工」;「某某開工 / 某某收工」會先確認是否指本工具交接。");
2057
2061
  console.log("============================================================");
2058
2062
  }
2059
2063
 
@@ -2150,13 +2154,16 @@ Commands:
2150
2154
  🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2151
2155
 
2152
2156
  安裝之後:
2153
- 不要把顯示出來的 "Work in ..." 文字輸入終端機。
2154
- 請打開能讀寫此資料夾的 AI agent,新增對話後貼上那句起步句。
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.
2155
2163
  例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。
2156
2164
  普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。
2157
- AI 會讀取 START_NEXT_SESSION_PROMPT.txt;第一次安裝後該檔案會啟動新手引導,
2165
+ AI 會依 AGENTS.md 讀取 START_NEXT_SESSION_PROMPT.txt;第一次安裝後該檔案會啟動新手引導,
2158
2166
  收工後該檔案會承載下一次接力狀態。
2159
- AI 已在正確專案內時,可用「Start Agent Handoff」/「開工」開始接力,
2160
2167
  用「Wrap up Agent Handoff」/「收工」保存交接;「某某開工 / 某某收工」
2161
2168
  會先確認是否指本工具交接。
2162
2169
 
@@ -2179,6 +2186,6 @@ Commands:
2179
2186
  console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
2180
2187
  }
2181
2188
 
2182
- function startupBootstrapPrompt(root) {
2183
- return `Work in ${root}. Read AGENTS.md first. Then 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 me the current state and your recommended next step.`;
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.`;
2184
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.18",
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": {
@@ -98,7 +98,7 @@ At full closeout:
98
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.
99
99
  8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
100
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 stable bootstrap sentence for the next local-agent session in a fenced `text` code block: `Work in <project root>. Read AGENTS.md first. Then 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 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.
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.
102
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.
103
103
 
104
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):
@@ -132,11 +132,11 @@ Use this closeout card:
132
132
  ⚠️ Boundary: <important boundary or none>
133
133
  ```
134
134
 
135
- Immediately before the fenced opening message, write:
136
-
137
- ```text
138
- 📋 Next session: copy and paste the whole block below
139
- ```
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
+ ```
140
140
 
141
141
  Record only work actually performed in the current session. Do not copy old completed work forward as new work.
142
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.
@@ -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. User-facing closeout output may show the stable bootstrap sentence that tells the next agent to read this file; do not hand-write a separate stateful prompt in the final response.
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>.
@@ -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>.