@clue-ai/cli 0.0.8 → 0.0.9
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/package.json +1 -1
- package/src/contracts.mjs +132 -127
- package/src/lifecycle-init.mjs +184 -179
- package/src/public-schema.cjs +4 -0
- package/src/setup-check.mjs +3 -1
- package/src/setup-tool.mjs +388 -375
package/src/setup-tool.mjs
CHANGED
|
@@ -3,406 +3,419 @@ import { join, resolve } from "node:path";
|
|
|
3
3
|
import readline from "node:readline/promises";
|
|
4
4
|
|
|
5
5
|
const SKILL_NAMES = [
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
6
|
+
"clue-setup-orchestrator",
|
|
7
|
+
"clue-route-semantic-snapshot",
|
|
8
|
+
"clue-semantic-gen",
|
|
9
|
+
"clue-sdk-instrumentation",
|
|
10
|
+
"clue-setup-audit",
|
|
11
|
+
"clue-local-verification",
|
|
12
|
+
"clue-setup-report",
|
|
13
13
|
];
|
|
14
14
|
|
|
15
15
|
const TARGETS = new Set(["codex", "claude_code"]);
|
|
16
16
|
|
|
17
17
|
const TARGET_SKILL_ROOTS = {
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
codex: [".agents", "skills"],
|
|
19
|
+
claude_code: [".claude", "skills"],
|
|
20
20
|
};
|
|
21
21
|
|
|
22
22
|
const normalizeTarget = (target) => {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
23
|
+
const normalized = String(target ?? "")
|
|
24
|
+
.trim()
|
|
25
|
+
.toLowerCase()
|
|
26
|
+
.replace(/[\s-]+/g, "_");
|
|
27
|
+
if (!TARGETS.has(normalized)) {
|
|
28
|
+
throw new Error("AIツールは codex または claude_code を指定してください");
|
|
29
|
+
}
|
|
30
|
+
return normalized;
|
|
31
31
|
};
|
|
32
32
|
|
|
33
33
|
const skillBody = (name) => {
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
34
|
+
const descriptions = {
|
|
35
|
+
"clue-setup-orchestrator":
|
|
36
|
+
"Use first when running the full Clue setup so one execution agent per implementation workstream and multiple monitoring agents coordinate separate setup phases.",
|
|
37
|
+
"clue-route-semantic-snapshot":
|
|
38
|
+
"Use when checking backend route coverage and semantic snapshot readiness without hand-authoring generated snapshot files.",
|
|
39
|
+
"clue-semantic-gen":
|
|
40
|
+
"Use when adding or updating Clue semantic snapshot CI for this repository.",
|
|
41
|
+
"clue-sdk-instrumentation":
|
|
42
|
+
"Use when adding ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout lifecycle calls to a customer repository.",
|
|
43
|
+
"clue-setup-audit":
|
|
44
|
+
"Use when reviewing Clue setup changes for missing lifecycle calls, unsafe instrumentation, leaked secrets, or bad insertion points.",
|
|
45
|
+
"clue-local-verification":
|
|
46
|
+
"Use when verifying local Clue setup artifacts before checking event delivery in the Clue setup screen.",
|
|
47
|
+
"clue-setup-report":
|
|
48
|
+
"Use when producing the final Clue setup report with changed files, blockers, env names, and next steps.",
|
|
49
|
+
};
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
51
|
+
const agentRoles = {
|
|
52
|
+
"clue-setup-orchestrator":
|
|
53
|
+
"Coordinator agent. Owns sequencing, agent assignment, gates, and blocker handling. It must not edit product code directly.",
|
|
54
|
+
"clue-route-semantic-snapshot":
|
|
55
|
+
"Semantic route readiness agent. Owns backend route inventory/readiness validation only. It must not author generated snapshot content or SDK code.",
|
|
56
|
+
"clue-semantic-gen":
|
|
57
|
+
"Semantic generation CI agent. Owns machine-owned CI workflow verification/refresh only. It must not hand-write snapshot content or SDK lifecycle code.",
|
|
58
|
+
"clue-sdk-instrumentation":
|
|
59
|
+
"SDK lifecycle implementation agent. Owns Clue SDK dependency, initialization, and lifecycle call implementation only.",
|
|
60
|
+
"clue-setup-audit":
|
|
61
|
+
"Read-only monitoring agent. Owns P0/P1 review for one completed workstream at a time. It must not edit files.",
|
|
62
|
+
"clue-local-verification":
|
|
63
|
+
"Read-only verification agent. Owns setup-check/setup-watch evidence and local verification readiness. It must not edit files.",
|
|
64
|
+
"clue-setup-report":
|
|
65
|
+
"Final reporting agent. Owns concise completion evidence only after execution and monitoring gates pass.",
|
|
66
|
+
};
|
|
67
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
68
|
+
const owns = {
|
|
69
|
+
"clue-setup-orchestrator": [
|
|
70
|
+
"read `.clue/setup-manifest.json` first",
|
|
71
|
+
"assign exactly one execution agent per implementation workstream",
|
|
72
|
+
"assign multiple read-only monitoring agents",
|
|
73
|
+
"stop on manifest blockers or P0/P1 findings",
|
|
74
|
+
],
|
|
75
|
+
"clue-route-semantic-snapshot": [
|
|
76
|
+
"backend route discovery readiness",
|
|
77
|
+
"route coverage gaps and unsupported-framework blockers",
|
|
78
|
+
"privacy-safe evidence needed by semantic generation",
|
|
79
|
+
],
|
|
80
|
+
"clue-semantic-gen": [
|
|
81
|
+
"`.github/workflows/clue-semantic-snapshot.yml` generated workflow shape",
|
|
82
|
+
"`semantic-gen` command wiring",
|
|
83
|
+
"GitHub secrets/variables referenced by name only",
|
|
84
|
+
"privacy boundary between customer repo CI and Clue API",
|
|
85
|
+
],
|
|
86
|
+
"clue-sdk-instrumentation": [
|
|
87
|
+
"real Clue SDK imports/dependencies",
|
|
88
|
+
"ClueInit bootstrap placement",
|
|
89
|
+
"ClueIdentify login-success coverage",
|
|
90
|
+
"ClueSetAccount account/workspace/tenant coverage",
|
|
91
|
+
"ClueLogout logout/session-reset coverage",
|
|
92
|
+
"failure isolation so host behavior never depends on Clue success",
|
|
93
|
+
],
|
|
94
|
+
"clue-setup-audit": [
|
|
95
|
+
"line-by-line diff review",
|
|
96
|
+
"responsibility boundary checks",
|
|
97
|
+
"P0/P1 findings before the next workstream continues",
|
|
98
|
+
],
|
|
99
|
+
"clue-local-verification": [
|
|
100
|
+
"`setup-check` evidence",
|
|
101
|
+
"`setup-watch --local` readiness",
|
|
102
|
+
"local URL confirmation without assuming ports",
|
|
103
|
+
],
|
|
104
|
+
"clue-setup-report": [
|
|
105
|
+
"changed files",
|
|
106
|
+
"commands run",
|
|
107
|
+
"skills and agents used",
|
|
108
|
+
"remaining blockers and required env names",
|
|
109
|
+
],
|
|
110
|
+
};
|
|
111
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
|
-
|
|
112
|
+
const mustNot = {
|
|
113
|
+
"clue-setup-orchestrator": [
|
|
114
|
+
"do product-code implementation itself",
|
|
115
|
+
"merge workstreams into one broad task",
|
|
116
|
+
"continue after a blocker without reporting it",
|
|
117
|
+
],
|
|
118
|
+
"clue-route-semantic-snapshot": [
|
|
119
|
+
"create SDK lifecycle calls",
|
|
120
|
+
"create or edit the CI workflow",
|
|
121
|
+
"hand-author generated semantic snapshot content",
|
|
122
|
+
],
|
|
123
|
+
"clue-semantic-gen": [
|
|
124
|
+
"inspect `.env` or secret files",
|
|
125
|
+
"send raw source files, prompts, completions, or secret values to Clue",
|
|
126
|
+
"hand-edit generated snapshot content",
|
|
127
|
+
],
|
|
128
|
+
"clue-sdk-instrumentation": [
|
|
129
|
+
"create no-op wrappers or placeholder lifecycle functions",
|
|
130
|
+
"place ClueInit on repeated UI/request paths",
|
|
131
|
+
"block login/logout/account/request flows on Clue success",
|
|
132
|
+
"guess service keys or ports",
|
|
133
|
+
],
|
|
134
|
+
"clue-setup-audit": [
|
|
135
|
+
"make edits",
|
|
136
|
+
"approve unclear lifecycle points",
|
|
137
|
+
"approve secret values in code, diff, or report",
|
|
138
|
+
],
|
|
139
|
+
"clue-local-verification": [
|
|
140
|
+
"make edits",
|
|
141
|
+
"assume localhost ports",
|
|
142
|
+
"treat setup-watch as complete before every expected implemented lifecycle check passes or is reported blocked",
|
|
143
|
+
],
|
|
144
|
+
"clue-setup-report": [
|
|
145
|
+
"claim complete with unverified workstreams",
|
|
146
|
+
"include secret values",
|
|
147
|
+
"hide blockers or skipped checks",
|
|
148
|
+
],
|
|
149
|
+
};
|
|
150
150
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
151
|
+
const outputs = {
|
|
152
|
+
"clue-setup-orchestrator": [
|
|
153
|
+
"agent plan with execution agents, monitoring agents, file ownership, and gate order",
|
|
154
|
+
"blocker list if setup cannot proceed",
|
|
155
|
+
],
|
|
156
|
+
"clue-route-semantic-snapshot": [
|
|
157
|
+
"route readiness result: ready or blocked",
|
|
158
|
+
"route coverage evidence and blocker details",
|
|
159
|
+
],
|
|
160
|
+
"clue-semantic-gen": [
|
|
161
|
+
"CI workflow verification result",
|
|
162
|
+
"whether regeneration was required and which command was used",
|
|
163
|
+
],
|
|
164
|
+
"clue-sdk-instrumentation": [
|
|
165
|
+
"implemented lifecycle locations",
|
|
166
|
+
"dependency/import changes",
|
|
167
|
+
"tests or verification commands",
|
|
168
|
+
],
|
|
169
|
+
"clue-setup-audit": [
|
|
170
|
+
"P0/P1 findings with file references",
|
|
171
|
+
"approval or blocked status for the reviewed workstream",
|
|
172
|
+
],
|
|
173
|
+
"clue-local-verification": [
|
|
174
|
+
"setup-check/setup-watch command evidence",
|
|
175
|
+
"passed, blocked, or cannot-run status with reasons",
|
|
176
|
+
],
|
|
177
|
+
"clue-setup-report": [
|
|
178
|
+
"final report with changed files, commands, skills, agents, verification, blockers, and env names",
|
|
179
|
+
],
|
|
180
|
+
};
|
|
181
181
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
182
|
+
const steps = {
|
|
183
|
+
"clue-setup-orchestrator": [
|
|
184
|
+
"Use one execution agent per implementation workstream.",
|
|
185
|
+
"Each execution agent owns exactly one workstream and its tests.",
|
|
186
|
+
"Required execution agents: SDK Lifecycle Execution Agent, Semantic Snapshot Readiness Execution Agent, and Semantic Snapshot CI Execution Agent.",
|
|
187
|
+
"Run execution agents in parallel only when file ownership does not conflict; otherwise run them sequentially with monitor gates between workstreams.",
|
|
188
|
+
"Use multiple monitoring agents for read-only checks, or named review passes if subagents are unavailable.",
|
|
189
|
+
"The initial `clue-ai setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment <environment>` command already performs repository discovery, semantic CI workflow generation, setup manifest generation, and writes service-specific environment guidance to `.env.clue` when backend routes can be detected.",
|
|
190
|
+
"Before implementation, read `.clue/setup-manifest.json` and treat it as the mechanical setup source of truth.",
|
|
191
|
+
"Use the service keys and watch targets from `.clue/setup-manifest.json`; do not invent service keys.",
|
|
192
|
+
"If `.clue/setup-manifest.json` has status `blocked`, stop and report its blockers instead of guessing.",
|
|
193
|
+
"Treat only semantic snapshot readiness, semantic snapshot CI, and SDK lifecycle implementation as implementation workstreams with execution agents.",
|
|
194
|
+
"Before each workstream, read and apply the matching Clue setup skill.",
|
|
195
|
+
"After each implementation workstream, run a monitoring check with `clue-setup-audit` before continuing.",
|
|
196
|
+
"For final local verification, read and apply `clue-local-verification`.",
|
|
197
|
+
"For the final report, read and apply `clue-setup-report`.",
|
|
198
|
+
"Do not continue past P0/P1 monitoring findings until fixed or reported as blocked.",
|
|
199
|
+
],
|
|
200
|
+
"clue-route-semantic-snapshot": [
|
|
201
|
+
"Use this skill as the source of truth for semantic snapshot readiness and route coverage verification.",
|
|
202
|
+
"Do not hand-author semantic snapshot content files.",
|
|
203
|
+
"Do not create or commit `.clue/semantic-request.runtime.json`; the semantic CI request must be passed through the generated workflow environment instead of a repository file.",
|
|
204
|
+
"Keep route coverage/readiness checks separate from CI workflow creation and SDK lifecycle implementation.",
|
|
205
|
+
"Do not create CI workflow files or SDK lifecycle calls from this skill.",
|
|
206
|
+
"Do not create or commit `.clue/semantic-routes.json`; route inventory is dynamic and must be recomputed mechanically by `clue-ai semantic-inventory`, `clue-ai setup-check`, or `clue-ai semantic-gen`.",
|
|
207
|
+
"If route inventory must be inspected locally, run `npx @clue-ai/cli semantic-inventory --framework <framework> --backend-root-path <path> --repo .` and review stdout instead of writing a repo file.",
|
|
208
|
+
"Inspect only allowed source paths.",
|
|
209
|
+
"Identify the backend framework, backend root path, route files, controllers, handlers, and route declaration patterns from privacy-safe evidence.",
|
|
210
|
+
"Run `npx @clue-ai/cli semantic-inventory --framework <framework> --backend-root-path <path> --repo .` whenever possible to verify route discovery without AI or secrets.",
|
|
211
|
+
"If `npx` cannot be used in the current environment, use the local `clue-ai semantic-inventory` command equivalent.",
|
|
212
|
+
"Verify that every API route can be discovered from the selected backend root path and that unsupported frameworks are reported as blockers.",
|
|
213
|
+
"The semantic snapshot CI command must mechanically enumerate operation_source_key, method, path_template, route fingerprints, and privacy-safe evidence before AI interpretation.",
|
|
214
|
+
"AI interpretation may summarize each mechanically discovered route, but it must not create missing routes or operation_source_key values.",
|
|
215
|
+
"The expected generated snapshot structure includes route entries with operation_source_key, method/path_template when available, route_summary, route_confidence, confidence_reason, and source_evidence_refs.",
|
|
216
|
+
"The expected generated snapshot structure includes layer_evidence for data effects, side effects, validation, permissions, failures, and component fingerprints when available.",
|
|
217
|
+
"The expected generated snapshot structure includes operation_effects only when target object evidence and domain behavior evidence are sufficient.",
|
|
218
|
+
"The expected generated snapshot structure preserves unresolved_operation_effects with missing_context instead of fabricating unknown operation effects.",
|
|
219
|
+
"Report route coverage gaps, unsupported backend frameworks, and unclear backend roots as blockers instead of guessing.",
|
|
220
|
+
],
|
|
221
|
+
"clue-semantic-gen": [
|
|
222
|
+
"Use this skill as the source of truth for semantic snapshot CI workflow format.",
|
|
223
|
+
"Keep CI workflow creation separate from route coverage/readiness checks and SDK lifecycle implementation.",
|
|
224
|
+
"Do not author semantic snapshot content, runtime request files, or SDK lifecycle calls from this skill.",
|
|
225
|
+
"Treat `.github/workflows/clue-semantic-snapshot.yml` as a machine-owned artifact generated by `clue-ai setup`; do not hand-edit it.",
|
|
226
|
+
"Create or update `.github/workflows/clue-semantic-snapshot.yml` only by running `npx @clue-ai/cli semantic-workflow --framework <framework> --backend-root-path <path> --repo .` when it must be refreshed.",
|
|
227
|
+
"If `npx` cannot be used in the current environment, use the local `clue-ai semantic-workflow` command equivalent instead of hand-writing the workflow.",
|
|
228
|
+
"The workflow must pass `CLUE_SEMANTIC_REQUEST_JSON` through the workflow environment and then call `npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .`.",
|
|
229
|
+
"Do not create, commit, or stage `.clue/semantic-request.runtime.json` in the customer repository.",
|
|
230
|
+
"The workflow must not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
|
|
231
|
+
"The workflow should send only repository id, commit sha, workflow run id, project key variable, service key, framework, source path allowlist, source path denylist, and Clue API base URL variable.",
|
|
232
|
+
"Use minimal GitHub permissions and checkout without persisted credentials when generating the workflow.",
|
|
233
|
+
"Reference GitHub Secrets and Variables by name only.",
|
|
234
|
+
"Required GitHub secrets are `CLUE_API_KEY` and `CLUE_AI_PROVIDER_API_KEY`.",
|
|
235
|
+
"Required GitHub variables are `CLUE_AI_PROVIDER` and `CLUE_AI_MODEL`.",
|
|
236
|
+
"Semantic generation runs inside the customer repository CI with the customer AI provider key; do not send raw source code, prompts, or completions to Clue.",
|
|
237
|
+
"Do not print or commit secret values.",
|
|
238
|
+
],
|
|
239
|
+
"clue-sdk-instrumentation": [
|
|
240
|
+
"Use this skill as the source of truth for Clue SDK lifecycle implementation.",
|
|
241
|
+
"Keep SDK lifecycle implementation separate from semantic snapshot and CI workflow work.",
|
|
242
|
+
"Do not create semantic snapshot content or semantic snapshot CI workflow files from this skill.",
|
|
243
|
+
"Do not create no-op wrappers around nonexistent `window.Clue*` globals or local placeholder functions.",
|
|
244
|
+
"Lifecycle calls must resolve to real Clue SDK imports or a real repository adapter that forwards to the Clue SDK.",
|
|
245
|
+
"Every Clue lifecycle call must be failure-isolated with try/catch, try/except, `.catch`, or an explicit safe Clue helper so Clue failure never stops the host service.",
|
|
246
|
+
"Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
|
|
247
|
+
"Add or report the required SDK dependency instead of fabricating lifecycle APIs.",
|
|
248
|
+
"For frontend code, add the real `@clue-ai/browser-sdk` dependency when missing. Do not invent `clue-js-sdk`, `@clue/browser-sdk`, local placeholder modules, or dynamic imports that hide a missing SDK.",
|
|
249
|
+
"When lifecycle edits are clear, write an exact replacement plan to a temporary local JSON file and apply it with `npx @clue-ai/cli lifecycle-apply --plan <plan-file> --repo .`.",
|
|
250
|
+
"If `npx` cannot be used in the current environment, use the local `clue-ai lifecycle-apply` command equivalent instead of manually applying the exact replacements.",
|
|
251
|
+
"Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
|
|
252
|
+
"Use environment variable names for Clue configuration values; do not paste project keys or API keys into code.",
|
|
253
|
+
"For local env files, use the service-specific env blocks written to `.env.clue` by `clue-ai setup`; do not ask the user to guess `CLUE_SERVICE_KEY`.",
|
|
254
|
+
"For browser code, use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_SERVICE_KEY`, and `CLUE_INGEST_ENDPOINT`. Let the target framework expose or inject those values safely without hard-coding a Next.js-only prefix.",
|
|
255
|
+
"Never put `CLUE_API_KEY` in frontend code, frontend env files, browser bundles, or client-readable config.",
|
|
256
|
+
"When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side `CLUE_API_KEY` and requests `POST /api/v1/ingest/browser-tokens` from Clue.",
|
|
257
|
+
"Configure frontend `ClueInit` with `browserTokenProvider` that calls the local backend token endpoint and returns the token string.",
|
|
258
|
+
"The browser token request must include project key, environment, service key, and the current browser origin; the backend must attach `x-clue-api-key` server-side when calling Clue.",
|
|
259
|
+
"For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT`.",
|
|
260
|
+
"Use `CLUE_SERVICE_KEY` as the canonical local service identifier. Do not ask the user to manage a separate producer id; SDKs should send producer id as the service key for setup verification compatibility.",
|
|
261
|
+
"For frontend code, pass `serviceKey` from `CLUE_SERVICE_KEY` to `ClueInit`. Do not require a separate producer id unless the repository already has one for compatibility.",
|
|
262
|
+
"For Django code, add `clue-django-sdk` to the backend dependency file when missing and use the Django SDK lifecycle helpers.",
|
|
263
|
+
"For other backend frameworks, use the matching Clue backend SDK if one exists; if no backend SDK exists, report a blocker instead of silently frontend-only setup.",
|
|
264
|
+
"Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
|
|
265
|
+
"Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
|
|
266
|
+
"Find the app/bootstrap entrypoint and add ClueInit only when the location is clear.",
|
|
267
|
+
"Place ClueInit in a stable app bootstrap, SDK adapter, or client singleton; do not place ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or other paths that can run repeatedly.",
|
|
268
|
+
"If the repository needs lifecycle calls from UI hooks, import a shared initialized Clue adapter instead of calling ClueInit again.",
|
|
269
|
+
"Find every clear frontend and backend login success path and add ClueIdentify to every one when the user identity is available.",
|
|
270
|
+
"Find every clear frontend and backend account, workspace, organization, or tenant resolution path and add ClueSetAccount to every one when the subject is available.",
|
|
271
|
+
"Find every clear frontend and backend logout/sign-out/session reset completion path and add ClueLogout to every one when the reset point is clear.",
|
|
272
|
+
"Skip unclear lifecycle points and report blockers.",
|
|
273
|
+
],
|
|
274
|
+
"clue-setup-audit": [
|
|
275
|
+
"Act as a read-only monitoring agent, not the execution agent.",
|
|
276
|
+
"Check one completed workstream at a time and report P0/P1 issues before more implementation continues.",
|
|
277
|
+
"Review changed files line by line.",
|
|
278
|
+
"Verify semantic snapshot, semantic CI, and SDK lifecycle responsibilities did not bleed into each other.",
|
|
279
|
+
"Reject hand-authored semantic snapshot content and runtime request files.",
|
|
280
|
+
"Reject semantic CI workflows that were not generated by or equivalent to `clue-ai semantic-workflow`.",
|
|
281
|
+
"Reject semantic CI workflows that send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
|
|
282
|
+
"Reject no-op lifecycle wrappers or lifecycle calls that do not resolve to a real Clue SDK import.",
|
|
283
|
+
"Reject wrong SDK package names. Frontend must use `@clue-ai/browser-sdk`; FastAPI must use `clue-fastapi-sdk`; Django must use `clue-django-sdk`.",
|
|
284
|
+
"Reject backend setup when backend routes exist but no backend Clue SDK dependency/import/init was added.",
|
|
285
|
+
"Reject lifecycle calls that are not failure-isolated; Clue failure must never stop the host service.",
|
|
286
|
+
"Reject setup that covers only one login path when multiple login success paths are clearly present.",
|
|
287
|
+
"Reject ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or any repeated user interaction path.",
|
|
288
|
+
"Reject broad ClueTrack instrumentation and DOM clue tags.",
|
|
289
|
+
"Confirm no project key, API key, secret, or env value appears in diff or report.",
|
|
290
|
+
"Confirm lifecycle insertions are minimal and reviewable.",
|
|
291
|
+
],
|
|
292
|
+
"clue-local-verification": [
|
|
293
|
+
"Act as a read-only monitoring agent for local verification evidence.",
|
|
294
|
+
"Verify each workstream independently before the final setup report.",
|
|
295
|
+
"Confirm generated skill files exist.",
|
|
296
|
+
"Confirm workflow files and SDK lifecycle imports/calls exist when those phases have run.",
|
|
297
|
+
"Confirm backend routes have a backend Clue SDK dependency/import/init when a backend exists.",
|
|
298
|
+
"Confirm install/import readiness separately from static lifecycle checks. `setup-check --require-sdk-lifecycle` is a static source check only and does not prove that npm/pip install, imports, app startup, or event delivery work.",
|
|
299
|
+
"Verify frontend SDK installability/import when frontend lifecycle code was added. Run the repository's package-manager install command when possible, then run a package-manager-level import/build/typecheck command. If this cannot run, report `blocked` or `partially complete`; do not call setup complete.",
|
|
300
|
+
'Verify backend SDK installability/import when backend lifecycle code was added. Run the repository\'s Python dependency install command when possible, then run an import check such as `python -c "import clue_fastapi_sdk"` or `python -c "import clue_django_sdk"` in the target environment. If this cannot run, report `blocked` or `partially complete`; do not call setup complete.',
|
|
301
|
+
"Confirm `.github/workflows/clue-semantic-snapshot.yml` calls `npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON`.",
|
|
302
|
+
"Confirm the semantic workflow does not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
|
|
303
|
+
"Confirm `.clue/semantic-request.runtime.json` is not created, committed, or staged.",
|
|
304
|
+
"Run `npx @clue-ai/cli setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle` when possible.",
|
|
305
|
+
"For interactive local verification, run `npx @clue-ai/cli setup-watch --local` and operate every local frontend/backend service until all expected checks pass.",
|
|
306
|
+
"If `setup-watch --local` cannot be completed because services are not running or human interaction is needed, report local verification as pending and do not state `setup completed`.",
|
|
307
|
+
"Only include lifecycle checks that the implementation ownership plan expects for that service. If a service emits an undeclared lifecycle event, treat it as a possible duplicate instrumentation issue.",
|
|
308
|
+
"Never assume localhost ports. Ask the repository scripts, env examples, or the running service output for the actual frontend/backend URLs.",
|
|
309
|
+
"If `npx` cannot be used in the current environment, use the local `clue-ai setup-check` command equivalent.",
|
|
310
|
+
"Confirm only env names are reported.",
|
|
311
|
+
"Leave event delivery verification to the Clue setup screen.",
|
|
312
|
+
],
|
|
313
|
+
"clue-setup-report": [
|
|
314
|
+
"Use this skill only after execution and monitoring passes are finished.",
|
|
315
|
+
"Never claim `setup completed` from `setup-check --require-sdk-lifecycle` alone. That check is static and does not verify dependency installation, imports, app startup, or event delivery.",
|
|
316
|
+
"Completion requires all applicable evidence: SDK dependencies install successfully, SDK imports work in the target frontend/backend environments, the app starts, `setup-check --require-sdk-lifecycle` passes, and `setup-watch --local` or the Clue setup screen confirms expected event delivery.",
|
|
317
|
+
"If any SDK package is unpublished, install/import checks were not run, app startup was not verified, or `setup-watch --local` was not completed, the final status must be `blocked`, `partially complete`, or `local verification pending`; it must not be `complete`.",
|
|
318
|
+
"Summarize changed files.",
|
|
319
|
+
"List completed setup phases.",
|
|
320
|
+
"List skills used for each workstream.",
|
|
321
|
+
"List execution agent and monitoring agents, or named review passes if subagents were unavailable.",
|
|
322
|
+
"List blockers with exact file or environment names when available.",
|
|
323
|
+
"List required env names without values.",
|
|
324
|
+
"List P0/P1 monitoring findings and fixes.",
|
|
325
|
+
"State that commit and push were not performed.",
|
|
326
|
+
],
|
|
327
|
+
};
|
|
315
328
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
329
|
+
return [
|
|
330
|
+
"---",
|
|
331
|
+
`name: ${name}`,
|
|
332
|
+
`description: ${descriptions[name]}`,
|
|
333
|
+
"---",
|
|
334
|
+
"",
|
|
335
|
+
"# Agent Role",
|
|
336
|
+
"",
|
|
337
|
+
agentRoles[name],
|
|
338
|
+
"",
|
|
339
|
+
"# Owns",
|
|
340
|
+
"",
|
|
341
|
+
...owns[name].map((item) => `- ${item}`),
|
|
342
|
+
"",
|
|
343
|
+
"# Must Not",
|
|
344
|
+
"",
|
|
345
|
+
...mustNot[name].map((item) => `- ${item}`),
|
|
346
|
+
"",
|
|
347
|
+
"# Output Contract",
|
|
348
|
+
"",
|
|
349
|
+
...outputs[name].map((item) => `- ${item}`),
|
|
350
|
+
"",
|
|
351
|
+
"# Shared Rules",
|
|
352
|
+
"",
|
|
353
|
+
"- For full Clue setup, use one execution agent per implementation workstream and multiple monitoring agents for read-only checks.",
|
|
354
|
+
"- The full setup must start with `clue-setup-orchestrator`.",
|
|
355
|
+
"- Each execution agent owns exactly one workstream; monitoring agents review one workstream at a time and report P0/P1 issues.",
|
|
356
|
+
"- Do not continue past a P0/P1 monitoring finding until it is fixed or explicitly reported as blocked.",
|
|
357
|
+
"- If subagents are unavailable, run the same structure as separate named review passes and say so in the final report.",
|
|
358
|
+
"- Do not expose project keys, API keys, secrets, tokens, or environment variable values.",
|
|
359
|
+
"- Do not ask the user to paste secret values.",
|
|
360
|
+
"- Do not read `.env`, `.env.*`, secret files, logs, dumps, build output, coverage output, `node_modules`, vendor directories, dependency directories, or dependency output.",
|
|
361
|
+
"- Report only environment variable names, never values.",
|
|
362
|
+
"- Do not commit or push changes.",
|
|
363
|
+
"- Prefer existing repository patterns and minimal diffs.",
|
|
364
|
+
"- If evidence is unclear, report a blocker instead of guessing.",
|
|
365
|
+
"- Do not merge semantic snapshot, semantic CI, SDK lifecycle, audit, verification, and report responsibilities into one undifferentiated task.",
|
|
366
|
+
"",
|
|
367
|
+
"# Workflow",
|
|
368
|
+
"",
|
|
369
|
+
...steps[name].map((step, index) => `${index + 1}. ${step}`),
|
|
370
|
+
"",
|
|
371
|
+
].join("\n");
|
|
359
372
|
};
|
|
360
373
|
|
|
361
374
|
const askTarget = async ({
|
|
362
|
-
|
|
363
|
-
|
|
375
|
+
input = process.stdin,
|
|
376
|
+
output = process.stdout,
|
|
364
377
|
} = {}) => {
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
378
|
+
const rl = readline.createInterface({ input, output });
|
|
379
|
+
try {
|
|
380
|
+
const answer = await rl.question(
|
|
381
|
+
"ClueのセットアップSkillsをどのAIツールに追加しますか？ [codex/claude_code] ",
|
|
382
|
+
);
|
|
383
|
+
return normalizeTarget(answer);
|
|
384
|
+
} finally {
|
|
385
|
+
rl.close();
|
|
386
|
+
}
|
|
374
387
|
};
|
|
375
388
|
|
|
376
389
|
export const installSetupSkills = async ({
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
390
|
+
repoRoot,
|
|
391
|
+
target,
|
|
392
|
+
input,
|
|
393
|
+
output,
|
|
381
394
|
} = {}) => {
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
395
|
+
const resolvedTarget = target
|
|
396
|
+
? normalizeTarget(target)
|
|
397
|
+
: await askTarget({ input, output });
|
|
398
|
+
const resolvedRepoRoot = resolve(repoRoot ?? ".");
|
|
399
|
+
const skillRoot = join(
|
|
400
|
+
resolvedRepoRoot,
|
|
401
|
+
...TARGET_SKILL_ROOTS[resolvedTarget],
|
|
402
|
+
);
|
|
403
|
+
const installed = [];
|
|
391
404
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
405
|
+
for (const skillName of SKILL_NAMES) {
|
|
406
|
+
const skillDir = join(skillRoot, skillName);
|
|
407
|
+
const skillPath = join(skillDir, "SKILL.md");
|
|
408
|
+
await mkdir(skillDir, { recursive: true });
|
|
409
|
+
await writeFile(skillPath, skillBody(skillName), "utf8");
|
|
410
|
+
installed.push(skillPath);
|
|
411
|
+
}
|
|
399
412
|
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
413
|
+
return {
|
|
414
|
+
target: resolvedTarget,
|
|
415
|
+
skill_root: join(...TARGET_SKILL_ROOTS[resolvedTarget]),
|
|
416
|
+
skills: SKILL_NAMES,
|
|
417
|
+
installed_files: installed.map((path) =>
|
|
418
|
+
path.replace(`${resolvedRepoRoot}/`, ""),
|
|
419
|
+
),
|
|
420
|
+
};
|
|
408
421
|
};
|