@adamchanadam/agent-handoff-kit 0.3.38 → 0.3.39
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 +5 -5
- package/bin/agent-handoff-kit.mjs +1385 -694
- 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 +166 -93
- package/package.json +1 -1
- package/packs/closeout.md +72 -0
- package/packs/integrations.md +21 -5
- package/packs/onboarding.md +30 -17
- package/packs/safety.md +5 -3
- package/runtime-core/AGENTS.core.md +107 -185
- package/runtime-core/PROJECT_INDEX.md +10 -8
- package/runtime-core/RULE_PACKS.md +10 -9
- package/runtime-core/SESSION_HANDOFF.md +9 -18
- package/runtime-core/SESSION_LOG.md +2 -24
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +3 -14
|
@@ -1,114 +1,187 @@
|
|
|
1
|
-
import { readFileSync } from "node:fs";
|
|
2
|
-
import path from "node:path";
|
|
3
|
-
|
|
4
|
-
const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
|
|
5
|
-
const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
|
|
6
|
-
const openingContentMarkers = [
|
|
7
|
-
"📋 Next session: agent-managed startup content below",
|
|
8
|
-
"📋 Next session: copy and paste the whole block below"
|
|
9
|
-
];
|
|
10
|
-
|
|
11
|
-
export function assessPromptMirrorRoot(root) {
|
|
12
|
-
const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
|
|
13
|
-
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
14
|
-
let handoffText = "";
|
|
15
|
-
let promptText = "";
|
|
16
|
-
|
|
17
|
-
try {
|
|
18
|
-
handoffText = readFileSync(handoffPath, "utf8");
|
|
19
|
-
} catch {
|
|
20
|
-
return { status: "missing", ok: false, reason: "handoff unreadable" };
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
try {
|
|
24
|
-
promptText = readFileSync(promptPath, "utf8");
|
|
25
|
-
} catch {
|
|
26
|
-
return { status: "missing", ok: false, reason: "prompt copy unreadable" };
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
|
|
1
|
+
import { lstatSync, readFileSync, readdirSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
|
|
5
|
+
const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
|
|
6
|
+
const openingContentMarkers = [
|
|
7
|
+
"📋 Next session: agent-managed startup content below",
|
|
8
|
+
"📋 Next session: copy and paste the whole block below"
|
|
9
|
+
];
|
|
10
|
+
|
|
11
|
+
export function assessPromptMirrorRoot(root) {
|
|
12
|
+
const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
|
|
13
|
+
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
14
|
+
let handoffText = "";
|
|
15
|
+
let promptText = "";
|
|
16
|
+
|
|
17
|
+
try {
|
|
18
|
+
handoffText = readFileSync(handoffPath, "utf8");
|
|
19
|
+
} catch {
|
|
20
|
+
return { status: "missing", ok: false, reason: "handoff unreadable" };
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
try {
|
|
24
|
+
promptText = readFileSync(promptPath, "utf8");
|
|
25
|
+
} catch {
|
|
26
|
+
return { status: "missing", ok: false, reason: "prompt copy unreadable" };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const otherTexts = collectCurrentGovernanceTexts(root, new Set([
|
|
30
|
+
path.resolve(handoffPath),
|
|
31
|
+
path.resolve(promptPath)
|
|
32
|
+
]));
|
|
33
|
+
return assessPromptMirrorTexts(handoffText, promptText, otherTexts);
|
|
30
34
|
}
|
|
31
35
|
|
|
32
|
-
export function assessPromptMirrorTexts(handoffText, promptText) {
|
|
33
|
-
const
|
|
34
|
-
|
|
36
|
+
export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []) {
|
|
37
|
+
const markerCount = countLiteral(handoffText, openingSectionMarker);
|
|
38
|
+
const headingCount = (handoffText.match(new RegExp(openingHeadingPattern.source, "gm")) ?? []).length;
|
|
39
|
+
const contentMarkerCount = openingContentMarkers.reduce((sum, marker) => sum + countLiteral(handoffText, marker), 0);
|
|
40
|
+
const openingSection = markerCount === 1 ? handoffText.slice(handoffText.indexOf(openingSectionMarker)) : "";
|
|
41
|
+
const fenceCount = (openingSection.match(/```text[^\r\n]*(?:\r\n?|\n)[\s\S]*?(?:\r\n?|\n)```/g) ?? []).length;
|
|
42
|
+
if (markerCount !== 1 || headingCount > 1 || contentMarkerCount !== 1 || fenceCount !== 1) {
|
|
35
43
|
return {
|
|
36
|
-
status: "
|
|
44
|
+
status: "structure-invalid",
|
|
37
45
|
ok: false,
|
|
38
|
-
reason:
|
|
39
|
-
};
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
if (openingMessage === promptText) {
|
|
43
|
-
return {
|
|
44
|
-
status: "match",
|
|
45
|
-
ok: true,
|
|
46
|
-
reason: "",
|
|
47
|
-
openingMessage,
|
|
48
|
-
firstDiff: null
|
|
46
|
+
reason: `opening structure must be unique (section marker=${markerCount}, heading=${headingCount}, copy marker=${contentMarkerCount}, fenced text=${fenceCount})`
|
|
49
47
|
};
|
|
50
48
|
}
|
|
51
49
|
|
|
50
|
+
const openingMessage = extractOpeningMessage(handoffText);
|
|
51
|
+
if (openingMessage == null) {
|
|
52
|
+
return {
|
|
53
|
+
status: "missing",
|
|
54
|
+
ok: false,
|
|
55
|
+
reason: "handoff opening message missing"
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
52
59
|
const normalizedOpening = normalizePrompt(openingMessage);
|
|
53
|
-
const
|
|
54
|
-
if (
|
|
60
|
+
const thirdCopies = otherTexts.filter(({ text }) => normalizePrompt(text).includes(normalizedOpening));
|
|
61
|
+
if (thirdCopies.length > 0) {
|
|
55
62
|
return {
|
|
56
|
-
status: "
|
|
57
|
-
ok:
|
|
58
|
-
reason:
|
|
63
|
+
status: "third-copy",
|
|
64
|
+
ok: false,
|
|
65
|
+
reason: `full opening message also appears in: ${thirdCopies.map(({ relative }) => relative).join(", ")}`,
|
|
59
66
|
openingMessage,
|
|
60
|
-
|
|
67
|
+
thirdCopies: thirdCopies.map(({ relative }) => relative)
|
|
61
68
|
};
|
|
62
69
|
}
|
|
63
70
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
}
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
const
|
|
75
|
-
if (
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
return
|
|
71
|
+
if (openingMessage === promptText) {
|
|
72
|
+
return {
|
|
73
|
+
status: "match",
|
|
74
|
+
ok: true,
|
|
75
|
+
reason: "",
|
|
76
|
+
openingMessage,
|
|
77
|
+
firstDiff: null
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const normalizedPrompt = normalizePrompt(promptText);
|
|
82
|
+
if (normalizedOpening === normalizedPrompt) {
|
|
83
|
+
return {
|
|
84
|
+
status: "newline-only",
|
|
85
|
+
ok: true,
|
|
86
|
+
reason: "only newline style or final newline differs",
|
|
87
|
+
openingMessage,
|
|
88
|
+
firstDiff: null
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
return {
|
|
93
|
+
status: "mismatch",
|
|
94
|
+
ok: false,
|
|
95
|
+
reason: "convenience copy differs from dev/SESSION_HANDOFF.md",
|
|
96
|
+
openingMessage,
|
|
97
|
+
firstDiff: firstDiff(normalizedOpening, normalizedPrompt)
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export function extractOpeningMessage(text) {
|
|
102
|
+
const sectionStart = findOpeningSectionStart(text);
|
|
103
|
+
if (sectionStart < 0) return null;
|
|
104
|
+
|
|
105
|
+
const sectionText = text.slice(sectionStart);
|
|
106
|
+
const marker = openingContentMarkers.find((candidate) => sectionText.includes(candidate));
|
|
107
|
+
if (!marker) return null;
|
|
108
|
+
|
|
109
|
+
const markerIndex = sectionText.indexOf(marker);
|
|
110
|
+
const afterMarker = sectionText.slice(markerIndex + marker.length);
|
|
111
|
+
const fenceMatch = /```text[^\r\n]*(?:\r\n?|\n)([\s\S]*?)(?:\r\n?|\n)```/.exec(afterMarker);
|
|
112
|
+
if (!fenceMatch) return null;
|
|
113
|
+
return fenceMatch[1];
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
export function normalizePrompt(text) {
|
|
117
|
+
return text.replace(/\r\n?/g, "\n").replace(/\n+$/g, "");
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function findOpeningSectionStart(text) {
|
|
121
|
+
const markerIndex = text.indexOf(openingSectionMarker);
|
|
122
|
+
if (markerIndex >= 0) return markerIndex;
|
|
123
|
+
|
|
124
|
+
const headingMatch = openingHeadingPattern.exec(text);
|
|
125
|
+
return headingMatch ? headingMatch.index : -1;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function firstDiff(left, right) {
|
|
129
|
+
const leftLines = left.split("\n");
|
|
130
|
+
const rightLines = right.split("\n");
|
|
131
|
+
const count = Math.max(leftLines.length, rightLines.length);
|
|
132
|
+
for (let index = 0; index < count; index += 1) {
|
|
133
|
+
if ((leftLines[index] ?? "") !== (rightLines[index] ?? "")) {
|
|
134
|
+
return {
|
|
135
|
+
line: index + 1,
|
|
136
|
+
handoff: leftLines[index] ?? "",
|
|
137
|
+
prompt: rightLines[index] ?? ""
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return null;
|
|
86
142
|
}
|
|
87
143
|
|
|
88
|
-
|
|
89
|
-
|
|
144
|
+
function countLiteral(text, token) {
|
|
145
|
+
if (!token) return 0;
|
|
146
|
+
let count = 0;
|
|
147
|
+
let offset = 0;
|
|
148
|
+
while ((offset = text.indexOf(token, offset)) >= 0) {
|
|
149
|
+
count += 1;
|
|
150
|
+
offset += token.length;
|
|
151
|
+
}
|
|
152
|
+
return count;
|
|
90
153
|
}
|
|
91
154
|
|
|
92
|
-
function
|
|
93
|
-
const
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
155
|
+
function collectCurrentGovernanceTexts(root, excluded) {
|
|
156
|
+
const candidates = [
|
|
157
|
+
"AGENTS.md",
|
|
158
|
+
"CLAUDE.md",
|
|
159
|
+
"GEMINI.md",
|
|
160
|
+
"dev/SESSION_LOG.md",
|
|
161
|
+
"dev/PROJECT_INDEX.md",
|
|
162
|
+
"dev/DOC_SYNC_REGISTRY.md",
|
|
163
|
+
"dev/RULE_PACKS.md",
|
|
164
|
+
"dev/PROJECT_DECISIONS.md"
|
|
165
|
+
];
|
|
166
|
+
const rulesDir = path.join(root, "dev", "rules");
|
|
167
|
+
try {
|
|
168
|
+
for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
|
|
169
|
+
if (entry.isFile() && entry.name.endsWith(".md")) candidates.push(`dev/rules/${entry.name}`);
|
|
170
|
+
}
|
|
171
|
+
} catch {
|
|
172
|
+
// Missing rules are reported by normal doctor checks.
|
|
173
|
+
}
|
|
99
174
|
|
|
100
|
-
|
|
101
|
-
const
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
prompt: rightLines[index] ?? ""
|
|
110
|
-
};
|
|
175
|
+
const results = [];
|
|
176
|
+
for (const relative of candidates) {
|
|
177
|
+
const absolute = path.resolve(root, relative);
|
|
178
|
+
if (excluded.has(absolute)) continue;
|
|
179
|
+
try {
|
|
180
|
+
if (lstatSync(absolute).isSymbolicLink()) continue;
|
|
181
|
+
results.push({ relative, text: readFileSync(absolute, "utf8") });
|
|
182
|
+
} catch {
|
|
183
|
+
// Missing or unreadable files are handled by their owning checks.
|
|
111
184
|
}
|
|
112
185
|
}
|
|
113
|
-
return
|
|
186
|
+
return results;
|
|
114
187
|
}
|
package/package.json
CHANGED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Closeout Pack
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
This pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.
|
|
6
|
+
|
|
7
|
+
## Required Reads
|
|
8
|
+
|
|
9
|
+
Read the current `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.
|
|
10
|
+
|
|
11
|
+
## Write Contract
|
|
12
|
+
|
|
13
|
+
Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.
|
|
14
|
+
|
|
15
|
+
- Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.
|
|
16
|
+
- Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.
|
|
17
|
+
- File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.
|
|
18
|
+
- Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.
|
|
19
|
+
- Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.
|
|
20
|
+
- Reusable procedures belong in the relevant pack, registered reference, or QA check.
|
|
21
|
+
- `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.
|
|
22
|
+
|
|
23
|
+
Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records that the mirror was regenerated and verified, plus an evidence reference when useful.
|
|
24
|
+
|
|
25
|
+
## Full Closeout
|
|
26
|
+
|
|
27
|
+
1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then rewrite or explicitly confirm every closeout-reconciled section.
|
|
28
|
+
2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
|
|
29
|
+
The bundled doctor is a mechanical floor for obvious overlap and unresolved fields; it cannot prove that renamed or paraphrased work is semantically consistent. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to doctor.
|
|
30
|
+
3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
|
|
31
|
+
4. Complete the persistence-routing and handoff-sufficiency fields. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history.
|
|
32
|
+
5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.
|
|
33
|
+
6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
|
|
34
|
+
7. Record the actual root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization.
|
|
35
|
+
8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.
|
|
36
|
+
9. Run the short maintenance trigger check below and record its result in the log.
|
|
37
|
+
10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.
|
|
38
|
+
11. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the sole fenced handoff opening-message block. Run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.
|
|
39
|
+
12. Run available project closeout / doctor checks. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
|
|
40
|
+
|
|
41
|
+
## Maintenance Trigger Check
|
|
42
|
+
|
|
43
|
+
Every full closeout runs this short check; full maintenance runs only when triggered.
|
|
44
|
+
|
|
45
|
+
- SESSION_LOG: trigger when the main log reaches at least 11 entries, exceeds 1500 lines, or the 10-closeout backstop is due. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md`. Port unique narrative before collapsing it.
|
|
46
|
+
- PROJECT_DECISIONS: trigger when a decisions-like handoff section has at least 30 entries; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive. Also write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.
|
|
47
|
+
- Backstop: every 10 closeouts, run the full long-term maintenance pass even when no semantic trigger is obvious. If the count cannot be determined confidently at the boundary, treat the backstop as due.
|
|
48
|
+
|
|
49
|
+
If no trigger applies, record one no-op reason. Handoff carries continuity; log and project decisions carry trace and long-term narrative.
|
|
50
|
+
|
|
51
|
+
## Opening Message And Card
|
|
52
|
+
|
|
53
|
+
The handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.
|
|
54
|
+
|
|
55
|
+
Use a verified version already present in the closeout reads; otherwise show `version unverified`. Never print the literal placeholder `v<version>`.
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
/\_/\ Agent Handoff Kit v<version>
|
|
59
|
+
( -.- ) handoff saved
|
|
60
|
+
> ^ <
|
|
61
|
+
|
|
62
|
+
✅ Done: <completed summary>
|
|
63
|
+
🔎 QC: <validation summary>
|
|
64
|
+
📌 Handoff: opening message ready
|
|
65
|
+
⚠️ Boundary: <important boundary or none>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. Do not hand-compose a third stateful prompt in the final response.
|
|
69
|
+
|
|
70
|
+
## Stop Conditions
|
|
71
|
+
|
|
72
|
+
Do not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.
|
package/packs/integrations.md
CHANGED
|
@@ -12,7 +12,7 @@ This pack does not teach users how to install tools. Installation is handled by
|
|
|
12
12
|
|
|
13
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
14
|
- The user asks whether the agent can directly read or write an external system.
|
|
15
|
-
-
|
|
15
|
+
- The current task or handoff names a declared integration as a dependency, or the user requests an integration health check.
|
|
16
16
|
- First-time onboarding asks the user to declare installed external tools.
|
|
17
17
|
- The project uses a multi-layer source-of-truth setup, for example Notion index + local source files + Google Drive reference mirrors.
|
|
18
18
|
- The user reports resource pressure, stale MCP or plugin services, browser automation left running, cache growth, or slowdown after external-tool use.
|
|
@@ -62,6 +62,20 @@ For browser and tool-operation work, first check `dev/PROJECT_INDEX.md` `## Tool
|
|
|
62
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
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
64
|
|
|
65
|
+
#### Local HTML / app validation fallback
|
|
66
|
+
|
|
67
|
+
A blocked browser surface is not the same as a blocked validation task. If a browser tool rejects a local `file://` page because of URL policy, sandbox policy, or browser-use safety policy, do not try to bypass that policy through raw CDP, alternate browser surfaces, extension state, or hidden browser commands. Treat the rejected `file://` attempt as one failed surface and switch to a materially safer project-local validation path when available.
|
|
68
|
+
|
|
69
|
+
For local HTML, static app, generated guide, or local UI validation, the preferred fallback is a short-lived localhost service:
|
|
70
|
+
|
|
71
|
+
1. Check `PROJECT_INDEX` `## Tool Operation References` for a registered browser, Chrome DevTools, Playwright, or local validation procedure.
|
|
72
|
+
2. If no registered procedure is available and the file can be safely served, start a task-owned local static server bound to loopback such as `127.0.0.1`.
|
|
73
|
+
3. Open the served `http://127.0.0.1:<port>/...` URL with the verified browser, DevTools, or Playwright surface.
|
|
74
|
+
4. Verify real behavior through visible page state, text hits, click/state changes, console evidence, screenshot, or another task-relevant readback.
|
|
75
|
+
5. Close the task-owned browser tab/context and stop the localhost service before completion; record any cleanup limit under the resource lifecycle rules.
|
|
76
|
+
|
|
77
|
+
Only mark local HTML / app validation as `blocked` after the registered operation reference, the localhost fallback, and the available verified browser / DevTools / Playwright surface are each unavailable or fail for a stated reason. A `file://` rejection alone is not enough evidence to stop.
|
|
78
|
+
|
|
65
79
|
### 2.1 External Tool Resource Lifecycle
|
|
66
80
|
|
|
67
81
|
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:
|
|
@@ -146,9 +160,9 @@ Record declared integrations in `PROJECT_INDEX` `## Installed Integrations`, usi
|
|
|
146
160
|
|
|
147
161
|
`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
162
|
|
|
149
|
-
#### Phase 3 —
|
|
163
|
+
#### Phase 3 — Before-use availability probe
|
|
150
164
|
|
|
151
|
-
|
|
165
|
+
Immediately before the current task uses a declared integration, run the smallest relevant availability probe when the runtime exposes the needed tool schema. Do not probe unrelated integrations at startup. `TBD`, examples, blank rows, and placeholder-only tables are not declarations.
|
|
152
166
|
|
|
153
167
|
- Probe success: update `Last Verified` and proceed.
|
|
154
168
|
- Probe fail: warn that the integration is declared but unavailable in the current runtime, then use fallback flow only for the affected surface.
|
|
@@ -178,11 +192,12 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
178
192
|
4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
|
|
179
193
|
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
180
194
|
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
|
|
195
|
+
7. **Cross-tool capability awareness**: verify availability immediately before use, when the current objective declares the integration as a dependency, or when the user requests a health check.
|
|
182
196
|
8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
|
|
183
197
|
9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
|
|
184
198
|
10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
|
|
185
199
|
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.
|
|
200
|
+
12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
|
|
186
201
|
|
|
187
202
|
## Checks
|
|
188
203
|
|
|
@@ -195,6 +210,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
195
210
|
- Before closeout, update `Last Verified` for integrations touched this session.
|
|
196
211
|
- Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
|
|
197
212
|
- Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
|
|
213
|
+
- For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
|
|
198
214
|
|
|
199
215
|
## Closeout
|
|
200
216
|
|
|
@@ -231,5 +247,5 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
231
247
|
- `packs/safety.md` Rule 12: credential leak prevention.
|
|
232
248
|
- `packs/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
|
|
233
249
|
- `packs/onboarding.md` Scenario F: first-contact declaration entry point.
|
|
234
|
-
- `runtime-core/AGENTS.core.md` Section 1:
|
|
250
|
+
- `runtime-core/AGENTS.core.md` Section 1: task-triggered availability probe discipline.
|
|
235
251
|
- `runtime-core/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
|
package/packs/onboarding.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Scope
|
|
4
4
|
|
|
5
|
-
Use this transient pack for first-time Agent Handoff Kit users
|
|
5
|
+
Use this transient pack for first-time Agent Handoff Kit users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state.
|
|
6
6
|
|
|
7
7
|
The goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.
|
|
8
8
|
|
|
@@ -14,16 +14,22 @@ Load this pack when the user message contains an onboarding signal such as:
|
|
|
14
14
|
|
|
15
15
|
- "I'm new" / "new user"
|
|
16
16
|
- "teach me" / "help me start" / "help me get started"
|
|
17
|
-
- "first time" / "first-time"
|
|
17
|
+
- "first time" / "first-time" when the user also asks for guidance
|
|
18
18
|
- "how do I start" / "show me how" / "getting started"
|
|
19
19
|
- "what can agent handoff kit do"
|
|
20
20
|
- vague project intent such as "I want to do a project"
|
|
21
|
-
- equivalent Chinese user phrases such as "新手", "教我用", "
|
|
21
|
+
- equivalent Chinese user phrases such as "新手", "教我用", "點開始", "能力", or "能做甚麼"
|
|
22
|
+
|
|
23
|
+
`I just installed` / "我剛安裝" alone records first-use eligibility; it does not load this pack when the same message or handoff already contains an executable objective.
|
|
24
|
+
|
|
25
|
+
### Continuity startup boundary
|
|
26
|
+
|
|
27
|
+
`Start Agent Handoff` / "開工" starts continuity and reads the current handoff state; it is not an onboarding signal. If the same message or loaded state contains a concrete objective, infer the working scenario and begin the first safe action. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as "新手,教我用" enter onboarding directly.
|
|
22
28
|
|
|
23
29
|
### Implicit signals
|
|
24
30
|
|
|
25
|
-
- The first user message is short and vague.
|
|
26
|
-
- `SESSION_HANDOFF` Active Objective is empty and
|
|
31
|
+
- The first user message is short and still genuinely vague after available project state is read.
|
|
32
|
+
- `SESSION_HANDOFF` first-use guidance state is `eligible`, Active Objective is empty, and the user has not supplied a concrete objective with enough material facts.
|
|
27
33
|
- The user asks a generic capability question instead of giving a concrete task.
|
|
28
34
|
- The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
|
|
29
35
|
|
|
@@ -33,11 +39,17 @@ Load this pack when the user message contains an onboarding signal such as:
|
|
|
33
39
|
|
|
34
40
|
The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
|
|
35
41
|
|
|
36
|
-
### 2.
|
|
42
|
+
### 2. Infer first; offer scenario choice only when needed
|
|
43
|
+
|
|
44
|
+
Infer when sufficient; ask only when unresolved. Read the user's message together with the available handoff and project state before deciding whether a chooser is needed.
|
|
45
|
+
|
|
46
|
+
When the user has already supplied a concrete, actionable objective and enough material facts, infer the closest working scenario, state the assumption briefly, load the regular task pack(s), and begin the first safe action. Do not require an A-F reply, repeat questions whose answers are already available, or reduce a concrete request to a generic minimum task.
|
|
47
|
+
|
|
48
|
+
Only show the scenario chooser when the user's intent remains genuinely unresolved or the user asks for guided onboarding. In that case, combine the startup card and chooser into one complete response. Do not print a partial startup card first or repeat the card.
|
|
37
49
|
|
|
38
|
-
|
|
50
|
+
This routing decision never removes a safety gate. High-risk, external, permission, cost, publishing, and irreversible actions still require the normal plan and explicit confirmation before execution.
|
|
39
51
|
|
|
40
|
-
|
|
52
|
+
The library contains six scenarios. Treat them as an internal inference library. When choices are genuinely required, show only the two or three most relevant options; use a short open question when no responsible shortlist can be inferred. Do not display all six merely because the library contains them.
|
|
41
53
|
|
|
42
54
|
- **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.
|
|
43
55
|
- **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.
|
|
@@ -46,19 +58,19 @@ Offer six scenarios:
|
|
|
46
58
|
- **E. Custom scenario**: the user has another goal.
|
|
47
59
|
- **F. Review installed external tools and design governance**: the user already has Connectors, MCPs, Plugins, Skills, or browser / notebook / crawler tools and wants a safe operating model.
|
|
48
60
|
|
|
49
|
-
### 3. 5-step walk-through pattern
|
|
61
|
+
### 3. Guided 5-step walk-through pattern
|
|
50
62
|
|
|
51
|
-
|
|
63
|
+
Use this five-step path only after the user selects guided onboarding or when clarification is genuinely needed:
|
|
52
64
|
|
|
53
65
|
1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.
|
|
54
66
|
2. Explain in three plain points how Agent Handoff Kit helps this scenario.
|
|
55
|
-
3. Ask for the first concrete task scope, offering
|
|
67
|
+
3. Ask for the first concrete task scope, offering at most two or three genuinely relevant options.
|
|
56
68
|
4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.
|
|
57
69
|
5. Wait for user confirmation, then transition to the regular work loop.
|
|
58
70
|
|
|
59
|
-
### 4.
|
|
71
|
+
### 4. Ask only for missing information
|
|
60
72
|
|
|
61
|
-
|
|
73
|
+
Skip any guided step already answered by the user or available project state. When a step is still needed, advance one step at a time and:
|
|
62
74
|
|
|
63
75
|
- state what the AI will do,
|
|
64
76
|
- state what the user needs to answer or confirm,
|
|
@@ -80,7 +92,7 @@ After the walk-through:
|
|
|
80
92
|
|
|
81
93
|
## Application Scenario Library
|
|
82
94
|
|
|
83
|
-
Each scenario
|
|
95
|
+
Each scenario is a fallback guidance template, not a mandatory questionnaire. The model may skip answered steps, infer the route when evidence is sufficient, and adapt wording while preserving intent, tone, and safety boundaries.
|
|
84
96
|
|
|
85
97
|
### Scenario A. Build systems, tools, platforms, websites, or apps
|
|
86
98
|
|
|
@@ -132,7 +144,7 @@ Step D.5: after confirmation, load coding / safety packs and begin the normal wo
|
|
|
132
144
|
|
|
133
145
|
### Scenario E. Custom scenario
|
|
134
146
|
|
|
135
|
-
Step E.1:
|
|
147
|
+
Step E.1: use any facts already provided, then ask only for missing information that materially affects the first safe action. Do not ask about technical comfort unless it changes the delivery approach.
|
|
136
148
|
|
|
137
149
|
Step E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.
|
|
138
150
|
|
|
@@ -185,6 +197,7 @@ After onboarding finishes:
|
|
|
185
197
|
3. Record next priorities only when they affect a later session.
|
|
186
198
|
4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.
|
|
187
199
|
5. Unload this pack and continue with the relevant regular pack(s).
|
|
200
|
+
6. Mark `ack:field:first-use-guidance-state` as `consumed` after the first guided task begins or the first full closeout completes. Never reset `consumed` or `not_applicable` to `eligible` during upgrade.
|
|
188
201
|
|
|
189
202
|
In a later session, reload onboarding only when the user gives a fresh onboarding signal or asks to restart the walk-through. Otherwise enter the normal work loop.
|
|
190
203
|
|
|
@@ -192,10 +205,10 @@ In a later session, reload onboarding only when the user gives a fresh onboardin
|
|
|
192
205
|
|
|
193
206
|
| Anti-pattern | Why it is wrong | Correct approach |
|
|
194
207
|
|---|---|---|
|
|
195
|
-
| Treating a vague first message as a specific task | The user may be trying to learn the workflow or choose a scenario. |
|
|
208
|
+
| Treating a genuinely vague first message as a specific task | The user may be trying to learn the workflow or choose a scenario. | Ask one concise question or show the two or three most relevant scenarios only when intent remains unresolved. |
|
|
196
209
|
| Making the first task broad | A first-time user needs rhythm and confidence before large changes. | Suggest one 10-15 minute minimum viable task. |
|
|
197
210
|
| Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |
|
|
198
211
|
| Assuming the user read README or guide pages | Many users start directly in an AI chat. | Surface only the concepts needed for the next step. |
|
|
199
212
|
| Keeping onboarding loaded after the first task starts | Onboarding is transient and will distract from normal task work. | Unload onboarding and load the regular pack(s). |
|
|
200
|
-
|
|
|
213
|
+
| Forcing the chooser or all five guided steps after the objective is already concrete | The user must repeat known information and the AI shifts technical work back to the user. | Infer the scenario, state the assumption, and begin the first safe action; ask only for missing facts or required risk approval. |
|
|
201
214
|
| Assuming no Connector, MCP, Plugin, or Skill exists | Paste-only fallback creates the wrong operating model for users who already connected tools. | Ask a lightweight external-tool question in step 1, or use Scenario F. |
|
package/packs/safety.md
CHANGED
|
@@ -16,10 +16,10 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
16
16
|
2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
|
|
17
17
|
3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
|
|
18
18
|
4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. Report the blocker and manual action needed.
|
|
19
|
-
5.
|
|
19
|
+
5. Never run `rm -rf`, `sudo rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, `git reset --hard`, or an obfuscated / wrapped equivalent. User request does not make these named commands permissible. Use a narrower reversible operation or provide a manual action list.
|
|
20
20
|
6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
|
|
21
|
-
7. On macOS / Linux,
|
|
22
|
-
8.
|
|
21
|
+
7. On macOS / Linux, never use destructive wildcards, recursive `chmod 777`, recursive `chown`, disk formatting, mount-point cleanup, or home/system-directory cleanup. Other destructive operations require explicit authorization plus resolved target verification and must use the narrowest safe tool.
|
|
22
|
+
8. Branch deletion, tag deletion, force push, and history rewrite require separate explicit authorization and affected-ref verification. The absolute prohibitions in Rule 5 remain prohibited even when such authorization exists.
|
|
23
23
|
9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
|
|
24
24
|
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, release tools, browser automation, DevTools, Playwright, crawlers, notebooks, desktop app automation, or local helper services, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or registered tool operation references for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
|
|
25
25
|
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
|
|
@@ -33,6 +33,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
33
33
|
(d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
|
|
34
34
|
13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
|
|
35
35
|
14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, notebook kernels, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, desktop app session, notebook kernel, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
|
|
36
|
+
15. Short-lived localhost validation services: when local HTML / app validation needs a safer fallback after `file://` is blocked, a task-owned loopback static server is allowed only within a bounded project or temp path, bound to localhost / loopback, and used for the current validation task. Record the served root, URL, and evidence collected. Stop the server before completion and verify it is no longer reachable when the runtime allows. Do not leave helper servers running as a convenience, expose them beyond loopback, reuse another agent's server without confirmation, or mutate browser profiles / extension state to make the validation pass.
|
|
36
37
|
|
|
37
38
|
## Checks
|
|
38
39
|
|
|
@@ -40,6 +41,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
40
41
|
- If checks cannot run, state the reason and mark the result unverified.
|
|
41
42
|
- For durable governance changes, update the project index, sync registry, and any human review map if they exist.
|
|
42
43
|
- For external-tool resource cleanup, report the ownership class used: task-owned, agent-managed, shared / user-owned / other-agent-owned / system-level, or unknown.
|
|
44
|
+
- For short-lived localhost validation services, report the served root / URL, evidence collected, and cleanup result or cleanup blocker.
|
|
43
45
|
|
|
44
46
|
## Closeout
|
|
45
47
|
|