@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.
- package/LICENSE +21 -21
- package/README.md +5 -5
- package/bin/agent-handoff-kit.mjs +1570 -752
- package/bin/migration-baselines/v0.3.38/integrations.md +235 -0
- package/bin/migration-baselines/v0.3.38/onboarding.md +201 -0
- package/bin/migration-baselines/v0.3.38/safety.md +46 -0
- package/bin/prompt-mirror-core.mjs +187 -114
- package/package.json +20 -31
- package/packs/agent-governance.md +103 -103
- package/packs/closeout.md +72 -0
- package/packs/coding.md +28 -28
- package/packs/communication.md +30 -30
- package/packs/integrations.md +251 -235
- package/packs/knowledge.md +5 -5
- package/packs/onboarding.md +214 -201
- package/packs/release.md +28 -28
- package/packs/research.md +30 -30
- package/packs/safety.md +29 -27
- package/packs/writing.md +36 -36
- package/runtime-core/AGENTS.core.md +61 -139
- 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 +10 -8
- package/runtime-core/RULE_PACKS.md +12 -11
- package/runtime-core/SESSION_HANDOFF.md +35 -44
- package/runtime-core/SESSION_LOG.md +35 -57
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +5 -16
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.
|
|
9
|
+
| Agent Handoff Kit template version | 0.3.40 | implementation candidate; not yet published |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|
|
@@ -21,11 +21,12 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
21
21
|
| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
|
|
22
22
|
| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
|
|
23
23
|
| `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
|
|
24
|
-
| `START_NEXT_SESSION_PROMPT.txt` |
|
|
24
|
+
| `START_NEXT_SESSION_PROMPT.txt` | portable generated mirror of the handoff opening-message block; `dev/SESSION_HANDOFF.md` remains authoritative | fallback when the next agent is not yet operating in this root; not an additional local startup read |
|
|
25
25
|
| `src/` | application source | coding task |
|
|
26
26
|
| `tests/` | tests | coding/QC |
|
|
27
27
|
| `docs/` | user or product docs | doc/public behavior change |
|
|
28
|
-
| `dev/` | governance state | startup
|
|
28
|
+
| `dev/` | governance state | read the handoff at startup; other files are task-routed or closeout-routed |
|
|
29
|
+
| `dev/rules/closeout.md` | full closeout contract | clear end-of-session or handoff intent only |
|
|
29
30
|
| `TBD` | local source-of-truth files | before tasks that depend on project facts |
|
|
30
31
|
| `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
|
|
31
32
|
|
|
@@ -38,7 +39,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
38
39
|
| Test suite | TBD | TBD |
|
|
39
40
|
| Runbook | TBD | TBD |
|
|
40
41
|
| Public docs | TBD | TBD |
|
|
41
|
-
| Generated
|
|
42
|
+
| Generated Markdown review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated Markdown outputs, specs, runbooks, checklists, or research notes, classify each file as indexed / synced / temporary / one-time evidence before completion; other durable formats require human review because doctor scans Markdown only |
|
|
42
43
|
|
|
43
44
|
## Fact Base
|
|
44
45
|
|
|
@@ -60,7 +61,7 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
60
61
|
|
|
61
62
|
> **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.
|
|
62
63
|
|
|
63
|
-
> Purpose:
|
|
64
|
+
> Purpose: tasks that use external tools read this section to understand declared capabilities and project roles. Declarations persist across sessions. A new session does not probe this table merely because it exists. `TBD`, examples, blanks, and placeholder-only rows are not installed integrations. Every real entry includes `Declared` and `Last Verified` so capability assumptions can be checked immediately before use.
|
|
64
65
|
|
|
65
66
|
### Connectors
|
|
66
67
|
|
|
@@ -106,13 +107,14 @@ Do not store credential values or machine-private paths here. Local machine-only
|
|
|
106
107
|
| Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
|
|
107
108
|
|---|---|---|---|---|---|
|
|
108
109
|
| TBD | TBD | TBD | TBD | TBD | TBD |
|
|
110
|
+
| Local HTML / app browser validation | TBD, for example project runbook or official browser-tool docs | Before validating local HTML, static app, generated guide, screenshot, click flow, or visual QA | TBD, include source and date | Prefer short-lived loopback localhost service when `file://` is blocked; record click/text/screenshot evidence and cleanup result; do not mutate user browser profiles or extension state | TBD |
|
|
109
111
|
|
|
110
112
|
## Local QC Commands
|
|
111
113
|
|
|
112
114
|
| Check | Command | Run before | Last verified |
|
|
113
115
|
|---|---|---|---|
|
|
114
116
|
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
|
|
115
|
-
| Project governance check | Check newly created Markdown
|
|
117
|
+
| Project governance check | Check newly created Markdown against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. Review non-Markdown durable outputs manually. | closeout / durable file changes | unverified until project-specific command exists |
|
|
116
118
|
|
|
117
119
|
## Workspace Identity
|
|
118
120
|
|
|
@@ -134,8 +136,8 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
134
136
|
| UI behavior | TBD | build + visual/manual check |
|
|
135
137
|
| Data model | TBD | migration/checks |
|
|
136
138
|
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
137
|
-
| Generated Markdown
|
|
138
|
-
| Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` |
|
|
139
|
+
| Generated Markdown | `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; review other formats manually |
|
|
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 |
|
|
139
141
|
|
|
140
142
|
## External Services
|
|
141
143
|
|
|
@@ -4,21 +4,22 @@ Read only the packs needed for the current task.
|
|
|
4
4
|
|
|
5
5
|
| Task signal | Pack | Purpose |
|
|
6
6
|
|---|---|---|
|
|
7
|
-
|
|
|
7
|
+
| Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
|
|
8
|
+
| Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install or "I just installed" is eligibility context, not a forced route. `Start Agent Handoff` / "開工" is continuity. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or no executable objective remains |
|
|
8
9
|
| Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
|
|
9
10
|
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
10
11
|
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
11
12
|
| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
|
|
12
|
-
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
13
|
-
| Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
14
|
-
| Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
|
|
15
|
-
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
16
|
-
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
17
|
-
|
|
|
18
|
-
| Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation;
|
|
19
|
-
| External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
|
|
20
|
-
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
13
|
+
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
14
|
+
| Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | <!-- ack:route:governance-bridge --> connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
15
|
+
| Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | <!-- ack:route:long-term-governance --> classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
|
|
16
|
+
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
17
|
+
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
18
|
+
| A task that actually uses an external Connector / MCP / Plugin / Skill; a handoff that declares one as a current-task dependency; or an explicit integration health check | `dev/rules/integrations.md` | <!-- ack:route:integration-use --> capability verification immediately before use, credential separation, source-of-truth boundaries, fallback, and cross-session resilience; registry placeholders alone do not load or probe |
|
|
19
|
+
| Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / local HTML validation / file:// blocked / `file://` blocked / localhost fallback / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | <!-- ack:route:runtime-tool --> verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; for local HTML / app validation, a blocked `file://` surface must route to a registered operation reference or short-lived localhost fallback before declaring blocked; preserve ownership and cleanup boundaries |
|
|
20
|
+
| External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | <!-- ack:route:resource-closeout --> ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
|
|
21
|
+
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
21
22
|
|
|
22
23
|
## Routing Rule
|
|
23
24
|
|
|
24
|
-
Load the minimum set. If uncertain, load the narrower pack first. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack
|
|
25
|
+
Load the minimum set. If uncertain, load the narrower pack first. Pack selection is normally silent; state it only when it changes risk or user action. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack. Packs can add stricter rules, but cannot weaken core safety or continuity.
|
|
@@ -12,7 +12,7 @@ Stable facts that should survive across sessions. Update only when they change,
|
|
|
12
12
|
3. Governance model: TBD
|
|
13
13
|
4. Source-of-truth ownership: TBD
|
|
14
14
|
5. Release / publish boundary: TBD
|
|
15
|
-
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations`
|
|
15
|
+
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
|
|
16
16
|
|
|
17
17
|
<!-- ack:section:closeout-reconciled-state -->
|
|
18
18
|
## Closeout-Reconciled State
|
|
@@ -26,6 +26,8 @@ This is the current-state area. At every full closeout, rewrite or explicitly co
|
|
|
26
26
|
2. Product/system state: TBD
|
|
27
27
|
3. Governance state: TBD
|
|
28
28
|
4. Source-of-truth notes: TBD
|
|
29
|
+
<!-- ack:field:first-use-guidance-state -->
|
|
30
|
+
5. First-use guidance state: eligible
|
|
29
31
|
|
|
30
32
|
<!-- ack:section:task-understanding-summary -->
|
|
31
33
|
## Task Understanding Summary
|
|
@@ -53,12 +55,12 @@ Record only work actually completed in the current session.
|
|
|
53
55
|
|
|
54
56
|
1. TBD
|
|
55
57
|
|
|
56
|
-
<!-- ack:section:next-priorities -->
|
|
57
|
-
## Next Priorities
|
|
58
|
-
|
|
59
|
-
Recommended next step: TBD — reason: TBD
|
|
60
|
-
|
|
61
|
-
1. TBD
|
|
58
|
+
<!-- ack:section:next-priorities -->
|
|
59
|
+
## Next Priorities
|
|
60
|
+
|
|
61
|
+
Recommended next step: TBD — reason: TBD
|
|
62
|
+
|
|
63
|
+
1. TBD
|
|
62
64
|
|
|
63
65
|
<!-- ack:section:next-task-required-reading -->
|
|
64
66
|
## Next Task Required Reading
|
|
@@ -109,27 +111,27 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
109
111
|
- Reconciled at: TBD
|
|
110
112
|
<!-- ack:field:state-sections-rewritten-or-confirmed -->
|
|
111
113
|
- State sections rewritten or confirmed current: TBD
|
|
112
|
-
<!-- ack:field:stale-snapshots-left -->
|
|
113
|
-
- Stale snapshots left in this handoff: TBD
|
|
114
|
-
<!-- ack:field:lifecycle-conflicts-resolved -->
|
|
115
|
-
- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
|
|
116
|
-
<!-- ack:field:persistence-routing-checked -->
|
|
117
|
-
- Persistence routing checked: TBD
|
|
118
|
-
<!-- ack:field:recommended-next-step-explicit -->
|
|
119
|
-
- Recommended next step is explicit and reasoned: TBD
|
|
120
|
-
<!-- ack:field:opening-message-matches-current-state -->
|
|
121
|
-
- Opening message matches current state: TBD
|
|
122
|
-
<!-- ack:field:next-ai-can-continue -->
|
|
123
|
-
- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
|
|
124
|
-
|
|
125
|
-
If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
|
|
126
|
-
|
|
127
|
-
Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message
|
|
114
|
+
<!-- ack:field:stale-snapshots-left -->
|
|
115
|
+
- Stale snapshots left in this handoff: TBD
|
|
116
|
+
<!-- ack:field:lifecycle-conflicts-resolved -->
|
|
117
|
+
- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
|
|
118
|
+
<!-- ack:field:persistence-routing-checked -->
|
|
119
|
+
- Persistence routing checked: TBD
|
|
120
|
+
<!-- ack:field:recommended-next-step-explicit -->
|
|
121
|
+
- Recommended next step is explicit and reasoned: TBD
|
|
122
|
+
<!-- ack:field:opening-message-matches-current-state -->
|
|
123
|
+
- Opening message matches current state: TBD
|
|
124
|
+
<!-- ack:field:next-ai-can-continue -->
|
|
125
|
+
- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
|
|
126
|
+
|
|
127
|
+
If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
|
|
128
|
+
|
|
129
|
+
Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message` as full content, including renamed or paraphrased work. 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. Doctor catches only mechanical contradictions and unresolved fields; its green result is not semantic proof. Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.
|
|
128
130
|
|
|
129
131
|
<!-- ack:section:handoff-sufficiency-check -->
|
|
130
132
|
## Handoff Sufficiency Check
|
|
131
133
|
|
|
132
|
-
Can the next AI continue from `AGENTS.md`, this handoff,
|
|
134
|
+
Can the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?
|
|
133
135
|
|
|
134
136
|
Answer: TBD
|
|
135
137
|
If no, update this handoff before closeout.
|
|
@@ -139,25 +141,14 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
|
|
|
139
141
|
<!-- ack:section:next-session-opening-message -->
|
|
140
142
|
## Next Session Opening Message
|
|
141
143
|
|
|
142
|
-
This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
|
|
143
|
-
|
|
144
|
-
📋 Next session: agent-managed startup content below
|
|
144
|
+
This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
|
|
145
|
+
|
|
146
|
+
📋 Next session: agent-managed startup content below
|
|
145
147
|
|
|
146
148
|
```text
|
|
147
|
-
Work in <absolute project root>.
|
|
148
|
-
|
|
149
|
-
Read
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
4. dev/PROJECT_INDEX.md
|
|
154
|
-
5. dev/RULE_PACKS.md
|
|
155
|
-
|
|
156
|
-
Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
|
|
157
|
-
|
|
158
|
-
If this root does not match the expected project root, stop and ask for confirmation.
|
|
159
|
-
|
|
160
|
-
This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
|
|
161
|
-
|
|
162
|
-
Before changing anything, tell me the current state and your recommended next step.
|
|
163
|
-
```
|
|
149
|
+
Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
|
|
150
|
+
|
|
151
|
+
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.
|
|
152
|
+
|
|
153
|
+
Resume the current objective. If my message or the handoff already gives an executable task, begin its first safe action in this response. 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.
|
|
154
|
+
```
|
|
@@ -1,57 +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
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
📋 Next session: agent-managed startup content below
|
|
37
|
-
|
|
38
|
-
```text
|
|
39
|
-
Work in <absolute project root>.
|
|
40
|
-
|
|
41
|
-
Read in order:
|
|
42
|
-
1. AGENTS.md
|
|
43
|
-
2. dev/SESSION_HANDOFF.md
|
|
44
|
-
3. dev/SESSION_LOG.md
|
|
45
|
-
4. dev/PROJECT_INDEX.md
|
|
46
|
-
5. dev/RULE_PACKS.md
|
|
47
|
-
|
|
48
|
-
Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
|
|
49
|
-
|
|
50
|
-
If this root does not match the expected project root, stop and ask for confirmation.
|
|
51
|
-
|
|
52
|
-
This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
|
|
53
|
-
|
|
54
|
-
Before changing anything, tell me the current state and your recommended next step.
|
|
55
|
-
```
|
|
56
|
-
<!-- ack:log-entry:end -->
|
|
57
|
-
````
|
|
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,16 +1,5 @@
|
|
|
1
|
-
Work in <absolute project root>.
|
|
2
|
-
|
|
3
|
-
Read
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
3. dev/SESSION_LOG.md
|
|
7
|
-
4. dev/PROJECT_INDEX.md
|
|
8
|
-
5. dev/RULE_PACKS.md
|
|
9
|
-
|
|
10
|
-
Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
|
|
11
|
-
|
|
12
|
-
If this root does not match the expected project root, stop and ask for confirmation.
|
|
13
|
-
|
|
14
|
-
This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
|
|
15
|
-
|
|
16
|
-
Before changing anything, tell me the current state and your recommended next step.
|
|
1
|
+
Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
|
|
2
|
+
|
|
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
|
+
|
|
5
|
+
Resume the current objective. If my message or the handoff already gives an executable task, begin its first safe action in this response. 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.
|