@adamchanadam/agent-handoff-kit 0.1.8 → 0.2.1

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.1.8` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
3
+ 狀態:`v0.2.1` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
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
 
@@ -8,6 +8,16 @@ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
8
8
 
9
9
  它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
10
10
 
11
+ > 🚀 **第一次用?你不需要先讀本 README 或任何文檔。**
12
+ >
13
+ > 安裝完成後,在 AI 對話中講一句:
14
+ >
15
+ > ```
16
+ > Work in <你的資料夾>. I just installed agent-handoff-kit. Help me get started.
17
+ > ```
18
+ >
19
+ > AI 會自動引導你選擇情景(寫代碼 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
20
+
11
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 則保留安裝、日常使用與限制。
12
22
 
13
23
  ## 它解決甚麼問題
@@ -39,7 +49,17 @@ npx @adamchanadam/agent-handoff-kit init
39
49
 
40
50
  ### 二、開工
41
51
 
42
- 打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。沒有那段文字時,可貼這句:
52
+ 打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。
53
+
54
+ **第一次用(R-029 onboarding trigger)**:
55
+
56
+ ```text
57
+ Work in <你的專案資料夾>. I just installed agent-handoff-kit. Help me get started.
58
+ ```
59
+
60
+ AI 會自動載入 onboarding pack,引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。
61
+
62
+ **之後 session(你已熟悉 v2 之後)可用更直接 prompt**:
43
63
 
44
64
  ```text
45
65
  Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
@@ -94,6 +114,7 @@ START_NEXT_SESSION_PROMPT.txt
94
114
  dev/SESSION_HANDOFF.md
95
115
  dev/SESSION_LOG.md
96
116
  dev/PROJECT_INDEX.md
117
+ dev/PROJECT_DECISIONS.md
97
118
  dev/DOC_SYNC_REGISTRY.md
98
119
  dev/RULE_PACKS.md
99
120
  dev/rules/*.md
@@ -108,12 +129,43 @@ dev/rules/*.md
108
129
  | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
109
130
  | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。主檔長期保持短小;N=11+ 嘅舊條目自動 archive 至 `dev/SESSION_LOG_archive/`,trace-back 用。接力靠 `SESSION_HANDOFF.md`,本檔屬冷資料層。 |
110
131
  | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
132
+ | `dev/PROJECT_DECISIONS.md` | 保存項目嘅長期演進、決策、架構取捨、學習觀察。屬 warm 資料層 —— AI 開工**不需要讀**本檔;遇到「之前點解咁做」嘅問題時 AI 自己嚟搵。短期單一 task 項目本檔保持近空;長期項目 AI 喺收工時自動 maintain。 |
111
133
  | `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
112
134
  | `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
113
- | `dev/rules/*.md` | 按任務載入的細分工作規則。 |
135
+ | `dev/rules/*.md` | 按任務載入的細分工作規則。含 9 個 pack:safety / coding / writing / research / agent-governance / release / knowledge / communication / **onboarding**(v0.2.0 新加,新手第一次用時 AI 主動載入做 walk-through)。 |
114
136
 
115
137
  你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
116
138
 
139
+ ## SESSION_LOG 嘅自動整理機制
140
+
141
+ 長期使用後,`dev/SESSION_LOG.md` 唔會無止境膨脹。每次你講「收工」,AI 會自動執行 N 規則整理(N 代表 session 嘅 entry 數,N=1 為最新):
142
+
143
+ - **N=1–3**:最新三條 session 條目保留完整內容(safety buffer,萬一交接出錯仍有 fallback)。
144
+ - **N=4–10**:核心內容已被 `dev/SESSION_HANDOFF.md` 等真源吸收嘅條目,自動降為短索引(日期 + 標題 + 真源 anchor)。
145
+ - **N=11+**:自動 archive 入 `dev/SESSION_LOG_archive/archive_<批次>_<日期區間>.md`;主檔末尾留一份 archive index 做 trace-back 入口。
146
+
147
+ 接力責任由 `dev/SESSION_HANDOFF.md` 對賬式更新承擔;`dev/SESSION_LOG.md` 屬 trace-back / 審計用嘅冷資料層。**新 AI session 開工唔需要讀完整 LOG**,只需要讀 `AGENTS.md` + `dev/SESSION_HANDOFF.md` + 索引文件就足夠接力。
148
+
149
+ 所以你部電腦嘅 `dev/` 資料夾唔會被 session log 不停撐大,亦唔需要你手動清理。如果主檔意外膨脹(11 條以上未 archive,或單檔超過 1500 行),`doctor` 會喺輸出顯示一個 warning 提醒 AI 下次收工執行整理;但呢個只屬提醒,唔會令 `doctor` 失敗、亦唔阻擋安裝。
150
+
151
+ ## 項目決策日誌
152
+
153
+ `dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察 narrative。屬 warm 資料層 —— AI 開工**不需要讀**本檔;當你問「之前為何這樣做」時,AI 自己會從這裡找答案。
154
+
155
+ - 短期 single-task 項目:本檔保持近空,你不需要 maintain
156
+ - 長期持續演進項目:AI 會在每次收工時自動 maintain
157
+ - HANDOFF 的「Confirmed Decisions」或同類 decisions section 累積至 30+ 條時,AI 自動 split 舊條目至此
158
+ - 觀察到任務需求演進、架構取捨、累積學習 pattern 時,AI 主動 append entry
159
+
160
+ 本檔含 4 個固定 H2 section:
161
+
162
+ - **Evolution Timeline** —— 任務需求嘅長期演進
163
+ - **Decisions Archive** —— 累積決策嘅冷封存
164
+ - **Architecture Choices** —— 主要架構取捨同 rationale
165
+ - **Insights & Learnings** —— 多 session 累積嘅學習觀察
166
+
167
+ 本檔同 SESSION_LOG 嘅 archive 機制屬同一套 hot / warm / cold 分層紀律 —— 你部電腦嘅 `dev/` 資料夾長期使用都唔會被無關 narrative 撐大,亦唔需要你手動清理。新手用戶完全唔需要打開本檔,亦唔需要記任何 schema —— 一切由 AI 自律執行。
168
+
117
169
  ## 工作模式
118
170
 
119
171
  你不需要記規則包名稱,只要描述任務。AI 會按任務切換工作模式。
@@ -199,9 +251,18 @@ npm package 只包含安裝所需內容:
199
251
 
200
252
  GitHub Pages 上的兩個 onboarding 頁 —— [`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)(實操指南)—— 由原始碼倉庫根目錄發佈;兩個 HTML 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
201
253
 
254
+ ## 配合 Adam-AI-Instructions 使用
255
+
256
+ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions)(Meta Instruction for AI)配合使用效果最好。兩者分工互補,不重疊:
257
+
258
+ - **Adam-AI-Instructions** 負責 AI 喺**單一對話**內嘅做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該點答你」嘅持久基準。
259
+ - **Agent Handoff Kit** 負責 AI 喺**對話之間**嘅接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 對話之間點記憶你個項目」嘅持久基準。
260
+
261
+ 到該 repo 嘅「**五、Prompt 索引**」揀啱你 AI 工具嘅 prompt(Claude Cowork / Claude Code / OpenAI Codex / ChatGPT 等),複製對應子目錄嘅 `prompt.md` 全文,貼入 AI 工具嘅 system prompt、personal preferences 或 project instructions(例如 Claude Cowork 的 Global Instructions、Claude Code 的 `~/.claude/CLAUDE.md`、ChatGPT 的 Custom Instructions)。然後再喺項目資料夾跑 `npx @adamchanadam/agent-handoff-kit init` 安裝呢套 Kit。兩者配合就能涵蓋「單次對話質素」+「跨對話接力」兩個維度。
262
+
202
263
  ## 目前限制
203
264
 
204
- - `v0.1.8` 是 GitHub 與 npm 同步發佈版本。
265
+ - `v0.2.1` 是 GitHub 與 npm 同步發佈版本。
205
266
  - 這是早期可用版本,尚未宣稱完整穩定。
206
267
  - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
207
268
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -19,6 +19,7 @@ const mappings = [
19
19
  ["runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md"],
20
20
  ["runtime-core/DOC_SYNC_REGISTRY.md", "dev/DOC_SYNC_REGISTRY.md"],
21
21
  ["runtime-core/RULE_PACKS.md", "dev/RULE_PACKS.md"],
22
+ ["runtime-core/PROJECT_DECISIONS.md", "dev/PROJECT_DECISIONS.md"],
22
23
  ["packs/safety.md", "dev/rules/safety.md"],
23
24
  ["packs/coding.md", "dev/rules/coding.md"],
24
25
  ["packs/writing.md", "dev/rules/writing.md"],
@@ -26,7 +27,8 @@ const mappings = [
26
27
  ["packs/agent-governance.md", "dev/rules/agent-governance.md"],
27
28
  ["packs/release.md", "dev/rules/release.md"],
28
29
  ["packs/knowledge.md", "dev/rules/knowledge.md"],
29
- ["packs/communication.md", "dev/rules/communication.md"]
30
+ ["packs/communication.md", "dev/rules/communication.md"],
31
+ ["packs/onboarding.md", "dev/rules/onboarding.md"]
30
32
  ];
31
33
 
32
34
  const requiredTargets = mappings.map(([, target]) => target);
@@ -158,6 +160,38 @@ const requiredAnchors = [
158
160
  "external APIs, SDKs, CLIs",
159
161
  "secret values"
160
162
  ]
163
+ },
164
+ {
165
+ target: "dev/PROJECT_DECISIONS.md",
166
+ label: "project decisions narrative anchors",
167
+ snippets: [
168
+ "Project Decisions Log",
169
+ "warm 資料層",
170
+ "AI 開工",
171
+ "不需要讀",
172
+ "AI 在收工時自動 update",
173
+ "Evolution Timeline",
174
+ "Decisions Archive",
175
+ "Architecture Choices",
176
+ "Insights & Learnings"
177
+ ]
178
+ },
179
+ {
180
+ target: "dev/rules/onboarding.md",
181
+ label: "onboarding pack core anchors",
182
+ snippets: [
183
+ "Onboarding Pack",
184
+ "transient pack",
185
+ "明確 onboarding signal keywords",
186
+ "5-step walk-through pattern",
187
+ "Application Scenario Library",
188
+ "Scenario A. 寫 / 改代碼項目",
189
+ "Scenario B. 整理研究資料",
190
+ "Scenario C. 整理電腦檔案",
191
+ "Scenario D. 學寫代碼",
192
+ "Scenario E. 其他",
193
+ "Tone Discipline"
194
+ ]
161
195
  }
162
196
  ];
163
197
 
@@ -268,7 +302,36 @@ const schemaChecks = [
268
302
  includes("dev/rules/safety.md"),
269
303
  includes("dev/rules/coding.md"),
270
304
  includes("dev/rules/research.md"),
271
- includes("dev/rules/release.md")
305
+ includes("dev/rules/release.md"),
306
+ // R-029 v0.2.1+: routing table must include onboarding pack first-time signal row.
307
+ // Without this anchor, the upgrade flow may silently leave v0.1.X users with a
308
+ // stale routing table that does not route onboarding signals.
309
+ includes("First-time user signals"),
310
+ includes("dev/rules/onboarding.md")
311
+ ]
312
+ },
313
+ {
314
+ target: "dev/PROJECT_DECISIONS.md",
315
+ label: "project decisions log structure",
316
+ checks: [
317
+ heading("Evolution Timeline"),
318
+ heading("Decisions Archive"),
319
+ heading("Architecture Choices"),
320
+ heading("Insights & Learnings"),
321
+ includes("(empty)")
322
+ ]
323
+ },
324
+ {
325
+ target: "dev/rules/onboarding.md",
326
+ label: "onboarding pack structure (R-029)",
327
+ checks: [
328
+ heading("Scope"),
329
+ heading("Load When"),
330
+ heading("Discipline"),
331
+ heading("Application Scenario Library"),
332
+ heading("Cross-reference to guide.html"),
333
+ heading("Tone Discipline"),
334
+ heading("Closeout")
272
335
  ]
273
336
  }
274
337
  ];
@@ -704,6 +767,21 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
704
767
  mergedText: mergeManagedBlock(targetText, sourceText)
705
768
  };
706
769
  }
770
+ // R-029 v0.2.0+: RULE_PACKS.md is a routing table, not a user customization target.
771
+ // Stale v0.1.X versions miss the "First-time user signals" onboarding routing row.
772
+ // Force-refresh during upgrade so R-029 onboarding routing propagates to existing users.
773
+ // Any user-added custom routing rows will be lost on upgrade — this is by design;
774
+ // RULE_PACKS.md is treated as a maintainer-owned routing table, similar to the
775
+ // AGENTS.md managed-core block. User customizations belong in pack rule files
776
+ // (packs/*.md), not in the routing table.
777
+ if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("First-time user signals")) {
778
+ return {
779
+ ...base,
780
+ action: "merge",
781
+ reason: "refresh stale routing table to include v0.2.0+ rows (R-029 onboarding signal routing)",
782
+ mergedText: sourceText
783
+ };
784
+ }
707
785
  if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
708
786
  return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
709
787
  }
@@ -1147,11 +1225,14 @@ function printInstallNextSteps(root, conflictCount) {
1147
1225
  console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
1148
1226
  console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
1149
1227
  console.log("------------------------------------------------------------");
1150
- console.log(`Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
1228
+ console.log(`Work in ${root}. I just installed agent-handoff-kit. Help me get started.`);
1151
1229
  console.log("------------------------------------------------------------");
1152
1230
  console.log("");
1153
- console.log("🚀 然後直接描述你的任務,例如:");
1154
- console.log(" 整理這個專案,先告訴我你讀到的目前狀態與下一步。");
1231
+ console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
1232
+ console.log(" 一步一步帶你做第一個任務(由 R-029 onboarding pack 主動接管)。");
1233
+ console.log("");
1234
+ console.log("💡 之後 session(你已熟悉 v2 之後)可改用更直接 prompt:");
1235
+ console.log(` Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
1155
1236
  console.log("");
1156
1237
  console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
1157
1238
  console.log(" npx @adamchanadam/agent-handoff-kit doctor");
@@ -1192,9 +1273,11 @@ Commands:
1192
1273
  🩺 doctor 檢查必要文件與交接結構是否完整。
1193
1274
 
1194
1275
  After install:
1195
- Do not type "Follow AGENTS.md" into Terminal.
1196
- Open your AI tool, start a new chat, paste the shown Work in ... message,
1197
- then describe your task in normal language.
1276
+ Do not type the shown "Work in ..." message into Terminal.
1277
+ Open your AI tool, start a new chat, and paste it there.
1278
+ The default post-install prompt triggers the R-029 onboarding pack — AI
1279
+ will guide you through scenario selection (coding / research / knowledge /
1280
+ learning / other) and walk you through your first task in 5 steps.
1198
1281
  `);
1199
1282
  console.log(`📦 版本:v${version}`);
1200
1283
  console.log(`🛠️ 模式:help ready`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.1.8",
3
+ "version": "0.2.1",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -18,6 +18,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
18
18
  5. Check complexity budget before adding default-core behavior.
19
19
  6. Before creating durable workflow, runbook, or instruction files, first verify whether `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, `dev/DOC_SYNC_REGISTRY.md`, or existing rule packs can carry the need without a new file.
20
20
  7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs its own handoff/log/index/registry persistence.
21
+ 8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` step 12): smart-detect substantive task evolution, multi-option architectural trade-offs, and cross-session patterns, then append entries to the appropriate H2 section. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
21
22
 
22
23
  ## Checks
23
24
 
@@ -26,6 +27,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
26
27
  - Confirm old overlapping wording was retired or marked legacy.
27
28
  - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
28
29
  - Before claiming completion, inspect the active root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`; do not assume child or demo workspaces cover the parent/root workspace.
30
+ - For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that closeout step 12 was applied where its trigger conditions were met.
29
31
 
30
32
  ## Closeout
31
33
 
@@ -0,0 +1,298 @@
1
+ # Onboarding Pack
2
+
3
+ ## Scope
4
+
5
+ 新手用戶 day-1 walk-through 與 application scenario routing。
6
+
7
+ 當用戶第一次使用 Agent Handoff Kit、沒有預設 expectation 或 prior context 時,本 pack 引導 AI 主動帶用戶完成第一個任務,不要求用戶先讀任何文檔。
8
+
9
+ 本 pack 屬 transient pack —— 完成 onboarding session 後,AI 自動 unload 並由 regular scenario pack(coding / research / writing / knowledge / ...)接手。
10
+
11
+ ## Load When
12
+
13
+ ### 明確 onboarding signal keywords(用戶 message 含任一即可)
14
+
15
+ - 「新手」/「I'm new」
16
+ - 「教我用」/「teach me」/「教我點用」
17
+ - 「help me start」/「help me get started」
18
+ - 「first time」/「first-time」
19
+ - 「我啱啱安裝」/「I just installed」
20
+ - 「點開始」/「how do I start」
21
+ - 「show me how」
22
+ - 「getting started」
23
+ - 「agent handoff kit 可幫我做什麼」/「what can agent handoff kit do」
24
+ - 「我想做 [類型] project」/「I want to do a [type] project」(vague project intent)
25
+ - 「點用」/「點 leverage」/「能力」/「能做甚麼」/「what can it do」
26
+
27
+ ### Implicit signals(任一即可)
28
+
29
+ - 用戶首段 message ≤ 30 字 + 任務描述 vague
30
+ - HANDOFF Active Objective 空白 + Session count 1(fresh installation context)
31
+ - 用戶 message 屬 generic capability question 而非 specific task description
32
+ - 用戶語氣 unfamiliar with v2 workflow(譬如問 AI 自己應該做甚麼,而非告訴 AI 做甚麼)
33
+
34
+ ## Discipline
35
+
36
+ ### 1. 不假設用戶已讀任何文檔
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
+ >
52
+ > 選擇其中一個(A/B/C/D/E),我會引導你做第一個任務。如果你想看完整 narrative example,可以開新 tab 看 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html 的 Case A/B/C。本指南是參考對照,不需要先讀。」
53
+
54
+ ### 3. 5-step walk-through pattern
55
+
56
+ 用戶選定 scenario 後,AI 跑 5 step walk-through(全部 scenario 共用同一 pattern,內容 customize per scenario):
57
+
58
+ 1. **AI 確認 project context**(root / 已有資料 / git status / 工具 stack)
59
+ 2. **AI 解釋 v2 如何 fit 這個 scenario**(高層 value statement,3 點 max)
60
+ 3. **AI ask user about 第一個 concrete task scope**(提供 4-6 個 option)
61
+ 4. **AI suggest minimum viable first task**(dry-run / minimal output,10-15 分鐘可完成)
62
+ 5. **AI ask user about confirm + 進入 actual work loop**(載入對應 regular scenario pack)
63
+
64
+ ### 4. 每 step 解釋 + 等用戶 confirm
65
+
66
+ 不可以一次過跑全部 5 step。每 step:
67
+ - 解釋緊做甚麼
68
+ - 等用戶「OK,下一步」/「我有問題」/「我想 skip 這 step」
69
+ - 若用戶有問題,先解答再繼續
70
+
71
+ ### 5. 進入 actual task 前先 verify minimum context
72
+
73
+ 用戶第一個任務應該 minimal scope(dry-run / 短輸出 / 10-15 分鐘可完成),讓用戶感覺到 v2 的 rhythm 才擴大 scope。**不要**第一個 task 就 commit 大改動。
74
+
75
+ ### 6. 完成 onboarding 後 transition
76
+
77
+ 5-step walk-through 完成後:
78
+ - 載入用戶 scenario 對應的 regular pack(coding / research / writing / knowledge / ...)
79
+ - Unload onboarding pack(transient pack,不長期駐留)
80
+ - 進入 PLAN → READ → CHANGE → QC → PERSIST 嘅 regular work loop
81
+ - SESSION_HANDOFF Active Objective 記錄 first-task scope
82
+
83
+ ## Application Scenario Library
84
+
85
+ 每個 scenario 提供 5 step walk-through 嘅紀律 wording 加 1 句 AI sample wording 作為 anchor。AI 模型可 adapt 具體 wording 但保留 intent 與 tone。
86
+
87
+ ### Scenario A. 寫 / 改代碼項目
88
+
89
+ **對應 guide.html Case A**(整理電腦下載目錄 + 公開發佈為 Git project)
90
+
91
+ #### Step A.1 — 確認 project context
92
+
93
+ - 任務:AI 確認 project root 存在 + 識別 stack + 檢查 git status
94
+ - AI sample wording:
95
+ > 「請告訴我你的 project 在哪個目錄?如果還未建立,可以在電腦開新 folder 然後告訴我路徑。我會檢查 git status、讀 README / package.json 識別你的 stack(譬如 Python / Node.js / Rust 等),再為下一步建議方向。」
96
+
97
+ #### Step A.2 — 解釋 v2 如何 fit
98
+
99
+ - 任務:AI 用 3 點解釋 v2 對 coding 項目的核心 value
100
+ - AI sample wording:
101
+ > 「v2 對 coding 項目的核心 value 有三點:(1) AI 跨對話記得你 project 的 stack、規則、進度,下次任何 AI 工具開新對話都接得返;(2) 危險指令(rm -rf、git reset --hard、強制推送)必須先講計劃,不會 silent 執行;(3) 收工時自動寫低你做過甚麼,連 commit hash 都記錄,方便日後追溯。」
102
+
103
+ #### Step A.3 — Ask user about 第一個 task scope
104
+
105
+ - 任務:AI 提供 4-6 個 concrete task option 讓用戶選
106
+ - AI sample wording:
107
+ > 「你的 project 現在最想處理的是:(a) bug fix / (b) 新功能 / (c) 重構既有代碼 / (d) 加測試 / (e) 寫 README / (f) Git initial commit?如果你想做的不在這幾項,告訴我即可,我會 customize。」
108
+
109
+ #### Step A.4 — Suggest minimum viable first task
110
+
111
+ - 任務:AI 將用戶選擇 narrow scope 至 10-15 分鐘可完成的 minimum viable task
112
+ - AI sample wording:
113
+ > 「你選『寫 README』。我建議第一個任務最 minimal scope:寫一個約 100 字的 README.md,含一句項目簡介加三點功能。寫好後你 review、加自己的修改,最後 git commit。整個過程約 10 分鐘。可以嗎?」
114
+
115
+ #### Step A.5 — Ask user about confirm + 進入 work loop
116
+
117
+ - 任務:AI 確認用戶同意 + 載入對應 regular pack + 開始 work loop
118
+ - AI sample wording:
119
+ > 「Confirm 之後,我會載入 coding 模式 + writing 模式(README 屬 writing),開始 PLAN → READ → CHANGE → QC → PERSIST 五階段。準備好嗎?」
120
+
121
+ ### Scenario B. 整理研究資料 / 寫報告
122
+
123
+ **對應 guide.html Case B**(開咖啡店市場調查 + 寫完成報告)
124
+
125
+ #### Step B.1 — 確認 project context
126
+
127
+ - AI sample wording:
128
+ > 「請告訴我三點:(1) 你的報告主題;(2) 已有資料在哪裡(Notion / Google Drive / 本地檔案);(3) 報告的讀者是誰(自己 / 客戶 / 合作伙伴 / 公開)。我會根據這三點建議分工。」
129
+
130
+ #### Step B.2 — 解釋 v2 如何 fit
131
+
132
+ - AI sample wording:
133
+ > 「v2 對研究類項目的核心 value 有三點:(1) 真源紀律 —— 每條 claim 必須引用,事實與推論分開寫,AI 不會憑印象寫;(2) 外部來源邊界 —— Notion / Drive 寫入由你親手做,AI 列步驟但不代辦你的帳號操作;(3) 跨 session 接力 —— 你寫到 50% 收工,下次接得返,包括引用紀律。」
134
+
135
+ #### Step B.3 — Ask user about 第一個 task scope
136
+
137
+ - AI sample wording:
138
+ > 「你想 first session 處理:(a) 列章節結構 / (b) 整理已有 reference 入 PROJECT_INDEX / (c) 寫摘要段 / (d) 寫第一個 sub-section / (e) 整體 review 已有 draft?」
139
+
140
+ #### Step B.4 — Suggest minimum viable first task
141
+
142
+ - AI sample wording:
143
+ > 「你選『列章節結構』。我建議第一個任務 minimal scope:列 5-7 個 H2 chapter heading 加每章一句目標。寫好後你 review、調整。約 15 分鐘可以完成。可以嗎?」
144
+
145
+ #### Step B.5 — Ask user about confirm + 進入 work loop
146
+
147
+ - AI sample wording:
148
+ > 「Confirm 之後,我會載入 research 模式 + writing 模式 + knowledge 模式(涉外部來源時 trigger)。開始五階段 work loop。」
149
+
150
+ ### Scenario C. 整理電腦檔案 / Notion / Drive 知識庫
151
+
152
+ **對應 guide.html Case A 的檔案整理部分 + Case B 的 Notion reference 部分**
153
+
154
+ #### Step C.1 — 確認 project context
155
+
156
+ - AI sample wording:
157
+ > 「請告訴我你想整理的是:(a) 電腦目錄(哪個 folder)/ (b) Notion DB(請描述 schema)/ (c) Google Drive(哪個 folder)/ (d) 多個來源混合(請描述)。」
158
+
159
+ #### Step C.2 — 解釋 v2 如何 fit
160
+
161
+ - AI sample wording:
162
+ > 「v2 對知識庫整理的核心 value 有三點:(1) 識別真源 vs reference vs draft —— PROJECT_INDEX 登記每份檔案的角色,避免 AI 將參考檔當真源;(2) Notion / Drive 寫入由你親手做,AI 列詳細步驟但不代辦;(3) 危險動作(大量檔案移動 / 重命名 / 刪除)必須 dry-run 列清單,等你 confirm 才實際執行。」
163
+
164
+ #### Step C.3 — Ask user about 第一個 task scope
165
+
166
+ - AI sample wording:
167
+ > 「你想 first session 處理:(a) 掃描 + 分類已有檔案 / (b) 建立 Notion DB schema / (c) 設計 folder 結構 / (d) 寫整理 script + dry-run / (e) 對齊 Notion 與本地 reference?」
168
+
169
+ #### Step C.4 — Suggest minimum viable first task
170
+
171
+ - AI sample wording:
172
+ > 「你選『掃描 + 分類已有檔案』。Minimal scope:先 dry-run 100 個檔案,列分類建議由你 confirm,先不做實際移動。約 15 分鐘可完成。可以嗎?」
173
+
174
+ #### Step C.5 — Ask user about confirm + 進入 work loop
175
+
176
+ - AI sample wording:
177
+ > 「Confirm 之後,我會載入 knowledge 模式 + safety 模式(涉檔案移動)。」
178
+
179
+ ### Scenario D. 學寫代碼(技術新手)
180
+
181
+ **不對應 specific guide case,屬 onboarding-only scenario**
182
+
183
+ #### Step D.1 — 確認 project context
184
+
185
+ - AI sample wording:
186
+ > 「你想學寫的是:(a) 簡單 script(譬如自動 organize 檔案)/ (b) 一個 web page(HTML/CSS/JS)/ (c) 一個 Python 小工具 / (d) 學 git/GitHub 基本概念?告訴我你的興趣方向,我會 customize 第一個練習。」
187
+
188
+ #### Step D.2 — 解釋 v2 如何 fit
189
+
190
+ - AI sample wording:
191
+ > 「v2 對學寫代碼的核心 value 有三點:(1) AI 幫你寫,但不會默默改你的檔案 —— 每改一步等你 review;(2) 危險指令 AI 自己拒絕,你可以在 sandbox 安全試;(3) 跨 session 記住你學到哪裡,下次接得返,包括之前學過的概念。」
192
+
193
+ #### Step D.3 — Ask user about 第一個 task scope
194
+
195
+ - AI sample wording:
196
+ > 「你選『簡單 script』?我建議第一個 script:『重命名 Downloads 目錄裡面所有 screenshot 加日期』—— 涉及 file system basics 加 Python basic syntax。你想試嗎?或者選其他方向。」
197
+
198
+ #### Step D.4 — Suggest minimum viable first task
199
+
200
+ - AI sample wording:
201
+ > 「First minimal scope:我寫一個 5 行 Python script,先做 dry-run(只 print 想做的 rename),你 review 後再做 actual rename。整個過程我會逐句解釋每一行做甚麼。約 15 分鐘。可以嗎?」
202
+
203
+ #### Step D.5 — Ask user about confirm + 進入 work loop
204
+
205
+ - AI sample wording:
206
+ > 「Confirm 之後,我會載入 coding 模式 + safety 模式。我會用最簡單的 wording 解釋每個概念,不假設你知道任何 jargon。」
207
+
208
+ ### Scenario E. 其他 / 用戶自定義情景
209
+
210
+ 如果用戶的 use case 不屬 A-D,AI ask user about 更多細節後 customize 5-step walk-through。
211
+
212
+ #### Step E.1 — 確認 project context(custom intake)
213
+
214
+ - AI sample wording:
215
+ > 「請告訴我四點:(1) 你想完成的目標(一句講完);(2) 已有資料 / 工具 / 限制;(3) 你的技術水平(零基礎 / 略有經驗 / 熟練);(4) 想 first session 達成的 minimal output。我會根據這四點 customize 一個 5-step walk-through,對應 v2 適合你的工作模式。」
216
+
217
+ #### Step E.2 — 解釋 v2 如何 fit(custom)
218
+
219
+ - AI 根據用戶 intake 嘅四點,customize 解釋 v2 嘅 value statement(保留「跨對話接力 + 安全護欄 + 自動 maintain」三項 universal value)
220
+
221
+ #### Step E.3 — Ask user about 第一個 task scope(custom)
222
+
223
+ - AI 提供 customized options 對應用戶嘅 use case
224
+
225
+ #### Step E.4 — Suggest minimum viable first task(custom)
226
+
227
+ - AI narrow scope 至 10-15 分鐘可完成 minimum viable task
228
+
229
+ #### Step E.5 — Ask user about confirm + 進入 work loop(custom)
230
+
231
+ - AI 載入適合 user use case 嘅 regular pack(可能組合多個 pack)
232
+
233
+ ## Cross-reference to guide.html
234
+
235
+ 每個 scenario walk-through 完成後(或者用戶問「我想睇完整 example」),AI 可以 mention:
236
+
237
+ > 「如果想看完整 narrative example,可以開新 tab 看 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html 的 Case A/B/C:
238
+ >
239
+ > - Case A 對應 onboarding scenario A(寫 / 改代碼項目)加 scenario C 的檔案整理部分
240
+ > - Case B 對應 onboarding scenario B(整理研究資料 / 寫報告)加 scenario C 的 Notion reference 部分
241
+ > - Case C 對應長期項目演進(適用於你項目運行到後期,跨多月時間軸)
242
+ >
243
+ > 本指南是參考對照,不需要先讀。」
244
+
245
+ ## Tone Discipline
246
+
247
+ ### 1. 書面語為主
248
+
249
+ 使用繁體中文書面語表達。避免廣東口語字符(嘅 / 咁 / 喺 / 揀 / 唔 / 乜 / 啱 / 嚟 / 咗 / 嗰)出現在 AI 對用戶 surface 的 sample wording。Pack 內部 governance instructions(rules / discipline 等 maintainer-facing wording)允許 mixed style。
250
+
251
+ ### 2. 講人話
252
+
253
+ 避免內部 jargon(R-XXX / PROJECT_INDEX / closeout step / managed core / SESSION_LOG N-rule 等),改用日常解釋:
254
+
255
+ - 「項目登記表」而非「PROJECT_INDEX」
256
+ - 「收工」而非「closeout」
257
+ - 「下次開工提示」而非「next-session opening message」
258
+ - 「AI 工作模式」而非「rule pack」
259
+ - 「危險指令」而非「destructive operation」
260
+
261
+ ### 3. 敍事 + 解釋
262
+
263
+ 每個解釋句要 self-contained,用戶讀完即知道意義。不留 unexplained acronym 或 inside-reference。
264
+
265
+ ### 4. 不過度解釋 internals
266
+
267
+ 用戶不需要知 AGENTS.md 結構、`dev/*` folder 含甚麼、closeout step 11/12 紀律細節。只解釋 surface impact:「AI 會記住你 project」而非「AGENTS.md startup contract 加 SESSION_HANDOFF 對賬式紀律」。
268
+
269
+ ### 5. 鼓勵性而非考試
270
+
271
+ 用「我會帶你做第一個任務」而非「請描述任務」。用「可以嗎?」而非「請確認」。
272
+
273
+ 每 step 標明角色分工:「我(AI)做 X,你做 Y」。避免讓用戶覺得自己被考核。
274
+
275
+ ## Closeout
276
+
277
+ 完成 onboarding session 後,AI 必執行:
278
+
279
+ 1. **確認用戶下一步**:用戶接下來知道如何使用 v2,包括下次如何開新對話、如何描述任務、如何收工。
280
+ 2. **更新 SESSION_HANDOFF Active Objective**:寫入用戶嘅第一個 task scope,方便下次接力。
281
+ 3. **更新 SESSION_HANDOFF Next Priorities**:列下次 session 嘅 next concrete action(譬如「完成 README,然後 git commit」)。
282
+ 4. **提供 standard handoff opening message**:「下一輪開新對話時貼以下一句⋯⋯」嘅 fenced text block。
283
+ 5. **Unload onboarding pack**:由 regular scenario pack(coding / research / writing / knowledge / ...)接手。
284
+
285
+ 下次 session 開新對話時:
286
+ - 如果用戶仍 vague:可以 re-trigger onboarding pack(用戶可能想重新 onboard)
287
+ - 如果用戶已熟悉:AI 直接進入 regular work loop,跳過 onboarding pack
288
+
289
+ ## Anti-pattern(不要做的事)
290
+
291
+ | Anti-pattern | 點解唔做 | 正確做法 |
292
+ |---|---|---|
293
+ | 收到 user vague message 立即 dive into 一個猜測嘅 task | 用戶可能根本未準備好 / 想其他嘢 / 想了解工具能力 | 主動 ask scenario A-E |
294
+ | 第一個 task suggest 大 scope(譬如「我幫你重構整個 codebase」) | 用戶感到 overwhelmed + 唔知 v2 嘅 rhythm | Suggest 10-15 分鐘 minimum viable task |
295
+ | 用 jargon 解釋 v2(R-XXX / PROJECT_INDEX / etc) | 新手 cognitive load 高,唔知 jargon 對應乜 | 用日常 wording 解釋 surface impact |
296
+ | 假設用戶讀過 README / intro / guide | 用戶可能跳過文檔直接從 AI 對話開始 | 主動 surface 必要 concept,但不灌輸 |
297
+ | 完成 onboarding 後唔 unload pack | Onboarding pack 屬 transient,長期駐留會 noise | Closeout 時 explicit unload + 載入 regular pack |
298
+ | 一次過跑 5 step 唔等用戶 confirm | 用戶 cognitive load 爆 + 失去 walk-through 精神 | 每 step 等用戶 confirm 才繼續 |
@@ -13,6 +13,8 @@ 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.
17
+
16
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.
17
19
 
18
20
  If a required file is missing, create the smallest useful version only after confirming the target project root.
@@ -86,6 +88,22 @@ At full closeout:
86
88
  10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `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.
87
89
  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.
88
90
 
91
+ 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):
92
+
93
+ (a) Decisions split check: If `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section (e.g. `## Confirmed Decisions`, `## Decisions`, `## 已定案決策`) with a numbered list of ≥ 30 entries, AI must split the oldest entries (retaining the most recent 8–22 in the handoff hot tier) into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first. If no such section exists in the handoff, this check is no-op (default for short single-task projects).
94
+
95
+ (b) Evolution append: If the current session observed substantive task evolution (user's task description differs substantially from prior sessions, or HANDOFF Current Baseline narrative shifted direction), AI must append an entry to `## Evolution Timeline`.
96
+
97
+ (c) Architecture append: If the current session plan involved a multi-option architectural trade-off (≥ 2 candidate paths + selected one + recorded rationale), AI must append an entry to `## Architecture Choices`.
98
+
99
+ (d) Insights append: If AI observed a cross-session accumulated pattern (recurring same-type problem, sustained-effective approach, persistently-painful tool), AI must append an entry to `## Insights & Learnings`.
100
+
101
+ AI must execute (a)–(d) proactively, not wait for user trigger or doctor warning. When none of the conditions are met, this step is no-op.
102
+
103
+ AI must smart-detect long-term vs short-term project signals to gauge how proactively to look for (b)–(d) trigger conditions: long-term signals (session count ≥ 4, active objective shifting, multi-subtask SESSION_LOG entries, decisions list ≥ 10, user asking "why did we do X earlier") imply more proactive detection; short-term single-task projects keep this step as no-op default.
104
+
105
+ Skipping any required (a)–(d) action when its condition is met is what would cause the next AI session to lose the long-term narrative — do not repeat that pattern. Handoff capability still rests on `dev/SESSION_HANDOFF.md`; `dev/PROJECT_DECISIONS.md` is the long-term narrative archive that surfaces when users ask retrospective questions.
106
+
89
107
  Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
90
108
 
91
109
  Use this closeout card:
@@ -0,0 +1,34 @@
1
+ # Project Decisions Log
2
+
3
+ 這個檔保存項目的長期演進、決策、架構取捨與學習觀察 narrative。屬 warm 資料層 —— AI 開工**不需要讀**本檔。
4
+
5
+ 🔹 短期 single-task project:本檔保持近空,你不需要 maintain
6
+ 🔹 長期持續演進項目:AI 會自動 maintain;當你問「我們之前為何這樣做」時,AI 會在這裡找答案
7
+
8
+ 不需要你手動寫 —— AI 在收工時自動 update。
9
+
10
+ ---
11
+
12
+ ## Evolution Timeline
13
+
14
+ 任務需求演進的長期 narrative。Newest first。AI 觀察到 substantive task evolution 時 append。
15
+
16
+ (empty)
17
+
18
+ ## Decisions Archive
19
+
20
+ 由 SESSION_HANDOFF.md 的「Confirmed Decisions」或同類 decisions section 累積至 30+ 時,AI 自動 split 落這裡的舊條目。Newest first。
21
+
22
+ (empty)
23
+
24
+ ## Architecture Choices
25
+
26
+ 主要架構取捨與 rationale。AI 在 plan 涉及 multi-option trade-off 時 append,並等用戶 confirm。
27
+
28
+ (empty)
29
+
30
+ ## Insights & Learnings
31
+
32
+ 累積式學習、反思、觀察。AI 觀察到多 session 累積 pattern 時 append。
33
+
34
+ (empty)
@@ -4,6 +4,7 @@ Read only the packs needed for the current task.
4
4
 
5
5
  | Task signal | Pack | Purpose |
6
6
  |---|---|---|
7
+ | First-time user signals (任一即可): "I'm new" / "新手" / "教我用" / "help me start" / "first time" / "我啱啱安裝" / "點開始" / "show me how" / "getting started" / "agent handoff kit 可幫我做甚麼" / "我想做 [type] project" / "點用" / "能力" / vague first message ≤ 30 chars / HANDOFF Active Objective 空白 + Session count 1 (fresh installation context) | `dev/rules/onboarding.md` | first-time user walk-through with 5 scenarios (A 寫代碼 / B 研究報告 / C 知識庫 / D 學寫代碼 / E 其他) × 5-step pattern (PLAN-style: confirm context / explain v2 fit / ask task scope / suggest minimum viable / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
7
8
  | Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
8
9
  | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
9
10
  | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |