@adamchanadam/agent-handoff-kit 0.3.34 → 0.3.35
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 +352 -171
- package/package.json +1 -1
- package/packs/agent-governance.md +13 -13
- package/packs/integrations.md +142 -120
- package/packs/onboarding.md +201 -393
- package/packs/safety.md +17 -15
- package/runtime-core/AGENTS.core.md +2 -2
- package/runtime-core/PROJECT_DECISIONS.md +7 -8
- package/runtime-core/PROJECT_INDEX.md +39 -39
- package/runtime-core/RULE_PACKS.md +5 -4
package/packs/safety.md
CHANGED
|
@@ -26,19 +26,21 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
26
26
|
(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 current tool schema and project-local runbook if available.
|
|
27
27
|
(c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
|
|
28
28
|
11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
|
|
29
|
-
12. Credential leak prevention (R-030 Integration governance):
|
|
29
|
+
12. Credential leak prevention (R-030 Integration governance):
|
|
30
30
|
(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 credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
|
|
31
|
-
(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.
|
|
32
|
-
(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.
|
|
33
|
-
(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).
|
|
34
|
-
13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
31
|
+
(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.
|
|
32
|
+
(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.
|
|
33
|
+
(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).
|
|
34
|
+
13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
|
|
35
|
+
14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
|
|
36
|
+
|
|
37
|
+
## Checks
|
|
38
|
+
|
|
39
|
+
- Report which safety-relevant command, path, API, install, deploy, release, or Git check was performed and the result.
|
|
40
|
+
- If checks cannot run, state the reason and mark the result unverified.
|
|
41
|
+
- For durable governance changes, update the project index, sync registry, and any human review map if they exist.
|
|
42
|
+
- For external-tool resource cleanup, report the ownership class used: task-owned, agent-managed, shared / user-owned / other-agent-owned / system-level, or unknown.
|
|
43
|
+
|
|
44
|
+
## Closeout
|
|
45
|
+
|
|
46
|
+
Record unresolved safety risks, blocked verification, pending manual actions, dirty worktrees, or external sync gaps in `dev/SESSION_HANDOFF.md`.
|
|
@@ -13,7 +13,7 @@ After this core is loaded, read in order:
|
|
|
13
13
|
|
|
14
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
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,
|
|
16
|
+
Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, contains onboarding signal keywords such as "I'm new", "help me start", "first time", "I just installed", "how do I start", "show me how", or equivalent Chinese phrases such as "新手", "教我用", "我剛安裝", "點開始", 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-F selection instead of immediately diving into task execution. Onboarding is a transient pack: after the user completes the first-task walk-through, unload it and load the regular scenario pack (coding / research / writing / knowledge / etc.) for ongoing work.
|
|
17
17
|
|
|
18
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
19
|
|
|
@@ -137,7 +137,7 @@ Closeout Write Contract: before writing `dev/SESSION_HANDOFF.md`, `dev/SESSION_L
|
|
|
137
137
|
|
|
138
138
|
(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.
|
|
139
139
|
|
|
140
|
-
(b) Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline when `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section
|
|
140
|
+
(b) Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline when `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section, for example `## Confirmed Decisions`, `## Decisions`, or a localized equivalent, with a numbered list of at least 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.
|
|
141
141
|
|
|
142
142
|
(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.
|
|
143
143
|
|
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
# Project Decisions Log
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
🔹 長期持續演進項目:AI 會在收工時先做維護觸發檢查;命中觸發或到定期兜底時才完整整理。當你問「我們之前為何這樣做」時,AI 會在這裡找答案
|
|
5
|
+
Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
|
|
9
8
|
|
|
10
9
|
Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
|
|
11
10
|
|
|
@@ -21,24 +20,24 @@ This file does not store raw build / upload / QC evidence, current next actions,
|
|
|
21
20
|
|
|
22
21
|
## Evolution Timeline
|
|
23
22
|
|
|
24
|
-
|
|
23
|
+
Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
|
|
25
24
|
|
|
26
25
|
(empty)
|
|
27
26
|
|
|
28
27
|
## Decisions Archive
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
|
|
31
30
|
|
|
32
31
|
(empty)
|
|
33
32
|
|
|
34
33
|
## Architecture Choices
|
|
35
34
|
|
|
36
|
-
|
|
35
|
+
Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
|
|
37
36
|
|
|
38
37
|
(empty)
|
|
39
38
|
|
|
40
39
|
## Insights & Learnings
|
|
41
40
|
|
|
42
|
-
|
|
41
|
+
Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
|
|
43
42
|
|
|
44
43
|
(empty)
|
|
@@ -54,48 +54,48 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
54
54
|
|---|---|---|---|---|---|---|
|
|
55
55
|
| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Google Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
|
|
56
56
|
|
|
57
|
-
> `via` column
|
|
57
|
+
> `via` column discipline: every External Sources row must reference an entry name under `## Installed Integrations`, such as `Notion Connector` or `Google Drive Connector`, so the access path is explicit. Sources without a declared integration use `manual paste`. Doctor and release QA enforce cross-section consistency.
|
|
58
58
|
|
|
59
59
|
## Installed Integrations
|
|
60
60
|
|
|
61
|
-
>
|
|
62
|
-
|
|
63
|
-
>
|
|
64
|
-
|
|
65
|
-
### Connectors
|
|
66
|
-
|
|
67
|
-
| Tool | Project Usage | Access Scope | Specific Instance | Credential Reference
|
|
68
|
-
|------|---------------|--------------|-------------------|---------------------|----------|---------------|
|
|
69
|
-
| TBD | TBD
|
|
70
|
-
|
|
71
|
-
### MCPs
|
|
72
|
-
|
|
73
|
-
| Server | Source | Project Usage | Credential Reference
|
|
74
|
-
|--------|--------|---------------|---------------------|----------|---------------|
|
|
75
|
-
| TBD | TBD
|
|
76
|
-
|
|
77
|
-
### Plugins
|
|
78
|
-
|
|
79
|
-
| Name | Bundle Content
|
|
80
|
-
|------|----------------------------------------|----------------|---------------|
|
|
81
|
-
| TBD | TBD | TBD | TBD |
|
|
82
|
-
|
|
83
|
-
### Skills
|
|
84
|
-
|
|
85
|
-
| Name | Source | When Triggered | Last Verified |
|
|
86
|
-
|------|--------|----------------|---------------|
|
|
87
|
-
| TBD | TBD
|
|
88
|
-
|
|
89
|
-
### Source-of-truth Architecture
|
|
90
|
-
|
|
91
|
-
>
|
|
92
|
-
|
|
93
|
-
| Layer | Surface
|
|
94
|
-
|-------|--------------------------|------|-----------------|
|
|
95
|
-
|
|
|
96
|
-
| Index | TBD
|
|
97
|
-
|
|
|
98
|
-
| Working draft | TBD
|
|
61
|
+
> **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.
|
|
62
|
+
|
|
63
|
+
> Purpose: a new AI session reads this section to understand declared external-tool capabilities and their project roles. Declarations persist across sessions. Every entry must include `Declared` and `Last Verified` fields so stale capability assumptions can be detected.
|
|
64
|
+
|
|
65
|
+
### Connectors
|
|
66
|
+
|
|
67
|
+
| Tool | Project Usage | Access Scope | Specific Instance | Credential Reference (no value) | Declared | Last Verified |
|
|
68
|
+
|------|---------------|--------------|-------------------|---------------------|----------|---------------|
|
|
69
|
+
| TBD | TBD, for example an index of source paths or persistent reference storage | read / read+write | TBD, for example database name + URL or folder path | TBD, for example `AI tool secure storage` / `OS credential store` | TBD | TBD |
|
|
70
|
+
|
|
71
|
+
### MCPs
|
|
72
|
+
|
|
73
|
+
| Server | Source | Project Usage | Credential Reference (no value) | Declared | Last Verified |
|
|
74
|
+
|--------|--------|---------------|---------------------|----------|---------------|
|
|
75
|
+
| TBD | TBD, for example GitHub repository URL | TBD | TBD, for example `tool config + env var name only` / `user-managed secret store` | TBD | TBD |
|
|
76
|
+
|
|
77
|
+
### Plugins
|
|
78
|
+
|
|
79
|
+
| Name | Bundle Content (Skills + MCP + hooks) | When Triggered | Last Verified |
|
|
80
|
+
|------|----------------------------------------|----------------|---------------|
|
|
81
|
+
| TBD | TBD | TBD | TBD |
|
|
82
|
+
|
|
83
|
+
### Skills
|
|
84
|
+
|
|
85
|
+
| Name | Source | When Triggered | Last Verified |
|
|
86
|
+
|------|--------|----------------|---------------|
|
|
87
|
+
| TBD | TBD, for example plugin bundle or user-level install | TBD | TBD |
|
|
88
|
+
|
|
89
|
+
### Source-of-truth Architecture
|
|
90
|
+
|
|
91
|
+
> When a project uses several integrations as a source-of-truth system, for example Notion index + local primary sources + Google Drive reference mirror, this table records each layer's role so agents do not cross write boundaries.
|
|
92
|
+
|
|
93
|
+
| Layer | Surface (specific instance) | Role | Write Direction |
|
|
94
|
+
|-------|--------------------------|------|-----------------|
|
|
95
|
+
| Source of truth | TBD, for example local `~/project/reference/` | Original auditable reference content | User-controlled placement; agent does not write directly unless explicitly authorized |
|
|
96
|
+
| Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |
|
|
97
|
+
| Persistent mirror | TBD, for example Drive folder `Project Reference/` | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically |
|
|
98
|
+
| Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |
|
|
99
99
|
|
|
100
100
|
## Local QC Commands
|
|
101
101
|
|
|
@@ -4,18 +4,19 @@ Read only the packs needed for the current task.
|
|
|
4
4
|
|
|
5
5
|
| Task signal | Pack | Purpose |
|
|
6
6
|
|---|---|---|
|
|
7
|
-
| First-time user signals
|
|
7
|
+
| First-time user signals: "I'm new" / "new user" / "teach me" / "help me start" / "first time" / "I just installed" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do" / vague first message <= 30 chars / HANDOFF Active Objective empty + Session count 1 (fresh installation context). Also recognize equivalent Chinese user phrases such as "新手", "教我用", "我剛安裝", "點開始", "開工", and "能力". | `dev/rules/onboarding.md` | first-time user walk-through with 6 scenarios (A build / B research report / C knowledge base / D learning to code / E custom / F external-tool governance) x 5-step pattern (confirm context / explain fit / ask task scope / suggest minimum viable task / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
|
|
8
8
|
| Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
|
|
9
9
|
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
10
10
|
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
11
11
|
| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
|
|
12
12
|
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
13
|
-
| Governance bridge /
|
|
14
|
-
| Long-term governance routing /
|
|
13
|
+
| Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
14
|
+
| Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
|
|
15
15
|
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
16
16
|
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
17
17
|
| External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Google Drive / Slack / Linear / Dropbox / HubSpot / GitHub / etc. external read-write | `dev/rules/integrations.md` | Connector-first default + credential separation + multi-layer source-of-truth + cross-session resilience |
|
|
18
|
-
|
|
|
18
|
+
| External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
|
|
19
|
+
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
19
20
|
|
|
20
21
|
## Routing Rule
|
|
21
22
|
|