@adamchanadam/agent-handoff-kit 0.3.27 → 0.3.28
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 +12 -8
- package/bin/agent-handoff-kit.mjs +37 -4
- package/package.json +1 -1
- package/packs/agent-governance.md +2 -2
- package/runtime-core/RULE_PACKS.md +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.28`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -35,7 +35,7 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
|
|
|
35
35
|
| 問題 | Agent Handoff Kit 怎樣處理 |
|
|
36
36
|
|---|---|
|
|
37
37
|
| 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
|
|
38
|
-
| 新建檔案、參考資料變孤兒 | 你可以叫 AI
|
|
38
|
+
| 新建檔案、參考資料變孤兒 | 你可以叫 AI 把文件接入 Agent Handoff Kit,用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
|
|
39
39
|
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
|
|
40
40
|
| AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
41
41
|
|
|
@@ -227,13 +227,16 @@ dev/rules/*.md
|
|
|
227
227
|
|
|
228
228
|
新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
|
|
229
229
|
|
|
230
|
-
##
|
|
230
|
+
## 把重要文件接入 Agent Handoff Kit
|
|
231
231
|
|
|
232
232
|
長期項目常會產生新文件,例如 stock list、production guide、runbook、workflow、checklist、研究真源或操作清單。文件本身做完,不代表下一個 AI 一定知道它存在,也不代表 AI 知道何時要讀、何時要更新、是否有另一份舊版真源。
|
|
233
233
|
|
|
234
|
-
|
|
234
|
+
常見有兩種用法。
|
|
235
|
+
|
|
236
|
+
第一種是指定一份文件,讓 AI 審核這份文件是否已接入治理層:
|
|
235
237
|
|
|
236
238
|
```text
|
|
239
|
+
把 docs/production-guide.md 接入 Agent Handoff Kit
|
|
237
240
|
治理打通 docs/production-guide.md
|
|
238
241
|
```
|
|
239
242
|
|
|
@@ -246,14 +249,15 @@ connect this document to governance
|
|
|
246
249
|
|
|
247
250
|
AI 會檢查這份文件是否已接入項目記憶:文件本身是否講清楚用途與更新時機、`dev/PROJECT_INDEX.md` 是否登記它、`dev/DOC_SYNC_REGISTRY.md` 是否記下同類變更要同步哪裡、相關 workflow 是否會提醒更新它,以及 handoff / log 是否各自放在正確角色。
|
|
248
251
|
|
|
249
|
-
|
|
252
|
+
第二種是不指定單一文件,先掃描整個 repo 有沒有疑似未接合的重要文件:
|
|
250
253
|
|
|
251
254
|
```text
|
|
255
|
+
掃描未接入 Agent Handoff Kit 的重要文件
|
|
252
256
|
掃描 repo 有沒有未接合文件
|
|
253
257
|
scan for unbridged governance documents
|
|
254
258
|
```
|
|
255
259
|
|
|
256
|
-
|
|
260
|
+
這個掃描只列出候選與缺口,不會一邊掃描一邊自動修改。若你同意其中某個建議,可以再叫 AI 按建議補丁更新索引、同步登記或相關流程。若涉及刪除、改名、合併真源,AI 只會列出合併、引用或退役建議,等你明確確認。
|
|
257
261
|
|
|
258
262
|
## 外部工具治理
|
|
259
263
|
|
|
@@ -279,7 +283,7 @@ scan for unbridged governance documents
|
|
|
279
283
|
| 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
|
|
280
284
|
| 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
|
|
281
285
|
| 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
|
|
282
|
-
| 新建重要文件後想避免變孤兒 | AI
|
|
286
|
+
| 新建重要文件後想避免變孤兒 | AI 治理規則;說「把 <檔案> 接入 Agent Handoff Kit」,讓 AI 檢查索引、同步責任、相關流程與重複真源風險 |
|
|
283
287
|
|
|
284
288
|
原則是只讀當前任務需要的規則,不是每次讀全部文件。
|
|
285
289
|
|
|
@@ -314,7 +318,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
314
318
|
|
|
315
319
|
## 目前限制
|
|
316
320
|
|
|
317
|
-
- 目前版本為 `v0.3.
|
|
321
|
+
- 目前版本為 `v0.3.28`;正式安裝請以 npm registry `latest` 顯示為準。
|
|
318
322
|
- 這是早期可用版本,仍在持續完善中。
|
|
319
323
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
320
324
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -382,6 +382,8 @@ const schemaChecks = [
|
|
|
382
382
|
// R-030 v0.3.0+: routing table must include integrations pack row.
|
|
383
383
|
includes("dev/rules/integrations.md"),
|
|
384
384
|
includes("Governance bridge / 治理打通"),
|
|
385
|
+
includes("接入 Agent Handoff Kit"),
|
|
386
|
+
includes("掃描未接入 Agent Handoff Kit 的重要文件"),
|
|
385
387
|
includes("scan for unbridged governance documents")
|
|
386
388
|
]
|
|
387
389
|
},
|
|
@@ -396,6 +398,8 @@ const schemaChecks = [
|
|
|
396
398
|
heading("Checks"),
|
|
397
399
|
heading("Closeout"),
|
|
398
400
|
includes("Governance bridge is a triggered review"),
|
|
401
|
+
includes("接入 Agent Handoff Kit"),
|
|
402
|
+
includes("掃描未接入 Agent Handoff Kit 的重要文件"),
|
|
399
403
|
includes("Status: bridged / partially bridged / unbridged / blocked"),
|
|
400
404
|
includes("duplicate source-of-truth risk")
|
|
401
405
|
]
|
|
@@ -1576,7 +1580,11 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1576
1580
|
}
|
|
1577
1581
|
// Governance bridge v0.3.27+: route durable document bridging requests to
|
|
1578
1582
|
// agent-governance without replacing user-added routing rows.
|
|
1579
|
-
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" &&
|
|
1583
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && (
|
|
1584
|
+
!targetText.includes("Governance bridge / 治理打通")
|
|
1585
|
+
|| !targetText.includes("接入 Agent Handoff Kit")
|
|
1586
|
+
|| !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件")
|
|
1587
|
+
)) {
|
|
1580
1588
|
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1581
1589
|
if (!mergedRulePacks) {
|
|
1582
1590
|
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
@@ -1590,7 +1598,11 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1590
1598
|
}
|
|
1591
1599
|
// Governance bridge v0.3.27+: add the triggered review workflow to the
|
|
1592
1600
|
// agent-governance pack only when the pack still has a trusted Checks section.
|
|
1593
|
-
if (targetRel === "dev/rules/agent-governance.md" && command === "upgrade" &&
|
|
1601
|
+
if (targetRel === "dev/rules/agent-governance.md" && command === "upgrade" && (
|
|
1602
|
+
!targetText.includes("## Governance Bridge Workflow")
|
|
1603
|
+
|| !targetText.includes("接入 Agent Handoff Kit")
|
|
1604
|
+
|| !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件")
|
|
1605
|
+
)) {
|
|
1594
1606
|
const mergedGovernancePack = mergeAgentGovernanceBridgeWorkflow(targetText, sourceText);
|
|
1595
1607
|
if (!mergedGovernancePack) {
|
|
1596
1608
|
return { ...base, action: "conflict", reason: "agent-governance pack structure was changed; manual merge required to add governance bridge workflow" };
|
|
@@ -1806,9 +1818,19 @@ function mergeOnboardingScenarioALabel(targetText) {
|
|
|
1806
1818
|
function mergeAgentGovernanceBridgeWorkflow(targetText, sourceText) {
|
|
1807
1819
|
const sourceMatch = sourceText.match(/9\. Governance bridge[\s\S]*?(?=\n## Checks)/);
|
|
1808
1820
|
const workflowMatch = sourceText.match(/\n## Governance Bridge Workflow[\s\S]*?(?=\n## Checks)/);
|
|
1821
|
+
const sourceLoadWhenLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("- User asks to \"治理打通\""));
|
|
1822
|
+
const sourceWorkflowIntroLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("Use this workflow when"));
|
|
1809
1823
|
if (!sourceMatch || !workflowMatch || !targetText.includes("\n## Checks")) return null;
|
|
1810
1824
|
|
|
1811
1825
|
let merged = targetText;
|
|
1826
|
+
const targetLoadWhenLine = merged.split(/\r?\n/).find((line) => line.startsWith("- User asks to \"治理打通\""));
|
|
1827
|
+
if (sourceLoadWhenLine && (!targetLoadWhenLine || !targetLoadWhenLine.includes("接入 Agent Handoff Kit"))) {
|
|
1828
|
+
merged = merged.replace(/- User asks to "治理打通"[^\n]*\n/, `${sourceLoadWhenLine}\n`);
|
|
1829
|
+
}
|
|
1830
|
+
const targetWorkflowIntroLine = merged.match(/^Use this workflow when[^\n]*$/m)?.[0] ?? "";
|
|
1831
|
+
if (sourceWorkflowIntroLine && !targetWorkflowIntroLine.includes("掃描未接入 Agent Handoff Kit 的重要文件")) {
|
|
1832
|
+
merged = merged.replace(/^Use this workflow when[^\n]*$/m, sourceWorkflowIntroLine);
|
|
1833
|
+
}
|
|
1812
1834
|
if (!merged.includes("Governance bridge is a triggered review")) {
|
|
1813
1835
|
const rulePrefix = sourceMatch[0].trimEnd();
|
|
1814
1836
|
merged = merged.replace(/\n## Checks/, `\n${rulePrefix}\n${workflowMatch[0]}\n## Checks`);
|
|
@@ -2452,8 +2474,19 @@ function mergeRulePacksRows(targetText, sourceText) {
|
|
|
2452
2474
|
|
|
2453
2475
|
const before = lines.slice(0, tableStart);
|
|
2454
2476
|
const table = lines.slice(tableStart, tableEnd);
|
|
2455
|
-
const after = lines.slice(tableEnd);
|
|
2456
|
-
const
|
|
2477
|
+
const after = lines.slice(tableEnd);
|
|
2478
|
+
const governanceBridgeSourceRow = sourceRows.find((row) => row.includes("Governance bridge / 治理打通"));
|
|
2479
|
+
if (
|
|
2480
|
+
governanceBridgeSourceRow
|
|
2481
|
+
&& targetText.includes("Governance bridge / 治理打通")
|
|
2482
|
+
&& (!targetText.includes("接入 Agent Handoff Kit") || !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件"))
|
|
2483
|
+
) {
|
|
2484
|
+
const replaced = lines.map((line) => (
|
|
2485
|
+
line.includes("Governance bridge / 治理打通") ? governanceBridgeSourceRow : line
|
|
2486
|
+
));
|
|
2487
|
+
return replaced.join("\n");
|
|
2488
|
+
}
|
|
2489
|
+
const sourceRowsToApply = sourceRows.filter((row) => {
|
|
2457
2490
|
if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
|
|
2458
2491
|
if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
|
|
2459
2492
|
if (row.includes("Governance bridge / 治理打通")) return !targetText.includes("Governance bridge / 治理打通");
|
package/package.json
CHANGED
|
@@ -8,7 +8,7 @@ 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 "治理打通", "bridge governance", "connect this document to governance", or scan for unbridged governance documents.
|
|
11
|
+
- User asks to "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", "掃描未接入 Agent Handoff Kit 的重要文件", "bridge governance", "connect this document to governance", or scan for unbridged governance documents.
|
|
12
12
|
|
|
13
13
|
## Rules
|
|
14
14
|
|
|
@@ -24,7 +24,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
24
24
|
|
|
25
25
|
## Governance Bridge Workflow
|
|
26
26
|
|
|
27
|
-
Use this workflow when the user asks for governance bridge / 治理打通 / connect this document to governance, or asks to scan for unbridged governance documents
|
|
27
|
+
Use this workflow when the user asks for governance bridge / 治理打通 / 把文件接入 Agent Handoff Kit / 接入 Agent Handoff Kit / connect this document to governance, or asks to scan for unbridged governance documents / 掃描未接入 Agent Handoff Kit 的重要文件.
|
|
28
28
|
|
|
29
29
|
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.
|
|
30
30
|
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.
|
|
@@ -10,7 +10,7 @@ Read only the packs needed for the current task.
|
|
|
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
|
-
| Governance bridge / 治理打通 / bridge governance / connect this document to governance / scan for unbridged governance documents | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
13
|
+
| Governance bridge / 治理打通 / 把文件接入 Agent Handoff Kit / 接入 Agent Handoff Kit / 掃描未接入 Agent Handoff Kit 的重要文件 / bridge governance / connect this document to governance / scan for unbridged governance documents | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
14
14
|
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
15
15
|
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
16
16
|
| 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 |
|