@adamchanadam/agent-handoff-kit 0.3.26 → 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 +42 -9
- package/bin/agent-handoff-kit.mjs +124 -25
- package/package.json +1 -1
- package/packs/agent-governance.md +27 -0
- package/runtime-core/RULE_PACKS.md +2 -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
|
-
| 新建檔案、參考資料變孤兒 |
|
|
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
|
|
|
@@ -225,9 +225,41 @@ dev/rules/*.md
|
|
|
225
225
|
|
|
226
226
|
當交接文件中的決策清單累積到三十條以上,AI 會自動把較舊的條目搬入本檔,保持交接文件簡潔。
|
|
227
227
|
|
|
228
|
-
新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
|
|
229
|
-
|
|
230
|
-
##
|
|
228
|
+
新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
|
|
229
|
+
|
|
230
|
+
## 把重要文件接入 Agent Handoff Kit
|
|
231
|
+
|
|
232
|
+
長期項目常會產生新文件,例如 stock list、production guide、runbook、workflow、checklist、研究真源或操作清單。文件本身做完,不代表下一個 AI 一定知道它存在,也不代表 AI 知道何時要讀、何時要更新、是否有另一份舊版真源。
|
|
233
|
+
|
|
234
|
+
常見有兩種用法。
|
|
235
|
+
|
|
236
|
+
第一種是指定一份文件,讓 AI 審核這份文件是否已接入治理層:
|
|
237
|
+
|
|
238
|
+
```text
|
|
239
|
+
把 docs/production-guide.md 接入 Agent Handoff Kit
|
|
240
|
+
治理打通 docs/production-guide.md
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
英文也可以說:
|
|
244
|
+
|
|
245
|
+
```text
|
|
246
|
+
bridge governance for docs/production-guide.md
|
|
247
|
+
connect this document to governance
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
AI 會檢查這份文件是否已接入項目記憶:文件本身是否講清楚用途與更新時機、`dev/PROJECT_INDEX.md` 是否登記它、`dev/DOC_SYNC_REGISTRY.md` 是否記下同類變更要同步哪裡、相關 workflow 是否會提醒更新它,以及 handoff / log 是否各自放在正確角色。
|
|
251
|
+
|
|
252
|
+
第二種是不指定單一文件,先掃描整個 repo 有沒有疑似未接合的重要文件:
|
|
253
|
+
|
|
254
|
+
```text
|
|
255
|
+
掃描未接入 Agent Handoff Kit 的重要文件
|
|
256
|
+
掃描 repo 有沒有未接合文件
|
|
257
|
+
scan for unbridged governance documents
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
這個掃描只列出候選與缺口,不會一邊掃描一邊自動修改。若你同意其中某個建議,可以再叫 AI 按建議補丁更新索引、同步登記或相關流程。若涉及刪除、改名、合併真源,AI 只會列出合併、引用或退役建議,等你明確確認。
|
|
261
|
+
|
|
262
|
+
## 外部工具治理
|
|
231
263
|
|
|
232
264
|
如你的項目涉及外部工具(例如 Notion、Google Drive、Slack、Linear、GitHub 等),Agent Handoff Kit 提供跨對話的治理紀律,確保 AI 在不同對話之間能穩定使用這些工具。
|
|
233
265
|
|
|
@@ -248,9 +280,10 @@ dev/rules/*.md
|
|
|
248
280
|
| 寫或改代碼、檢查錯誤、執行測試 | 寫代碼規則;涉及刪除、覆寫、Git、套件管理或外部服務時,再讀安全規則 |
|
|
249
281
|
| 查資料、比較來源、整理證據 | 研究規則 |
|
|
250
282
|
| 改 README、寫說明、整理文案 | 寫作規則,通常再加溝通規則 |
|
|
251
|
-
| 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
|
|
252
|
-
| 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
|
|
253
|
-
| 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
|
|
283
|
+
| 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
|
|
284
|
+
| 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
|
|
285
|
+
| 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
|
|
286
|
+
| 新建重要文件後想避免變孤兒 | AI 治理規則;說「把 <檔案> 接入 Agent Handoff Kit」,讓 AI 檢查索引、同步責任、相關流程與重複真源風險 |
|
|
254
287
|
|
|
255
288
|
原則是只讀當前任務需要的規則,不是每次讀全部文件。
|
|
256
289
|
|
|
@@ -285,7 +318,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
285
318
|
|
|
286
319
|
## 目前限制
|
|
287
320
|
|
|
288
|
-
- 目前版本為 `v0.3.
|
|
321
|
+
- 目前版本為 `v0.3.28`;正式安裝請以 npm registry `latest` 顯示為準。
|
|
289
322
|
- 這是早期可用版本,仍在持續完善中。
|
|
290
323
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
291
324
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -363,11 +363,11 @@ const schemaChecks = [
|
|
|
363
363
|
tableHeader("Change type", "Also check/update", "Verification")
|
|
364
364
|
]
|
|
365
365
|
},
|
|
366
|
-
{
|
|
367
|
-
target: "dev/RULE_PACKS.md",
|
|
368
|
-
label: "rule pack router coverage",
|
|
369
|
-
checks: [
|
|
370
|
-
heading("Routing Rule"),
|
|
366
|
+
{
|
|
367
|
+
target: "dev/RULE_PACKS.md",
|
|
368
|
+
label: "rule pack router coverage",
|
|
369
|
+
checks: [
|
|
370
|
+
heading("Routing Rule"),
|
|
371
371
|
includes("Load the minimum set"),
|
|
372
372
|
includes("cannot weaken core safety"),
|
|
373
373
|
includes("dev/rules/safety.md"),
|
|
@@ -379,10 +379,31 @@ const schemaChecks = [
|
|
|
379
379
|
// stale routing table that does not route onboarding signals.
|
|
380
380
|
includes("First-time user signals"),
|
|
381
381
|
includes("dev/rules/onboarding.md"),
|
|
382
|
-
// R-030 v0.3.0+: routing table must include integrations pack row.
|
|
383
|
-
includes("dev/rules/integrations.md")
|
|
384
|
-
|
|
385
|
-
|
|
382
|
+
// R-030 v0.3.0+: routing table must include integrations pack row.
|
|
383
|
+
includes("dev/rules/integrations.md"),
|
|
384
|
+
includes("Governance bridge / 治理打通"),
|
|
385
|
+
includes("接入 Agent Handoff Kit"),
|
|
386
|
+
includes("掃描未接入 Agent Handoff Kit 的重要文件"),
|
|
387
|
+
includes("scan for unbridged governance documents")
|
|
388
|
+
]
|
|
389
|
+
},
|
|
390
|
+
{
|
|
391
|
+
target: "dev/rules/agent-governance.md",
|
|
392
|
+
label: "agent governance pack structure",
|
|
393
|
+
checks: [
|
|
394
|
+
heading("Scope"),
|
|
395
|
+
heading("Load When"),
|
|
396
|
+
heading("Rules"),
|
|
397
|
+
heading("Governance Bridge Workflow"),
|
|
398
|
+
heading("Checks"),
|
|
399
|
+
heading("Closeout"),
|
|
400
|
+
includes("Governance bridge is a triggered review"),
|
|
401
|
+
includes("接入 Agent Handoff Kit"),
|
|
402
|
+
includes("掃描未接入 Agent Handoff Kit 的重要文件"),
|
|
403
|
+
includes("Status: bridged / partially bridged / unbridged / blocked"),
|
|
404
|
+
includes("duplicate source-of-truth risk")
|
|
405
|
+
]
|
|
406
|
+
},
|
|
386
407
|
{
|
|
387
408
|
target: "dev/PROJECT_DECISIONS.md",
|
|
388
409
|
label: "project decisions log structure",
|
|
@@ -1545,18 +1566,54 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1545
1566
|
};
|
|
1546
1567
|
}
|
|
1547
1568
|
// R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
|
|
1548
|
-
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
|
|
1549
|
-
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1550
|
-
if (!mergedRulePacks) {
|
|
1551
|
-
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1569
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
|
|
1570
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1571
|
+
if (!mergedRulePacks) {
|
|
1572
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1552
1573
|
}
|
|
1553
1574
|
return {
|
|
1554
1575
|
...base,
|
|
1555
1576
|
action: "merge",
|
|
1556
1577
|
reason: "merge missing v0.3.0+ routing rows while preserving existing custom rows (Integration governance routing)",
|
|
1557
|
-
mergedText: mergedRulePacks
|
|
1558
|
-
};
|
|
1559
|
-
}
|
|
1578
|
+
mergedText: mergedRulePacks
|
|
1579
|
+
};
|
|
1580
|
+
}
|
|
1581
|
+
// Governance bridge v0.3.27+: route durable document bridging requests to
|
|
1582
|
+
// agent-governance without replacing user-added routing rows.
|
|
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
|
+
)) {
|
|
1588
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1589
|
+
if (!mergedRulePacks) {
|
|
1590
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1591
|
+
}
|
|
1592
|
+
return {
|
|
1593
|
+
...base,
|
|
1594
|
+
action: "merge",
|
|
1595
|
+
reason: "merge missing governance bridge routing row while preserving existing custom rows",
|
|
1596
|
+
mergedText: mergedRulePacks
|
|
1597
|
+
};
|
|
1598
|
+
}
|
|
1599
|
+
// Governance bridge v0.3.27+: add the triggered review workflow to the
|
|
1600
|
+
// agent-governance pack only when the pack still has a trusted Checks section.
|
|
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
|
+
)) {
|
|
1606
|
+
const mergedGovernancePack = mergeAgentGovernanceBridgeWorkflow(targetText, sourceText);
|
|
1607
|
+
if (!mergedGovernancePack) {
|
|
1608
|
+
return { ...base, action: "conflict", reason: "agent-governance pack structure was changed; manual merge required to add governance bridge workflow" };
|
|
1609
|
+
}
|
|
1610
|
+
return {
|
|
1611
|
+
...base,
|
|
1612
|
+
action: "merge",
|
|
1613
|
+
reason: "insert governance bridge workflow into agent-governance pack without replacing local additions",
|
|
1614
|
+
mergedText: mergedGovernancePack
|
|
1615
|
+
};
|
|
1616
|
+
}
|
|
1560
1617
|
// R-030 v0.3.0+: dev/PROJECT_INDEX.md gets ## Installed Integrations section auto-inserted before
|
|
1561
1618
|
// ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
|
|
1562
1619
|
// is fully preserved (including any user-filled rows). User can later manually add the `via` column
|
|
@@ -1729,7 +1786,7 @@ function isUpgradeFromOlderTemplate(context) {
|
|
|
1729
1786
|
&& compareSemver(rootTemplateVersion, currentVersion) < 0;
|
|
1730
1787
|
}
|
|
1731
1788
|
|
|
1732
|
-
function looksLikeExpandedKitBridge(targetRel, text) {
|
|
1789
|
+
function looksLikeExpandedKitBridge(targetRel, text) {
|
|
1733
1790
|
if (text.includes("This file is a bridge only")) return false;
|
|
1734
1791
|
if (targetRel === "CLAUDE.md") {
|
|
1735
1792
|
return (text.includes("This file provides guidance to Claude Code") && text.includes("## Session Startup"))
|
|
@@ -1758,6 +1815,35 @@ function mergeOnboardingScenarioALabel(targetText) {
|
|
|
1758
1815
|
return merged;
|
|
1759
1816
|
}
|
|
1760
1817
|
|
|
1818
|
+
function mergeAgentGovernanceBridgeWorkflow(targetText, sourceText) {
|
|
1819
|
+
const sourceMatch = sourceText.match(/9\. Governance bridge[\s\S]*?(?=\n## Checks)/);
|
|
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"));
|
|
1823
|
+
if (!sourceMatch || !workflowMatch || !targetText.includes("\n## Checks")) return null;
|
|
1824
|
+
|
|
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
|
+
}
|
|
1834
|
+
if (!merged.includes("Governance bridge is a triggered review")) {
|
|
1835
|
+
const rulePrefix = sourceMatch[0].trimEnd();
|
|
1836
|
+
merged = merged.replace(/\n## Checks/, `\n${rulePrefix}\n${workflowMatch[0]}\n## Checks`);
|
|
1837
|
+
}
|
|
1838
|
+
if (!merged.includes("For governance bridge work, confirm the target file")) {
|
|
1839
|
+
merged = merged.replace(
|
|
1840
|
+
"- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.",
|
|
1841
|
+
"- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.\n- For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable."
|
|
1842
|
+
);
|
|
1843
|
+
}
|
|
1844
|
+
return merged;
|
|
1845
|
+
}
|
|
1846
|
+
|
|
1761
1847
|
function hasTrustedOnboardingScenarioLibrary(text) {
|
|
1762
1848
|
const bounds = textSectionBounds(text, "## Application Scenario Library", "## Cross-reference to guide.html");
|
|
1763
1849
|
if (!bounds) return false;
|
|
@@ -2371,8 +2457,9 @@ function mergeHandoffArchiveContinuityRule(targetText, sourceText) {
|
|
|
2371
2457
|
function mergeRulePacksRows(targetText, sourceText) {
|
|
2372
2458
|
const requiredPacks = [
|
|
2373
2459
|
"dev/rules/onboarding.md",
|
|
2374
|
-
"dev/rules/integrations.md"
|
|
2375
|
-
|
|
2460
|
+
"dev/rules/integrations.md",
|
|
2461
|
+
"dev/rules/agent-governance.md"
|
|
2462
|
+
];
|
|
2376
2463
|
const sourceRows = sourceText
|
|
2377
2464
|
.split(/\r?\n/)
|
|
2378
2465
|
.filter((line) => line.startsWith("|") && requiredPacks.some((pack) => line.includes(pack)));
|
|
@@ -2387,12 +2474,24 @@ function mergeRulePacksRows(targetText, sourceText) {
|
|
|
2387
2474
|
|
|
2388
2475
|
const before = lines.slice(0, tableStart);
|
|
2389
2476
|
const table = lines.slice(tableStart, tableEnd);
|
|
2390
|
-
const after = lines.slice(tableEnd);
|
|
2391
|
-
const
|
|
2392
|
-
|
|
2393
|
-
|
|
2394
|
-
|
|
2395
|
-
|
|
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) => {
|
|
2490
|
+
if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
|
|
2491
|
+
if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
|
|
2492
|
+
if (row.includes("Governance bridge / 治理打通")) return !targetText.includes("Governance bridge / 治理打通");
|
|
2493
|
+
return false;
|
|
2494
|
+
});
|
|
2396
2495
|
if (sourceRowsToApply.length === 0) return targetText;
|
|
2397
2496
|
|
|
2398
2497
|
const merged = [
|
package/package.json
CHANGED
|
@@ -8,6 +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 "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", "掃描未接入 Agent Handoff Kit 的重要文件", "bridge governance", "connect this document to governance", or scan for unbridged governance documents.
|
|
11
12
|
|
|
12
13
|
## Rules
|
|
13
14
|
|
|
@@ -19,6 +20,31 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
19
20
|
6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
|
|
20
21
|
7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
|
|
21
22
|
8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
|
|
23
|
+
9. Governance bridge is a triggered review, not a default startup scan. Use it when an important file, source-of-truth document, runbook, production guide, workflow, checklist, stock list, or similar durable document may need to be connected to project governance.
|
|
24
|
+
|
|
25
|
+
## Governance Bridge Workflow
|
|
26
|
+
|
|
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
|
+
|
|
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
|
+
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.
|
|
31
|
+
3. Check `dev/PROJECT_INDEX.md`: the file should be discoverable with its role and "read when" condition. Source-of-truth or reference files should appear in Fact Base, External Sources, Directory Map, Entry Points, or another existing indexed home that fits the project.
|
|
32
|
+
4. Check `dev/DOC_SYNC_REGISTRY.md`: future same-type changes should have a matching change type or an explicit reason no durable sync rule is needed.
|
|
33
|
+
5. Check related workflows, guides, runbooks, or rule packs: if a process creates or updates the file, that process should say when to update the file or its index row.
|
|
34
|
+
6. Check `dev/SESSION_HANDOFF.md`: only current state, next action, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
|
|
35
|
+
7. Check `dev/SESSION_LOG.md`: this session's bridge review, validation, and evidence can be logged when it affects future action, but log entries must not become current state.
|
|
36
|
+
8. Search for duplicate source-of-truth risk. If another file has the same durable role, recommend merge, reference, or retire options; do not delete, rename, or move files without explicit approval.
|
|
37
|
+
|
|
38
|
+
For repo-wide scans, report candidates as candidates. Do not fail ordinary docs merely because they are not indexed; only durable files that future agents need to discover, update, or distinguish from drafts should be bridged.
|
|
39
|
+
|
|
40
|
+
Output format:
|
|
41
|
+
|
|
42
|
+
- Status: bridged / partially bridged / unbridged / blocked.
|
|
43
|
+
- Already bridged: list the governance links that are present.
|
|
44
|
+
- Gaps: list missing links and why they matter for the next agent.
|
|
45
|
+
- Suggested patches: list exact files and sections to update.
|
|
46
|
+
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
47
|
+
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
22
48
|
|
|
23
49
|
## Checks
|
|
24
50
|
|
|
@@ -27,6 +53,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
27
53
|
- Confirm old overlapping wording was retired or marked legacy.
|
|
28
54
|
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
29
55
|
- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
|
|
56
|
+
- For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.
|
|
30
57
|
- Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
|
|
31
58
|
- For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
|
|
32
59
|
|
|
@@ -9,7 +9,8 @@ Read only the packs needed for the current task.
|
|
|
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
|
-
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
12
|
+
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
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 |
|
|
13
14
|
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
14
15
|
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
15
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 |
|