@adamchanadam/agent-handoff-kit 0.3.21 → 0.3.23
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 +849 -157
- package/package.json +1 -1
- package/packs/research.md +2 -0
- package/runtime-core/AGENTS.core.md +14 -10
- package/runtime-core/PROJECT_DECISIONS.md +10 -0
- package/runtime-core/SESSION_HANDOFF.md +3 -1
- package/runtime-core/SESSION_LOG.md +1 -0
package/package.json
CHANGED
package/packs/research.md
CHANGED
|
@@ -26,3 +26,5 @@ Use for source gathering, evidence comparison, fact synthesis, recommendations,
|
|
|
26
26
|
## Closeout
|
|
27
27
|
|
|
28
28
|
Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
|
|
29
|
+
|
|
30
|
+
If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
|
|
@@ -34,6 +34,8 @@ After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empt
|
|
|
34
34
|
|
|
35
35
|
After startup reads are complete, show one short startup card. If onboarding is loaded, combine this card and the onboarding choice list into one first response. Do not print any standalone startup card before the onboarding rule has been read. Do not print a partial card. Do not print the cat banner twice. If you started drafting a card and then discovered onboarding applies, discard the draft and output only the final combined response.
|
|
36
36
|
|
|
37
|
+
Display version rule: after reading `dev/PROJECT_INDEX.md`, take the card version from the `## Stack` row `Agent Handoff Kit template version`. Print it as `vX.Y.Z`. If that row is missing, unreadable, or not a version, print `version unverified`. Never print the literal placeholder `v<version>` in user-facing startup or closeout output.
|
|
38
|
+
|
|
37
39
|
```text
|
|
38
40
|
/\_/\ Agent Handoff Kit v<version>
|
|
39
41
|
( o.o ) continuity ready
|
|
@@ -45,7 +47,7 @@ After startup reads are complete, show one short startup card. If onboarding is
|
|
|
45
47
|
🚀 下一步:<next action>
|
|
46
48
|
```
|
|
47
49
|
|
|
48
|
-
Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation.
|
|
50
|
+
Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation.
|
|
49
51
|
|
|
50
52
|
## 2. Work Loop
|
|
51
53
|
|
|
@@ -55,7 +57,7 @@ Use this loop for every task:
|
|
|
55
57
|
2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
|
|
56
58
|
3. CHANGE: make focused changes only.
|
|
57
59
|
4. QC: run available checks or state why they cannot run.
|
|
58
|
-
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.
|
|
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.
|
|
59
61
|
|
|
60
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.
|
|
61
63
|
|
|
@@ -94,7 +96,7 @@ At full closeout:
|
|
|
94
96
|
3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
|
|
95
97
|
4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
|
|
96
98
|
5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
|
|
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.
|
|
99
|
+
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 the `Persistence routing checked` field is complete, 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.
|
|
98
100
|
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.
|
|
99
101
|
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
100
102
|
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.
|
|
@@ -103,11 +105,11 @@ At full closeout:
|
|
|
103
105
|
|
|
104
106
|
Hard triggers:
|
|
105
107
|
|
|
106
|
-
(a) Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline) when `dev/SESSION_LOG.md` reaches N ≥ 11 entries, or when the main log exceeds 1500 lines. If triggered, move N ≥ 11 entries into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved, maintain `dev/SESSION_LOG_archive/INDEX.md`, collapse absorbed N=4–10 entries to short-index lines, and port any unique narrative into the relevant durable source before collapsing it. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
|
|
108
|
+
(a) Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline) when `dev/SESSION_LOG.md` reaches N ≥ 11 entries, or when the main log exceeds 1500 lines. If triggered, move N ≥ 11 entries into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved, maintain `dev/SESSION_LOG_archive/INDEX.md`, collapse absorbed N=4–10 entries to short-index lines, and port any unique narrative into the relevant durable source before collapsing it. If a research trail affected a long-term decision, public claim, strategy, governance rule, or material selection, port its evidence chain into `dev/PROJECT_DECISIONS.md` using that file's research-derived decision format before collapsing the log. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
|
|
107
109
|
|
|
108
110
|
(b) Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline when `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section (e.g. `## Confirmed Decisions`, `## Decisions`, `## 已定案決策`) with a numbered list of ≥ 30 entries. If triggered, split the oldest entries, retaining the most recent 8–22 in the handoff hot tier, into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first.
|
|
109
111
|
|
|
110
|
-
(c) Append to `dev/PROJECT_DECISIONS.md` immediately, or at closeout, when the current session includes substantive task evolution, a multi-option architectural trade-off with recorded rationale, a cross-session accumulated pattern, or a user retrospective question. Use `## Evolution Timeline`, `## Architecture Choices`, or `## Insights & Learnings` as appropriate.
|
|
112
|
+
(c) Append to `dev/PROJECT_DECISIONS.md` immediately, or at closeout, when the current session includes substantive task evolution, a multi-option architectural trade-off with recorded rationale, a cross-session accumulated pattern, or a user retrospective question. Use `## Evolution Timeline`, `## Architecture Choices`, or `## Insights & Learnings` as appropriate. If the decision is research-derived, use that file's evidence-chain format so the source, summary, inference, decision impact, and uncertainty survive future compression.
|
|
111
113
|
|
|
112
114
|
(d) Run a full long-term maintenance pass every 10 closeouts as a backstop, even if no trigger seems obvious. Count closeouts from the main `dev/SESSION_LOG.md` entries plus archive index entry counts when an archive exists; if the count cannot be determined confidently, treat the current N=10 boundary as the backstop trigger.
|
|
113
115
|
|
|
@@ -115,10 +117,12 @@ At full closeout:
|
|
|
115
117
|
|
|
116
118
|
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.
|
|
117
119
|
|
|
118
|
-
Use this closeout card:
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
120
|
+
Use this closeout card:
|
|
121
|
+
|
|
122
|
+
Use the same display version rule as startup: take the version from `dev/PROJECT_INDEX.md` `## Stack` row `Agent Handoff Kit template version`, print it as `vX.Y.Z`, and fall back to `version unverified` only when it cannot be verified. Never print the literal placeholder `v<version>`.
|
|
123
|
+
|
|
124
|
+
```text
|
|
125
|
+
/\_/\ Agent Handoff Kit v<version>
|
|
122
126
|
( -.- ) handoff saved
|
|
123
127
|
> ^ <
|
|
124
128
|
|
|
@@ -146,7 +150,7 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
|
|
|
146
150
|
|
|
147
151
|
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.
|
|
148
152
|
|
|
149
|
-
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.
|
|
153
|
+
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.
|
|
150
154
|
|
|
151
155
|
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.
|
|
152
156
|
|
|
@@ -7,6 +7,16 @@
|
|
|
7
7
|
|
|
8
8
|
不需要你手動寫 —— AI 在收工時自動 update;重大決策可在發生時即時記錄,不必等到最後才回想。
|
|
9
9
|
|
|
10
|
+
Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
- YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
|
|
17
|
+
|
|
18
|
+
This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
|
|
19
|
+
|
|
10
20
|
---
|
|
11
21
|
|
|
12
22
|
## Evolution Timeline
|
|
@@ -111,6 +111,8 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
111
111
|
- Stale snapshots left in this handoff: TBD
|
|
112
112
|
<!-- ack:field:lifecycle-conflicts-resolved -->
|
|
113
113
|
- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
|
|
114
|
+
<!-- ack:field:persistence-routing-checked -->
|
|
115
|
+
- Persistence routing checked: TBD
|
|
114
116
|
<!-- ack:field:opening-message-matches-current-state -->
|
|
115
117
|
- Opening message matches current state: TBD
|
|
116
118
|
<!-- ack:field:next-ai-can-continue -->
|
|
@@ -118,7 +120,7 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
118
120
|
|
|
119
121
|
If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
|
|
120
122
|
|
|
121
|
-
Lifecycle consistency rule: 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.
|
|
123
|
+
Lifecycle consistency rule: 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. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.
|
|
122
124
|
|
|
123
125
|
<!-- ack:section:handoff-sufficiency-check -->
|
|
124
126
|
## Handoff Sufficiency Check
|
|
@@ -20,6 +20,7 @@ Before closeout, record whether older log detail was kept, summarized, or archiv
|
|
|
20
20
|
- **Changed:** <files changed, or none>
|
|
21
21
|
- **Done:** <work completed this session>
|
|
22
22
|
- **QC:** <checks run and results, or why not run>
|
|
23
|
+
- **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
|
|
23
24
|
- **Sync:** <doc/external sync status>
|
|
24
25
|
- **Pending:** <next work>
|
|
25
26
|
- **Risks:** <known risks or none>
|