@adamchanadam/agent-handoff-kit 0.3.30 → 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 +122 -107
- package/bin/agent-handoff-kit.mjs +1752 -1618
- package/package.json +19 -29
- package/packs/agent-governance.md +17 -0
- package/packs/safety.md +13 -12
- package/packs/writing.md +4 -0
- package/runtime-core/AGENTS.core.md +97 -90
- package/runtime-core/DOC_SYNC_REGISTRY.md +1 -0
- package/runtime-core/PROJECT_INDEX.md +8 -6
package/package.json
CHANGED
|
@@ -1,30 +1,20 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.3.
|
|
4
|
-
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"agent-handoff-kit": "bin/agent-handoff-kit.mjs"
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"bin/",
|
|
11
|
-
"runtime-core/",
|
|
12
|
-
"packs/",
|
|
13
|
-
"README.md",
|
|
14
|
-
"LICENSE"
|
|
15
|
-
],
|
|
16
|
-
"
|
|
17
|
-
"
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
21
|
-
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
22
|
-
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
23
|
-
"qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
|
|
24
|
-
"qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
|
|
25
|
-
},
|
|
26
|
-
"engines": {
|
|
27
|
-
"node": ">=18"
|
|
28
|
-
},
|
|
29
|
-
"license": "MIT"
|
|
1
|
+
{
|
|
2
|
+
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
+
"version": "0.3.32",
|
|
4
|
+
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"agent-handoff-kit": "bin/agent-handoff-kit.mjs"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"bin/",
|
|
11
|
+
"runtime-core/",
|
|
12
|
+
"packs/",
|
|
13
|
+
"README.md",
|
|
14
|
+
"LICENSE"
|
|
15
|
+
],
|
|
16
|
+
"engines": {
|
|
17
|
+
"node": ">=18"
|
|
18
|
+
},
|
|
19
|
+
"license": "MIT"
|
|
30
20
|
}
|
|
@@ -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/safety.md
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
# Safety Pack
|
|
2
2
|
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
-
|
|
7
|
-
## Load When
|
|
8
|
-
|
|
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, or public release state.
|
|
11
|
-
- Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
|
|
12
|
-
|
|
13
|
-
## Rules
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
+
|
|
7
|
+
## Load When
|
|
8
|
+
|
|
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, or public release state.
|
|
11
|
+
- Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
|
|
12
|
+
|
|
13
|
+
## Rules
|
|
14
14
|
|
|
15
15
|
1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
|
|
16
16
|
2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
|
|
@@ -22,7 +22,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
22
22
|
8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
|
|
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
24
|
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks. Differentiate three layers of external access (R-030 Integration governance; see `dev/rules/integrations.md`):
|
|
25
|
-
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server behavior; still verify destructive write parameters before invocation.
|
|
25
|
+
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server behavior; still verify destructive write parameters before invocation.
|
|
26
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 project-local runbook if available.
|
|
27
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.
|
|
@@ -31,6 +31,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
31
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
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
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.
|
|
34
35
|
|
|
35
36
|
## Checks
|
|
36
37
|
|
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
|
|
|
@@ -13,17 +13,19 @@ After this core is loaded, read in order:
|
|
|
13
13
|
|
|
14
14
|
Then classify the user's task and read only the required rule pack(s). State which pack(s) you loaded and why, using plain language so the user understands the working mode without needing to know pack names.
|
|
15
15
|
|
|
16
|
-
Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, or contains onboarding signal keywords (e.g. "新手", "I'm new", "教我用", "help me start", "first time", "我剛安裝", "點開始", "show me how", "agent handoff kit 可幫我做甚麼", "我想做 [type] project", "點用", "能力"), or if the session is a fresh installation (HANDOFF Active Objective empty + Session count 1), load `dev/rules/onboarding.md` proactively BEFORE doing the regular task loop. The onboarding pack surfaces the AI's role and offers Scenario A-F selection (instead of immediately diving into task execution). Onboarding is a transient pack: after the user completes their first-task walk-through, unload it and load the regular scenario pack (coding / research / writing / knowledge / etc) for ongoing work.
|
|
16
|
+
Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, or contains onboarding signal keywords (e.g. "新手", "I'm new", "教我用", "help me start", "first time", "我剛安裝", "點開始", "show me how", "agent handoff kit 可幫我做甚麼", "我想做 [type] project", "點用", "能力"), or if the session is a fresh installation (HANDOFF Active Objective empty + Session count 1), load `dev/rules/onboarding.md` proactively BEFORE doing the regular task loop. The onboarding pack surfaces the AI's role and offers Scenario A-F selection (instead of immediately diving into task execution). Onboarding is a transient pack: after the user completes their first-task walk-through, unload it and load the regular scenario pack (coding / research / writing / knowledge / etc) for ongoing work.
|
|
17
17
|
|
|
18
|
-
If the user did not paste the previous opening message but the current project root is clear, read `AGENTS.md` first as fallback entry, then use this read order. If the root is unclear or mismatched, stop and ask for the intended project root before reading or editing project state.
|
|
19
|
-
|
|
20
|
-
Detect clear startup / handoff-start intent in natural language, such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff". When that intent is clear and the current project root is clear, open `START_NEXT_SESSION_PROMPT.txt` and follow the opening message inside. If `START_NEXT_SESSION_PROMPT.txt` is missing or seems stale, read `dev/SESSION_HANDOFF.md` instead. Before changing anything, tell the user the current state and your recommended next step.
|
|
21
|
-
|
|
22
|
-
Ambiguous startup phrases need one concise confirmation question before treating them as Agent Handoff Kit startup. In particular, if the user says "<something> 開工", "<something> start", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to start Agent Handoff Kit continuity for this project.
|
|
23
|
-
|
|
24
|
-
If a required file is missing, create the smallest useful version only after confirming the target project root.
|
|
18
|
+
If the user did not paste the previous opening message but the current project root is clear, read `AGENTS.md` first as fallback entry, then use this read order. If the root is unclear or mismatched, stop and ask for the intended project root before reading or editing project state.
|
|
19
|
+
|
|
20
|
+
Detect clear startup / handoff-start intent in natural language, such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff". When that intent is clear and the current project root is clear, open `START_NEXT_SESSION_PROMPT.txt` and follow the opening message inside. If `START_NEXT_SESSION_PROMPT.txt` is missing or seems stale, read `dev/SESSION_HANDOFF.md` instead. Before changing anything, tell the user the current state and your recommended next step.
|
|
25
21
|
|
|
26
|
-
|
|
22
|
+
Ambiguous startup phrases need one concise confirmation question before treating them as Agent Handoff Kit startup. In particular, if the user says "<something> 開工", "<something> start", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to start Agent Handoff Kit continuity for this project.
|
|
23
|
+
|
|
24
|
+
If a required file is missing, create the smallest useful version only after confirming the target project root.
|
|
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.
|
|
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
|
|
|
@@ -32,22 +34,22 @@ After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empt
|
|
|
32
34
|
- If probe fails (current AI tool lacks the Connector / auth expired / network issue): print warning in the startup card (`⚠️ Boundary` line) noting which Integration is declared-but-unavailable + that this session will fallback to paste flow when that external surface is touched. Do not attempt to auto-fix auth or credential issues; surface to the user to handle via the AI tool's own settings interface.
|
|
33
35
|
- Credential separation: AI must never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens). Credentials live in OS-level secure storage or AI-tool-specific config, never in `dev/*` files. Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) and redact + warn the user to rotate the token if accidentally pasted.
|
|
34
36
|
|
|
35
|
-
After startup reads are complete, show one short startup card. If onboarding is loaded, combine this card and the onboarding choice list into one first response. Do not print any standalone startup card before the onboarding rule has been read. Do not print a partial card. Do not print the cat banner twice. If you started drafting a card and then discovered onboarding applies, discard the draft and output only the final combined response.
|
|
36
|
-
|
|
37
|
-
Display version rule: after reading `dev/PROJECT_INDEX.md`, take the card version from the `## Stack` row `Agent Handoff Kit template version`. Print it as `vX.Y.Z`. If that row is missing, unreadable, or not a version, print `version unverified`. Never print the literal placeholder `v<version>` in user-facing startup or closeout output.
|
|
38
|
-
|
|
39
|
-
```text
|
|
40
|
-
/\_/\ Agent Handoff Kit v<version>
|
|
41
|
-
( o.o ) continuity ready
|
|
42
|
-
> ^ <
|
|
43
|
-
|
|
44
|
-
🔎 交接狀態:<loaded / new install / resumed>
|
|
45
|
-
📌 目前目標:<current objective>
|
|
46
|
-
⚠️ 注意事項:<important boundary or none>
|
|
47
|
-
🚀 下一步:<next action>
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation.
|
|
37
|
+
After startup reads are complete, show one short startup card. If onboarding is loaded, combine this card and the onboarding choice list into one first response. Do not print any standalone startup card before the onboarding rule has been read. Do not print a partial card. Do not print the cat banner twice. If you started drafting a card and then discovered onboarding applies, discard the draft and output only the final combined response.
|
|
38
|
+
|
|
39
|
+
Display version rule: after reading `dev/PROJECT_INDEX.md`, take the card version from the `## Stack` row `Agent Handoff Kit template version`. Print it as `vX.Y.Z`. If that row is missing, unreadable, or not a version, print `version unverified`. Never print the literal placeholder `v<version>` in user-facing startup or closeout output.
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
/\_/\ Agent Handoff Kit v<version>
|
|
43
|
+
( o.o ) continuity ready
|
|
44
|
+
> ^ <
|
|
45
|
+
|
|
46
|
+
🔎 交接狀態:<loaded / new install / resumed>
|
|
47
|
+
📌 目前目標:<current objective>
|
|
48
|
+
⚠️ 注意事項:<important boundary or none>
|
|
49
|
+
🚀 下一步:<next action>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation.
|
|
51
53
|
|
|
52
54
|
## 2. Work Loop
|
|
53
55
|
|
|
@@ -56,40 +58,43 @@ 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.
|
|
61
|
+
4. QC: run available checks or state why they cannot run.
|
|
60
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.
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
-
|
|
80
|
-
-
|
|
81
|
-
-
|
|
82
|
-
-
|
|
83
|
-
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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.
|
|
64
|
+
|
|
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.
|
|
66
|
+
|
|
67
|
+
For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
|
|
68
|
+
|
|
69
|
+
## 2.1 Persistence Gate
|
|
70
|
+
|
|
71
|
+
Use exactly one of these tiers after each task:
|
|
72
|
+
|
|
73
|
+
1. No persistence: choose this when the task produced no durable fact. Examples: one-off answers, active draft / image iterations not approved as final, routine successful checks that can be rerun, transient tool output, and ordinary progress that remains visible in the current chat.
|
|
74
|
+
2. Lightweight checkpoint: choose this when a durable fact exists and the session continues, when the agent may be interrupted before full closeout, or when uncertain whether the fact is durable. Write only the smallest correct home. Lightweight checkpoint is not full closeout: do not regenerate `START_NEXT_SESSION_PROMPT.txt`, do not show a closeout card, do not run full closeout maintenance, and do not reconcile every handoff section unless the fact itself requires it.
|
|
75
|
+
3. Full closeout: choose this only for explicit end-of-session / handoff intent, tool or day boundary, user-requested handoff, agent about to stop, or completed release / external sync / governance change that needs the next agent to continue from persisted state.
|
|
76
|
+
|
|
77
|
+
Task contract changes are durable facts when they affect future action. If the user adds or changes the product goal, requirements, development checklist, acceptance rules, exclusions, priority, or task scope during a long-running task, first reconcile those changes into one current task contract before continuing. If a dedicated spec, backlog, issue, runbook, or project document is already the authoritative home, update that home and cite it from `dev/SESSION_HANDOFF.md`; otherwise merge the current contract into `dev/SESSION_HANDOFF.md` under `Task Understanding Summary`, `Active Objective`, `Next Priorities`, and `Next Task Required Reading`. Do not scatter the same task contract across chat memory, log entries, draft docs, and startup prompts.
|
|
78
|
+
|
|
79
|
+
Route durable facts by file role:
|
|
80
|
+
|
|
81
|
+
- Current objective, next action, unresolved risk, blocker, or a fact needed at startup belongs in `dev/SESSION_HANDOFF.md`.
|
|
82
|
+
- Chronological evidence, command output, validation result, and research trace belongs in `dev/SESSION_LOG.md` when it affects future action or cannot be cheaply rerun. Routine successful checks that can be rerun are not durable facts.
|
|
83
|
+
- File maps, command maps, reference maps, source locations, and installed capability maps belong in `dev/PROJECT_INDEX.md`.
|
|
84
|
+
- Sync obligations across repositories, docs, mirrors, or external surfaces belong in `dev/DOC_SYNC_REGISTRY.md`.
|
|
85
|
+
- Long-term decisions, architecture trade-offs, durable rationale, and research-derived decisions belong in `dev/PROJECT_DECISIONS.md`. Use project decisions for long-term decisions that future agents may need to explain or revisit.
|
|
86
|
+
- Reusable operating procedures and practice-to-mechanism lessons belong in the relevant rule pack, registered reference, or QA check. Do not store reusable procedure knowledge only in handoff or log.
|
|
87
|
+
|
|
88
|
+
External Impact Note: if a task reads from, writes to, generates artifacts for, pushes, publishes, or updates anything outside the expected project root confirmed at startup, record one concise note per external target as soon as the external effect is complete; full closeout later reconciles the note. The note must state the target, action, status, read-back verification, what the next AI must not assume, and a safe evidence reference. Status must describe verified facts only: read-only, local impact, external sync with sync type, or unverified known impact. Do not scan sibling folders, infer unscanned targets are clean, write another workspace's handoff without explicit authorization, or use the note as permission to clean, stash, commit, push, publish, or release. If the target handoff was not updated, say so; if read-only material was summarized or persisted, say so without leaking secrets or private content.
|
|
89
|
+
|
|
90
|
+
Do not persist one-time delivery instructions, old hashes, old version facts, incident notes, routine green validation, or unapproved draft status as current state, next priorities, durable anchors, or startup instructions. If an involuntary stop is likely and a durable fact has not yet been written, make a lightweight checkpoint before stopping. If uncertain whether a fact is durable, choose lightweight checkpoint.
|
|
91
|
+
|
|
92
|
+
## 2.2 Upgrade Done Contract
|
|
88
93
|
|
|
89
94
|
`agent-handoff-kit upgrade` is considered complete only when all of the following hold. The CLI enforces this contract; do not declare upgrade success without it.
|
|
90
95
|
|
|
91
96
|
1. `AGENTS.md` health state is `clean`: exactly one `# Agent Handoff Kit Core Runtime` heading, exactly one paired managed-core marker block, and no unmarked stale core ranges. Sandwich states (managed marker plus an unmarked stale core) are not clean; the installer must replace the stale ranges, not skip.
|
|
92
|
-
2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, handoff lifecycle checks, and credential separation checks. A `START_NEXT_SESSION_PROMPT.txt` convenience-copy warning does not block upgrade health; that file is regenerated at full closeout.
|
|
97
|
+
2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, handoff lifecycle checks, and credential separation checks. A `START_NEXT_SESSION_PROMPT.txt` convenience-copy warning does not block upgrade health; that file is regenerated at full closeout.
|
|
93
98
|
3. The migration report records every action taken, with backup paths for merged files.
|
|
94
99
|
|
|
95
100
|
If any check fails, the upgrade did not finish; resolve the failure (or hand the failure output to the user) before reporting completion. This contract is the single source of truth for upgrade success; downstream QA scripts and release-grade QA derive their assertions from it.
|
|
@@ -109,43 +114,45 @@ Do not claim completion without evidence from checks, inspection, or a clear exp
|
|
|
109
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.
|
|
110
115
|
|
|
111
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.
|
|
112
|
-
|
|
113
|
-
At full closeout:
|
|
114
117
|
|
|
115
|
-
|
|
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.
|
|
116
119
|
|
|
117
|
-
|
|
120
|
+
At full closeout:
|
|
121
|
+
|
|
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.
|
|
123
|
+
|
|
124
|
+
1. Reconcile `dev/SESSION_HANDOFF.md`. Do not append a new state snapshot under old state. Verify `Durable Anchors`, then rewrite or explicitly confirm every section under `Closeout-Reconciled State`.
|
|
118
125
|
2. Add a concise entry to `dev/SESSION_LOG.md` with work actually completed this session and the exact next-session opening message.
|
|
119
126
|
3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
|
|
120
127
|
4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
|
|
121
128
|
5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
|
|
122
|
-
6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, whether the `Persistence routing checked` field is complete, whether completed / pending / risk / opening-message lifecycle conflicts were resolved, and whether the opening message matches current state. In the same step, run the handoff lifecycle consistency check before declaring handoff ready: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.
|
|
123
|
-
7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
|
|
124
|
-
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
125
|
-
9. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is the stateful startup prompt that the next local agent must read. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
|
|
126
|
-
10. Show a short closeout card, then provide the next-session startup entry in a fenced `text` code block. Primary entry, when the next local AI agent is already opened at this project root: `Start Agent Handoff` / `開工`. Fallback entry, when the next AI agent is not yet pointed at the project root: `Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
|
|
127
|
-
11. Run the closeout maintenance trigger check. This is a short required check, not a full maintenance pass every time. Record the result in the new `dev/SESSION_LOG.md` entry under `Log maintenance`.
|
|
128
|
-
|
|
129
|
-
Hard triggers:
|
|
130
|
-
|
|
131
|
-
(a) Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline) when `dev/SESSION_LOG.md` reaches N ≥ 11 entries, or when the main log exceeds 1500 lines. If triggered, move N ≥ 11 entries into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved, maintain `dev/SESSION_LOG_archive/INDEX.md`, collapse absorbed N=4–10 entries to short-index lines, and port any unique narrative into the relevant durable source before collapsing it. If a research trail affected a long-term decision, public claim, strategy, governance rule, or material selection, port its evidence chain into `dev/PROJECT_DECISIONS.md` using that file's research-derived decision format before collapsing the log. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
|
|
132
|
-
|
|
133
|
-
(b) Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline when `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section (e.g. `## Confirmed Decisions`, `## Decisions`, `## 已定案決策`) with a numbered list of ≥ 30 entries. If triggered, split the oldest entries, retaining the most recent 8–22 in the handoff hot tier, into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first.
|
|
134
|
-
|
|
135
|
-
(c) Append to `dev/PROJECT_DECISIONS.md` immediately, or at closeout, when the current session includes substantive task evolution, a multi-option architectural trade-off with recorded rationale, a cross-session accumulated pattern, or a user retrospective question. Use `## Evolution Timeline`, `## Architecture Choices`, or `## Insights & Learnings` as appropriate. If the decision is research-derived, use that file's evidence-chain format so the source, summary, inference, decision impact, and uncertainty survive future compression.
|
|
136
|
-
|
|
137
|
-
(d) Run a full long-term maintenance pass every 10 closeouts as a backstop, even if no trigger seems obvious. Count closeouts from the main `dev/SESSION_LOG.md` entries plus archive index entry counts when an archive exists; if the count cannot be determined confidently, treat the current N=10 boundary as the backstop trigger.
|
|
138
|
-
|
|
139
|
-
If none of the hard triggers, semantic triggers, or 10-closeout backstop applies, write a one-line no-op reason and do not perform full long-term maintenance. This keeps routine closeout fast while still preventing silent drift.
|
|
129
|
+
6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, whether the `Persistence routing checked` field is complete, whether completed / pending / risk / opening-message lifecycle conflicts were resolved, and whether the opening message matches current state. In the same step, run the handoff lifecycle consistency check before declaring handoff ready: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.
|
|
130
|
+
7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
|
|
131
|
+
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
132
|
+
9. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is the stateful startup prompt that the next local agent must read. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
|
|
133
|
+
10. Show a short closeout card, then provide the next-session startup entry in a fenced `text` code block. Primary entry, when the next local AI agent is already opened at this project root: `Start Agent Handoff` / `開工`. Fallback entry, when the next AI agent is not yet pointed at the project root: `Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
|
|
134
|
+
11. Run the closeout maintenance trigger check. This is a short required check, not a full maintenance pass every time. Record the result in the new `dev/SESSION_LOG.md` entry under `Log maintenance`.
|
|
135
|
+
|
|
136
|
+
Hard triggers:
|
|
137
|
+
|
|
138
|
+
(a) Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline) when `dev/SESSION_LOG.md` reaches N ≥ 11 entries, or when the main log exceeds 1500 lines. If triggered, move N ≥ 11 entries into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved, maintain `dev/SESSION_LOG_archive/INDEX.md`, collapse absorbed N=4–10 entries to short-index lines, and port any unique narrative into the relevant durable source before collapsing it. If a research trail affected a long-term decision, public claim, strategy, governance rule, or material selection, port its evidence chain into `dev/PROJECT_DECISIONS.md` using that file's research-derived decision format before collapsing the log. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
|
|
139
|
+
|
|
140
|
+
(b) Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline when `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section (e.g. `## Confirmed Decisions`, `## Decisions`, `## 已定案決策`) with a numbered list of ≥ 30 entries. If triggered, split the oldest entries, retaining the most recent 8–22 in the handoff hot tier, into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first.
|
|
141
|
+
|
|
142
|
+
(c) Append to `dev/PROJECT_DECISIONS.md` immediately, or at closeout, when the current session includes substantive task evolution, a multi-option architectural trade-off with recorded rationale, a cross-session accumulated pattern, or a user retrospective question. Use `## Evolution Timeline`, `## Architecture Choices`, or `## Insights & Learnings` as appropriate. If the decision is research-derived, use that file's evidence-chain format so the source, summary, inference, decision impact, and uncertainty survive future compression.
|
|
143
|
+
|
|
144
|
+
(d) Run a full long-term maintenance pass every 10 closeouts as a backstop, even if no trigger seems obvious. Count closeouts from the main `dev/SESSION_LOG.md` entries plus archive index entry counts when an archive exists; if the count cannot be determined confidently, treat the current N=10 boundary as the backstop trigger.
|
|
145
|
+
|
|
146
|
+
If none of the hard triggers, semantic triggers, or 10-closeout backstop applies, write a one-line no-op reason and do not perform full long-term maintenance. This keeps routine closeout fast while still preventing silent drift.
|
|
140
147
|
|
|
141
148
|
Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
|
|
142
149
|
|
|
143
|
-
Use this closeout card:
|
|
144
|
-
|
|
145
|
-
Use the same display version rule as startup: take the version from `dev/PROJECT_INDEX.md` `## Stack` row `Agent Handoff Kit template version`, print it as `vX.Y.Z`, and fall back to `version unverified` only when it cannot be verified. Never print the literal placeholder `v<version>`.
|
|
146
|
-
|
|
147
|
-
```text
|
|
148
|
-
/\_/\ Agent Handoff Kit v<version>
|
|
150
|
+
Use this closeout card:
|
|
151
|
+
|
|
152
|
+
Use the same display version rule as startup: take the version from `dev/PROJECT_INDEX.md` `## Stack` row `Agent Handoff Kit template version`, print it as `vX.Y.Z`, and fall back to `version unverified` only when it cannot be verified. Never print the literal placeholder `v<version>`.
|
|
153
|
+
|
|
154
|
+
```text
|
|
155
|
+
/\_/\ Agent Handoff Kit v<version>
|
|
149
156
|
( -.- ) handoff saved
|
|
150
157
|
> ^ <
|
|
151
158
|
|
|
@@ -155,11 +162,11 @@ Use the same display version rule as startup: take the version from `dev/PROJECT
|
|
|
155
162
|
⚠️ Boundary: <important boundary or none>
|
|
156
163
|
```
|
|
157
164
|
|
|
158
|
-
In `dev/SESSION_HANDOFF.md`, immediately before the fenced `Next Session Opening Message` content, write:
|
|
159
|
-
|
|
160
|
-
```text
|
|
161
|
-
📋 Next session: agent-managed startup content below
|
|
162
|
-
```
|
|
165
|
+
In `dev/SESSION_HANDOFF.md`, immediately before the fenced `Next Session Opening Message` content, write:
|
|
166
|
+
|
|
167
|
+
```text
|
|
168
|
+
📋 Next session: agent-managed startup content below
|
|
169
|
+
```
|
|
163
170
|
|
|
164
171
|
Record only work actually performed in the current session. Do not copy old completed work forward as new work.
|
|
165
172
|
`dev/SESSION_HANDOFF.md` carries continuity. `dev/SESSION_LOG.md` carries recent evidence. Archive old detail only when needed; do not create an archive directory by default.
|
|
@@ -173,9 +180,9 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
|
|
|
173
180
|
|
|
174
181
|
When a task references external tools (Notion / Google Drive / Slack / Linear / GitHub / Dropbox / HubSpot / Atlassian / etc.) or `dev/PROJECT_INDEX.md` `## Installed Integrations` is non-empty, load `dev/rules/integrations.md` together with the relevant domain pack. The integrations pack covers Connector-first defaults, credential separation, multi-layer source-of-truth architecture, and cross-session resilience for declared integrations.
|
|
175
182
|
|
|
176
|
-
After the task, apply the Persistence Gate in Section 2.1. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
|
|
177
|
-
|
|
178
|
-
If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs the Section 2.1 persistence-gate decision before the task is complete.
|
|
183
|
+
After the task, apply the Persistence Gate in Section 2.1. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
|
|
184
|
+
|
|
185
|
+
If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs the Section 2.1 persistence-gate decision before the task is complete.
|
|
179
186
|
|
|
180
187
|
## Core Complexity Rule
|
|
181
188
|
|
|
@@ -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
|