@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/package.json
CHANGED
|
@@ -8,8 +8,8 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
8
8
|
|
|
9
9
|
- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
|
|
10
10
|
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
|
-
- User asks to "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", "掃描未接入 Agent Handoff Kit 的重要文件"
|
|
12
|
-
- User asks to make something long-term, cross-session, reusable,
|
|
11
|
+
- User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
12
|
+
- User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
|
|
13
13
|
- The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
|
|
14
14
|
|
|
15
15
|
## Rules
|
|
@@ -23,14 +23,14 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
23
23
|
7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
|
|
24
24
|
8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
|
|
25
25
|
9. Governance bridge is a triggered review, not a default startup scan. Use it when an important file, source-of-truth document, runbook, production guide, workflow, checklist, stock list, or similar durable document may need to be connected to project governance.
|
|
26
|
-
10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not
|
|
26
|
+
10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
|
|
27
27
|
11. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
|
|
28
28
|
12. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
|
|
29
29
|
13. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
|
|
30
30
|
|
|
31
31
|
## Governance Bridge Workflow
|
|
32
32
|
|
|
33
|
-
Use this workflow when the user asks for governance bridge
|
|
33
|
+
Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
34
34
|
|
|
35
35
|
1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.
|
|
36
36
|
2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.
|
|
@@ -43,6 +43,15 @@ Use this workflow when the user asks for governance bridge / 治理打通 / 把
|
|
|
43
43
|
|
|
44
44
|
For repo-wide scans, report candidates as candidates. Do not fail ordinary docs merely because they are not indexed; only durable files that future agents need to discover, update, or distinguish from drafts should be bridged.
|
|
45
45
|
|
|
46
|
+
Output format:
|
|
47
|
+
|
|
48
|
+
- Status: bridged / partially bridged / unbridged / blocked.
|
|
49
|
+
- Already bridged: list the governance links that are present.
|
|
50
|
+
- Gaps: list missing links and why they matter for the next agent.
|
|
51
|
+
- Suggested patches: list exact files and sections to update.
|
|
52
|
+
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
53
|
+
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
54
|
+
|
|
46
55
|
## Generated Artifact Governance Workflow
|
|
47
56
|
|
|
48
57
|
Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
|
|
@@ -73,15 +82,6 @@ Use this workflow when the user asks to write something into long-term governanc
|
|
|
73
82
|
4. Add or update a QA check when the same failure class could recur and can be tested.
|
|
74
83
|
5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
|
|
75
84
|
|
|
76
|
-
Output format:
|
|
77
|
-
|
|
78
|
-
- Status: bridged / partially bridged / unbridged / blocked.
|
|
79
|
-
- Already bridged: list the governance links that are present.
|
|
80
|
-
- Gaps: list missing links and why they matter for the next agent.
|
|
81
|
-
- Suggested patches: list exact files and sections to update.
|
|
82
|
-
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
83
|
-
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
84
|
-
|
|
85
85
|
## Checks
|
|
86
86
|
|
|
87
87
|
- Verify affected files are indexed or intentionally installed templates.
|
package/packs/integrations.md
CHANGED
|
@@ -2,42 +2,43 @@
|
|
|
2
2
|
|
|
3
3
|
## Scope
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Use this pack for governance of already-installed external tool integrations: **Connectors** (official or platform-vetted MCP servers), **MCPs** (community or custom MCP servers), **Plugins** (bundles that may register skills, MCP servers, hooks, or apps), and **Skills** (`SKILL.md` instruction sets).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
When a task touches external sources or external write surfaces such as Notion, Google Drive, Dropbox, Slack, Linear, GitHub, HubSpot, browsers, crawlers, notebooks, or local helper services, this pack makes the agent check declared integrations first, prefer direct runtime access when available, and fall back to manual packets only when the integration is unavailable.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
This pack does not teach users how to install tools. Installation is handled by the user's AI runtime, tool vendor, or official documentation. This pack governs what happens after a tool is already installed: declaration, verification, safe use, resource lifecycle, drift handling, and cross-session continuity.
|
|
10
10
|
|
|
11
11
|
## Load When
|
|
12
12
|
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
13
|
+
- The task mentions Notion, Google Drive, Slack, Linear, Dropbox, HubSpot, GitHub, browser automation, crawlers, notebooks, local helper services, or other external tools.
|
|
14
|
+
- The user asks whether the agent can directly read or write an external system.
|
|
15
|
+
- `dev/PROJECT_INDEX.md` has a non-empty `## Installed Integrations` section.
|
|
16
|
+
- First-time onboarding asks the user to declare installed external tools.
|
|
17
|
+
- The project uses a multi-layer source-of-truth setup, for example Notion index + local source files + Google Drive reference mirrors.
|
|
18
|
+
- The user reports resource pressure, stale MCP or plugin services, browser automation left running, cache growth, or slowdown after external-tool use.
|
|
18
19
|
|
|
19
20
|
## Discipline
|
|
20
21
|
|
|
21
|
-
### 1.
|
|
22
|
+
### 1. Credential Separation Principle
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
Credential values such as API keys, OAuth tokens, app secrets, and refresh tokens belong only in AI runtime secure storage, OS credential stores, tool configuration, environment indirection, or user-managed secret stores. Agent Handoff Kit files may record credential references, never credential values.
|
|
24
25
|
|
|
25
|
-
|
|
|
26
|
-
|
|
27
|
-
| AI
|
|
28
|
-
| OS credential store | macOS Keychain
|
|
29
|
-
| Tool config / env indirection |
|
|
30
|
-
| User-managed secret store |
|
|
26
|
+
| Storage layer | Examples | What Kit files may record |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| AI runtime secure storage / Connector storage | Notion, Slack, Linear, Google Drive, Atlassian, HubSpot, or similar connectors | Storage type or connector name only |
|
|
29
|
+
| OS credential store | macOS Keychain, Windows Credential Manager, Linux secret service | `OS credential store` only |
|
|
30
|
+
| Tool config / env indirection | AI tool MCP config, plugin config, environment variable name | Config location or env var name only; never the value |
|
|
31
|
+
| User-managed secret store | Team vault or secret manager | Store type or owner only |
|
|
31
32
|
|
|
32
|
-
|
|
33
|
+
No file under `dev/` should contain a credential value. Enforce three rules:
|
|
33
34
|
|
|
34
|
-
1.
|
|
35
|
-
2.
|
|
36
|
-
3.
|
|
35
|
+
1. Do not ask the user to paste credential values into chat.
|
|
36
|
+
2. If a credential-like prefix appears, redact it and warn the user to rotate the token when appropriate. Examples include `sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, and `AIza`.
|
|
37
|
+
3. Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, self-check that no credential value is being persisted. Doctor also checks `PROJECT_INDEX`, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes.
|
|
37
38
|
|
|
38
39
|
### 2. External Tool Usage Verification Gate
|
|
39
40
|
|
|
40
|
-
|
|
41
|
+
Agents must not use model memory, old session experience, copied examples, Connector marketing text, or guessed command shapes as the source for external-tool usage. Before first use of an external tool layer in the current task, and again before any write, destructive action, permission-sensitive action, raw API / SDK / CLI / URI call, plugin API change, or retry after `unknown tool`, `invalid arguments`, HTTP 400 / 404, permission, auth, or schema errors, verify the current usage source for that layer:
|
|
41
42
|
|
|
42
43
|
| Layer | Required current source before invocation |
|
|
43
44
|
|---|---|
|
|
@@ -49,151 +50,172 @@ AI must not use model memory, old session experience, copied examples, Connector
|
|
|
49
50
|
|
|
50
51
|
If the required source cannot be inspected, mark the tool use `blocked` or `unverified`, ask the user for the current docs/schema/runbook, or fall back to a manual packet. Do not continue by trial and error. Connector-first means schema-first for the active runtime, not memory-first.
|
|
51
52
|
|
|
52
|
-
###
|
|
53
|
+
### 2.1 External Tool Resource Lifecycle
|
|
54
|
+
|
|
55
|
+
External tools must be treated as resources with ownership, not just capabilities. After using Connector, MCP, plugin, browser automation, local server, crawler, notebook, or similar external tool services, classify any opened session, process, browser context, temporary directory, cache, or helper service into one of these ownership classes:
|
|
56
|
+
|
|
57
|
+
| Ownership class | Examples | Agent action |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| Task-owned | Process, browser context, temp directory, or helper service clearly started by this task and no longer needed. Evidence may include parent-child process chain, start time, tool family, task-created path, or runtime session handle. | Close or clean up automatically through the runtime or tool's graceful shutdown API when available; OS-level termination is allowed only when ownership is clear and graceful close is unavailable or failed. |
|
|
60
|
+
| Agent-managed | Kit-managed or agent-created temp/cache under a known task workspace, with bounded path and age/size rules. | Clean automatically inside the declared boundary. Never scan or clean broad user, system, browser, package-manager, or marketplace caches through this class. |
|
|
61
|
+
| Shared / user-owned / other-agent-owned / system-level | User's normal browser, another AI agent's active browser or MCP service, global MCP service, global npm/cache directory, shared credential store, project files, OS temp root, or any process whose owner is uncertain. | Do not terminate, delete, disable, or reconfigure automatically. Report evidence and propose exact remediation for user confirmation. |
|
|
62
|
+
| Unknown | Generic `node`, `python`, `chrome`, or helper process without reliable owner evidence. | Treat as shared until proven otherwise. |
|
|
63
|
+
|
|
64
|
+
For ordinary external-tool tasks, perform a lightweight closeout check: close task-owned handles, note any known retained session, and report only meaningful residual risk. For long-running, multi-tool, MCP-heavy, browser-automation, repeated-error, or user-reported slowdown tasks, perform a fuller resource review when the runtime exposes enough data: group by tool family, count, approximate memory where available, age / start time where available, and ownership class. If process command lines or environment details may contain secrets, redact arguments and secret-like values before reporting.
|
|
65
|
+
|
|
66
|
+
The preferred cleanup order is: graceful tool/session close, then task-owned process termination, then task-owned temp cleanup. Shared or ambiguous resources require explicit user confirmation with exact process IDs or paths, tool names, expected impact, and restart path before any termination, cache deletion, tool disablement, or configuration change. Never terminate or clean up a tool resource that may belong to another AI agent running on the same machine unless ownership has been proven for the current task.
|
|
53
67
|
|
|
54
|
-
|
|
68
|
+
### 3. Integration Type Discipline
|
|
55
69
|
|
|
56
|
-
|
|
70
|
+
#### 3.1 Connectors
|
|
57
71
|
|
|
58
|
-
|
|
59
|
-
- AI 可使用 active runtime 已暴露、且已讀取 tool description / input schema 嘅 Connector tool 直接 read / write
|
|
60
|
-
- Write operations 必 read-back verify 後才聲稱成功(沿用 `packs/knowledge.md` Rule 6 紀律)
|
|
61
|
-
- Auth 失敗(token expired / revoked)即 surface「請開 Claude Desktop Settings → Extensions → 重新 authenticate」+ 唔嘗試自動 fix
|
|
72
|
+
Connectors are ready-to-use external tool surfaces exposed by the active AI runtime. Their credentials are normally managed by runtime secure storage, OS credential storage, or connector storage.
|
|
62
73
|
|
|
63
|
-
|
|
74
|
+
Discipline:
|
|
64
75
|
|
|
65
|
-
|
|
76
|
+
- Use only runtime-exposed tools whose current name, description, and input schema have been inspected.
|
|
77
|
+
- Read back every external write before claiming success.
|
|
78
|
+
- If auth fails, surface the failure and point the user to the runtime or connector settings. Do not attempt automatic re-auth.
|
|
66
79
|
|
|
67
|
-
|
|
68
|
-
- 用 active runtime 已暴露、且已讀取 tool description / input schema 嘅 MCP tool(同 Connectors 一樣遵守 schema-first)
|
|
69
|
-
- 因為非官方 vetted,AI 對 write operation 加倍小心:destructive writes 必先 dry-run + 用戶 confirm(沿用 `packs/safety.md` Rule 1)
|
|
70
|
-
- Server 失靈(process crash / config error)即 surface「請檢查 MCP config + 重啟 AI tool」+ 唔嘗試自動 fix
|
|
80
|
+
#### 3.2 MCPs
|
|
71
81
|
|
|
72
|
-
|
|
82
|
+
MCP servers may be official, community, custom, or project-local. Custom MCPs often depend on manual configuration.
|
|
73
83
|
|
|
74
|
-
|
|
84
|
+
Discipline:
|
|
75
85
|
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
- 若 plugin 提供 MCP server,當 Connector / MCP 處理(見 2.1 / 2.2)
|
|
86
|
+
- Use only the active runtime's exposed tool name, description, and input schema.
|
|
87
|
+
- Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `packs/safety.md`.
|
|
88
|
+
- If the server fails because of process crash, config error, or unavailable runtime state, surface the failure, recommend checking MCP config and restarting the host tool, and do not blindly retry.
|
|
80
89
|
|
|
81
|
-
#### 3.
|
|
90
|
+
#### 3.3 Plugins
|
|
82
91
|
|
|
83
|
-
|
|
92
|
+
Plugins are distribution bundles. A plugin may register skills, MCP servers, hooks, apps, or other runtime capabilities.
|
|
84
93
|
|
|
85
|
-
|
|
86
|
-
- AI 喺對話過程 detect skill 觸發條件(明示 keyword 或 implicit signal)即自動 invoke
|
|
87
|
-
- Skill 內容屬 instruction overlay,與 rule pack 紀律 layer 共存
|
|
88
|
-
- 若 skill 與 rule pack 紀律有 conflict,rule pack(safety / governance 等)優先
|
|
94
|
+
Discipline:
|
|
89
95
|
|
|
90
|
-
|
|
96
|
+
- Do not invoke a plugin as a separate abstraction unless the runtime exposes such an action.
|
|
97
|
+
- If a plugin provides a skill, follow the skill trigger rules.
|
|
98
|
+
- If a plugin provides an MCP server or app tool, treat it under the Connector / MCP rules above and the resource lifecycle rules in this pack.
|
|
91
99
|
|
|
92
|
-
|
|
100
|
+
#### 3.4 Skills
|
|
93
101
|
|
|
94
|
-
|
|
95
|
-
|-------|------|-----------------|
|
|
96
|
-
| 真源(source of truth) | 原始可審計嘅 reference 內容 | 由用戶手動置入;AI 不直接寫入 |
|
|
97
|
-
| Index | 登記每份真源檔嘅 metadata + 摘要 + tag | AI 經 Connector 直接讀寫 |
|
|
98
|
-
| 持久化參考檔(mirror) | 防本機 disk failure / 跨裝置 access | 用戶手動同步;AI 唔自動 push |
|
|
99
|
-
| Working draft | AI 寫 task output | AI 直接 read + write 本機檔 |
|
|
102
|
+
Skills are instruction overlays, usually stored as `SKILL.md`, and may be installed directly or shipped by a plugin.
|
|
100
103
|
|
|
101
|
-
|
|
104
|
+
Discipline:
|
|
102
105
|
|
|
103
|
-
|
|
106
|
+
- Invoke a skill when the user explicitly names it or when the skill's trigger conditions are clearly met.
|
|
107
|
+
- Skill instructions coexist with rule-pack discipline.
|
|
108
|
+
- If a skill conflicts with safety, governance, or closeout rules, the rule pack and core safety boundary take precedence.
|
|
104
109
|
|
|
105
|
-
|
|
110
|
+
### 4. Source-of-truth Architecture
|
|
106
111
|
|
|
107
|
-
|
|
112
|
+
When a project uses multiple integrations as a source-of-truth system, read `dev/PROJECT_INDEX.md` `## Installed Integrations` `### Source-of-truth Architecture` before acting.
|
|
108
113
|
|
|
109
|
-
|
|
114
|
+
| Layer | Role | Write direction |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| Source of truth | Original auditable reference content | User places or controls it; agent does not directly write it unless the project explicitly declares that integration as writable truth. |
|
|
117
|
+
| Index | Metadata, summary, tags, and references for source files | Agent may read/write through declared Connector or MCP when verified. |
|
|
118
|
+
| Persistent mirror | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically. |
|
|
119
|
+
| Working draft | Task output and local work product | Agent may read/write local files under normal safety rules. |
|
|
120
|
+
|
|
121
|
+
Each layer's responsible integration must be explicit in `PROJECT_INDEX`. Do not cross layers, for example by treating an index as primary truth or pushing a working draft to a mirror without authorization.
|
|
122
|
+
|
|
123
|
+
### 5. Cross-session Lifecycle
|
|
110
124
|
|
|
111
|
-
|
|
125
|
+
#### Phase 0 — First-contact declaration
|
|
112
126
|
|
|
113
|
-
|
|
127
|
+
During first-time onboarding, ask the user whether relevant external tools are already installed or available. This may be handled by the onboarding pack's external-tool scenario.
|
|
114
128
|
|
|
115
|
-
|
|
129
|
+
#### Phase 1 — Initial recording
|
|
116
130
|
|
|
117
|
-
|
|
131
|
+
Record declared integrations in `PROJECT_INDEX` `## Installed Integrations`, using the Connectors / MCPs / Plugins / Skills subsections and the Source-of-truth Architecture table when needed.
|
|
118
132
|
|
|
119
|
-
|
|
133
|
+
#### Phase 2 — Cross-session handoff
|
|
120
134
|
|
|
121
|
-
|
|
122
|
-
- Probe fail(current AI tool 冇裝 / auth expired / network 問題)→ startup card warn 一句「⚠️ Boundary: <tool> declared but unavailable in this runtime; will fallback to paste flow when that surface is touched」;用戶決定點處理
|
|
135
|
+
`SESSION_HANDOFF` durable anchors should point future agents to `PROJECT_INDEX` `## Installed Integrations`. The next-session opening message already includes `PROJECT_INDEX` in the read order.
|
|
123
136
|
|
|
124
|
-
####
|
|
137
|
+
#### Phase 3 — Startup availability probe
|
|
125
138
|
|
|
126
|
-
|
|
139
|
+
After reading `PROJECT_INDEX`, run a minimal availability probe for each declared integration when the runtime exposes the needed tool schema.
|
|
127
140
|
|
|
128
|
-
|
|
141
|
+
- Probe success: update `Last Verified` and proceed.
|
|
142
|
+
- Probe fail: warn that the integration is declared but unavailable in the current runtime, then use fallback flow only for the affected surface.
|
|
129
143
|
|
|
130
|
-
|
|
144
|
+
#### Phase 4 — Task execution
|
|
131
145
|
|
|
132
|
-
-
|
|
133
|
-
- AI 唔嘗試自動 fix auth
|
|
134
|
-
- 更新 PROJECT_INDEX `Last Verified` cell + 加 note 紀錄 drift event
|
|
135
|
-
- Closeout 時 SESSION_LOG 紀錄 drift narrative,handoff 提示下次開工 verify
|
|
146
|
+
Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available, fall back to manual packet only when unavailable, and ask the user when the referenced integration is undeclared.
|
|
136
147
|
|
|
137
|
-
####
|
|
148
|
+
#### Phase 5 — Mid-session drift handling
|
|
138
149
|
|
|
139
|
-
|
|
150
|
+
If an integration fails mid-task because of expired auth, rate limit, network timeout, tool crash, or missing runtime capability:
|
|
140
151
|
|
|
141
|
-
-
|
|
142
|
-
-
|
|
143
|
-
-
|
|
152
|
+
- Surface the failure and impact.
|
|
153
|
+
- Do not auto-fix credentials or auth.
|
|
154
|
+
- Update `PROJECT_INDEX` `Last Verified` / note fields where appropriate.
|
|
155
|
+
- Record the drift in `SESSION_LOG` and unresolved risk in `SESSION_HANDOFF` when it affects future work.
|
|
156
|
+
|
|
157
|
+
#### Phase 6 — Cross-tool consistency
|
|
158
|
+
|
|
159
|
+
Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use fallback flow unless the user chooses to install or switch tools.
|
|
144
160
|
|
|
145
161
|
## Rules
|
|
146
162
|
|
|
147
|
-
1. **Credential
|
|
148
|
-
2. **External Tool Usage Verification Gate
|
|
149
|
-
3. **Declaration before use
|
|
150
|
-
4. **Connector-first default
|
|
151
|
-
5. **Write operations read-back
|
|
152
|
-
6. **No auto-fix credential / auth issues
|
|
153
|
-
7. **Cross-tool capability awareness
|
|
154
|
-
8. **
|
|
155
|
-
9. **Drift event mandatory recording
|
|
156
|
-
10. **Plugin / Skill
|
|
163
|
+
1. **Credential separation**: never ask for, log, or persist credential values. Redact credential-like values and warn about rotation when appropriate.
|
|
164
|
+
2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or versioned local runbooks before invoking or retrying external tools.
|
|
165
|
+
3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` before external-tool work. If absent, ask about integration status rather than assuming none exists.
|
|
166
|
+
4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
|
|
167
|
+
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
168
|
+
6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
|
|
169
|
+
7. **Cross-tool capability awareness**: verify availability at startup and warn when the current runtime lacks a declared integration.
|
|
170
|
+
8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
|
|
171
|
+
9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
|
|
172
|
+
10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
|
|
173
|
+
11. **External tool resource lifecycle**: after external-tool use, classify resources by ownership. Task-owned / agent-managed resources may be closed or cleaned automatically; shared, user-owned, system-level, other-agent-owned, or unknown resources require evidence reporting and user confirmation before remediation.
|
|
157
174
|
|
|
158
175
|
## Checks
|
|
159
176
|
|
|
160
|
-
-
|
|
161
|
-
-
|
|
162
|
-
-
|
|
163
|
-
-
|
|
164
|
-
-
|
|
165
|
-
-
|
|
166
|
-
-
|
|
177
|
+
- Verify `dev/PROJECT_INDEX.md` `## Installed Integrations` exists and has the expected subsections when the project declares integrations.
|
|
178
|
+
- Before probing or invoking a declared integration, inspect current runtime tool description and input schema.
|
|
179
|
+
- Before external-tool first use, write, destructive operation, raw API / SDK / CLI / URI / plugin API call, or retry after tool error, confirm the current usage source.
|
|
180
|
+
- Surface and record mid-session integration drift.
|
|
181
|
+
- After external-tool use, perform ownership-based resource closeout. For long-running, multi-tool, MCP, browser automation, repeated-error, or slowdown scenarios, report grouped residual processes or services when observable.
|
|
182
|
+
- Before closeout, update `Last Verified` for integrations touched this session.
|
|
183
|
+
- Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
|
|
184
|
+
- Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
|
|
167
185
|
|
|
168
186
|
## Closeout
|
|
169
187
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
5. 若 session 中新加 Integration(用戶 mid-session declare),確認已寫入 PROJECT_INDEX + cross-reference External Sources `via` column
|
|
188
|
+
1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells for integrations touched this session.
|
|
189
|
+
2. If drift happened, record the drift narrative, impact, and suggested next handling in `SESSION_LOG`.
|
|
190
|
+
3. Add unresolved integration failures to `SESSION_HANDOFF` `## Risks / Blockers`.
|
|
191
|
+
4. If unresolved drift affects startup, mention the next-session verification need in the opening message.
|
|
192
|
+
5. If the user declared a new integration during the session, ensure it is registered in `PROJECT_INDEX` and cross-referenced from External Sources when applicable.
|
|
193
|
+
6. If shared or ambiguous external-tool processes, caches, browser contexts, or helper services remain, record only a redacted evidence summary and recommended remediation. Do not write raw secret-bearing command lines into handoff or log files.
|
|
177
194
|
|
|
178
|
-
## Anti-
|
|
195
|
+
## Anti-patterns
|
|
179
196
|
|
|
180
|
-
| Anti-pattern |
|
|
197
|
+
| Anti-pattern | Why it is wrong | Correct approach |
|
|
181
198
|
|---|---|---|
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
| Connector
|
|
185
|
-
| unknown tool / invalid args
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
|
|
|
199
|
+
| Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations first; ask about integration status if undeclared. |
|
|
200
|
+
| Guessing tool names, endpoints, CLI flags, URI parameters, or plugin APIs from memory | Stale examples cause unknown tool, invalid args, 400 / 404, permission, or auth loops. | Verify active runtime schema, official docs, official types/samples, or versioned local runbooks. |
|
|
201
|
+
| Treating a Connector marketing page or old example as executable schema | Marketing pages do not prove the active runtime's current tool name or input schema. | Use active runtime tool list/schema as the invocation source. |
|
|
202
|
+
| Retrying unknown tool / invalid args by changing names or parameters repeatedly | Trial-and-error hides the real schema or docs gap. | Stop same-pattern retries and return to the External Tool Usage Verification Gate. |
|
|
203
|
+
| Writing credential values into `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG` | Project files and git history are persistent; leaked credentials remain exposed. | Record credential references only, never values. |
|
|
204
|
+
| Using a credential value pasted in chat and then recording it | Chat history and logs may persist the secret. | Redact, warn, and ask the user to rotate if needed. |
|
|
205
|
+
| Auto-fixing auth or re-auth flows | Auth belongs to the user and the runtime/tool boundary. | Surface the failure and point to the runtime or tool settings. |
|
|
206
|
+
| Claiming an external write succeeded without read-back | External writes may fail silently or partially. | Read back and compare before claiming success. |
|
|
207
|
+
| Crossing source-of-truth layers | It can corrupt truth, mirrors, or working drafts. | Follow the declared layer role and write direction in `PROJECT_INDEX`. |
|
|
208
|
+
| Skipping startup availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
|
|
209
|
+
| Leaving task-owned MCP / browser / helper processes running after the task | Turns one-off tool use into a long-lived resource leak and can slow the host. | Use graceful close or task-owned process cleanup automatically; switch to user confirmation only when ownership is unclear. |
|
|
210
|
+
| Broadly killing by process name such as `node.exe`, `python`, or `chrome` | A generic process name does not prove ownership and may terminate user work, another project, or another AI agent's active tools. | Classify by tool family, process ID, start time, parent chain, and task-created path; treat unknown ownership as shared. |
|
|
211
|
+
| Automatically cleaning global caches, marketplace caches, OS temp roots, or browser profiles | May remove shared state, login state, or data other tools still need. | Automatically clean only task-owned / agent-managed bounded paths; report evidence and wait for confirmation otherwise. |
|
|
192
212
|
|
|
193
213
|
## Cross-reference
|
|
194
214
|
|
|
195
|
-
- `packs/knowledge.md` Rule 5
|
|
196
|
-
- `packs/safety.md` Rule
|
|
197
|
-
- `packs/
|
|
198
|
-
- `
|
|
199
|
-
- `
|
|
215
|
+
- `packs/knowledge.md` Rule 5: Connector-first source access discipline.
|
|
216
|
+
- `packs/safety.md` Rule 10: external API / SDK / CLI / tool verification boundary.
|
|
217
|
+
- `packs/safety.md` Rule 12: credential leak prevention.
|
|
218
|
+
- `packs/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
|
|
219
|
+
- `packs/onboarding.md` Scenario F: first-contact declaration entry point.
|
|
220
|
+
- `runtime-core/AGENTS.core.md` Section 1: startup availability probe discipline.
|
|
221
|
+
- `runtime-core/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
|