@adamchanadam/agent-handoff-kit 0.3.52 → 0.3.54
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/LICENSE +21 -21
- package/README.en.md +4 -4
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +4165 -7153
- package/bin/installed-file-contract.mjs +11 -11
- package/bin/migration-baselines/official-origin-catalog.json +381 -1
- package/bin/prompt-mirror-core.mjs +84 -84
- package/bin/upgrade-inventory.mjs +192 -463
- package/package.json +1 -1
- package/packs/agent-governance.md +103 -103
- package/packs/closeout.md +5 -5
- package/packs/coding.md +28 -28
- package/packs/integrations.md +7 -7
- package/packs/knowledge.md +1 -1
- package/packs/research.md +30 -30
- package/runtime-core/AGENTS.core.md +12 -12
- package/runtime-core/CLAUDE.md +13 -13
- package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
- package/runtime-core/GEMINI.md +17 -17
- package/runtime-core/PROJECT_DECISIONS.md +43 -43
- package/runtime-core/PROJECT_INDEX.md +5 -5
- package/runtime-core/SESSION_HANDOFF.md +1 -1
- package/runtime-core/SESSION_LOG.md +35 -35
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
- package/bin/semantic-candidate.mjs +0 -594
package/runtime-core/GEMINI.md
CHANGED
|
@@ -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.
|
|
9
|
+
| Agent Handoff Kit template version | 0.3.54 | current template version |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|
|
@@ -39,7 +39,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
39
39
|
| Test suite | TBD | TBD |
|
|
40
40
|
| Runbook | TBD | TBD |
|
|
41
41
|
| Public docs | TBD | TBD |
|
|
42
|
-
|
|
|
42
|
+
| Durable artifact review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating docs, generated outputs, specs, runbooks, checklists, research notes, or other durable artifacts, classify each file as indexed / synced / temporary / one-time evidence before completion; doctor validates explicit Kit contracts and formal typed user-rule paths only, not arbitrary project artifacts |
|
|
43
43
|
|
|
44
44
|
## Fact Base
|
|
45
45
|
|
|
@@ -113,8 +113,8 @@ Do not store credential values or machine-private paths here. Local machine-only
|
|
|
113
113
|
|
|
114
114
|
| Check | Command | Run before | Last verified |
|
|
115
115
|
|---|---|---|---|
|
|
116
|
-
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout /
|
|
117
|
-
| Project governance check | Check newly created
|
|
116
|
+
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / Kit contract health / explicit registered-path checks | package latest |
|
|
117
|
+
| Project governance check | Check newly created durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. This is an AI responsibility, not a root-discovery doctor scan. | closeout / durable file changes | unverified until project-specific command exists |
|
|
118
118
|
|
|
119
119
|
## Workspace Identity
|
|
120
120
|
|
|
@@ -136,7 +136,7 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
136
136
|
| UI behavior | TBD | build + visual/manual check |
|
|
137
137
|
| Data model | TBD | migration/checks |
|
|
138
138
|
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
139
|
-
|
|
|
139
|
+
| Durable artifacts | docs, generated outputs, project-specific reference folders, specs, runbooks, checklists, research notes | classify as indexed / synced / temporary / one-time evidence when created or modified by the AI; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable |
|
|
140
140
|
| Closeout/startup contract | `AGENTS.md`, `dev/rules/closeout.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | hot-path reads stay minimal; lifecycle state agrees; log has no full prompt; prompt mirror regenerated from handoff at closeout |
|
|
141
141
|
|
|
142
142
|
## External Services
|
|
@@ -156,5 +156,5 @@ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Tr
|
|
|
156
156
|
|
|
157
157
|
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
158
158
|
|
|
159
|
-
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
|
|
159
|
+
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
|
|
160
160
|
```
|
|
@@ -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
|
+
````
|
|
@@ -2,4 +2,4 @@ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Tr
|
|
|
2
2
|
|
|
3
3
|
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
4
4
|
|
|
5
|
-
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
|
|
5
|
+
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
|