@adamchanadam/agent-handoff-kit 0.3.17 → 0.3.18
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 +28 -17
- package/bin/agent-handoff-kit.mjs +43 -29
- package/package.json +1 -1
- package/runtime-core/AGENTS.core.md +12 -6
- package/runtime-core/PROJECT_INDEX.md +2 -2
- package/runtime-core/SESSION_HANDOFF.md +8 -6
- package/runtime-core/SESSION_LOG.md +3 -1
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +3 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.18` 候選準備。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -10,13 +10,13 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
|
|
|
10
10
|
|
|
11
11
|
> 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
|
|
12
12
|
>
|
|
13
|
-
>
|
|
13
|
+
> 安裝完成後,在能讀寫本機專案資料夾的 AI agent 對話中貼上:
|
|
14
14
|
>
|
|
15
15
|
> ```
|
|
16
|
-
> Work in <你的資料夾>.
|
|
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.
|
|
17
17
|
> ```
|
|
18
18
|
>
|
|
19
|
-
> AI
|
|
19
|
+
> AI 會打開專案內的開工提示。第一次安裝後,提示會帶它載入新手引導;之後每次收工後,提示會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
|
|
20
20
|
|
|
21
21
|
想先看非技術版介紹,可打開 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
22
|
|
|
@@ -37,7 +37,13 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
|
|
|
37
37
|
|
|
38
38
|

|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話貼固定開工句;AI 會打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
|
|
41
|
+
|
|
42
|
+
### 適用工具
|
|
43
|
+
|
|
44
|
+
Agent Handoff Kit 適合能讀寫本機專案資料夾的 agentic AI 工具,例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity,或其他具備本機工作區讀寫能力的工具。
|
|
45
|
+
|
|
46
|
+
它不適合普通 web chat AI,例如沒有本機檔案讀寫能力的 ChatGPT、Claude、Gemini 網頁版。上載檔案或貼上交接內容不能取代本工具需要的本機讀寫能力;這類工具不能可靠維護專案內的交接文件。
|
|
41
47
|
|
|
42
48
|
### 一、安裝
|
|
43
49
|
|
|
@@ -51,7 +57,7 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
|
|
|
51
57
|
|
|
52
58
|
安裝完成後,終端機會顯示一段 `Work in ...` 文字。請特別留意:那一段不是給終端機的指令,而是要貼到 AI 對話。
|
|
53
59
|
|
|
54
|
-
可用的 AI
|
|
60
|
+
可用的 AI 工具必須能讀寫此資料夾。不同工具對入口檔的支援可能不同;本工具會同時放置 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,讓常見工具能找到同一套開工路徑。Google 官方遷移文件說明,Antigravity CLI 會讀工作資料夾內的 `GEMINI.md` 和 `AGENTS.md`;因此 `AGENTS.md` 仍是唯一真源,`GEMINI.md` 只做橋接。
|
|
55
61
|
|
|
56
62
|
> 補充:`--yes` 只是讓 npm 先取得這個工具,避免多問一次安裝確認。真正會建立項目文件的是 `init`;`doctor` 只檢查,不會安裝或改動你的項目文件。
|
|
57
63
|
|
|
@@ -71,22 +77,24 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
|
|
|
71
77
|
|
|
72
78
|
### 二、開工
|
|
73
79
|
|
|
74
|
-
|
|
80
|
+
打開能讀寫本機專案資料夾的 AI agent,在新對話貼上安裝工具顯示的文字。
|
|
75
81
|
|
|
76
|
-
|
|
82
|
+
**日常開工句(第一次安裝後與之後每次接力都用同一句)**:
|
|
77
83
|
|
|
78
84
|
```text
|
|
79
|
-
Work in <你的專案資料夾>.
|
|
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.
|
|
80
86
|
```
|
|
81
87
|
|
|
82
|
-
AI
|
|
88
|
+
第一次安裝後,`START_NEXT_SESSION_PROMPT.txt` 內會放新手引導,AI 會帶你選擇使用情境(建構系統 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。每次收工後,同一個檔案會改成下一次接力需要的真實狀態。你不需要手動打開或複製整份交接內容。
|
|
83
89
|
|
|
84
|
-
|
|
90
|
+
如果 AI 工具已經在正確專案資料夾內,而且會讀 `AGENTS.md`,日常也可以只說:
|
|
85
91
|
|
|
86
92
|
```text
|
|
87
|
-
|
|
93
|
+
Start Agent Handoff
|
|
88
94
|
```
|
|
89
95
|
|
|
96
|
+
中文可說「開工」。若你說的是「某某開工」(例如餐廳開工、項目開工)這類帶其他上下文的話,AI 應先反問你是否指 Agent Handoff Kit 接力,而不是立即啟動交接流程。
|
|
97
|
+
|
|
90
98
|
然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
|
|
91
99
|
|
|
92
100
|
### 三、收工
|
|
@@ -100,17 +108,20 @@ Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing a
|
|
|
100
108
|
也可以輸入:
|
|
101
109
|
|
|
102
110
|
```text
|
|
111
|
+
Wrap up Agent Handoff
|
|
103
112
|
wrap up
|
|
104
113
|
handoff
|
|
105
114
|
```
|
|
106
115
|
|
|
107
|
-
AI
|
|
116
|
+
若你說的是「某某收工」(例如餐廳收工、今天活動收工)這類帶其他上下文的話,AI 應先反問你是否要執行 Agent Handoff Kit 收工交接,而不是立即改寫交接文件。
|
|
117
|
+
|
|
118
|
+
AI 應更新交接文件,並同步更新下一次開工提示副本:
|
|
108
119
|
|
|
109
120
|
```text
|
|
110
121
|
START_NEXT_SESSION_PROMPT.txt
|
|
111
122
|
```
|
|
112
123
|
|
|
113
|
-
|
|
124
|
+
這個檔案保存下一次真正要讀的開工內容。你下次仍只需貼同一條日常開工句,讓 AI 自己打開這個檔案。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
|
|
114
125
|
|
|
115
126
|
## 檢查是否安裝完整
|
|
116
127
|
|
|
@@ -122,7 +133,7 @@ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
|
|
|
122
133
|
|
|
123
134
|
看到「檢查通過」代表必要文件與基本結構通過檢查。若 `START_NEXT_SESSION_PROMPT.txt` 落後於 `dev/SESSION_HANDOFF.md`,`doctor` 只會提醒;這個便利副本應在收工 closeout 時由 AI 重新生成,不需要在 session 中途手動更新。
|
|
124
135
|
|
|
125
|
-
`doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,仍應把 `Work in ...`
|
|
136
|
+
`doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,仍應把 `Work in ...` 起步句貼到能讀寫本機資料夾的 AI agent 對話,讓 AI 讀入口文件並說明目前狀態。
|
|
126
137
|
|
|
127
138
|
## 會安裝甚麼
|
|
128
139
|
|
|
@@ -147,7 +158,7 @@ dev/rules/*.md
|
|
|
147
158
|
| `AGENTS.md` | AI 開工時最先讀的入口文件。 |
|
|
148
159
|
| `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
|
|
149
160
|
| `GEMINI.md` | 讓 Google Antigravity CLI、Gemini CLI 遷移期或相容入口工具找到同一套入口。Antigravity CLI 會讀 `AGENTS.md` 與 `GEMINI.md`,所以此檔只做橋接,不另寫一套規則。 |
|
|
150
|
-
| `START_NEXT_SESSION_PROMPT.txt` |
|
|
161
|
+
| `START_NEXT_SESSION_PROMPT.txt` | 下一次開工時由 AI 讀取的提示副本;初次安裝時放新手引導,收工後由交接文件自動產生。 |
|
|
151
162
|
| `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
|
|
152
163
|
| `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。長期使用後舊條目會自動整理入封存資料夾,主檔保持簡短。日常使用不需要打開本檔,做審計或追溯時才看。 |
|
|
153
164
|
| `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
|
|
@@ -261,7 +272,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
261
272
|
|
|
262
273
|
## 目前限制
|
|
263
274
|
|
|
264
|
-
- 目前版本為 `v0.3.
|
|
275
|
+
- 目前版本為 `v0.3.18` 候選準備;npm registry `latest` 在正式發布前仍以已發布版本為準。
|
|
265
276
|
- 這是早期可用版本,仍在持續完善中。
|
|
266
277
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
267
278
|
- `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
|
-
"
|
|
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,8 +65,10 @@ const requiredAnchors = [
|
|
|
63
65
|
label: "closeout intent and full handoff",
|
|
64
66
|
snippets: [
|
|
65
67
|
"Detect end-of-session or handoff intent",
|
|
66
|
-
"收工",
|
|
67
|
-
"
|
|
68
|
+
"收工",
|
|
69
|
+
"Wrap up Agent Handoff",
|
|
70
|
+
"Ambiguous closeout phrases",
|
|
71
|
+
"wrap up",
|
|
68
72
|
"handoff",
|
|
69
73
|
"Reconcile `dev/SESSION_HANDOFF.md`",
|
|
70
74
|
"Add a concise entry to `dev/SESSION_LOG.md`",
|
|
@@ -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
|
|
779
|
-
}
|
|
780
|
+
function getFirstUseNextStep(root, lastCloseout) {
|
|
781
|
+
if (lastCloseout.date) return null;
|
|
782
|
+
return `檢查已通過。下一步不要再留在終端機;打開能讀寫此資料夾的 AI agent,貼上:${startupBootstrapPrompt(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.
|
|
@@ -2041,15 +2045,17 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
|
|
|
2041
2045
|
}
|
|
2042
2046
|
console.log("------------------------------------------------------------");
|
|
2043
2047
|
console.log("⚠️ 下面這句不是終端機指令。");
|
|
2044
|
-
console.log("📋
|
|
2045
|
-
console.log("
|
|
2046
|
-
console.log("
|
|
2047
|
-
console.log(
|
|
2048
|
-
console.log(
|
|
2049
|
-
console.log("");
|
|
2050
|
-
console.log("
|
|
2051
|
-
console.log("
|
|
2052
|
-
|
|
2048
|
+
console.log("📋 請打開能讀寫此資料夾的 AI agent,新增對話後貼上:");
|
|
2049
|
+
console.log(" 例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。");
|
|
2050
|
+
console.log(" 普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。");
|
|
2051
|
+
console.log("------------------------------------------------------------");
|
|
2052
|
+
console.log(startupBootstrapPrompt(root));
|
|
2053
|
+
console.log("------------------------------------------------------------");
|
|
2054
|
+
console.log("");
|
|
2055
|
+
console.log("🚀 AI 會先確認這個資料夾,讀取 START_NEXT_SESSION_PROMPT.txt。第一次安裝後,該檔案會觸發新手引導;收工後,該檔案會承載下一次接力狀態。");
|
|
2056
|
+
console.log(" 之後若 AI 已在正確專案內,可說「Start Agent Handoff」/「開工」或「Wrap up Agent Handoff」/「收工」;「某某開工 / 某某收工」會先確認是否指本工具交接。");
|
|
2057
|
+
console.log("============================================================");
|
|
2058
|
+
}
|
|
2053
2059
|
|
|
2054
2060
|
// R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
|
|
2055
2061
|
// (`printInstallNextSteps`) because the user is not first-time; pushing them through
|
|
@@ -2143,14 +2149,18 @@ Commands:
|
|
|
2143
2149
|
🔄 已裝過:先用 upgrade --dry-run 預演,再決定是否正式升級。
|
|
2144
2150
|
🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
|
|
2145
2151
|
|
|
2146
|
-
安裝之後:
|
|
2147
|
-
不要把顯示出來的 "Work in ..." 文字輸入終端機。
|
|
2148
|
-
|
|
2149
|
-
|
|
2150
|
-
|
|
2151
|
-
|
|
2152
|
-
|
|
2153
|
-
|
|
2152
|
+
安裝之後:
|
|
2153
|
+
不要把顯示出來的 "Work in ..." 文字輸入終端機。
|
|
2154
|
+
請打開能讀寫此資料夾的 AI agent,新增對話後貼上那句起步句。
|
|
2155
|
+
例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。
|
|
2156
|
+
普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。
|
|
2157
|
+
AI 會讀取 START_NEXT_SESSION_PROMPT.txt;第一次安裝後該檔案會啟動新手引導,
|
|
2158
|
+
收工後該檔案會承載下一次接力狀態。
|
|
2159
|
+
AI 已在正確專案內時,可用「Start Agent Handoff」/「開工」開始接力,
|
|
2160
|
+
用「Wrap up Agent Handoff」/「收工」保存交接;「某某開工 / 某某收工」
|
|
2161
|
+
會先確認是否指本工具交接。
|
|
2162
|
+
|
|
2163
|
+
終端機範例:
|
|
2154
2164
|
npx --yes @adamchanadam/agent-handoff-kit@latest init
|
|
2155
2165
|
npx --yes @adamchanadam/agent-handoff-kit@latest doctor
|
|
2156
2166
|
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
@@ -2165,6 +2175,10 @@ Commands:
|
|
|
2165
2175
|
"Need to install" 提示。真正會建立項目文件的是 init;doctor 只檢查。
|
|
2166
2176
|
`);
|
|
2167
2177
|
console.log(`📦 版本:v${version}`);
|
|
2168
|
-
console.log(`🛠️ 模式:help ready`);
|
|
2169
|
-
console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
|
|
2170
|
-
}
|
|
2178
|
+
console.log(`🛠️ 模式:help ready`);
|
|
2179
|
+
console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
|
|
2180
|
+
}
|
|
2181
|
+
|
|
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.`;
|
|
2184
|
+
}
|
package/package.json
CHANGED
|
@@ -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
|
-
|
|
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
|
|
95
|
-
10. Show a short closeout card, then provide the
|
|
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.
|
|
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):
|
|
@@ -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
|
|
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
|
|
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.
|
|
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
137
|
|
|
138
|
-
📋 Next session: copy and paste the whole block below
|
|
138
|
+
📋 Next session: copy and paste the whole block 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
|
-
|
|
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
|
+
```
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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.
|