@adamchanadam/agent-handoff-kit 0.3.31 → 0.3.32
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 +2 -2
- package/bin/agent-handoff-kit.mjs +144 -26
- package/package.json +1 -1
- package/packs/agent-governance.md +17 -0
- package/packs/writing.md +4 -0
- package/runtime-core/AGENTS.core.md +13 -8
- package/runtime-core/DOC_SYNC_REGISTRY.md +1 -0
- package/runtime-core/PROJECT_INDEX.md +8 -6
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.32`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
6
|
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
|
|
@@ -198,7 +198,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
198
198
|
|
|
199
199
|
## ⚠️ 目前限制
|
|
200
200
|
|
|
201
|
-
- 目前版本為 `v0.3.
|
|
201
|
+
- 目前版本為 `v0.3.32`;正式安裝請以 npm registry `latest` 顯示為準。
|
|
202
202
|
- 這是早期可用版本,仍在持續完善中。
|
|
203
203
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
204
204
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -57,10 +57,11 @@ const requiredAnchors = [
|
|
|
57
57
|
"Start Agent Handoff",
|
|
58
58
|
"Ambiguous startup phrases",
|
|
59
59
|
"Reachable is not the same as ingested",
|
|
60
|
-
"Do not treat unread sources as absent",
|
|
61
|
-
"Task contract changes are durable facts",
|
|
62
|
-
"External Impact Note",
|
|
63
|
-
|
|
60
|
+
"Do not treat unread sources as absent",
|
|
61
|
+
"Task contract changes are durable facts",
|
|
62
|
+
"External Impact Note",
|
|
63
|
+
"ARTIFACT GOVERNANCE GATE",
|
|
64
|
+
// R-030 v0.3.0+: forces managed-core merge on v0.2.x → v0.3.0 upgrade to propagate
|
|
64
65
|
// startup availability probe + integrations pack reference + credential separation discipline.
|
|
65
66
|
"startup availability probe",
|
|
66
67
|
"dev/rules/integrations.md",
|
|
@@ -87,9 +88,10 @@ const requiredAnchors = [
|
|
|
87
88
|
"Use the same display version rule as startup",
|
|
88
89
|
"Never print the literal placeholder `v<version>`",
|
|
89
90
|
"next-session startup entry",
|
|
90
|
-
"State Reconciliation Check",
|
|
91
|
-
"handoff lifecycle consistency",
|
|
92
|
-
"
|
|
91
|
+
"State Reconciliation Check",
|
|
92
|
+
"handoff lifecycle consistency",
|
|
93
|
+
"A final chat summary without updated handoff/log/prompt evidence is not closeout",
|
|
94
|
+
"Do not append a new state snapshot",
|
|
93
95
|
"START_NEXT_SESSION_PROMPT.txt"
|
|
94
96
|
]
|
|
95
97
|
},
|
|
@@ -797,10 +799,10 @@ async function runDoctor(root, version, options = {}) {
|
|
|
797
799
|
const temperatureResult = await checkHandoffTemperatureBoundary(root);
|
|
798
800
|
console.log(`\nhandoff temperature boundary checks: ${temperatureResult.checked}`);
|
|
799
801
|
console.log(`${temperatureResult.ok ? "ok" : "missing"} dev/SESSION_HANDOFF.md / START_NEXT_SESSION_PROMPT.txt (current-state evidence boundary)`);
|
|
800
|
-
if (!temperatureResult.ok) {
|
|
801
|
-
for (const finding of temperatureResult.findings) {
|
|
802
|
-
console.log(` missing: ${finding}`);
|
|
803
|
-
}
|
|
802
|
+
if (!temperatureResult.ok) {
|
|
803
|
+
for (const finding of temperatureResult.findings) {
|
|
804
|
+
console.log(` missing: ${finding}`);
|
|
805
|
+
}
|
|
804
806
|
printDoctorSummary(version, root, "needs-fix", {
|
|
805
807
|
checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked,
|
|
806
808
|
failedKind: "handoff temperature boundary checks",
|
|
@@ -808,12 +810,29 @@ async function runDoctor(root, version, options = {}) {
|
|
|
808
810
|
nextStep: "把一次性驗收證據、舊版本狀態、source token 或 Evidence chain 從 Durable Anchors / Next Priorities / opening message 移回 SESSION_LOG、PROJECT_INDEX 或 PROJECT_DECISIONS。"
|
|
809
811
|
});
|
|
810
812
|
process.exitCode = 1;
|
|
811
|
-
return "failed";
|
|
812
|
-
}
|
|
813
|
-
|
|
814
|
-
const
|
|
815
|
-
|
|
816
|
-
|
|
813
|
+
return "failed";
|
|
814
|
+
}
|
|
815
|
+
|
|
816
|
+
const artifactResult = await checkGeneratedMarkdownGovernance(root);
|
|
817
|
+
console.log(`\ngenerated markdown governance checks: ${artifactResult.checked}`);
|
|
818
|
+
console.log(`${artifactResult.ok ? "ok" : "missing"} dev/PROJECT_INDEX.md (generated Markdown / durable artifact registration)`);
|
|
819
|
+
if (!artifactResult.ok) {
|
|
820
|
+
for (const finding of artifactResult.findings) {
|
|
821
|
+
console.log(` missing: ${finding}`);
|
|
822
|
+
}
|
|
823
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
824
|
+
checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked + artifactResult.checked,
|
|
825
|
+
failedKind: "generated markdown governance checks",
|
|
826
|
+
failedCount: artifactResult.findings.length,
|
|
827
|
+
nextStep: "把新生成或新修改的 Markdown / durable artifact 登記到 dev/PROJECT_INDEX.md,或在 SESSION_LOG / task summary 明確標成 draft、temporary 或 one-time evidence;如內容重複,先合併到單一真源。"
|
|
828
|
+
});
|
|
829
|
+
process.exitCode = 1;
|
|
830
|
+
return "failed";
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
const mirrorRows = await checkPromptMirror(root);
|
|
834
|
+
const mirrorBlockingFailures = mirrorRows.filter((row) => !row.ok && row.reason !== "convenience copy differs from dev/SESSION_HANDOFF.md");
|
|
835
|
+
const mirrorWarnings = mirrorRows.filter((row) => !row.ok && row.reason === "convenience copy differs from dev/SESSION_HANDOFF.md");
|
|
817
836
|
console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
|
|
818
837
|
for (const row of mirrorRows) {
|
|
819
838
|
const status = row.ok ? "ok" : row.reason === "convenience copy differs from dev/SESSION_HANDOFF.md" ? "warn" : "missing";
|
|
@@ -869,7 +888,7 @@ async function runDoctor(root, version, options = {}) {
|
|
|
869
888
|
|
|
870
889
|
const overallHealthy = credentialResult.ok;
|
|
871
890
|
printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
|
|
872
|
-
|
|
891
|
+
checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked + artifactResult.checked + mirrorRows.length + 2,
|
|
873
892
|
failedKind: !credentialResult.ok ? "credential leak" : null,
|
|
874
893
|
failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
|
|
875
894
|
warningKind: mirrorWarnings.length > 0 ? "prompt mirror warning" : null,
|
|
@@ -883,7 +902,7 @@ async function runDoctor(root, version, options = {}) {
|
|
|
883
902
|
return overallHealthy ? "passed" : "failed";
|
|
884
903
|
}
|
|
885
904
|
|
|
886
|
-
async function checkResearchDecisionTrace(root) {
|
|
905
|
+
async function checkResearchDecisionTrace(root) {
|
|
887
906
|
const decisionsPath = path.join(root, "dev/PROJECT_DECISIONS.md");
|
|
888
907
|
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
889
908
|
let decisionsText = "";
|
|
@@ -916,12 +935,111 @@ async function checkResearchDecisionTrace(root) {
|
|
|
916
935
|
}
|
|
917
936
|
});
|
|
918
937
|
|
|
919
|
-
return { ok: findings.length === 0, checked: 1, findings };
|
|
920
|
-
}
|
|
921
|
-
|
|
922
|
-
function
|
|
923
|
-
|
|
924
|
-
|
|
938
|
+
return { ok: findings.length === 0, checked: 1, findings };
|
|
939
|
+
}
|
|
940
|
+
|
|
941
|
+
async function checkGeneratedMarkdownGovernance(root) {
|
|
942
|
+
let indexText = "";
|
|
943
|
+
let logText = "";
|
|
944
|
+
let handoffText = "";
|
|
945
|
+
try {
|
|
946
|
+
indexText = await readFile(path.join(root, "dev/PROJECT_INDEX.md"), "utf8");
|
|
947
|
+
} catch {
|
|
948
|
+
return { ok: false, checked: 1, findings: ["dev/PROJECT_INDEX.md unreadable; cannot verify generated Markdown governance"] };
|
|
949
|
+
}
|
|
950
|
+
try {
|
|
951
|
+
logText = await readFile(path.join(root, "dev/SESSION_LOG.md"), "utf8");
|
|
952
|
+
} catch {
|
|
953
|
+
logText = "";
|
|
954
|
+
}
|
|
955
|
+
try {
|
|
956
|
+
handoffText = await readFile(path.join(root, "dev/SESSION_HANDOFF.md"), "utf8");
|
|
957
|
+
} catch {
|
|
958
|
+
handoffText = "";
|
|
959
|
+
}
|
|
960
|
+
|
|
961
|
+
const markdownFiles = await listMarkdownFiles(root);
|
|
962
|
+
const findings = [];
|
|
963
|
+
for (const rel of markdownFiles) {
|
|
964
|
+
if (!isGeneratedArtifactCandidate(rel)) continue;
|
|
965
|
+
if (isArtifactGoverned(rel, { indexText, logText, handoffText })) continue;
|
|
966
|
+
findings.push(`${rel} is not registered in dev/PROJECT_INDEX.md and is not explicitly classified as draft / temporary / one-time evidence`);
|
|
967
|
+
}
|
|
968
|
+
|
|
969
|
+
return { ok: findings.length === 0, checked: 1, findings };
|
|
970
|
+
}
|
|
971
|
+
|
|
972
|
+
async function listMarkdownFiles(root) {
|
|
973
|
+
const results = [];
|
|
974
|
+
async function walk(dir) {
|
|
975
|
+
let entries = [];
|
|
976
|
+
try {
|
|
977
|
+
entries = await readdir(dir, { withFileTypes: true });
|
|
978
|
+
} catch {
|
|
979
|
+
return;
|
|
980
|
+
}
|
|
981
|
+
for (const entry of entries) {
|
|
982
|
+
if (entry.name === ".git" || entry.name === "node_modules") continue;
|
|
983
|
+
const full = path.join(dir, entry.name);
|
|
984
|
+
if (entry.isDirectory()) {
|
|
985
|
+
await walk(full);
|
|
986
|
+
continue;
|
|
987
|
+
}
|
|
988
|
+
if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
|
|
989
|
+
results.push(path.relative(root, full).split(path.sep).join("/"));
|
|
990
|
+
}
|
|
991
|
+
}
|
|
992
|
+
await walk(root);
|
|
993
|
+
return results.sort();
|
|
994
|
+
}
|
|
995
|
+
|
|
996
|
+
function isGeneratedArtifactCandidate(rel) {
|
|
997
|
+
const normalized = rel.replaceAll("\\", "/");
|
|
998
|
+
const lower = normalized.toLowerCase();
|
|
999
|
+
const kitManaged = new Set([
|
|
1000
|
+
"agents.md",
|
|
1001
|
+
"claude.md",
|
|
1002
|
+
"gemini.md",
|
|
1003
|
+
"readme.md",
|
|
1004
|
+
"dev/session_handoff.md",
|
|
1005
|
+
"dev/session_log.md",
|
|
1006
|
+
"dev/project_index.md",
|
|
1007
|
+
"dev/doc_sync_registry.md",
|
|
1008
|
+
"dev/rule_packs.md",
|
|
1009
|
+
"dev/project_decisions.md"
|
|
1010
|
+
]);
|
|
1011
|
+
if (kitManaged.has(lower)) return false;
|
|
1012
|
+
if (lower.startsWith("dev/rules/")) return false;
|
|
1013
|
+
if (lower.startsWith("dev/governance_migrations/")) return false;
|
|
1014
|
+
if (lower.startsWith("dev/session_log_archive/")) return false;
|
|
1015
|
+
if (lower.startsWith("docs/")) return true;
|
|
1016
|
+
if (lower.startsWith("outputs/")) return true;
|
|
1017
|
+
if (lower.startsWith("output/")) return true;
|
|
1018
|
+
if (lower.startsWith("research/")) return true;
|
|
1019
|
+
if (lower.startsWith("references/")) return true;
|
|
1020
|
+
if (lower.startsWith("reference/")) return true;
|
|
1021
|
+
if (lower.startsWith("runbooks/")) return true;
|
|
1022
|
+
if (lower.startsWith("specs/")) return true;
|
|
1023
|
+
if (lower.startsWith("requirements/")) return true;
|
|
1024
|
+
return !normalized.includes("/");
|
|
1025
|
+
}
|
|
1026
|
+
|
|
1027
|
+
function isArtifactGoverned(rel, { indexText, logText, handoffText }) {
|
|
1028
|
+
const normalized = rel.replaceAll("\\", "/");
|
|
1029
|
+
if (indexText.includes(normalized)) return true;
|
|
1030
|
+
const escaped = normalized.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
1031
|
+
const labels = "(draft|temporary|one-time evidence|non-authoritative|not source of truth|草稿|臨時|暫存|一次性|非真源|非權威)";
|
|
1032
|
+
const afterPath = new RegExp(`${escaped}[\\s\\S]{0,240}${labels}`, "i");
|
|
1033
|
+
const beforePath = new RegExp(`${labels}[\\s\\S]{0,240}${escaped}`, "i");
|
|
1034
|
+
return afterPath.test(logText)
|
|
1035
|
+
|| beforePath.test(logText)
|
|
1036
|
+
|| afterPath.test(handoffText)
|
|
1037
|
+
|| beforePath.test(handoffText);
|
|
1038
|
+
}
|
|
1039
|
+
|
|
1040
|
+
function stripFencedCodeBlocks(text) {
|
|
1041
|
+
return text.replace(/```[\s\S]*?```/g, "");
|
|
1042
|
+
}
|
|
925
1043
|
|
|
926
1044
|
function markdownListBlocks(text) {
|
|
927
1045
|
const blocks = [];
|
|
@@ -1182,7 +1300,7 @@ function printDoctorSummary(version, root, mode, details) {
|
|
|
1182
1300
|
}
|
|
1183
1301
|
} else {
|
|
1184
1302
|
console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
|
|
1185
|
-
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : details.failedKind === "research decision trace checks" ? "研究導向決策缺少可追溯來源鏈。" : details.failedKind === "handoff temperature boundary checks" ? "當前交接內容混入一次性或歷史證據。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
1303
|
+
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : details.failedKind === "research decision trace checks" ? "研究導向決策缺少可追溯來源鏈。" : details.failedKind === "handoff temperature boundary checks" ? "當前交接內容混入一次性或歷史證據。" : details.failedKind === "generated markdown governance checks" ? "有 Markdown 或 durable artifact 未完成入庫、同步或臨時分類。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
1186
1304
|
}
|
|
1187
1305
|
console.log("");
|
|
1188
1306
|
console.log(`📦 版本:v${version}`);
|
package/package.json
CHANGED
|
@@ -10,6 +10,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
10
10
|
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
11
|
- User asks to "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", "掃描未接入 Agent Handoff Kit 的重要文件", "bridge governance", "connect this document to governance", or scan for unbridged governance documents.
|
|
12
12
|
- User asks to make something long-term, cross-session, reusable, "寫入長期治理", "轉成長期機制", "之後都要遵守", or says future sessions should remember an API / MCP / tool-use pattern.
|
|
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.
|
|
13
14
|
|
|
14
15
|
## Rules
|
|
15
16
|
|
|
@@ -24,6 +25,8 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
24
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.
|
|
25
26
|
10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not say "轉成長期機制" or "寫入長期治理", 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.
|
|
26
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.
|
|
27
30
|
|
|
28
31
|
## Governance Bridge Workflow
|
|
29
32
|
|
|
@@ -40,6 +43,18 @@ Use this workflow when the user asks for governance bridge / 治理打通 / 把
|
|
|
40
43
|
|
|
41
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.
|
|
42
45
|
|
|
46
|
+
## Generated Artifact Governance Workflow
|
|
47
|
+
|
|
48
|
+
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.
|
|
49
|
+
|
|
50
|
+
1. List the artifacts created or materially changed in this task.
|
|
51
|
+
2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
|
|
52
|
+
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.
|
|
53
|
+
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.
|
|
54
|
+
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.
|
|
55
|
+
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.
|
|
56
|
+
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.
|
|
57
|
+
|
|
43
58
|
## Long-term Governance Routing
|
|
44
59
|
|
|
45
60
|
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.
|
|
@@ -73,6 +88,8 @@ Output format:
|
|
|
73
88
|
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
74
89
|
- Confirm old overlapping wording was retired or marked legacy.
|
|
75
90
|
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
91
|
+
- Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
|
|
92
|
+
- Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
|
|
76
93
|
- 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.
|
|
77
94
|
- 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.
|
|
78
95
|
- 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.
|
package/packs/writing.md
CHANGED
|
@@ -18,12 +18,16 @@ Use for drafting, editing, style, structure, publication copy, documentation pro
|
|
|
18
18
|
5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
|
|
19
19
|
6. For public Traditional Chinese docs or HTML aimed at non-technical readers, use steady written Chinese. Keep English only for commands, paths, URLs, file names, product names, and unavoidable tool names. Avoid mixed half-English fragments, internal governance codes, and developer-only wording in reader-facing prose.
|
|
20
20
|
7. For public README, onboarding, and other user-facing docs, use the product-journey rule: the user states the goal, the AI handles technical work. Keep one primary user path. Do not make users choose between install, upgrade, doctor, dry-run, or terminal commands when an AI-assisted path exists. Put technical commands in the dedicated AI install page, CLI help, or advanced examples instead of duplicating them in the main README flow.
|
|
21
|
+
8. When writing or revising Markdown files, decide whether the output is a durable source, a reference, a runbook, a public document, a reusable generated artifact, a draft, or one-time evidence. Durable outputs must be indexed or tied to a registered source/sync home before completion; drafts and one-time evidence must be labeled so they do not become hidden current state.
|
|
22
|
+
9. If a new document repeats requirements, instructions, acceptance rules, or process already owned by another file, consolidate into the existing source or make the new file explicitly subordinate. Do not let writing work create parallel truth.
|
|
21
23
|
|
|
22
24
|
## Checks
|
|
23
25
|
|
|
24
26
|
- Verify requested format, language, and tone.
|
|
25
27
|
- Check links, commands, names, and version-sensitive claims when relevant.
|
|
26
28
|
- Check `dev/DOC_SYNC_REGISTRY.md` if public docs or user-facing instructions changed.
|
|
29
|
+
- For any Markdown file created or materially changed, check whether `dev/PROJECT_INDEX.md` needs a Directory Map, Fact Base, Entry Points, or read-condition update.
|
|
30
|
+
- Check duplicate-source risk before keeping a new requirement, checklist, process, or instruction document.
|
|
27
31
|
- For public Chinese docs, read the final text as a new user journey: the next action should be clear without technical background.
|
|
28
32
|
- For README-style docs, confirm the main path does not become parallel instructions: no repeated manual install section, no competing command table, and no requirement that the reader understand internal files before taking the first action.
|
|
29
33
|
|
|
@@ -23,7 +23,9 @@ Ambiguous startup phrases need one concise confirmation question before treating
|
|
|
23
23
|
|
|
24
24
|
If a required file is missing, create the smallest useful version only after confirming the target project root.
|
|
25
25
|
|
|
26
|
-
Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent. If tool output is truncated, paginated, or only a search hit, continue reading the relevant source or mark coverage as partial; do not present a complete conclusion from partial output.
|
|
26
|
+
Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent. If tool output is truncated, paginated, or only a search hit, continue reading the relevant source or mark coverage as partial; do not present a complete conclusion from partial output.
|
|
27
|
+
|
|
28
|
+
When creating or materially changing Markdown files, generated documents, research outputs, specifications, runbooks, checklists, guides, or other durable artifacts, do not leave them as orphan files. Before claiming the task is complete, classify each new or materially changed artifact as one of: draft / one-time evidence, source of truth, reference, runbook, workflow, public document, generated output, or intentionally temporary. Then either register it in `dev/PROJECT_INDEX.md` with a role and read condition, register a sync obligation in `dev/DOC_SYNC_REGISTRY.md`, point to an existing authoritative home and mark the file as non-authoritative, or explicitly record why it is temporary / one-time evidence. If several files carry the same durable rule or requirement, consolidate or point to the single authoritative home instead of creating parallel truth.
|
|
27
29
|
|
|
28
30
|
After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empty, run startup availability probe (R-030 Integration governance discipline; see `dev/rules/integrations.md`):
|
|
29
31
|
|
|
@@ -56,8 +58,9 @@ Use this loop for every task:
|
|
|
56
58
|
1. PLAN: restate the user's intent, scope, risk, and acceptance criteria.
|
|
57
59
|
2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
|
|
58
60
|
3. CHANGE: make focused changes only.
|
|
59
|
-
4. QC: run available checks or state why they cannot run.
|
|
60
|
-
5. PERSISTENCE GATE: decide whether this task produced a durable fact before writing governance files. A durable fact is information the next agent cannot reliably reconstruct and that affects future action.
|
|
61
|
+
4. QC: run available checks or state why they cannot run.
|
|
62
|
+
5. PERSISTENCE GATE: decide whether this task produced a durable fact before writing governance files. A durable fact is information the next agent cannot reliably reconstruct and that affects future action.
|
|
63
|
+
6. ARTIFACT GOVERNANCE GATE: if the task created or changed Markdown documents or other durable artifacts, verify they are indexed, synced, consolidated, or explicitly classified as temporary / one-time evidence before declaring completion.
|
|
61
64
|
|
|
62
65
|
External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence-gate check for the active project root, and completion cannot be claimed until that check is answered at the correct tier.
|
|
63
66
|
|
|
@@ -108,11 +111,13 @@ Do not claim completion without evidence from checks, inspection, or a clear exp
|
|
|
108
111
|
|
|
109
112
|
## 4. Closeout And Handoff
|
|
110
113
|
|
|
111
|
-
Detect end-of-session or handoff intent in natural language, such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
|
|
112
|
-
|
|
113
|
-
Ambiguous closeout phrases need one concise confirmation question before full closeout. In particular, if the user says "<something> 收工", "<something> close", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to wrap up Agent Handoff Kit and write the project handoff.
|
|
114
|
-
|
|
115
|
-
|
|
114
|
+
Detect end-of-session or handoff intent in natural language, such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
|
|
115
|
+
|
|
116
|
+
Ambiguous closeout phrases need one concise confirmation question before full closeout. In particular, if the user says "<something> 收工", "<something> close", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to wrap up Agent Handoff Kit and write the project handoff.
|
|
117
|
+
|
|
118
|
+
If the user sends only a clear closeout phrase such as "收工", "wrap up", "handoff", or "Wrap up Agent Handoff", do not answer with a summary-only message. Enter full closeout immediately: announce that Agent Handoff Kit closeout is starting, read the current handoff/log/index, reconcile state, write the required files, run the available checks, and only then show the closeout card. A final chat summary without updated handoff/log/prompt evidence is not closeout.
|
|
119
|
+
|
|
120
|
+
At full closeout:
|
|
116
121
|
|
|
117
122
|
Closeout Write Contract: before writing `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or `START_NEXT_SESSION_PROMPT.txt`, classify each fact by role and write it to the matching structured area. Use one Agent Handoff Kit marker standard as the machine boundary: `ack:section:*` for sections, `ack:field:*` for fields, `ack:log-entry:start/end` for log entries, and managed-core BEGIN/END for the installed AGENTS core. Do not remove or translate these markers. New closeout writes must use this marker standard; natural-language headings are only human labels, and legacy heading fallback is only for migration / repair of older installs. Current state and next action go only in `dev/SESSION_HANDOFF.md`. Trace evidence, one-time tasks, old build / release / hash facts, and completed delivery details go only in `dev/SESSION_LOG.md` unless promoted to `dev/PROJECT_INDEX.md`, `dev/PROJECT_DECISIONS.md`, `dev/DOC_SYNC_REGISTRY.md`, or a rule pack. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the handoff opening-message block; do not hand-write separate startup state there.
|
|
118
123
|
|
|
@@ -9,6 +9,7 @@ Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
|
|
|
9
9
|
| Change type | Also check/update | Verification |
|
|
10
10
|
|---|---|---|
|
|
11
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 |
|
|
12
13
|
| Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
|
|
13
14
|
| Public behavior change | README, public docs, changelog | docs mention current behavior |
|
|
14
15
|
| API or SDK behavior change | API docs, examples, tests | tests or documented reason |
|
|
@@ -35,9 +35,10 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
35
35
|
|---|---|---|
|
|
36
36
|
| App entry | TBD | TBD |
|
|
37
37
|
| Main config | TBD | TBD |
|
|
38
|
-
| Test suite | TBD | TBD |
|
|
39
|
-
| Runbook | TBD | TBD |
|
|
40
|
-
| Public docs | TBD | TBD |
|
|
38
|
+
| Test suite | TBD | TBD |
|
|
39
|
+
| Runbook | TBD | TBD |
|
|
40
|
+
| Public docs | TBD | TBD |
|
|
41
|
+
| Generated artifact review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated outputs, specs, runbooks, checklists, or research artifacts, classify each artifact as indexed / synced / temporary / one-time evidence before completion |
|
|
41
42
|
|
|
42
43
|
## Fact Base
|
|
43
44
|
|
|
@@ -100,8 +101,8 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
100
101
|
|
|
101
102
|
| Check | Command | Run before | Last verified |
|
|
102
103
|
|---|---|---|---|
|
|
103
|
-
| Agent Handoff Kit doctor |
|
|
104
|
-
| Project governance check |
|
|
104
|
+
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
|
|
105
|
+
| Project governance check | Check newly created Markdown / durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence | closeout / durable file changes | unverified until project-specific command exists |
|
|
105
106
|
|
|
106
107
|
## Workspace Identity
|
|
107
108
|
|
|
@@ -122,7 +123,8 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
122
123
|
| API behavior | TBD | tests + docs sync |
|
|
123
124
|
| UI behavior | TBD | build + visual/manual check |
|
|
124
125
|
| Data model | TBD | migration/checks |
|
|
125
|
-
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
126
|
+
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
127
|
+
| Generated Markdown or durable artifact | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable |
|
|
126
128
|
| Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current + prompt file regenerated from handoff at closeout |
|
|
127
129
|
|
|
128
130
|
## External Services
|