@adamchanadam/agent-handoff-kit 0.2.3 → 0.3.0
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 +303 -269
- package/bin/agent-handoff-kit.mjs +1434 -1285
- package/package.json +1 -1
- package/packs/integrations.md +179 -0
- package/packs/knowledge.md +35 -31
- package/packs/onboarding.md +389 -298
- package/packs/safety.md +37 -29
- package/runtime-core/AGENTS.core.md +153 -144
- package/runtime-core/PROJECT_INDEX.md +136 -93
- package/runtime-core/RULE_PACKS.md +20 -19
- package/runtime-core/SESSION_HANDOFF.md +151 -150
package/packs/safety.md
CHANGED
|
@@ -1,29 +1,37 @@
|
|
|
1
|
-
# Safety Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
-
|
|
7
|
-
## Rules
|
|
8
|
-
|
|
9
|
-
1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
|
|
10
|
-
2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
|
|
11
|
-
3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
|
|
12
|
-
4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. Report the blocker and manual action needed.
|
|
13
|
-
5. Do not run recursive or bulk destructive commands such as `rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, or equivalent cleanup operations unless the user explicitly requested the operation and resolved absolute targets are verified.
|
|
14
|
-
6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
|
|
15
|
-
7. On macOS / Linux, do not run `rm -rf`, `sudo rm`, recursive `chmod`, recursive `chown`, or destructive wildcard operations unless the user explicitly requested the operation and target paths are listed and verified.
|
|
16
|
-
8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
|
|
17
|
-
9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
|
|
18
|
-
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks.
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
1
|
+
# Safety Pack
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
+
|
|
7
|
+
## Rules
|
|
8
|
+
|
|
9
|
+
1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
|
|
10
|
+
2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
|
|
11
|
+
3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
|
|
12
|
+
4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. Report the blocker and manual action needed.
|
|
13
|
+
5. Do not run recursive or bulk destructive commands such as `rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, or equivalent cleanup operations unless the user explicitly requested the operation and resolved absolute targets are verified.
|
|
14
|
+
6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
|
|
15
|
+
7. On macOS / Linux, do not run `rm -rf`, `sudo rm`, recursive `chmod`, recursive `chown`, or destructive wildcard operations unless the user explicitly requested the operation and target paths are listed and verified.
|
|
16
|
+
8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
|
|
17
|
+
9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
|
|
18
|
+
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks. Differentiate three layers of external access (R-030 Integration governance; see `dev/rules/integrations.md`):
|
|
19
|
+
(a) Anthropic-vetted Connectors (e.g. Notion / Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server behavior; still verify destructive write parameters before invocation.
|
|
20
|
+
(b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against project-local runbook if available.
|
|
21
|
+
(c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
|
|
22
|
+
11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
|
|
23
|
+
12. Credential leak prevention (R-030 Integration governance):
|
|
24
|
+
(a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage (OS Keychain / Credential Manager / AI tool config) or env vars, never in `dev/*`.
|
|
25
|
+
(b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
|
|
26
|
+
(c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
|
|
27
|
+
(d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
|
|
28
|
+
|
|
29
|
+
## Checks
|
|
30
|
+
|
|
31
|
+
- Report which safety-relevant command, path, API, install, deploy, release, or Git check was performed and the result.
|
|
32
|
+
- If checks cannot run, state the reason and mark the result unverified.
|
|
33
|
+
- For durable governance changes, update the project index, sync registry, and any human review map if they exist.
|
|
34
|
+
|
|
35
|
+
## Closeout
|
|
36
|
+
|
|
37
|
+
Record unresolved safety risks, blocked verification, pending manual actions, dirty worktrees, or external sync gaps in `dev/SESSION_HANDOFF.md`.
|
|
@@ -1,144 +1,153 @@
|
|
|
1
|
-
# Agent Handoff Kit Core Runtime
|
|
2
|
-
|
|
3
|
-
This is the lightweight core. It is the always-read contract for AI sessions.
|
|
4
|
-
|
|
5
|
-
## 1. Startup Reads
|
|
6
|
-
|
|
7
|
-
After this core is loaded, read in order:
|
|
8
|
-
|
|
9
|
-
1. `dev/SESSION_HANDOFF.md`
|
|
10
|
-
2. the latest entry in `dev/SESSION_LOG.md`
|
|
11
|
-
3. `dev/PROJECT_INDEX.md`
|
|
12
|
-
4. `dev/RULE_PACKS.md`
|
|
13
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
19
|
-
|
|
20
|
-
If a required file is missing, create the smallest useful version only after confirming the target project root.
|
|
21
|
-
|
|
22
|
-
Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent.
|
|
23
|
-
|
|
24
|
-
After
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
1
|
+
# Agent Handoff Kit Core Runtime
|
|
2
|
+
|
|
3
|
+
This is the lightweight core. It is the always-read contract for AI sessions.
|
|
4
|
+
|
|
5
|
+
## 1. Startup Reads
|
|
6
|
+
|
|
7
|
+
After this core is loaded, read in order:
|
|
8
|
+
|
|
9
|
+
1. `dev/SESSION_HANDOFF.md`
|
|
10
|
+
2. the latest entry in `dev/SESSION_LOG.md`
|
|
11
|
+
3. `dev/PROJECT_INDEX.md`
|
|
12
|
+
4. `dev/RULE_PACKS.md`
|
|
13
|
+
|
|
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
|
+
|
|
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
|
+
|
|
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.
|
|
19
|
+
|
|
20
|
+
If a required file is missing, create the smallest useful version only after confirming the target project root.
|
|
21
|
+
|
|
22
|
+
Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent.
|
|
23
|
+
|
|
24
|
+
After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empty, run startup availability probe (R-030 Integration governance discipline; see `dev/rules/integrations.md`):
|
|
25
|
+
|
|
26
|
+
- For each declared Integration under Connectors / MCPs subsection, attempt minimal capability probe (e.g. for Notion: try `mcp__notion__search` with project DB name; for Drive: try `mcp__google-drive__list` with project folder).
|
|
27
|
+
- If probe succeeds: update the corresponding `Last Verified` cell to today's date; proceed normally.
|
|
28
|
+
- If probe fails (current AI tool lacks the Connector / auth expired / network issue): print warning in the startup card (`⚠️ Boundary` line) noting which Integration is declared-but-unavailable + that this session will fallback to paste flow when that external surface is touched. Do not attempt to auto-fix auth or credential issues; surface to the user to handle via the AI tool's own settings interface.
|
|
29
|
+
- Credential separation: AI must never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens). Credentials live in OS-level secure storage or AI-tool-specific config, never in `dev/*` files. Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) and redact + warn the user to rotate the token if accidentally pasted.
|
|
30
|
+
|
|
31
|
+
After startup reads are complete, show a short startup card:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
/\_/\ Agent Handoff Kit v<version>
|
|
35
|
+
( o.o ) continuity ready
|
|
36
|
+
> ^ <
|
|
37
|
+
|
|
38
|
+
🔎 Handoff: loaded
|
|
39
|
+
📌 Objective: <current objective>
|
|
40
|
+
⚠️ Boundary: <important boundary or none>
|
|
41
|
+
🚀 Next: <next action>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Keep the card short. Use the full product name, not an abbreviation. If the installed template or CLI version is unknown, write `version unverified` instead of guessing.
|
|
45
|
+
|
|
46
|
+
## 2. Work Loop
|
|
47
|
+
|
|
48
|
+
Use this loop for every task:
|
|
49
|
+
|
|
50
|
+
1. PLAN: restate the user's intent, scope, risk, and acceptance criteria.
|
|
51
|
+
2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
|
|
52
|
+
3. CHANGE: make focused changes only.
|
|
53
|
+
4. QC: run available checks or state why they cannot run.
|
|
54
|
+
5. PERSIST: update handoff/log and any affected project index or sync registry.
|
|
55
|
+
|
|
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
|
+
|
|
58
|
+
For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
|
|
59
|
+
|
|
60
|
+
## 2.1 Upgrade Done Contract
|
|
61
|
+
|
|
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
|
+
|
|
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 prompt mirror checks.
|
|
66
|
+
3. The migration report records every action taken, with backup paths for merged files.
|
|
67
|
+
|
|
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.
|
|
69
|
+
|
|
70
|
+
## 3. Safety Boundaries
|
|
71
|
+
|
|
72
|
+
Do not delete, reset, overwrite, bulk-move, or publish without explicit user approval.
|
|
73
|
+
|
|
74
|
+
Do not guess commands, APIs, SDK behavior, deployment steps, or file ownership when project docs or official docs are needed. Mark unverified facts as unverified.
|
|
75
|
+
|
|
76
|
+
Do not modify unrelated files. If unexpected user changes appear, work with them or ask before touching them.
|
|
77
|
+
|
|
78
|
+
Do not claim completion without evidence from checks, inspection, or a clear explanation of what could not be verified.
|
|
79
|
+
|
|
80
|
+
## 4. Closeout And Handoff
|
|
81
|
+
|
|
82
|
+
Detect end-of-session or handoff intent in natural language, such as "收工", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
|
|
83
|
+
|
|
84
|
+
At full closeout:
|
|
85
|
+
|
|
86
|
+
1. Reconcile `dev/SESSION_HANDOFF.md`. Do not append a new state snapshot under old state. Verify `Durable Anchors`, then rewrite or explicitly confirm every section under `Closeout-Reconciled State`.
|
|
87
|
+
2. Add a concise entry to `dev/SESSION_LOG.md` with work actually completed this session and the exact next-session opening message.
|
|
88
|
+
3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
|
|
89
|
+
4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
|
|
90
|
+
5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
|
|
91
|
+
6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, and whether the opening message matches current state.
|
|
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
|
+
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
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.
|
|
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
|
+
|
|
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):
|
|
99
|
+
|
|
100
|
+
(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).
|
|
101
|
+
|
|
102
|
+
(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`.
|
|
103
|
+
|
|
104
|
+
(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`.
|
|
105
|
+
|
|
106
|
+
(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`.
|
|
107
|
+
|
|
108
|
+
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.
|
|
109
|
+
|
|
110
|
+
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.
|
|
111
|
+
|
|
112
|
+
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.
|
|
113
|
+
|
|
114
|
+
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.
|
|
115
|
+
|
|
116
|
+
Use this closeout card:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
/\_/\ Agent Handoff Kit v<version>
|
|
120
|
+
( -.- ) handoff saved
|
|
121
|
+
> ^ <
|
|
122
|
+
|
|
123
|
+
✅ Done: <completed summary>
|
|
124
|
+
🔎 QC: <validation summary>
|
|
125
|
+
📌 Handoff: opening message ready
|
|
126
|
+
⚠️ Boundary: <important boundary or none>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Immediately before the fenced opening message, write:
|
|
130
|
+
|
|
131
|
+
```text
|
|
132
|
+
📋 Next session: copy and paste the whole block below
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Record only work actually performed in the current session. Do not copy old completed work forward as new work.
|
|
136
|
+
`dev/SESSION_HANDOFF.md` carries continuity. `dev/SESSION_LOG.md` carries recent evidence. Archive old detail only when needed; do not create an archive directory by default.
|
|
137
|
+
Do not declare handoff ready if `dev/SESSION_HANDOFF.md` still contains stale state, unreconciled placeholders in current-state sections, or an opening message that no longer matches the reconciled state.
|
|
138
|
+
|
|
139
|
+
## 5. Pack Loading
|
|
140
|
+
|
|
141
|
+
Use `dev/RULE_PACKS.md` to decide which pack to read.
|
|
142
|
+
|
|
143
|
+
A pack may add task-specific requirements. A pack cannot weaken core safety. If two packs conflict, choose the safer and more verifiable path, then record the conflict in closeout.
|
|
144
|
+
|
|
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
|
+
|
|
147
|
+
After the task, persist durable facts into handoff/log/index/registry. Do not assume the next session remembers pack context unless it is recorded.
|
|
148
|
+
|
|
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
|
+
|
|
151
|
+
## Core Complexity Rule
|
|
152
|
+
|
|
153
|
+
New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
|