@adamchanadam/agent-handoff-kit 0.3.39 → 0.3.40
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +223 -96
- package/bin/migration-baselines/v0.3.38/integrations.md +235 -235
- package/bin/migration-baselines/v0.3.38/onboarding.md +201 -201
- package/bin/prompt-mirror-core.mjs +84 -84
- package/package.json +20 -31
- 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/packs/onboarding.md
CHANGED
|
@@ -1,214 +1,214 @@
|
|
|
1
|
-
# Onboarding Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
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
|
-
|
|
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
|
-
|
|
9
|
-
## Load When
|
|
10
|
-
|
|
11
|
-
### Explicit onboarding signal keywords
|
|
12
|
-
|
|
13
|
-
Load this pack when the user message contains an onboarding signal such as:
|
|
14
|
-
|
|
15
|
-
- "I'm new" / "new user"
|
|
16
|
-
- "teach me" / "help me start" / "help me get started"
|
|
17
|
-
- "first time" / "first-time" when the user also asks for guidance
|
|
18
|
-
- "how do I start" / "show me how" / "getting started"
|
|
19
|
-
- "what can agent handoff kit do"
|
|
20
|
-
- vague project intent such as "I want to do a project"
|
|
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.
|
|
28
|
-
|
|
29
|
-
### Implicit signals
|
|
30
|
-
|
|
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.
|
|
33
|
-
- The user asks a generic capability question instead of giving a concrete task.
|
|
34
|
-
- The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
|
|
35
|
-
|
|
36
|
-
## Discipline
|
|
37
|
-
|
|
38
|
-
### 1. Do not assume prior reading
|
|
39
|
-
|
|
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.
|
|
41
|
-
|
|
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.
|
|
49
|
-
|
|
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.
|
|
51
|
-
|
|
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.
|
|
53
|
-
|
|
54
|
-
- **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.
|
|
55
|
-
- **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.
|
|
56
|
-
- **C. Organize local files, Notion, Google Drive, or a knowledge base**: the user wants source, reference, mirror, and draft material kept clear.
|
|
57
|
-
- **D. Learn to code**: the user is a technical beginner and wants a small guided exercise.
|
|
58
|
-
- **E. Custom scenario**: the user has another goal.
|
|
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.
|
|
60
|
-
|
|
61
|
-
### 3. Guided 5-step walk-through pattern
|
|
62
|
-
|
|
63
|
-
Use this five-step path only after the user selects guided onboarding or when clarification is genuinely needed:
|
|
64
|
-
|
|
65
|
-
1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.
|
|
66
|
-
2. Explain in three plain points how Agent Handoff Kit helps this scenario.
|
|
67
|
-
3. Ask for the first concrete task scope, offering at most two or three genuinely relevant options.
|
|
68
|
-
4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.
|
|
69
|
-
5. Wait for user confirmation, then transition to the regular work loop.
|
|
70
|
-
|
|
71
|
-
### 4. Ask only for missing information
|
|
72
|
-
|
|
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:
|
|
74
|
-
|
|
75
|
-
- state what the AI will do,
|
|
76
|
-
- state what the user needs to answer or confirm,
|
|
77
|
-
- answer questions before continuing,
|
|
78
|
-
- let the user skip or change the step.
|
|
79
|
-
|
|
80
|
-
### 5. Keep the first task small
|
|
81
|
-
|
|
82
|
-
The first task should be a preview, a short draft, a small classification sample, a dry-run, or another bounded result. Do not begin with broad refactors, bulk file moves, publishing, deployment, or destructive operations.
|
|
83
|
-
|
|
84
|
-
### 6. Transition after onboarding
|
|
85
|
-
|
|
86
|
-
After the walk-through:
|
|
87
|
-
|
|
88
|
-
- load the regular pack(s) for the chosen task,
|
|
89
|
-
- unload this transient onboarding pack,
|
|
90
|
-
- enter the PLAN -> READ -> CHANGE -> QC -> PERSIST work loop,
|
|
91
|
-
- record the first-task scope in `SESSION_HANDOFF` when the persistence gate requires it.
|
|
92
|
-
|
|
93
|
-
## Application Scenario Library
|
|
94
|
-
|
|
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.
|
|
96
|
-
|
|
97
|
-
### Scenario A. Build systems, tools, platforms, websites, or apps
|
|
98
|
-
|
|
99
|
-
Step A.1: ask for the project folder, current stack if known, whether git exists, and whether GitHub, Linear, Slack, Notion, Google Drive, or other external tools are connected.
|
|
100
|
-
|
|
101
|
-
Step A.2: explain that Kit helps the AI remember project state across sessions, avoid silent risky commands, and record what changed at closeout.
|
|
102
|
-
|
|
103
|
-
Step A.3: offer task choices such as fix a bug, add a feature, organize code, add tests, write README, or prepare a first commit.
|
|
104
|
-
|
|
105
|
-
Step A.4: suggest a small first task, such as a short README section, one failing test investigation, or a dry-run plan.
|
|
106
|
-
|
|
107
|
-
Step A.5: after confirmation, load the relevant coding / writing / safety packs and begin the normal work loop.
|
|
108
|
-
|
|
109
|
-
### Scenario B. Organize research or write a report
|
|
110
|
-
|
|
111
|
-
Step B.1: ask for the topic, existing source locations, intended reader, and whether Notion, Google Drive, or another source tool is connected.
|
|
112
|
-
|
|
113
|
-
Step B.2: explain that Kit separates source evidence from inference, records source locations, and preserves progress across sessions.
|
|
114
|
-
|
|
115
|
-
Step B.3: offer task choices such as outline sections, register sources, summarize one source, draft a subsection, or review an existing draft.
|
|
116
|
-
|
|
117
|
-
Step B.4: suggest a small first task, such as a 5-7 heading outline with one sentence per section.
|
|
118
|
-
|
|
119
|
-
Step B.5: after confirmation, load research / writing / knowledge packs and begin the normal work loop.
|
|
120
|
-
|
|
121
|
-
### Scenario C. Organize local files, Notion, Google Drive, or a knowledge base
|
|
122
|
-
|
|
123
|
-
Step C.1: ask what needs organizing: local folder, Notion database, Google Drive folder, or mixed sources. Ask which external tools are connected or unknown.
|
|
124
|
-
|
|
125
|
-
Step C.2: explain that Kit separates source of truth, references, mirrors, and drafts, and that risky file operations require dry-run and confirmation.
|
|
126
|
-
|
|
127
|
-
Step C.3: offer task choices such as scan and classify files, design a folder structure, draft a Notion schema, write a dry-run script, or align local references with an external index.
|
|
128
|
-
|
|
129
|
-
Step C.4: suggest a small first task, such as classifying a bounded sample without moving files.
|
|
130
|
-
|
|
131
|
-
Step C.5: after confirmation, load knowledge / safety / integrations packs as needed.
|
|
132
|
-
|
|
133
|
-
### Scenario D. Learn to code
|
|
134
|
-
|
|
135
|
-
Step D.1: ask which direction the user wants: small automation, web page, Python tool, Git / GitHub basics, or another beginner task. Ask whether any relevant tools are already installed.
|
|
136
|
-
|
|
137
|
-
Step D.2: explain that Kit keeps learning progress across sessions, keeps risky operations explicit, and lets the user review each small change.
|
|
138
|
-
|
|
139
|
-
Step D.3: offer one small exercise, such as a dry-run file renamer, a one-page HTML example, or a tiny Python script.
|
|
140
|
-
|
|
141
|
-
Step D.4: keep the exercise small enough to explain line by line.
|
|
142
|
-
|
|
143
|
-
Step D.5: after confirmation, load coding / safety packs and begin the normal work loop.
|
|
144
|
-
|
|
145
|
-
### Scenario E. Custom scenario
|
|
146
|
-
|
|
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.
|
|
148
|
-
|
|
149
|
-
Step E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.
|
|
150
|
-
|
|
151
|
-
Step E.3: offer task choices tailored to the user's answer.
|
|
152
|
-
|
|
153
|
-
Step E.4: suggest one minimum viable first task.
|
|
154
|
-
|
|
155
|
-
Step E.5: after confirmation, load the appropriate regular pack combination.
|
|
156
|
-
|
|
157
|
-
### Scenario F. External-tool governance
|
|
158
|
-
|
|
159
|
-
Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
|
|
160
|
-
|
|
161
|
-
Step F.1: collect installed external tools by category: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. If the user does not know the category, ask for names only and classify them.
|
|
162
|
-
|
|
163
|
-
Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
|
|
164
|
-
|
|
165
|
-
Step F.3: map source-of-truth architecture: source of truth, index, persistent mirror, and working draft. Make each layer's write boundary explicit.
|
|
166
|
-
|
|
167
|
-
Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
|
|
168
|
-
|
|
169
|
-
Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. Mark unavailable tools as blocked / unverified instead of guessing.
|
|
170
|
-
|
|
171
|
-
## Cross-reference to guide.html
|
|
172
|
-
|
|
173
|
-
When the user asks for a fuller example, mention `agent-handoff-kit-guide.html` as an optional reference. The guide is not required reading.
|
|
174
|
-
|
|
175
|
-
- Case A aligns with Scenario A plus parts of Scenario C.
|
|
176
|
-
- Case B aligns with Scenario B plus Scenario F.
|
|
177
|
-
- Case C aligns with long-running project evolution.
|
|
178
|
-
|
|
179
|
-
## Tone Discipline
|
|
180
|
-
|
|
181
|
-
Use plain user-facing language. Avoid internal jargon in onboarding replies unless the user asks for implementation details.
|
|
182
|
-
|
|
183
|
-
- Say "project registry" before exposing `PROJECT_INDEX`.
|
|
184
|
-
- Say "wrap up" or the user's own closeout phrase before exposing closeout internals.
|
|
185
|
-
- Say "next-session startup message" only when discussing the persisted handoff file.
|
|
186
|
-
- Say "working mode" before exposing "rule pack".
|
|
187
|
-
- Say "risky command" before exposing "destructive operation".
|
|
188
|
-
|
|
189
|
-
Keep user-facing explanations self-contained. For the public product's Chinese surfaces, use steady written Traditional Chinese and avoid Cantonese spoken characters. Inside this AI-facing pack, keep instructions in English and use Chinese only as quoted user phrases that the runtime must recognize.
|
|
190
|
-
|
|
191
|
-
## Closeout
|
|
192
|
-
|
|
193
|
-
After onboarding finishes:
|
|
194
|
-
|
|
195
|
-
1. Confirm that the user knows the next practical action, how to start a later session, and how to request closeout.
|
|
196
|
-
2. Update `SESSION_HANDOFF` only when the persistence gate says the first-task scope or next action is durable.
|
|
197
|
-
3. Record next priorities only when they affect a later session.
|
|
198
|
-
4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.
|
|
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.
|
|
201
|
-
|
|
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.
|
|
203
|
-
|
|
204
|
-
## Anti-patterns
|
|
205
|
-
|
|
206
|
-
| Anti-pattern | Why it is wrong | Correct approach |
|
|
207
|
-
|---|---|---|
|
|
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. |
|
|
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. |
|
|
210
|
-
| Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |
|
|
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. |
|
|
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). |
|
|
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. |
|
|
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. |
|
|
1
|
+
# Onboarding Pack
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
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
|
+
|
|
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
|
+
|
|
9
|
+
## Load When
|
|
10
|
+
|
|
11
|
+
### Explicit onboarding signal keywords
|
|
12
|
+
|
|
13
|
+
Load this pack when the user message contains an onboarding signal such as:
|
|
14
|
+
|
|
15
|
+
- "I'm new" / "new user"
|
|
16
|
+
- "teach me" / "help me start" / "help me get started"
|
|
17
|
+
- "first time" / "first-time" when the user also asks for guidance
|
|
18
|
+
- "how do I start" / "show me how" / "getting started"
|
|
19
|
+
- "what can agent handoff kit do"
|
|
20
|
+
- vague project intent such as "I want to do a project"
|
|
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.
|
|
28
|
+
|
|
29
|
+
### Implicit signals
|
|
30
|
+
|
|
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.
|
|
33
|
+
- The user asks a generic capability question instead of giving a concrete task.
|
|
34
|
+
- The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
|
|
35
|
+
|
|
36
|
+
## Discipline
|
|
37
|
+
|
|
38
|
+
### 1. Do not assume prior reading
|
|
39
|
+
|
|
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.
|
|
41
|
+
|
|
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.
|
|
49
|
+
|
|
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.
|
|
51
|
+
|
|
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.
|
|
53
|
+
|
|
54
|
+
- **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.
|
|
55
|
+
- **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.
|
|
56
|
+
- **C. Organize local files, Notion, Google Drive, or a knowledge base**: the user wants source, reference, mirror, and draft material kept clear.
|
|
57
|
+
- **D. Learn to code**: the user is a technical beginner and wants a small guided exercise.
|
|
58
|
+
- **E. Custom scenario**: the user has another goal.
|
|
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.
|
|
60
|
+
|
|
61
|
+
### 3. Guided 5-step walk-through pattern
|
|
62
|
+
|
|
63
|
+
Use this five-step path only after the user selects guided onboarding or when clarification is genuinely needed:
|
|
64
|
+
|
|
65
|
+
1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.
|
|
66
|
+
2. Explain in three plain points how Agent Handoff Kit helps this scenario.
|
|
67
|
+
3. Ask for the first concrete task scope, offering at most two or three genuinely relevant options.
|
|
68
|
+
4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.
|
|
69
|
+
5. Wait for user confirmation, then transition to the regular work loop.
|
|
70
|
+
|
|
71
|
+
### 4. Ask only for missing information
|
|
72
|
+
|
|
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:
|
|
74
|
+
|
|
75
|
+
- state what the AI will do,
|
|
76
|
+
- state what the user needs to answer or confirm,
|
|
77
|
+
- answer questions before continuing,
|
|
78
|
+
- let the user skip or change the step.
|
|
79
|
+
|
|
80
|
+
### 5. Keep the first task small
|
|
81
|
+
|
|
82
|
+
The first task should be a preview, a short draft, a small classification sample, a dry-run, or another bounded result. Do not begin with broad refactors, bulk file moves, publishing, deployment, or destructive operations.
|
|
83
|
+
|
|
84
|
+
### 6. Transition after onboarding
|
|
85
|
+
|
|
86
|
+
After the walk-through:
|
|
87
|
+
|
|
88
|
+
- load the regular pack(s) for the chosen task,
|
|
89
|
+
- unload this transient onboarding pack,
|
|
90
|
+
- enter the PLAN -> READ -> CHANGE -> QC -> PERSIST work loop,
|
|
91
|
+
- record the first-task scope in `SESSION_HANDOFF` when the persistence gate requires it.
|
|
92
|
+
|
|
93
|
+
## Application Scenario Library
|
|
94
|
+
|
|
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.
|
|
96
|
+
|
|
97
|
+
### Scenario A. Build systems, tools, platforms, websites, or apps
|
|
98
|
+
|
|
99
|
+
Step A.1: ask for the project folder, current stack if known, whether git exists, and whether GitHub, Linear, Slack, Notion, Google Drive, or other external tools are connected.
|
|
100
|
+
|
|
101
|
+
Step A.2: explain that Kit helps the AI remember project state across sessions, avoid silent risky commands, and record what changed at closeout.
|
|
102
|
+
|
|
103
|
+
Step A.3: offer task choices such as fix a bug, add a feature, organize code, add tests, write README, or prepare a first commit.
|
|
104
|
+
|
|
105
|
+
Step A.4: suggest a small first task, such as a short README section, one failing test investigation, or a dry-run plan.
|
|
106
|
+
|
|
107
|
+
Step A.5: after confirmation, load the relevant coding / writing / safety packs and begin the normal work loop.
|
|
108
|
+
|
|
109
|
+
### Scenario B. Organize research or write a report
|
|
110
|
+
|
|
111
|
+
Step B.1: ask for the topic, existing source locations, intended reader, and whether Notion, Google Drive, or another source tool is connected.
|
|
112
|
+
|
|
113
|
+
Step B.2: explain that Kit separates source evidence from inference, records source locations, and preserves progress across sessions.
|
|
114
|
+
|
|
115
|
+
Step B.3: offer task choices such as outline sections, register sources, summarize one source, draft a subsection, or review an existing draft.
|
|
116
|
+
|
|
117
|
+
Step B.4: suggest a small first task, such as a 5-7 heading outline with one sentence per section.
|
|
118
|
+
|
|
119
|
+
Step B.5: after confirmation, load research / writing / knowledge packs and begin the normal work loop.
|
|
120
|
+
|
|
121
|
+
### Scenario C. Organize local files, Notion, Google Drive, or a knowledge base
|
|
122
|
+
|
|
123
|
+
Step C.1: ask what needs organizing: local folder, Notion database, Google Drive folder, or mixed sources. Ask which external tools are connected or unknown.
|
|
124
|
+
|
|
125
|
+
Step C.2: explain that Kit separates source of truth, references, mirrors, and drafts, and that risky file operations require dry-run and confirmation.
|
|
126
|
+
|
|
127
|
+
Step C.3: offer task choices such as scan and classify files, design a folder structure, draft a Notion schema, write a dry-run script, or align local references with an external index.
|
|
128
|
+
|
|
129
|
+
Step C.4: suggest a small first task, such as classifying a bounded sample without moving files.
|
|
130
|
+
|
|
131
|
+
Step C.5: after confirmation, load knowledge / safety / integrations packs as needed.
|
|
132
|
+
|
|
133
|
+
### Scenario D. Learn to code
|
|
134
|
+
|
|
135
|
+
Step D.1: ask which direction the user wants: small automation, web page, Python tool, Git / GitHub basics, or another beginner task. Ask whether any relevant tools are already installed.
|
|
136
|
+
|
|
137
|
+
Step D.2: explain that Kit keeps learning progress across sessions, keeps risky operations explicit, and lets the user review each small change.
|
|
138
|
+
|
|
139
|
+
Step D.3: offer one small exercise, such as a dry-run file renamer, a one-page HTML example, or a tiny Python script.
|
|
140
|
+
|
|
141
|
+
Step D.4: keep the exercise small enough to explain line by line.
|
|
142
|
+
|
|
143
|
+
Step D.5: after confirmation, load coding / safety packs and begin the normal work loop.
|
|
144
|
+
|
|
145
|
+
### Scenario E. Custom scenario
|
|
146
|
+
|
|
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.
|
|
148
|
+
|
|
149
|
+
Step E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.
|
|
150
|
+
|
|
151
|
+
Step E.3: offer task choices tailored to the user's answer.
|
|
152
|
+
|
|
153
|
+
Step E.4: suggest one minimum viable first task.
|
|
154
|
+
|
|
155
|
+
Step E.5: after confirmation, load the appropriate regular pack combination.
|
|
156
|
+
|
|
157
|
+
### Scenario F. External-tool governance
|
|
158
|
+
|
|
159
|
+
Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
|
|
160
|
+
|
|
161
|
+
Step F.1: collect installed external tools by category: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. If the user does not know the category, ask for names only and classify them.
|
|
162
|
+
|
|
163
|
+
Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
|
|
164
|
+
|
|
165
|
+
Step F.3: map source-of-truth architecture: source of truth, index, persistent mirror, and working draft. Make each layer's write boundary explicit.
|
|
166
|
+
|
|
167
|
+
Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
|
|
168
|
+
|
|
169
|
+
Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. Mark unavailable tools as blocked / unverified instead of guessing.
|
|
170
|
+
|
|
171
|
+
## Cross-reference to guide.html
|
|
172
|
+
|
|
173
|
+
When the user asks for a fuller example, mention `agent-handoff-kit-guide.html` as an optional reference. The guide is not required reading.
|
|
174
|
+
|
|
175
|
+
- Case A aligns with Scenario A plus parts of Scenario C.
|
|
176
|
+
- Case B aligns with Scenario B plus Scenario F.
|
|
177
|
+
- Case C aligns with long-running project evolution.
|
|
178
|
+
|
|
179
|
+
## Tone Discipline
|
|
180
|
+
|
|
181
|
+
Use plain user-facing language. Avoid internal jargon in onboarding replies unless the user asks for implementation details.
|
|
182
|
+
|
|
183
|
+
- Say "project registry" before exposing `PROJECT_INDEX`.
|
|
184
|
+
- Say "wrap up" or the user's own closeout phrase before exposing closeout internals.
|
|
185
|
+
- Say "next-session startup message" only when discussing the persisted handoff file.
|
|
186
|
+
- Say "working mode" before exposing "rule pack".
|
|
187
|
+
- Say "risky command" before exposing "destructive operation".
|
|
188
|
+
|
|
189
|
+
Keep user-facing explanations self-contained. For the public product's Chinese surfaces, use steady written Traditional Chinese and avoid Cantonese spoken characters. Inside this AI-facing pack, keep instructions in English and use Chinese only as quoted user phrases that the runtime must recognize.
|
|
190
|
+
|
|
191
|
+
## Closeout
|
|
192
|
+
|
|
193
|
+
After onboarding finishes:
|
|
194
|
+
|
|
195
|
+
1. Confirm that the user knows the next practical action, how to start a later session, and how to request closeout.
|
|
196
|
+
2. Update `SESSION_HANDOFF` only when the persistence gate says the first-task scope or next action is durable.
|
|
197
|
+
3. Record next priorities only when they affect a later session.
|
|
198
|
+
4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.
|
|
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.
|
|
201
|
+
|
|
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.
|
|
203
|
+
|
|
204
|
+
## Anti-patterns
|
|
205
|
+
|
|
206
|
+
| Anti-pattern | Why it is wrong | Correct approach |
|
|
207
|
+
|---|---|---|
|
|
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. |
|
|
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. |
|
|
210
|
+
| Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |
|
|
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. |
|
|
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). |
|
|
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. |
|
|
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/release.md
CHANGED
|
@@ -1,28 +1,28 @@
|
|
|
1
|
-
# Release Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for release, publish, deploy, tag, version bump, hotfix, or GA completion claims.
|
|
6
|
-
|
|
7
|
-
## Load When
|
|
8
|
-
|
|
9
|
-
- User asks to publish, deploy, tag, release, upload, announce, or mark work as production-ready.
|
|
10
|
-
- A task changes package metadata, changelog, release notes, or distribution artifacts.
|
|
11
|
-
|
|
12
|
-
## Rules
|
|
13
|
-
|
|
14
|
-
1. Treat release claims as evidence-bound.
|
|
15
|
-
2. Verify version, target branch, commit, artifacts, release notes, and public docs before claiming completion.
|
|
16
|
-
3. Do not publish, deploy, tag, or upload without explicit user approval.
|
|
17
|
-
4. Keep rollback or recovery notes when release risk is non-trivial.
|
|
18
|
-
5. Preserve migration and upgrade safety for existing users.
|
|
19
|
-
|
|
20
|
-
## Checks
|
|
21
|
-
|
|
22
|
-
- Run build/test/package checks required by `dev/PROJECT_INDEX.md`.
|
|
23
|
-
- Check README, changelog, migration notes, and `dev/DOC_SYNC_REGISTRY.md`.
|
|
24
|
-
- Record exact command results or blockers.
|
|
25
|
-
|
|
26
|
-
## Closeout
|
|
27
|
-
|
|
28
|
-
Record release status, version, commit, artifacts, verification evidence, blocked items, and post-release follow-up.
|
|
1
|
+
# Release Pack
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for release, publish, deploy, tag, version bump, hotfix, or GA completion claims.
|
|
6
|
+
|
|
7
|
+
## Load When
|
|
8
|
+
|
|
9
|
+
- User asks to publish, deploy, tag, release, upload, announce, or mark work as production-ready.
|
|
10
|
+
- A task changes package metadata, changelog, release notes, or distribution artifacts.
|
|
11
|
+
|
|
12
|
+
## Rules
|
|
13
|
+
|
|
14
|
+
1. Treat release claims as evidence-bound.
|
|
15
|
+
2. Verify version, target branch, commit, artifacts, release notes, and public docs before claiming completion.
|
|
16
|
+
3. Do not publish, deploy, tag, or upload without explicit user approval.
|
|
17
|
+
4. Keep rollback or recovery notes when release risk is non-trivial.
|
|
18
|
+
5. Preserve migration and upgrade safety for existing users.
|
|
19
|
+
|
|
20
|
+
## Checks
|
|
21
|
+
|
|
22
|
+
- Run build/test/package checks required by `dev/PROJECT_INDEX.md`.
|
|
23
|
+
- Check README, changelog, migration notes, and `dev/DOC_SYNC_REGISTRY.md`.
|
|
24
|
+
- Record exact command results or blockers.
|
|
25
|
+
|
|
26
|
+
## Closeout
|
|
27
|
+
|
|
28
|
+
Record release status, version, commit, artifacts, verification evidence, blocked items, and post-release follow-up.
|
package/packs/research.md
CHANGED
|
@@ -1,30 +1,30 @@
|
|
|
1
|
-
# Research Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
|
|
6
|
-
|
|
7
|
-
## Load When
|
|
8
|
-
|
|
9
|
-
- User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
|
|
10
|
-
- The topic may have changed recently or needs precise attribution.
|
|
11
|
-
|
|
12
|
-
## Rules
|
|
13
|
-
|
|
14
|
-
1. Prefer primary sources, official docs, papers, standards, or direct data when available.
|
|
15
|
-
2. Separate verified facts, source summaries, and inference.
|
|
16
|
-
3. Record dates for time-sensitive facts.
|
|
17
|
-
4. Do not overstate confidence when sources conflict or coverage is thin.
|
|
18
|
-
5. Keep source quotes short and cite where evidence came from.
|
|
19
|
-
|
|
20
|
-
## Checks
|
|
21
|
-
|
|
22
|
-
- Confirm source relevance, date, and authority.
|
|
23
|
-
- Cross-check important claims with more than one source when practical.
|
|
24
|
-
- Record open questions or unverified claims.
|
|
25
|
-
|
|
26
|
-
## Closeout
|
|
27
|
-
|
|
28
|
-
Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
|
|
29
|
-
|
|
30
|
-
If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
|
|
1
|
+
# Research Pack
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
|
|
6
|
+
|
|
7
|
+
## Load When
|
|
8
|
+
|
|
9
|
+
- User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
|
|
10
|
+
- The topic may have changed recently or needs precise attribution.
|
|
11
|
+
|
|
12
|
+
## Rules
|
|
13
|
+
|
|
14
|
+
1. Prefer primary sources, official docs, papers, standards, or direct data when available.
|
|
15
|
+
2. Separate verified facts, source summaries, and inference.
|
|
16
|
+
3. Record dates for time-sensitive facts.
|
|
17
|
+
4. Do not overstate confidence when sources conflict or coverage is thin.
|
|
18
|
+
5. Keep source quotes short and cite where evidence came from.
|
|
19
|
+
|
|
20
|
+
## Checks
|
|
21
|
+
|
|
22
|
+
- Confirm source relevance, date, and authority.
|
|
23
|
+
- Cross-check important claims with more than one source when practical.
|
|
24
|
+
- Record open questions or unverified claims.
|
|
25
|
+
|
|
26
|
+
## Closeout
|
|
27
|
+
|
|
28
|
+
Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
|
|
29
|
+
|
|
30
|
+
If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
|