@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/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,26 +23,37 @@ 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.
|
|
37
37
|
3. Check `dev/PROJECT_INDEX.md`: the file should be discoverable with its role and "read when" condition. Source-of-truth or reference files should appear in Fact Base, External Sources, Directory Map, Entry Points, or another existing indexed home that fits the project.
|
|
38
38
|
4. Check `dev/DOC_SYNC_REGISTRY.md`: future same-type changes should have a matching change type or an explicit reason no durable sync rule is needed.
|
|
39
39
|
5. Check related workflows, guides, runbooks, or rule packs: if a process creates or updates the file, that process should say when to update the file or its index row.
|
|
40
|
-
6. Check `dev/SESSION_HANDOFF.md`: only current state, next action, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
|
|
40
|
+
6. Check `dev/SESSION_HANDOFF.md`: only current state, recommended next action with reason, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
|
|
41
41
|
7. Check `dev/SESSION_LOG.md`: this session's bridge review, validation, and evidence can be logged when it affects future action, but log entries must not become current state.
|
|
42
42
|
8. Search for duplicate source-of-truth risk. If another file has the same durable role, recommend merge, reference, or retire options; do not delete, rename, or move files without explicit approval.
|
|
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
|
+
- Use bridged only when every applicable governance link is present. If only `dev/PROJECT_INDEX.md` or `dev/SESSION_LOG.md` was updated, report partially bridged.
|
|
50
|
+
- Already bridged: list the governance links that are present.
|
|
51
|
+
- Gaps: list missing links and why they matter for the next agent.
|
|
52
|
+
- Not applicable: list skipped layers with a reason.
|
|
53
|
+
- Suggested patches: list exact files and sections to update.
|
|
54
|
+
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
55
|
+
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
56
|
+
|
|
46
57
|
## Generated Artifact Governance Workflow
|
|
47
58
|
|
|
48
59
|
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.
|
|
@@ -61,7 +72,7 @@ Use this workflow when the user asks to write something into long-term governanc
|
|
|
61
72
|
|
|
62
73
|
1. Classify the knowledge before writing:
|
|
63
74
|
- Current task contract changes, including product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope -> the existing authoritative spec / backlog / issue / runbook when one exists; otherwise `dev/SESSION_HANDOFF.md` current-state sections.
|
|
64
|
-
- Current task state, next action, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
|
|
75
|
+
- Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
|
|
65
76
|
- Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
|
|
66
77
|
- File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
|
|
67
78
|
- Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
|
|
@@ -73,15 +84,6 @@ Use this workflow when the user asks to write something into long-term governanc
|
|
|
73
84
|
4. Add or update a QA check when the same failure class could recur and can be tested.
|
|
74
85
|
5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
|
|
75
86
|
|
|
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
87
|
## Checks
|
|
86
88
|
|
|
87
89
|
- Verify affected files are indexed or intentionally installed templates.
|
package/packs/communication.md
CHANGED
|
@@ -16,12 +16,14 @@ Use for reply format, language behavior, output schema, user-facing explanation,
|
|
|
16
16
|
3. Mark assumptions and unverified facts.
|
|
17
17
|
4. Keep operational instructions copy-paste-ready when they are meant for future sessions.
|
|
18
18
|
5. Avoid exposing internal process unless it helps the user act.
|
|
19
|
+
6. Give a clear recommended next step whenever the user needs to continue. If there is one best path, state it directly with a short reason. Offer two or three choices only when the user truly must decide; mark the recommended choice and do not turn an already-made technical judgment into an open question.
|
|
19
20
|
|
|
20
21
|
## Checks
|
|
21
22
|
|
|
22
23
|
- Verify required headings, schema fields, or language split.
|
|
23
24
|
- Check public README or docs if user-facing behavior changed.
|
|
24
25
|
- Confirm handoff/opening messages are complete and root-specific when needed.
|
|
26
|
+
- Confirm user-facing next-step wording names the recommended action and reason when a continuation is needed.
|
|
25
27
|
|
|
26
28
|
## Closeout
|
|
27
29
|
|
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, screenshots, DevTools, Playwright, desktop app automation, crawlers, notebooks, or local helper services, this pack makes the agent check declared integrations and tool operation references 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, UI validation, screenshot capture, Chrome, Playwright, DevTools, desktop app 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,186 @@ 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
|
+
#### Runtime-Controlled Tool Operation Variants
|
|
54
|
+
|
|
55
|
+
For browser and tool-operation work, first check `dev/PROJECT_INDEX.md` `## Tool Operation References` when present. A successful method from a previous session is reusable only when it is registered there with source, version/date, scope, known limits, and last verification.
|
|
56
|
+
|
|
57
|
+
| Variant | Examples | Required source before use |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| Browser / UI validation | Browser tool, screenshot, Chrome, DevTools, Playwright smoke test, visual QA | Active runtime browser/tool schema; registered tool operation reference; or current official docs for raw CLI/SDK use. Do not guess Chrome, Playwright, or DevTools commands. |
|
|
60
|
+
| Desktop or local app automation | Desktop app session, app plugin, local browser profile, extension-dependent workflow | Active app/plugin/tool schema or official automation API docs. Do not mutate user sessions, profiles, or extension state without confirmation. |
|
|
61
|
+
| Crawler / scraper / local helper | Firecrawl-like tools, crawler services, local helper server | Active tool schema, registered operation reference, or official docs. Respect source permissions, rate limits, and cleanup boundaries. |
|
|
62
|
+
| Notebook / data runtime | Notebook kernel, data runtime, long-lived analysis server | Active runtime/kernel schema or registered operation reference. Classify kernels and servers by ownership before cleanup. |
|
|
63
|
+
| Raw CLI / SDK / tool server | Direct command invocation, SDK script, MCP/tool server operation | Current official docs, installed package types, or registered operation reference. Mark blocked or unverified if unavailable. |
|
|
64
|
+
|
|
65
|
+
### 2.1 External Tool Resource Lifecycle
|
|
66
|
+
|
|
67
|
+
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:
|
|
68
|
+
|
|
69
|
+
| Ownership class | Examples | Agent action |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| 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. |
|
|
72
|
+
| 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. |
|
|
73
|
+
| 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. |
|
|
74
|
+
| Unknown | Generic `node`, `python`, `chrome`, or helper process without reliable owner evidence. | Treat as shared until proven otherwise. |
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
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.
|
|
79
|
+
|
|
80
|
+
### 3. Integration Type Discipline
|
|
81
|
+
|
|
82
|
+
#### 3.1 Connectors
|
|
53
83
|
|
|
54
|
-
|
|
84
|
+
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.
|
|
55
85
|
|
|
56
|
-
|
|
86
|
+
Discipline:
|
|
57
87
|
|
|
58
|
-
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
- Auth 失敗(token expired / revoked)即 surface「請開 Claude Desktop Settings → Extensions → 重新 authenticate」+ 唔嘗試自動 fix
|
|
88
|
+
- Use only runtime-exposed tools whose current name, description, and input schema have been inspected.
|
|
89
|
+
- Read back every external write before claiming success.
|
|
90
|
+
- If auth fails, surface the failure and point the user to the runtime or connector settings. Do not attempt automatic re-auth.
|
|
62
91
|
|
|
63
|
-
#### 3.2 MCPs
|
|
92
|
+
#### 3.2 MCPs
|
|
64
93
|
|
|
65
|
-
|
|
94
|
+
MCP servers may be official, community, custom, or project-local. Custom MCPs often depend on manual configuration.
|
|
66
95
|
|
|
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
|
|
96
|
+
Discipline:
|
|
71
97
|
|
|
72
|
-
|
|
98
|
+
- Use only the active runtime's exposed tool name, description, and input schema.
|
|
99
|
+
- Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `packs/safety.md`.
|
|
100
|
+
- 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.
|
|
73
101
|
|
|
74
|
-
|
|
102
|
+
#### 3.3 Plugins
|
|
75
103
|
|
|
76
|
-
|
|
77
|
-
- AI 唔需要 separately invoke plugin —— plugin 自身會 register 它嘅 skills + MCP servers
|
|
78
|
-
- 若 plugin 提供 skill,AI 按 skill 觸發條件自動 invoke(同 system skill 紀律一致)
|
|
79
|
-
- 若 plugin 提供 MCP server,當 Connector / MCP 處理(見 2.1 / 2.2)
|
|
104
|
+
Plugins are distribution bundles. A plugin may register skills, MCP servers, hooks, apps, or other runtime capabilities.
|
|
80
105
|
|
|
81
|
-
|
|
106
|
+
Discipline:
|
|
82
107
|
|
|
83
|
-
|
|
108
|
+
- Do not invoke a plugin as a separate abstraction unless the runtime exposes such an action.
|
|
109
|
+
- If a plugin provides a skill, follow the skill trigger rules.
|
|
110
|
+
- 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.
|
|
84
111
|
|
|
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 等)優先
|
|
112
|
+
#### 3.4 Skills
|
|
89
113
|
|
|
90
|
-
|
|
114
|
+
Skills are instruction overlays, usually stored as `SKILL.md`, and may be installed directly or shipped by a plugin.
|
|
91
115
|
|
|
92
|
-
|
|
116
|
+
Discipline:
|
|
93
117
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
| Index | 登記每份真源檔嘅 metadata + 摘要 + tag | AI 經 Connector 直接讀寫 |
|
|
98
|
-
| 持久化參考檔(mirror) | 防本機 disk failure / 跨裝置 access | 用戶手動同步;AI 唔自動 push |
|
|
99
|
-
| Working draft | AI 寫 task output | AI 直接 read + write 本機檔 |
|
|
118
|
+
- Invoke a skill when the user explicitly names it or when the skill's trigger conditions are clearly met.
|
|
119
|
+
- Skill instructions coexist with rule-pack discipline.
|
|
120
|
+
- If a skill conflicts with safety, governance, or closeout rules, the rule pack and core safety boundary take precedence.
|
|
100
121
|
|
|
101
|
-
|
|
122
|
+
### 4. Source-of-truth Architecture
|
|
102
123
|
|
|
103
|
-
|
|
124
|
+
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.
|
|
104
125
|
|
|
105
|
-
|
|
126
|
+
| Layer | Role | Write direction |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| 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. |
|
|
129
|
+
| Index | Metadata, summary, tags, and references for source files | Agent may read/write through declared Connector or MCP when verified. |
|
|
130
|
+
| Persistent mirror | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically. |
|
|
131
|
+
| Working draft | Task output and local work product | Agent may read/write local files under normal safety rules. |
|
|
132
|
+
|
|
133
|
+
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.
|
|
106
134
|
|
|
107
|
-
|
|
135
|
+
### 5. Cross-session Lifecycle
|
|
108
136
|
|
|
109
|
-
####
|
|
137
|
+
#### Phase 0 — First-contact declaration
|
|
110
138
|
|
|
111
|
-
|
|
139
|
+
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.
|
|
112
140
|
|
|
113
|
-
####
|
|
141
|
+
#### Phase 1 — Initial recording
|
|
114
142
|
|
|
115
|
-
`
|
|
143
|
+
Record declared integrations in `PROJECT_INDEX` `## Installed Integrations`, using the Connectors / MCPs / Plugins / Skills subsections and the Source-of-truth Architecture table when needed.
|
|
116
144
|
|
|
117
|
-
####
|
|
145
|
+
#### Phase 2 — Cross-session handoff
|
|
118
146
|
|
|
119
|
-
|
|
147
|
+
`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.
|
|
120
148
|
|
|
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」;用戶決定點處理
|
|
149
|
+
#### Phase 3 — Startup availability probe
|
|
123
150
|
|
|
124
|
-
|
|
151
|
+
After reading `PROJECT_INDEX`, run a minimal availability probe for each declared integration when the runtime exposes the needed tool schema.
|
|
125
152
|
|
|
126
|
-
|
|
153
|
+
- Probe success: update `Last Verified` and proceed.
|
|
154
|
+
- Probe fail: warn that the integration is declared but unavailable in the current runtime, then use fallback flow only for the affected surface.
|
|
127
155
|
|
|
128
|
-
####
|
|
156
|
+
#### Phase 4 — Task execution
|
|
129
157
|
|
|
130
|
-
|
|
158
|
+
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.
|
|
131
159
|
|
|
132
|
-
|
|
133
|
-
- AI 唔嘗試自動 fix auth
|
|
134
|
-
- 更新 PROJECT_INDEX `Last Verified` cell + 加 note 紀錄 drift event
|
|
135
|
-
- Closeout 時 SESSION_LOG 紀錄 drift narrative,handoff 提示下次開工 verify
|
|
160
|
+
#### Phase 5 — Mid-session drift handling
|
|
136
161
|
|
|
137
|
-
|
|
162
|
+
If an integration fails mid-task because of expired auth, rate limit, network timeout, tool crash, or missing runtime capability:
|
|
138
163
|
|
|
139
|
-
|
|
164
|
+
- Surface the failure and impact.
|
|
165
|
+
- Do not auto-fix credentials or auth.
|
|
166
|
+
- Update `PROJECT_INDEX` `Last Verified` / note fields where appropriate.
|
|
167
|
+
- Record the drift in `SESSION_LOG` and unresolved risk in `SESSION_HANDOFF` when it affects future work.
|
|
140
168
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
-
|
|
169
|
+
#### Phase 6 — Cross-tool consistency
|
|
170
|
+
|
|
171
|
+
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
172
|
|
|
145
173
|
## Rules
|
|
146
174
|
|
|
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
|
|
175
|
+
1. **Credential separation**: never ask for, log, or persist credential values. Redact credential-like values and warn about rotation when appropriate.
|
|
176
|
+
2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
|
|
177
|
+
3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, ask about integration status rather than assuming none exists.
|
|
178
|
+
4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
|
|
179
|
+
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
180
|
+
6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
|
|
181
|
+
7. **Cross-tool capability awareness**: verify availability at startup and warn when the current runtime lacks a declared integration.
|
|
182
|
+
8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
|
|
183
|
+
9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
|
|
184
|
+
10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
|
|
185
|
+
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
186
|
|
|
158
187
|
## Checks
|
|
159
188
|
|
|
160
|
-
-
|
|
161
|
-
-
|
|
162
|
-
-
|
|
163
|
-
-
|
|
164
|
-
-
|
|
165
|
-
-
|
|
166
|
-
-
|
|
189
|
+
- Verify `dev/PROJECT_INDEX.md` `## Installed Integrations` exists and has the expected subsections when the project declares integrations.
|
|
190
|
+
- Before probing or invoking a declared integration, inspect current runtime tool description and input schema.
|
|
191
|
+
- Before browser validation, screenshots, Chrome, Playwright, DevTools, desktop automation, crawler, notebook, or raw CLI/SDK/tool-server work, verify the current source from runtime schema, official docs, or `PROJECT_INDEX` `## Tool Operation References`.
|
|
192
|
+
- 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.
|
|
193
|
+
- Surface and record mid-session integration drift.
|
|
194
|
+
- 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.
|
|
195
|
+
- Before closeout, update `Last Verified` for integrations touched this session.
|
|
196
|
+
- Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
|
|
197
|
+
- Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
|
|
167
198
|
|
|
168
199
|
## Closeout
|
|
169
200
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
5. 若 session 中新加 Integration(用戶 mid-session declare),確認已寫入 PROJECT_INDEX + cross-reference External Sources `via` column
|
|
201
|
+
1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells for integrations touched this session.
|
|
202
|
+
2. If drift happened, record the drift narrative, impact, and suggested next handling in `SESSION_LOG`.
|
|
203
|
+
3. Add unresolved integration failures to `SESSION_HANDOFF` `## Risks / Blockers`.
|
|
204
|
+
4. If unresolved drift affects startup, mention the next-session verification need in the opening message.
|
|
205
|
+
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.
|
|
206
|
+
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
207
|
|
|
178
|
-
## Anti-
|
|
208
|
+
## Anti-patterns
|
|
179
209
|
|
|
180
|
-
| Anti-pattern |
|
|
210
|
+
| Anti-pattern | Why it is wrong | Correct approach |
|
|
181
211
|
|---|---|---|
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
|
|
|
212
|
+
| 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. |
|
|
213
|
+
| 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. |
|
|
214
|
+
| Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference; mark blocked or use a manual packet when unavailable. |
|
|
215
|
+
| 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. |
|
|
216
|
+
| 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. |
|
|
217
|
+
| 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. |
|
|
218
|
+
| 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. |
|
|
219
|
+
| 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. |
|
|
220
|
+
| Claiming an external write succeeded without read-back | External writes may fail silently or partially. | Read back and compare before claiming success. |
|
|
221
|
+
| Crossing source-of-truth layers | It can corrupt truth, mirrors, or working drafts. | Follow the declared layer role and write direction in `PROJECT_INDEX`. |
|
|
222
|
+
| 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. |
|
|
223
|
+
| 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. |
|
|
224
|
+
| 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. |
|
|
225
|
+
| 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
226
|
|
|
193
227
|
## Cross-reference
|
|
194
228
|
|
|
195
|
-
- `packs/knowledge.md` Rule 5
|
|
196
|
-
- `packs/safety.md` Rule
|
|
197
|
-
- `packs/
|
|
198
|
-
- `
|
|
199
|
-
- `
|
|
229
|
+
- `packs/knowledge.md` Rule 5: Connector-first source access discipline.
|
|
230
|
+
- `packs/safety.md` Rule 10: external API / SDK / CLI / tool verification boundary.
|
|
231
|
+
- `packs/safety.md` Rule 12: credential leak prevention.
|
|
232
|
+
- `packs/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
|
|
233
|
+
- `packs/onboarding.md` Scenario F: first-contact declaration entry point.
|
|
234
|
+
- `runtime-core/AGENTS.core.md` Section 1: startup availability probe discipline.
|
|
235
|
+
- `runtime-core/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
|