@su-record/vibe 2.8.50 → 2.8.52

package/README.md

@@ -1,694 +1,190 @@
-# VIBE — AI Coding Framework
-
-[![npm version](https://img.shields.io/npm/v/@su-record/vibe)](https://www.npmjs.com/package/@su-record/vibe)
-[![npm downloads](https://img.shields.io/npm/dt/@su-record/vibe.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@su-record/vibe)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.5+-blue)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**One install adds 56 agents, 45 skills, multi-LLM orchestration, and automated quality gates to your AI coding workflow.**
-
-Works with Claude Code, Codex, Cursor, and Gemini CLI.
-
-```bash
-npm install -g @su-record/vibe
-vibe init
-```
-
----
-
-## Why Vibe
-
-AI generates working code, but quality is left to chance.
-Vibe solves this structurally.
-
-| Problem | Solution |
-|---------|----------|
-| AI scatters `any` types | Quality Gate blocks `any` / `@ts-ignore` |
-| Expecting one-shot perfection | SPEC → Implement → Verify staged workflow |
-| Merging without review | 12 agents run parallel code review |
-| Accepting AI output blindly | GPT + Gemini cross-validation |
-| Losing context between sessions | Session RAG auto-saves and restores |
-| Getting lost on complex tasks | SwarmOrchestrator auto-decomposes + parallelizes |
-
-### Design Philosophy
-
-| Principle | Description |
-|-----------|-------------|
-| **Easy Vibe Coding** | Fast flow — think collaboratively with AI |
-| **Minimum Quality Guaranteed** | Type safety, code quality, security — automatic baseline |
-| **Iterative Reasoning** | Break down problems, ask questions, reason together |
-
----
-
-## Workflow
-
-```mermaid
-flowchart LR
-    A["/vibe.spec"] --> B["/vibe.spec.review"]
-    B --> C["/vibe.run"]
-    C --> D["Auto Review"]
-    D --> E["Done"]
-```
-
-1. **`/vibe.spec`** — Define requirements as a SPEC document (GPT + Gemini parallel research)
-2. **`/vibe.spec.review`** — SPEC quality review + Codex adversarial review (triple cross-validation)
-3. **`/vibe.run`** — Implement from SPEC (Codex rescue parallel delegation) + triple code review
-4. **Auto Review** — 12 specialized agents review in parallel + boundary verification, P1/P2 auto-fix
-
-Add `ultrawork` to automate the entire pipeline:
-
-```bash
-/vibe.run "feature" ultrawork
-```
-
----
-
-## Multi-CLI Support
-
-| CLI | Install Location | Agents | Skills | Instructions |
-|-----|-----------------|--------|--------|-------------|
-| **Claude Code** | `~/.claude/agents/` | 56 | `~/.claude/skills/` | `CLAUDE.md` |
-| **Codex** | `~/.codex/plugins/vibe/` | 56 | Plugin built-in | `AGENTS.md` |
-| **Cursor** | `~/.cursor/agents/` | 56 | `~/.cursor/skills/` | `.cursorrules` |
-| **Gemini CLI** | `~/.gemini/agents/` | 56 | `~/.gemini/skills/` | `GEMINI.md` |
-
-### Codex Plugin Integration
-
-When the Codex Claude Code plugin (`codex-plugin-cc`) is installed, Vibe automatically integrates it across every workflow stage:
-
-| Workflow | Codex Usage | Command |
-|----------|------------|---------|
-| **spec review** | Adversarial SPEC challenge | `/codex:adversarial-review` |
-| **run** | Parallel implementation delegation | `/codex:rescue --background` |
-| **run / review** | Triple code review (GPT + Gemini + Codex) | `/codex:review` |
-| **run / review** | Fallback on auto-fix failure | `/codex:rescue` |
-| **verify** | Final review gate | `/codex:review` |
-| **Stop hook** | Auto-review on code changes | `codex-review-gate.js` |
-
-Auto-skips when Codex is not installed — existing workflow continues as-is.
-
----
-
-## Agents (56)
-
-### Core Agents (19)
-
-| Category | Agents |
-|----------|--------|
-| **Exploration** | Explorer (High / Medium / Low) |
-| **Implementation** | Implementer (High / Medium / Low) |
-| **Architecture** | Architect (High / Medium / Low) |
-| **Utility** | Searcher, Tester, Simplifier, Refactor Cleaner, Build Error Resolver, Compounder, Diagrammer, E2E Tester, UI Previewer, Junior Mentor |
-
-### Review Agents (12)
-
-Security, Performance, Architecture, Complexity, Simplicity, Data Integrity, Test Coverage, Git History, TypeScript, Python, Rails, React
-
-### UI/UX Agents (8)
-
-Design intelligence backed by 48 CSV datasets. Industry analysis → Design system generation → Implementation guide → Accessibility audit.
-
-| Phase | Agents |
-|-------|--------|
-| SPEC | ui-industry-analyzer, ui-design-system-gen, ui-layout-architect |
-| RUN | ui-stack-implementer, ui-dataviz-advisor |
-| REVIEW | ux-compliance-reviewer, ui-a11y-auditor, ui-antipattern-detector |
-
-### QA & Research (11)
-
-| Category | Agents |
-|----------|--------|
-| **QA** | QA Coordinator, Edge Case Finder, Acceptance Tester |
-| **Research** | Best Practices, Framework Docs, Codebase Patterns, Security Advisory |
-| **Analysis** | Requirements Analyst, UX Advisor, API Documenter, Changelog Writer |
-
-QA Coordinator analyzes changed code and dispatches appropriate QA agents in parallel, then produces a unified QA report.
-
-### Event Agents (6)
-
-Event Content, Event Image, Event Speaker, Event Ops, Event Comms, Event Scheduler
-
----
-
-## Skills (45)
-
-Domain-specific skill modules auto-installed based on detected stack. Classified into 3 tiers to prevent context overload.
-
-**Core (4):** Tech Debt, Characterization Test, Arch Guard, Exec Plan
-
-**Standard (11):** Parallel Research, Handoff, Priority Todos, Agents MD, Claude MD Guide, Capability Loop, Design Teach, Vibe Figma, Vibe Figma Extract, Vibe Figma Convert, Vibe Docs
-
-**Optional (4):** Commit Push PR, Git Worktree, Tool Fallback, Context7
-
-**Design (8):** UI/UX Pro Max, Design Audit, Design Critique, Design Polish, Design Normalize, Design Distill, Brand Assets, SEO Checklist
-
-**Domain (3):** Commerce Patterns, E2E Commerce, Video Production
-
-**PM (3):** Create PRD, Prioritization Frameworks, User Personas
-
-**Event (3):** Event Planning, Event Comms, Event Ops
-
-**Stack-Specific (2):** TypeScript Advanced Types, Vercel React Best Practices
-
-**Figma Pipeline (7):** Figma Rules, Figma Pipeline, Figma Frame, Figma Style, Figma Analyze, Figma Consolidate, Figma Codegen
-
-### External Skills (skills.sh)
-
-Install community skills from the [skills.sh](https://skills.sh) ecosystem:
-
-```bash
-vibe skills add vercel-labs/next-skills
-```
-
-Auto-installed by stack during `vibe init` / `vibe update`:
-
-| Stack | Auto-installed Package |
-|-------|----------------------|
-| `typescript-react` | `vercel-labs/agent-skills` |
-| `typescript-nextjs` | `vercel-labs/agent-skills`, `vercel-labs/next-skills` |
-
----
-
-## Multi-LLM Orchestration
-
-| Provider | Role | Auth |
-|----------|------|------|
-| **Claude** (Opus / Sonnet / Haiku) | SPEC writing, code review, orchestration | Built-in (Claude Code) |
-| **GPT** | Reasoning, architecture, edge-case analysis | Codex CLI / API Key |
-| **Gemini** | Research, cross-validation, UI/UX | gemini-cli / API Key |
-
-### Dynamic Model Routing
-
-Auto-switches based on active LLM availability. Defaults to Claude-only operation.
-
-| State | Behavior |
-|-------|----------|
-| **Claude only** | Opus (design/judgment) + Sonnet (review/implementation) + Haiku (exploration) |
-| **+ GPT** | Implementation → GPT, review → GPT, reasoning → GPT |
-| **+ Gemini** | Research/review gets parallel Gemini |
-| **+ GPT + Gemini** | Full orchestration across all models |
-
----
-
-## 24 Framework Detection
-
-Auto-detects project stack and applies framework-specific coding rules.
-Supports monorepos (pnpm-workspace, npm workspaces, Lerna, Nx, Turborepo).
-
-- **TypeScript (12)** — Next.js, React, Angular, Vue, Svelte, Nuxt, NestJS, Node, Electron, Tauri, React Native, Astro
-- **Python (2)** — Django, FastAPI
-- **Java/Kotlin (2)** — Spring Boot, Android
-- **Other** — Rails, Go, Rust, Swift (iOS), Unity (C#), Flutter (Dart), Godot (GDScript)
-
-Also detects: databases (PostgreSQL, MySQL, MongoDB, Redis, Prisma, Drizzle, etc.), state management (Redux, Zustand, Jotai, Pinia, etc.), CI/CD, and hosting platforms.
-
----
-
-## Orchestrators
-
-### SwarmOrchestrator
-
-Auto-decomposes tasks with complexity score ≥ 15 into parallel subtasks.
-Max depth 2, concurrent limit 5, default timeout 5 min.
-
-### PhasePipeline
-
-`prepare()` → `execute()` → `cleanup()` lifecycle.
-In ULTRAWORK mode, the next phase's `prepare()` runs in parallel.
-
-### BackgroundManager
-
-Per-model/provider concurrency limits. Timeout retry (max 3, exponential backoff). 24-hour TTL auto-cleanup.
-
----
-
-## Infrastructure
-
-### Session RAG
-
-SQLite + FTS5 hybrid search for cross-session context persistence.
-
-**4 entity types:** Decision, Constraint, Goal, Evidence
-
-```
-Score = BM25 × 0.4 + Recency × 0.3 + Priority × 0.3
-```
-
-On session start, active Goals, critical Constraints, and recent Decisions are auto-injected.
-
-### Structured Telemetry
-
-8 typed span kinds track all operations:
-
-`skill_run` · `agent_run` · `edit` · `build` · `review` · `hook` · `llm_call` · `decision`
-
-Parent-child hierarchy via `parent_id`. All data stays in local JSONL.
-
-### Evolution System
-
-Self-improving agent/skill/rule generation with benchmarking:
-
-- Usage tracking and insight extraction
-- Skill gap detection
-- Auto-generation with evaluation runners
-- Circuit breaker and rollback safety
-
-### Component Registry
-
-Runtime component registration/resolution with metadata:
-
-```typescript
-import { ComponentRegistry } from '@su-record/vibe/tools';
-
-const skills = new ComponentRegistry<SkillRunner>();
-skills.register('review', () => new ReviewRunner(), { version: '2.0' });
-const runner = skills.resolve('review');
-```
-
----
-
-## Hooks (21 scripts)
-
-| Event | Script | Role |
-|-------|--------|------|
-| SessionStart | `session-start.js` | Restore session context, load memory |
-| PreToolUse | `pre-tool-guard.js` | Block destructive commands, scope protection |
-| PostToolUse | `code-check.js` | Type safety / complexity verification |
-| PostToolUse | `post-edit.js` | Git index update |
-| UserPromptSubmit | `prompt-dispatcher.js` | Command routing |
-| UserPromptSubmit | `keyword-detector.js` | Magic keyword detection |
-| UserPromptSubmit | `llm-orchestrate.js` | Multi-LLM dispatch |
-| Notification | `context-save.js` | Auto-save at 80/90/95% context |
-| Notification | `stop-notify.js` | Session end notification |
-
-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`
-
----
-
-## Figma → Code Pipeline
-
-Design-to-code with responsive support and design skill integration.
-
-```bash
-# Setup: vibe figma setup <token>
-/vibe.figma "https://figma.com/design/ABC/Project?node-id=1-2"
-
-# Responsive (mobile + desktop)
-/vibe.figma "mobile-url" "desktop-url"
-```
-
-### What It Does
-
-| Phase | Description |
-|-------|-------------|
-| **Extract** | Figma REST API → node tree + CSS + images (token required) |
-| **Analyze** | Image-first analysis → viewport diff table (responsive mode) |
-| **Generate** | Stack-aware code (React/Vue/Svelte/SCSS/Tailwind) + design tokens |
-| **Integrate** | Maps to project's existing design system (MASTER.md, design-context.json) |
-
-### Responsive Design
-
-Auto-detected when 2+ URLs provided. Generates fluid scaling with `clamp()` for typography/spacing, `@media` only for layout structure changes.
-
-| Config | Default | Description |
-|--------|---------|-------------|
-| `breakpoint` | 1024px | PC↔Mobile boundary |
-| `pcTarget` | 1920px | PC main target resolution |
-| `mobileMinimum` | 360px | Minimum mobile viewport |
-| `designPc` | 2560px | Figma PC artboard (2x) |
-| `designMobile` | 720px | Figma Mobile artboard (2x) |
-
-Customize: `vibe figma breakpoints --set breakpoint=768`
-
-### Design Skill Pipeline
-
-After code generation, chain design skills for quality assurance:
-
-```
-/vibe.figma → /design-normalize → /design-audit → /design-polish
-```
-
----
-
-## Quality Gates
-
-| Guard | Mechanism |
-|-------|-----------|
-| **Type Safety** | Quality Gate — blocks `any`, `@ts-ignore` |
-| **Code Review** | 12 Sonnet agents parallel review + Codex triple cross-validation |
-| **Boundary Check** | API ↔ Frontend type/routing/state consistency verification |
-| **Completeness** | Ralph Loop — iterates until 100% (no scope reduction) |
-| **Convergence** | P1=0 means done; scope narrows on repeated rounds |
-| **Scope Protection** | pre-tool-guard — prevents out-of-scope modifications |
-| **Context Protection** | context-save — auto-saves at 80/90/95% |
-| **Evidence Gate** | No completion claims without evidence |
-
-**Complexity limits:** Function ≤ 50 lines | Nesting ≤ 3 | Parameters ≤ 5 | Cyclomatic complexity ≤ 10
-
----
-
-## Slash Commands
-
-| Command | Description |
-|---------|-------------|
-| `/vibe.spec "feature"` | Write SPEC + GPT/Gemini parallel research |
-| `/vibe.spec.review` | SPEC quality review |
-| `/vibe.run "feature"` | Implement from SPEC + parallel code review |
-| `/vibe.verify "feature"` | BDD verification against SPEC |
-| `/vibe.review` | 12-agent parallel code review |
-| `/vibe.trace "feature"` | Requirements traceability matrix |
-| `/vibe.reason "problem"` | Systematic reasoning framework |
-| `/vibe.analyze` | Project analysis |
-| `/vibe.event` | Event automation |
-| `/vibe.figma "url"` | Figma design → production code (responsive, multi-URL) |
-| `/vibe.utils` | Utilities (E2E, diagrams, UI, session restore) |
-
----
-
-## Magic Keywords
-
-| Keyword | Effect |
-|---------|--------|
-| `ultrawork` / `ulw` | Parallel processing + phase pipelining + auto-continue + Ralph Loop |
-| `ralph` | Iterate until 100% complete (no scope reduction) |
-| `ralplan` | Iterative planning + persistence |
-| `verify` | Strict verification mode |
-| `quick` | Fast mode, minimal verification |
-
----
-
-## CLI
-
-```bash
-# Project
-vibe init [project]       # Initialize project
-vibe update               # Update settings (re-detect stacks)
-vibe upgrade              # Upgrade to latest version
-vibe setup                # Interactive setup wizard
-vibe status               # Show status
-vibe remove               # Uninstall
-
-# LLM Auth
-vibe gpt auth|key|status|logout
-vibe gemini auth|key|status|logout
-vibe claude key|status|logout
-
-# External Skills
-vibe skills add <owner/repo>   # Install skills from skills.sh
-
-# Figma
-vibe figma breakpoints                # Show/set responsive breakpoints
-vibe figma status|logout              # Token management
-
-# Channels
-vibe telegram setup|chat|status
-vibe slack setup|channel|status
-
-# Diagnostics
-vibe config show          # Unified config view (global + project)
-vibe stats [--week|--quality]  # Usage telemetry summary
-
-# Other
-vibe env import [path]    # Migrate .env → config.json
-vibe help / version
-```
-
-### Auth Priority
-
-| Provider | Priority |
-|----------|----------|
-| **GPT** | Codex CLI → API Key |
-| **Gemini** | gemini-cli auto-detect → API Key |
-
----
-
-## Subpath Exports
-
-```typescript
-import { MemoryStorage, SessionRAGStore } from '@su-record/vibe/memory';
-import { SwarmOrchestrator, PhasePipeline } from '@su-record/vibe/orchestrator';
-import { findSymbol, validateCodeQuality } from '@su-record/vibe/tools';
-import { InMemoryStorage, ComponentRegistry, createSpan } from '@su-record/vibe/tools';
-```
-
-| Subpath | Key Exports |
-|---------|-------------|
-| `@su-record/vibe/memory` | `MemoryStorage`, `IMemoryStorage`, `InMemoryStorage`, `KnowledgeGraph`, `SessionRAGStore` |
-| `@su-record/vibe/orchestrator` | `SwarmOrchestrator`, `PhasePipeline`, `BackgroundManager` |
-| `@su-record/vibe/tools` | `findSymbol`, `validateCodeQuality`, `createSpan`, `ComponentRegistry`, etc. |
-| `@su-record/vibe/tools/memory` | Memory tools |
-| `@su-record/vibe/tools/convention` | Code quality tools |
-| `@su-record/vibe/tools/semantic` | Semantic analysis (symbol search, AST, LSP) |
-| `@su-record/vibe/tools/ui` | UI/UX tools |
-| `@su-record/vibe/tools/interaction` | User interaction tools |
-| `@su-record/vibe/tools/time` | Time utilities |
-
----
-
-## Configuration
-
-### Global: `~/.vibe/config.json`
-
-Auth, channels, and model settings (file permissions `0o600`).
-
-```json
-{
-  "credentials": {
-    "gpt": { "apiKey": "..." },
-    "gemini": { "apiKey": "..." }
-  },
-  "channels": {
-    "telegram": { "botToken": "...", "allowedChatIds": ["..."] },
-    "slack": { "botToken": "...", "appToken": "...", "allowedChannelIds": ["..."] }
-  },
-  "models": { "gpt": "gpt-5.4", "gemini": "gemini-3.1-pro-preview" }
-}
-```
-
-### Project: `.claude/vibe/config.json`
-
-Per-project settings — language, quality, stacks, details, references, installedExternalSkills.
-
----
-
-## Project Structure
-
-```
-your-project/
-├── .claude/
-│   ├── vibe/
-│   │   ├── config.json        # Project config
-│   │   ├── constitution.md    # Project principles
-│   │   ├── specs/             # SPEC documents
-│   │   ├── features/          # Feature tracking
-│   │   ├── todos/             # P1/P2/P3 issues
-│   │   └── reports/           # Review reports
-│   └── skills/                # Local + external skills
-├── CLAUDE.md                  # Project guide (auto-generated)
-├── AGENTS.md                  # Codex CLI guide (auto-generated)
-└── ...
-
-~/.vibe/config.json            # Global config (auth, channels, models)
-~/.vibe/analytics/             # Telemetry (local JSONL)
-│   ├── skill-usage.jsonl
-│   ├── spans.jsonl
-│   └── decisions.jsonl
-~/.claude/
-├── vibe/
-│   ├── rules/                 # Coding rules
-│   ├── skills/                # Global skills
-│   └── ui-ux-data/            # UI/UX CSV datasets (48 files)
-├── commands/                  # Slash commands
-└── agents/                    # Agent definitions (56)
-~/.codex/
-└── plugins/vibe/              # Codex plugin
-    ├── .codex-plugin/plugin.json
-    ├── agents/
-    ├── skills/
-    └── AGENTS.md
-```
-
----
-
-## Architecture
-
-```mermaid
-flowchart TD
-    A["User Request"] --> B["keyword-detector"]
-    B --> C["prompt-dispatcher"]
-    C --> D["SmartRouter"]
-
-    D --> E["LLMCluster"]
-    E --> E1["GPT (Reasoning)"]
-    E --> E2["Gemini (Research)"]
-
-    D --> F["PhasePipeline"]
-    F --> G["SwarmOrchestrator"]
-    G --> H["BackgroundManager"]
-    H --> I["AgentRegistry"]
-
-    D --> J["Parallel Review"]
-    J --> J1["12 Sonnet Review Agents"]
-    J --> J2["Codex Review"]
-    J1 --> K["Triple Cross-Validation → P1/P2/P3"]
-    J2 --> K
-    J --> J3["Boundary Verification"]
-
-    L["Session RAG"] -.-> M["Decision / Constraint / Goal / Evidence"]
-    N["VibeSpan"] -.-> O["spans.jsonl (Local Telemetry)"]
-    P["Quality Gate"] -.-> Q["pre-tool-guard → Block"]
-    P -.-> R["code-check → Verify"]
-```
-
----
-
-## 하네스 시스템 (Harness System)
-
-> **Agent = Model + Harness**
-
-하네스는 AI 에이전트에서 **모델을 제외한 모든 것** — AI가 일하는 환경 전체입니다.
-`vibe init` 한 번으로 가이드(Guides)와 센서(Sensors)가 설치되어, AI가 올바른 방향으로 일하고 스스로 교정하는 구조를 만듭니다.
-
-| 축 | 역할 | 구성 요소 |
-|---|------|----------|
-| **Guides** (피드포워드) | 행동 **전에** 방향 설정 | CLAUDE.md, 규칙, 에이전트 56개, 스킬 45개, 커맨드 |
-| **Sensors** (피드백) | 행동 **후에** 관찰·교정 | 훅 21개 (품질 게이트, 자동 테스트), 이볼루션 엔진 |
-
-### 구성 요소
-
-| 구성 요소 | 분류 | 역할 |
-|-----------|------|------|
-| **CLAUDE.md / 규칙** | Guide | 프로젝트 지침, 코딩 표준 — AI가 읽고 따르는 컨텍스트 |
-| **에이전트 (56개)** | Guide | 탐색·구현·아키텍처·리뷰·QA·UI/UX 전문 페르소나 |
-| **스킬 (45개, 3티어)** | Guide | 도메인별 재사용 워크플로우 모듈 |
-| **커맨드** | Guide | 구조화된 작업 인터페이스 (/vibe.spec, /vibe.run 등) |
-| **훅 (21개)** | Sensor | 라이프사이클 이벤트 인터셉트 — 위험 차단, 품질 검증 |
-| **품질 게이트 (3계층)** | Sensor | 센티넬 가드 → 프리툴 가드 → 코드 체크 |
-| **LLM 비용 추적** | Sensor | llm-costs.jsonl — 프로바이더별 토큰·비용·지연 시간 기록 |
-| **롤백 체크포인트** | Sensor | 자동 커밋마다 `vibe-checkpoint-N` 태그 생성 (최근 5개 유지) |
-| **에스컬레이션** | Sensor | 동일 파일 P1/P2 이슈 3회 반복 → 사용자 개입 요청 |
-| **Session RAG / 메모리** | Both | 세션 간 컨텍스트 지속 + 자동 복원 |
-| **이볼루션 엔진** | Sensor | 훅 실행 패턴 분석 → 규칙/스킬 자기 개선 |
-| **텔레메트리** | Sensor | hook-traces.jsonl, spans.jsonl — 관찰 가능성 |
-
-### 훅 실행 흐름
-
-```
-사용자 액션 (Bash / Edit / Write / Prompt)
-    ↓
-SessionStart ─── session-start.js
-    세션 메모리 복원, 컨텍스트 로드, 하네스 버전 체크
-    ↓
-PreToolUse ──── sentinel-guard.js → pre-tool-guard.js
-    파괴적 명령 차단 (rm -rf, force push, DB drop 등)
-    ↓
-[도구 실행]
-    ↓
-PostToolUse ─── auto-format.js → code-check.js → auto-test.js
-    자동 포맷 → 타입 안전성·복잡도 검증 → 테스트 실행
-    ↓
-UserPromptSubmit ── prompt-dispatcher.js → keyword-detector.js → llm-orchestrate.js
-    커맨드 라우팅 → 매직 키워드 감지 → 외부 LLM 디스패치
-    ↓
-Notification ─── context-save.js
-    컨텍스트 80/90/95%에서 자동 저장
-    ↓
-Stop ──────── codex-review-gate.js → stop-notify.js → auto-commit.js
-    리뷰 게이트 → 세션 종료 알림 → 자동 커밋 + 롤백 체크포인트
-```
-
-### 3계층 품질 게이트
-
-| 계층 | 스크립트 | 검증 내용 |
-|------|---------|----------|
-| **1. 센티넬 가드** | `sentinel-guard.js` | `rm -rf /`, `git reset --hard`, DB drop, fork bomb 등 치명적 명령 원천 차단 |
-| **2. 프리툴 가드** | `pre-tool-guard.js` | 위험 패턴 경고 — force push, .env 수정, 시스템 디렉토리 쓰기 |
-| **3. 코드 체크** | `code-check.js` | `any` 타입 차단, `@ts-ignore` 차단, 함수 ≤50줄, 중첩 ≤3, 파라미터 ≤5, 순환복잡도 ≤10 |
-
-### 스킬 티어 시스템
-
-컨텍스트 과부하(Curse of Instructions)를 방지하기 위해 스킬을 3단계로 분류합니다.
-
-| 티어 | 로딩 방식 | 목적 | 예시 |
-|------|----------|------|------|
-| **Core** | 항상 활성 | 버그·실수 방지 안전망 | techdebt, arch-guard, exec-plan |
-| **Standard** | 프로젝트 스택에 따라 선택 | 워크플로우 지원 | parallel-research, handoff, design-teach |
-| **Optional** | 명시적 `/skill`로만 호출 | 래퍼/참조용 | commit-push-pr, git-worktree, context7 |
-
-### 이볼루션 엔진 (자기 개선)
-
-```
-훅 실행 추적 (spans.jsonl)
-    ↓
-패턴 분석 — 반복 차단 패턴 클러스터링 (7일 히스토리)
-    ↓
-인사이트 생성 — 최적화/경고/갭 분류 + 신뢰도 점수
-    ↓
-규칙·스킬 자동 생성 (suggest 또는 auto 모드)
-    ↓
-서킷 브레이커 — 회귀 발생 시 롤백
-```
-
-### LLM 비용 추적
-
-외부 LLM(GPT, Gemini) 호출마다 토큰, 비용, 지연 시간을 `~/.vibe/llm-costs.jsonl`에 기록합니다.
-캐시 히트 시 비용 0으로 기록. 프로바이더별 모델 단가 자동 적용.
-
-```jsonl
-{"ts":"...","provider":"gpt","model":"gpt-5.4","inputTokens":150,"outputTokens":420,"cost":0.0069,"durationMs":2340,"cached":false}
-```
-
-`vibe stats --quality`로 누적 비용 확인 가능.
-
-### 롤백 체크포인트
-
-에이전트 자동 커밋마다 `vibe-checkpoint-N` git 태그를 생성합니다.
-문제 발생 시 한 줄로 롤백:
-
-```bash
-git reset --hard vibe-checkpoint-3
-```
-
-최근 5개만 유지, 오래된 체크포인트는 자동 정리.
-
-### 에스컬레이션 (Human-in-the-loop)
-
-동일 파일에서 P1/P2 이슈가 3회 반복되면 자동 수정을 멈추고 사용자에게 개입을 요청합니다.
-
-```
-🚨 [ESCALATION] auth.ts: 동일 이슈 3회 반복
-   → 사용자 개입 필요 — 자동 수정이 수렴하지 않고 있습니다.
-```
-
-AI가 같은 실수를 반복하며 맴도는 것을 방지하는 센서입니다.
-
-### 설치 흐름
-
-```bash
-npm install -g @su-record/vibe   # postinstall → 글로벌 에셋 배포
-vibe init                         # 프로젝트 하네스 설치
-```
-
-**postinstall** (글로벌):
-- `~/.claude/agents/` — 56개 에이전트 정의
-- `~/.claude/skills/` — 글로벌 스킬
-- `~/.claude/commands/` — 슬래시 커맨드
-
-**vibe init** (프로젝트):
-- 24개 프레임워크 자동 감지
-- `.claude/settings.local.json`에 훅 등록
-- 스택별 스킬·규칙 설치
-- `CLAUDE.md` 생성 (프레임워크별 코딩 규칙)
-
----
-
-## Requirements
-
-- **Node.js** >= 18.0.0
-- **Claude Code** (required)
-- GPT, Gemini (optional — for multi-LLM features)
-
-## License
-
-MIT License - Copyright (c) 2025 Su
+# VIBE
+
+**AI writes code. Vibe makes sure it's good.**
+
+[![npm](https://img.shields.io/npm/v/@su-record/vibe)](https://www.npmjs.com/package/@su-record/vibe)
+[![npm downloads](https://img.shields.io/npm/dt/@su-record/vibe.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@su-record/vibe)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+
+> One install. 56 agents, 45 skills, multi-LLM orchestration, and automated quality gates — added to your existing AI coding workflow.
+
+```bash
+npm install -g @su-record/vibe
+vibe init
+```
+
+Works with **Claude Code**, **Codex**, **Cursor**, and **Gemini CLI**.
+
+---
+
+## The Problem
+
+AI coding tools generate working code, but:
+
+- Types are `any`, reviews are skipped, tests are forgotten
+- You catch issues manually — after the damage is done
+- Context vanishes between sessions
+- Complex tasks spiral without structure
+
+**Vibe is a harness.** It wraps around your AI coding tool and enforces quality automatically — before, during, and after code generation.
+
+---
+
+## How It Works
+
+```
+Agent = Model + Harness
+```
+
+| | Role | What's Inside |
+|---|------|--------------|
+| **Guides** (feedforward) | Set direction *before* action | CLAUDE.md, 56 agents, 45 skills, coding rules |
+| **Sensors** (feedback) | Observe and correct *after* action | 21 hooks, quality gates, evolution engine |
+
+### Workflow
+
+```mermaid
+flowchart LR
+    A["/vibe.spec"] --> B["/vibe.spec.review"]
+    B --> C["/vibe.run"]
+    C --> D["Auto Review"]
+    D --> E["Done"]
+```
+
+1. **Define** — `/vibe.spec` writes requirements with GPT + Gemini parallel research
+2. **Review** — `/vibe.spec.review` runs triple cross-validation (Claude + GPT + Gemini)
+3. **Implement** — `/vibe.run` builds from SPEC with parallel code review
+4. **Verify** — 12 agents review in parallel, P1/P2 issues auto-fixed
+
+Add `ultrawork` to run the entire pipeline hands-free:
+
+```bash
+/vibe.run "add user authentication" ultrawork
+```
+
+---
+
+## Key Features
+
+**Quality Gates** — Blocks `any` types, `@ts-ignore`, functions > 50 lines. Three-layer defense: sentinel guard → pre-tool guard → code check.
+
+**56 Specialized Agents** — Exploration, implementation, architecture, 12 parallel reviewers, 8 UI/UX agents, QA coordination. Each agent is purpose-built, not a generic wrapper.
+
+**Multi-LLM Orchestration** — Claude for orchestration, GPT for reasoning, Gemini for research. Auto-routes based on available models. Works Claude-only by default.
+
+**Session RAG** — SQLite + FTS5 hybrid search persists decisions, constraints, and goals across sessions. Context is restored automatically on session start.
+
+**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.
+
+**Self-Improvement** — Evolution engine analyzes hook execution patterns, detects skill gaps, and generates new rules. Circuit breaker rolls back on regression.
+
+---
+
+## What's Included
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| **Agents** | 56 | Explorer, Implementer, Architect (3 depth levels each), 12 review specialists, 8 UI/UX, QA coordinator |
+| **Skills** | 45 | 3-tier system (core/standard/optional) to prevent context overload |
+| **Hooks** | 21 | Session restore, destructive command blocking, auto-format, quality check, context auto-save |
+| **Frameworks** | 24 | TypeScript (12), Python (2), Java/Kotlin (2), Rails, Go, Rust, Swift, Flutter, Unity, Godot |
+| **Slash Commands** | 11 | `/vibe.spec`, `/vibe.run`, `/vibe.review`, `/vibe.trace`, `/vibe.figma`, and more |
+
+---
+
+## Multi-CLI Support
+
+| CLI | Agents | Skills | Instructions |
+|-----|--------|--------|-------------|
+| Claude Code | `~/.claude/agents/` | `~/.claude/skills/` | `CLAUDE.md` |
+| Codex | `~/.codex/plugins/vibe/` | Plugin built-in | `AGENTS.md` |
+| Cursor | `~/.cursor/agents/` | `~/.cursor/skills/` | `.cursorrules` |
+| Gemini CLI | `~/.gemini/agents/` | `~/.gemini/skills/` | `GEMINI.md` |
+
+---
+
+## Multi-LLM Routing
+
+| Provider | Role | Required |
+|----------|------|----------|
+| **Claude** | Orchestration, SPEC, review | Yes (via Claude Code) |
+| **GPT** | Reasoning, architecture, edge cases | Optional (Codex CLI or API key) |
+| **Gemini** | Research, cross-validation, UI/UX | Optional (gemini-cli or API key) |
+
+Auto-switches based on model availability. Claude-only is the default — GPT and Gemini enhance but aren't required.
+
+Codex CLI or gemini-cli are auto-detected if installed. To set API keys manually:
+
+```bash
+vibe gpt key <your-api-key>
+vibe gemini key <your-api-key>
+```
+
+---
+
+## Figma → Code
+
+Design-to-code pipeline with tree-based structural mapping (not screenshot guessing).
+
+```bash
+/vibe.figma              # All URLs at once (storyboard + mobile + desktop)
+/vibe.figma --new        # New feature mode (create standalone styles)
+/vibe.figma --refine     # Refine mode (compare existing code with Figma → fix)
+```
+
+Pass storyboard, mobile, and desktop Figma URLs together. Extracts tree + node images via Figma REST API → remaps across breakpoints → generates stack-aware code (React/Vue/Svelte/SCSS/Tailwind) → visual verification loop.
+
+---
+
+## CLI Reference
+
+```bash
+vibe init                      # Initialize project (detect stack, install harness)
+vibe update                    # Re-detect stacks, refresh config
+vibe upgrade                   # Upgrade to latest version
+vibe status                    # Show current status
+vibe config show               # Unified config view
+vibe stats [--week|--quality]  # Usage telemetry
+
+vibe gpt key|status            # GPT API key setup
+vibe gemini key|status         # Gemini API key setup
+vibe figma breakpoints         # Responsive breakpoints
+vibe skills add <owner/repo>   # Install skills from skills.sh
+```
+
+---
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `~/.vibe/config.json` | Global — credentials, channels, models (0o600) |
+| `.claude/vibe/config.json` | Project — stacks, capabilities, quality settings |
+
+---
+
+## Magic Keywords
+
+| Keyword | Effect |
+|---------|--------|
+| `ultrawork` | Full automation — parallel agents + auto-continue + quality loop |
+| `ralph` | Iterate until 100% complete (no scope reduction) |
+| `quick` | Fast mode, minimal verification |
+
+---
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Claude Code (required)
+- GPT, Gemini (optional — for multi-LLM features)
+
+## Documentation
+
+- [README (Korean)](README.ko.md)
+- [Release Notes](RELEASE_NOTES.md)
+
+## License
+
+MIT — Copyright (c) 2025 Su