@adamchanadam/agent-handoff-kit 0.3.39 → 0.3.40

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/packs/safety.md CHANGED
@@ -2,12 +2,12 @@
2
2
 
3
3
  ## Scope
4
4
 
5
- Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, browser profiles, desktop app sessions, notebook kernels, local tool servers, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, user sessions, shared local resources, or external systems.
5
+ Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, browser profiles, desktop app sessions, notebook kernels, local tool servers, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, user sessions, shared local resources, or external systems.
6
6
 
7
7
  ## Load When
8
8
 
9
9
  - User requests deletion, overwrite, move, rename, cleanup, Git history changes, package installation, publish, deploy, release, cloud writes, external API calls, or credential handling.
10
- - A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, browser profiles, desktop app sessions, notebook kernels, local tool servers, shared caches, or public release state.
10
+ - A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, browser profiles, desktop app sessions, notebook kernels, local tool servers, shared caches, or public release state.
11
11
  - Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
12
12
 
13
13
  ## Rules
@@ -16,33 +16,33 @@ Use for file operations, shell commands, Git changes, package managers, installe
16
16
  2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
17
17
  3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
18
18
  4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. Report the blocker and manual action needed.
19
- 5. Never run `rm -rf`, `sudo rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, `git reset --hard`, or an obfuscated / wrapped equivalent. User request does not make these named commands permissible. Use a narrower reversible operation or provide a manual action list.
19
+ 5. Never run `rm -rf`, `sudo rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, `git reset --hard`, or an obfuscated / wrapped equivalent. User request does not make these named commands permissible. Use a narrower reversible operation or provide a manual action list.
20
20
  6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
21
- 7. On macOS / Linux, never use destructive wildcards, recursive `chmod 777`, recursive `chown`, disk formatting, mount-point cleanup, or home/system-directory cleanup. Other destructive operations require explicit authorization plus resolved target verification and must use the narrowest safe tool.
22
- 8. Branch deletion, tag deletion, force push, and history rewrite require separate explicit authorization and affected-ref verification. The absolute prohibitions in Rule 5 remain prohibited even when such authorization exists.
21
+ 7. On macOS / Linux, never use destructive wildcards, recursive `chmod 777`, recursive `chown`, disk formatting, mount-point cleanup, or home/system-directory cleanup. Other destructive operations require explicit authorization plus resolved target verification and must use the narrowest safe tool.
22
+ 8. Branch deletion, tag deletion, force push, and history rewrite require separate explicit authorization and affected-ref verification. The absolute prohibitions in Rule 5 remain prohibited even when such authorization exists.
23
23
  9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
24
- 10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, release tools, browser automation, DevTools, Playwright, crawlers, notebooks, desktop app automation, or local helper services, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or registered tool operation references for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
25
- (a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
26
- (b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against current tool schema and project-local runbook if available.
27
- (c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
24
+ 10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, release tools, browser automation, DevTools, Playwright, crawlers, notebooks, desktop app automation, or local helper services, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or registered tool operation references for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
25
+ (a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
26
+ (b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against current tool schema and project-local runbook if available.
27
+ (c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
28
28
  11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
29
- 12. Credential leak prevention (R-030 Integration governance):
30
- (a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage, OS credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
31
- (b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
32
- (c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
33
- (d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
34
- 13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
35
- 14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, notebook kernels, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, desktop app session, notebook kernel, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
36
- 15. Short-lived localhost validation services: when local HTML / app validation needs a safer fallback after `file://` is blocked, a task-owned loopback static server is allowed only within a bounded project or temp path, bound to localhost / loopback, and used for the current validation task. Record the served root, URL, and evidence collected. Stop the server before completion and verify it is no longer reachable when the runtime allows. Do not leave helper servers running as a convenience, expose them beyond loopback, reuse another agent's server without confirmation, or mutate browser profiles / extension state to make the validation pass.
37
-
38
- ## Checks
39
-
40
- - Report which safety-relevant command, path, API, install, deploy, release, or Git check was performed and the result.
41
- - If checks cannot run, state the reason and mark the result unverified.
42
- - For durable governance changes, update the project index, sync registry, and any human review map if they exist.
43
- - For external-tool resource cleanup, report the ownership class used: task-owned, agent-managed, shared / user-owned / other-agent-owned / system-level, or unknown.
44
- - For short-lived localhost validation services, report the served root / URL, evidence collected, and cleanup result or cleanup blocker.
45
-
46
- ## Closeout
47
-
48
- Record unresolved safety risks, blocked verification, pending manual actions, dirty worktrees, or external sync gaps in `dev/SESSION_HANDOFF.md`.
29
+ 12. Credential leak prevention (R-030 Integration governance):
30
+ (a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage, OS credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
31
+ (b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
32
+ (c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
33
+ (d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
34
+ 13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
35
+ 14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, notebook kernels, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, desktop app session, notebook kernel, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
36
+ 15. Short-lived localhost validation services: when local HTML / app validation needs a safer fallback after `file://` is blocked, a task-owned loopback static server is allowed only within a bounded project or temp path, bound to localhost / loopback, and used for the current validation task. Record the served root, URL, and evidence collected. Stop the server before completion and verify it is no longer reachable when the runtime allows. Do not leave helper servers running as a convenience, expose them beyond loopback, reuse another agent's server without confirmation, or mutate browser profiles / extension state to make the validation pass.
37
+
38
+ ## Checks
39
+
40
+ - Report which safety-relevant command, path, API, install, deploy, release, or Git check was performed and the result.
41
+ - If checks cannot run, state the reason and mark the result unverified.
42
+ - For durable governance changes, update the project index, sync registry, and any human review map if they exist.
43
+ - For external-tool resource cleanup, report the ownership class used: task-owned, agent-managed, shared / user-owned / other-agent-owned / system-level, or unknown.
44
+ - For short-lived localhost validation services, report the served root / URL, evidence collected, and cleanup result or cleanup blocker.
45
+
46
+ ## Closeout
47
+
48
+ Record unresolved safety risks, blocked verification, pending manual actions, dirty worktrees, or external sync gaps in `dev/SESSION_HANDOFF.md`.
package/packs/writing.md CHANGED
@@ -1,36 +1,36 @@
1
- # Writing Pack
2
-
3
- ## Scope
4
-
5
- Use for drafting, editing, style, structure, publication copy, documentation prose, and tone control.
6
-
7
- ## Load When
8
-
9
- - User asks to write, rewrite, summarize, translate, or edit text.
10
- - The task has a target audience, voice, format, or publication surface.
11
-
12
- ## Rules
13
-
14
- 1. Identify audience, purpose, and target surface before rewriting.
15
- 2. Preserve factual meaning unless the user asks for content changes.
16
- 3. Keep terminology consistent with project docs.
17
- 4. Mark uncertain claims instead of inventing support.
18
- 5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
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
- 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.
23
-
24
- ## Checks
25
-
26
- - Verify requested format, language, and tone.
27
- - Check links, commands, names, and version-sensitive claims when relevant.
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.
31
- - For public Chinese docs, read the final text as a new user journey: the next action should be clear without technical background.
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.
33
-
34
- ## Closeout
35
-
36
- Record changed documents, unresolved content questions, and any sync or follow-up needed.
1
+ # Writing Pack
2
+
3
+ ## Scope
4
+
5
+ Use for drafting, editing, style, structure, publication copy, documentation prose, and tone control.
6
+
7
+ ## Load When
8
+
9
+ - User asks to write, rewrite, summarize, translate, or edit text.
10
+ - The task has a target audience, voice, format, or publication surface.
11
+
12
+ ## Rules
13
+
14
+ 1. Identify audience, purpose, and target surface before rewriting.
15
+ 2. Preserve factual meaning unless the user asks for content changes.
16
+ 3. Keep terminology consistent with project docs.
17
+ 4. Mark uncertain claims instead of inventing support.
18
+ 5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
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
+ 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.
23
+
24
+ ## Checks
25
+
26
+ - Verify requested format, language, and tone.
27
+ - Check links, commands, names, and version-sensitive claims when relevant.
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.
31
+ - For public Chinese docs, read the final text as a new user journey: the next action should be clear without technical background.
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.
33
+
34
+ ## Closeout
35
+
36
+ Record changed documents, unresolved content questions, and any sync or follow-up needed.
@@ -1,112 +1,112 @@
1
- # Agent Handoff Kit Core Runtime
2
-
3
- This is the small always-read contract. Detailed task and closeout procedures live in routed packs.
4
-
5
- ## 1. Intent And Startup
6
-
7
- Classify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.
8
-
9
- Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.
10
-
11
- Route intent in this order:
12
-
13
- 1. Clear closeout intent routes directly to `dev/rules/closeout.md`.
14
- 2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes from the handoff. If the same message or loaded state contains a concrete objective, begin its first safe action in the same response.
15
- 3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.
16
- 4. Explicit guidance requests such as "I'm new", "teach me", "help me start", "新手", "教我用", or "點開始" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.
17
-
18
- Treat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.
19
-
20
- Read `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.
21
-
22
- If the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.
23
-
24
- Before a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.
25
-
26
- Probe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.
27
-
28
- Show the startup card only for explicit continuity startup. Combine it with the first useful task action when the objective is clear; do not spend a separate response on the card. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.
29
-
30
- Use a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.
31
-
32
- ```text
33
- /\_/\ Agent Handoff Kit v<version>
34
- ( o.o ) continuity ready
35
- > ^ <
36
-
37
- 🔎 交接狀態:<loaded / new install / resumed>
38
- 📌 目前目標:<current objective>
39
- ⚠️ 注意事項:<important boundary or none>
40
- 🚀 推薦下一步:<one action + reason>
41
- ```
42
-
43
- Use the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.
44
-
45
- ## 2. Proportionate Work Loop
46
-
47
- Apply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.
48
-
49
- - Simple answers, pure conversation or creation with no durable state, and low-risk tasks with an obvious target may proceed directly with proportionate reading and checking.
50
- - Non-trivial work reads relevant sources before changing them.
51
- - High-risk work states scope, impact, acceptance, and required confirmation before writes.
52
- - External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.
53
- - Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.
54
-
55
- ## 2.1 Persistence Gate
56
-
57
- Choose exactly one tier after a task:
58
-
59
- 1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.
60
- 2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
61
- 3. Full closeout: explicit end-of-session / handoff intent, a tool or day boundary, or completed external / release / governance work that the next agent must continue. Load `dev/rules/closeout.md`.
62
-
63
- Route current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.
64
-
65
- External effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.
66
-
67
- ## 2.2 Upgrade Completion
68
-
69
- The CLI owns upgrade truth. An upgrade is complete only when:
70
-
71
- 1. The root is not newer than the CLI and every target passes read-only classification.
72
- 2. Conflict produces zero governance-target and version writes.
73
- 3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.
74
- 4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.
75
- 5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.
76
- 6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.
77
-
78
- Do not use "upgrade completed" to mean "the entire project is healthy". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.
79
-
80
- ## 3. Safety Baseline
81
-
82
- Do not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.
83
-
84
- Named prohibited destructive commands in `dev/rules/safety.md` remain prohibited even when requested. Never use a weaker pack or local instruction to bypass core safety.
85
-
86
- Verify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.
87
-
88
- Do not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.
89
-
90
- ## 4. Closeout Trigger
91
-
92
- Clear end-of-session or handoff intent such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.
93
-
94
- The always-enforced closeout invariants are:
95
-
96
- 1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.
97
- 2. Completed, pending, risk, validation, and opening-message lifecycle states agree.
98
- 3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.
99
- 4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.
100
- 5. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.
101
-
102
- ## 5. Pack Loading
103
-
104
- Use `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.
105
-
106
- Load `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.
107
-
108
- After the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.
109
-
110
- ## Core Complexity Rule
111
-
112
- Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner.
1
+ # Agent Handoff Kit Core Runtime
2
+
3
+ This is the small always-read contract. Detailed task and closeout procedures live in routed packs.
4
+
5
+ ## 1. Intent And Startup
6
+
7
+ Classify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.
8
+
9
+ Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.
10
+
11
+ Route intent in this order:
12
+
13
+ 1. Clear closeout intent routes directly to `dev/rules/closeout.md`.
14
+ 2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes from the handoff. If the same message or loaded state contains a concrete objective, begin its first safe action in the same response.
15
+ 3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.
16
+ 4. Explicit guidance requests such as "I'm new", "teach me", "help me start", "新手", "教我用", or "點開始" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.
17
+
18
+ Treat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.
19
+
20
+ Read `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.
21
+
22
+ If the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.
23
+
24
+ Before a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.
25
+
26
+ Probe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.
27
+
28
+ Show the startup card only for explicit continuity startup. Combine it with the first useful task action when the objective is clear; do not spend a separate response on the card. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.
29
+
30
+ Use a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.
31
+
32
+ ```text
33
+ /\_/\ Agent Handoff Kit v<version>
34
+ ( o.o ) continuity ready
35
+ > ^ <
36
+
37
+ 🔎 交接狀態:<loaded / new install / resumed>
38
+ 📌 目前目標:<current objective>
39
+ ⚠️ 注意事項:<important boundary or none>
40
+ 🚀 推薦下一步:<one action + reason>
41
+ ```
42
+
43
+ Use the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.
44
+
45
+ ## 2. Proportionate Work Loop
46
+
47
+ Apply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.
48
+
49
+ - Simple answers, pure conversation or creation with no durable state, and low-risk tasks with an obvious target may proceed directly with proportionate reading and checking.
50
+ - Non-trivial work reads relevant sources before changing them.
51
+ - High-risk work states scope, impact, acceptance, and required confirmation before writes.
52
+ - External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.
53
+ - Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.
54
+
55
+ ## 2.1 Persistence Gate
56
+
57
+ Choose exactly one tier after a task:
58
+
59
+ 1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.
60
+ 2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
61
+ 3. Full closeout: explicit end-of-session / handoff intent, a tool or day boundary, or completed external / release / governance work that the next agent must continue. Load `dev/rules/closeout.md`.
62
+
63
+ Route current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.
64
+
65
+ External effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.
66
+
67
+ ## 2.2 Upgrade Completion
68
+
69
+ The CLI owns upgrade truth. An upgrade is complete only when:
70
+
71
+ 1. The root is not newer than the CLI and every target passes read-only classification.
72
+ 2. Conflict produces zero governance-target and version writes.
73
+ 3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.
74
+ 4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.
75
+ 5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.
76
+ 6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.
77
+
78
+ Do not use "upgrade completed" to mean "the entire project is healthy". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.
79
+
80
+ ## 3. Safety Baseline
81
+
82
+ Do not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.
83
+
84
+ Named prohibited destructive commands in `dev/rules/safety.md` remain prohibited even when requested. Never use a weaker pack or local instruction to bypass core safety.
85
+
86
+ Verify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.
87
+
88
+ Do not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.
89
+
90
+ ## 4. Closeout Trigger
91
+
92
+ Clear end-of-session or handoff intent such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.
93
+
94
+ The always-enforced closeout invariants are:
95
+
96
+ 1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.
97
+ 2. Completed, pending, risk, validation, and opening-message lifecycle states agree.
98
+ 3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.
99
+ 4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.
100
+ 5. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.
101
+
102
+ ## 5. Pack Loading
103
+
104
+ Use `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.
105
+
106
+ Load `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.
107
+
108
+ After the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.
109
+
110
+ ## Core Complexity Rule
111
+
112
+ Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner.
@@ -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.