start-vibing 4.4.16 → 4.4.18
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 +42 -42
- package/template/.claude/CLAUDE.md +620 -458
- package/template/.claude/settings.json +2 -0
package/package.json
CHANGED
|
@@ -1,42 +1,42 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "start-vibing",
|
|
3
|
-
"version": "4.4.
|
|
4
|
-
"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. e2e-audit 0.2.0 refactor (skill-only, no agents): SessionStart hook + slash command make the skill keyword-invokable (\"e2e audit\", \"roda o e2e\", \"integration test\", \"test coverage gaps\"). Source-first discovery via detect-stack, discover-routes (Next app/pages/Remix/SvelteKit/Nuxt/Astro), discover-api-surface (HTTP handlers, tRPC procedures, GraphQL, server actions, middleware auth), inventory-existing-tests (preserve prior corpus + sha256 drift hash), and detect-uncovered (branch-diff vs origin/main finds changes not covered by existing specs). Report-then-ask between mapping and Playwright run; post-run-feedback report before writing findings. SHOT+TRACE+ASSERT+SOURCE evidence quad per non-meta finding; meta rules (coverage-gap-*, uncovered-*, test-drift, stack-detect, post-run-feedback) exempt. verify-audit.sh enforces schema + quad. Generic (no project leakage). super-design 0.7.0 carries over.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"start-vibing": "./dist/cli.js"
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"dist",
|
|
11
|
-
"template"
|
|
12
|
-
],
|
|
13
|
-
"scripts": {
|
|
14
|
-
"build": "bun build ./src/cli.ts --outdir ./dist --target node",
|
|
15
|
-
"dev": "bun run ./src/cli.ts",
|
|
16
|
-
"prepublishOnly": "bun run build"
|
|
17
|
-
},
|
|
18
|
-
"keywords": [
|
|
19
|
-
"claude",
|
|
20
|
-
"claude-code",
|
|
21
|
-
"ai",
|
|
22
|
-
"agents",
|
|
23
|
-
"skills",
|
|
24
|
-
"hooks",
|
|
25
|
-
"automation",
|
|
26
|
-
"workflow",
|
|
27
|
-
"cli"
|
|
28
|
-
],
|
|
29
|
-
"author": "joaov",
|
|
30
|
-
"license": "MIT",
|
|
31
|
-
"repository": {
|
|
32
|
-
"type": "git",
|
|
33
|
-
"url": "https://github.com/LimaTechnologies/ai-development"
|
|
34
|
-
},
|
|
35
|
-
"engines": {
|
|
36
|
-
"node": ">=18.0.0"
|
|
37
|
-
},
|
|
38
|
-
"devDependencies": {
|
|
39
|
-
"@types/node": "^20.0.0",
|
|
40
|
-
"typescript": "^5.0.0"
|
|
41
|
-
}
|
|
42
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "start-vibing",
|
|
3
|
+
"version": "4.4.18",
|
|
4
|
+
"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. e2e-audit 0.2.0 refactor (skill-only, no agents): SessionStart hook + slash command make the skill keyword-invokable (\"e2e audit\", \"roda o e2e\", \"integration test\", \"test coverage gaps\"). Source-first discovery via detect-stack, discover-routes (Next app/pages/Remix/SvelteKit/Nuxt/Astro), discover-api-surface (HTTP handlers, tRPC procedures, GraphQL, server actions, middleware auth), inventory-existing-tests (preserve prior corpus + sha256 drift hash), and detect-uncovered (branch-diff vs origin/main finds changes not covered by existing specs). Report-then-ask between mapping and Playwright run; post-run-feedback report before writing findings. SHOT+TRACE+ASSERT+SOURCE evidence quad per non-meta finding; meta rules (coverage-gap-*, uncovered-*, test-drift, stack-detect, post-run-feedback) exempt. verify-audit.sh enforces schema + quad. Generic (no project leakage). super-design 0.7.0 carries over.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"start-vibing": "./dist/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"dist",
|
|
11
|
+
"template"
|
|
12
|
+
],
|
|
13
|
+
"scripts": {
|
|
14
|
+
"build": "bun build ./src/cli.ts --outdir ./dist --target node",
|
|
15
|
+
"dev": "bun run ./src/cli.ts",
|
|
16
|
+
"prepublishOnly": "bun run build"
|
|
17
|
+
},
|
|
18
|
+
"keywords": [
|
|
19
|
+
"claude",
|
|
20
|
+
"claude-code",
|
|
21
|
+
"ai",
|
|
22
|
+
"agents",
|
|
23
|
+
"skills",
|
|
24
|
+
"hooks",
|
|
25
|
+
"automation",
|
|
26
|
+
"workflow",
|
|
27
|
+
"cli"
|
|
28
|
+
],
|
|
29
|
+
"author": "joaov",
|
|
30
|
+
"license": "MIT",
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "https://github.com/LimaTechnologies/ai-development"
|
|
34
|
+
},
|
|
35
|
+
"engines": {
|
|
36
|
+
"node": ">=18.0.0"
|
|
37
|
+
},
|
|
38
|
+
"devDependencies": {
|
|
39
|
+
"@types/node": "^20.0.0",
|
|
40
|
+
"typescript": "^5.0.0"
|
|
41
|
+
}
|
|
42
|
+
}
|
|
@@ -1,458 +1,620 @@
|
|
|
1
|
-
# Claude Development System - Agent Context
|
|
2
|
-
|
|
3
|
-
This file provides detailed context for the development system installed by `start-vibing v4`.
|
|
4
|
-
For user-facing project rules, see `/CLAUDE.md`.
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## Language Policy (HARD RULE)
|
|
9
|
-
|
|
10
|
-
> **ENGLISH ONLY — for everything Claude produces — UNLESS the user explicitly asks for another language in the current request.**
|
|
11
|
-
|
|
12
|
-
Applies to **every** output, no exceptions beyond an explicit user override:
|
|
13
|
-
|
|
14
|
-
- Chat replies, status updates, summaries, questions back to the user
|
|
15
|
-
- Code (identifiers, variables, function/class names, type names)
|
|
16
|
-
- Comments, JSDoc, docstrings
|
|
17
|
-
- Commit messages, PR titles, PR descriptions, branch names
|
|
18
|
-
- Documentation (`/docs/**`, README, CLAUDE.md updates, changelogs, ADRs)
|
|
19
|
-
- Test names, error messages, log messages, CLI help strings
|
|
20
|
-
- File and folder names, configuration keys
|
|
21
|
-
|
|
22
|
-
The user may write to Claude in Portuguese, Spanish, or any other language — Claude still responds and writes in English unless the user explicitly says e.g. "responda em português", "write this in Spanish". An override applies only to the current request; revert to English on the next turn. Never mix English + another language in the same output. If unsure whether a request is an override, default to English and ask one short clarifying question.
|
|
23
|
-
|
|
24
|
-
---
|
|
25
|
-
|
|
26
|
-
##
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
.
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
**
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
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
|
-
|
|
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
|
-
|
|
315
|
-
|
|
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
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
Research
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
1
|
+
# Claude Development System - Agent Context
|
|
2
|
+
|
|
3
|
+
This file provides detailed context for the development system installed by `start-vibing v4`.
|
|
4
|
+
For user-facing project rules, see `/CLAUDE.md`.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Language Policy (HARD RULE)
|
|
9
|
+
|
|
10
|
+
> **ENGLISH ONLY — for everything Claude produces — UNLESS the user explicitly asks for another language in the current request.**
|
|
11
|
+
|
|
12
|
+
Applies to **every** output, no exceptions beyond an explicit user override:
|
|
13
|
+
|
|
14
|
+
- Chat replies, status updates, summaries, questions back to the user
|
|
15
|
+
- Code (identifiers, variables, function/class names, type names)
|
|
16
|
+
- Comments, JSDoc, docstrings
|
|
17
|
+
- Commit messages, PR titles, PR descriptions, branch names
|
|
18
|
+
- Documentation (`/docs/**`, README, CLAUDE.md updates, changelogs, ADRs)
|
|
19
|
+
- Test names, error messages, log messages, CLI help strings
|
|
20
|
+
- File and folder names, configuration keys
|
|
21
|
+
|
|
22
|
+
The user may write to Claude in Portuguese, Spanish, or any other language — Claude still responds and writes in English unless the user explicitly says e.g. "responda em português", "write this in Spanish". An override applies only to the current request; revert to English on the next turn. Never mix English + another language in the same output. If unsure whether a request is an override, default to English and ask one short clarifying question.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Response Style (HARD RULE)
|
|
27
|
+
|
|
28
|
+
> **Be brief by default. Output tokens cost ~5x input and are ~8x slower to generate. Verbose responses are also re-processed every turn — the cost compounds.**
|
|
29
|
+
|
|
30
|
+
Adapted from Anthropic's official Opus 4.7 system prompt for Claude Code (April 2026 post-mortem — single addition reported as having "outsized effect on intelligence in Claude Code"):
|
|
31
|
+
|
|
32
|
+
- **Final responses ≤100 words** unless the task genuinely requires more (multi-step plan, design rationale, teaching, code review with rationale).
|
|
33
|
+
- **Text between tool calls ≤25 words.** One sentence per update at key moments — not a running commentary on internal deliberation.
|
|
34
|
+
- **No prefacing.** Skip "Great question!", "I'll help you with that", "Let me start by…". Just do the thing.
|
|
35
|
+
- **No trailing summaries.** The diff is visible. Don't re-narrate what just happened. End-of-turn = 1–2 sentences max, what changed and what's next.
|
|
36
|
+
- **No re-explanations.** If it's already in this conversation or in CLAUDE.md, don't repeat it.
|
|
37
|
+
- **Don't add docstrings, comments, or type annotations to code you didn't change.** Comment only when WHY is non-obvious. Names already explain WHAT.
|
|
38
|
+
- **Don't reference the current task in code.** No `// added for ticket X` / `// used by feature Y` — that belongs in PR descriptions, not source.
|
|
39
|
+
|
|
40
|
+
### Brevity ≠ cutting reasoning
|
|
41
|
+
|
|
42
|
+
Cut **visible explanations**, NOT **internal thinking**:
|
|
43
|
+
|
|
44
|
+
- Visible prose costs output tokens, gets re-processed every turn, and on large models often _hurts_ accuracy via over-elaboration (arXiv 2604.00025 — restricting outputs to <50 words gave +26.3pp accuracy on GSM8K/MMLU-STEM).
|
|
45
|
+
- Internal thinking/reasoning budget _improves_ quality on hard tasks (Anthropic guidance). Do NOT set `MAX_THINKING_TOKENS=0` or `effort=low` on complex problems.
|
|
46
|
+
- Code comments produced DURING generation often help — they act as logical pivots between natural language and code (arXiv 2404.07549 improves pass@1). Strip prose AROUND the code, not comments INSIDE it.
|
|
47
|
+
|
|
48
|
+
### When to override brevity
|
|
49
|
+
|
|
50
|
+
- User explicitly asks for detail ("explain why", "walk me through").
|
|
51
|
+
- Teaching mode (user is learning the codebase or domain).
|
|
52
|
+
- Design / planning discussion where rationale matters.
|
|
53
|
+
- Code review with inline findings + rationale.
|
|
54
|
+
|
|
55
|
+
Default = terse. Verbose only on signal.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## What start-vibing v4 Installs
|
|
60
|
+
|
|
61
|
+
start-vibing is a CLI (`npx start-vibing`) that sets up Claude Code with a complete development system in ~30 seconds:
|
|
62
|
+
|
|
63
|
+
| Component | Count | Installation Method |
|
|
64
|
+
| -------------------- | ----- | ---------------------------------------------------- |
|
|
65
|
+
| **MCP Servers** | 8 | `claude mcp add` (parallel, ~20s) |
|
|
66
|
+
| **Plugins** | 9 | `claude plugin install` (parallel, auto-accept, ~3s) |
|
|
67
|
+
| **Community Skills** | 5 | Direct HTTPS download from GitHub (~0.3s) |
|
|
68
|
+
| **Template Files** | ~30 | File copy (agents, skills, config, CLAUDE.md) |
|
|
69
|
+
|
|
70
|
+
### Installation Architecture
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
npx start-vibing
|
|
74
|
+
├── Phase 1: Copy template files (agents, skills, config)
|
|
75
|
+
├── Phase 2: Verify/install Claude Code CLI
|
|
76
|
+
├── Phase 3: Install 8 MCP servers (parallel via Promise.all)
|
|
77
|
+
├── Phase 4: Install 9 plugins (parallel, stdin auto-accept 'y')
|
|
78
|
+
├── Phase 5: Download 5 community skills (parallel HTTPS from GitHub)
|
|
79
|
+
└── Phase 6: Launch Claude Code (resume last session or new)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
All phases run best-effort. MCP and plugin failures are non-blocking — `settings.json` `enabledPlugins` is the fallback for plugins.
|
|
83
|
+
|
|
84
|
+
### CLI Options
|
|
85
|
+
|
|
86
|
+
| Flag | Effect |
|
|
87
|
+
| ------------------- | ------------------------------------------------- |
|
|
88
|
+
| `--force` | Overwrite all files (including custom ones) |
|
|
89
|
+
| `--new` | Start fresh Claude session (default: resume last) |
|
|
90
|
+
| `--no-claude` | Skip Claude Code installation and launch |
|
|
91
|
+
| `--no-mcp` | Skip MCP server installation |
|
|
92
|
+
| `--no-skills` | Skip community skills installation |
|
|
93
|
+
| `--no-update-check` | Skip version check |
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## System Architecture
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
.claude/
|
|
101
|
+
├── agents/ # 5 active subagents (flat structure)
|
|
102
|
+
├── skills/ # Custom + 5 community skills (auto-injected by description match)
|
|
103
|
+
├── scripts/ # Utility scripts
|
|
104
|
+
├── config/ # Project-specific configuration (JSON files)
|
|
105
|
+
└── commands/ # Slash commands (feature, fix, research, validate)
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Agents (5 Active Subagents)
|
|
111
|
+
|
|
112
|
+
| Agent | Model | Purpose |
|
|
113
|
+
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------- |
|
|
114
|
+
| **research-web** | sonnet | Researches best practices (2025-2026) with ontology-based structuring, output to `/docs/research/` |
|
|
115
|
+
| **documenter** | sonnet | Analyzes sessions via git log/diff, writes changelog + technical docs + ADRs to `/docs/` |
|
|
116
|
+
| **commit-manager** | haiku | Manages git commits, conventional format, merge workflow |
|
|
117
|
+
| **claude-md-compactor** | sonnet | Compacts CLAUDE.md when it exceeds 40k chars |
|
|
118
|
+
| **tester-unit** | sonnet | Creates unit tests with Vitest for new functions and utilities |
|
|
119
|
+
|
|
120
|
+
### Agent Workflow Order
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
implement -> quality gates -> documenter -> commit-manager -> complete
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Agents are dispatched via the `Agent` tool with `subagent_type` matching agent names. They run autonomously and return results to the orchestrator.
|
|
127
|
+
|
|
128
|
+
### Research Agent Details
|
|
129
|
+
|
|
130
|
+
The research-web agent outputs findings to `/docs/research/[topic].md` (NOT to `.claude/skills/research-cache/`).
|
|
131
|
+
|
|
132
|
+
**Research flow:**
|
|
133
|
+
|
|
134
|
+
1. Check `/docs/research/` for existing findings (reuse if fresh < 3 months)
|
|
135
|
+
2. Build ontology map (concepts → relationships → constraints)
|
|
136
|
+
3. Search with `[topic] [aspect] [2025-2026] [context]` queries
|
|
137
|
+
4. Triangulate (3+ sources for any claim)
|
|
138
|
+
5. Save structured output to `/docs/research/`
|
|
139
|
+
|
|
140
|
+
**For UI/UX tasks, the agent also runs:**
|
|
141
|
+
|
|
142
|
+
- Competitor analysis (3-5 competitors, heuristic evaluation)
|
|
143
|
+
- Design system pattern check (shadcn/ui, Radix, WCAG 2.1)
|
|
144
|
+
- User flow mapping (happy path + 2 error paths)
|
|
145
|
+
- Accessibility audit plan (axe, keyboard nav, screen reader)
|
|
146
|
+
|
|
147
|
+
### Documenter Agent Details
|
|
148
|
+
|
|
149
|
+
The documenter agent runs after implementation, analyzes the session, and writes structured docs to `/docs/`.
|
|
150
|
+
|
|
151
|
+
**Documentation flow:**
|
|
152
|
+
|
|
153
|
+
1. Run `git log` + `git diff` to analyze what changed
|
|
154
|
+
2. Classify changes: per-commit, per-feature, per-session
|
|
155
|
+
3. Mini-research for technologies used (check `/docs/research/` first, else 1-2 queries)
|
|
156
|
+
4. Write changelog (`/docs/changelog/`), technical docs (`/docs/technical/`), ADRs (`/docs/decisions/`)
|
|
157
|
+
5. Update all indexes (`/docs/index.md` + per-folder indexes)
|
|
158
|
+
|
|
159
|
+
**Output structure:**
|
|
160
|
+
|
|
161
|
+
```
|
|
162
|
+
/docs/
|
|
163
|
+
├── index.md # Root index
|
|
164
|
+
├── changelog/ # Per-session changelogs
|
|
165
|
+
│ ├── index.md
|
|
166
|
+
│ └── YYYY-MM-DD-summary.md
|
|
167
|
+
├── technical/ # Deep feature/architecture docs
|
|
168
|
+
│ ├── index.md
|
|
169
|
+
│ └── feature-name.md
|
|
170
|
+
├── decisions/ # Architecture Decision Records
|
|
171
|
+
│ ├── index.md
|
|
172
|
+
│ └── NNNN-decision.md
|
|
173
|
+
└── research/ # Managed by research-web
|
|
174
|
+
├── index.md
|
|
175
|
+
└── topic.md
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**Writing rules:**
|
|
179
|
+
|
|
180
|
+
- Self-contained sections (AI RAG chunk retrieval)
|
|
181
|
+
- What→Why→How progression (humans first)
|
|
182
|
+
- Before→After pattern for all changes (mandatory)
|
|
183
|
+
- Consistent terminology (one name per concept)
|
|
184
|
+
- Official docs URLs for all technologies cited
|
|
185
|
+
- Every doc linked from its folder index AND root index
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Plugins (9 via enabledPlugins)
|
|
190
|
+
|
|
191
|
+
Plugins are the primary extension mechanism. All 9 are installed in parallel with auto-accept (`stdin.write('y\n')` x3). If CLI install fails, `settings.json` `enabledPlugins` ensures they activate on next Claude session.
|
|
192
|
+
|
|
193
|
+
### Core Workflow Plugins
|
|
194
|
+
|
|
195
|
+
| Plugin | Mechanism | Purpose |
|
|
196
|
+
| ------------------- | ------------------- | ------------------------------------------------------------------- |
|
|
197
|
+
| **superpowers** | Skills + commands | TDD, brainstorming, debugging, planning, code review, git worktrees |
|
|
198
|
+
| **ralph-loop** | Stop hook + command | Iterative autonomous development loop with checkpoints |
|
|
199
|
+
| **context7** | Skill + agent + MCP | Auto library docs — replaces manual context7 MCP server |
|
|
200
|
+
| **code-simplifier** | Skill + command | Refine code for clarity, reduce nesting, improve naming |
|
|
201
|
+
|
|
202
|
+
### Development Plugins
|
|
203
|
+
|
|
204
|
+
| Plugin | Mechanism | Purpose |
|
|
205
|
+
| --------------------- | -------------------------- | -------------------------------------------------------- |
|
|
206
|
+
| **typescript-lsp** | LSP server (auto) | Type diagnostics, go-to-definition, hover info |
|
|
207
|
+
| **security-guidance** | PreToolUse hook (auto) | OWASP Top 10, vulnerability scan, blocks unsafe patterns |
|
|
208
|
+
| **code-review** | `/code-review` command | Code quality analysis, PR review |
|
|
209
|
+
| **commit-commands** | `/commit` command | Git commit, push, PR flows with conventional format |
|
|
210
|
+
| **frontend-design** | `/frontend-design` command | Production-grade UI design with competitor research |
|
|
211
|
+
|
|
212
|
+
### Plugin Installation Details
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
// How plugins are installed (src/plugins.ts):
|
|
216
|
+
// 1. Check if already installed via `claude plugin list`
|
|
217
|
+
// 2. Spawn `claude plugin install <name>@claude-plugins-official --scope user`
|
|
218
|
+
// 3. Auto-accept all prompts via stdin: proc.stdin.write('y\n') x3
|
|
219
|
+
// 4. All 9 run in parallel via Promise.all (completes in ~3s)
|
|
220
|
+
// 5. Fallback: settings.json enabledPlugins activates them even if CLI install fails
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Using Superpowers (RECOMMENDED)
|
|
224
|
+
|
|
225
|
+
Superpowers provides structured workflows for feature development:
|
|
226
|
+
|
|
227
|
+
```
|
|
228
|
+
/brainstorming → Before designing features (ALWAYS for creative work)
|
|
229
|
+
/write-plan → Plan multi-step implementations into executable specs
|
|
230
|
+
/execute-plan → Execute plans with TDD (red-green-refactor cycle)
|
|
231
|
+
/systematic-debugging → Debug with root-cause analysis (not guessing)
|
|
232
|
+
/verification-before-completion → Verify before claiming work is done
|
|
233
|
+
/requesting-code-review → Get review after major features
|
|
234
|
+
/dispatching-parallel-agents → Run 2+ independent tasks in parallel via subagents
|
|
235
|
+
/using-git-worktrees → Isolate feature work from current branch
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
### Using Ralph Loop (FOR BIG TASKS)
|
|
239
|
+
|
|
240
|
+
Ralph Loop runs Claude autonomously in a continuous implementation loop:
|
|
241
|
+
|
|
242
|
+
```
|
|
243
|
+
/ralph-loop "implement full CRUD for users" --max-iterations 10
|
|
244
|
+
/cancel-ralph → Abort if needed
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
All file changes and git history persist between iterations. Best for multi-file features, complex refactors, or sustained autonomous work.
|
|
248
|
+
|
|
249
|
+
### Using Code Simplifier (POST-IMPLEMENTATION)
|
|
250
|
+
|
|
251
|
+
After implementing, run `/simplify` to:
|
|
252
|
+
|
|
253
|
+
- Reduce nesting and redundancy
|
|
254
|
+
- Improve naming and readability
|
|
255
|
+
- Replace nested ternaries with early returns
|
|
256
|
+
- Simplify without changing behavior
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## MCP Servers (8 Installed)
|
|
261
|
+
|
|
262
|
+
All 8 MCPs are installed in parallel via `claude mcp add -s user` (~20s total). Each runs as a subprocess spawned by Claude Code on demand.
|
|
263
|
+
|
|
264
|
+
### Required MCPs (ALWAYS use these)
|
|
265
|
+
|
|
266
|
+
| Server | Package | Purpose |
|
|
267
|
+
| --------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
268
|
+
| `sequential-thinking` | `@modelcontextprotocol/server-sequential-thinking` | Structured reasoning for multi-step tasks, architecture decisions, debugging |
|
|
269
|
+
| `playwright` | `@playwright/mcp@latest` | Browser automation for UI verification, E2E tests, visual validation |
|
|
270
|
+
|
|
271
|
+
> These 2 are **non-negotiable**. Skipping them leads to poor planning and untested UIs.
|
|
272
|
+
|
|
273
|
+
> **Note**: `context7` is now a **plugin** with auto-invocation skill (not an MCP). Library docs are fetched automatically when you use any library.
|
|
274
|
+
|
|
275
|
+
### Standard MCPs
|
|
276
|
+
|
|
277
|
+
| Server | Package | Transport | Purpose |
|
|
278
|
+
| ----------------- | ------------------------------------- | ----------- | ------------------------------------------------ |
|
|
279
|
+
| `memory` | `@modelcontextprotocol/server-memory` | stdio (npx) | Persistent knowledge graph across sessions |
|
|
280
|
+
| `nextjs-devtools` | `next-devtools-mcp@latest` | stdio (npx) | Next.js runtime errors, routes, cache inspection |
|
|
281
|
+
| `mongodb` | `@mongodb-js/mongodb-mcp-server` | stdio (npx) | MongoDB queries, schema inspection, aggregation |
|
|
282
|
+
| `jira` | `@aashari/mcp-server-atlassian-jira` | stdio (npx) | Issue tracking, task management |
|
|
283
|
+
| `git` | `mcp-server-git` | stdio (uvx) | Git operations, repo search, history, diffs |
|
|
284
|
+
| `fetch` | `mcp-server-fetch` | stdio (uvx) | Fetch web pages as markdown |
|
|
285
|
+
|
|
286
|
+
### Optional MCPs (install manually)
|
|
287
|
+
|
|
288
|
+
These are shown to the user after setup but not auto-installed:
|
|
289
|
+
|
|
290
|
+
| Server | Install Command |
|
|
291
|
+
| -------- | ----------------------------------------------------------------------------------- |
|
|
292
|
+
| `github` | `claude mcp add --transport http -s user github https://api.githubcopilot.com/mcp/` |
|
|
293
|
+
| `sentry` | `claude mcp add --transport http -s user sentry https://mcp.sentry.dev/mcp` |
|
|
294
|
+
| `figma` | `claude mcp add --transport http -s user figma https://mcp.figma.com/mcp` |
|
|
295
|
+
| `linear` | `claude mcp add --transport http -s user linear https://mcp.linear.app/sse` |
|
|
296
|
+
| `stripe` | `claude mcp add --transport http -s user stripe https://mcp.stripe.com` |
|
|
297
|
+
| `vercel` | `claude mcp add --transport http -s user vercel https://mcp.vercel.com` |
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
## Community Skills (5 from GitHub)
|
|
302
|
+
|
|
303
|
+
Skills are SKILL.md files placed in `.claude/skills/<name>/SKILL.md`. They are auto-injected into Claude's context when the task matches their frontmatter `description`.
|
|
304
|
+
|
|
305
|
+
### Installation Method
|
|
306
|
+
|
|
307
|
+
Community skills are downloaded directly from GitHub raw URLs (the `skillsadd` npm package is deprecated — its backend `skills.ws` is down). Each skill is a single SKILL.md file.
|
|
308
|
+
|
|
309
|
+
```typescript
|
|
310
|
+
// How skills are installed (src/skills.ts):
|
|
311
|
+
// 1. Check if .claude/skills/<name>/SKILL.md already exists (skip if so)
|
|
312
|
+
// 2. HTTPS GET from raw.githubusercontent.com/<owner>/<repo>/main/skills/<name>/SKILL.md
|
|
313
|
+
// 3. Write to .claude/skills/<name>/SKILL.md
|
|
314
|
+
// 4. All 5 run in parallel via Promise.all (completes in ~0.3s)
|
|
315
|
+
// 5. No external CLI dependency — just Node.js https module
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
### Installed Skills
|
|
319
|
+
|
|
320
|
+
| Skill | Source Repo | Purpose |
|
|
321
|
+
| ------------------------- | -------------------------- | -------------------------------------------- |
|
|
322
|
+
| **react-best-practices** | `vercel-labs/agent-skills` | React/Next.js performance optimization rules |
|
|
323
|
+
| **web-design-guidelines** | `vercel-labs/agent-skills` | 100+ WCAG accessibility + UX audit rules |
|
|
324
|
+
| **composition-patterns** | `vercel-labs/agent-skills` | Compound component and composition patterns |
|
|
325
|
+
| **webapp-testing** | `anthropics/skills` | Real browser test execution with Playwright |
|
|
326
|
+
| **mcp-builder** | `anthropics/skills` | Guide for building MCP servers |
|
|
327
|
+
|
|
328
|
+
### Adding More Skills
|
|
329
|
+
|
|
330
|
+
To install additional skills from [skills.sh](https://skills.sh), use the working CLI:
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
# List available skills in a repo
|
|
334
|
+
npx skills add vercel-labs/agent-skills --list
|
|
335
|
+
|
|
336
|
+
# Install a specific skill
|
|
337
|
+
npx skills add vercel-labs/agent-skills --skill <name> --yes
|
|
338
|
+
|
|
339
|
+
# Install from anthropics
|
|
340
|
+
npx skills add anthropics/skills --skill <name> --yes
|
|
341
|
+
|
|
342
|
+
# Manual fallback (if CLI fails)
|
|
343
|
+
mkdir -p .claude/skills/<name>
|
|
344
|
+
curl -o .claude/skills/<name>/SKILL.md \
|
|
345
|
+
https://raw.githubusercontent.com/<owner>/<repo>/main/skills/<name>/SKILL.md
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## Configuration Files
|
|
351
|
+
|
|
352
|
+
Project-specific settings in `.claude/config/`:
|
|
353
|
+
|
|
354
|
+
| File | Purpose |
|
|
355
|
+
| --------------------- | ------------------------------ |
|
|
356
|
+
| `project-config.json` | Stack, structure, commands |
|
|
357
|
+
| `quality-gates.json` | Quality check commands |
|
|
358
|
+
| `testing-config.json` | Test framework and conventions |
|
|
359
|
+
| `security-rules.json` | Security audit rules |
|
|
360
|
+
|
|
361
|
+
Agents read config files before acting. Do NOT hardcode project specifics — update the JSON files instead.
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## settings.json (enabledPlugins)
|
|
366
|
+
|
|
367
|
+
The `.claude/settings.json` file contains `enabledPlugins` which is the fallback mechanism for plugin activation. Even if `claude plugin install` fails, having the plugin listed in `enabledPlugins` ensures Claude prompts to install it on first use.
|
|
368
|
+
|
|
369
|
+
```json
|
|
370
|
+
{
|
|
371
|
+
"enabledPlugins": {
|
|
372
|
+
"typescript-lsp@claude-plugins-official": true,
|
|
373
|
+
"security-guidance@claude-plugins-official": true,
|
|
374
|
+
"code-review@claude-plugins-official": true,
|
|
375
|
+
"commit-commands@claude-plugins-official": true,
|
|
376
|
+
"frontend-design@claude-plugins-official": true,
|
|
377
|
+
"superpowers@claude-plugins-official": true,
|
|
378
|
+
"ralph-loop@claude-plugins-official": true,
|
|
379
|
+
"context7@claude-plugins-official": true,
|
|
380
|
+
"code-simplifier@claude-plugins-official": true
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## Execution Protocol
|
|
388
|
+
|
|
389
|
+
### Before Implementation
|
|
390
|
+
|
|
391
|
+
1. Use `/brainstorming` for creative work or feature design
|
|
392
|
+
2. Use `/write-plan` for multi-step tasks
|
|
393
|
+
3. Use `context7` (auto via plugin) for library docs
|
|
394
|
+
4. Research if needed (research-web agent → saves to `/docs/research/`)
|
|
395
|
+
|
|
396
|
+
### During Implementation
|
|
397
|
+
|
|
398
|
+
1. Use superpowers TDD (red-green-refactor)
|
|
399
|
+
2. Use `/ralph-loop` for autonomous big tasks
|
|
400
|
+
3. Run quality gates as you go
|
|
401
|
+
|
|
402
|
+
### After Implementation
|
|
403
|
+
|
|
404
|
+
1. Run `/simplify` (code-simplifier) on changed files
|
|
405
|
+
2. Run quality gates (`bun run typecheck && lint && test`)
|
|
406
|
+
3. Run documenter agent (changelog + technical docs + ADRs to `/docs/`)
|
|
407
|
+
4. Update CLAUDE.md with architecture changes
|
|
408
|
+
5. Commit via commit-manager agent (FINAL step)
|
|
409
|
+
|
|
410
|
+
---
|
|
411
|
+
|
|
412
|
+
## Documentation Policy
|
|
413
|
+
|
|
414
|
+
> Documentation is automatic via the **documenter agent**. It lives in `/docs/`.
|
|
415
|
+
|
|
416
|
+
### After Completing Work
|
|
417
|
+
|
|
418
|
+
The documenter agent runs automatically after implementation:
|
|
419
|
+
|
|
420
|
+
1. Analyzes git log/diff for the session
|
|
421
|
+
2. Writes changelog + technical docs + ADRs as needed
|
|
422
|
+
3. Updates all indexes
|
|
423
|
+
4. Docs are ready for commit
|
|
424
|
+
|
|
425
|
+
### Research Output
|
|
426
|
+
|
|
427
|
+
Research findings go to `/docs/research/[topic].md` — NOT to `.claude/skills/research-cache/`.
|
|
428
|
+
|
|
429
|
+
- Ontology-based structure: concepts → relationships → constraints → implementation path
|
|
430
|
+
- Freshness tracked per file (< 3 months fresh, 3-6 aging, 6-12 stale, > 12 outdated)
|
|
431
|
+
- Always check existing research before running new searches
|
|
432
|
+
|
|
433
|
+
### What NOT to Do
|
|
434
|
+
|
|
435
|
+
- Do NOT maintain `.claude/skills/codebase-knowledge/domains/` (legacy)
|
|
436
|
+
- Do NOT save research to `.claude/skills/research-cache/` — use `/docs/research/` instead
|
|
437
|
+
- Do NOT mix doc types in one file (changelog ≠ technical ≠ decision)
|
|
438
|
+
- Do NOT leave docs unlinked from indexes
|
|
439
|
+
- Do NOT skip Before→After pattern in changelogs
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
## Quality Requirements
|
|
444
|
+
|
|
445
|
+
All implementations MUST:
|
|
446
|
+
|
|
447
|
+
- [ ] Pass typecheck (`bun run typecheck`)
|
|
448
|
+
- [ ] Pass lint (`bun run lint`)
|
|
449
|
+
- [ ] Pass unit tests (`bun run test`)
|
|
450
|
+
- [ ] Be documented by documenter agent (changelog + technical/ADR if applicable)
|
|
451
|
+
- [ ] Be committed with conventional commits
|
|
452
|
+
- [ ] Have CLAUDE.md updated with architecture/rule changes
|
|
453
|
+
|
|
454
|
+
---
|
|
455
|
+
|
|
456
|
+
## FORBIDDEN Actions
|
|
457
|
+
|
|
458
|
+
| Action | Reason |
|
|
459
|
+
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
460
|
+
| Speak/write in non-English | EN ONLY (chat, code, docs, commits) — see Language Policy. Override only via explicit user request, current turn only |
|
|
461
|
+
| Verbose responses by default | ≤100 words final, ≤25 words between tool calls — see Response Style. Brevity is intelligence in Claude Code |
|
|
462
|
+
| Preface answers ("Great question!", "I'll help you with that") | No filler. Just do the thing |
|
|
463
|
+
| Trailing summary of what just happened | Diff is visible. End-of-turn = 1–2 sentences max |
|
|
464
|
+
| Add docstrings/comments/type annotations to code you did NOT change | Anthropic guidance: only modified code gets new comments. Names explain WHAT, comments only when WHY is non-obvious |
|
|
465
|
+
| Reference current task/ticket inside code (`// added for X`) | Belongs in PR description, not source — rots over time |
|
|
466
|
+
| Re-explain what's already in CLAUDE.md or earlier in this conversation | Wastes output tokens AND re-processes every turn |
|
|
467
|
+
| Cut thinking budget on hard tasks (`MAX_THINKING_TOKENS=0`/`low`) | Cut visible prose, not internal reasoning. Thinking improves accuracy on hard tasks |
|
|
468
|
+
| Inline UI reference patterns (Grid/Modal/List/Toast/etc.) in CLAUDE.md | Patterns belong in `.claude/skills/research-cache/cache/` — recurring input cost otherwise |
|
|
469
|
+
| Skip typecheck | Catches runtime errors |
|
|
470
|
+
| Use `any` type | Defeats strict mode |
|
|
471
|
+
| Define types in `src/` | Must be in `types/` |
|
|
472
|
+
| Use `@types/` alias | Reserved by TypeScript |
|
|
473
|
+
| Commit directly to main | Create feature/fix branches |
|
|
474
|
+
| Skip documenter after implementation | Changelog + docs are mandatory |
|
|
475
|
+
| Mix doc types in one file | Changelog ≠ technical ≠ decision |
|
|
476
|
+
| Leave docs unlinked from index | Undiscoverable docs are useless |
|
|
477
|
+
| Skip superpowers for features | Use brainstorming + TDD |
|
|
478
|
+
| Skip code-simplifier | Run /simplify post-implementation |
|
|
479
|
+
| Use MUI/Chakra | Use shadcn/ui + Radix |
|
|
480
|
+
| Files > 400 lines | MUST split into smaller |
|
|
481
|
+
| 'use client' at top level | Push to leaf components only |
|
|
482
|
+
| Waterfall data fetching | Use Promise.all() for parallel |
|
|
483
|
+
| Skip CLAUDE.md update | MUST update after implementations |
|
|
484
|
+
|
|
485
|
+
---
|
|
486
|
+
|
|
487
|
+
## Universal Project Rules
|
|
488
|
+
|
|
489
|
+
> Rules that apply to every project using this system. Project-specific overrides go in `/CLAUDE.md`.
|
|
490
|
+
|
|
491
|
+
### HTTP Requests
|
|
492
|
+
|
|
493
|
+
| Rule | Implementation |
|
|
494
|
+
| ----------------------- | ------------------------------ |
|
|
495
|
+
| Use axios ONLY | Never `fetch()` or raw `axios` |
|
|
496
|
+
| `withCredentials: true` | ALWAYS for cookies/sessions |
|
|
497
|
+
| Extend base instance | Create `lib/api/axios.ts` |
|
|
498
|
+
| Type responses | `api.get<User>('/users')` |
|
|
499
|
+
| Centralize errors | Use interceptors |
|
|
500
|
+
|
|
501
|
+
### Path Aliases
|
|
502
|
+
|
|
503
|
+
| Alias | Maps To | Use For |
|
|
504
|
+
| ---------- | ------------------- | ------------- |
|
|
505
|
+
| `$types/*` | `./types/*` | Type defs |
|
|
506
|
+
| `@common` | `./common/index.ts` | Logger, utils |
|
|
507
|
+
| `@db` | `./common/db/` | DB connection |
|
|
508
|
+
|
|
509
|
+
NEVER use `@types/` (reserved by TypeScript).
|
|
510
|
+
|
|
511
|
+
### Types Location
|
|
512
|
+
|
|
513
|
+
- ALL interfaces/types MUST be in `types/` folder.
|
|
514
|
+
- NEVER define types in `src/` files.
|
|
515
|
+
- EXCEPTION: Zod inferred types and Mongoose Documents.
|
|
516
|
+
|
|
517
|
+
### TypeScript Strict
|
|
518
|
+
|
|
519
|
+
```typescript
|
|
520
|
+
process.env['VARIABLE']; // bracket notation
|
|
521
|
+
source: 'listed' as const; // literal type
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
### Quality Gates
|
|
525
|
+
|
|
526
|
+
```bash
|
|
527
|
+
bun run typecheck # MUST pass
|
|
528
|
+
bun run lint # MUST pass
|
|
529
|
+
bun run test # MUST pass
|
|
530
|
+
docker compose build # MUST pass (Docker projects)
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
### Commit Format
|
|
534
|
+
|
|
535
|
+
```
|
|
536
|
+
[type]: [description]
|
|
537
|
+
|
|
538
|
+
- Detail 1
|
|
539
|
+
- Detail 2
|
|
540
|
+
|
|
541
|
+
Generated with Claude Code
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
Types: `feat`, `fix`, `refactor`, `docs`, `chore`. NEVER commit directly to `main` — branch as `feature/` | `fix/` | `refactor/` | `test/` first.
|
|
545
|
+
|
|
546
|
+
### UI Architecture
|
|
547
|
+
|
|
548
|
+
Web apps MUST have **separate UIs** per platform — not just "responsive design".
|
|
549
|
+
|
|
550
|
+
| Platform | Layout |
|
|
551
|
+
| ----------------- | ------------------------------------------- |
|
|
552
|
+
| Mobile (375px) | Full-screen modals, bottom nav, touch-first |
|
|
553
|
+
| Tablet (768px) | Condensed dropdowns, hybrid nav |
|
|
554
|
+
| Desktop (1280px+) | Sidebar left, top navbar with search |
|
|
555
|
+
|
|
556
|
+
ANY task editing `.tsx`/`.jsx` MUST consider all 3 viewports. Use `/frontend-design` plugin or research competitors before new UI features.
|
|
557
|
+
|
|
558
|
+
### Component Organization
|
|
559
|
+
|
|
560
|
+
| Question | Location |
|
|
561
|
+
| -------------------------------- | ------------------------- |
|
|
562
|
+
| Used in ONE page only? | `app/[page]/_components/` |
|
|
563
|
+
| Used across 2+ features? | `components/shared/` |
|
|
564
|
+
| UI primitive (Button, Input)? | `components/ui/` |
|
|
565
|
+
| Layout element (Header, Footer)? | `components/layout/` |
|
|
566
|
+
|
|
567
|
+
### File Size
|
|
568
|
+
|
|
569
|
+
| Lines | Action |
|
|
570
|
+
| ------- | ---------------------------------- |
|
|
571
|
+
| < 200 | Keep in single file |
|
|
572
|
+
| 200-400 | Consider splitting |
|
|
573
|
+
| > 400 | MUST split into smaller components |
|
|
574
|
+
|
|
575
|
+
### Mandatory Planning
|
|
576
|
+
|
|
577
|
+
Use `EnterPlanMode` for non-trivial tasks BEFORE implementing.
|
|
578
|
+
|
|
579
|
+
| Task Type | Plan Required |
|
|
580
|
+
| -------------------- | ------------- |
|
|
581
|
+
| New feature | YES |
|
|
582
|
+
| UI changes (any JSX) | YES |
|
|
583
|
+
| Multi-file changes | YES |
|
|
584
|
+
| Bug fix (simple) | NO |
|
|
585
|
+
| Single-line fix | NO |
|
|
586
|
+
|
|
587
|
+
### UI Reference Material (NOT inlined here)
|
|
588
|
+
|
|
589
|
+
Detailed UI patterns — Grid Layouts, Modal/Dialog, Lists, Multi-Step Forms, Toast, Optimistic UI, Data Display, Navigation, Animation, Icon Libraries — live in:
|
|
590
|
+
|
|
591
|
+
- `.claude/skills/research-cache/cache/*.md` — pattern docs (`grid-layout-patterns-2025`, `modal-dialog-design-patterns-2024-2025`, `list-design-patterns-web-apps`, `multi-step-form-patterns`, `react-toast-notifications`, `optimistic-ui-patterns-react`, `data-display-patterns-2024-2025`, `navigation-header-design-patterns-2025`).
|
|
592
|
+
- Skills (`shadcn-ui`, `nextjs-app-router`, `react-patterns`, `tailwind-patterns`) — auto-injected by description match when relevant.
|
|
593
|
+
|
|
594
|
+
DO NOT inline this material into CLAUDE.md — it's recurring input cost for material only needed on demand. Read the cache file or skill when you actually need the pattern.
|
|
595
|
+
|
|
596
|
+
### NRY (Never Repeat Yourself)
|
|
597
|
+
|
|
598
|
+
Common Claude mistakes:
|
|
599
|
+
|
|
600
|
+
- Multi-line bash with `\` continuations (breaks permissions).
|
|
601
|
+
- Relative paths in permission patterns.
|
|
602
|
+
- Using bash for file operations (use Read/Write/Edit).
|
|
603
|
+
- Ignoring context size — use `/compact` at natural breakpoints, `/clear` when switching contexts.
|
|
604
|
+
|
|
605
|
+
---
|
|
606
|
+
|
|
607
|
+
## Updating start-vibing
|
|
608
|
+
|
|
609
|
+
```bash
|
|
610
|
+
# Update to latest version
|
|
611
|
+
npx start-vibing@latest
|
|
612
|
+
|
|
613
|
+
# Force overwrite all template files (preserves custom skills)
|
|
614
|
+
npx start-vibing --force
|
|
615
|
+
|
|
616
|
+
# Check current version
|
|
617
|
+
npx start-vibing --version
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
Template files use smart copy: `.claude/settings.json`, `CLAUDE.md`, and custom skills in `.claude/skills/` are preserved by default. Use `--force` to overwrite everything.
|