@adamchanadam/agent-handoff-kit 0.3.40 → 0.3.41
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/LICENSE +21 -21
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +331 -121
- package/bin/installed-file-contract.mjs +45 -0
- package/bin/migration-baselines/official-origin-catalog.json +9828 -0
- package/bin/official-origin-catalog.mjs +192 -0
- package/bin/prompt-mirror-core.mjs +84 -84
- package/package.json +32 -20
- package/packs/agent-governance.md +103 -103
- package/packs/closeout.md +72 -72
- package/packs/coding.md +28 -28
- package/packs/communication.md +30 -30
- package/packs/integrations.md +251 -251
- package/packs/knowledge.md +5 -5
- package/packs/onboarding.md +214 -214
- package/packs/release.md +28 -28
- package/packs/research.md +30 -30
- package/packs/safety.md +29 -29
- package/packs/writing.md +36 -36
- package/runtime-core/AGENTS.core.md +112 -112
- package/runtime-core/CLAUDE.md +13 -13
- package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
- package/runtime-core/GEMINI.md +17 -17
- package/runtime-core/PROJECT_DECISIONS.md +43 -43
- package/runtime-core/PROJECT_INDEX.md +1 -1
- package/runtime-core/RULE_PACKS.md +14 -14
- package/runtime-core/SESSION_HANDOFF.md +36 -36
- package/runtime-core/SESSION_LOG.md +35 -35
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +5 -5
- package/bin/migration-baselines/v0.3.38/integrations.md +0 -235
- package/bin/migration-baselines/v0.3.38/onboarding.md +0 -201
- package/bin/migration-baselines/v0.3.38/safety.md +0 -46
|
@@ -1,201 +0,0 @@
|
|
|
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. |
|
|
@@ -1,46 +0,0 @@
|
|
|
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`.
|