@adamchanadam/agent-handoff-kit 0.2.3 → 0.3.1
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/README.md +62 -85
- package/bin/agent-handoff-kit.mjs +1528 -1285
- package/package.json +1 -1
- package/packs/integrations.md +179 -0
- package/packs/knowledge.md +35 -31
- package/packs/onboarding.md +389 -298
- package/packs/safety.md +37 -29
- package/runtime-core/AGENTS.core.md +153 -144
- package/runtime-core/PROJECT_INDEX.md +136 -93
- package/runtime-core/RULE_PACKS.md +20 -19
- package/runtime-core/SESSION_HANDOFF.md +151 -150
|
@@ -1,93 +1,136 @@
|
|
|
1
|
-
# Project Index
|
|
2
|
-
|
|
3
|
-
Purpose: give a stateless AI a compact map of the project before it reads or edits files.
|
|
4
|
-
|
|
5
|
-
## Stack
|
|
6
|
-
|
|
7
|
-
| Field | Value | Last verified |
|
|
8
|
-
|---|---|---|
|
|
9
|
-
| Agent Handoff Kit template version | 0.1.7 | package prototype |
|
|
10
|
-
| Runtime | TBD | TBD |
|
|
11
|
-
| Framework | TBD | TBD |
|
|
12
|
-
| Package manager | TBD | TBD |
|
|
13
|
-
| Test command | TBD | TBD |
|
|
14
|
-
| Build command | TBD | TBD |
|
|
15
|
-
| Deploy command | TBD | TBD |
|
|
16
|
-
|
|
17
|
-
## Directory Map
|
|
18
|
-
|
|
19
|
-
| Path | Role | Read when |
|
|
20
|
-
|---|---|---|
|
|
21
|
-
| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
|
|
22
|
-
| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
|
|
23
|
-
| `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini CLI startup |
|
|
24
|
-
| `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
|
|
25
|
-
| `src/` | application source | coding task |
|
|
26
|
-
| `tests/` | tests | coding/QC |
|
|
27
|
-
| `docs/` | user or product docs | doc/public behavior change |
|
|
28
|
-
| `dev/` | governance state | startup/closeout |
|
|
29
|
-
| `TBD` | local source-of-truth files | before tasks that depend on project facts |
|
|
30
|
-
| `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
|
|
31
|
-
|
|
32
|
-
## Entry Points
|
|
33
|
-
|
|
34
|
-
| Entry | Path | Notes |
|
|
35
|
-
|---|---|---|
|
|
36
|
-
| App entry | TBD | TBD |
|
|
37
|
-
| Main config | TBD | TBD |
|
|
38
|
-
| Test suite | TBD | TBD |
|
|
39
|
-
| Runbook | TBD | TBD |
|
|
40
|
-
| Public docs | TBD | TBD |
|
|
41
|
-
|
|
42
|
-
## Fact Base
|
|
43
|
-
|
|
44
|
-
Reachable means the source can be found. It does not mean the source has been read in this session.
|
|
45
|
-
|
|
46
|
-
| Source | Role | Required before | Access method | Last verified |
|
|
47
|
-
|---|---|---|---|---|
|
|
48
|
-
| TBD | local source of truth / reference / draft / archive | TBD | path or instruction | TBD |
|
|
49
|
-
|
|
50
|
-
## External Sources
|
|
51
|
-
|
|
52
|
-
| Source | Role | Required before | Access method | Write-back rule | Last verified |
|
|
53
|
-
|
|
54
|
-
| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | read-back required / manual only / no write | TBD |
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
1
|
+
# Project Index
|
|
2
|
+
|
|
3
|
+
Purpose: give a stateless AI a compact map of the project before it reads or edits files.
|
|
4
|
+
|
|
5
|
+
## Stack
|
|
6
|
+
|
|
7
|
+
| Field | Value | Last verified |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Agent Handoff Kit template version | 0.1.7 | package prototype |
|
|
10
|
+
| Runtime | TBD | TBD |
|
|
11
|
+
| Framework | TBD | TBD |
|
|
12
|
+
| Package manager | TBD | TBD |
|
|
13
|
+
| Test command | TBD | TBD |
|
|
14
|
+
| Build command | TBD | TBD |
|
|
15
|
+
| Deploy command | TBD | TBD |
|
|
16
|
+
|
|
17
|
+
## Directory Map
|
|
18
|
+
|
|
19
|
+
| Path | Role | Read when |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
|
|
22
|
+
| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
|
|
23
|
+
| `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini CLI startup |
|
|
24
|
+
| `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
|
|
25
|
+
| `src/` | application source | coding task |
|
|
26
|
+
| `tests/` | tests | coding/QC |
|
|
27
|
+
| `docs/` | user or product docs | doc/public behavior change |
|
|
28
|
+
| `dev/` | governance state | startup/closeout |
|
|
29
|
+
| `TBD` | local source-of-truth files | before tasks that depend on project facts |
|
|
30
|
+
| `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
|
|
31
|
+
|
|
32
|
+
## Entry Points
|
|
33
|
+
|
|
34
|
+
| Entry | Path | Notes |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| App entry | TBD | TBD |
|
|
37
|
+
| Main config | TBD | TBD |
|
|
38
|
+
| Test suite | TBD | TBD |
|
|
39
|
+
| Runbook | TBD | TBD |
|
|
40
|
+
| Public docs | TBD | TBD |
|
|
41
|
+
|
|
42
|
+
## Fact Base
|
|
43
|
+
|
|
44
|
+
Reachable means the source can be found. It does not mean the source has been read in this session.
|
|
45
|
+
|
|
46
|
+
| Source | Role | Required before | Access method | Last verified |
|
|
47
|
+
|---|---|---|---|---|
|
|
48
|
+
| TBD | local source of truth / reference / draft / archive | TBD | path or instruction | TBD |
|
|
49
|
+
|
|
50
|
+
## External Sources
|
|
51
|
+
|
|
52
|
+
| Source | Role | Required before | Access method | `via` | Write-back rule | Last verified |
|
|
53
|
+
|---|---|---|---|---|---|---|
|
|
54
|
+
| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
|
|
55
|
+
|
|
56
|
+
> `via` column 紀律:每行 External Sources 必引用 `## Installed Integrations` 嘅 entry 名稱(譬如 `Notion Connector`、`Drive Connector`),確認該 source 經邊個 integration 訪問;無 declared Integration 嘅 source 用 `manual paste`。Cross-section consistency 由 doctor + qa:release 強制 enforce。
|
|
57
|
+
|
|
58
|
+
## Installed Integrations
|
|
59
|
+
|
|
60
|
+
> ⚠️ **機密分離原則**:本 section 只記錄 **項目使用紀錄** + **公開參考座標**(Notion DB 名 / URL / folder path 等),**絕對不記錄 API key / OAuth token / 任何 credential value**。Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions 嘅 OS Keychain / Claude Code MCP config)。AI 寫入本 section 前必 self-check 確認無 credential leak;doctor 對本 section + SESSION_HANDOFF + SESSION_LOG 強制 grep credential prefix patterns(`sk-` / `ntn_` / `ya29.` / `xoxp-` / `ghp_` / `sl.` / `AKIA` / `AIza` 等)。
|
|
61
|
+
|
|
62
|
+
> 用途:新 AI session 開工讀本 section 知道項目可用嘅外部工具能力 + 各自分工。Declare 一次後跨 session AI 都會 leverage;每個 entry 必含 `Declared` + `Last Verified` 防漂移。
|
|
63
|
+
|
|
64
|
+
### Connectors(Anthropic 官方 vetted)
|
|
65
|
+
|
|
66
|
+
| Tool | Project Usage | Access Scope | Specific Instance | Credential Location | Declared | Last Verified |
|
|
67
|
+
|------|---------------|--------------|-------------------|---------------------|----------|---------------|
|
|
68
|
+
| TBD | TBD(譬如 DB Index 記真源 path / 持久化參考檔儲存) | read / read+write | TBD(譬如 DB 名 + URL / folder path) | TBD(譬如 `Claude Desktop Extensions`) | TBD | TBD |
|
|
69
|
+
|
|
70
|
+
### MCPs(community / custom)
|
|
71
|
+
|
|
72
|
+
| Server | Source | Project Usage | Credential Location | Declared | Last Verified |
|
|
73
|
+
|--------|--------|---------------|---------------------|----------|---------------|
|
|
74
|
+
| TBD | TBD(譬如 GitHub repo URL) | TBD | TBD(譬如 `Claude Code MCP config + env var`) | TBD | TBD |
|
|
75
|
+
|
|
76
|
+
### Plugins(Claude Code plugin bundle)
|
|
77
|
+
|
|
78
|
+
| Name | Bundle Content(Skills + MCP + hooks) | When Triggered | Last Verified |
|
|
79
|
+
|------|----------------------------------------|----------------|---------------|
|
|
80
|
+
| TBD | TBD | TBD | TBD |
|
|
81
|
+
|
|
82
|
+
### Skills(SKILL.md instruction set)
|
|
83
|
+
|
|
84
|
+
| Name | Source | When Triggered | Last Verified |
|
|
85
|
+
|------|--------|----------------|---------------|
|
|
86
|
+
| TBD | TBD(譬如 plugin bundle / user-level install) | TBD | TBD |
|
|
87
|
+
|
|
88
|
+
### Source-of-truth Architecture(多層持久化組合)
|
|
89
|
+
|
|
90
|
+
> 當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Drive 參考檔),本表描述每層分工,避免 AI 跨層越界。
|
|
91
|
+
|
|
92
|
+
| Layer | Surface(具體 instance) | Role | Write Direction |
|
|
93
|
+
|-------|--------------------------|------|-----------------|
|
|
94
|
+
| 真源(source of truth) | TBD(譬如 本機 `~/project/reference/`) | 原始可審計 reference 內容 | 用戶手動置入;AI 不直接寫入 |
|
|
95
|
+
| Index | TBD(譬如 Notion DB「Project Index」) | 登記每份真源檔 metadata + 摘要 + tag | AI 經 Connector 直接讀寫 |
|
|
96
|
+
| 持久化參考檔(mirror) | TBD(譬如 Drive folder「Project Reference/」) | 防本機 disk failure / 跨裝置 access | 用戶手動同步;AI 唔自動 push |
|
|
97
|
+
| Working draft | TBD(譬如 本機 `~/project/output/`) | AI 寫 task output | AI 直接 read + write 本機 |
|
|
98
|
+
|
|
99
|
+
## Local QC Commands
|
|
100
|
+
|
|
101
|
+
| Check | Command | Run before | Last verified |
|
|
102
|
+
|---|---|---|---|
|
|
103
|
+
| Agent Handoff Kit doctor | TBD | closeout / governance changes | TBD |
|
|
104
|
+
| Project governance check | TBD | closeout / durable file changes | TBD |
|
|
105
|
+
|
|
106
|
+
## Workspace Identity
|
|
107
|
+
|
|
108
|
+
Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
109
|
+
|
|
110
|
+
| Field | Value | Last verified |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| Expected project root | TBD | TBD |
|
|
113
|
+
| Git root | TBD | TBD |
|
|
114
|
+
| Branch / commit | TBD | TBD |
|
|
115
|
+
| Worktree or parallel workspace | TBD | TBD |
|
|
116
|
+
| Uncommitted change summary | TBD | TBD |
|
|
117
|
+
|
|
118
|
+
## Change Hotspots
|
|
119
|
+
|
|
120
|
+
| Change type | Likely files | Required checks |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| API behavior | TBD | tests + docs sync |
|
|
123
|
+
| UI behavior | TBD | build + visual/manual check |
|
|
124
|
+
| Data model | TBD | migration/checks |
|
|
125
|
+
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
126
|
+
| Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + prompt convenience copy matches handoff + workspace identity current |
|
|
127
|
+
|
|
128
|
+
## External Services
|
|
129
|
+
|
|
130
|
+
| Service | Scope | Verification source | Last verified |
|
|
131
|
+
|---|---|---|---|
|
|
132
|
+
| TBD | TBD | TBD | TBD |
|
|
133
|
+
|
|
134
|
+
## Maintenance Rule
|
|
135
|
+
|
|
136
|
+
Update this file when stack, commands, directory roles, entry points, external services, workspace identity, durable runbooks, or governance file map changes.
|
|
@@ -1,19 +1,20 @@
|
|
|
1
|
-
# Rule Packs Router
|
|
2
|
-
|
|
3
|
-
Read only the packs needed for the current task.
|
|
4
|
-
|
|
5
|
-
| Task signal | Pack | Purpose |
|
|
6
|
-
|---|---|---|
|
|
7
|
-
| First-time user signals (任一即可): "I'm new" / "新手" / "教我用" / "help me start" / "first time" / "我啱啱安裝" / "點開始" / "show me how" / "getting started" / "agent handoff kit 可幫我做甚麼" / "我想做 [type] project" / "點用" / "能力" / vague first message ≤ 30 chars / HANDOFF Active Objective 空白 + Session count 1 (fresh installation context) | `dev/rules/onboarding.md` | first-time user walk-through with 5 scenarios (A 寫代碼 / B 研究報告 / C 知識庫 / D 學寫代碼 / E 其他) × 5-step pattern (PLAN-style: confirm context / explain v2 fit / ask task scope / suggest minimum viable / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
|
|
8
|
-
| 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
|
-
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
10
|
-
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
11
|
-
| 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
|
-
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
14
|
-
| External notes, knowledge base, Notion, Obsidian, Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
15
|
-
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
1
|
+
# Rule Packs Router
|
|
2
|
+
|
|
3
|
+
Read only the packs needed for the current task.
|
|
4
|
+
|
|
5
|
+
| Task signal | Pack | Purpose |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| First-time user signals (任一即可): "I'm new" / "新手" / "教我用" / "help me start" / "first time" / "我啱啱安裝" / "點開始" / "show me how" / "getting started" / "agent handoff kit 可幫我做甚麼" / "我想做 [type] project" / "點用" / "能力" / vague first message ≤ 30 chars / HANDOFF Active Objective 空白 + Session count 1 (fresh installation context) | `dev/rules/onboarding.md` | first-time user walk-through with 5 scenarios (A 寫代碼 / B 研究報告 / C 知識庫 / D 學寫代碼 / E 其他) × 5-step pattern (PLAN-style: confirm context / explain v2 fit / ask task scope / suggest minimum viable / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
|
|
8
|
+
| 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
|
+
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
10
|
+
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
11
|
+
| 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
|
+
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
14
|
+
| External notes, knowledge base, Notion, Obsidian, Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
15
|
+
| External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Drive / Slack / Linear / Dropbox / HubSpot / GitHub / etc. external read-write | `dev/rules/integrations.md` | Connector-first default + credential separation + multi-layer source-of-truth + cross-session resilience |
|
|
16
|
+
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
17
|
+
|
|
18
|
+
## Routing Rule
|
|
19
|
+
|
|
20
|
+
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 and state why. Packs can add stricter rules, but cannot weaken core safety or closeout requirements.
|
|
@@ -1,150 +1,151 @@
|
|
|
1
|
-
# Session Handoff
|
|
2
|
-
|
|
3
|
-
Last Updated: TBD
|
|
4
|
-
|
|
5
|
-
<!-- ack:section:durable-anchors -->
|
|
6
|
-
## Durable Anchors
|
|
7
|
-
|
|
8
|
-
Stable facts that should survive across sessions. Update only when they change, but verify they still match reality at closeout.
|
|
9
|
-
|
|
10
|
-
1. Project root and boundary: TBD
|
|
11
|
-
2. Product/system identity: TBD
|
|
12
|
-
3. Governance model: TBD
|
|
13
|
-
4. Source-of-truth ownership: TBD
|
|
14
|
-
5. Release / publish boundary: TBD
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
- Checks
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
-
|
|
109
|
-
|
|
110
|
-
-
|
|
111
|
-
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
1
|
+
# Session Handoff
|
|
2
|
+
|
|
3
|
+
Last Updated: TBD
|
|
4
|
+
|
|
5
|
+
<!-- ack:section:durable-anchors -->
|
|
6
|
+
## Durable Anchors
|
|
7
|
+
|
|
8
|
+
Stable facts that should survive across sessions. Update only when they change, but verify they still match reality at closeout.
|
|
9
|
+
|
|
10
|
+
1. Project root and boundary: TBD
|
|
11
|
+
2. Product/system identity: TBD
|
|
12
|
+
3. Governance model: TBD
|
|
13
|
+
4. Source-of-truth ownership: TBD
|
|
14
|
+
5. Release / publish boundary: TBD
|
|
15
|
+
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` section is the project's authoritative declaration of installed Connectors / MCPs / Plugins / Skills + Source-of-truth Architecture sub-table. New AI session must read it after governance reads and run availability probe per `runtime-core/AGENTS.core.md` Section 1. Credential values never appear here or in any `dev/*` file — they live in AI tool secure storage only.
|
|
16
|
+
|
|
17
|
+
<!-- ack:section:closeout-reconciled-state -->
|
|
18
|
+
## Closeout-Reconciled State
|
|
19
|
+
|
|
20
|
+
This is the current-state area. At every full closeout, rewrite or explicitly confirm every section below. Do not append a new state snapshot under an old one.
|
|
21
|
+
|
|
22
|
+
<!-- ack:section:current-baseline -->
|
|
23
|
+
## Current Baseline
|
|
24
|
+
|
|
25
|
+
1. Project root: TBD
|
|
26
|
+
2. Product/system state: TBD
|
|
27
|
+
3. Governance state: TBD
|
|
28
|
+
4. Source-of-truth notes: TBD
|
|
29
|
+
|
|
30
|
+
<!-- ack:section:task-understanding-summary -->
|
|
31
|
+
## Task Understanding Summary
|
|
32
|
+
|
|
33
|
+
<!-- ack:field:user-intent -->
|
|
34
|
+
- User intent: TBD
|
|
35
|
+
<!-- ack:field:task-essence -->
|
|
36
|
+
- Task essence: TBD
|
|
37
|
+
- User value: TBD
|
|
38
|
+
<!-- ack:field:success-criteria -->
|
|
39
|
+
- Success criteria: TBD
|
|
40
|
+
- Key background already read: TBD
|
|
41
|
+
- Background still unread or blocked: TBD
|
|
42
|
+
- Non-goals / boundaries: TBD
|
|
43
|
+
|
|
44
|
+
<!-- ack:section:active-objective -->
|
|
45
|
+
## Active Objective
|
|
46
|
+
|
|
47
|
+
TBD
|
|
48
|
+
|
|
49
|
+
<!-- ack:section:completed-this-session -->
|
|
50
|
+
## Completed This Session
|
|
51
|
+
|
|
52
|
+
Record only work actually completed in the current session.
|
|
53
|
+
|
|
54
|
+
1. TBD
|
|
55
|
+
|
|
56
|
+
<!-- ack:section:next-priorities -->
|
|
57
|
+
## Next Priorities
|
|
58
|
+
|
|
59
|
+
1. TBD
|
|
60
|
+
|
|
61
|
+
<!-- ack:section:next-task-required-reading -->
|
|
62
|
+
## Next Task Required Reading
|
|
63
|
+
|
|
64
|
+
Before acting on the next task, read or mark blocked:
|
|
65
|
+
|
|
66
|
+
| Source | Why required | Status |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| TBD | TBD | pending |
|
|
69
|
+
|
|
70
|
+
<!-- ack:section:risks-blockers -->
|
|
71
|
+
## Risks / Blockers
|
|
72
|
+
|
|
73
|
+
1. TBD
|
|
74
|
+
|
|
75
|
+
<!-- ack:section:validation-qc -->
|
|
76
|
+
## Validation / QC
|
|
77
|
+
|
|
78
|
+
- Checks run this session: TBD
|
|
79
|
+
- Checks not run and why: TBD
|
|
80
|
+
- Handoff evidence location: TBD
|
|
81
|
+
|
|
82
|
+
<!-- ack:section:workspace-identity -->
|
|
83
|
+
## Workspace Identity
|
|
84
|
+
|
|
85
|
+
Expected project root: TBD
|
|
86
|
+
Git root: TBD
|
|
87
|
+
Branch: TBD
|
|
88
|
+
Commit: TBD
|
|
89
|
+
Worktree / parallel workspace status: TBD
|
|
90
|
+
Uncommitted changes summary: TBD
|
|
91
|
+
|
|
92
|
+
<!-- ack:section:sync-status -->
|
|
93
|
+
## Sync Status
|
|
94
|
+
|
|
95
|
+
Use statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
|
|
96
|
+
|
|
97
|
+
- Project index: TBD
|
|
98
|
+
- Doc sync registry: TBD
|
|
99
|
+
- Public docs / README: TBD
|
|
100
|
+
- External knowledge tools: TBD
|
|
101
|
+
|
|
102
|
+
<!-- ack:section:state-reconciliation-check -->
|
|
103
|
+
## State Reconciliation Check
|
|
104
|
+
|
|
105
|
+
At full closeout, complete this check after updating the state sections above.
|
|
106
|
+
|
|
107
|
+
- Reconciled at: TBD
|
|
108
|
+
<!-- ack:field:state-sections-rewritten-or-confirmed -->
|
|
109
|
+
- State sections rewritten or confirmed current: TBD
|
|
110
|
+
<!-- ack:field:stale-snapshots-left -->
|
|
111
|
+
- Stale snapshots left in this handoff: TBD
|
|
112
|
+
<!-- ack:field:opening-message-matches-current-state -->
|
|
113
|
+
- Opening message matches current state: TBD
|
|
114
|
+
<!-- ack:field:next-ai-can-continue -->
|
|
115
|
+
- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
|
|
116
|
+
|
|
117
|
+
If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
|
|
118
|
+
|
|
119
|
+
<!-- ack:section:handoff-sufficiency-check -->
|
|
120
|
+
## Handoff Sufficiency Check
|
|
121
|
+
|
|
122
|
+
Can the next AI continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history?
|
|
123
|
+
|
|
124
|
+
Answer: TBD
|
|
125
|
+
If no, update this handoff before closeout.
|
|
126
|
+
|
|
127
|
+
Continuity rule: this file carries current state and next action. `dev/SESSION_LOG.md` carries recent evidence only. Archive old detail only when needed; do not create an archive directory by default.
|
|
128
|
+
|
|
129
|
+
<!-- ack:section:next-session-opening-message -->
|
|
130
|
+
## Next Session Opening Message
|
|
131
|
+
|
|
132
|
+
This fenced block is the authoritative startup prompt. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy.
|
|
133
|
+
|
|
134
|
+
📋 Next session: copy and paste the whole block below
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
Work in <absolute project root>.
|
|
138
|
+
|
|
139
|
+
Read in order:
|
|
140
|
+
1. AGENTS.md
|
|
141
|
+
2. dev/SESSION_HANDOFF.md
|
|
142
|
+
3. dev/SESSION_LOG.md
|
|
143
|
+
4. dev/PROJECT_INDEX.md
|
|
144
|
+
5. dev/RULE_PACKS.md
|
|
145
|
+
|
|
146
|
+
Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
|
|
147
|
+
|
|
148
|
+
If this root does not match the expected project root, stop and ask for confirmation.
|
|
149
|
+
|
|
150
|
+
After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.
|
|
151
|
+
```
|