@su-record/vibe 2.8.50 → 2.8.51
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +190 -0
- package/README.md +190 -694
- package/agents/ui-previewer.md +1 -1
- package/commands/vibe.run.md +1 -1
- package/commands/vibe.spec.md +2 -2
- package/commands/vibe.utils.md +1 -1
- package/dist/cli/index.d.ts.map +1 -1
- package/dist/cli/index.js +2 -7
- package/dist/cli/index.js.map +1 -1
- package/dist/cli/postinstall/inline-skills.js +2 -2
- package/dist/cli/postinstall/inline-skills.js.map +1 -1
- package/dist/cli/postinstall/main.js +1 -1
- package/dist/cli/postinstall/main.js.map +1 -1
- package/dist/infra/lib/SkillRepository.js +2 -2
- package/package.json +1 -1
- package/skills/brand-assets/SKILL.md +1 -1
- package/skills/chub-usage/SKILL.md +33 -9
package/README.md
CHANGED
|
@@ -1,694 +1,190 @@
|
|
|
1
|
-
# VIBE
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[![
|
|
6
|
-
[![
|
|
7
|
-
[![License: MIT](https://img.shields.io/badge/
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
##
|
|
21
|
-
|
|
22
|
-
AI
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
```mermaid
|
|
47
|
-
flowchart LR
|
|
48
|
-
A["/vibe.spec"] --> B["/vibe.spec.review"]
|
|
49
|
-
B --> C["/vibe.run"]
|
|
50
|
-
C --> D["Auto Review"]
|
|
51
|
-
D --> E["Done"]
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
1.
|
|
55
|
-
2.
|
|
56
|
-
3.
|
|
57
|
-
4. **
|
|
58
|
-
|
|
59
|
-
Add `ultrawork` to
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
/vibe.run "
|
|
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
|
-
## 24 Framework Detection
|
|
195
|
-
|
|
196
|
-
Auto-detects project stack and applies framework-specific coding rules.
|
|
197
|
-
Supports monorepos (pnpm-workspace, npm workspaces, Lerna, Nx, Turborepo).
|
|
198
|
-
|
|
199
|
-
- **TypeScript (12)** — Next.js, React, Angular, Vue, Svelte, Nuxt, NestJS, Node, Electron, Tauri, React Native, Astro
|
|
200
|
-
- **Python (2)** — Django, FastAPI
|
|
201
|
-
- **Java/Kotlin (2)** — Spring Boot, Android
|
|
202
|
-
- **Other** — Rails, Go, Rust, Swift (iOS), Unity (C#), Flutter (Dart), Godot (GDScript)
|
|
203
|
-
|
|
204
|
-
Also detects: databases (PostgreSQL, MySQL, MongoDB, Redis, Prisma, Drizzle, etc.), state management (Redux, Zustand, Jotai, Pinia, etc.), CI/CD, and hosting platforms.
|
|
205
|
-
|
|
206
|
-
---
|
|
207
|
-
|
|
208
|
-
## Orchestrators
|
|
209
|
-
|
|
210
|
-
### SwarmOrchestrator
|
|
211
|
-
|
|
212
|
-
Auto-decomposes tasks with complexity score ≥ 15 into parallel subtasks.
|
|
213
|
-
Max depth 2, concurrent limit 5, default timeout 5 min.
|
|
214
|
-
|
|
215
|
-
### PhasePipeline
|
|
216
|
-
|
|
217
|
-
`prepare()` → `execute()` → `cleanup()` lifecycle.
|
|
218
|
-
In ULTRAWORK mode, the next phase's `prepare()` runs in parallel.
|
|
219
|
-
|
|
220
|
-
### BackgroundManager
|
|
221
|
-
|
|
222
|
-
Per-model/provider concurrency limits. Timeout retry (max 3, exponential backoff). 24-hour TTL auto-cleanup.
|
|
223
|
-
|
|
224
|
-
---
|
|
225
|
-
|
|
226
|
-
## Infrastructure
|
|
227
|
-
|
|
228
|
-
### Session RAG
|
|
229
|
-
|
|
230
|
-
SQLite + FTS5 hybrid search for cross-session context persistence.
|
|
231
|
-
|
|
232
|
-
**4 entity types:** Decision, Constraint, Goal, Evidence
|
|
233
|
-
|
|
234
|
-
```
|
|
235
|
-
Score = BM25 × 0.4 + Recency × 0.3 + Priority × 0.3
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
On session start, active Goals, critical Constraints, and recent Decisions are auto-injected.
|
|
239
|
-
|
|
240
|
-
### Structured Telemetry
|
|
241
|
-
|
|
242
|
-
8 typed span kinds track all operations:
|
|
243
|
-
|
|
244
|
-
`skill_run` · `agent_run` · `edit` · `build` · `review` · `hook` · `llm_call` · `decision`
|
|
245
|
-
|
|
246
|
-
Parent-child hierarchy via `parent_id`. All data stays in local JSONL.
|
|
247
|
-
|
|
248
|
-
### Evolution System
|
|
249
|
-
|
|
250
|
-
Self-improving agent/skill/rule generation with benchmarking:
|
|
251
|
-
|
|
252
|
-
- Usage tracking and insight extraction
|
|
253
|
-
- Skill gap detection
|
|
254
|
-
- Auto-generation with evaluation runners
|
|
255
|
-
- Circuit breaker and rollback safety
|
|
256
|
-
|
|
257
|
-
### Component Registry
|
|
258
|
-
|
|
259
|
-
Runtime component registration/resolution with metadata:
|
|
260
|
-
|
|
261
|
-
```typescript
|
|
262
|
-
import { ComponentRegistry } from '@su-record/vibe/tools';
|
|
263
|
-
|
|
264
|
-
const skills = new ComponentRegistry<SkillRunner>();
|
|
265
|
-
skills.register('review', () => new ReviewRunner(), { version: '2.0' });
|
|
266
|
-
const runner = skills.resolve('review');
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
---
|
|
270
|
-
|
|
271
|
-
## Hooks (21 scripts)
|
|
272
|
-
|
|
273
|
-
| Event | Script | Role |
|
|
274
|
-
|-------|--------|------|
|
|
275
|
-
| SessionStart | `session-start.js` | Restore session context, load memory |
|
|
276
|
-
| PreToolUse | `pre-tool-guard.js` | Block destructive commands, scope protection |
|
|
277
|
-
| PostToolUse | `code-check.js` | Type safety / complexity verification |
|
|
278
|
-
| PostToolUse | `post-edit.js` | Git index update |
|
|
279
|
-
| UserPromptSubmit | `prompt-dispatcher.js` | Command routing |
|
|
280
|
-
| UserPromptSubmit | `keyword-detector.js` | Magic keyword detection |
|
|
281
|
-
| UserPromptSubmit | `llm-orchestrate.js` | Multi-LLM dispatch |
|
|
282
|
-
| Notification | `context-save.js` | Auto-save at 80/90/95% context |
|
|
283
|
-
| Notification | `stop-notify.js` | Session end notification |
|
|
284
|
-
|
|
285
|
-
Additional: `codex-review-gate.js`, `codex-detect.js`, `sentinel-guard.js`, `skill-injector.js`, `evolution-engine.js`, `hud-status.js`, `auto-commit.js`, `auto-format.js`, `auto-test.js`, `command-log.js`, `pr-test-gate.js`, `figma-extract.js`
|
|
286
|
-
|
|
287
|
-
---
|
|
288
|
-
|
|
289
|
-
## Figma → Code Pipeline
|
|
290
|
-
|
|
291
|
-
Design-to-code with responsive support and design skill integration.
|
|
292
|
-
|
|
293
|
-
```bash
|
|
294
|
-
# Setup: vibe figma setup <token>
|
|
295
|
-
/vibe.figma "https://figma.com/design/ABC/Project?node-id=1-2"
|
|
296
|
-
|
|
297
|
-
# Responsive (mobile + desktop)
|
|
298
|
-
/vibe.figma "mobile-url" "desktop-url"
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
### What It Does
|
|
302
|
-
|
|
303
|
-
| Phase | Description |
|
|
304
|
-
|-------|-------------|
|
|
305
|
-
| **Extract** | Figma REST API → node tree + CSS + images (token required) |
|
|
306
|
-
| **Analyze** | Image-first analysis → viewport diff table (responsive mode) |
|
|
307
|
-
| **Generate** | Stack-aware code (React/Vue/Svelte/SCSS/Tailwind) + design tokens |
|
|
308
|
-
| **Integrate** | Maps to project's existing design system (MASTER.md, design-context.json) |
|
|
309
|
-
|
|
310
|
-
### Responsive Design
|
|
311
|
-
|
|
312
|
-
Auto-detected when 2+ URLs provided. Generates fluid scaling with `clamp()` for typography/spacing, `@media` only for layout structure changes.
|
|
313
|
-
|
|
314
|
-
| Config | Default | Description |
|
|
315
|
-
|--------|---------|-------------|
|
|
316
|
-
| `breakpoint` | 1024px | PC↔Mobile boundary |
|
|
317
|
-
| `pcTarget` | 1920px | PC main target resolution |
|
|
318
|
-
| `mobileMinimum` | 360px | Minimum mobile viewport |
|
|
319
|
-
| `designPc` | 2560px | Figma PC artboard (2x) |
|
|
320
|
-
| `designMobile` | 720px | Figma Mobile artboard (2x) |
|
|
321
|
-
|
|
322
|
-
Customize: `vibe figma breakpoints --set breakpoint=768`
|
|
323
|
-
|
|
324
|
-
### Design Skill Pipeline
|
|
325
|
-
|
|
326
|
-
After code generation, chain design skills for quality assurance:
|
|
327
|
-
|
|
328
|
-
```
|
|
329
|
-
/vibe.figma → /design-normalize → /design-audit → /design-polish
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
---
|
|
333
|
-
|
|
334
|
-
## Quality Gates
|
|
335
|
-
|
|
336
|
-
| Guard | Mechanism |
|
|
337
|
-
|-------|-----------|
|
|
338
|
-
| **Type Safety** | Quality Gate — blocks `any`, `@ts-ignore` |
|
|
339
|
-
| **Code Review** | 12 Sonnet agents parallel review + Codex triple cross-validation |
|
|
340
|
-
| **Boundary Check** | API ↔ Frontend type/routing/state consistency verification |
|
|
341
|
-
| **Completeness** | Ralph Loop — iterates until 100% (no scope reduction) |
|
|
342
|
-
| **Convergence** | P1=0 means done; scope narrows on repeated rounds |
|
|
343
|
-
| **Scope Protection** | pre-tool-guard — prevents out-of-scope modifications |
|
|
344
|
-
| **Context Protection** | context-save — auto-saves at 80/90/95% |
|
|
345
|
-
| **Evidence Gate** | No completion claims without evidence |
|
|
346
|
-
|
|
347
|
-
**Complexity limits:** Function ≤ 50 lines | Nesting ≤ 3 | Parameters ≤ 5 | Cyclomatic complexity ≤ 10
|
|
348
|
-
|
|
349
|
-
---
|
|
350
|
-
|
|
351
|
-
## Slash Commands
|
|
352
|
-
|
|
353
|
-
| Command | Description |
|
|
354
|
-
|---------|-------------|
|
|
355
|
-
| `/vibe.spec "feature"` | Write SPEC + GPT/Gemini parallel research |
|
|
356
|
-
| `/vibe.spec.review` | SPEC quality review |
|
|
357
|
-
| `/vibe.run "feature"` | Implement from SPEC + parallel code review |
|
|
358
|
-
| `/vibe.verify "feature"` | BDD verification against SPEC |
|
|
359
|
-
| `/vibe.review` | 12-agent parallel code review |
|
|
360
|
-
| `/vibe.trace "feature"` | Requirements traceability matrix |
|
|
361
|
-
| `/vibe.reason "problem"` | Systematic reasoning framework |
|
|
362
|
-
| `/vibe.analyze` | Project analysis |
|
|
363
|
-
| `/vibe.event` | Event automation |
|
|
364
|
-
| `/vibe.figma "url"` | Figma design → production code (responsive, multi-URL) |
|
|
365
|
-
| `/vibe.utils` | Utilities (E2E, diagrams, UI, session restore) |
|
|
366
|
-
|
|
367
|
-
---
|
|
368
|
-
|
|
369
|
-
## Magic Keywords
|
|
370
|
-
|
|
371
|
-
| Keyword | Effect |
|
|
372
|
-
|---------|--------|
|
|
373
|
-
| `ultrawork` / `ulw` | Parallel processing + phase pipelining + auto-continue + Ralph Loop |
|
|
374
|
-
| `ralph` | Iterate until 100% complete (no scope reduction) |
|
|
375
|
-
| `ralplan` | Iterative planning + persistence |
|
|
376
|
-
| `verify` | Strict verification mode |
|
|
377
|
-
| `quick` | Fast mode, minimal verification |
|
|
378
|
-
|
|
379
|
-
---
|
|
380
|
-
|
|
381
|
-
## CLI
|
|
382
|
-
|
|
383
|
-
```bash
|
|
384
|
-
# Project
|
|
385
|
-
vibe init [project] # Initialize project
|
|
386
|
-
vibe update # Update settings (re-detect stacks)
|
|
387
|
-
vibe upgrade # Upgrade to latest version
|
|
388
|
-
vibe setup # Interactive setup wizard
|
|
389
|
-
vibe status # Show status
|
|
390
|
-
vibe remove # Uninstall
|
|
391
|
-
|
|
392
|
-
# LLM Auth
|
|
393
|
-
vibe gpt auth|key|status|logout
|
|
394
|
-
vibe gemini auth|key|status|logout
|
|
395
|
-
vibe claude key|status|logout
|
|
396
|
-
|
|
397
|
-
# External Skills
|
|
398
|
-
vibe skills add <owner/repo> # Install skills from skills.sh
|
|
399
|
-
|
|
400
|
-
# Figma
|
|
401
|
-
vibe figma breakpoints # Show/set responsive breakpoints
|
|
402
|
-
vibe figma status|logout # Token management
|
|
403
|
-
|
|
404
|
-
# Channels
|
|
405
|
-
vibe telegram setup|chat|status
|
|
406
|
-
vibe slack setup|channel|status
|
|
407
|
-
|
|
408
|
-
# Diagnostics
|
|
409
|
-
vibe config show # Unified config view (global + project)
|
|
410
|
-
vibe stats [--week|--quality] # Usage telemetry summary
|
|
411
|
-
|
|
412
|
-
# Other
|
|
413
|
-
vibe env import [path] # Migrate .env → config.json
|
|
414
|
-
vibe help / version
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
### Auth Priority
|
|
418
|
-
|
|
419
|
-
| Provider | Priority |
|
|
420
|
-
|----------|----------|
|
|
421
|
-
| **GPT** | Codex CLI → API Key |
|
|
422
|
-
| **Gemini** | gemini-cli auto-detect → API Key |
|
|
423
|
-
|
|
424
|
-
---
|
|
425
|
-
|
|
426
|
-
## Subpath Exports
|
|
427
|
-
|
|
428
|
-
```typescript
|
|
429
|
-
import { MemoryStorage, SessionRAGStore } from '@su-record/vibe/memory';
|
|
430
|
-
import { SwarmOrchestrator, PhasePipeline } from '@su-record/vibe/orchestrator';
|
|
431
|
-
import { findSymbol, validateCodeQuality } from '@su-record/vibe/tools';
|
|
432
|
-
import { InMemoryStorage, ComponentRegistry, createSpan } from '@su-record/vibe/tools';
|
|
433
|
-
```
|
|
434
|
-
|
|
435
|
-
| Subpath | Key Exports |
|
|
436
|
-
|---------|-------------|
|
|
437
|
-
| `@su-record/vibe/memory` | `MemoryStorage`, `IMemoryStorage`, `InMemoryStorage`, `KnowledgeGraph`, `SessionRAGStore` |
|
|
438
|
-
| `@su-record/vibe/orchestrator` | `SwarmOrchestrator`, `PhasePipeline`, `BackgroundManager` |
|
|
439
|
-
| `@su-record/vibe/tools` | `findSymbol`, `validateCodeQuality`, `createSpan`, `ComponentRegistry`, etc. |
|
|
440
|
-
| `@su-record/vibe/tools/memory` | Memory tools |
|
|
441
|
-
| `@su-record/vibe/tools/convention` | Code quality tools |
|
|
442
|
-
| `@su-record/vibe/tools/semantic` | Semantic analysis (symbol search, AST, LSP) |
|
|
443
|
-
| `@su-record/vibe/tools/ui` | UI/UX tools |
|
|
444
|
-
| `@su-record/vibe/tools/interaction` | User interaction tools |
|
|
445
|
-
| `@su-record/vibe/tools/time` | Time utilities |
|
|
446
|
-
|
|
447
|
-
---
|
|
448
|
-
|
|
449
|
-
## Configuration
|
|
450
|
-
|
|
451
|
-
### Global: `~/.vibe/config.json`
|
|
452
|
-
|
|
453
|
-
Auth, channels, and model settings (file permissions `0o600`).
|
|
454
|
-
|
|
455
|
-
```json
|
|
456
|
-
{
|
|
457
|
-
"credentials": {
|
|
458
|
-
"gpt": { "apiKey": "..." },
|
|
459
|
-
"gemini": { "apiKey": "..." }
|
|
460
|
-
},
|
|
461
|
-
"channels": {
|
|
462
|
-
"telegram": { "botToken": "...", "allowedChatIds": ["..."] },
|
|
463
|
-
"slack": { "botToken": "...", "appToken": "...", "allowedChannelIds": ["..."] }
|
|
464
|
-
},
|
|
465
|
-
"models": { "gpt": "gpt-5.4", "gemini": "gemini-3.1-pro-preview" }
|
|
466
|
-
}
|
|
467
|
-
```
|
|
468
|
-
|
|
469
|
-
### Project: `.claude/vibe/config.json`
|
|
470
|
-
|
|
471
|
-
Per-project settings — language, quality, stacks, details, references, installedExternalSkills.
|
|
472
|
-
|
|
473
|
-
---
|
|
474
|
-
|
|
475
|
-
## Project Structure
|
|
476
|
-
|
|
477
|
-
```
|
|
478
|
-
your-project/
|
|
479
|
-
├── .claude/
|
|
480
|
-
│ ├── vibe/
|
|
481
|
-
│ │ ├── config.json # Project config
|
|
482
|
-
│ │ ├── constitution.md # Project principles
|
|
483
|
-
│ │ ├── specs/ # SPEC documents
|
|
484
|
-
│ │ ├── features/ # Feature tracking
|
|
485
|
-
│ │ ├── todos/ # P1/P2/P3 issues
|
|
486
|
-
│ │ └── reports/ # Review reports
|
|
487
|
-
│ └── skills/ # Local + external skills
|
|
488
|
-
├── CLAUDE.md # Project guide (auto-generated)
|
|
489
|
-
├── AGENTS.md # Codex CLI guide (auto-generated)
|
|
490
|
-
└── ...
|
|
491
|
-
|
|
492
|
-
~/.vibe/config.json # Global config (auth, channels, models)
|
|
493
|
-
~/.vibe/analytics/ # Telemetry (local JSONL)
|
|
494
|
-
│ ├── skill-usage.jsonl
|
|
495
|
-
│ ├── spans.jsonl
|
|
496
|
-
│ └── decisions.jsonl
|
|
497
|
-
~/.claude/
|
|
498
|
-
├── vibe/
|
|
499
|
-
│ ├── rules/ # Coding rules
|
|
500
|
-
│ ├── skills/ # Global skills
|
|
501
|
-
│ └── ui-ux-data/ # UI/UX CSV datasets (48 files)
|
|
502
|
-
├── commands/ # Slash commands
|
|
503
|
-
└── agents/ # Agent definitions (56)
|
|
504
|
-
~/.codex/
|
|
505
|
-
└── plugins/vibe/ # Codex plugin
|
|
506
|
-
├── .codex-plugin/plugin.json
|
|
507
|
-
├── agents/
|
|
508
|
-
├── skills/
|
|
509
|
-
└── AGENTS.md
|
|
510
|
-
```
|
|
511
|
-
|
|
512
|
-
---
|
|
513
|
-
|
|
514
|
-
## Architecture
|
|
515
|
-
|
|
516
|
-
```mermaid
|
|
517
|
-
flowchart TD
|
|
518
|
-
A["User Request"] --> B["keyword-detector"]
|
|
519
|
-
B --> C["prompt-dispatcher"]
|
|
520
|
-
C --> D["SmartRouter"]
|
|
521
|
-
|
|
522
|
-
D --> E["LLMCluster"]
|
|
523
|
-
E --> E1["GPT (Reasoning)"]
|
|
524
|
-
E --> E2["Gemini (Research)"]
|
|
525
|
-
|
|
526
|
-
D --> F["PhasePipeline"]
|
|
527
|
-
F --> G["SwarmOrchestrator"]
|
|
528
|
-
G --> H["BackgroundManager"]
|
|
529
|
-
H --> I["AgentRegistry"]
|
|
530
|
-
|
|
531
|
-
D --> J["Parallel Review"]
|
|
532
|
-
J --> J1["12 Sonnet Review Agents"]
|
|
533
|
-
J --> J2["Codex Review"]
|
|
534
|
-
J1 --> K["Triple Cross-Validation → P1/P2/P3"]
|
|
535
|
-
J2 --> K
|
|
536
|
-
J --> J3["Boundary Verification"]
|
|
537
|
-
|
|
538
|
-
L["Session RAG"] -.-> M["Decision / Constraint / Goal / Evidence"]
|
|
539
|
-
N["VibeSpan"] -.-> O["spans.jsonl (Local Telemetry)"]
|
|
540
|
-
P["Quality Gate"] -.-> Q["pre-tool-guard → Block"]
|
|
541
|
-
P -.-> R["code-check → Verify"]
|
|
542
|
-
```
|
|
543
|
-
|
|
544
|
-
---
|
|
545
|
-
|
|
546
|
-
## 하네스 시스템 (Harness System)
|
|
547
|
-
|
|
548
|
-
> **Agent = Model + Harness**
|
|
549
|
-
|
|
550
|
-
하네스는 AI 에이전트에서 **모델을 제외한 모든 것** — AI가 일하는 환경 전체입니다.
|
|
551
|
-
`vibe init` 한 번으로 가이드(Guides)와 센서(Sensors)가 설치되어, AI가 올바른 방향으로 일하고 스스로 교정하는 구조를 만듭니다.
|
|
552
|
-
|
|
553
|
-
| 축 | 역할 | 구성 요소 |
|
|
554
|
-
|---|------|----------|
|
|
555
|
-
| **Guides** (피드포워드) | 행동 **전에** 방향 설정 | CLAUDE.md, 규칙, 에이전트 56개, 스킬 45개, 커맨드 |
|
|
556
|
-
| **Sensors** (피드백) | 행동 **후에** 관찰·교정 | 훅 21개 (품질 게이트, 자동 테스트), 이볼루션 엔진 |
|
|
557
|
-
|
|
558
|
-
### 구성 요소
|
|
559
|
-
|
|
560
|
-
| 구성 요소 | 분류 | 역할 |
|
|
561
|
-
|-----------|------|------|
|
|
562
|
-
| **CLAUDE.md / 규칙** | Guide | 프로젝트 지침, 코딩 표준 — AI가 읽고 따르는 컨텍스트 |
|
|
563
|
-
| **에이전트 (56개)** | Guide | 탐색·구현·아키텍처·리뷰·QA·UI/UX 전문 페르소나 |
|
|
564
|
-
| **스킬 (45개, 3티어)** | Guide | 도메인별 재사용 워크플로우 모듈 |
|
|
565
|
-
| **커맨드** | Guide | 구조화된 작업 인터페이스 (/vibe.spec, /vibe.run 등) |
|
|
566
|
-
| **훅 (21개)** | Sensor | 라이프사이클 이벤트 인터셉트 — 위험 차단, 품질 검증 |
|
|
567
|
-
| **품질 게이트 (3계층)** | Sensor | 센티넬 가드 → 프리툴 가드 → 코드 체크 |
|
|
568
|
-
| **LLM 비용 추적** | Sensor | llm-costs.jsonl — 프로바이더별 토큰·비용·지연 시간 기록 |
|
|
569
|
-
| **롤백 체크포인트** | Sensor | 자동 커밋마다 `vibe-checkpoint-N` 태그 생성 (최근 5개 유지) |
|
|
570
|
-
| **에스컬레이션** | Sensor | 동일 파일 P1/P2 이슈 3회 반복 → 사용자 개입 요청 |
|
|
571
|
-
| **Session RAG / 메모리** | Both | 세션 간 컨텍스트 지속 + 자동 복원 |
|
|
572
|
-
| **이볼루션 엔진** | Sensor | 훅 실행 패턴 분석 → 규칙/스킬 자기 개선 |
|
|
573
|
-
| **텔레메트리** | Sensor | hook-traces.jsonl, spans.jsonl — 관찰 가능성 |
|
|
574
|
-
|
|
575
|
-
### 훅 실행 흐름
|
|
576
|
-
|
|
577
|
-
```
|
|
578
|
-
사용자 액션 (Bash / Edit / Write / Prompt)
|
|
579
|
-
↓
|
|
580
|
-
SessionStart ─── session-start.js
|
|
581
|
-
세션 메모리 복원, 컨텍스트 로드, 하네스 버전 체크
|
|
582
|
-
↓
|
|
583
|
-
PreToolUse ──── sentinel-guard.js → pre-tool-guard.js
|
|
584
|
-
파괴적 명령 차단 (rm -rf, force push, DB drop 등)
|
|
585
|
-
↓
|
|
586
|
-
[도구 실행]
|
|
587
|
-
↓
|
|
588
|
-
PostToolUse ─── auto-format.js → code-check.js → auto-test.js
|
|
589
|
-
자동 포맷 → 타입 안전성·복잡도 검증 → 테스트 실행
|
|
590
|
-
↓
|
|
591
|
-
UserPromptSubmit ── prompt-dispatcher.js → keyword-detector.js → llm-orchestrate.js
|
|
592
|
-
커맨드 라우팅 → 매직 키워드 감지 → 외부 LLM 디스패치
|
|
593
|
-
↓
|
|
594
|
-
Notification ─── context-save.js
|
|
595
|
-
컨텍스트 80/90/95%에서 자동 저장
|
|
596
|
-
↓
|
|
597
|
-
Stop ──────── codex-review-gate.js → stop-notify.js → auto-commit.js
|
|
598
|
-
리뷰 게이트 → 세션 종료 알림 → 자동 커밋 + 롤백 체크포인트
|
|
599
|
-
```
|
|
600
|
-
|
|
601
|
-
### 3계층 품질 게이트
|
|
602
|
-
|
|
603
|
-
| 계층 | 스크립트 | 검증 내용 |
|
|
604
|
-
|------|---------|----------|
|
|
605
|
-
| **1. 센티넬 가드** | `sentinel-guard.js` | `rm -rf /`, `git reset --hard`, DB drop, fork bomb 등 치명적 명령 원천 차단 |
|
|
606
|
-
| **2. 프리툴 가드** | `pre-tool-guard.js` | 위험 패턴 경고 — force push, .env 수정, 시스템 디렉토리 쓰기 |
|
|
607
|
-
| **3. 코드 체크** | `code-check.js` | `any` 타입 차단, `@ts-ignore` 차단, 함수 ≤50줄, 중첩 ≤3, 파라미터 ≤5, 순환복잡도 ≤10 |
|
|
608
|
-
|
|
609
|
-
### 스킬 티어 시스템
|
|
610
|
-
|
|
611
|
-
컨텍스트 과부하(Curse of Instructions)를 방지하기 위해 스킬을 3단계로 분류합니다.
|
|
612
|
-
|
|
613
|
-
| 티어 | 로딩 방식 | 목적 | 예시 |
|
|
614
|
-
|------|----------|------|------|
|
|
615
|
-
| **Core** | 항상 활성 | 버그·실수 방지 안전망 | techdebt, arch-guard, exec-plan |
|
|
616
|
-
| **Standard** | 프로젝트 스택에 따라 선택 | 워크플로우 지원 | parallel-research, handoff, design-teach |
|
|
617
|
-
| **Optional** | 명시적 `/skill`로만 호출 | 래퍼/참조용 | commit-push-pr, git-worktree, context7 |
|
|
618
|
-
|
|
619
|
-
### 이볼루션 엔진 (자기 개선)
|
|
620
|
-
|
|
621
|
-
```
|
|
622
|
-
훅 실행 추적 (spans.jsonl)
|
|
623
|
-
↓
|
|
624
|
-
패턴 분석 — 반복 차단 패턴 클러스터링 (7일 히스토리)
|
|
625
|
-
↓
|
|
626
|
-
인사이트 생성 — 최적화/경고/갭 분류 + 신뢰도 점수
|
|
627
|
-
↓
|
|
628
|
-
규칙·스킬 자동 생성 (suggest 또는 auto 모드)
|
|
629
|
-
↓
|
|
630
|
-
서킷 브레이커 — 회귀 발생 시 롤백
|
|
631
|
-
```
|
|
632
|
-
|
|
633
|
-
### LLM 비용 추적
|
|
634
|
-
|
|
635
|
-
외부 LLM(GPT, Gemini) 호출마다 토큰, 비용, 지연 시간을 `~/.vibe/llm-costs.jsonl`에 기록합니다.
|
|
636
|
-
캐시 히트 시 비용 0으로 기록. 프로바이더별 모델 단가 자동 적용.
|
|
637
|
-
|
|
638
|
-
```jsonl
|
|
639
|
-
{"ts":"...","provider":"gpt","model":"gpt-5.4","inputTokens":150,"outputTokens":420,"cost":0.0069,"durationMs":2340,"cached":false}
|
|
640
|
-
```
|
|
641
|
-
|
|
642
|
-
`vibe stats --quality`로 누적 비용 확인 가능.
|
|
643
|
-
|
|
644
|
-
### 롤백 체크포인트
|
|
645
|
-
|
|
646
|
-
에이전트 자동 커밋마다 `vibe-checkpoint-N` git 태그를 생성합니다.
|
|
647
|
-
문제 발생 시 한 줄로 롤백:
|
|
648
|
-
|
|
649
|
-
```bash
|
|
650
|
-
git reset --hard vibe-checkpoint-3
|
|
651
|
-
```
|
|
652
|
-
|
|
653
|
-
최근 5개만 유지, 오래된 체크포인트는 자동 정리.
|
|
654
|
-
|
|
655
|
-
### 에스컬레이션 (Human-in-the-loop)
|
|
656
|
-
|
|
657
|
-
동일 파일에서 P1/P2 이슈가 3회 반복되면 자동 수정을 멈추고 사용자에게 개입을 요청합니다.
|
|
658
|
-
|
|
659
|
-
```
|
|
660
|
-
🚨 [ESCALATION] auth.ts: 동일 이슈 3회 반복
|
|
661
|
-
→ 사용자 개입 필요 — 자동 수정이 수렴하지 않고 있습니다.
|
|
662
|
-
```
|
|
663
|
-
|
|
664
|
-
AI가 같은 실수를 반복하며 맴도는 것을 방지하는 센서입니다.
|
|
665
|
-
|
|
666
|
-
### 설치 흐름
|
|
667
|
-
|
|
668
|
-
```bash
|
|
669
|
-
npm install -g @su-record/vibe # postinstall → 글로벌 에셋 배포
|
|
670
|
-
vibe init # 프로젝트 하네스 설치
|
|
671
|
-
```
|
|
672
|
-
|
|
673
|
-
**postinstall** (글로벌):
|
|
674
|
-
- `~/.claude/agents/` — 56개 에이전트 정의
|
|
675
|
-
- `~/.claude/skills/` — 글로벌 스킬
|
|
676
|
-
- `~/.claude/commands/` — 슬래시 커맨드
|
|
677
|
-
|
|
678
|
-
**vibe init** (프로젝트):
|
|
679
|
-
- 24개 프레임워크 자동 감지
|
|
680
|
-
- `.claude/settings.local.json`에 훅 등록
|
|
681
|
-
- 스택별 스킬·규칙 설치
|
|
682
|
-
- `CLAUDE.md` 생성 (프레임워크별 코딩 규칙)
|
|
683
|
-
|
|
684
|
-
---
|
|
685
|
-
|
|
686
|
-
## Requirements
|
|
687
|
-
|
|
688
|
-
- **Node.js** >= 18.0.0
|
|
689
|
-
- **Claude Code** (required)
|
|
690
|
-
- GPT, Gemini (optional — for multi-LLM features)
|
|
691
|
-
|
|
692
|
-
## License
|
|
693
|
-
|
|
694
|
-
MIT License - Copyright (c) 2025 Su
|
|
1
|
+
# VIBE
|
|
2
|
+
|
|
3
|
+
**AI writes code. Vibe makes sure it's good.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@su-record/vibe)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
9
|
+
> One install. 56 agents, 45 skills, multi-LLM orchestration, and automated quality gates — added to your existing AI coding workflow.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g @su-record/vibe
|
|
13
|
+
vibe init
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Works with **Claude Code**, **Codex**, **Cursor**, and **Gemini CLI**.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## The Problem
|
|
21
|
+
|
|
22
|
+
AI coding tools generate working code, but:
|
|
23
|
+
|
|
24
|
+
- Types are `any`, reviews are skipped, tests are forgotten
|
|
25
|
+
- You catch issues manually — after the damage is done
|
|
26
|
+
- Context vanishes between sessions
|
|
27
|
+
- Complex tasks spiral without structure
|
|
28
|
+
|
|
29
|
+
**Vibe is a harness.** It wraps around your AI coding tool and enforces quality automatically — before, during, and after code generation.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## How It Works
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
Agent = Model + Harness
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
| | Role | What's Inside |
|
|
40
|
+
|---|------|--------------|
|
|
41
|
+
| **Guides** (feedforward) | Set direction *before* action | CLAUDE.md, 56 agents, 45 skills, coding rules |
|
|
42
|
+
| **Sensors** (feedback) | Observe and correct *after* action | 21 hooks, quality gates, evolution engine |
|
|
43
|
+
|
|
44
|
+
### Workflow
|
|
45
|
+
|
|
46
|
+
```mermaid
|
|
47
|
+
flowchart LR
|
|
48
|
+
A["/vibe.spec"] --> B["/vibe.spec.review"]
|
|
49
|
+
B --> C["/vibe.run"]
|
|
50
|
+
C --> D["Auto Review"]
|
|
51
|
+
D --> E["Done"]
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
1. **Define** — `/vibe.spec` writes requirements with GPT + Gemini parallel research
|
|
55
|
+
2. **Review** — `/vibe.spec.review` runs triple cross-validation (Claude + GPT + Gemini)
|
|
56
|
+
3. **Implement** — `/vibe.run` builds from SPEC with parallel code review
|
|
57
|
+
4. **Verify** — 12 agents review in parallel, P1/P2 issues auto-fixed
|
|
58
|
+
|
|
59
|
+
Add `ultrawork` to run the entire pipeline hands-free:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
/vibe.run "add user authentication" ultrawork
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Key Features
|
|
68
|
+
|
|
69
|
+
**Quality Gates** — Blocks `any` types, `@ts-ignore`, functions > 50 lines. Three-layer defense: sentinel guard → pre-tool guard → code check.
|
|
70
|
+
|
|
71
|
+
**56 Specialized Agents** — Exploration, implementation, architecture, 12 parallel reviewers, 8 UI/UX agents, QA coordination. Each agent is purpose-built, not a generic wrapper.
|
|
72
|
+
|
|
73
|
+
**Multi-LLM Orchestration** — Claude for orchestration, GPT for reasoning, Gemini for research. Auto-routes based on available models. Works Claude-only by default.
|
|
74
|
+
|
|
75
|
+
**Session RAG** — SQLite + FTS5 hybrid search persists decisions, constraints, and goals across sessions. Context is restored automatically on session start.
|
|
76
|
+
|
|
77
|
+
**24 Framework Detection** — Auto-detects your stack (Next.js, React, Django, Spring Boot, Rails, Go, Rust, and 17 more) and applies framework-specific rules. Monorepo-aware.
|
|
78
|
+
|
|
79
|
+
**Self-Improvement** — Evolution engine analyzes hook execution patterns, detects skill gaps, and generates new rules. Circuit breaker rolls back on regression.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## What's Included
|
|
84
|
+
|
|
85
|
+
| Category | Count | Examples |
|
|
86
|
+
|----------|-------|---------|
|
|
87
|
+
| **Agents** | 56 | Explorer, Implementer, Architect (3 depth levels each), 12 review specialists, 8 UI/UX, QA coordinator |
|
|
88
|
+
| **Skills** | 45 | 3-tier system (core/standard/optional) to prevent context overload |
|
|
89
|
+
| **Hooks** | 21 | Session restore, destructive command blocking, auto-format, quality check, context auto-save |
|
|
90
|
+
| **Frameworks** | 24 | TypeScript (12), Python (2), Java/Kotlin (2), Rails, Go, Rust, Swift, Flutter, Unity, Godot |
|
|
91
|
+
| **Slash Commands** | 11 | `/vibe.spec`, `/vibe.run`, `/vibe.review`, `/vibe.trace`, `/vibe.figma`, and more |
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Multi-CLI Support
|
|
96
|
+
|
|
97
|
+
| CLI | Agents | Skills | Instructions |
|
|
98
|
+
|-----|--------|--------|-------------|
|
|
99
|
+
| Claude Code | `~/.claude/agents/` | `~/.claude/skills/` | `CLAUDE.md` |
|
|
100
|
+
| Codex | `~/.codex/plugins/vibe/` | Plugin built-in | `AGENTS.md` |
|
|
101
|
+
| Cursor | `~/.cursor/agents/` | `~/.cursor/skills/` | `.cursorrules` |
|
|
102
|
+
| Gemini CLI | `~/.gemini/agents/` | `~/.gemini/skills/` | `GEMINI.md` |
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Multi-LLM Routing
|
|
107
|
+
|
|
108
|
+
| Provider | Role | Required |
|
|
109
|
+
|----------|------|----------|
|
|
110
|
+
| **Claude** | Orchestration, SPEC, review | Yes (via Claude Code) |
|
|
111
|
+
| **GPT** | Reasoning, architecture, edge cases | Optional (Codex CLI or API key) |
|
|
112
|
+
| **Gemini** | Research, cross-validation, UI/UX | Optional (gemini-cli or API key) |
|
|
113
|
+
|
|
114
|
+
Auto-switches based on model availability. Claude-only is the default — GPT and Gemini enhance but aren't required.
|
|
115
|
+
|
|
116
|
+
Codex CLI or gemini-cli are auto-detected if installed. To set API keys manually:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
vibe gpt key <your-api-key>
|
|
120
|
+
vibe gemini key <your-api-key>
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Figma → Code
|
|
126
|
+
|
|
127
|
+
Design-to-code pipeline with tree-based structural mapping (not screenshot guessing).
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
/vibe.figma "https://figma.com/design/ABC/Project?node-id=1-2"
|
|
131
|
+
|
|
132
|
+
# Responsive (mobile + desktop)
|
|
133
|
+
/vibe.figma "mobile-url" "desktop-url"
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Extracts via Figma REST API → generates stack-aware code (React/Vue/Svelte/SCSS/Tailwind) → maps to your existing design system.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## CLI Reference
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
vibe init # Initialize project (detect stack, install harness)
|
|
144
|
+
vibe update # Re-detect stacks, refresh config
|
|
145
|
+
vibe upgrade # Upgrade to latest version
|
|
146
|
+
vibe status # Show current status
|
|
147
|
+
vibe config show # Unified config view
|
|
148
|
+
vibe stats [--week|--quality] # Usage telemetry
|
|
149
|
+
|
|
150
|
+
vibe gpt key|status # GPT API key setup
|
|
151
|
+
vibe gemini key|status # Gemini API key setup
|
|
152
|
+
vibe figma breakpoints # Responsive breakpoints
|
|
153
|
+
vibe skills add <owner/repo> # Install skills from skills.sh
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Configuration
|
|
159
|
+
|
|
160
|
+
| File | Purpose |
|
|
161
|
+
|------|---------|
|
|
162
|
+
| `~/.vibe/config.json` | Global — credentials, channels, models (0o600) |
|
|
163
|
+
| `.claude/vibe/config.json` | Project — stacks, capabilities, quality settings |
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Magic Keywords
|
|
168
|
+
|
|
169
|
+
| Keyword | Effect |
|
|
170
|
+
|---------|--------|
|
|
171
|
+
| `ultrawork` | Full automation — parallel agents + auto-continue + quality loop |
|
|
172
|
+
| `ralph` | Iterate until 100% complete (no scope reduction) |
|
|
173
|
+
| `quick` | Fast mode, minimal verification |
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Requirements
|
|
178
|
+
|
|
179
|
+
- Node.js >= 18.0.0
|
|
180
|
+
- Claude Code (required)
|
|
181
|
+
- GPT, Gemini (optional — for multi-LLM features)
|
|
182
|
+
|
|
183
|
+
## Documentation
|
|
184
|
+
|
|
185
|
+
- [README (Korean)](README.ko.md)
|
|
186
|
+
- [Release Notes](RELEASE_NOTES.md)
|
|
187
|
+
|
|
188
|
+
## License
|
|
189
|
+
|
|
190
|
+
MIT — Copyright (c) 2025 Su
|