@adamchanadam/agent-handoff-kit 0.3.12 → 0.3.13
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 +2 -2
- package/bin/agent-handoff-kit.mjs +732 -693
- package/docs/whatsnew/v0.3.13.md +23 -0
- package/package.json +1 -1
- package/packs/agent-governance.md +2 -1
- package/runtime-core/AGENTS.core.md +2 -2
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# v0.3.13
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
本版修正升級後自動檢查失敗時的下一步提示。若 `upgrade` 已經執行,但自動 `doctor` 發現某個保留檔案真的缺少必要段落,CLI 會列出缺失檔案、檢查名稱與缺少文字,並給出交給 AI 非破壞性修補的步驟;不再只叫新手回頭跑 `upgrade --dry-run`。
|
|
6
|
+
|
|
7
|
+
同時,本版把可重用操作程序的歸位規則收斂到既有 `agent-governance` pack:長期操作方法應進入相關 rule pack 或已登記 reference,不應只寫入 handoff / log 當作完成。
|
|
8
|
+
|
|
9
|
+
## 對你已有檔案的影響
|
|
10
|
+
|
|
11
|
+
既有項目不用重裝。`START_NEXT_SESSION_PROMPT.txt` 仍只是 closeout 便利副本;若它只是落後於 `dev/SESSION_HANDOFF.md`,普通 `doctor` 只會提醒,不會把項目判定為失敗。
|
|
12
|
+
|
|
13
|
+
若升級後看到 anchor 缺失,代表某個保留檔案缺少 Kit 需要的固定段落。工具不會覆寫你的內容;你應把完整 `doctor` 輸出交給 AI,請它按缺失文字補回對應段落。
|
|
14
|
+
|
|
15
|
+
## 建議下一步
|
|
16
|
+
|
|
17
|
+
升級前可先預演:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
如果預演沒有 conflict,再執行正式升級。正式升級後若自動檢查失敗,請按 CLI 顯示的「怎樣修」步驟交給 AI 修補;不要把 `upgrade --dry-run` 當成修補動作。
|
package/package.json
CHANGED
|
@@ -16,7 +16,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
16
16
|
3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
|
|
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
|
-
6. Before creating durable workflow, runbook, or instruction files, first verify whether `dev/SESSION_HANDOFF.md
|
|
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
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
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.
|
|
22
22
|
|
|
@@ -26,6 +26,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
26
26
|
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
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
|
+
- 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.
|
|
29
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
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 closeout step 12 was applied where its trigger conditions were met.
|
|
31
32
|
|
|
@@ -51,7 +51,7 @@ Use this loop for every task:
|
|
|
51
51
|
2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
|
|
52
52
|
3. CHANGE: make focused changes only.
|
|
53
53
|
4. QC: run available checks or state why they cannot run.
|
|
54
|
-
5. PERSIST:
|
|
54
|
+
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 store reusable procedure knowledge only in handoff or log.
|
|
55
55
|
|
|
56
56
|
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.
|
|
57
57
|
|
|
@@ -144,7 +144,7 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
|
|
|
144
144
|
|
|
145
145
|
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.
|
|
146
146
|
|
|
147
|
-
After the task, persist durable facts into handoff
|
|
147
|
+
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, 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.
|
|
148
148
|
|
|
149
149
|
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.
|
|
150
150
|
|