@adamchanadam/agent-handoff-kit 0.4.0 → 0.4.2

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.
@@ -1,98 +1,100 @@
1
- import { createHash } from "node:crypto";
1
+ import { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
2
+ export { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
3
+ import { createHash } from "node:crypto";
2
4
  import { lstat, readdir, readFile, realpath } from "node:fs/promises";
3
5
  import path from "node:path";
4
6
  import { installedFileContracts } from "./installed-file-contract.mjs";
5
7
  import { FORMAL_USER_RULES_ENTRY_ANCHOR, readFormalUserRules } from "./user-rules-router.mjs";
6
-
8
+
7
9
  export const UPGRADE_INVENTORY_SCHEMA = 1;
8
-
9
- const formalEntryTargets = Object.freeze([
10
- "AGENTS.md",
11
- "CLAUDE.md",
12
- "GEMINI.md",
13
- "START_NEXT_SESSION_PROMPT.txt"
14
- ]);
15
-
10
+
11
+ const formalEntryTargets = Object.freeze([
12
+ "AGENTS.md",
13
+ "CLAUDE.md",
14
+ "GEMINI.md",
15
+ "START_NEXT_SESSION_PROMPT.txt"
16
+ ]);
17
+
16
18
  const archiveDirectories = Object.freeze([
17
19
  { relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
18
20
  { relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
19
21
  ]);
20
-
22
+
21
23
  /**
22
24
  * Builds a read-only, hash-bound description of the Kit data that an upgrade
23
25
  * can reach now. Ordinary workspace files, generic Markdown references, and
24
26
  * committed historical transaction receipts are not current upgrade authority.
25
27
  */
26
- export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
27
- if (!root) throw new Error("upgrade inventory requires a project root");
28
- const rootPath = path.resolve(root);
29
- const rootStats = await lstat(rootPath).catch((error) => {
30
- if (error?.code === "ENOENT") return null;
31
- throw error;
32
- });
33
- if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
34
- throw new Error("upgrade inventory root must be a real directory");
35
- }
36
- const realRoot = await realpath(rootPath);
28
+ export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
29
+ if (!root) throw new Error("upgrade inventory requires a project root");
30
+ const rootPath = path.resolve(root);
31
+ const rootStats = await lstat(rootPath).catch((error) => {
32
+ if (error?.code === "ENOENT") return null;
33
+ throw error;
34
+ });
35
+ if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
36
+ throw new Error("upgrade inventory root must be a real directory");
37
+ }
38
+ const realRoot = await realpath(rootPath);
37
39
  const entries = new Map();
38
40
  const blockers = [];
39
-
40
- const addBlocker = (relative, reason) => {
41
- const key = `${relative}\0${reason}`;
42
- if (!blockers.some((item) => `${item.path}\0${item.reason}` === key)) blockers.push({ path: relative, reason });
43
- };
44
-
41
+
42
+ const addBlocker = (relative, reason) => {
43
+ const key = `${relative}\0${reason}`;
44
+ if (!blockers.some((item) => `${item.path}\0${item.reason}` === key)) blockers.push({ path: relative, reason });
45
+ };
46
+
45
47
  async function addFile(relative, classification, reachability = null) {
46
- const normalized = normalizeProjectRelative(relative);
47
- if (!normalized) {
48
- addBlocker(String(relative), "reference escapes the selected project root");
49
- return null;
50
- }
51
- const absolute = path.resolve(rootPath, normalized);
52
- if (!isInside(rootPath, absolute)) {
53
- addBlocker(normalized, "reference escapes the selected project root");
54
- return null;
55
- }
56
- const stats = await lstat(absolute).catch((error) => {
57
- if (error?.code === "ENOENT") return null;
58
- throw error;
59
- });
60
- if (!stats) return null;
61
- if (stats.isSymbolicLink()) {
62
- addBlocker(normalized, "symbolic links and junctions are not accepted as inventory sources");
63
- return null;
64
- }
65
- if (!stats.isFile()) {
66
- addBlocker(normalized, "inventory source is not a regular file");
67
- return null;
68
- }
69
- const resolved = await realpath(absolute);
70
- if (!isInside(realRoot, resolved)) {
71
- addBlocker(normalized, "resolved inventory source is outside the selected project root");
72
- return null;
73
- }
74
-
75
- const buffer = await readFile(absolute);
76
- let entry = entries.get(normalized);
77
- if (!entry) {
78
- entry = {
79
- path: normalized,
80
- sha256: sha256(buffer),
81
- bytes: buffer.length,
82
- classifications: new Set(),
83
- reachability: new Map(),
84
- text: decodeUtf8(buffer)
85
- };
86
- entries.set(normalized, entry);
87
- }
88
- entry.classifications.add(classification);
89
- if (reachability) entry.reachability.set(`${reachability.from}\0${reachability.via}`, reachability);
48
+ const normalized = normalizeProjectRelative(relative);
49
+ if (!normalized) {
50
+ addBlocker(String(relative), "reference escapes the selected project root");
51
+ return null;
52
+ }
53
+ const absolute = path.resolve(rootPath, normalized);
54
+ if (!isInside(rootPath, absolute)) {
55
+ addBlocker(normalized, "reference escapes the selected project root");
56
+ return null;
57
+ }
58
+ const stats = await lstat(absolute).catch((error) => {
59
+ if (error?.code === "ENOENT") return null;
60
+ throw error;
61
+ });
62
+ if (!stats) return null;
63
+ if (stats.isSymbolicLink()) {
64
+ addBlocker(normalized, "symbolic links and junctions are not accepted as inventory sources");
65
+ return null;
66
+ }
67
+ if (!stats.isFile()) {
68
+ addBlocker(normalized, "inventory source is not a regular file");
69
+ return null;
70
+ }
71
+ const resolved = await realpath(absolute);
72
+ if (!isInside(realRoot, resolved)) {
73
+ addBlocker(normalized, "resolved inventory source is outside the selected project root");
74
+ return null;
75
+ }
76
+
77
+ const buffer = await readFile(absolute);
78
+ let entry = entries.get(normalized);
79
+ if (!entry) {
80
+ entry = {
81
+ path: normalized,
82
+ sha256: sha256(buffer),
83
+ bytes: buffer.length,
84
+ classifications: new Set(),
85
+ reachability: new Map(),
86
+ text: decodeUtf8(buffer)
87
+ };
88
+ entries.set(normalized, entry);
89
+ }
90
+ entry.classifications.add(classification);
91
+ if (reachability) entry.reachability.set(`${reachability.from}\0${reachability.via}`, reachability);
90
92
  return entry;
91
93
  }
92
-
93
- for (const contract of contracts) {
94
- const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
95
- await addFile(
94
+
95
+ for (const contract of contracts) {
96
+ const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
97
+ await addFile(
96
98
  contract.targetRel,
97
99
  "managed-contract",
98
100
  isFormalEntry ? { from: "formal-entry", via: contract.targetRel } : { from: "managed-contract", via: contract.targetRel }
@@ -115,54 +117,54 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
115
117
  addBlocker("dev/USER_RULES.md", `formal user-rules state is unsafe: ${String(error?.message ?? error)}`);
116
118
  }
117
119
  }
118
-
119
- const frozenEntries = [...entries.values()]
120
- .map((entry) => ({
121
- path: entry.path,
122
- sha256: entry.sha256,
123
- bytes: entry.bytes,
124
- classifications: [...entry.classifications].sort(),
125
- reachability: [...entry.reachability.values()]
126
- .sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`))
127
- }))
128
- .sort((left, right) => left.path.localeCompare(right.path));
129
- const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
130
- const digestInput = {
131
- schemaVersion: UPGRADE_INVENTORY_SCHEMA,
132
- entries: frozenEntries,
133
- blockers: sortedBlockers
134
- };
135
-
136
- return Object.freeze({
137
- schemaVersion: UPGRADE_INVENTORY_SCHEMA,
138
- status: sortedBlockers.length === 0 ? "ready" : "blocked",
139
- entries: frozenEntries,
140
- blockers: sortedBlockers,
141
- inventorySha256: sha256(Buffer.from(`${JSON.stringify(digestInput)}\n`, "utf8")),
142
- formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
143
- });
144
-
120
+
121
+ const frozenEntries = [...entries.values()]
122
+ .map((entry) => ({
123
+ path: entry.path,
124
+ sha256: entry.sha256,
125
+ bytes: entry.bytes,
126
+ classifications: [...entry.classifications].sort(),
127
+ reachability: [...entry.reachability.values()]
128
+ .sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`))
129
+ }))
130
+ .sort((left, right) => left.path.localeCompare(right.path));
131
+ const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
132
+ const digestInput = {
133
+ schemaVersion: UPGRADE_INVENTORY_SCHEMA,
134
+ entries: frozenEntries,
135
+ blockers: sortedBlockers
136
+ };
137
+
138
+ return Object.freeze({
139
+ schemaVersion: UPGRADE_INVENTORY_SCHEMA,
140
+ status: sortedBlockers.length === 0 ? "ready" : "blocked",
141
+ entries: frozenEntries,
142
+ blockers: sortedBlockers,
143
+ inventorySha256: sha256(Buffer.from(`${JSON.stringify(digestInput)}\n`, "utf8")),
144
+ formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
145
+ });
146
+
145
147
  async function addTree(relativeDirectory, classification) {
146
- const normalized = normalizeProjectRelative(relativeDirectory);
147
- if (!normalized) {
148
+ const normalized = normalizeProjectRelative(relativeDirectory);
149
+ if (!normalized) {
148
150
  addBlocker(String(relativeDirectory), "dynamic directory escapes the selected project root");
149
151
  return;
150
152
  }
151
153
  const absolute = path.resolve(rootPath, normalized);
152
154
  const stats = await lstat(absolute).catch((error) => {
153
155
  if (error?.code === "ENOENT") return null;
154
- throw error;
155
- });
156
- if (!stats) return;
157
- if (!stats.isDirectory() || stats.isSymbolicLink()) {
158
- addBlocker(normalized, "dynamic inventory directory is not a safe real directory");
159
- return;
160
- }
161
- const resolved = await realpath(absolute);
162
- if (!isInside(realRoot, resolved)) {
163
- addBlocker(normalized, "dynamic inventory directory resolves outside the selected project root");
164
- return;
165
- }
156
+ throw error;
157
+ });
158
+ if (!stats) return;
159
+ if (!stats.isDirectory() || stats.isSymbolicLink()) {
160
+ addBlocker(normalized, "dynamic inventory directory is not a safe real directory");
161
+ return;
162
+ }
163
+ const resolved = await realpath(absolute);
164
+ if (!isInside(realRoot, resolved)) {
165
+ addBlocker(normalized, "dynamic inventory directory resolves outside the selected project root");
166
+ return;
167
+ }
166
168
  for (const item of await readdir(absolute, { withFileTypes: true })) {
167
169
  const child = `${normalized}/${item.name}`;
168
170
  const childAbsolute = path.join(absolute, item.name);
@@ -193,171 +195,49 @@ export async function readProjectIndexTemplateVersion(root) {
193
195
  return parseProjectIndexTemplateVersion(bytes.toString("utf8"));
194
196
  }
195
197
 
196
- export function parseProjectIndexTemplateVersion(text) {
197
- return projectIndexTemplateVersionEvidence(text)?.version ?? null;
198
+ export function extractExplicitLocalReferences(text) {
199
+ const matches = new Map();
200
+ const add = (raw, via) => {
201
+ const normalized = normalizeReference(raw);
202
+ if (normalized) matches.set(`${normalized}\0${via}`, { path: normalized, via });
203
+ };
204
+ for (const match of String(text).matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g)) add(match[1], "markdown-link");
205
+ for (const match of String(text).matchAll(/`([^`\r\n]+)`/g)) add(match[1], "inline-code-path");
206
+ for (const match of String(text).matchAll(/^\s*@([^\s]+)\s*$/gm)) add(match[1], "bridge-import");
207
+ // Do not treat the dot before a filename extension as sentence punctuation.
208
+ // On Windows, the truncated `dev/USER_RULES` then aliases the real
209
+ // `dev/user_rules/` directory, making a valid formal router look unsafe.
210
+ for (const match of String(text).matchAll(/(?:^|[\s("'`])((?:[\p{L}\p{N}_-]+[\\/])+[\p{L}\p{N}_. -]*[\p{L}\p{N}_.-])(?=$|[\s,;:,。!?)\]}>"'])/gu)) add(match[1], "plain-local-path");
211
+ return [...matches.values()].sort((left, right) => `${left.path}\0${left.via}`.localeCompare(`${right.path}\0${right.via}`));
198
212
  }
199
213
 
200
- export function projectIndexTemplateVersionRow(text) {
201
- return projectIndexTemplateVersionEvidence(text)?.row ?? null;
214
+ function normalizeReference(raw) {
215
+ const value = String(raw).trim().replace(/^<|>$/g, "");
216
+ if (!value || value.includes("://") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/")) return null;
217
+ const withoutFragment = value.split(/[?#]/, 1)[0].replaceAll("\\", "/");
218
+ if (!withoutFragment || withoutFragment.endsWith("/") || (!withoutFragment.includes("/") && !/\.[\p{L}\p{N}]+$/u.test(withoutFragment))) return null;
219
+ return normalizeProjectRelative(withoutFragment);
202
220
  }
203
221
 
204
- export function materializeProjectIndexTemplateVersion(text, version) {
205
- if (!isStableSemver(version)) return text;
206
- const evidence = projectIndexTemplateVersionEvidence(text);
207
- if (!evidence) return text;
208
- return String(text).slice(0, evidence.rowStart)
209
- + evidence.row.replace(`| ${evidence.version} |`, `| ${version} |`)
210
- + String(text).slice(evidence.rowEnd);
222
+ function normalizeProjectRelative(relative) {
223
+ const normalized = path.posix.normalize(String(relative).replaceAll("\\", "/").replace(/^\.\//, ""));
224
+ if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
225
+ return normalized;
211
226
  }
212
227
 
213
- function projectIndexTemplateVersionEvidence(text) {
214
- const value = String(text);
215
- const normalized = value.replace(/\r\n/g, "\n");
216
- const visibleLines = markdownVisibleLinesOutsideHiddenBlocks(value);
217
- const headings = [];
218
- for (const item of visibleLines) if (/^## [^\r\n]+$/u.test(item.text)) headings.push({ title: item.text.trim(), line: item.line, offset: item.normalizedStart });
219
- const stackHeadings = headings.filter((heading) => heading.title === "## Stack");
220
- if (stackHeadings.length !== 1) return null;
221
- const stack = stackHeadings[0];
222
- const nextHeading = headings.find((heading) => heading.line > stack.line);
223
- const stackStart = stack.offset + visibleLines.find((line) => line.line === stack.line)?.text.length + 1;
224
- const stackEnd = nextHeading ? nextHeading.offset : normalized.length;
225
- const stackLines = visibleLines.filter((line) => line.normalizedStart >= stackStart && line.normalizedStart < stackEnd);
226
- const candidateRows = [];
227
- const rowPattern = /^\| Agent Handoff Kit template version \| ([^|\n]+) \| [^|\n]+ \|$/u;
228
- for (const line of stackLines) {
229
- const match = rowPattern.exec(line.text);
230
- if (!match) continue;
231
- const version = match[1].trim();
232
- if (!isStableSemver(version)) return null;
233
- candidateRows.push({
234
- version,
235
- row: line.text,
236
- rowStart: line.start,
237
- rowEnd: line.end
238
- });
239
- }
240
- const versionLabelRows = stackLines.filter((line) => line.text.startsWith("| Agent Handoff Kit template version |"));
241
- if (versionLabelRows.length !== candidateRows.length || candidateRows.length !== 1) return null;
242
- const [row] = candidateRows;
243
- return { version: row.version, row: row.row, rowStart: row.rowStart, rowEnd: row.rowEnd };
228
+ function isInside(root, target) {
229
+ const relative = path.relative(path.resolve(root), path.resolve(target));
230
+ return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
244
231
  }
245
232
 
246
- export function markdownVisibleLinesOutsideHiddenBlocks(text) {
247
- const value = String(text);
248
- const normalized = value.replace(/\r\n/g, "\n");
249
- const lines = normalized.split("\n");
250
- const result = [];
251
- let offset = 0;
252
- let fence = null;
253
- let inComment = false;
254
- for (let index = 0; index < lines.length; index += 1) {
255
- const line = lines[index];
256
- if (inComment) {
257
- if (line.includes("-->")) inComment = false;
258
- offset += line.length + 1;
259
- continue;
260
- }
261
- const fenceMatch = /^\s{0,3}(`{3,}|~{3,})(?![`~])(.*)$/u.exec(line);
262
- const fenceRun = fenceMatch?.[1] ?? null;
263
- if (fence) {
264
- if (
265
- fenceRun
266
- && fenceRun[0] === fence.char
267
- && fenceRun.length >= fence.length
268
- && /^\s*$/u.test(fenceMatch?.[2] ?? "")
269
- ) {
270
- fence = null;
271
- }
272
- offset += line.length + 1;
273
- continue;
274
- }
275
- if (fenceRun) {
276
- fence = { char: fenceRun[0], length: fenceRun.length };
277
- offset += line.length + 1;
278
- continue;
279
- }
280
- const commentStart = line.indexOf("<!--");
281
- if (commentStart >= 0) {
282
- if (line.indexOf("-->", commentStart + 4) < 0) inComment = true;
283
- offset += line.length + 1;
284
- continue;
285
- }
286
- result.push({
287
- text: line,
288
- line: index,
289
- normalizedStart: offset,
290
- normalizedEnd: offset + line.length,
291
- start: originalOffsetForNormalizedOffset(value, offset),
292
- end: originalOffsetForNormalizedOffset(value, offset + line.length)
293
- });
294
- offset += line.length + 1;
233
+ function decodeUtf8(buffer) {
234
+ try {
235
+ return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
236
+ } catch {
237
+ return null;
295
238
  }
296
- return result;
297
239
  }
298
240
 
299
- function originalOffsetForNormalizedOffset(text, normalizedOffset) {
300
- let original = 0;
301
- let normalized = 0;
302
- while (original < text.length && normalized < normalizedOffset) {
303
- if (text[original] === "\r" && text[original + 1] === "\n") {
304
- original += 2;
305
- normalized += 1;
306
- } else {
307
- original += 1;
308
- normalized += 1;
309
- }
310
- }
311
- return original;
312
- }
313
-
314
- function isStableSemver(value) {
315
- return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.test(String(value));
241
+ function sha256(value) {
242
+ return createHash("sha256").update(value).digest("hex");
316
243
  }
317
-
318
- export function extractExplicitLocalReferences(text) {
319
- const matches = new Map();
320
- const add = (raw, via) => {
321
- const normalized = normalizeReference(raw);
322
- if (normalized) matches.set(`${normalized}\0${via}`, { path: normalized, via });
323
- };
324
- for (const match of String(text).matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g)) add(match[1], "markdown-link");
325
- for (const match of String(text).matchAll(/`([^`\r\n]+)`/g)) add(match[1], "inline-code-path");
326
- for (const match of String(text).matchAll(/^\s*@([^\s]+)\s*$/gm)) add(match[1], "bridge-import");
327
- // Do not treat the dot before a filename extension as sentence punctuation.
328
- // On Windows, the truncated `dev/USER_RULES` then aliases the real
329
- // `dev/user_rules/` directory, making a valid formal router look unsafe.
330
- for (const match of String(text).matchAll(/(?:^|[\s("'`])((?:[\p{L}\p{N}_-]+[\\/])+[\p{L}\p{N}_. -]*[\p{L}\p{N}_.-])(?=$|[\s,;:,。!?)\]}>"'])/gu)) add(match[1], "plain-local-path");
331
- return [...matches.values()].sort((left, right) => `${left.path}\0${left.via}`.localeCompare(`${right.path}\0${right.via}`));
332
- }
333
-
334
- function normalizeReference(raw) {
335
- const value = String(raw).trim().replace(/^<|>$/g, "");
336
- if (!value || value.includes("://") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/")) return null;
337
- const withoutFragment = value.split(/[?#]/, 1)[0].replaceAll("\\", "/");
338
- if (!withoutFragment || withoutFragment.endsWith("/") || (!withoutFragment.includes("/") && !/\.[\p{L}\p{N}]+$/u.test(withoutFragment))) return null;
339
- return normalizeProjectRelative(withoutFragment);
340
- }
341
-
342
- function normalizeProjectRelative(relative) {
343
- const normalized = path.posix.normalize(String(relative).replaceAll("\\", "/").replace(/^\.\//, ""));
344
- if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
345
- return normalized;
346
- }
347
-
348
- function isInside(root, target) {
349
- const relative = path.relative(path.resolve(root), path.resolve(target));
350
- return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
351
- }
352
-
353
- function decodeUtf8(buffer) {
354
- try {
355
- return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
356
- } catch {
357
- return null;
358
- }
359
- }
360
-
361
- function sha256(value) {
362
- return createHash("sha256").update(value).digest("hex");
363
- }
package/docs/commands.md CHANGED
@@ -1,59 +1,61 @@
1
- # 快捷入口 / Kit shortcuts
2
-
3
- 啟用後,在專案的 AI 對話輸入短口令即可。Claude Code、Gemini CLI、Antigravity CLI 用 `/handoff-kit-help`;Codex 用 `$handoff-kit-help`,或輸入 `/skills` 選擇 `handoff-kit-help`。Codex 並不提供相同的直接 `/handoff-kit-*` 自訂命令。
4
-
5
- | 用途 | Claude / Gemini / Antigravity | Codex |
6
- |---|---|---|
7
- | 開工、接收交接 | `/handoff-kit-start` | `$handoff-kit-start` |
8
- | 收工、保存及檢查交接 | `/handoff-kit-close` | `$handoff-kit-close` |
9
- | 開啟自動更新的進度頁 | `/handoff-kit-progress` | `$handoff-kit-progress` |
10
- | 檢查文件是否接上治理 | `/handoff-kit-align` | `$handoff-kit-align` |
11
- | 新手引導 | `/handoff-kit-onboard` | `$handoff-kit-onboard` |
12
- | 保存日後要遵守的工作規則 | `/handoff-kit-remember` | `$handoff-kit-remember` |
13
- | 檢查 Kit 安裝狀態 | `/handoff-kit-check` | `$handoff-kit-check` |
14
- | 顯示這份功能選單 | `/handoff-kit-help` | `$handoff-kit-help` |
15
-
16
- 可在口令後補充目標,例如 `/handoff-kit-align docs/plan.md`、`/handoff-kit-remember 回覆請用繁體中文`,或 `/handoff-kit-start 繼續完成目前目標`。單獨開工只接收狀態;未指定文件的對齊先列候選,不自行整理整個專案。收工會執行原有完整流程,但不新增提交或發佈權限。原有「開工」「收工」等自然語句仍可使用。
17
-
18
- ## 每個專案啟用一次
19
-
20
- 對 AI 說:「在這個專案啟用 Kit 常用快捷入口。」正常 AI 安裝教學亦包含這一步。AI 應先完成 Kit 安裝/升級及其驗收,再執行:
21
-
22
- ```text
23
- npx --yes @adamchanadam/agent-handoff-kit@latest commands --root . --dry-run
24
- npx --yes @adamchanadam/agent-handoff-kit@latest commands --root . --yes
25
- ```
26
-
27
- 預設建立全部平台入口;`--agent claude|gemini|codex|antigravity` 可只建立指定平台。Codex 與 Antigravity 共用一份 `.agents/skills`。程序只建立缺少的入口;相同內容保持不動;任何同名差異會在寫入前停止,不覆寫用戶設定。中斷時保留已完成入口,重新預覽再補齊。此程序不代替 Kit 健康檢查,亦不修改全機設定或官方規則正文。
28
-
29
- 快捷入口只可安裝在專案內。預覽及啟用都會拒絕使用者主目錄、磁碟根目錄,以及已知的 AI 全域設定位置(包括環境變數指定的位置);即使目錄已有 Kit 檔案也不例外。若任何入口的輸出位置會落入全域範圍,整批停止,不建立檔案或目錄。主目錄下的一般專案及 Codex 管理的 `worktrees` 內專案仍可使用;全域設定資料夾本身不能當作專案。
30
-
31
- 如入口未出現,重新開啟該專案的 AI 對話;Gemini CLI 亦可用 `/commands reload`。舊版 CLI 若顯示不認識 `commands`,代表執行的套件未包含此功能。未發佈開發版必須使用已選定的本機套件,不能把 npm 舊版當成新功能驗收。
32
-
33
- 入口由 `bin/commands.mjs` 統一產生。Claude 使用 `.claude/skills/handoff-kit-*/SKILL.md`,Gemini 使用 `.gemini/commands/handoff-kit-*.toml`,Codex/Antigravity 使用 `.agents/skills/handoff-kit-*/SKILL.md`。規則仍由專案 `AGENTS.md`、`dev/RULE_PACKS.md` 及其指向的文件負責。這些入口不會因被 AI 自動發現便授權執行。
34
-
35
- ## 進度頁與使用成本
36
-
37
- `handoff-kit-progress` 自動開啟頁面,同一專案重複使用會重用相符服務。全部頁面斷線後保留 8 小時,閒置時暫停讀檔;其後服務才自動停止,下次再用口令會重新啟動。不同專案各自識別;頁面正在顯示哪個專案,以頁面專案名稱為準。詳見[進度頁說明](progress.md)。
38
-
39
- 口令本身由 AI 處理,會使用少量對話內容;進度頁之後由本機程式讀取既有紀錄並自動更新,不需 AI 再寫報告、重做 HTML 或逐步呼叫更新。使用既有 Node.js 18+ 與瀏覽器,不需額外安裝 Python 或服務平台。`npx` 取得工具可能需要網絡;頁面服務本身只在本機運行。
40
-
41
- ## English
42
-
43
- Use `/handoff-kit-*` in Claude Code, Gemini CLI and Antigravity CLI. In Codex, use `$handoff-kit-*` or select the skill through `/skills`; direct custom `/handoff-kit-*` commands are not equivalent Codex syntax.
44
-
45
- The eight entries are **handoff-kit-start** (resume), **handoff-kit-close** (save and verify the full handoff), **handoff-kit-progress** (open the live overview), **handoff-kit-align** (check document governance links), **handoff-kit-onboard** (guided introduction), **handoff-kit-remember** (save an explicitly requested future working rule), **handoff-kit-check** (check the Kit installation), and **handoff-kit-help** (menu).
46
-
47
- Add context after an entry, such as `/handoff-kit-align docs/plan.md` or `/handoff-kit-start continue the current objective`. Bare start only recovers state. Alignment without a target lists candidates before any edits. Closeout follows the existing complete workflow without granting Git or publishing permission. Natural-language requests still work.
48
-
49
- Ask the AI to “Enable Kit shortcuts in this project.” After installing/upgrading Kit and verifying that operation, run the two commands above: preview, then enable with `--yes`. This setup step is included in the AI installation guide. The default enables all platforms; `--agent claude|gemini|codex|antigravity` selects one. Codex and Antigravity share `.agents/skills`. Missing files are created, identical files kept, and any different same-name file stops the preflight with zero writes. After interruption, completed files remain and a new preview shows what is left. This setup does not replace health checks, change global settings or rewrite official rules.
50
-
51
- Shortcuts are project-local only. Preview and enable both refuse user home directories, filesystem roots and known shared AI configuration locations, including environment-configured locations, even if Kit files exist there. If any generated entry would land in global scope, the whole operation stops without creating files or directories. Ordinary projects beneath home and projects inside Codex-managed `worktrees` remain supported; the global configuration folder itself cannot serve as a project.
52
-
53
- Reopen the project's AI session if entries do not appear; Gemini also supports `/commands reload`. An unrecognized `commands` option means the running package lacks this feature. Use the selected local package for unreleased development; testing npm's older release cannot verify new features.
54
-
55
- `bin/commands.mjs` owns the shared content and generates Claude `.claude/skills/handoff-kit-*/SKILL.md`, Gemini `.gemini/commands/handoff-kit-*.toml`, and Codex/Antigravity `.agents/skills/handoff-kit-*/SKILL.md`. Project `AGENTS.md`, `dev/RULE_PACKS.md` and their routed owners still define procedures. Automatic skill discovery does not authorize action.
56
-
57
- `handoff-kit-progress` opens the view and reuses a matching service for the same project. The service stays available for eight hours after all pages disconnect, without idle file polling; invoke the entry again to reuse it or restart it after expiry. Projects have separate identities; check the displayed project name. See [the progress guide](progress.md). An AI invocation uses some conversation tokens; subsequent page updates read existing records locally, without more AI reports, redesigned HTML or per-step update calls. It uses the existing Node.js 18+ environment and a browser; no Python or hosting platform is required. `npx` tool acquisition may need network access, while the view itself runs locally.
58
-
59
- Platform references: [Claude skills](https://code.claude.com/docs/en/skills), [Gemini custom commands](https://geminicli.com/docs/cli/custom-commands/), [Antigravity CLI skills](https://antigravity.google/docs/skills?app=cli), [Codex skills](https://learn.chatgpt.com/docs/build-skills).
1
+ # Agent Handoff Kit 常用指令
2
+
3
+ [English](#shortcuts)
4
+
5
+ 這份說明包含尚未發布的更新;正式下載可用的功能,以已發布版本為準。
6
+
7
+ 在專案的 AI 對話輸入指令,不是在終端機。Claude Code、Gemini CLI、Antigravity CLI 用 /;Codex 用 $,也可從 /skills 選取。 例如 Codex 用 `$handoff-kit-start`。
8
+
9
+ | 想做甚麼 | 指令 |
10
+ |---|---|
11
+ | 接回上次工作 | [`/handoff-kit-start`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#start) |
12
+ | 看專案全貌 | [`/handoff-kit-progress`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#progress) |
13
+ | 準備結束這次對話 | [`/handoff-kit-close`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#close) |
14
+ | 第一次用,想有人帶路 | [`/handoff-kit-onboard`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#onboard) |
15
+ | 忘了用哪個指令 | [`/handoff-kit-help`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#help) |
16
+ | 讓下次 AI 找得到重要文件 | [`/handoff-kit-align`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#align) |
17
+ | 希望以後都照這樣做 | [`/handoff-kit-remember`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#remember) |
18
+ | 交接功能出了問題 | [`/handoff-kit-check`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#check) |
19
+ | 想用最新正式版 | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#update) |
20
+
21
+ 日常用開工、進度頁、收工;其他按需要用。每個指令的例子與注意事項都在[使用指南](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html),不用另外讀一套教學。
22
+
23
+ ### 安裝與選單
24
+
25
+ 安裝或升級時,指令入口會一併放好,只供目前專案使用,不安裝到電腦的共用設定。不用額外啟用。舊對話未顯示時,重新開啟專案對話;Gemini CLI 可用 `/commands reload`。Codex 選單有簡短中英文說明,例如「開工 / Start」。
26
+
27
+ 如果入口缺漏,把[安裝頁](../agent-handoff-kit-ai-install.html)的句子交給 AI。同版本也可補齊缺項;你的自訂內容遇到衝突會保留並停止,不會強行覆寫。檔案齊備只證明安裝結果,實際選單和呼叫仍須在所用工具確認。
28
+
29
+ ### 使用成本
30
+
31
+ 叫 AI 執行指令及平常保存紀錄會使用一些 token。進度頁開啟後,查看、篩選和自動更新由本機程式處理,不再叫 AI 寫報告。[進度頁說明](progress.md)包含重開、斷線和資料不完整時的處理。
32
+
33
+ ## Shortcuts
34
+
35
+ This guide includes updates that have not been released yet. Features available to download depend on the published version.
36
+
37
+ Enter shortcuts in your project’s AI conversation, not in the terminal. Claude Code, Gemini CLI and Antigravity CLI use /; Codex uses $, or selection through /skills. For example, Codex uses `$handoff-kit-start`.
38
+
39
+ | What you want to do | Shortcut |
40
+ |---|---|
41
+ | Pick up where you left off | [`/handoff-kit-start`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#start) |
42
+ | See the whole project | [`/handoff-kit-progress`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#progress) |
43
+ | Finish this conversation | [`/handoff-kit-close`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#close) |
44
+ | Get help getting started | [`/handoff-kit-onboard`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#onboard) |
45
+ | Find the right shortcut | [`/handoff-kit-help`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#help) |
46
+ | Help the next AI find an important file | [`/handoff-kit-align`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#align) |
47
+ | Keep a working preference for next time | [`/handoff-kit-remember`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#remember) |
48
+ | Check whether the tool is installed correctly | [`/handoff-kit-check`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#check) |
49
+ | Get the latest released version | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#update) |
50
+
51
+ Start, Progress and Wrap up are the everyday shortcuts; use the others as needed. Examples and limits for each are in the [guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html), so you do not need a second set of instructions.
52
+
53
+ ### Installation and menus
54
+
55
+ Installation and upgrades include the shortcuts for this project only, not shared computer-wide settings. No separate activation is needed. If an older conversation does not show them, reopen the project conversation; Gemini CLI can use `/commands reload`. Codex has short bilingual labels such as “開工 / Start”.
56
+
57
+ For missing entries, give the AI the sentence on the [setup page](../agent-handoff-kit-ai-install.en.html). Reapplying the same version can fill missing files. Conflicting custom content is kept and the operation stops, without forced overwrites. Complete files prove installation only; check menus and invocation in the tool you use.
58
+
59
+ ### Usage cost
60
+
61
+ Asking the AI to run a shortcut and saving normal records use some tokens. Once the dashboard is open, viewing, filtering and automatic updates run locally without asking the AI to write another report. [Dashboard help](progress.md) covers reopening, disconnections and incomplete data.