@adamchanadam/agent-handoff-kit 0.3.9 → 0.3.11
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 +35 -26
- package/bin/agent-handoff-kit.mjs +267 -170
- package/docs/whatsnew/v0.3.1.md +5 -5
- package/docs/whatsnew/v0.3.10.md +19 -0
- package/docs/whatsnew/v0.3.11.md +19 -0
- package/docs/whatsnew/v0.3.2.md +5 -5
- package/docs/whatsnew/v0.3.3.md +5 -5
- package/docs/whatsnew/v0.3.4.md +2 -2
- package/package.json +1 -1
- package/packs/integrations.md +7 -7
- package/packs/onboarding.md +125 -121
- package/packs/safety.md +1 -1
- package/packs/writing.md +2 -0
- package/runtime-core/AGENTS.core.md +15 -15
- package/runtime-core/CLAUDE.md +8 -8
- package/runtime-core/GEMINI.md +7 -3
- package/runtime-core/PROJECT_INDEX.md +4 -4
- package/runtime-core/RULE_PACKS.md +3 -3
package/packs/writing.md
CHANGED
|
@@ -16,12 +16,14 @@ Use for drafting, editing, style, structure, publication copy, documentation pro
|
|
|
16
16
|
3. Keep terminology consistent with project docs.
|
|
17
17
|
4. Mark uncertain claims instead of inventing support.
|
|
18
18
|
5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
|
|
19
|
+
6. For public Traditional Chinese docs or HTML aimed at non-technical readers, use steady written Chinese. Keep English only for commands, paths, URLs, file names, product names, and unavoidable tool names. Avoid mixed half-English fragments, internal governance codes, and developer-only wording in reader-facing prose.
|
|
19
20
|
|
|
20
21
|
## Checks
|
|
21
22
|
|
|
22
23
|
- Verify requested format, language, and tone.
|
|
23
24
|
- Check links, commands, names, and version-sensitive claims when relevant.
|
|
24
25
|
- Check `dev/DOC_SYNC_REGISTRY.md` if public docs or user-facing instructions changed.
|
|
26
|
+
- For public Chinese docs, read the final text as a new user journey: the next action should be clear without technical background.
|
|
25
27
|
|
|
26
28
|
## Closeout
|
|
27
29
|
|
|
@@ -13,7 +13,7 @@ After this core is loaded, read in order:
|
|
|
13
13
|
|
|
14
14
|
Then classify the user's task and read only the required rule pack(s). State which pack(s) you loaded and why, using plain language so the user understands the working mode without needing to know pack names.
|
|
15
15
|
|
|
16
|
-
Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, or contains onboarding signal keywords (e.g. "新手", "I'm new", "教我用", "help me start", "first time", "
|
|
16
|
+
Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, or contains onboarding signal keywords (e.g. "新手", "I'm new", "教我用", "help me start", "first time", "我剛安裝", "點開始", "show me how", "agent handoff kit 可幫我做甚麼", "我想做 [type] project", "點用", "能力"), or if the session is a fresh installation (HANDOFF Active Objective empty + Session count 1), load `dev/rules/onboarding.md` proactively BEFORE doing the regular task loop. The onboarding pack surfaces the AI's role and offers Scenario A-F selection (instead of immediately diving into task execution). Onboarding is a transient pack: after the user completes their first-task walk-through, unload it and load the regular scenario pack (coding / research / writing / knowledge / etc) for ongoing work.
|
|
17
17
|
|
|
18
18
|
If the user did not paste the previous opening message but the current project root is clear, read `AGENTS.md` first as fallback entry, then use this read order. If the root is unclear or mismatched, stop and ask for the intended project root before reading or editing project state.
|
|
19
19
|
|
|
@@ -28,20 +28,20 @@ After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empt
|
|
|
28
28
|
- If probe fails (current AI tool lacks the Connector / auth expired / network issue): print warning in the startup card (`⚠️ Boundary` line) noting which Integration is declared-but-unavailable + that this session will fallback to paste flow when that external surface is touched. Do not attempt to auto-fix auth or credential issues; surface to the user to handle via the AI tool's own settings interface.
|
|
29
29
|
- Credential separation: AI must never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens). Credentials live in OS-level secure storage or AI-tool-specific config, never in `dev/*` files. Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) and redact + warn the user to rotate the token if accidentally pasted.
|
|
30
30
|
|
|
31
|
-
After startup reads are complete, show
|
|
32
|
-
|
|
33
|
-
```text
|
|
34
|
-
/\_/\ Agent Handoff Kit v<version>
|
|
35
|
-
( o.o ) continuity ready
|
|
36
|
-
> ^ <
|
|
37
|
-
|
|
38
|
-
🔎
|
|
39
|
-
📌
|
|
40
|
-
⚠️
|
|
41
|
-
🚀
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Keep the card short. Use the full product name, not an abbreviation. If the installed template or CLI version is unknown, write `version unverified` instead of guessing.
|
|
31
|
+
After startup reads are complete, show one short startup card. If onboarding is loaded, combine this card and the onboarding choice list into one first response. Do not print any standalone startup card before the onboarding rule has been read. Do not print a partial card. Do not print the cat banner twice. If you started drafting a card and then discovered onboarding applies, discard the draft and output only the final combined response.
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
/\_/\ Agent Handoff Kit v<version>
|
|
35
|
+
( o.o ) continuity ready
|
|
36
|
+
> ^ <
|
|
37
|
+
|
|
38
|
+
🔎 交接狀態:<loaded / new install / resumed>
|
|
39
|
+
📌 目前目標:<current objective>
|
|
40
|
+
⚠️ 注意事項:<important boundary or none>
|
|
41
|
+
🚀 下一步:<next action>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation. If the installed template or CLI version is unknown, write `version unverified` instead of guessing.
|
|
45
45
|
|
|
46
46
|
## 2. Work Loop
|
|
47
47
|
|
package/runtime-core/CLAUDE.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
|
-
# Claude Entry Bridge
|
|
1
|
+
# Claude Code Entry Bridge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
@AGENTS.md
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
This file is a bridge only. Claude Code reads `CLAUDE.md` automatically, so this bridge imports `AGENTS.md`, which remains the single authoritative startup file for Agent Handoff Kit.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Do not expand, summarize, replace, or "improve" this file during onboarding, setup, `/init`, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
2. Read `AGENTS.md`.
|
|
11
|
-
3. Follow the startup read order in `AGENTS.md`.
|
|
9
|
+
If the user says `I just installed agent-handoff-kit`, `help me get started`, or similar first-use wording, do not run Claude Code `/init` and do not load an `init` skill. Agent Handoff Kit is already installed. Read `AGENTS.md`, load the onboarding rule when appropriate, and guide the user through the first task.
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
Only edit this file when the user explicitly asks to edit `CLAUDE.md` itself, or when `agent-handoff-kit upgrade` reports a bridge conflict and asks for manual repair.
|
|
12
|
+
|
|
13
|
+
After loading this bridge, follow `AGENTS.md` and the startup read order defined there.
|
package/runtime-core/GEMINI.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
|
-
# Gemini Entry Bridge
|
|
1
|
+
# Antigravity / Gemini Entry Bridge
|
|
2
2
|
|
|
3
|
-
This file exists
|
|
3
|
+
This file is a bridge only. It exists for Google Antigravity CLI, Gemini CLI during migration, and compatible tools that still read `GEMINI.md`.
|
|
4
4
|
|
|
5
|
-
Authoritative operating rules remain in `AGENTS.md`.
|
|
5
|
+
Authoritative operating rules remain in `AGENTS.md`.
|
|
6
|
+
|
|
7
|
+
Do not expand, summarize, replace, or "improve" this file during onboarding, setup, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
|
|
8
|
+
|
|
9
|
+
Antigravity CLI may read both `AGENTS.md` and `GEMINI.md` from the active workspace. If `AGENTS.md` has already been loaded, do not treat this bridge as a second rule source and do not repeat the same instructions.
|
|
6
10
|
|
|
7
11
|
At session startup:
|
|
8
12
|
|
|
@@ -20,7 +20,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
20
20
|
|---|---|---|
|
|
21
21
|
| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
|
|
22
22
|
| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
|
|
23
|
-
| `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini
|
|
23
|
+
| `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
|
|
24
24
|
| `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
|
|
25
25
|
| `src/` | application source | coding task |
|
|
26
26
|
| `tests/` | tests | coding/QC |
|
|
@@ -51,9 +51,9 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
51
51
|
|
|
52
52
|
| Source | Role | Required before | Access method | `via` | Write-back rule | Last verified |
|
|
53
53
|
|---|---|---|---|---|---|---|
|
|
54
|
-
| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
|
|
54
|
+
| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Google Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
|
|
55
55
|
|
|
56
|
-
> `via` column 紀律:每行 External Sources 必引用 `## Installed Integrations` 嘅 entry 名稱(譬如 `Notion Connector`、`Drive Connector`),確認該 source 經邊個 integration 訪問;無 declared Integration 嘅 source 用 `manual paste`。Cross-section consistency 由 doctor + qa:release 強制 enforce。
|
|
56
|
+
> `via` column 紀律:每行 External Sources 必引用 `## Installed Integrations` 嘅 entry 名稱(譬如 `Notion Connector`、`Google Drive Connector`),確認該 source 經邊個 integration 訪問;無 declared Integration 嘅 source 用 `manual paste`。Cross-section consistency 由 doctor + qa:release 強制 enforce。
|
|
57
57
|
|
|
58
58
|
## Installed Integrations
|
|
59
59
|
|
|
@@ -87,7 +87,7 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
87
87
|
|
|
88
88
|
### Source-of-truth Architecture(多層持久化組合)
|
|
89
89
|
|
|
90
|
-
> 當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Drive 參考檔),本表描述每層分工,避免 AI 跨層越界。
|
|
90
|
+
> 當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Google Drive 參考檔),本表描述每層分工,避免 AI 跨層越界。
|
|
91
91
|
|
|
92
92
|
| Layer | Surface(具體 instance) | Role | Write Direction |
|
|
93
93
|
|-------|--------------------------|------|-----------------|
|
|
@@ -4,15 +4,15 @@ Read only the packs needed for the current task.
|
|
|
4
4
|
|
|
5
5
|
| Task signal | Pack | Purpose |
|
|
6
6
|
|---|---|---|
|
|
7
|
-
| First-time user signals (任一即可): "I'm new" / "新手" / "教我用" / "help me start" / "first time" / "我啱啱安裝" / "點開始" / "show me how" / "getting started" / "agent handoff kit 可幫我做甚麼" / "我想做 [type] project" / "點用" / "能力" / vague first message ≤ 30 chars / HANDOFF Active Objective 空白 + Session count 1 (fresh installation context) | `dev/rules/onboarding.md` | first-time user walk-through with
|
|
7
|
+
| First-time user signals (任一即可): "I'm new" / "新手" / "教我用" / "help me start" / "first time" / "我啱啱安裝" / "點開始" / "show me how" / "getting started" / "agent handoff kit 可幫我做甚麼" / "我想做 [type] project" / "點用" / "能力" / vague first message ≤ 30 chars / HANDOFF Active Objective 空白 + Session count 1 (fresh installation context) | `dev/rules/onboarding.md` | first-time user walk-through with 6 scenarios (A 建構系統 / B 研究報告 / C 知識庫 / D 學寫代碼 / E 其他 / F 外部工具治理) × 5-step pattern (PLAN-style: confirm context / explain v2 fit / ask task scope / suggest minimum viable / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
|
|
8
8
|
| Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
|
|
9
9
|
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
10
10
|
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
11
11
|
| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
|
|
12
12
|
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
13
13
|
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
14
|
-
| External notes, knowledge base, Notion, Obsidian, Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
15
|
-
| External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Drive / Slack / Linear / Dropbox / HubSpot / GitHub / etc. external read-write | `dev/rules/integrations.md` | Connector-first default + credential separation + multi-layer source-of-truth + cross-session resilience |
|
|
14
|
+
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
15
|
+
| External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Google Drive / Slack / Linear / Dropbox / HubSpot / GitHub / etc. external read-write | `dev/rules/integrations.md` | Connector-first default + credential separation + multi-layer source-of-truth + cross-session resilience |
|
|
16
16
|
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
17
17
|
|
|
18
18
|
## Routing Rule
|