@adamchanadam/agent-handoff-kit 0.3.11 → 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 +7 -3
- package/bin/agent-handoff-kit.mjs +705 -654
- package/docs/whatsnew/v0.3.12.md +19 -0
- 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 +4 -4
- package/runtime-core/PROJECT_INDEX.md +1 -1
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# v0.3.12
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
本版修正 `doctor` 對下次開工提示便利副本的判斷。`dev/SESSION_HANDOFF.md` 仍是權威;`START_NEXT_SESSION_PROMPT.txt` 只是給你下次開工複製用的副本,應在收工 closeout 時重新產生。
|
|
6
|
+
|
|
7
|
+
## 對你已有檔案的影響
|
|
8
|
+
|
|
9
|
+
既有項目不用重裝。若你在一個 session 中途更新了 handoff,但還未收工,`doctor` 不會再因便利副本暫時落後而判定項目失敗。它會提醒你:完成任務後請 AI 執行 closeout,屆時再重生便利副本。
|
|
10
|
+
|
|
11
|
+
## 建議下一步
|
|
12
|
+
|
|
13
|
+
升級前可先預演:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
如果預演沒有 conflict,再執行正式升級。升級後可用 `doctor` 檢查;若只有便利副本提醒,繼續工作即可,收工時再讓 AI 保存交接。
|
|
@@ -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
|
|
|
@@ -62,7 +62,7 @@ For high-risk work, pause after PLAN. High-risk means destructive operations, am
|
|
|
62
62
|
`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.
|
|
63
63
|
|
|
64
64
|
1. `AGENTS.md` health state is `clean`: exactly one `# Agent Handoff Kit Core Runtime` heading, exactly one paired managed-core marker block, and no unmarked stale core ranges. Sandwich states (managed marker plus an unmarked stale core) are not clean; the installer must replace the stale ranges, not skip.
|
|
65
|
-
2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, and
|
|
65
|
+
2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, handoff lifecycle checks, and credential separation checks. A `START_NEXT_SESSION_PROMPT.txt` convenience-copy warning does not block upgrade health; that file is regenerated at full closeout.
|
|
66
66
|
3. The migration report records every action taken, with backup paths for merged files.
|
|
67
67
|
|
|
68
68
|
If any check fails, the upgrade did not finish; resolve the failure (or hand the failure output to the user) before reporting completion. This contract is the single source of truth for upgrade success; downstream QA scripts and release-grade QA derive their assertions from it.
|
|
@@ -92,7 +92,7 @@ At full closeout:
|
|
|
92
92
|
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
93
|
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
94
94
|
9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
|
|
95
|
-
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.
|
|
95
|
+
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. 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.
|
|
96
96
|
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
97
|
|
|
98
98
|
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):
|
|
@@ -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
|
|
|
@@ -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 + prompt convenience copy
|
|
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 convenience copy regenerated from handoff at closeout |
|
|
127
127
|
|
|
128
128
|
## External Services
|
|
129
129
|
|