@su-record/vibe 2.9.15 → 2.9.16

package/CLAUDE.md

@@ -1,190 +1,101 @@
-# VIBE
-
-## Project Nature
-
-> **This is the source code for `@su-record/vibe` npm package.**
-> Modify files in THIS repository only — never the installed copy (`~/.claude/`, `~/.vibe/`).
-
-## Philosophy
-
-> **vibe = Easy vibe coding + Minimum quality guaranteed**
-
-- **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 (don't delegate)
-
-## Constraints (Hard Rules)
-
-### Code Behavior
-
-- **Modify only requested scope** — Don't touch unrelated code
-- **Preserve existing style** — Follow project conventions
-- **Edit existing files, never create new ones** — Fix problems at source
-- **Respect user interrupts** — Ctrl+C/Escape = previous task CANCELLED
-
-### Complexity Limits
-
-| Metric | Limit |
-|--------|-------|
-| Function length | ≤50 lines |
-| Nesting depth | ≤3 levels |
-| Parameters | ≤5 |
-| Cyclomatic complexity | ≤10 |
-
-### TypeScript (Enforced by Quality Gate hooks)
-
-- No `any` — use `unknown` + type guards
-- No `as any` — define proper interfaces
-- No `@ts-ignore` — fix type issues at root
-- Explicit return types on all functions
-
-### Convergence Principle (Quality-First, No Round Cap)
-
-- **Loop until quality = 100** — no hard round cap on review/auto-fix loops
-- **P1 = 0 AND no new findings** → done (the natural termination signal)
-- **Narrowing scope per round (noise reduction)** — Round 1: full scope, Round 2: P1+P2, Round 3+: P1 only — keeps looping until P1=0
-- **Stuck detection → ask the user** — Same findings (or same score) as previous round means auto-fixer hit a wall. Prompt the user to fill in values, explicitly approve sub-100, or abort. Never silently proceed with sub-100 quality.
-- **ultrawork exception** — In `ultrawork` mode, skip the user prompt and record remaining gaps as TODO to keep the loop non-interactive.
-- **Changed files only** — Never scan the entire project
-
-### Forbidden Patterns
-
-- No `console.log` in commits
-- No hardcoded strings/numbers (use constants)
-- No commented-out code
-- No incomplete code without TODO
-
-## Architecture (What's NOT Obvious)
-
-### Module System
-
-- ESM only (`"type": "module"`) — imports need `.js` extension
-- TypeScript strict mode → `dist/` via `tsc`
-- Build before test: `npm run build && npx vitest run`
-
-### Config Locations (Don't Confuse)
-
-| Path | Purpose |
-|------|---------|
-| `~/.vibe/config.json` | Global credentials, channels, models (0o600) |
-| `.claude/vibe/config.json` | Project stacks, capabilities, details |
-| `.claude/settings.local.json` | Project hooks (auto-generated, don't commit) |
-
-### Installation Flow
-
-- `postinstall` → global assets (`~/.claude/agents/`, `~/.claude/skills/`, `~/.claude/commands/`)
-- `vibe init` → project setup (detect stacks → config → constitution → rules → hooks → local skills + languages)
-- `vibe update` → re-detect stacks, refresh project config (preserves user capabilities)
-
-### Key Directories (Where to Find Things)
-
-| What | Where |
-|------|-------|
-| CLI commands | `src/cli/commands/` |
-| Postinstall modules | `src/cli/postinstall/` |
-| Stack detection | `src/cli/detect.ts` |
-| Auth (all LLMs) | `src/cli/auth.ts` |
-| Setup helpers | `src/cli/setup.ts`, `src/cli/setup/` |
-| Hooks scripts | `hooks/scripts/` |
-| Agent definitions | `agents/` |
-| Team definitions | `agents/teams/` |
-| Skill definitions | `skills/` |
-| Language rules | `languages/` |
-| SPEC/rule templates | `vibe/rules/`, `vibe/templates/` |
-| Infra (daemon, memory, policy) | `src/infra/` |
-| Telemetry (local JSONL) | `src/infra/lib/telemetry/` |
-| Test helpers (shared) | `src/test-helpers/` |
-| Skill catalog generator | `scripts/gen-skill-docs.ts` |
-
-### Gotchas
-
-- `better-sqlite3` WAL mode — DB module uses synchronous API
-- `crypto.timingSafeEqual` requires same-length buffers — check length first
-- `GLOBAL_SKILLS_CORE`, `GLOBAL_SKILLS_STANDARD`, `GLOBAL_SKILLS_OPTIONAL`, `STACK_TO_SKILLS`, `CAPABILITY_SKILLS` in `src/cli/postinstall/constants.ts` — single source of truth for stack→asset mapping
-- Hook dispatch chain: `prompt-dispatcher.js` → `keyword-detector.js` → `llm-orchestrate.js` (order matters)
-- Pre-existing test failures in `prdParser.test.ts` (7) and `traceabilityMatrix.test.ts` (1) — unrelated to current work
-
-## Workflow
-
-```text
-/vibe.spec  →  vibe.interview (skill)  →  vibe.plan (skill)  →  vibe.spec (skill) → vibe.spec.review (skill)  →  ┬→  /vibe.run → /vibe.verify → /vibe.trace → Done
-                                                                                                                   │    (Logic Track)
-                                                                                                                   └→  /vibe.figma → FE UI 코드
-                                                                                                                        (UI Track — type ∈ {website,webapp,mobile}만)
-```
-
-**단일 진입점**: `/vibe.spec`은 "무엇을 개발할지" 질문으로 시작해서 전체 흐름을 오케스트레이션한다. 사용자는 `/vibe.*` 커맨드 이름을 외울 필요 없음. **Smart Resume**: 기존 interview/plan/spec 파일 존재 여부로 어느 단계부터 시작할지 자동 판단.
-
-**커맨드 `/vibe.spec` vs 스킬 `vibe.spec`**: 커맨드는 **전체 워크플로 오케스트레이터**, 스킬은 그 안의 **SPEC 작성 단계**. `/vibe.figma` 커맨드와 `vibe.figma` 스킬 관계와 동일한 패턴.
-
-**스킬 기반 workflow**:
-- `vibe.interview` — 반복 인터뷰로 요구사항 수집 (사용자 "그만"까지). 타입별 체크리스트(`skills/vibe.interview/checklists/{type}.md`).
-- `vibe.plan` — interview → 마크다운 기획서 정제 (`.claude/vibe/plans/{feature}.md`).
-- `vibe.spec` — 기획서 → PTCF SPEC + Feature(BDD) 파일.
-- `vibe.spec.review` — GPT/Gemini Race Review + 품질 게이트.
-- 모두 자연어 트리거(만들자/개발하자/신규/아이디어)로도 자동 활성화.
-
-**UI/Logic 분기**: 기획서의 `type` 필드로 자동 판단. UI 포함 프로젝트(website/webapp/mobile)는 Logic + UI 트랙 병렬, 비-UI(api/library)는 Logic만.
-
-| Task Size | Approach |
-|-----------|----------|
-| 1-2 files | Plan Mode |
-| 3+ files | `/vibe.spec` (전체 워크플로 오케스트레이션) |
-
-## Magic Keywords
-
-| Keyword | Effect |
-|---------|--------|
-| `ultrawork` / `ulw` | Parallel agents + 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 |
-
-## Skill Tier System
-
-Skills are classified into 3 tiers to prevent context overload (Curse of Instructions):
-
-| Tier | Loading | Purpose | Count |
-|------|---------|---------|-------|
-| **core** | Always active | Bug/mistake prevention + workflow entry (interview/plan) | ~11 |
-| **standard** | Project setup selects | Workflow support by stack/capability | ~21 |
-| **optional** | Explicit `/skill` only | Reference/wrapper — not auto-loaded | ~4 |
-
-**Constants**: `GLOBAL_SKILLS_CORE` + `GLOBAL_SKILLS_STANDARD` in `src/cli/postinstall/constants.ts`
-
-## Proactive Skill Suggestions
-
-When the user's context matches a pattern below, suggest the relevant skill **once** per session. If the user says "stop suggesting", disable for the rest of the session.
-
-| User Context | Suggested Skill | Tier | Signal |
-|-------------|-----------------|------|--------|
-| New project/feature idea, no plan yet | `/vibe.spec` | command | "만들자", "개발하자", "신규", "아이디어", "무엇을 만들", "let's build", "new feature" |
-| Interview 완료, 기획서 필요 | `/vibe.spec` | command | `.claude/vibe/interviews/*.md` 존재, 기획서 없음 (Smart Resume으로 Phase 2부터) |
-| 전체 워크플로 진입 | `/vibe.spec` | command | "어디서부터 시작", "전체 워크플로", 커맨드 이름 모를 때 |
-| 기획서 → 코드 명세 | `/vibe.spec` | command | `.claude/vibe/plans/*.md` 존재, SPEC 없음 (Smart Resume으로 Phase 3부터) |
-| SPEC exists, ready to implement | `/vibe.run` | core | SPEC file present, no implementation started |
-| Implementation done, verifying | `/vibe.trace` | core | Code changes match SPEC phases |
-| Technical debt accumulating | `/techdebt` | core | Multiple `any` types, console.log, unused imports |
-| Multi-file refactoring planned | `/exec-plan` | core | 3+ files to change, complex dependencies |
-| Complex feature, unknown tech | `/parallel-research` | standard | "how should we", "which library", architecture questions |
-| Debugging errors repeatedly | `/vibe.trace` | core | 3+ error cycles without resolution |
-| Session ending, work incomplete | `/handoff` | standard | 70%+ context, incomplete tasks |
-| Building new UI/UX | `/design-teach` | standard | "new page", "landing", "dashboard", Figma URL |
-| UI code review | `/design-audit` | standard | After implementing UI components |
-| New project setup / CLAUDE.md | `/claude-md-guide` | standard | "new project", "write CLAUDE.md" |
-| Before shipping UI | `/design-polish` | standard | "ready to deploy", "final check" |
-| External API/SDK code needed | `/chub-usage` | optional | "Stripe 연동", "OpenAI API", SDK/API code request |
-
-## Context Management
-
-- **Exploration/Search**: Haiku | **Implementation**: Sonnet | **Architecture**: Opus
-- At 70%+ context: `save_memory` → `/new` → `/vibe.utils --continue`
-
-## Git Commit Rules
-
-**Must include:** `.claude/vibe/plans/`, `.claude/vibe/specs/`, `.claude/vibe/features/`, `.claude/vibe/todos/`, `.claude/vibe/config.json`, `CLAUDE.md`
-
-**Exclude:** `~/.claude/vibe/rules/`, `~/.claude/commands/`, `~/.claude/agents/`, `~/.claude/skills/`, `.claude/settings.local.json`
-
-<!-- VIBE:END -->
+# VIBE
+
+> Source code for `@su-record/vibe` npm package. Modify files in THIS repository only — never the installed copies (`~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.coco/`, `~/.vibe/`).
+>
+> **File-to-CLI mapping:**
+> - `CLAUDE.md` — **Claude Code** (100% supported) · **content SSOT**
+> - `AGENTS.md` — **coco** (100% supported, primary) · Codex CLI (best-effort)
+> - `GEMINI.md` — Gemini CLI (best-effort)
+>
+> `AGENTS.md` and `GEMINI.md` are regenerated from this file via `/vibe.docs agent`. Edit here first.
+
+## Hard Rules
+
+### Behavior
+- **Modify only requested scope** — Every changed line traces to the user's request
+- **Edit existing files over creating new** — Fix at source
+- **Preserve existing style** — Match conventions even if you'd do it differently
+- **Respect Ctrl+C / Escape** — Previous task CANCELLED
+- **State assumptions, ask when uncertain** — Don't pick silently when ambiguity exists; push back if a simpler approach exists
+
+### Goal-Driven Execution
+Transform imperative tasks into verifiable goals **before** coding:
+
+| Instead of | Transform to |
+|---|---|
+| "Add validation" | "Tests for invalid inputs pass" |
+| "Fix the bug" | "A test reproducing it passes" |
+| "Refactor X" | "Tests pass before and after" |
+
+Weak criteria ("make it work") require constant clarification. Strong criteria let the loop run independently.
+
+### TypeScript (enforced by Quality Gate hooks)
+- No `any` / `as any` / `@ts-ignore` — use `unknown` + type guards; fix at root
+- Explicit return types on all functions
+
+### Complexity Limits
+Function ≤50 lines · Nesting ≤3 · Params ≤5 · Cyclomatic ≤10
+
+### Forbidden Patterns
+No `console.log` in commits · No hardcoded strings/numbers · No commented-out code · No incomplete code without TODO
+
+### Convergence (review / auto-fix loops)
+- **Loop until P1 = 0 AND no new findings** — no round cap
+- **Narrowing scope**: Round 1 full → Round 2 P1+P2 → Round 3+ P1 only
+- **Stuck detection** (same findings/score 2 rounds in a row) → ask user (fill values / approve sub-100 / abort). Never silently proceed sub-100
+- **`ultrawork` exception** — skip user prompt; record gaps as TODO to stay non-interactive
+- **Changed files only** — never full-project scan
+
+## Architecture (Non-Obvious)
+
+### Module System
+- ESM only (`"type": "module"`) — imports need `.js` extension
+- Build before test: `npm run build && npx vitest run`
+
+### Config Locations
+| Path | Purpose |
+|---|---|
+| `~/.vibe/config.json` | Global credentials, models (0o600) |
+| `.claude/vibe/config.json` | Project stacks, capabilities |
+| `.claude/settings.local.json` | Project hooks (auto-generated, don't commit) |
+
+### Gotchas
+- `better-sqlite3` WAL mode — synchronous API
+- `crypto.timingSafeEqual` requires same-length buffers — check length first
+- **Stack → asset SSOT**: `GLOBAL_SKILLS_*`, `STACK_TO_SKILLS`, `CAPABILITY_SKILLS` in `src/cli/postinstall/constants.ts`
+- **Hook dispatch order**: `prompt-dispatcher.js` → `keyword-detector.js` → `llm-orchestrate.js`
+
+## Workflow
+
+`/vibe.spec` is the single entry point — orchestrates interview → plan → spec → review → `/vibe.run` → `/vibe.verify` → `/vibe.trace`. For UI types (website/webapp/mobile), `/vibe.figma` branches in parallel. Smart Resume detects existing `.claude/vibe/{interviews,plans,specs}/*.md` to skip phases.
+
+| Task Size | Approach |
+|---|---|
+| 1–2 files | Plan Mode |
+| 3+ files | `/vibe.spec` |
+
+## Magic Keywords
+
+| Keyword | Effect |
+|---|---|
+| `ultrawork` / `ulw` | Parallel agents + auto-continue + Ralph Loop |
+| `ralph` | Iterate to 100% (no scope reduction) |
+| `ralplan` | Iterative planning + persistence |
+| `verify` | Strict verification mode |
+| `quick` | Fast mode, minimal verification |
+
+## Skill Tiers
+
+3 tiers prevent context overload: **core** (always active) / **standard** (project-setup selected) / **optional** (explicit `/skill` only). SSOT: `GLOBAL_SKILLS_CORE` + `GLOBAL_SKILLS_STANDARD` in `src/cli/postinstall/constants.ts`. Proactive triggers live in each skill's frontmatter.
+
+## Context Management
+
+- Exploration → Haiku · Implementation → Sonnet · Architecture → Opus
+- At 70%+ context: `save_memory` → `/new` → `/vibe.utils --continue`
+
+## Git
+
+**Include**: `.claude/vibe/{plans,specs,features,todos}/`, `.claude/vibe/config.json`, `CLAUDE.md`
+**Exclude**: `~/.claude/{rules,commands,agents,skills}/`, `.claude/settings.local.json`
+
+<!-- VIBE:END -->

package/README.ko.md

@@ -1,171 +1,171 @@
-# VIBE
-
-**바이브 코딩은 쉽게. 최소 품질은 보장.**
-
-[![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)
-
-Vibe는 AI 코딩 도구를 위한 품질 하네스입니다. Claude Code, Codex, Cursor, Gemini CLI를 감싸고, 타입 안전성, 코드 품질, 보안을 자동으로 강제합니다. 빠르게 바이브 코딩하되, 엉망인 코드가 나가지 않게.
-
-```bash
-npm install -g @su-record/vibe
-vibe init
-```
-
----
-
-## 워크플로우
-
-진입점 하나. 나머지는 자동.
-
-```
-/vibe.spec "커피 브랜드 랜딩 페이지"
-     |
-     v
-  인터뷰    ─── "타깃은 누구?" "어떤 섹션?" "다크 모드?" ───
-     |                   (사용자가 "그만"할 때까지 반복)
-     v
-  기획서    ─── 구조화된 마크다운 기획서 (.claude/vibe/plans/)
-     |
-     v
-  SPEC     ─── PTCF 명세 + BDD 피처, GPT+Gemini 병렬 리서치
-     |
-     v
-  리뷰     ─── Race Review (GPT vs Gemini), 품질 게이트 (100점, 수렴까지 루프)
-     |
-     +──────────────────────────────┐
-     v                              v
-  /vibe.run (로직)             /vibe.figma (UI)
-  SPEC 기반 구현               Figma 디자인 ↔ 코드
-  12개 에이전트 리뷰            읽기 또는 쓰기
-     |                              |
-     v                              v
-  /vibe.verify ──── /vibe.trace ──── 완료
-```
-
-**Smart Resume** — 아무 단계에서나 멈추고, 세션을 닫고, 나중에 돌아오세요. `/vibe.spec`이 중단된 위치를 자동 감지하고 이어서 진행합니다. feature 이름을 외울 필요 없음.
-
-**ultrawork** — 어느 명령이든 `ultrawork`를 붙이면 모든 확인 게이트를 건너뛰고 전체 파이프라인을 자동 실행합니다.
-
----
-
-## 빠른 시작
-
-```bash
-# 설치
-npm install -g @su-record/vibe
-
-# 프로젝트 초기화 (스택 자동 감지)
-cd your-project
-vibe init
-
-# AI 코딩 도구 시작
-claude
-
-# 워크플로우 실행
-/vibe.spec "사용자 인증 추가"
-```
-
----
-
-## Figma ↔ 코드
-
-양방향. Figma에서 디자인을 읽거나, 기획서에서 Figma에 디자인을 쓰거나.
-
-```bash
-# READ — 기존 프로젝트에 UI 추가 (프로젝트 컨벤션 준수)
-/vibe.figma <figma-url> <figma-url>
-
-# READ — 신규 독립 페이지 (독립 스타일)
-/vibe.figma --new <figma-url>
-
-# WRITE — 기획서에서 Figma 디자인 생성
-/vibe.figma plan.md --create                 # Full (와이어 + 비주얼 디자인)
-/vibe.figma plan.md --create-storyboard      # 와이어만
-/vibe.figma plan.md --create-design          # 비주얼 디자인만
-```
-
-**READ 동작**: Figma REST API로 노드 트리 + 30개 CSS 속성 추출. Auto Layout → Flexbox 1:1 기계적 매핑. 스크린샷은 검증용 — 트리가 원천.
-
-**WRITE 동작**: 기획서의 Look & Feel, 레이아웃, 반응형 전략 섹션을 파싱하여 와이어프레임을 먼저 그리고 (구조 검토), 그 위에 디자인 시스템 컴포넌트로 비주얼 적용. 멱등성 보장 — 기획서 수정 후 재실행하면 변경된 섹션만 갱신.
-
----
-
-## 품질 게이트
-
-모든 도구 호출마다 3계층 방어:
-
-| 계층 | 차단 대상 |
-|------|----------|
-| Pre-commit 훅 | `any` 타입, `@ts-ignore`, `console.log`, 50줄 초과 함수 |
-| 리뷰 에이전트 | 12개 전문 리뷰어 병렬 실행 (보안, 성능, 접근성, 복잡도, ...) |
-| 수렴 루프 | 리뷰 findings P1=0까지 루프. 라운드 캡 없음. Stuck이면 사용자에게 질문, 절대 조용히 넘어가지 않음. |
-
----
-
-## 주요 기능
-
-**40+ 에이전트** — 탐색, 구현, 아키텍처, 병렬 코드 리뷰, UI/UX 분석, 보안 감사, Figma 분석/빌드.
-
-**44개 스킬** — 한 번에 다 로드되지 않음. 3-tier 시스템으로 컨텍스트 과부하 방지:
-
-| 티어 | 로드 시점 | 용도 | 예시 |
-|------|----------|------|------|
-| **Core** | 항상 활성 | 버그 방지, 워크플로 진입 | 품질 게이트, 인터뷰, 기획 |
-| **Standard** | `vibe init`이 스택별 선택 | 스택/역할 지원 | figma, design-audit, techdebt |
-| **Optional** | 명시적 `/skill` 호출만 | 레퍼런스, 래퍼 | chub-usage, context7 |
-
-**멀티 LLM** — Claude가 오케스트레이션, GPT가 추론, Gemini가 리서치. 가용 모델에 따라 자동 라우팅. 기본값은 Claude 단독. Coco 환경(GPT 주관)에서는 Claude CLI가 보조로 전환되어 cross-validation 수행 — `~/.coco/` 감지로 역할 자동 역전.
-
-**스택 감지** — 24개 프레임워크 자동 감지 (Next.js, Django, Rails, Go, Rust, Flutter 등) 후 프레임워크별 규칙과 스킬 적용.
-
-**세션 메모리** — 결정, 제약, 목표가 SQLite + FTS5 검색으로 세션 간 유지.
-
-**Smart Resume** — `.last-feature` 포인터가 마지막 작업을 추적. 인자 없이 `/vibe.spec`을 호출하면 중단된 위치를 보여주거나 진행 중 feature 목록을 제시.
-
----
-
-## 지원 도구
-
-| CLI | 상태 |
-|-----|------|
-| [Claude Code](https://claude.ai/code) | 전체 지원 |
-| Coco (`~/.coco/`) | 전체 지원 (자동 감지) |
-| [Codex](https://github.com/openai/codex) | 플러그인 |
-| [Cursor](https://cursor.sh) | 에이전트 + 룰 |
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | 에이전트 + 스킬 |
-
----
-
-## 명령어
-
-| 명령어 | 용도 |
-|--------|------|
-| `/vibe.spec` | 단일 진입점 — 인터뷰, 기획, SPEC, 리뷰, 그리고 구현까지 |
-| `/vibe.run` | SPEC 기반 구현 |
-| `/vibe.figma` | Figma ↔ 코드 (읽기 또는 쓰기, 3가지 모드) |
-| `/vibe.verify` | 구현이 SPEC에 맞는지 검증 |
-| `/vibe.trace` | 요구사항 추적 매트릭스 |
-
----
-
-## 문서
-
-상세 가이드, 스킬 레퍼런스, 설정 방법은 [Wiki](https://github.com/su-record/vibe/wiki)를 참고하세요.
-
-- [README (English)](README.md)
-- [릴리스 노트](RELEASE_NOTES.md)
-
----
-
-## 요구사항
-
-- Node.js >= 18.0.0
-- Claude Code (필수)
-- GPT, Gemini (선택)
-
-## 라이선스
-
-MIT — Copyright (c) 2025 Su
+# VIBE
+
+**바이브 코딩은 쉽게. 최소 품질은 보장.**
+
+[![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)
+
+Vibe는 AI 코딩 도구를 위한 품질 하네스입니다. Claude Code, Codex, Cursor, Gemini CLI를 감싸고, 타입 안전성, 코드 품질, 보안을 자동으로 강제합니다. 빠르게 바이브 코딩하되, 엉망인 코드가 나가지 않게.
+
+```bash
+npm install -g @su-record/vibe
+vibe init
+```
+
+---
+
+## 워크플로우
+
+진입점 하나. 나머지는 자동.
+
+```
+/vibe.spec "커피 브랜드 랜딩 페이지"
+     |
+     v
+  인터뷰    ─── "타깃은 누구?" "어떤 섹션?" "다크 모드?" ───
+     |                   (사용자가 "그만"할 때까지 반복)
+     v
+  기획서    ─── 구조화된 마크다운 기획서 (.claude/vibe/plans/)
+     |
+     v
+  SPEC     ─── PTCF 명세 + BDD 피처, GPT+Gemini 병렬 리서치
+     |
+     v
+  리뷰     ─── Race Review (GPT vs Gemini), 품질 게이트 (100점, 수렴까지 루프)
+     |
+     +──────────────────────────────┐
+     v                              v
+  /vibe.run (로직)             /vibe.figma (UI)
+  SPEC 기반 구현               Figma 디자인 ↔ 코드
+  12개 에이전트 리뷰            읽기 또는 쓰기
+     |                              |
+     v                              v
+  /vibe.verify ──── /vibe.trace ──── 완료
+```
+
+**Smart Resume** — 아무 단계에서나 멈추고, 세션을 닫고, 나중에 돌아오세요. `/vibe.spec`이 중단된 위치를 자동 감지하고 이어서 진행합니다. feature 이름을 외울 필요 없음.
+
+**ultrawork** — 어느 명령이든 `ultrawork`를 붙이면 모든 확인 게이트를 건너뛰고 전체 파이프라인을 자동 실행합니다.
+
+---
+
+## 빠른 시작
+
+```bash
+# 설치
+npm install -g @su-record/vibe
+
+# 프로젝트 초기화 (스택 자동 감지)
+cd your-project
+vibe init
+
+# AI 코딩 도구 시작
+claude
+
+# 워크플로우 실행
+/vibe.spec "사용자 인증 추가"
+```
+
+---
+
+## Figma ↔ 코드
+
+양방향. Figma에서 디자인을 읽거나, 기획서에서 Figma에 디자인을 쓰거나.
+
+```bash
+# READ — 기존 프로젝트에 UI 추가 (프로젝트 컨벤션 준수)
+/vibe.figma <figma-url> <figma-url>
+
+# READ — 신규 독립 페이지 (독립 스타일)
+/vibe.figma --new <figma-url>
+
+# WRITE — 기획서에서 Figma 디자인 생성
+/vibe.figma plan.md --create                 # Full (와이어 + 비주얼 디자인)
+/vibe.figma plan.md --create-storyboard      # 와이어만
+/vibe.figma plan.md --create-design          # 비주얼 디자인만
+```
+
+**READ 동작**: Figma REST API로 노드 트리 + 30개 CSS 속성 추출. Auto Layout → Flexbox 1:1 기계적 매핑. 스크린샷은 검증용 — 트리가 원천.
+
+**WRITE 동작**: 기획서의 Look & Feel, 레이아웃, 반응형 전략 섹션을 파싱하여 와이어프레임을 먼저 그리고 (구조 검토), 그 위에 디자인 시스템 컴포넌트로 비주얼 적용. 멱등성 보장 — 기획서 수정 후 재실행하면 변경된 섹션만 갱신.
+
+---
+
+## 품질 게이트
+
+모든 도구 호출마다 3계층 방어:
+
+| 계층 | 차단 대상 |
+|------|----------|
+| Pre-commit 훅 | `any` 타입, `@ts-ignore`, `console.log`, 50줄 초과 함수 |
+| 리뷰 에이전트 | 12개 전문 리뷰어 병렬 실행 (보안, 성능, 접근성, 복잡도, ...) |
+| 수렴 루프 | 리뷰 findings P1=0까지 루프. 라운드 캡 없음. Stuck이면 사용자에게 질문, 절대 조용히 넘어가지 않음. |
+
+---
+
+## 주요 기능
+
+**40+ 에이전트** — 탐색, 구현, 아키텍처, 병렬 코드 리뷰, UI/UX 분석, 보안 감사, Figma 분석/빌드.
+
+**44개 스킬** — 한 번에 다 로드되지 않음. 3-tier 시스템으로 컨텍스트 과부하 방지:
+
+| 티어 | 로드 시점 | 용도 | 예시 |
+|------|----------|------|------|
+| **Core** | 항상 활성 | 버그 방지, 워크플로 진입 | 품질 게이트, 인터뷰, 기획 |
+| **Standard** | `vibe init`이 스택별 선택 | 스택/역할 지원 | figma, design-audit, techdebt |
+| **Optional** | 명시적 `/skill` 호출만 | 레퍼런스, 래퍼 | chub-usage, context7 |
+
+**멀티 LLM** — Claude가 오케스트레이션, GPT가 추론, Gemini가 리서치. 가용 모델에 따라 자동 라우팅. 기본값은 Claude 단독. coco 환경(GPT 주관)에서는 Claude CLI가 보조로 전환되어 cross-validation 수행 — `~/.coco/` 감지로 역할 자동 역전.
+
+**스택 감지** — 24개 프레임워크 자동 감지 (Next.js, Django, Rails, Go, Rust, Flutter 등) 후 프레임워크별 규칙과 스킬 적용.
+
+**세션 메모리** — 결정, 제약, 목표가 SQLite + FTS5 검색으로 세션 간 유지.
+
+**Smart Resume** — `.last-feature` 포인터가 마지막 작업을 추적. 인자 없이 `/vibe.spec`을 호출하면 중단된 위치를 보여주거나 진행 중 feature 목록을 제시.
+
+---
+
+## 지원 도구
+
+| CLI | 상태 |
+|-----|------|
+| [Claude Code](https://claude.ai/code) | 전체 지원 |
+| coco (`~/.coco/`) | 전체 지원 (자동 감지) |
+| [Codex](https://github.com/openai/codex) | 플러그인 |
+| [Cursor](https://cursor.sh) | 에이전트 + 룰 |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | 에이전트 + 스킬 |
+
+---
+
+## 명령어
+
+| 명령어 | 용도 |
+|--------|------|
+| `/vibe.spec` | 단일 진입점 — 인터뷰, 기획, SPEC, 리뷰, 그리고 구현까지 |
+| `/vibe.run` | SPEC 기반 구현 |
+| `/vibe.figma` | Figma ↔ 코드 (읽기 또는 쓰기, 3가지 모드) |
+| `/vibe.verify` | 구현이 SPEC에 맞는지 검증 |
+| `/vibe.trace` | 요구사항 추적 매트릭스 |
+
+---
+
+## 문서
+
+상세 가이드, 스킬 레퍼런스, 설정 방법은 [Wiki](https://github.com/su-record/vibe/wiki)를 참고하세요.
+
+- [README (English)](README.md)
+- [릴리스 노트](RELEASE_NOTES.md)
+
+---
+
+## 요구사항
+
+- Node.js >= 18.0.0
+- Claude Code (필수)
+- GPT, Gemini (선택)
+
+## 라이선스
+
+MIT — Copyright (c) 2025 Su