@adamchanadam/agent-handoff-kit 0.3.44 → 0.3.46

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 CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Prompt Templates
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Prompt Templates
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [繁體中文](README.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
4
4
 
5
- Current source candidate: `v0.3.44`. The currently published npm release is `v0.3.43`.
5
+ Current published release: `v0.3.46` (GitHub Release and npm `@latest`).
6
6
 
7
7
  <p align="center">
8
8
  <img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit overview animation" width="720">
@@ -33,10 +33,18 @@ You do not decide whether the folder needs an install, upgrade, health check, or
33
33
 
34
34
  If the folder already contains older Kit files or AI memory files such as `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`, use the same request. The AI inspects first; it must not silently overwrite them.
35
35
 
36
- For a non-technical introduction, open the [English introduction](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html). For complete walkthroughs, open the [English practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html).
37
- To see how Agent Handoff Kit sits in a local agentic AI workflow, open [`local-agentic-ai-workflow-case-study.en.html`](https://adamchanadam.github.io/agent-handoff-kit/local-agentic-ai-workflow-case-study.en.html).
38
-
39
- ## 🧭 How to read this repository
36
+ For a non-technical introduction, open the [English introduction](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html). For complete walkthroughs, open the [English practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html).
37
+ To see how Agent Handoff Kit sits in a local agentic AI workflow, open [`local-agentic-ai-workflow-case-study.en.html`](https://adamchanadam.github.io/agent-handoff-kit/local-agentic-ai-workflow-case-study.en.html).
38
+
39
+ ## 🐱 How to read the status card
40
+
41
+ | Status | Meaning |
42
+ |---|---|
43
+ | `( o.o ) continuity ready` | Ready to continue; the AI has loaded resumable state. |
44
+ | `( -.- ) handoff saved` | Closeout has been saved; next time you can say `Start Agent Handoff` or `開工`. |
45
+ | `( x.x ) handoff blocked` | Not broken; something still needs to be saved, committed, verified, or handled. Follow the Blocker line first and do not treat this session as handed off. |
46
+
47
+ ## 🧭 How to read this repository
40
48
 
41
49
  If you only want to use the kit, start from these four pages:
42
50
 
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  English: [README.en.md](README.en.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
4
4
 
5
- 目前候選版本:`v0.3.44`(尚未發佈);正式可用版本是 `v0.3.43`。
5
+ 目前正式版本:`v0.3.46`(GitHub Release 與 npm `@latest`)。
6
6
 
7
7
  <p align="center">
8
8
  <img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
@@ -29,13 +29,21 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
29
29
  2. 安裝完成後,對 AI 說 `Start Agent Handoff` 或「開工」。
30
30
  3. 完成本輪工作後,對 AI 說「收工」。
31
31
 
32
- 🔎 你不用判斷安裝、升級、檢查或檔案結構。AI 會先說明它看到的資料夾、風險與下一步;需要你確認時才停下來。
33
-
34
- 已裝過舊版,或資料夾裡已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,也用同一句交給 AI 判斷。AI 會先檢查,不會靜默覆寫。
35
-
36
- 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html)。想看完整操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html)。想了解它在本機 Agentic AI 工作系統中的位置,可看 [`local-agentic-ai-workflow-case-study.html`](https://adamchanadam.github.io/agent-handoff-kit/local-agentic-ai-workflow-case-study.html)。
37
-
38
- ## 🧭 這個 repo 怎樣讀
32
+ 🔎 你不用判斷安裝、升級、檢查或檔案結構。AI 會先說明它看到的資料夾、風險與下一步;需要你確認時才停下來。
33
+
34
+ 已裝過舊版,或資料夾裡已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,也用同一句交給 AI 判斷。AI 會先檢查,不會靜默覆寫。
35
+
36
+ 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html)。想看完整操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html)。想了解它在本機 Agentic AI 工作系統中的位置,可看 [`local-agentic-ai-workflow-case-study.html`](https://adamchanadam.github.io/agent-handoff-kit/local-agentic-ai-workflow-case-study.html)。
37
+
38
+ ## 🐱 狀態卡怎樣讀
39
+
40
+ | 狀態 | 意思 |
41
+ |---|---|
42
+ | `( o.o ) continuity ready` | 可以接力,AI 已讀到可繼續的狀態。 |
43
+ | `( -.- ) handoff saved` | 已收工保存,下次可以再說「開工」。 |
44
+ | `( x.x ) handoff blocked` | 不是壞了;只是仍有未保存、未提交、未驗證或需要處理的事。先照 Blocker 行處理,不要把本輪當作已完成交接。 |
45
+
46
+ ## 🧭 這個 repo 怎樣讀
39
47
 
40
48
  如果你只是想使用 Agent Handoff Kit,只需要看四個入口:
41
49
 
@@ -654,6 +654,7 @@ function printCloseoutStatusCard(version, result) {
654
654
  console.log("");
655
655
  console.log("status: blocked");
656
656
  console.log(`⚠️ Blocker: ${result.findings.join("; ")}`);
657
+ console.log("💬 說明:這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。");
657
658
  console.log("📌 Handoff: keep the current state resumable; do not call this closeout complete");
658
659
  }
659
660
 
@@ -1,4 +1,4 @@
1
- import { lstatSync, readFileSync, readdirSync } from "node:fs";
1
+ import { lstatSync, readFileSync, readdirSync } from "node:fs";
2
2
  import path from "node:path";
3
3
 
4
4
  const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
@@ -26,28 +26,28 @@ export function assessPromptMirrorRoot(root) {
26
26
  return { status: "missing", ok: false, reason: "prompt copy unreadable" };
27
27
  }
28
28
 
29
- const otherTexts = collectCurrentGovernanceTexts(root, new Set([
30
- path.resolve(handoffPath),
31
- path.resolve(promptPath)
32
- ]));
33
- return assessPromptMirrorTexts(handoffText, promptText, otherTexts);
34
- }
35
-
36
- export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []) {
37
- const markerCount = countLiteral(handoffText, openingSectionMarker);
38
- const headingCount = (handoffText.match(new RegExp(openingHeadingPattern.source, "gm")) ?? []).length;
39
- const contentMarkerCount = openingContentMarkers.reduce((sum, marker) => sum + countLiteral(handoffText, marker), 0);
40
- const openingSection = markerCount === 1 ? handoffText.slice(handoffText.indexOf(openingSectionMarker)) : "";
41
- const fenceCount = (openingSection.match(/```text[^\r\n]*(?:\r\n?|\n)[\s\S]*?(?:\r\n?|\n)```/g) ?? []).length;
42
- if (markerCount !== 1 || headingCount > 1 || contentMarkerCount !== 1 || fenceCount !== 1) {
43
- return {
44
- status: "structure-invalid",
45
- ok: false,
46
- reason: `opening structure must be unique (section marker=${markerCount}, heading=${headingCount}, copy marker=${contentMarkerCount}, fenced text=${fenceCount})`
47
- };
48
- }
49
-
50
- const openingMessage = extractOpeningMessage(handoffText);
29
+ const otherTexts = collectCurrentGovernanceTexts(root, new Set([
30
+ path.resolve(handoffPath),
31
+ path.resolve(promptPath)
32
+ ]));
33
+ return assessPromptMirrorTexts(handoffText, promptText, otherTexts);
34
+ }
35
+
36
+ export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []) {
37
+ const markerCount = countLiteral(handoffText, openingSectionMarker);
38
+ const headingCount = (handoffText.match(new RegExp(openingHeadingPattern.source, "gm")) ?? []).length;
39
+ const contentMarkerCount = openingContentMarkers.reduce((sum, marker) => sum + countLiteral(handoffText, marker), 0);
40
+ const openingSection = markerCount === 1 ? handoffText.slice(handoffText.indexOf(openingSectionMarker)) : "";
41
+ const fenceCount = (openingSection.match(/```text[^\r\n]*(?:\r\n?|\n)[\s\S]*?(?:\r\n?|\n)```/g) ?? []).length;
42
+ if (markerCount !== 1 || headingCount > 1 || contentMarkerCount !== 1 || fenceCount !== 1) {
43
+ return {
44
+ status: "structure-invalid",
45
+ ok: false,
46
+ reason: `opening structure must be unique (section marker=${markerCount}, heading=${headingCount}, copy marker=${contentMarkerCount}, fenced text=${fenceCount})`
47
+ };
48
+ }
49
+
50
+ const openingMessage = extractOpeningMessage(handoffText);
51
51
  if (openingMessage == null) {
52
52
  return {
53
53
  status: "missing",
@@ -56,19 +56,19 @@ export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []
56
56
  };
57
57
  }
58
58
 
59
- const normalizedOpening = normalizePrompt(openingMessage);
60
- const thirdCopies = otherTexts.filter(({ text }) => normalizePrompt(text).includes(normalizedOpening));
61
- if (thirdCopies.length > 0) {
62
- return {
63
- status: "third-copy",
64
- ok: false,
65
- reason: `full opening message also appears in: ${thirdCopies.map(({ relative }) => relative).join(", ")}`,
66
- openingMessage,
67
- thirdCopies: thirdCopies.map(({ relative }) => relative)
68
- };
69
- }
70
-
71
- if (openingMessage === promptText) {
59
+ const normalizedOpening = normalizePrompt(openingMessage);
60
+ const thirdCopies = otherTexts.filter(({ text }) => normalizePrompt(text).includes(normalizedOpening));
61
+ if (thirdCopies.length > 0) {
62
+ return {
63
+ status: "third-copy",
64
+ ok: false,
65
+ reason: `full opening message also appears in: ${thirdCopies.map(({ relative }) => relative).join(", ")}`,
66
+ openingMessage,
67
+ thirdCopies: thirdCopies.map(({ relative }) => relative)
68
+ };
69
+ }
70
+
71
+ if (openingMessage === promptText) {
72
72
  return {
73
73
  status: "match",
74
74
  ok: true,
@@ -78,7 +78,7 @@ export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []
78
78
  };
79
79
  }
80
80
 
81
- const normalizedPrompt = normalizePrompt(promptText);
81
+ const normalizedPrompt = normalizePrompt(promptText);
82
82
  if (normalizedOpening === normalizedPrompt) {
83
83
  return {
84
84
  status: "newline-only",
@@ -125,7 +125,7 @@ function findOpeningSectionStart(text) {
125
125
  return headingMatch ? headingMatch.index : -1;
126
126
  }
127
127
 
128
- function firstDiff(left, right) {
128
+ function firstDiff(left, right) {
129
129
  const leftLines = left.split("\n");
130
130
  const rightLines = right.split("\n");
131
131
  const count = Math.max(leftLines.length, rightLines.length);
@@ -139,49 +139,49 @@ function firstDiff(left, right) {
139
139
  }
140
140
  }
141
141
  return null;
142
- }
143
-
144
- function countLiteral(text, token) {
145
- if (!token) return 0;
146
- let count = 0;
147
- let offset = 0;
148
- while ((offset = text.indexOf(token, offset)) >= 0) {
149
- count += 1;
150
- offset += token.length;
151
- }
152
- return count;
153
- }
154
-
155
- function collectCurrentGovernanceTexts(root, excluded) {
156
- const candidates = [
157
- "AGENTS.md",
158
- "CLAUDE.md",
159
- "GEMINI.md",
160
- "dev/SESSION_LOG.md",
161
- "dev/PROJECT_INDEX.md",
162
- "dev/DOC_SYNC_REGISTRY.md",
163
- "dev/RULE_PACKS.md",
164
- "dev/PROJECT_DECISIONS.md"
165
- ];
166
- const rulesDir = path.join(root, "dev", "rules");
167
- try {
168
- for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
169
- if (entry.isFile() && entry.name.endsWith(".md")) candidates.push(`dev/rules/${entry.name}`);
170
- }
171
- } catch {
172
- // Missing rules are reported by normal doctor checks.
173
- }
174
-
175
- const results = [];
176
- for (const relative of candidates) {
177
- const absolute = path.resolve(root, relative);
178
- if (excluded.has(absolute)) continue;
179
- try {
180
- if (lstatSync(absolute).isSymbolicLink()) continue;
181
- results.push({ relative, text: readFileSync(absolute, "utf8") });
182
- } catch {
183
- // Missing or unreadable files are handled by their owning checks.
184
- }
185
- }
186
- return results;
187
- }
142
+ }
143
+
144
+ function countLiteral(text, token) {
145
+ if (!token) return 0;
146
+ let count = 0;
147
+ let offset = 0;
148
+ while ((offset = text.indexOf(token, offset)) >= 0) {
149
+ count += 1;
150
+ offset += token.length;
151
+ }
152
+ return count;
153
+ }
154
+
155
+ function collectCurrentGovernanceTexts(root, excluded) {
156
+ const candidates = [
157
+ "AGENTS.md",
158
+ "CLAUDE.md",
159
+ "GEMINI.md",
160
+ "dev/SESSION_LOG.md",
161
+ "dev/PROJECT_INDEX.md",
162
+ "dev/DOC_SYNC_REGISTRY.md",
163
+ "dev/RULE_PACKS.md",
164
+ "dev/PROJECT_DECISIONS.md"
165
+ ];
166
+ const rulesDir = path.join(root, "dev", "rules");
167
+ try {
168
+ for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
169
+ if (entry.isFile() && entry.name.endsWith(".md")) candidates.push(`dev/rules/${entry.name}`);
170
+ }
171
+ } catch {
172
+ // Missing rules are reported by normal doctor checks.
173
+ }
174
+
175
+ const results = [];
176
+ for (const relative of candidates) {
177
+ const absolute = path.resolve(root, relative);
178
+ if (excluded.has(absolute)) continue;
179
+ try {
180
+ if (lstatSync(absolute).isSymbolicLink()) continue;
181
+ results.push({ relative, text: readFileSync(absolute, "utf8") });
182
+ } catch {
183
+ // Missing or unreadable files are handled by their owning checks.
184
+ }
185
+ }
186
+ return results;
187
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.44",
3
+ "version": "0.3.46",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,103 +1,103 @@
1
- # Agent Governance Pack
2
-
3
- ## Scope
4
-
5
- Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
6
-
7
- ## Load When
8
-
9
- - User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
10
- - A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
11
- - User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
12
- - User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
13
- - The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
14
-
15
- ## Rules
16
-
17
- 1. Locate the existing source of truth before adding a rule.
18
- 2. Prefer merge, replace, or registry rows over append-only rule growth.
19
- 3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
20
- 4. Do not let development-only workspace rules enter public runtime.
21
- 5. Check complexity budget before adding default-core behavior.
22
- 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.
23
- 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.
24
- 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.
25
- 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.
26
- 10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
27
- 11. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
28
- 12. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
29
- 13. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
30
-
31
- ## Governance Bridge Workflow
32
-
33
- Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
34
-
35
- 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.
36
- 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.
37
- 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.
38
- 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.
39
- 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.
40
- 6. Check `dev/SESSION_HANDOFF.md`: only current state, recommended next action with reason, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
41
- 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.
42
- 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.
43
-
44
- 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.
45
-
46
- Output format:
47
-
48
- - Status: bridged / partially bridged / unbridged / blocked.
49
- - Use bridged only when every applicable governance link is present. If only `dev/PROJECT_INDEX.md` or `dev/SESSION_LOG.md` was updated, report partially bridged.
50
- - Already bridged: list the governance links that are present.
51
- - Gaps: list missing links and why they matter for the next agent.
52
- - Not applicable: list skipped layers with a reason.
53
- - Suggested patches: list exact files and sections to update.
54
- - Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
55
- - Acceptance: give one concrete check that proves the bridge is complete.
56
-
57
- ## Generated Artifact Governance Workflow
58
-
59
- Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
60
-
61
- 1. List the artifacts created or materially changed in this task.
62
- 2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
63
- 3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.
64
- 4. For artifacts that require future mirror, external index, publication, or repeated sync, update `dev/DOC_SYNC_REGISTRY.md` or record why no durable sync rule applies.
65
- 5. For one-time evidence, draft, or temporary files, record that classification in `dev/SESSION_LOG.md` or the task summary, and do not promote it to current handoff unless it affects the next action.
66
- 6. Search for duplicate source-of-truth risk before keeping a new document. If another file already owns the same rule, requirement, checklist, or process, merge into that file or make the new document explicitly subordinate.
67
- 7. Before claiming completion, run the available project governance check or `agent-handoff-kit doctor`; if it reports orphan artifact candidates, register, consolidate, or explicitly classify them.
68
-
69
- ## Long-term Governance Routing
70
-
71
- Use this workflow when the user asks to write something into long-term governance, turn an experience into a mechanism, make a rule apply across sessions, or when the content itself clearly has durable force.
72
-
73
- 1. Classify the knowledge before writing:
74
- - Current task contract changes, including product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope -> the existing authoritative spec / backlog / issue / runbook when one exists; otherwise `dev/SESSION_HANDOFF.md` current-state sections.
75
- - Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
76
- - Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
77
- - File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
78
- - Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
79
- - Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
80
- - Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
81
- - API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
82
- 2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
83
- 3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
84
- 4. Add or update a QA check when the same failure class could recur and can be tested.
85
- 5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
86
-
87
- ## Checks
88
-
89
- - Verify affected files are indexed or intentionally installed templates.
90
- - Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
91
- - Confirm old overlapping wording was retired or marked legacy.
92
- - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
93
- - Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
94
- - Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
95
- - 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.
96
- - Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.
97
- - 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.
98
- - 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.
99
- - 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.
100
-
101
- ## Closeout
102
-
103
- Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
1
+ # Agent Governance Pack
2
+
3
+ ## Scope
4
+
5
+ Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
6
+
7
+ ## Load When
8
+
9
+ - User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
10
+ - A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
11
+ - User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
12
+ - User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
13
+ - The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
14
+
15
+ ## Rules
16
+
17
+ 1. Locate the existing source of truth before adding a rule.
18
+ 2. Prefer merge, replace, or registry rows over append-only rule growth.
19
+ 3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
20
+ 4. Do not let development-only workspace rules enter public runtime.
21
+ 5. Check complexity budget before adding default-core behavior.
22
+ 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.
23
+ 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.
24
+ 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.
25
+ 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.
26
+ 10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
27
+ 11. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
28
+ 12. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
29
+ 13. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
30
+
31
+ ## Governance Bridge Workflow
32
+
33
+ Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
34
+
35
+ 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.
36
+ 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.
37
+ 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.
38
+ 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.
39
+ 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.
40
+ 6. Check `dev/SESSION_HANDOFF.md`: only current state, recommended next action with reason, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
41
+ 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.
42
+ 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.
43
+
44
+ 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.
45
+
46
+ Output format:
47
+
48
+ - Status: bridged / partially bridged / unbridged / blocked.
49
+ - Use bridged only when every applicable governance link is present. If only `dev/PROJECT_INDEX.md` or `dev/SESSION_LOG.md` was updated, report partially bridged.
50
+ - Already bridged: list the governance links that are present.
51
+ - Gaps: list missing links and why they matter for the next agent.
52
+ - Not applicable: list skipped layers with a reason.
53
+ - Suggested patches: list exact files and sections to update.
54
+ - Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
55
+ - Acceptance: give one concrete check that proves the bridge is complete.
56
+
57
+ ## Generated Artifact Governance Workflow
58
+
59
+ Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
60
+
61
+ 1. List the artifacts created or materially changed in this task.
62
+ 2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
63
+ 3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.
64
+ 4. For artifacts that require future mirror, external index, publication, or repeated sync, update `dev/DOC_SYNC_REGISTRY.md` or record why no durable sync rule applies.
65
+ 5. For one-time evidence, draft, or temporary files, record that classification in `dev/SESSION_LOG.md` or the task summary, and do not promote it to current handoff unless it affects the next action.
66
+ 6. Search for duplicate source-of-truth risk before keeping a new document. If another file already owns the same rule, requirement, checklist, or process, merge into that file or make the new document explicitly subordinate.
67
+ 7. Before claiming completion, run the available project governance check or `agent-handoff-kit doctor`; if it reports orphan artifact candidates, register, consolidate, or explicitly classify them.
68
+
69
+ ## Long-term Governance Routing
70
+
71
+ Use this workflow when the user asks to write something into long-term governance, turn an experience into a mechanism, make a rule apply across sessions, or when the content itself clearly has durable force.
72
+
73
+ 1. Classify the knowledge before writing:
74
+ - Current task contract changes, including product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope -> the existing authoritative spec / backlog / issue / runbook when one exists; otherwise `dev/SESSION_HANDOFF.md` current-state sections.
75
+ - Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
76
+ - Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
77
+ - File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
78
+ - Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
79
+ - Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
80
+ - Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
81
+ - API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
82
+ 2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
83
+ 3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
84
+ 4. Add or update a QA check when the same failure class could recur and can be tested.
85
+ 5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
86
+
87
+ ## Checks
88
+
89
+ - Verify affected files are indexed or intentionally installed templates.
90
+ - Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
91
+ - Confirm old overlapping wording was retired or marked legacy.
92
+ - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
93
+ - Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
94
+ - Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
95
+ - 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.
96
+ - Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.
97
+ - 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.
98
+ - 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.
99
+ - 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.
100
+
101
+ ## Closeout
102
+
103
+ Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
package/packs/closeout.md CHANGED
@@ -67,7 +67,7 @@ status: complete
67
67
  ⚠️ Boundary: <important boundary or none>
68
68
  ```
69
69
 
70
- For `status: blocked`, the command instead says `handoff blocked`; retain that status and reason, then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. Do not hand-compose a third stateful prompt in the final response.
70
+ For `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. Do not hand-compose a third stateful prompt in the final response.
71
71
 
72
72
  ## Stop Conditions
73
73
 
package/packs/coding.md CHANGED
@@ -1,28 +1,28 @@
1
- # Coding Pack
2
-
3
- ## Scope
4
-
5
- Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
-
7
- ## Load When
8
-
9
- - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
- - The task depends on framework, runtime, dependency, or API behavior.
11
-
12
- ## Rules
13
-
14
- 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
- 2. Inspect relevant source, tests, configs, and docs before changing code.
16
- 3. Prefer project-local patterns and helpers over new abstractions.
17
- 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
- 5. Preserve unrelated user changes.
19
-
20
- ## Checks
21
-
22
- - Run the narrowest relevant test, build, lint, or typecheck available.
23
- - If a check cannot run, record why and what remains unverified.
24
- - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
-
26
- ## Closeout
27
-
28
- Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
1
+ # Coding Pack
2
+
3
+ ## Scope
4
+
5
+ Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
+
7
+ ## Load When
8
+
9
+ - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
+ - The task depends on framework, runtime, dependency, or API behavior.
11
+
12
+ ## Rules
13
+
14
+ 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
+ 2. Inspect relevant source, tests, configs, and docs before changing code.
16
+ 3. Prefer project-local patterns and helpers over new abstractions.
17
+ 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
+ 5. Preserve unrelated user changes.
19
+
20
+ ## Checks
21
+
22
+ - Run the narrowest relevant test, build, lint, or typecheck available.
23
+ - If a check cannot run, record why and what remains unverified.
24
+ - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
+
26
+ ## Closeout
27
+
28
+ Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
@@ -15,11 +15,11 @@ Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositor
15
15
  2. Record access mode and sync expectation before relying on external content.
16
16
  3. Prefer local durable files for installable runtime text unless the project declares otherwise.
17
17
  4. Do not perform destructive external writes without explicit confirmation.
18
- 5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
19
- (a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
20
- (b) If a declared Integration is functional in the current session (verified during startup probe per `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
21
- (c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
22
- (d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
18
+ 5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
19
+ (a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
20
+ (b) If a declared Integration is functional in the current session (verified during startup probe per `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
21
+ (c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
22
+ (d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
23
23
  6. When writing to an external mirror or index, read back the written record before claiming sync success.
24
24
  7. Preserve local file paths as plain text, code, or structured rich text fields when the external tool parses Markdown links or escape characters.
25
25
 
package/packs/research.md CHANGED
@@ -1,30 +1,30 @@
1
- # Research Pack
2
-
3
- ## Scope
4
-
5
- Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
6
-
7
- ## Load When
8
-
9
- - User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
10
- - The topic may have changed recently or needs precise attribution.
11
-
12
- ## Rules
13
-
14
- 1. Prefer primary sources, official docs, papers, standards, or direct data when available.
15
- 2. Separate verified facts, source summaries, and inference.
16
- 3. Record dates for time-sensitive facts.
17
- 4. Do not overstate confidence when sources conflict or coverage is thin.
18
- 5. Keep source quotes short and cite where evidence came from.
19
-
20
- ## Checks
21
-
22
- - Confirm source relevance, date, and authority.
23
- - Cross-check important claims with more than one source when practical.
24
- - Record open questions or unverified claims.
25
-
26
- ## Closeout
27
-
28
- Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
29
-
30
- If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
1
+ # Research Pack
2
+
3
+ ## Scope
4
+
5
+ Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
6
+
7
+ ## Load When
8
+
9
+ - User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
10
+ - The topic may have changed recently or needs precise attribution.
11
+
12
+ ## Rules
13
+
14
+ 1. Prefer primary sources, official docs, papers, standards, or direct data when available.
15
+ 2. Separate verified facts, source summaries, and inference.
16
+ 3. Record dates for time-sensitive facts.
17
+ 4. Do not overstate confidence when sources conflict or coverage is thin.
18
+ 5. Keep source quotes short and cite where evidence came from.
19
+
20
+ ## Checks
21
+
22
+ - Confirm source relevance, date, and authority.
23
+ - Cross-check important claims with more than one source when practical.
24
+ - Record open questions or unverified claims.
25
+
26
+ ## Closeout
27
+
28
+ Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
29
+
30
+ If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
@@ -1,13 +1,13 @@
1
- # Claude Code Entry Bridge
2
-
3
- @AGENTS.md
4
-
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
-
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
-
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.
10
-
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.
1
+ # Claude Code Entry Bridge
2
+
3
+ @AGENTS.md
4
+
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
+
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
+
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.
10
+
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.
@@ -1,24 +1,24 @@
1
- # Doc Sync Registry
2
-
3
- Purpose: map change types to documents and checks. Keep this as rows, not long prose.
4
-
5
- ## Status Vocabulary
6
-
7
- Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
8
-
9
- | Change type | Also check/update | Verification |
10
- |---|---|---|
11
- | New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
12
- | Generated Markdown or durable artifact | `dev/PROJECT_INDEX.md` Directory Map / Fact Base / Entry Points, and this registry when future updates need sync | artifact classified as indexed / synced / temporary / one-time evidence; duplicate source-of-truth risk checked |
13
- | Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
14
- | Public behavior change | README, public docs, changelog | docs mention current behavior |
15
- | API or SDK behavior change | API docs, examples, tests | tests or documented reason |
16
- | Runbook change | runbook path in `PROJECT_INDEX.md` | procedure still executable |
17
- | Governance rule change | relevant pack/core, registry, README if public-facing | complexity budget checked |
18
- | Closeout/startup contract change | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, README quick usage | opening message schema + workspace identity present |
19
- | Workspace identity change | `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md` | root/branch/commit/status recorded or marked unverified |
20
- | Release | release notes, README version, changelog | release pack checklist |
21
-
22
- ## Registry Rule
23
-
24
- If a change has no matching row, add a row before closeout or record why no durable sync rule is needed. At closeout, record sync status for every row touched by the session.
1
+ # Doc Sync Registry
2
+
3
+ Purpose: map change types to documents and checks. Keep this as rows, not long prose.
4
+
5
+ ## Status Vocabulary
6
+
7
+ Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
8
+
9
+ | Change type | Also check/update | Verification |
10
+ |---|---|---|
11
+ | New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
12
+ | Generated Markdown or durable artifact | `dev/PROJECT_INDEX.md` Directory Map / Fact Base / Entry Points, and this registry when future updates need sync | artifact classified as indexed / synced / temporary / one-time evidence; duplicate source-of-truth risk checked |
13
+ | Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
14
+ | Public behavior change | README, public docs, changelog | docs mention current behavior |
15
+ | API or SDK behavior change | API docs, examples, tests | tests or documented reason |
16
+ | Runbook change | runbook path in `PROJECT_INDEX.md` | procedure still executable |
17
+ | Governance rule change | relevant pack/core, registry, README if public-facing | complexity budget checked |
18
+ | Closeout/startup contract change | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, README quick usage | opening message schema + workspace identity present |
19
+ | Workspace identity change | `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md` | root/branch/commit/status recorded or marked unverified |
20
+ | Release | release notes, README version, changelog | release pack checklist |
21
+
22
+ ## Registry Rule
23
+
24
+ If a change has no matching row, add a row before closeout or record why no durable sync rule is needed. At closeout, record sync status for every row touched by the session.
@@ -1,17 +1,17 @@
1
- # Antigravity / Gemini Entry Bridge
2
-
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
-
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.
10
-
11
- At session startup:
12
-
13
- 1. Confirm the current root is the intended project root.
14
- 2. Read `AGENTS.md`.
15
- 3. Follow the startup read order in `AGENTS.md`.
16
-
17
- If the current root does not match the intended project root, stop and ask the user to confirm the workspace before reading or editing project state.
1
+ # Antigravity / Gemini Entry Bridge
2
+
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
+
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.
10
+
11
+ At session startup:
12
+
13
+ 1. Confirm the current root is the intended project root.
14
+ 2. Read `AGENTS.md`.
15
+ 3. Follow the startup read order in `AGENTS.md`.
16
+
17
+ If the current root does not match the intended project root, stop and ask the user to confirm the workspace before reading or editing project state.
@@ -1,43 +1,43 @@
1
- # Project Decisions Log
2
-
3
- This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
-
5
- Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
-
7
- The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
-
9
- Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
-
11
- ```text
12
- - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
- ```
14
-
15
- The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
-
17
- This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
-
19
- ---
20
-
21
- ## Evolution Timeline
22
-
23
- Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
-
25
- (empty)
26
-
27
- ## Decisions Archive
28
-
29
- Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
30
-
31
- (empty)
32
-
33
- ## Architecture Choices
34
-
35
- Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
-
37
- (empty)
38
-
39
- ## Insights & Learnings
40
-
41
- Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
-
43
- (empty)
1
+ # Project Decisions Log
2
+
3
+ This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
+
5
+ Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
+
7
+ The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
+
9
+ Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
+
11
+ ```text
12
+ - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
+ ```
14
+
15
+ The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
+
17
+ This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
+
19
+ ---
20
+
21
+ ## Evolution Timeline
22
+
23
+ Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
+
25
+ (empty)
26
+
27
+ ## Decisions Archive
28
+
29
+ Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
30
+
31
+ (empty)
32
+
33
+ ## Architecture Choices
34
+
35
+ Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
+
37
+ (empty)
38
+
39
+ ## Insights & Learnings
40
+
41
+ Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
+
43
+ (empty)
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.3.44 | current template version |
9
+ | Agent Handoff Kit template version | 0.3.46 | current template version |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |
@@ -1,35 +1,35 @@
1
- # Session Log
2
-
3
- <!-- ack:section:session-log-preamble -->
4
-
5
- > **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
6
-
7
- Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
-
9
- This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
-
11
- Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
12
-
13
- Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
-
15
- <!-- ack:section:session-log-entry-template -->
16
-
17
- ## Entry Template
18
-
19
- ````markdown
20
- <!-- ack:log-entry:start -->
21
- ## <YYYY-MM-DD> — <short session title>
22
-
23
- - **ID:** <agent_or_session_id>
24
- - **Summary:** <one sentence>
25
- - **Changed:** <files changed, or none>
26
- - **Done:** <work completed this session>
27
- - **QC:** <checks run and results, or why not run>
28
- - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
29
- - **Sync:** <doc/external sync status>
30
- - **Pending:** <next work>
31
- - **Risks:** <known risks or none>
32
- - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
- - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
34
- <!-- ack:log-entry:end -->
35
- ````
1
+ # Session Log
2
+
3
+ <!-- ack:section:session-log-preamble -->
4
+
5
+ > **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
6
+
7
+ Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
+
9
+ This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
+
11
+ Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
12
+
13
+ Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
+
15
+ <!-- ack:section:session-log-entry-template -->
16
+
17
+ ## Entry Template
18
+
19
+ ````markdown
20
+ <!-- ack:log-entry:start -->
21
+ ## <YYYY-MM-DD> — <short session title>
22
+
23
+ - **ID:** <agent_or_session_id>
24
+ - **Summary:** <one sentence>
25
+ - **Changed:** <files changed, or none>
26
+ - **Done:** <work completed this session>
27
+ - **QC:** <checks run and results, or why not run>
28
+ - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
29
+ - **Sync:** <doc/external sync status>
30
+ - **Pending:** <next work>
31
+ - **Risks:** <known risks or none>
32
+ - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
+ - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
34
+ <!-- ack:log-entry:end -->
35
+ ````