@adamchanadam/agent-handoff-kit 0.3.38 → 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.
@@ -0,0 +1,72 @@
1
+ # Closeout Pack
2
+
3
+ ## Scope
4
+
5
+ This pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.
6
+
7
+ ## Required Reads
8
+
9
+ Read the current `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.
10
+
11
+ ## Write Contract
12
+
13
+ Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.
14
+
15
+ - Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.
16
+ - Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.
17
+ - File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.
18
+ - Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.
19
+ - Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.
20
+ - Reusable procedures belong in the relevant pack, registered reference, or QA check.
21
+ - `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.
22
+
23
+ Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records that the mirror was regenerated and verified, plus an evidence reference when useful.
24
+
25
+ ## Full Closeout
26
+
27
+ 1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then rewrite or explicitly confirm every closeout-reconciled section.
28
+ 2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
29
+ The bundled doctor is a mechanical floor for obvious overlap and unresolved fields; it cannot prove that renamed or paraphrased work is semantically consistent. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to doctor.
30
+ 3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
31
+ 4. Complete the persistence-routing and handoff-sufficiency fields. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history.
32
+ 5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.
33
+ 6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
34
+ 7. Record the actual root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization.
35
+ 8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.
36
+ 9. Run the short maintenance trigger check below and record its result in the log.
37
+ 10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.
38
+ 11. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the sole fenced handoff opening-message block. Run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.
39
+ 12. Run available project closeout / doctor checks. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
40
+
41
+ ## Maintenance Trigger Check
42
+
43
+ Every full closeout runs this short check; full maintenance runs only when triggered.
44
+
45
+ - SESSION_LOG: trigger when the main log reaches at least 11 entries, exceeds 1500 lines, or the 10-closeout backstop is due. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md`. Port unique narrative before collapsing it.
46
+ - PROJECT_DECISIONS: trigger when a decisions-like handoff section has at least 30 entries; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive. Also write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.
47
+ - Backstop: every 10 closeouts, run the full long-term maintenance pass even when no semantic trigger is obvious. If the count cannot be determined confidently at the boundary, treat the backstop as due.
48
+
49
+ If no trigger applies, record one no-op reason. Handoff carries continuity; log and project decisions carry trace and long-term narrative.
50
+
51
+ ## Opening Message And Card
52
+
53
+ The handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.
54
+
55
+ Use a verified version already present in the closeout reads; otherwise show `version unverified`. Never print the literal placeholder `v<version>`.
56
+
57
+ ```text
58
+ /\_/\ Agent Handoff Kit v<version>
59
+ ( -.- ) handoff saved
60
+ > ^ <
61
+
62
+ ✅ Done: <completed summary>
63
+ 🔎 QC: <validation summary>
64
+ 📌 Handoff: opening message ready
65
+ ⚠️ Boundary: <important boundary or none>
66
+ ```
67
+
68
+ Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. Do not hand-compose a third stateful prompt in the final response.
69
+
70
+ ## Stop Conditions
71
+
72
+ Do not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.
package/packs/coding.md CHANGED
@@ -1,28 +1,28 @@
1
- # Coding Pack
2
-
3
- ## Scope
4
-
5
- Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
-
7
- ## Load When
8
-
9
- - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
- - The task depends on framework, runtime, dependency, or API behavior.
11
-
12
- ## Rules
13
-
14
- 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
- 2. Inspect relevant source, tests, configs, and docs before changing code.
16
- 3. Prefer project-local patterns and helpers over new abstractions.
17
- 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
- 5. Preserve unrelated user changes.
19
-
20
- ## Checks
21
-
22
- - Run the narrowest relevant test, build, lint, or typecheck available.
23
- - If a check cannot run, record why and what remains unverified.
24
- - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
-
26
- ## Closeout
27
-
28
- Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
1
+ # Coding Pack
2
+
3
+ ## Scope
4
+
5
+ Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
+
7
+ ## Load When
8
+
9
+ - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
+ - The task depends on framework, runtime, dependency, or API behavior.
11
+
12
+ ## Rules
13
+
14
+ 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
+ 2. Inspect relevant source, tests, configs, and docs before changing code.
16
+ 3. Prefer project-local patterns and helpers over new abstractions.
17
+ 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
+ 5. Preserve unrelated user changes.
19
+
20
+ ## Checks
21
+
22
+ - Run the narrowest relevant test, build, lint, or typecheck available.
23
+ - If a check cannot run, record why and what remains unverified.
24
+ - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
+
26
+ ## Closeout
27
+
28
+ Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
@@ -1,30 +1,30 @@
1
- # Communication Pack
2
-
3
- ## Scope
4
-
5
- Use for reply format, language behavior, output schema, user-facing explanation, and cross-agent handoff wording.
6
-
7
- ## Load When
8
-
9
- - User requests a specific response format, language, style, report, review, or schema.
10
- - The task changes public-facing instructions or AI-facing reply discipline.
11
-
12
- ## Rules
13
-
14
- 1. Match the user's language unless a project file requires another language.
15
- 2. Lead with decisions, findings, or results before background.
16
- 3. Mark assumptions and unverified facts.
17
- 4. Keep operational instructions copy-paste-ready when they are meant for future sessions.
18
- 5. Avoid exposing internal process unless it helps the user act.
19
- 6. Give a clear recommended next step whenever the user needs to continue. If there is one best path, state it directly with a short reason. Offer two or three choices only when the user truly must decide; mark the recommended choice and do not turn an already-made technical judgment into an open question.
20
-
21
- ## Checks
22
-
23
- - Verify required headings, schema fields, or language split.
24
- - Check public README or docs if user-facing behavior changed.
25
- - Confirm handoff/opening messages are complete and root-specific when needed.
26
- - Confirm user-facing next-step wording names the recommended action and reason when a continuation is needed.
27
-
28
- ## Closeout
29
-
30
- Record any durable response-format decisions and where they were persisted.
1
+ # Communication Pack
2
+
3
+ ## Scope
4
+
5
+ Use for reply format, language behavior, output schema, user-facing explanation, and cross-agent handoff wording.
6
+
7
+ ## Load When
8
+
9
+ - User requests a specific response format, language, style, report, review, or schema.
10
+ - The task changes public-facing instructions or AI-facing reply discipline.
11
+
12
+ ## Rules
13
+
14
+ 1. Match the user's language unless a project file requires another language.
15
+ 2. Lead with decisions, findings, or results before background.
16
+ 3. Mark assumptions and unverified facts.
17
+ 4. Keep operational instructions copy-paste-ready when they are meant for future sessions.
18
+ 5. Avoid exposing internal process unless it helps the user act.
19
+ 6. Give a clear recommended next step whenever the user needs to continue. If there is one best path, state it directly with a short reason. Offer two or three choices only when the user truly must decide; mark the recommended choice and do not turn an already-made technical judgment into an open question.
20
+
21
+ ## Checks
22
+
23
+ - Verify required headings, schema fields, or language split.
24
+ - Check public README or docs if user-facing behavior changed.
25
+ - Confirm handoff/opening messages are complete and root-specific when needed.
26
+ - Confirm user-facing next-step wording names the recommended action and reason when a continuation is needed.
27
+
28
+ ## Closeout
29
+
30
+ Record any durable response-format decisions and where they were persisted.