@adamchanadam/agent-handoff-kit 0.3.46 → 0.3.47

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/research.md CHANGED
@@ -1,30 +1,30 @@
1
- # Research Pack
2
-
3
- ## Scope
4
-
5
- Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
6
-
7
- ## Load When
8
-
9
- - User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
10
- - The topic may have changed recently or needs precise attribution.
11
-
12
- ## Rules
13
-
14
- 1. Prefer primary sources, official docs, papers, standards, or direct data when available.
15
- 2. Separate verified facts, source summaries, and inference.
16
- 3. Record dates for time-sensitive facts.
17
- 4. Do not overstate confidence when sources conflict or coverage is thin.
18
- 5. Keep source quotes short and cite where evidence came from.
19
-
20
- ## Checks
21
-
22
- - Confirm source relevance, date, and authority.
23
- - Cross-check important claims with more than one source when practical.
24
- - Record open questions or unverified claims.
25
-
26
- ## Closeout
27
-
28
- Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
29
-
30
- If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
1
+ # Research Pack
2
+
3
+ ## Scope
4
+
5
+ Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
6
+
7
+ ## Load When
8
+
9
+ - User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
10
+ - The topic may have changed recently or needs precise attribution.
11
+
12
+ ## Rules
13
+
14
+ 1. Prefer primary sources, official docs, papers, standards, or direct data when available.
15
+ 2. Separate verified facts, source summaries, and inference.
16
+ 3. Record dates for time-sensitive facts.
17
+ 4. Do not overstate confidence when sources conflict or coverage is thin.
18
+ 5. Keep source quotes short and cite where evidence came from.
19
+
20
+ ## Checks
21
+
22
+ - Confirm source relevance, date, and authority.
23
+ - Cross-check important claims with more than one source when practical.
24
+ - Record open questions or unverified claims.
25
+
26
+ ## Closeout
27
+
28
+ Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
29
+
30
+ If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
@@ -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.
@@ -1,43 +1,43 @@
1
- # Project Decisions Log
2
-
3
- This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
-
5
- Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
-
7
- The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
-
9
- Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
-
11
- ```text
12
- - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
- ```
14
-
15
- The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
-
17
- This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
-
19
- ---
20
-
21
- ## Evolution Timeline
22
-
23
- Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
-
25
- (empty)
26
-
27
- ## Decisions Archive
28
-
29
- Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
30
-
31
- (empty)
32
-
33
- ## Architecture Choices
34
-
35
- Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
-
37
- (empty)
38
-
39
- ## Insights & Learnings
40
-
41
- Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
-
43
- (empty)
1
+ # Project Decisions Log
2
+
3
+ This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
+
5
+ Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
+
7
+ The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
+
9
+ Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
+
11
+ ```text
12
+ - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
+ ```
14
+
15
+ The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
+
17
+ This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
+
19
+ ---
20
+
21
+ ## Evolution Timeline
22
+
23
+ Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
+
25
+ (empty)
26
+
27
+ ## Decisions Archive
28
+
29
+ Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
30
+
31
+ (empty)
32
+
33
+ ## Architecture Choices
34
+
35
+ Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
+
37
+ (empty)
38
+
39
+ ## Insights & Learnings
40
+
41
+ Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
+
43
+ (empty)
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.3.46 | current template version |
9
+ | Agent Handoff Kit template version | 0.3.47 | current template version |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |
@@ -1,35 +1,35 @@
1
- # Session Log
2
-
3
- <!-- ack:section:session-log-preamble -->
4
-
5
- > **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
6
-
7
- Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
-
9
- This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
-
11
- Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
12
-
13
- Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
-
15
- <!-- ack:section:session-log-entry-template -->
16
-
17
- ## Entry Template
18
-
19
- ````markdown
20
- <!-- ack:log-entry:start -->
21
- ## <YYYY-MM-DD> — <short session title>
22
-
23
- - **ID:** <agent_or_session_id>
24
- - **Summary:** <one sentence>
25
- - **Changed:** <files changed, or none>
26
- - **Done:** <work completed this session>
27
- - **QC:** <checks run and results, or why not run>
28
- - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
29
- - **Sync:** <doc/external sync status>
30
- - **Pending:** <next work>
31
- - **Risks:** <known risks or none>
32
- - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
- - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
34
- <!-- ack:log-entry:end -->
35
- ````
1
+ # Session Log
2
+
3
+ <!-- ack:section:session-log-preamble -->
4
+
5
+ > **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
6
+
7
+ Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
+
9
+ This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
+
11
+ Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
12
+
13
+ Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
+
15
+ <!-- ack:section:session-log-entry-template -->
16
+
17
+ ## Entry Template
18
+
19
+ ````markdown
20
+ <!-- ack:log-entry:start -->
21
+ ## <YYYY-MM-DD> — <short session title>
22
+
23
+ - **ID:** <agent_or_session_id>
24
+ - **Summary:** <one sentence>
25
+ - **Changed:** <files changed, or none>
26
+ - **Done:** <work completed this session>
27
+ - **QC:** <checks run and results, or why not run>
28
+ - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
29
+ - **Sync:** <doc/external sync status>
30
+ - **Pending:** <next work>
31
+ - **Risks:** <known risks or none>
32
+ - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
+ - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
34
+ <!-- ack:log-entry:end -->
35
+ ````