@su-record/vibe 2.9.1 → 2.9.3

package/CLAUDE.md

@@ -38,12 +38,13 @@
 - No `@ts-ignore` — fix type issues at root
 - Explicit return types on all functions
 
-### Convergence Principle (Over-Diagnosis Prevention)
+### Convergence Principle (Quality-First, No Round Cap)
 
-- **P1 only is mandatory, P2/P3 are best-effort** — P1=0 means done
-- **Repeated reviews narrow scope** — Round 2: P1+P2 only, Round 3+: P1 only
-- **Convergence detection** — Same results as previous round → stop immediately
-- **3 failures = escalation** — No more retries, move to TODO
+- **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
@@ -86,6 +87,7 @@
 | 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/` |
@@ -105,13 +107,29 @@
 ## Workflow
 
 ```text
-/vibe.spec → /new → /vibe.spec.review → /vibe.run → /vibe.trace → (auto) code review → Done
+/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` |
+| 3+ files | `/vibe.spec` (전체 워크플로 오케스트레이션) |
 
 ## Magic Keywords
 
@@ -129,7 +147,7 @@ Skills are classified into 3 tiers to prevent context overload (Curse of Instruc
 
 | Tier | Loading | Purpose | Count |
 |------|---------|---------|-------|
-| **core** | Always active | Bug/mistake prevention safety nets | ~9 |
+| **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 |
 
@@ -141,7 +159,10 @@ When the user's context matches a pattern below, suggest the relevant skill **on
 
 | User Context | Suggested Skill | Tier | Signal |
 |-------------|-----------------|------|--------|
-| Writing a new SPEC / planning | `/vibe.spec` | core | "let's build", "new feature", "requirements" |
+| 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 |
@@ -162,7 +183,7 @@ When the user's context matches a pattern below, suggest the relevant skill **on
 
 ## Git Commit Rules
 
-**Must include:** `.claude/vibe/specs/`, `.claude/vibe/features/`, `.claude/vibe/todos/`, `.claude/vibe/config.json`, `CLAUDE.md`
+**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`
 

package/README.ko.md

@@ -1,13 +1,13 @@
 # VIBE
 
-**AI가 코드를 쓴다. 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를 감싸고, 타입 안전성, 코드 품질, 보안을 자동으로 강제합니다.
+Vibe는 AI 코딩 도구를 위한 품질 하네스입니다. Claude Code, Codex, Cursor, Gemini CLI를 감싸고, 타입 안전성, 코드 품질, 보안을 자동으로 강제합니다. 빠르게 바이브 코딩하되, 엉망인 코드가 나가지 않게.
 
 ```bash
 npm install -g @su-record/vibe
@@ -16,61 +16,114 @@ 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 ──── 완료
 ```
-사용자: "사용자 인증 추가해줘"
 
-  /vibe.spec        → GPT + Gemini 병렬 리서치 → SPEC 문서 자동 생성
-  /vibe.run         → SPEC 기반 구현 → 12개 에이전트 병렬 리뷰
-  품질 게이트        → any 타입 차단, 긴 함수 차단, 위험한 명령 차단
-  완료              → 리뷰 통과된 타입 안전 코드만 남음
+**Smart Resume** — 아무 단계에서나 멈추고, 세션을 닫고, 나중에 돌아오세요. `/vibe.spec`이 중단된 위치를 자동 감지하고 이어서 진행합니다. feature 이름을 외울 필요 없음.
 
-전부 자동. 프롬프트 한 줄이면 됩니다.
-```
+**ultrawork** — 어느 명령이든 `ultrawork`를 붙이면 모든 확인 게이트를 건너뛰고 전체 파이프라인을 자동 실행합니다.
 
 ---
 
 ## 빠른 시작
 
 ```bash
-# 1. 설치
+# 설치
 npm install -g @su-record/vibe
 
-# 2. 프로젝트 초기화 (스택 자동 감지)
+# 프로젝트 초기화 (스택 자동 감지)
 cd your-project
 vibe init
 
-# 3. AI 코딩 도구와 함께 사용
-claude                                 # Claude Code
-# 또는 codex, cursor, gemini — 모두 지원
+# AI 코딩 도구 시작
+claude
 
-# 4. 워크플로우 시작
-/vibe.spec "사용자 인증 추가"            # 요구사항 작성
-/vibe.run                              # SPEC 기반 구현
+# 워크플로우 실행
+/vibe.spec "사용자 인증 추가"
 ```
 
-`ultrawork`를 붙이면 전체 파이프라인이 자동화됩니다:
+---
+
+## Figma ↔ 코드
+
+양방향. Figma에서 디자인을 읽거나, 기획서에서 Figma에 디자인을 쓰거나.
 
 ```bash
-/vibe.run "사용자 인증 추가" ultrawork
+# 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이면 사용자에게 질문, 절대 조용히 넘어가지 않음. |
+
 ---
 
 ## 주요 기능
 
-**품질 게이트** — `any` 타입, `@ts-ignore`, 50줄 초과 함수를 차단. 3계층 방어가 모든 도구 호출마다 실행.
+**40+ 에이전트** — 탐색, 구현, 아키텍처, 병렬 코드 리뷰, UI/UX 분석, 보안 감사, Figma 분석/빌드.
+
+**44개 스킬** — 한 번에 다 로드되지 않음. 3-tier 시스템으로 컨텍스트 과부하 방지:
 
-**전문 에이전트** — 탐색, 구현, 아키텍처, 코드 리뷰(12개 병렬), UI/UX 분석 등 56개 목적 특화 에이전트.
+| 티어 | 로드 시점 | 용도 | 예시 |
+|------|----------|------|------|
+| **Core** | 항상 활성 | 버그 방지, 워크플로 진입 | 품질 게이트, 인터뷰, 기획 |
+| **Standard** | `vibe init`이 스택별 선택 | 스택/역할 지원 | figma, design-audit, techdebt |
+| **Optional** | 명시적 `/skill` 호출만 | 레퍼런스, 래퍼 | chub-usage, context7 |
 
 **멀티 LLM** — Claude가 오케스트레이션, GPT가 추론, Gemini가 리서치. 가용 모델에 따라 자동 라우팅. 기본값은 Claude 단독.
 
-**세션 메모리** — 결정, 제약, 목표가 SQLite + FTS5 검색으로 세션 간 유지.
+**스택 감지** — 24개 프레임워크 자동 감지 (Next.js, Django, Rails, Go, Rust, Flutter 등) 후 프레임워크별 규칙과 스킬 적용.
 
-**스택 감지** — 24개 프레임워크 자동 감지 (Next.js, Django, Rails, Go, Rust, Flutter 등) 후 프레임워크별 규칙 적용.
+**세션 메모리** — 결정, 제약, 목표가 SQLite + FTS5 검색으로 세션 간 유지.
 
-**Figma → 코드** — 트리 기반 구조적 매핑으로 디자인 대비 90% 완성도 목표. Figma REST API에서 30+ CSS 속성을 추출하여 반응형 코드 생성.
+**Smart Resume** — `.last-feature` 포인터가 마지막 작업을 추적. 인자 없이 `/vibe.spec`을 호출하면 중단된 위치를 보여주거나 진행 중 feature 목록을 제시.
 
 ---
 
@@ -85,6 +138,18 @@ claude                                 # Claude Code
 
 ---
 
+## 명령어
+
+| 명령어 | 용도 |
+|--------|------|
+| `/vibe.spec` | 단일 진입점 — 인터뷰, 기획, SPEC, 리뷰, 그리고 구현까지 |
+| `/vibe.run` | SPEC 기반 구현 |
+| `/vibe.figma` | Figma ↔ 코드 (읽기 또는 쓰기, 3가지 모드) |
+| `/vibe.verify` | 구현이 SPEC에 맞는지 검증 |
+| `/vibe.trace` | 요구사항 추적 매트릭스 |
+
+---
+
 ## 문서
 
 상세 가이드, 스킬 레퍼런스, 설정 방법은 [Wiki](https://github.com/su-record/vibe/wiki)를 참고하세요.

package/README.md

@@ -1,13 +1,13 @@
 # VIBE
 
-**AI writes code. Vibe makes sure it's good.**
+**Easy vibe coding. Minimum quality guaranteed.**
 
 [![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 is a quality harness for AI coding tools. It wraps around Claude Code, Codex, Cursor, or Gemini CLI and automatically enforces type safety, code quality, and security — before, during, and after code generation.
+Vibe is a quality harness for AI coding tools. It wraps around Claude Code, Codex, Cursor, or Gemini CLI and automatically enforces type safety, code quality, and security — so you can vibe-code fast without shipping garbage.
 
 ```bash
 npm install -g @su-record/vibe
@@ -16,61 +16,159 @@ vibe init
 
 ---
 
-## How It Works
+## The Workflow
 
+One entry point. Everything else is automatic.
+
+```
+/vibe.spec "coffee brand landing page"
+     |
+     v
+  Interview  ─── "Who's the audience?" "What sections?" "Dark mode?" ───
+     |                     (loops until you say stop)
+     v
+  Plan       ─── Structured planning document (.claude/vibe/plans/)
+     |
+     v
+  SPEC       ─── PTCF spec + BDD features, GPT+Gemini parallel research
+     |
+     v
+  Review     ─── Race review (GPT vs Gemini), quality gate (100-point, loop until perfect)
+     |
+     +──────────────────────────────┐
+     v                              v
+  /vibe.run (Logic)            /vibe.figma (UI)
+  Implement from SPEC          Figma design ↔ Code
+  12 agents review             Read or Write
+     |                              |
+     v                              v
+  /vibe.verify ──── /vibe.trace ──── Done
 ```
-You: "Add user authentication"
 
-  /vibe.spec        → GPT + Gemini research in parallel → SPEC document
-  /vibe.run         → Implement from SPEC → 12 agents review in parallel
-  Quality gates     → Block any types, long functions, dangerous commands
-  Done              → Only reviewed, type-safe code remains
+**Smart Resume** — Stop at any step, close the session, come back later. `/vibe.spec` auto-detects where you left off and picks up from there. No need to remember feature names.
 
-Every step is automatic. You type one prompt.
-```
+**ultrawork** — Add `ultrawork` to skip all confirmation gates and run the full pipeline hands-free.
 
 ---
 
 ## Quick Start
 
 ```bash
-# 1. Install
+# Install
 npm install -g @su-record/vibe
 
-# 2. Initialize your project (auto-detects stack)
+# Initialize (auto-detects your stack, generates project-aware CLAUDE.md)
 cd your-project
 vibe init
 
-# 3. Use with your AI coding tool
-claude                              # Claude Code
-# or codex, cursor, gemini — all supported
+# Start your AI coding tool
+claude
+
+# Run the workflow
+/vibe.spec "add user authentication"
+```
+
+---
+
+## Harness Engineering
+
+Vibe is built on the [Harness Engineering](https://anthropic.com/engineering/harness-design) principle — designing the working environment so AI operates effectively on its own.
+
+### The 6 Axes
+
+| Axis | What it covers | Vibe implementation |
+|------|---------------|---------------------|
+| **Scaffolding** | Project structure, tools, boundaries | `/vibe.scaffold` generates optimized folder structure (docs/, .dev/, layered src/) |
+| **Context** | What AI knows | `vibe init` generates project-aware CLAUDE.md from actual structure analysis |
+| **Planning** | What to build | `/vibe.spec` → interview → plan → SPEC → review pipeline |
+| **Orchestration** | How to execute | 40+ agents, 12 teams, skill-based dispatch |
+| **Verification** | How to trust | Hooks, convergence loops, RTM traceability |
+| **Compounding** | How to improve | Evolution engine, session memory, auto-generated skills |
+
+### Diagnose Your Project
+
+```bash
+/vibe.harness    # Score your project across all 6 axes (0-100)
+```
+
+Produces a detailed report with per-axis scores, grade (S/A/B/C/D), and auto-fixable improvement suggestions. Detects project type (app vs package/library) and adjusts scoring accordingly.
+
+---
+
+## Analyze Anything
+
+`/vibe.analyze` works on more than just source code:
 
-# 4. Try the workflow
-/vibe.spec "add user authentication"   # Write requirements
-/vibe.run                              # Implement from SPEC
+```bash
+/vibe.analyze "login"              # Feature/module code exploration
+/vibe.analyze --code               # Code quality analysis
+/vibe.analyze report.pdf           # Document analysis (PDF, slides, markdown)
+/vibe.analyze https://example.com  # Website analysis (UX, tech, SEO, a11y)
+/vibe.analyze https://figma.com/…  # Figma design analysis
 ```
 
-Add `ultrawork` to any command for full automation:
+Auto-detects input type (file extension → URL pattern → flag → string) and routes to the appropriate analysis mode with mode-specific quality gates.
+
+---
+
+## Figma ↔ Code
+
+Bidirectional. Read designs from Figma, or write designs to Figma from a plan.
 
 ```bash
-/vibe.run "add user authentication" ultrawork
+# READ — Add UI to existing project (follows project conventions)
+/vibe.figma <figma-url> <figma-url>
+
+# READ — New standalone page (independent styles)
+/vibe.figma --new <figma-url>
+
+# WRITE — Create Figma design from plan document
+/vibe.figma plan.md --create                 # Full (wireframe + visual design)
+/vibe.figma plan.md --create-storyboard      # Wireframe only
+/vibe.figma plan.md --create-design          # Visual design only
 ```
 
+**How READ works**: Extracts the Figma node tree + 30 CSS properties via REST API, maps Auto Layout to Flexbox 1:1, generates responsive SCSS. Screenshot is for verification only — the tree is the source of truth.
+
+**How WRITE works**: Parses plan document sections (Look & Feel, layout, responsive strategy), builds wireframe first for structure review, then applies visual design with design system components. Idempotent — re-run after editing the plan and only changed sections update.
+
+---
+
+## Quality Gates
+
+Three layers of defense on every tool call:
+
+| Layer | What it blocks |
+|-------|----------------|
+| Pre-commit hooks | `any` types, `@ts-ignore`, `console.log`, functions > 50 lines |
+| Review agents | 12 specialized reviewers run in parallel (security, performance, a11y, complexity, ...) |
+| Convergence loop | Review findings loop until P1 = 0. No round cap. Stuck = ask user, never silently proceed. |
+
 ---
 
-## What It Does
+## Key Features
+
+**40+ agents** — Exploration, implementation, architecture, parallel code review, UI/UX analysis, security audit, Figma analysis/building.
 
-**Quality gates** — Blocks `any` types, `@ts-ignore`, functions over 50 lines. Three-layer defense runs on every tool call.
+**44 skills** — Not all loaded at once. 3-tier system prevents context overload:
 
-**Specialized agents** — 56 purpose-built agents for exploration, implementation, architecture, code review (12 in parallel), and UI/UX analysis.
+| Tier | When loaded | Purpose | Examples |
+|------|-------------|---------|----------|
+| **Core** | Always active | Bug prevention, workflow entry | quality gates, interview, plan |
+| **Standard** | `vibe init` selects by stack | Stack/capability support | figma, design-audit, techdebt |
+| **Optional** | Explicit `/skill` only | Reference, wrappers | chub-usage, context7 |
 
 **Multi-LLM** — Claude orchestrates, GPT reasons, Gemini researches. Auto-routes by availability. Works Claude-only by default.
 
+**Stack detection** — Auto-detects 24 frameworks (Next.js, Django, Rails, Go, Rust, Flutter, and more) and applies framework-specific rules and skills.
+
+**Project-aware CLAUDE.md** — `vibe init` and `vibe update` analyze your project's actual structure (folders, tech stack, build commands) and generate a tailored CLAUDE.md — not a static template.
+
 **Session memory** — Decisions, constraints, and goals persist across sessions via SQLite + FTS5 hybrid search.
 
-**Stack detection** — Auto-detects 24 frameworks (Next.js, Django, Rails, Go, Rust, Flutter, and more) and applies framework-specific rules.
+**Smart Resume** — `.last-feature` pointer tracks your latest work. `/vibe.spec` without arguments shows where you left off or lists all in-progress features.
 
-**Figma → Code** — Tree-based structural mapping targeting 90% design fidelity. Extracts 30+ CSS properties from Figma REST API, remaps across breakpoints, generates responsive code.
+**Self-repair** — Skills include error recovery tables. `/vibe.harness` diagnoses gaps and chains to `/vibe.scaffold` → `vibe update` for automated fixes.
 
 ---
 
@@ -85,6 +183,22 @@ Add `ultrawork` to any command for full automation:
 
 ---
 
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/vibe.spec` | Single entry point — interview, plan, spec, review, then run |
+| `/vibe.run` | Implement from SPEC |
+| `/vibe.figma` | Figma ↔ Code (read or write, 3 modes) |
+| `/vibe.verify` | Verify implementation against SPEC |
+| `/vibe.trace` | Requirements traceability matrix |
+| `/vibe.analyze` | Analyze any target — code, documents, websites, Figma |
+| `/vibe.scaffold` | Generate or audit project folder structure |
+| `/vibe.harness` | Diagnose Harness Engineering maturity (6-axis scoring) |
+| `/vibe.docs` | Generate project documentation |
+
+---
+
 ## Documentation
 
 Full guides, skill reference, and configuration details are in the [Wiki](https://github.com/su-record/vibe/wiki).

package/agents/teams/debug-team.md

@@ -0,0 +1,70 @@
+# Debug Team
+
+빌드/테스트 실패 시 아키텍트 진단 → 구현자 수정 → 테스터 검증 사이클.
+
+## 팀 구성
+
+| 팀원 | 역할 | Model |
+|------|------|-------|
+| architect (리더) | 근본 원인 진단, 수정 방향 설계, 아키텍처 레벨 문제 식별 | Opus |
+| implementer | architect 진단에 따라 최소 diff 수정 적용 | Sonnet |
+| tester | 수정 후 즉시 테스트 실행, 회귀 검증 | Haiku |
+
+## 활성화 조건
+
+- 동일 빌드/테스트 실패 3회 이상
+- UltraQA `architecture_question` 상태 진입 시
+
+## 워크플로우
+
+```
+[입력: 에러 출력 + 실패 파일 + 이전 시도 이력]
+    |
+architect: 근본 원인 분석 (증상이 아닌 원인)
+    |
+    └──→ implementer: 최소 diff 수정
+            └──→ tester: 테스트 실행
+                    ├─ PASS → 완료
+                    └─ FAIL → architect 재진단 (3회 실패 → 사용자 에스컬레이션)
+```
+
+## spawn 패턴
+
+```text
+TeamCreate(team_name="debug-{feature}", description="Debug team for {feature} build/test failure")
+
+Task(team_name="debug-{feature}", name="architect", subagent_type="architect",
+  prompt="Debug team leader. Diagnose root cause of build/test failure.
+  Error: {error_output}
+  Failed files: {failed_files}
+  Previous attempts: {attempt_history}
+  Role: Analyze error, identify root cause (not symptoms). Design minimal fix.
+  Send diagnosis to implementer via SendMessage. If same failure 3x, escalate to user.")
+
+Task(team_name="debug-{feature}", name="implementer", subagent_type="implementer",
+  mode="bypassPermissions",
+  prompt="Debug team fixer. Apply minimal-diff fixes based on architect diagnosis.
+  Role: Wait for architect diagnosis. Apply ONLY the specific fix recommended.
+  Do NOT refactor surrounding code. Notify tester when fix is applied.")
+
+Task(team_name="debug-{feature}", name="tester", subagent_type="tester",
+  mode="bypassPermissions",
+  prompt="Debug team verifier. Run tests after each fix to verify resolution.
+  Role: Wait for implementer fix notification. Run failing tests.
+  Report results to architect. If still failing, provide detailed error output.")
+```
+
+## 팀원 간 통신
+
+```text
+architect → implementer: "근본 원인: circular import in module A→B→A. B의 import를 lazy로 변경하세요"
+implementer → tester: "수정 완료. 기존 실패 테스트 재실행 요청합니다"
+tester → architect: "여전히 실패. 새로운 에러: TypeError at line 42"
+architect → broadcast: "3회 실패. 사용자 에스컬레이션이 필요합니다"
+```
+
+## ⛔ 하지 않는 것
+
+- 주변 코드 리팩터링 (최소 diff만)
+- 증상 치료 (근본 원인 해결만)
+- 4회 이상 자동 재시도 (3회 실패 → 사용자 에스컬레이션)

package/agents/teams/dev-team.md

@@ -0,0 +1,88 @@
+# Dev Team
+
+에이전트들이 팀을 이루어 서로 소통하며 구현하는 풀 구현 팀.
+
+## 팀 구성
+
+| 팀원 | 역할 | Model |
+|------|------|-------|
+| architect (리더) | 설계 결정, 구현 방향 조율, SPEC 준수 검증, 팀 합의 주도 | Opus |
+| implementer | 핵심 비즈니스 로직 구현, architect 설계를 따라 코드 작성 | Sonnet |
+| tester | 구현 완료 즉시 테스트 작성, 실패 시 implementer에 피드백 | Haiku |
+| security-reviewer | 실시간 보안 취약점 검증, 블로킹 이슈 식별 | Sonnet |
+
+## 활성화 조건
+
+- ULTRAWORK 모드 + 3개 이상 시나리오
+- 또는 복잡도 점수 20+ (High)
+
+## 워크플로우
+
+```
+architect: SPEC Phase 분석 → 구현 계획 수립 → TaskList에 작업 등록
+    |
+    ├──→ implementer: TaskList에서 claim → 코드 작성
+    │       ├──→ tester: 컴포넌트 완료 즉시 테스트 (점진적)
+    │       │       └── 실패 시 → implementer에 피드백
+    │       └──← security-reviewer: 실시간 보안 검증
+    │               └── 블로킹 이슈 → implementer 즉시 수정
+    |
+architect: 모든 시나리오 통과 확인 → 팀 종료
+```
+
+## spawn 패턴
+
+```text
+TeamCreate(team_name="dev-{feature}", description="Implementation team for {feature} Phase {N}")
+
+Task(team_name="dev-{feature}", name="architect", subagent_type="architect",
+  prompt="구현 팀 리더. Phase {N}의 SPEC을 분석하고 구현 계획을 수립하세요.
+  SPEC: {spec_content}
+  Feature Scenarios: {scenarios}
+  역할: 설계 결정, 구현 방향 조율, 팀원 간 충돌 해결, SPEC 준수 검증.
+  TaskList에 구현 작업을 등록하세요. implementer에게 설계를 SendMessage로 전달하세요.
+  모든 시나리오가 통과할 때까지 팀을 조율하세요.")
+
+Task(team_name="dev-{feature}", name="implementer", subagent_type="implementer",
+  mode="bypassPermissions",
+  prompt="구현 팀 코드 담당. SPEC: {spec_content}
+  역할: architect의 설계를 따라 프로덕션 코드 작성.
+  architect에게서 설계를 받으면 구현을 시작하세요.
+  컴포넌트 구현 완료 시 tester에게 SendMessage로 테스트 요청하세요.
+  security-reviewer의 블로킹 이슈는 즉시 수정하세요.
+  TaskList에서 구현 작업을 claim하세요.")
+
+Task(team_name="dev-{feature}", name="tester", subagent_type="tester",
+  mode="bypassPermissions",
+  prompt="구현 팀 테스트 담당. SPEC: {spec_content}
+  역할: implementer가 완료한 컴포넌트부터 즉시 테스트 작성.
+  구현 전체를 기다리지 말고 컴포넌트 단위로 점진적 테스트하세요.
+  테스트 실패 시 implementer에게 SendMessage로 피드백하세요.
+  edge case 발견 시 architect에게 설계 검토를 요청하세요.
+  TaskList에서 테스트 작업을 claim하세요.")
+
+Task(team_name="dev-{feature}", name="security-reviewer", subagent_type="security-reviewer",
+  mode="bypassPermissions",
+  prompt="구현 팀 보안 담당. SPEC: {spec_content}
+  역할: 구현 코드의 보안 취약점 실시간 검증.
+  보안 이슈는 BLOCKING — implementer에게 SendMessage로 즉시 수정 요청하세요.
+  심각한 설계 결함 발견 시 architect에게 SendMessage로 알리세요.
+  TaskList에서 보안 검증 작업을 claim하세요.")
+```
+
+## 팀원 간 통신
+
+```text
+architect → implementer: "Repository 패턴으로 데이터 접근 계층 분리해서 구현해주세요. 인터페이스는 TaskList에 등록했습니다"
+implementer → tester: "LoginService 구현 완료. 정상/실패/잠금 시나리오 테스트 요청합니다"
+security-reviewer → implementer: "SQL injection 위험: raw query 사용 감지. parameterized query로 즉시 수정 필요"
+tester → architect: "edge case 3건 실패 (빈 입력, 특수문자, 동시 요청). 설계 검토 요청합니다"
+architect → broadcast: "Phase {N} 모든 시나리오 통과 확인. 구현 완료합니다"
+```
+
+## ⛔ 하지 않는 것
+
+- SPEC 범위 밖의 기능 추가
+- architect 승인 없이 설계 변경
+- 테스트 실패 상태에서 다음 컴포넌트 진행
+- security-reviewer 블로킹 이슈 무시