@adamchanadam/agent-handoff-kit 0.3.24 → 0.3.25

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.24`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.25`。這是早期可用版本,仍在持續完善中。
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
 
@@ -45,7 +45,7 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
45
45
 
46
46
  ![Agent Handoff Kit 新手流程](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-new-user-flow.png)
47
47
 
48
- 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
48
+ 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。準備結束本輪工作時說「收工」,讓 AI 留下下一次能接上的交接。
49
49
 
50
50
  ### 適用工具
51
51
 
@@ -97,6 +97,8 @@ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
97
97
 
98
98
  `@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
99
99
 
100
+ 正式升級最後會自動做一次 `doctor` 健康檢查。若檔案已是最新版本,但交接狀態仍需要處理,工具會列出需要修正的位置;若屬於工具可安全判斷的 Kit 結構或提示副本問題,會先自動修復再檢查。
101
+
100
102
  看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
101
103
 
102
104
  即使目前資料夾已安裝舊版 Kit 文件,電腦也未必已經有可直接執行的 npm 工具。判斷點不是資料夾有沒有 `AGENTS.md` 或 `dev/`,而是你是否用上方 `npx --yes ... @latest` 路徑取得最新工具。裸寫不帶 `--yes` / `@latest` 的 `npx ... doctor` 不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
@@ -127,7 +129,7 @@ Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff.
127
129
 
128
130
  ### 三、收工
129
131
 
130
- 工作完成想結束時,只需輸入:
132
+ 本輪工作完成、準備結束時,只需輸入:
131
133
 
132
134
  ```text
133
135
  收工
@@ -283,7 +285,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
283
285
 
284
286
  ## 目前限制
285
287
 
286
- - 目前版本為 `v0.3.24`;正式安裝請以 npm registry `latest` 顯示為準。
288
+ - 目前版本為 `v0.3.25`;正式安裝請以 npm registry `latest` 顯示為準。
287
289
  - 這是早期可用版本,仍在持續完善中。
288
290
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
289
291
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.24",
3
+ "version": "0.3.25",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -17,7 +17,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
17
17
  4. Do not let development-only workspace rules enter public runtime.
18
18
  5. Check complexity budget before adding default-core behavior.
19
19
  6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
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.
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 the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
21
21
  8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
22
22
 
23
23
  ## Checks
@@ -27,7 +27,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
27
27
  - Confirm old overlapping wording was retired or marked legacy.
28
28
  - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
29
29
  - Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
30
- - 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
+ - Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
31
31
  - 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 the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
32
32
 
33
33
  ## Closeout
@@ -57,13 +57,32 @@ Use this loop for every task:
57
57
  2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
58
58
  3. CHANGE: make focused changes only.
59
59
  4. QC: run available checks or state why they cannot run.
60
- 5. PERSIST: classify durable facts before writing them. Current state belongs in handoff, chronological evidence in log, file / command / reference maps in project index, sync obligations in doc sync registry, and reusable operating procedure in the relevant rule pack or registered reference. Do not persist one-time delivery instructions, historical validation evidence, old hashes, old version facts, or incident notes as current state, next priorities, durable anchors, or startup instructions. Do not store reusable procedure knowledge only in handoff or log.
61
-
62
- External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence step for the active project root, and completion cannot be claimed until that root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md` have been inspected and updated or explicitly marked not applicable.
63
-
64
- For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
65
-
66
- ## 2.1 Upgrade Done Contract
60
+ 5. PERSISTENCE GATE: decide whether this task produced a durable fact before writing governance files. A durable fact is information the next agent cannot reliably reconstruct and that affects future action.
61
+
62
+ External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence-gate check for the active project root, and completion cannot be claimed until that check is answered at the correct tier.
63
+
64
+ For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
65
+
66
+ ## 2.1 Persistence Gate
67
+
68
+ Use exactly one of these tiers after each task:
69
+
70
+ 1. No persistence: choose this when the task produced no durable fact. Examples: one-off answers, active draft / image iterations not approved as final, routine successful checks that can be rerun, transient tool output, and ordinary progress that remains visible in the current chat.
71
+ 2. Lightweight checkpoint: choose this when a durable fact exists and the session continues, when the agent may be interrupted before full closeout, or when uncertain whether the fact is durable. Write only the smallest correct home. Lightweight checkpoint is not full closeout: do not regenerate `START_NEXT_SESSION_PROMPT.txt`, do not show a closeout card, do not run full closeout maintenance, and do not reconcile every handoff section unless the fact itself requires it.
72
+ 3. Full closeout: choose this only for explicit end-of-session / handoff intent, tool or day boundary, user-requested handoff, agent about to stop, or completed release / external sync / governance change that needs the next agent to continue from persisted state.
73
+
74
+ Route durable facts by file role:
75
+
76
+ - Current objective, next action, unresolved risk, blocker, or a fact needed at startup belongs in `dev/SESSION_HANDOFF.md`.
77
+ - Chronological evidence, command output, validation result, and research trace belongs in `dev/SESSION_LOG.md` when it affects future action or cannot be cheaply rerun. Routine successful checks that can be rerun are not durable facts.
78
+ - File maps, command maps, reference maps, source locations, and installed capability maps belong in `dev/PROJECT_INDEX.md`.
79
+ - Sync obligations across repositories, docs, mirrors, or external surfaces belong in `dev/DOC_SYNC_REGISTRY.md`.
80
+ - Long-term decisions, architecture trade-offs, durable rationale, and research-derived decisions belong in `dev/PROJECT_DECISIONS.md`. Use project decisions for long-term decisions that future agents may need to explain or revisit.
81
+ - Reusable operating procedures and practice-to-mechanism lessons belong in the relevant rule pack, registered reference, or QA check. Do not store reusable procedure knowledge only in handoff or log.
82
+
83
+ Do not persist one-time delivery instructions, old hashes, old version facts, incident notes, routine green validation, or unapproved draft status as current state, next priorities, durable anchors, or startup instructions. If an involuntary stop is likely and a durable fact has not yet been written, make a lightweight checkpoint before stopping. If uncertain whether a fact is durable, choose lightweight checkpoint.
84
+
85
+ ## 2.2 Upgrade Done Contract
67
86
 
68
87
  `agent-handoff-kit upgrade` is considered complete only when all of the following hold. The CLI enforces this contract; do not declare upgrade success without it.
69
88
 
@@ -152,9 +171,9 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
152
171
 
153
172
  When a task references external tools (Notion / Google Drive / Slack / Linear / GitHub / Dropbox / HubSpot / Atlassian / etc.) or `dev/PROJECT_INDEX.md` `## Installed Integrations` is non-empty, load `dev/rules/integrations.md` together with the relevant domain pack. The integrations pack covers Connector-first defaults, credential separation, multi-layer source-of-truth architecture, and cross-session resilience for declared integrations.
154
173
 
155
- After the task, persist durable facts into the correct home: handoff for current state, log for trace evidence, project index for file / command / reference maps, doc sync registry for sync obligations, project decisions for long-term decisions or research-derived rationale, and rule packs or registered references for reusable operating procedures. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
156
-
157
- If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs Agent Handoff Kit persistence before the task is complete.
174
+ After the task, apply the Persistence Gate in Section 2.1. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
175
+
176
+ If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs the Section 2.1 persistence-gate decision before the task is complete.
158
177
 
159
178
  ## Core Complexity Rule
160
179