@adamchanadam/agent-handoff-kit 0.3.38 → 0.3.39

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.
@@ -0,0 +1,235 @@
1
+ # Integrations Pack
2
+
3
+ ## Scope
4
+
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
+
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
+
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
+
11
+ ## Load When
12
+
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.
19
+
20
+ ## Discipline
21
+
22
+ ### 1. Credential Separation Principle
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.
25
+
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 |
32
+
33
+ No file under `dev/` should contain a credential value. Enforce three rules:
34
+
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.
38
+
39
+ ### 2. External Tool Usage Verification Gate
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:
42
+
43
+ | Layer | Required current source before invocation |
44
+ |---|---|
45
+ | Connector / MCP tool | Current runtime-exposed tool name, description, and input schema. Use the tool list/schema exposed by the active AI runtime or MCP server; do not invent `mcp__*` names or arguments. |
46
+ | Plugin / Skill | Current plugin/skill instructions plus any registered MCP tool schema it exposes. |
47
+ | Raw API / SDK / CLI / URI | Current official documentation or a project-local runbook that states source, version/date, and scope. If the runbook lacks those, verify against official docs. |
48
+ | Local app plugin API | Official API documentation, official type definitions, official sample project, or local installed package types matching the project version. |
49
+ | Project-local runbook | Accept as a task source only when it records the upstream source, version/date, scope, and known limits. |
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.
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
83
+
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.
85
+
86
+ Discipline:
87
+
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.
91
+
92
+ #### 3.2 MCPs
93
+
94
+ MCP servers may be official, community, custom, or project-local. Custom MCPs often depend on manual configuration.
95
+
96
+ Discipline:
97
+
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.
101
+
102
+ #### 3.3 Plugins
103
+
104
+ Plugins are distribution bundles. A plugin may register skills, MCP servers, hooks, apps, or other runtime capabilities.
105
+
106
+ Discipline:
107
+
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.
111
+
112
+ #### 3.4 Skills
113
+
114
+ Skills are instruction overlays, usually stored as `SKILL.md`, and may be installed directly or shipped by a plugin.
115
+
116
+ Discipline:
117
+
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.
121
+
122
+ ### 4. Source-of-truth Architecture
123
+
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.
125
+
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.
134
+
135
+ ### 5. Cross-session Lifecycle
136
+
137
+ #### Phase 0 — First-contact declaration
138
+
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.
140
+
141
+ #### Phase 1 — Initial recording
142
+
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.
144
+
145
+ #### Phase 2 — Cross-session handoff
146
+
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.
148
+
149
+ #### Phase 3 — Startup availability probe
150
+
151
+ After reading `PROJECT_INDEX`, run a minimal availability probe for each declared integration when the runtime exposes the needed tool schema.
152
+
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.
155
+
156
+ #### Phase 4 — Task execution
157
+
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.
159
+
160
+ #### Phase 5 — Mid-session drift handling
161
+
162
+ If an integration fails mid-task because of expired auth, rate limit, network timeout, tool crash, or missing runtime capability:
163
+
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.
168
+
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.
172
+
173
+ ## Rules
174
+
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.
186
+
187
+ ## Checks
188
+
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.
198
+
199
+ ## Closeout
200
+
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.
207
+
208
+ ## Anti-patterns
209
+
210
+ | Anti-pattern | Why it is wrong | Correct approach |
211
+ |---|---|---|
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. |
226
+
227
+ ## Cross-reference
228
+
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.
@@ -0,0 +1,201 @@
1
+ # Onboarding Pack
2
+
3
+ ## Scope
4
+
5
+ Use this transient pack for first-time Agent Handoff Kit users, vague first messages, or fresh-install sessions where the user has not yet chosen a working scenario.
6
+
7
+ The goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.
8
+
9
+ ## Load When
10
+
11
+ ### Explicit onboarding signal keywords
12
+
13
+ Load this pack when the user message contains an onboarding signal such as:
14
+
15
+ - "I'm new" / "new user"
16
+ - "teach me" / "help me start" / "help me get started"
17
+ - "first time" / "first-time" / "I just installed"
18
+ - "how do I start" / "show me how" / "getting started"
19
+ - "what can agent handoff kit do"
20
+ - vague project intent such as "I want to do a project"
21
+ - equivalent Chinese user phrases such as "新手", "教我用", "我剛安裝", "點開始", "開工", "能力", or "能做甚麼"
22
+
23
+ ### Implicit signals
24
+
25
+ - The first user message is short and vague.
26
+ - `SESSION_HANDOFF` Active Objective is empty and Session count is 1.
27
+ - The user asks a generic capability question instead of giving a concrete task.
28
+ - The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
29
+
30
+ ## Discipline
31
+
32
+ ### 1. Do not assume prior reading
33
+
34
+ The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
35
+
36
+ ### 2. Offer scenario choice before task execution
37
+
38
+ When onboarding applies, the first visible response must combine the startup card and scenario chooser into one complete response. Do not print a partial startup card first. Do not repeat the status card, current objective, warnings, or next step.
39
+
40
+ Offer six scenarios:
41
+
42
+ - **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.
43
+ - **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.
44
+ - **C. Organize local files, Notion, Google Drive, or a knowledge base**: the user wants source, reference, mirror, and draft material kept clear.
45
+ - **D. Learn to code**: the user is a technical beginner and wants a small guided exercise.
46
+ - **E. Custom scenario**: the user has another goal.
47
+ - **F. Review installed external tools and design governance**: the user already has Connectors, MCPs, Plugins, Skills, or browser / notebook / crawler tools and wants a safe operating model.
48
+
49
+ ### 3. 5-step walk-through pattern
50
+
51
+ After the user picks a scenario, guide one small first task through five steps:
52
+
53
+ 1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.
54
+ 2. Explain in three plain points how Agent Handoff Kit helps this scenario.
55
+ 3. Ask for the first concrete task scope, offering four to six practical options.
56
+ 4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.
57
+ 5. Wait for user confirmation, then transition to the regular work loop.
58
+
59
+ ### 4. Advance one step at a time
60
+
61
+ Do not run all five steps in one message. At each step:
62
+
63
+ - state what the AI will do,
64
+ - state what the user needs to answer or confirm,
65
+ - answer questions before continuing,
66
+ - let the user skip or change the step.
67
+
68
+ ### 5. Keep the first task small
69
+
70
+ The first task should be a preview, a short draft, a small classification sample, a dry-run, or another bounded result. Do not begin with broad refactors, bulk file moves, publishing, deployment, or destructive operations.
71
+
72
+ ### 6. Transition after onboarding
73
+
74
+ After the walk-through:
75
+
76
+ - load the regular pack(s) for the chosen task,
77
+ - unload this transient onboarding pack,
78
+ - enter the PLAN -> READ -> CHANGE -> QC -> PERSIST work loop,
79
+ - record the first-task scope in `SESSION_HANDOFF` when the persistence gate requires it.
80
+
81
+ ## Application Scenario Library
82
+
83
+ Each scenario keeps the same five-step rhythm. The model may adapt wording, but must preserve the intent, tone, and safety boundaries.
84
+
85
+ ### Scenario A. Build systems, tools, platforms, websites, or apps
86
+
87
+ Step A.1: ask for the project folder, current stack if known, whether git exists, and whether GitHub, Linear, Slack, Notion, Google Drive, or other external tools are connected.
88
+
89
+ Step A.2: explain that Kit helps the AI remember project state across sessions, avoid silent risky commands, and record what changed at closeout.
90
+
91
+ Step A.3: offer task choices such as fix a bug, add a feature, organize code, add tests, write README, or prepare a first commit.
92
+
93
+ Step A.4: suggest a small first task, such as a short README section, one failing test investigation, or a dry-run plan.
94
+
95
+ Step A.5: after confirmation, load the relevant coding / writing / safety packs and begin the normal work loop.
96
+
97
+ ### Scenario B. Organize research or write a report
98
+
99
+ Step B.1: ask for the topic, existing source locations, intended reader, and whether Notion, Google Drive, or another source tool is connected.
100
+
101
+ Step B.2: explain that Kit separates source evidence from inference, records source locations, and preserves progress across sessions.
102
+
103
+ Step B.3: offer task choices such as outline sections, register sources, summarize one source, draft a subsection, or review an existing draft.
104
+
105
+ Step B.4: suggest a small first task, such as a 5-7 heading outline with one sentence per section.
106
+
107
+ Step B.5: after confirmation, load research / writing / knowledge packs and begin the normal work loop.
108
+
109
+ ### Scenario C. Organize local files, Notion, Google Drive, or a knowledge base
110
+
111
+ Step C.1: ask what needs organizing: local folder, Notion database, Google Drive folder, or mixed sources. Ask which external tools are connected or unknown.
112
+
113
+ Step C.2: explain that Kit separates source of truth, references, mirrors, and drafts, and that risky file operations require dry-run and confirmation.
114
+
115
+ Step C.3: offer task choices such as scan and classify files, design a folder structure, draft a Notion schema, write a dry-run script, or align local references with an external index.
116
+
117
+ Step C.4: suggest a small first task, such as classifying a bounded sample without moving files.
118
+
119
+ Step C.5: after confirmation, load knowledge / safety / integrations packs as needed.
120
+
121
+ ### Scenario D. Learn to code
122
+
123
+ Step D.1: ask which direction the user wants: small automation, web page, Python tool, Git / GitHub basics, or another beginner task. Ask whether any relevant tools are already installed.
124
+
125
+ Step D.2: explain that Kit keeps learning progress across sessions, keeps risky operations explicit, and lets the user review each small change.
126
+
127
+ Step D.3: offer one small exercise, such as a dry-run file renamer, a one-page HTML example, or a tiny Python script.
128
+
129
+ Step D.4: keep the exercise small enough to explain line by line.
130
+
131
+ Step D.5: after confirmation, load coding / safety packs and begin the normal work loop.
132
+
133
+ ### Scenario E. Custom scenario
134
+
135
+ Step E.1: ask for four facts: objective, existing material or tools, technical comfort level, and the first small result the user wants.
136
+
137
+ Step E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.
138
+
139
+ Step E.3: offer task choices tailored to the user's answer.
140
+
141
+ Step E.4: suggest one minimum viable first task.
142
+
143
+ Step E.5: after confirmation, load the appropriate regular pack combination.
144
+
145
+ ### Scenario F. External-tool governance
146
+
147
+ Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
148
+
149
+ Step F.1: collect installed external tools by category: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. If the user does not know the category, ask for names only and classify them.
150
+
151
+ Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
152
+
153
+ Step F.3: map source-of-truth architecture: source of truth, index, persistent mirror, and working draft. Make each layer's write boundary explicit.
154
+
155
+ Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
156
+
157
+ Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. Mark unavailable tools as blocked / unverified instead of guessing.
158
+
159
+ ## Cross-reference to guide.html
160
+
161
+ When the user asks for a fuller example, mention `agent-handoff-kit-guide.html` as an optional reference. The guide is not required reading.
162
+
163
+ - Case A aligns with Scenario A plus parts of Scenario C.
164
+ - Case B aligns with Scenario B plus Scenario F.
165
+ - Case C aligns with long-running project evolution.
166
+
167
+ ## Tone Discipline
168
+
169
+ Use plain user-facing language. Avoid internal jargon in onboarding replies unless the user asks for implementation details.
170
+
171
+ - Say "project registry" before exposing `PROJECT_INDEX`.
172
+ - Say "wrap up" or the user's own closeout phrase before exposing closeout internals.
173
+ - Say "next-session startup message" only when discussing the persisted handoff file.
174
+ - Say "working mode" before exposing "rule pack".
175
+ - Say "risky command" before exposing "destructive operation".
176
+
177
+ Keep user-facing explanations self-contained. For the public product's Chinese surfaces, use steady written Traditional Chinese and avoid Cantonese spoken characters. Inside this AI-facing pack, keep instructions in English and use Chinese only as quoted user phrases that the runtime must recognize.
178
+
179
+ ## Closeout
180
+
181
+ After onboarding finishes:
182
+
183
+ 1. Confirm that the user knows the next practical action, how to start a later session, and how to request closeout.
184
+ 2. Update `SESSION_HANDOFF` only when the persistence gate says the first-task scope or next action is durable.
185
+ 3. Record next priorities only when they affect a later session.
186
+ 4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.
187
+ 5. Unload this pack and continue with the relevant regular pack(s).
188
+
189
+ In a later session, reload onboarding only when the user gives a fresh onboarding signal or asks to restart the walk-through. Otherwise enter the normal work loop.
190
+
191
+ ## Anti-patterns
192
+
193
+ | Anti-pattern | Why it is wrong | Correct approach |
194
+ |---|---|---|
195
+ | Treating a vague first message as a specific task | The user may be trying to learn the workflow or choose a scenario. | Offer the A-F scenario chooser first. |
196
+ | Making the first task broad | A first-time user needs rhythm and confidence before large changes. | Suggest one 10-15 minute minimum viable task. |
197
+ | Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |
198
+ | Assuming the user read README or guide pages | Many users start directly in an AI chat. | Surface only the concepts needed for the next step. |
199
+ | Keeping onboarding loaded after the first task starts | Onboarding is transient and will distract from normal task work. | Unload onboarding and load the regular pack(s). |
200
+ | Running all five steps without waiting | The user loses control of the walk-through. | Pause for confirmation at each step. |
201
+ | Assuming no Connector, MCP, Plugin, or Skill exists | Paste-only fallback creates the wrong operating model for users who already connected tools. | Ask a lightweight external-tool question in step 1, or use Scenario F. |
@@ -0,0 +1,46 @@
1
+ # Safety Pack
2
+
3
+ ## Scope
4
+
5
+ Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, 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
+
7
+ ## Load When
8
+
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, browser profiles, desktop app sessions, notebook kernels, local tool servers, shared caches, or public release state.
11
+ - Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
12
+
13
+ ## Rules
14
+
15
+ 1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
16
+ 2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
17
+ 3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
18
+ 4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. Report the blocker and manual action needed.
19
+ 5. Do not run recursive or bulk destructive commands such as `rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, or equivalent cleanup operations unless the user explicitly requested the operation and resolved absolute targets are verified.
20
+ 6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
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
+ 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
+ 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, 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
+ (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
+ (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
+ (c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
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):
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
+ 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`.