@adamchanadam/agent-handoff-kit 0.3.40 → 0.3.41
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 +1 -1
- package/bin/agent-handoff-kit.mjs +331 -121
- package/bin/installed-file-contract.mjs +45 -0
- package/bin/migration-baselines/official-origin-catalog.json +9828 -0
- package/bin/official-origin-catalog.mjs +192 -0
- package/bin/prompt-mirror-core.mjs +84 -84
- package/package.json +32 -20
- package/packs/agent-governance.md +103 -103
- package/packs/closeout.md +72 -72
- package/packs/coding.md +28 -28
- package/packs/communication.md +30 -30
- package/packs/integrations.md +251 -251
- package/packs/knowledge.md +5 -5
- package/packs/onboarding.md +214 -214
- package/packs/release.md +28 -28
- package/packs/research.md +30 -30
- package/packs/safety.md +29 -29
- package/packs/writing.md +36 -36
- package/runtime-core/AGENTS.core.md +112 -112
- 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 +1 -1
- package/runtime-core/RULE_PACKS.md +14 -14
- package/runtime-core/SESSION_HANDOFF.md +36 -36
- package/runtime-core/SESSION_LOG.md +35 -35
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +5 -5
- package/bin/migration-baselines/v0.3.38/integrations.md +0 -235
- package/bin/migration-baselines/v0.3.38/onboarding.md +0 -201
- package/bin/migration-baselines/v0.3.38/safety.md +0 -46
|
@@ -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.41 | implementation candidate; not yet published |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|
|
@@ -2,24 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
Read only the packs needed for the current task.
|
|
4
4
|
|
|
5
|
-
| Task signal | Pack | Purpose |
|
|
6
|
-
|---|---|---|
|
|
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 |
|
|
5
|
+
| Task signal | Pack | Purpose |
|
|
6
|
+
|---|---|---|
|
|
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 |
|
|
9
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 |
|
|
10
10
|
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
11
11
|
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
12
12
|
| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
|
|
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 |
|
|
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 |
|
|
22
22
|
|
|
23
23
|
## Routing Rule
|
|
24
24
|
|
|
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.
|
|
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` 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.
|
|
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
|
|
@@ -25,9 +25,9 @@ This is the current-state area. At every full closeout, rewrite or explicitly co
|
|
|
25
25
|
1. Project root: TBD
|
|
26
26
|
2. Product/system state: TBD
|
|
27
27
|
3. Governance state: TBD
|
|
28
|
-
4. Source-of-truth notes: TBD
|
|
29
|
-
<!-- ack:field:first-use-guidance-state -->
|
|
30
|
-
5. First-use guidance state: eligible
|
|
28
|
+
4. Source-of-truth notes: TBD
|
|
29
|
+
<!-- ack:field:first-use-guidance-state -->
|
|
30
|
+
5. First-use guidance state: eligible
|
|
31
31
|
|
|
32
32
|
<!-- ack:section:task-understanding-summary -->
|
|
33
33
|
## Task Understanding Summary
|
|
@@ -55,12 +55,12 @@ Record only work actually completed in the current session.
|
|
|
55
55
|
|
|
56
56
|
1. TBD
|
|
57
57
|
|
|
58
|
-
<!-- ack:section:next-priorities -->
|
|
59
|
-
## Next Priorities
|
|
60
|
-
|
|
61
|
-
Recommended next step: TBD — reason: TBD
|
|
62
|
-
|
|
63
|
-
1. TBD
|
|
58
|
+
<!-- ack:section:next-priorities -->
|
|
59
|
+
## Next Priorities
|
|
60
|
+
|
|
61
|
+
Recommended next step: TBD — reason: TBD
|
|
62
|
+
|
|
63
|
+
1. TBD
|
|
64
64
|
|
|
65
65
|
<!-- ack:section:next-task-required-reading -->
|
|
66
66
|
## Next Task Required Reading
|
|
@@ -111,27 +111,27 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
111
111
|
- Reconciled at: TBD
|
|
112
112
|
<!-- ack:field:state-sections-rewritten-or-confirmed -->
|
|
113
113
|
- State sections rewritten or confirmed current: TBD
|
|
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.
|
|
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.
|
|
130
130
|
|
|
131
131
|
<!-- ack:section:handoff-sufficiency-check -->
|
|
132
132
|
## Handoff Sufficiency Check
|
|
133
133
|
|
|
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?
|
|
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?
|
|
135
135
|
|
|
136
136
|
Answer: TBD
|
|
137
137
|
If no, update this handoff before closeout.
|
|
@@ -141,14 +141,14 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
|
|
|
141
141
|
<!-- ack:section:next-session-opening-message -->
|
|
142
142
|
## Next Session Opening Message
|
|
143
143
|
|
|
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
|
|
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
|
|
147
147
|
|
|
148
148
|
```text
|
|
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
|
-
```
|
|
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,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
|
+
````
|
|
@@ -1,5 +1,5 @@
|
|
|
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.
|
|
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.
|
|
@@ -1,235 +0,0 @@
|
|
|
1
|
-
# Integrations Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use this pack for governance of already-installed external tool integrations: **Connectors** (official or platform-vetted MCP servers), **MCPs** (community or custom MCP servers), **Plugins** (bundles that may register skills, MCP servers, hooks, or apps), and **Skills** (`SKILL.md` instruction sets).
|
|
6
|
-
|
|
7
|
-
When a task touches external sources or external write surfaces such as Notion, Google Drive, Dropbox, Slack, Linear, GitHub, HubSpot, browsers, screenshots, DevTools, Playwright, desktop app automation, crawlers, notebooks, or local helper services, this pack makes the agent check declared integrations and tool operation references first, prefer direct runtime access when available, and fall back to manual packets only when the integration is unavailable.
|
|
8
|
-
|
|
9
|
-
This pack does not teach users how to install tools. Installation is handled by the user's AI runtime, tool vendor, or official documentation. This pack governs what happens after a tool is already installed: declaration, verification, safe use, resource lifecycle, drift handling, and cross-session continuity.
|
|
10
|
-
|
|
11
|
-
## Load When
|
|
12
|
-
|
|
13
|
-
- The task mentions Notion, Google Drive, Slack, Linear, Dropbox, HubSpot, GitHub, browser automation, UI validation, screenshot capture, Chrome, Playwright, DevTools, desktop app automation, crawlers, notebooks, local helper services, or other external tools.
|
|
14
|
-
- The user asks whether the agent can directly read or write an external system.
|
|
15
|
-
- `dev/PROJECT_INDEX.md` has a non-empty `## Installed Integrations` section.
|
|
16
|
-
- First-time onboarding asks the user to declare installed external tools.
|
|
17
|
-
- The project uses a multi-layer source-of-truth setup, for example Notion index + local source files + Google Drive reference mirrors.
|
|
18
|
-
- The user reports resource pressure, stale MCP or plugin services, browser automation left running, cache growth, or slowdown after external-tool use.
|
|
19
|
-
|
|
20
|
-
## Discipline
|
|
21
|
-
|
|
22
|
-
### 1. Credential Separation Principle
|
|
23
|
-
|
|
24
|
-
Credential values such as API keys, OAuth tokens, app secrets, and refresh tokens belong only in AI runtime secure storage, OS credential stores, tool configuration, environment indirection, or user-managed secret stores. Agent Handoff Kit files may record credential references, never credential values.
|
|
25
|
-
|
|
26
|
-
| Storage layer | Examples | What Kit files may record |
|
|
27
|
-
|---|---|---|
|
|
28
|
-
| AI runtime secure storage / Connector storage | Notion, Slack, Linear, Google Drive, Atlassian, HubSpot, or similar connectors | Storage type or connector name only |
|
|
29
|
-
| OS credential store | macOS Keychain, Windows Credential Manager, Linux secret service | `OS credential store` only |
|
|
30
|
-
| Tool config / env indirection | AI tool MCP config, plugin config, environment variable name | Config location or env var name only; never the value |
|
|
31
|
-
| User-managed secret store | Team vault or secret manager | Store type or owner only |
|
|
32
|
-
|
|
33
|
-
No file under `dev/` should contain a credential value. Enforce three rules:
|
|
34
|
-
|
|
35
|
-
1. Do not ask the user to paste credential values into chat.
|
|
36
|
-
2. If a credential-like prefix appears, redact it and warn the user to rotate the token when appropriate. Examples include `sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, and `AIza`.
|
|
37
|
-
3. Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, self-check that no credential value is being persisted. Doctor also checks `PROJECT_INDEX`, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes.
|
|
38
|
-
|
|
39
|
-
### 2. External Tool Usage Verification Gate
|
|
40
|
-
|
|
41
|
-
Agents must not use model memory, old session experience, copied examples, Connector marketing text, or guessed command shapes as the source for external-tool usage. Before first use of an external tool layer in the current task, and again before any write, destructive action, permission-sensitive action, raw API / SDK / CLI / URI call, plugin API change, or retry after `unknown tool`, `invalid arguments`, HTTP 400 / 404, permission, auth, or schema errors, verify the current usage source for that layer:
|
|
42
|
-
|
|
43
|
-
| Layer | Required current source before invocation |
|
|
44
|
-
|---|---|
|
|
45
|
-
| Connector / MCP tool | Current runtime-exposed tool name, description, and input schema. Use the tool list/schema exposed by the active AI runtime or MCP server; do not invent `mcp__*` names or arguments. |
|
|
46
|
-
| Plugin / Skill | Current plugin/skill instructions plus any registered MCP tool schema it exposes. |
|
|
47
|
-
| Raw API / SDK / CLI / URI | Current official documentation or a project-local runbook that states source, version/date, and scope. If the runbook lacks those, verify against official docs. |
|
|
48
|
-
| Local app plugin API | Official API documentation, official type definitions, official sample project, or local installed package types matching the project version. |
|
|
49
|
-
| Project-local runbook | Accept as a task source only when it records the upstream source, version/date, scope, and known limits. |
|
|
50
|
-
|
|
51
|
-
If the required source cannot be inspected, mark the tool use `blocked` or `unverified`, ask the user for the current docs/schema/runbook, or fall back to a manual packet. Do not continue by trial and error. Connector-first means schema-first for the active runtime, not memory-first.
|
|
52
|
-
|
|
53
|
-
#### Runtime-Controlled Tool Operation Variants
|
|
54
|
-
|
|
55
|
-
For browser and tool-operation work, first check `dev/PROJECT_INDEX.md` `## Tool Operation References` when present. A successful method from a previous session is reusable only when it is registered there with source, version/date, scope, known limits, and last verification.
|
|
56
|
-
|
|
57
|
-
| Variant | Examples | Required source before use |
|
|
58
|
-
|---|---|---|
|
|
59
|
-
| Browser / UI validation | Browser tool, screenshot, Chrome, DevTools, Playwright smoke test, visual QA | Active runtime browser/tool schema; registered tool operation reference; or current official docs for raw CLI/SDK use. Do not guess Chrome, Playwright, or DevTools commands. |
|
|
60
|
-
| Desktop or local app automation | Desktop app session, app plugin, local browser profile, extension-dependent workflow | Active app/plugin/tool schema or official automation API docs. Do not mutate user sessions, profiles, or extension state without confirmation. |
|
|
61
|
-
| Crawler / scraper / local helper | Firecrawl-like tools, crawler services, local helper server | Active tool schema, registered operation reference, or official docs. Respect source permissions, rate limits, and cleanup boundaries. |
|
|
62
|
-
| Notebook / data runtime | Notebook kernel, data runtime, long-lived analysis server | Active runtime/kernel schema or registered operation reference. Classify kernels and servers by ownership before cleanup. |
|
|
63
|
-
| Raw CLI / SDK / tool server | Direct command invocation, SDK script, MCP/tool server operation | Current official docs, installed package types, or registered operation reference. Mark blocked or unverified if unavailable. |
|
|
64
|
-
|
|
65
|
-
### 2.1 External Tool Resource Lifecycle
|
|
66
|
-
|
|
67
|
-
External tools must be treated as resources with ownership, not just capabilities. After using Connector, MCP, plugin, browser automation, local server, crawler, notebook, or similar external tool services, classify any opened session, process, browser context, temporary directory, cache, or helper service into one of these ownership classes:
|
|
68
|
-
|
|
69
|
-
| Ownership class | Examples | Agent action |
|
|
70
|
-
|---|---|---|
|
|
71
|
-
| Task-owned | Process, browser context, temp directory, or helper service clearly started by this task and no longer needed. Evidence may include parent-child process chain, start time, tool family, task-created path, or runtime session handle. | Close or clean up automatically through the runtime or tool's graceful shutdown API when available; OS-level termination is allowed only when ownership is clear and graceful close is unavailable or failed. |
|
|
72
|
-
| Agent-managed | Kit-managed or agent-created temp/cache under a known task workspace, with bounded path and age/size rules. | Clean automatically inside the declared boundary. Never scan or clean broad user, system, browser, package-manager, or marketplace caches through this class. |
|
|
73
|
-
| Shared / user-owned / other-agent-owned / system-level | User's normal browser, another AI agent's active browser or MCP service, global MCP service, global npm/cache directory, shared credential store, project files, OS temp root, or any process whose owner is uncertain. | Do not terminate, delete, disable, or reconfigure automatically. Report evidence and propose exact remediation for user confirmation. |
|
|
74
|
-
| Unknown | Generic `node`, `python`, `chrome`, or helper process without reliable owner evidence. | Treat as shared until proven otherwise. |
|
|
75
|
-
|
|
76
|
-
For ordinary external-tool tasks, perform a lightweight closeout check: close task-owned handles, note any known retained session, and report only meaningful residual risk. For long-running, multi-tool, MCP-heavy, browser-automation, repeated-error, or user-reported slowdown tasks, perform a fuller resource review when the runtime exposes enough data: group by tool family, count, approximate memory where available, age / start time where available, and ownership class. If process command lines or environment details may contain secrets, redact arguments and secret-like values before reporting.
|
|
77
|
-
|
|
78
|
-
The preferred cleanup order is: graceful tool/session close, then task-owned process termination, then task-owned temp cleanup. Shared or ambiguous resources require explicit user confirmation with exact process IDs or paths, tool names, expected impact, and restart path before any termination, cache deletion, tool disablement, or configuration change. Never terminate or clean up a tool resource that may belong to another AI agent running on the same machine unless ownership has been proven for the current task.
|
|
79
|
-
|
|
80
|
-
### 3. Integration Type Discipline
|
|
81
|
-
|
|
82
|
-
#### 3.1 Connectors
|
|
83
|
-
|
|
84
|
-
Connectors are ready-to-use external tool surfaces exposed by the active AI runtime. Their credentials are normally managed by runtime secure storage, OS credential storage, or connector storage.
|
|
85
|
-
|
|
86
|
-
Discipline:
|
|
87
|
-
|
|
88
|
-
- Use only runtime-exposed tools whose current name, description, and input schema have been inspected.
|
|
89
|
-
- Read back every external write before claiming success.
|
|
90
|
-
- If auth fails, surface the failure and point the user to the runtime or connector settings. Do not attempt automatic re-auth.
|
|
91
|
-
|
|
92
|
-
#### 3.2 MCPs
|
|
93
|
-
|
|
94
|
-
MCP servers may be official, community, custom, or project-local. Custom MCPs often depend on manual configuration.
|
|
95
|
-
|
|
96
|
-
Discipline:
|
|
97
|
-
|
|
98
|
-
- Use only the active runtime's exposed tool name, description, and input schema.
|
|
99
|
-
- Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `packs/safety.md`.
|
|
100
|
-
- If the server fails because of process crash, config error, or unavailable runtime state, surface the failure, recommend checking MCP config and restarting the host tool, and do not blindly retry.
|
|
101
|
-
|
|
102
|
-
#### 3.3 Plugins
|
|
103
|
-
|
|
104
|
-
Plugins are distribution bundles. A plugin may register skills, MCP servers, hooks, apps, or other runtime capabilities.
|
|
105
|
-
|
|
106
|
-
Discipline:
|
|
107
|
-
|
|
108
|
-
- Do not invoke a plugin as a separate abstraction unless the runtime exposes such an action.
|
|
109
|
-
- If a plugin provides a skill, follow the skill trigger rules.
|
|
110
|
-
- If a plugin provides an MCP server or app tool, treat it under the Connector / MCP rules above and the resource lifecycle rules in this pack.
|
|
111
|
-
|
|
112
|
-
#### 3.4 Skills
|
|
113
|
-
|
|
114
|
-
Skills are instruction overlays, usually stored as `SKILL.md`, and may be installed directly or shipped by a plugin.
|
|
115
|
-
|
|
116
|
-
Discipline:
|
|
117
|
-
|
|
118
|
-
- Invoke a skill when the user explicitly names it or when the skill's trigger conditions are clearly met.
|
|
119
|
-
- Skill instructions coexist with rule-pack discipline.
|
|
120
|
-
- If a skill conflicts with safety, governance, or closeout rules, the rule pack and core safety boundary take precedence.
|
|
121
|
-
|
|
122
|
-
### 4. Source-of-truth Architecture
|
|
123
|
-
|
|
124
|
-
When a project uses multiple integrations as a source-of-truth system, read `dev/PROJECT_INDEX.md` `## Installed Integrations` `### Source-of-truth Architecture` before acting.
|
|
125
|
-
|
|
126
|
-
| Layer | Role | Write direction |
|
|
127
|
-
|---|---|---|
|
|
128
|
-
| Source of truth | Original auditable reference content | User places or controls it; agent does not directly write it unless the project explicitly declares that integration as writable truth. |
|
|
129
|
-
| Index | Metadata, summary, tags, and references for source files | Agent may read/write through declared Connector or MCP when verified. |
|
|
130
|
-
| Persistent mirror | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically. |
|
|
131
|
-
| Working draft | Task output and local work product | Agent may read/write local files under normal safety rules. |
|
|
132
|
-
|
|
133
|
-
Each layer's responsible integration must be explicit in `PROJECT_INDEX`. Do not cross layers, for example by treating an index as primary truth or pushing a working draft to a mirror without authorization.
|
|
134
|
-
|
|
135
|
-
### 5. Cross-session Lifecycle
|
|
136
|
-
|
|
137
|
-
#### Phase 0 — First-contact declaration
|
|
138
|
-
|
|
139
|
-
During first-time onboarding, ask the user whether relevant external tools are already installed or available. This may be handled by the onboarding pack's external-tool scenario.
|
|
140
|
-
|
|
141
|
-
#### Phase 1 — Initial recording
|
|
142
|
-
|
|
143
|
-
Record declared integrations in `PROJECT_INDEX` `## Installed Integrations`, using the Connectors / MCPs / Plugins / Skills subsections and the Source-of-truth Architecture table when needed.
|
|
144
|
-
|
|
145
|
-
#### Phase 2 — Cross-session handoff
|
|
146
|
-
|
|
147
|
-
`SESSION_HANDOFF` durable anchors should point future agents to `PROJECT_INDEX` `## Installed Integrations`. The next-session opening message already includes `PROJECT_INDEX` in the read order.
|
|
148
|
-
|
|
149
|
-
#### Phase 3 — Startup availability probe
|
|
150
|
-
|
|
151
|
-
After reading `PROJECT_INDEX`, run a minimal availability probe for each declared integration when the runtime exposes the needed tool schema.
|
|
152
|
-
|
|
153
|
-
- Probe success: update `Last Verified` and proceed.
|
|
154
|
-
- Probe fail: warn that the integration is declared but unavailable in the current runtime, then use fallback flow only for the affected surface.
|
|
155
|
-
|
|
156
|
-
#### Phase 4 — Task execution
|
|
157
|
-
|
|
158
|
-
Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available, fall back to manual packet only when unavailable, and ask the user when the referenced integration is undeclared.
|
|
159
|
-
|
|
160
|
-
#### Phase 5 — Mid-session drift handling
|
|
161
|
-
|
|
162
|
-
If an integration fails mid-task because of expired auth, rate limit, network timeout, tool crash, or missing runtime capability:
|
|
163
|
-
|
|
164
|
-
- Surface the failure and impact.
|
|
165
|
-
- Do not auto-fix credentials or auth.
|
|
166
|
-
- Update `PROJECT_INDEX` `Last Verified` / note fields where appropriate.
|
|
167
|
-
- Record the drift in `SESSION_LOG` and unresolved risk in `SESSION_HANDOFF` when it affects future work.
|
|
168
|
-
|
|
169
|
-
#### Phase 6 — Cross-tool consistency
|
|
170
|
-
|
|
171
|
-
Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use fallback flow unless the user chooses to install or switch tools.
|
|
172
|
-
|
|
173
|
-
## Rules
|
|
174
|
-
|
|
175
|
-
1. **Credential separation**: never ask for, log, or persist credential values. Redact credential-like values and warn about rotation when appropriate.
|
|
176
|
-
2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
|
|
177
|
-
3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, ask about integration status rather than assuming none exists.
|
|
178
|
-
4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
|
|
179
|
-
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
180
|
-
6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
|
|
181
|
-
7. **Cross-tool capability awareness**: verify availability at startup and warn when the current runtime lacks a declared integration.
|
|
182
|
-
8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
|
|
183
|
-
9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
|
|
184
|
-
10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
|
|
185
|
-
11. **External tool resource lifecycle**: after external-tool use, classify resources by ownership. Task-owned / agent-managed resources may be closed or cleaned automatically; shared, user-owned, system-level, other-agent-owned, or unknown resources require evidence reporting and user confirmation before remediation.
|
|
186
|
-
|
|
187
|
-
## Checks
|
|
188
|
-
|
|
189
|
-
- Verify `dev/PROJECT_INDEX.md` `## Installed Integrations` exists and has the expected subsections when the project declares integrations.
|
|
190
|
-
- Before probing or invoking a declared integration, inspect current runtime tool description and input schema.
|
|
191
|
-
- Before browser validation, screenshots, Chrome, Playwright, DevTools, desktop automation, crawler, notebook, or raw CLI/SDK/tool-server work, verify the current source from runtime schema, official docs, or `PROJECT_INDEX` `## Tool Operation References`.
|
|
192
|
-
- Before external-tool first use, write, destructive operation, raw API / SDK / CLI / URI / plugin API call, or retry after tool error, confirm the current usage source.
|
|
193
|
-
- Surface and record mid-session integration drift.
|
|
194
|
-
- After external-tool use, perform ownership-based resource closeout. For long-running, multi-tool, MCP, browser automation, repeated-error, or slowdown scenarios, report grouped residual processes or services when observable.
|
|
195
|
-
- Before closeout, update `Last Verified` for integrations touched this session.
|
|
196
|
-
- Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
|
|
197
|
-
- Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
|
|
198
|
-
|
|
199
|
-
## Closeout
|
|
200
|
-
|
|
201
|
-
1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells for integrations touched this session.
|
|
202
|
-
2. If drift happened, record the drift narrative, impact, and suggested next handling in `SESSION_LOG`.
|
|
203
|
-
3. Add unresolved integration failures to `SESSION_HANDOFF` `## Risks / Blockers`.
|
|
204
|
-
4. If unresolved drift affects startup, mention the next-session verification need in the opening message.
|
|
205
|
-
5. If the user declared a new integration during the session, ensure it is registered in `PROJECT_INDEX` and cross-referenced from External Sources when applicable.
|
|
206
|
-
6. If shared or ambiguous external-tool processes, caches, browser contexts, or helper services remain, record only a redacted evidence summary and recommended remediation. Do not write raw secret-bearing command lines into handoff or log files.
|
|
207
|
-
|
|
208
|
-
## Anti-patterns
|
|
209
|
-
|
|
210
|
-
| Anti-pattern | Why it is wrong | Correct approach |
|
|
211
|
-
|---|---|---|
|
|
212
|
-
| Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations first; ask about integration status if undeclared. |
|
|
213
|
-
| Guessing tool names, endpoints, CLI flags, URI parameters, or plugin APIs from memory | Stale examples cause unknown tool, invalid args, 400 / 404, permission, or auth loops. | Verify active runtime schema, official docs, official types/samples, or versioned local runbooks. |
|
|
214
|
-
| Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference; mark blocked or use a manual packet when unavailable. |
|
|
215
|
-
| Treating a Connector marketing page or old example as executable schema | Marketing pages do not prove the active runtime's current tool name or input schema. | Use active runtime tool list/schema as the invocation source. |
|
|
216
|
-
| Retrying unknown tool / invalid args by changing names or parameters repeatedly | Trial-and-error hides the real schema or docs gap. | Stop same-pattern retries and return to the External Tool Usage Verification Gate. |
|
|
217
|
-
| Writing credential values into `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG` | Project files and git history are persistent; leaked credentials remain exposed. | Record credential references only, never values. |
|
|
218
|
-
| Using a credential value pasted in chat and then recording it | Chat history and logs may persist the secret. | Redact, warn, and ask the user to rotate if needed. |
|
|
219
|
-
| Auto-fixing auth or re-auth flows | Auth belongs to the user and the runtime/tool boundary. | Surface the failure and point to the runtime or tool settings. |
|
|
220
|
-
| Claiming an external write succeeded without read-back | External writes may fail silently or partially. | Read back and compare before claiming success. |
|
|
221
|
-
| Crossing source-of-truth layers | It can corrupt truth, mirrors, or working drafts. | Follow the declared layer role and write direction in `PROJECT_INDEX`. |
|
|
222
|
-
| Skipping startup availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
|
|
223
|
-
| Leaving task-owned MCP / browser / helper processes running after the task | Turns one-off tool use into a long-lived resource leak and can slow the host. | Use graceful close or task-owned process cleanup automatically; switch to user confirmation only when ownership is unclear. |
|
|
224
|
-
| Broadly killing by process name such as `node.exe`, `python`, or `chrome` | A generic process name does not prove ownership and may terminate user work, another project, or another AI agent's active tools. | Classify by tool family, process ID, start time, parent chain, and task-created path; treat unknown ownership as shared. |
|
|
225
|
-
| Automatically cleaning global caches, marketplace caches, OS temp roots, or browser profiles | May remove shared state, login state, or data other tools still need. | Automatically clean only task-owned / agent-managed bounded paths; report evidence and wait for confirmation otherwise. |
|
|
226
|
-
|
|
227
|
-
## Cross-reference
|
|
228
|
-
|
|
229
|
-
- `packs/knowledge.md` Rule 5: Connector-first source access discipline.
|
|
230
|
-
- `packs/safety.md` Rule 10: external API / SDK / CLI / tool verification boundary.
|
|
231
|
-
- `packs/safety.md` Rule 12: credential leak prevention.
|
|
232
|
-
- `packs/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
|
|
233
|
-
- `packs/onboarding.md` Scenario F: first-contact declaration entry point.
|
|
234
|
-
- `runtime-core/AGENTS.core.md` Section 1: startup availability probe discipline.
|
|
235
|
-
- `runtime-core/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
|