@adamchanadam/agent-handoff-kit 0.3.34 → 0.3.36
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 +576 -247
- package/package.json +1 -1
- package/packs/agent-governance.md +17 -15
- package/packs/communication.md +2 -0
- package/packs/integrations.md +156 -120
- package/packs/onboarding.md +201 -393
- package/packs/safety.md +20 -18
- package/runtime-core/AGENTS.core.md +13 -13
- package/runtime-core/PROJECT_DECISIONS.md +7 -8
- package/runtime-core/PROJECT_INDEX.md +57 -47
- package/runtime-core/RULE_PACKS.md +6 -4
- package/runtime-core/SESSION_HANDOFF.md +9 -5
package/packs/safety.md
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
## Scope
|
|
4
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.
|
|
5
|
+
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, browser profiles, desktop app sessions, notebook kernels, local tool servers, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, user sessions, shared local resources, or external systems.
|
|
6
6
|
|
|
7
7
|
## Load When
|
|
8
8
|
|
|
9
9
|
- User requests deletion, overwrite, move, rename, cleanup, Git history changes, package installation, publish, deploy, release, cloud writes, external API calls, or credential handling.
|
|
10
|
-
- A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, or public release state.
|
|
10
|
+
- A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, browser profiles, desktop app sessions, notebook kernels, local tool servers, shared caches, or public release state.
|
|
11
11
|
- Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
|
|
12
12
|
|
|
13
13
|
## Rules
|
|
@@ -21,24 +21,26 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
21
21
|
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.
|
|
22
22
|
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.
|
|
23
23
|
9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
|
|
24
|
-
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools,
|
|
24
|
+
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, release tools, browser automation, DevTools, Playwright, crawlers, notebooks, desktop app automation, or local helper services, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or registered tool operation references for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
|
|
25
25
|
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
|
|
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, notebook kernels, 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; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, 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, desktop app session, notebook kernel, 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
|
|
|
@@ -43,13 +43,13 @@ Display version rule: after reading `dev/PROJECT_INDEX.md`, take the card versio
|
|
|
43
43
|
( o.o ) continuity ready
|
|
44
44
|
> ^ <
|
|
45
45
|
|
|
46
|
-
🔎 交接狀態:<loaded / new install / resumed>
|
|
47
|
-
📌 目前目標:<current objective>
|
|
48
|
-
⚠️ 注意事項:<important boundary or none>
|
|
49
|
-
🚀
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation.
|
|
46
|
+
🔎 交接狀態:<loaded / new install / resumed>
|
|
47
|
+
📌 目前目標:<current objective>
|
|
48
|
+
⚠️ 注意事項:<important boundary or none>
|
|
49
|
+
🚀 推薦下一步:<one recommended next action + short reason>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation. The next-step line must name the recommended action, not only list possible work. If there are several valid paths, state the best first action and the reason; offer choices only when the user must decide.
|
|
53
53
|
|
|
54
54
|
## 2. Work Loop
|
|
55
55
|
|
|
@@ -76,9 +76,9 @@ Use exactly one of these tiers after each task:
|
|
|
76
76
|
|
|
77
77
|
Task contract changes are durable facts when they affect future action. If the user adds or changes the product goal, requirements, development checklist, acceptance rules, exclusions, priority, or task scope during a long-running task, first reconcile those changes into one current task contract before continuing. If a dedicated spec, backlog, issue, runbook, or project document is already the authoritative home, update that home and cite it from `dev/SESSION_HANDOFF.md`; otherwise merge the current contract into `dev/SESSION_HANDOFF.md` under `Task Understanding Summary`, `Active Objective`, `Next Priorities`, and `Next Task Required Reading`. Do not scatter the same task contract across chat memory, log entries, draft docs, and startup prompts.
|
|
78
78
|
|
|
79
|
-
Route durable facts by file role:
|
|
80
|
-
|
|
81
|
-
- Current objective, next action, unresolved risk, blocker, or a fact needed at startup belongs in `dev/SESSION_HANDOFF.md`.
|
|
79
|
+
Route durable facts by file role:
|
|
80
|
+
|
|
81
|
+
- Current objective, recommended next action with reason, unresolved risk, blocker, or a fact needed at startup belongs in `dev/SESSION_HANDOFF.md`.
|
|
82
82
|
- Chronological evidence, command output, validation result, and research trace belongs in `dev/SESSION_LOG.md` when it affects future action or cannot be cheaply rerun. Routine successful checks that can be rerun are not durable facts.
|
|
83
83
|
- File maps, command maps, reference maps, source locations, and installed capability maps belong in `dev/PROJECT_INDEX.md`.
|
|
84
84
|
- Sync obligations across repositories, docs, mirrors, or external surfaces belong in `dev/DOC_SYNC_REGISTRY.md`.
|
|
@@ -126,7 +126,7 @@ Closeout Write Contract: before writing `dev/SESSION_HANDOFF.md`, `dev/SESSION_L
|
|
|
126
126
|
3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
|
|
127
127
|
4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
|
|
128
128
|
5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
|
|
129
|
-
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.
|
|
129
|
+
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, whether the recommended next step is explicit and reasoned, 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.
|
|
130
130
|
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.
|
|
131
131
|
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
132
132
|
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.
|
|
@@ -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,53 +54,63 @@ 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
|
|
99
|
-
|
|
100
|
-
##
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
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
|
+
|
|
100
|
+
## Tool Operation References
|
|
101
|
+
|
|
102
|
+
Use this section for project-local runbooks or verified procedures for runtime-controlled tools such as browser validation, screenshots, DevTools, Playwright, crawlers, notebooks, desktop app automation, MCP/plugin helpers, or raw CLI/SDK operations.
|
|
103
|
+
|
|
104
|
+
Do not store credential values or machine-private paths here. Local machine-only references may be listed only when the project explicitly depends on them, and the scope / limits must say they are not portable.
|
|
105
|
+
|
|
106
|
+
| Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
|
|
107
|
+
|---|---|---|---|---|---|
|
|
108
|
+
| TBD | TBD | TBD | TBD | TBD | TBD |
|
|
109
|
+
|
|
110
|
+
## Local QC Commands
|
|
111
|
+
|
|
112
|
+
| Check | Command | Run before | Last verified |
|
|
113
|
+
|---|---|---|---|
|
|
104
114
|
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
|
|
105
115
|
| Project governance check | Check newly created Markdown / durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence | closeout / durable file changes | unverified until project-specific command exists |
|
|
106
116
|
|
|
@@ -133,6 +143,6 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
133
143
|
|---|---|---|---|
|
|
134
144
|
| TBD | TBD | TBD | TBD |
|
|
135
145
|
|
|
136
|
-
## Maintenance Rule
|
|
137
|
-
|
|
138
|
-
Update this file when stack, commands, directory roles, entry points, external services, workspace identity, durable runbooks, or governance file map changes.
|
|
146
|
+
## Maintenance Rule
|
|
147
|
+
|
|
148
|
+
Update this file when stack, commands, directory roles, entry points, external services, runtime-controlled tool operation references, workspace identity, durable runbooks, or governance file map changes.
|
|
@@ -4,18 +4,20 @@ 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
|
+
| Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; block or use a manual packet when unavailable; preserve ownership and cleanup boundaries |
|
|
19
|
+
| 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 |
|
|
20
|
+
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
19
21
|
|
|
20
22
|
## Routing Rule
|
|
21
23
|
|
|
@@ -53,10 +53,12 @@ Record only work actually completed in the current session.
|
|
|
53
53
|
|
|
54
54
|
1. TBD
|
|
55
55
|
|
|
56
|
-
<!-- ack:section:next-priorities -->
|
|
57
|
-
## Next Priorities
|
|
58
|
-
|
|
59
|
-
|
|
56
|
+
<!-- ack:section:next-priorities -->
|
|
57
|
+
## Next Priorities
|
|
58
|
+
|
|
59
|
+
Recommended next step: TBD — reason: TBD
|
|
60
|
+
|
|
61
|
+
1. TBD
|
|
60
62
|
|
|
61
63
|
<!-- ack:section:next-task-required-reading -->
|
|
62
64
|
## Next Task Required Reading
|
|
@@ -113,6 +115,8 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
113
115
|
- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
|
|
114
116
|
<!-- ack:field:persistence-routing-checked -->
|
|
115
117
|
- Persistence routing checked: TBD
|
|
118
|
+
<!-- ack:field:recommended-next-step-explicit -->
|
|
119
|
+
- Recommended next step is explicit and reasoned: TBD
|
|
116
120
|
<!-- ack:field:opening-message-matches-current-state -->
|
|
117
121
|
- Opening message matches current state: TBD
|
|
118
122
|
<!-- ack:field:next-ai-can-continue -->
|
|
@@ -120,7 +124,7 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
120
124
|
|
|
121
125
|
If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
|
|
122
126
|
|
|
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.
|
|
127
|
+
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. Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision. 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.
|
|
124
128
|
|
|
125
129
|
<!-- ack:section:handoff-sufficiency-check -->
|
|
126
130
|
## Handoff Sufficiency Check
|