@su-record/vibe 2.7.20 → 2.7.22

package/README.md

@@ -1,4 +1,4 @@
-# VIBE — AI Coding Framework for Claude Code
+# 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)
@@ -6,7 +6,9 @@
 [![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)
 
-**설치 한 줄로 Claude Code에 53개 에이전트, 43+ 도구, 멀티 LLM 오케스트레이션을 더합니다.**
+**설치 한 줄로 56개 에이전트, 43+ 도구, 멀티 LLM 오케스트레이션을 더합니다.**
+
+Claude Code, Codex, Cursor, Gemini CLI 모두 지원.
 
 ```bash
 npm install -g @su-record/vibe
@@ -24,7 +26,7 @@ Vibe는 구조로 해결합니다.
 |------|------|
 | AI가 `any` 타입 남발 | Quality Gate가 `any`/`@ts-ignore` 차단 |
 | 한 번에 완성 기대 | SPEC → 구현 → 검증 단계별 워크플로우 |
-| 리뷰 없이 머지 | 12개 에이전트 병렬 리뷰 |
+| 리뷰 없이 머지 | 12개 에이전트 병렬 리뷰 + 경계면 불일치 감지 |
 | AI 결과를 그대로 수용 | GPT + Gemini 교차 검증 |
 | 컨텍스트 소실 | Session RAG로 자동 저장/복원 |
 | 복잡한 작업에서 길을 잃음 | SwarmOrchestrator 자동 분해 + 병렬 실행 |
@@ -39,6 +41,42 @@ Vibe는 구조로 해결합니다.
 
 ---
 
+## 멀티 CLI 지원
+
+| CLI | 설치 방식 | 에이전트 | 스킬 | 지시사항 |
+|-----|----------|---------|------|---------|
+| **Claude Code** | `~/.claude/agents/` (YAML frontmatter) | 56개 | `~/.claude/skills/` | `CLAUDE.md` |
+| **Codex** | `~/.codex/plugins/vibe/` (Plugin) | 56개 | 플러그인 내장 | `AGENTS.md` |
+| **Cursor** | `~/.cursor/agents/` | 56개 | `~/.cursor/skills/` | `.cursorrules` |
+| **Gemini CLI** | `~/.gemini/agents/` | 56개 | `~/.gemini/skills/` | `GEMINI.md` |
+
+### Codex 플러그인 통합
+
+Codex Claude Code 플러그인(`codex-plugin-cc`) 설치 시 워크플로우 전 단계에서 자동 활용:
+
+| 워크플로우 | Codex 활용 | 명령 |
+|-----------|-----------|------|
+| **spec review** | SPEC 설계 도전 리뷰 | `/codex:adversarial-review` |
+| **run** | 병렬 구현 위임 | `/codex:rescue --background` |
+| **run / review** | 3중 교차 코드 리뷰 (GPT+Gemini+Codex) | `/codex:review` |
+| **run / review** | auto-fix 실패 시 폴백 | `/codex:rescue` |
+| **verify** | 최종 리뷰 게이트 | `/codex:review` |
+| **Stop 훅** | 코드 변경 시 자동 리뷰 | `codex-review-gate.js` |
+
+Codex 미설치 시 자동 스킵 — 기존 워크플로우로 동작.
+
+`vibe init` 시 Codex 플러그인 번들도 자동 생성:
+
+```
+~/.codex/plugins/vibe/
+├── .codex-plugin/plugin.json   # 플러그인 매니페스트
+├── agents/                     # 56개 에이전트 (순수 마크다운)
+├── skills/                     # 전역 스킬
+└── AGENTS.md                   # VIBE 지시사항
+```
+
+---
+
 ## 워크플로우
 
 ```mermaid
@@ -50,9 +88,9 @@ flowchart LR
 ```
 
 1. **`/vibe.spec`** — 요구사항을 SPEC 문서로 정의 (GPT + Gemini 병렬 리서치)
-2. **`/vibe.spec.review`** — SPEC 품질 리뷰
-3. **`/vibe.run`** — SPEC 기반 구현 + 병렬 코드 리뷰
-4. **자동 리뷰** — 12개 전문 에이전트 병렬 검토, P1/P2 자동 수정
+2. **`/vibe.spec.review`** — SPEC 품질 리뷰 + Codex adversarial review (3중 교차 검증)
+3. **`/vibe.run`** — SPEC 기반 구현 (Codex rescue 병렬 위임) + 3중 코드 리뷰
+4. **자동 리뷰** — 12개 전문 에이전트 병렬 검토 + Codex/경계면 검증, P1/P2 자동 수정
 
 `ultrawork` 키워드를 붙이면 전 과정이 자동화됩니다:
 
@@ -62,7 +100,7 @@ flowchart LR
 
 ---
 
-## 에이전트 (53개)
+## 에이전트 (56개)
 
 ### 메인 에이전트 (19)
 
@@ -87,48 +125,42 @@ Security, Performance, Architecture, Complexity, Simplicity, Data Integrity, Tes
 | RUN | ui-stack-implementer, ui-dataviz-advisor |
 | REVIEW | ux-compliance-reviewer, ui-a11y-auditor, ui-antipattern-detector |
 
-### 리서치 & QA (10)
-
-Best Practices, Framework Docs, Codebase Patterns, Security Advisory, Requirements Analyst, UX Advisor, Acceptance Tester, Edge Case Finder, API Documenter, Changelog Writer
-
-### 이벤트 에이전트 (6)
+### QA & 리서치 (11)
 
-Event Listener, Event Trigger, Event Filter, Event Logger, Event Scheduler, Event Aggregator
+| 카테고리 | 에이전트 |
+|----------|---------|
+| **QA** | QA Coordinator, Edge Case Finder, Acceptance Tester |
+| **리서치** | Best Practices, Framework Docs, Codebase Patterns, Security Advisory |
+| **분석** | Requirements Analyst, UX Advisor, API Documenter, Changelog Writer |
 
-### 에이전트 팀 (9팀)
+QA Coordinator는 변경된 코드를 분석하여 적절한 QA 에이전트를 병렬 디스패치하고, 통합 QA 리포트를 생성합니다.
 
-에이전트가 팀을 구성하여 공유 태스크 리스트로 협업합니다.
+### 이벤트 에이전트 (6)
 
-| 팀 | 트리거 | 멤버 |
-|----|--------|------|
-| Lite | `/vibe.run` 일반 | architect, implementer, tester |
-| Dev | `/vibe.run` ULTRAWORK | + security-reviewer |
-| Research | `/vibe.spec` | 4개 리서치 에이전트 |
-| Review Debate | `/vibe.review` | security, architecture, performance, simplicity |
-| Debug | `/vibe.run` 실패 | architect, implementer, tester |
-| Security | `/vibe.run` 보안 | security, data-integrity, security-advisory, tester |
-| Migration | `/vibe.run` 마이그레이션 | + build-error-resolver |
-| Fullstack | `/vibe.run` 풀스택 | frontend + backend implementer |
-| SPEC Debate | `/vibe.spec.review` | 동일 |
+Event Content, Event Image, Event Speaker, Event Ops, Event Comms, Event Scheduler
 
 ---
 
 ## 멀티 LLM 오케스트레이션
 
-| 프로바이더 | 역할 | 인증 |
-|-----------|------|------|
-| **Claude** | 오케스트레이션, 코드 생성 | 내장 (Claude Code) |
-| **GPT** | 아키텍처, 디버깅, 교차 리뷰 | Codex CLI / API Key |
-| **Gemini** | UI/UX, 웹 검색, 음성, 리서치 | gemini-cli / API Key |
+| 프로바이더 | 모델 | 역할 | 인증 |
+|-----------|------|------|------|
+| **Claude** | Opus / Sonnet / Haiku | SPEC 작성, 코드 리뷰, 오케스트레이션 | 내장 (Claude Code) |
+| **GPT** | gpt-5.4 | 추론, 아키텍처, 엣지케이스 분석 | Codex CLI / API Key |
+| **Codex** | gpt-5.3-codex | 구현, 멀티파일 코딩 | Codex CLI / Plugin |
+| **Codex Spark** | gpt-5.3-codex-spark | 초고속 리뷰/린트 (1000+ tok/s) | Codex CLI / Plugin |
+| **Gemini** | gemini-3.1-pro | 리서치, 교차 검증, UI/UX | gemini-cli / API Key |
 
-### SmartRouter
+### 동적 모델 라우팅
 
-작업 유형별 자동 라우팅. 각 프로바이더는 CLI 위임 방식으로 호출합니다 (Codex CLI, gemini-cli).
+Codex/Gemini 활성화 상태에 따라 자동 스위칭. 기본은 Claude만으로 동작.
 
-| 작업 유형 | 우선순위 |
-|----------|---------|
-| 코드 분석, 리뷰, 추론, 아키텍처 | GPT → Gemini → Claude |
-| UI/UX, 웹 검색 | Gemini → GPT → Claude |
+| 상태 | 동작 |
+|------|------|
+| **Claude only** | Opus(설계/판단) + Sonnet(리뷰/구현) + Haiku(탐색) |
+| **+Codex** | 구현→5.3-Codex, 리뷰→Spark, 추론→5.4 스위칭 |
+| **+Gemini** | 리서치/리뷰에 Gemini 병렬 추가 |
+| **+Codex +Gemini** | 풀 오케스트레이션 (7개 모델) |
 
 ---
 
@@ -150,6 +182,58 @@ ULTRAWORK 모드에서 다음 Phase의 `prepare()`를 병렬 실행.
 
 ---
 
+## 인프라 패턴
+
+Agent-Lightning(Microsoft Research)의 핵심 아키텍처 패턴을 적용합니다.
+
+### Store Interface
+
+`IMemoryStorage` 인터페이스로 스토어를 추상화합니다. 테스트에서 SQLite 없이 `InMemoryStorage`로 교체 가능.
+
+```typescript
+import { InMemoryStorage } from '@su-record/vibe/tools';
+const store = new InMemoryStorage(); // DB 없이 테스트
+```
+
+### Structured Telemetry Spans
+
+8종의 타입화된 스팬으로 모든 작업을 추적합니다.
+
+| 스팬 타입 | 용도 |
+|----------|------|
+| `skill_run` | 스킬 실행 |
+| `agent_run` | 에이전트 실행 |
+| `edit` | 파일 수정 |
+| `build` | 빌드/컴파일 |
+| `review` | 코드 리뷰 |
+| `hook` | 훅 실행 |
+| `llm_call` | LLM 호출 |
+| `decision` | 의사결정 |
+
+```typescript
+import { createSpan, completeSpan } from '@su-record/vibe/tools';
+
+const span = createSpan('agent_run', 'explorer-low', { model: 'haiku' });
+// ... 작업 수행
+const done = completeSpan(span, 'ok', 1500);
+```
+
+부모-자식 계층 추적을 지원합니다 (`parent_id`). 모든 데이터는 로컬 JSONL에만 저장됩니다.
+
+### Component Registry
+
+런타임 컴포넌트 등록/해제를 지원하는 범용 레지스트리입니다.
+
+```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');
+```
+
+---
+
 ## Session RAG
 
 SQLite + FTS5 하이브리드 검색으로 세션 간 컨텍스트를 유지합니다.
@@ -166,22 +250,21 @@ SQLite + FTS5 하이브리드 검색으로 세션 간 컨텍스트를 유지합
 
 ## 스킬
 
-### 내장 스킬
+### 내장 스킬 (26개)
 
 에이전트가 활용하는 도메인별 스킬 모듈입니다. 스택 감지 결과에 따라 자동 설치됩니다.
 
 **코어**: Core Capabilities, Parallel Research, Commit Push PR, Git Worktree, Handoff, Priority Todos, Tool Fallback, Context7, Tech Debt, Characterization Test, Agents MD, Exec Plan, Arch Guard, Capability Loop
 
-**프론트엔드**: Frontend Design, UI/UX Pro Max, Brand Assets, SEO Checklist, Vercel React Best Practices
+**프론트엔드**: Frontend Design, UI/UX Pro Max, Brand Assets, SEO Checklist
 
-**도메인**: Commerce Patterns, E2E Commerce, Video Production, TypeScript Advanced Types
+**도메인**: Commerce Patterns, E2E Commerce, Video Production
 
 ### 외부 스킬 (skills.sh)
 
 [skills.sh](https://skills.sh) 에코시스템의 외부 스킬을 설치할 수 있습니다.
 
 ```bash
-# 수동 설치
 vibe skills add vercel-labs/next-skills
 ```
 
@@ -192,8 +275,6 @@ vibe skills add vercel-labs/next-skills
 | `typescript-react` | `vercel-labs/agent-skills` |
 | `typescript-nextjs` | `vercel-labs/agent-skills`, `vercel-labs/next-skills` |
 
-설치된 패키지는 `.claude/vibe/config.json`의 `installedExternalSkills`로 추적되어 중복 설치를 방지합니다.
-
 ---
 
 ## 25개 프레임워크 지원
@@ -239,7 +320,8 @@ vibe skills add vercel-labs/next-skills
 | 가드레일 | 메커니즘 |
 |----------|---------|
 | **타입 안전성** | Quality Gate — `any`, `@ts-ignore` 차단 |
-| **코드 리뷰** | 12개 전문 에이전트 병렬 리뷰 |
+| **코드 리뷰** | 12개 Sonnet 에이전트 병렬 리뷰 + Codex 3중 교차 검증 |
+| **경계면 검증** | API↔프론트엔드 타입/라우팅/상태 정합성 자동 검증 |
 | **완성도** | Ralph Loop — 100%까지 반복 (범위 축소 없음) |
 | **수렴 보장** | Convergence — P1=0이면 완료, 반복 시 범위 축소 |
 | **스코프 보호** | pre-tool-guard — 요청 범위 외 수정 방지 |
@@ -262,7 +344,7 @@ vibe skills add vercel-labs/next-skills
 | UserPromptSubmit | `keyword-detector.js` | 매직 키워드 감지 |
 | Notification | `context-save.js` | 컨텍스트 80/90/95% 자동 저장 |
 
-추가: `llm-orchestrate.js`, `code-review.js`, `recall.js`, `complexity.js`, `compound.js`, `stop-notify.js`
+추가: `llm-orchestrate.js`, `codex-review-gate.js`, `codex-detect.js`, `code-review.js`, `recall.js`, `complexity.js`, `compound.js`, `stop-notify.js`
 
 ---
 
@@ -366,13 +448,16 @@ vibe help / version
 import { MemoryStorage, SessionRAGStore } from '@su-record/vibe/memory';
 import { SwarmOrchestrator, PhasePipeline } from '@su-record/vibe/orchestrator';
 import { findSymbol, validateCodeQuality } from '@su-record/vibe/tools';
+
+// Agent-Lightning 패턴
+import { InMemoryStorage, ComponentRegistry, createSpan } from '@su-record/vibe/tools';
 ```
 
 | 서브패스 | 주요 export |
 |---------|------------|
-| `@su-record/vibe/memory` | `MemoryStorage`, `KnowledgeGraph`, `SessionRAGStore` |
+| `@su-record/vibe/memory` | `MemoryStorage`, `IMemoryStorage`, `InMemoryStorage`, `KnowledgeGraph`, `SessionRAGStore` |
 | `@su-record/vibe/orchestrator` | `SwarmOrchestrator`, `PhasePipeline`, `BackgroundManager` |
-| `@su-record/vibe/tools` | `findSymbol`, `validateCodeQuality`, `saveMemory` 등 |
+| `@su-record/vibe/tools` | `findSymbol`, `validateCodeQuality`, `createSpan`, `ComponentRegistry` 등 |
 | `@su-record/vibe/tools/memory` | 메모리 도구 |
 | `@su-record/vibe/tools/convention` | 코드 품질 도구 |
 | `@su-record/vibe/tools/semantic` | 시맨틱 분석 도구 |
@@ -396,18 +481,27 @@ your-project/
 │   │   └── reports/           # 리뷰 리포트
 │   └── skills/                # 로컬 + 외부 스킬
 ├── CLAUDE.md                  # 프로젝트 가이드 (자동 생성)
+├── AGENTS.md                  # Codex CLI 가이드 (자동 생성)
 └── ...
 
 ~/.vibe/config.json            # 전역 설정 (인증, 채널, 모델)
+~/.vibe/analytics/             # 텔레메트리 (로컬 JSONL)
+│   ├── skill-usage.jsonl      # 스킬 사용 기록
+│   ├── spans.jsonl            # 구조화된 스팬
+│   └── decisions.jsonl        # 의사결정 추적
 ~/.claude/
 ├── vibe/
 │   ├── rules/                 # 코딩 규칙
 │   ├── skills/                # 전역 스킬
-│   ├── ui-ux-data/            # UI/UX CSV 데이터
-│   ├── session-rag.db         # Session RAG (SQLite + FTS5)
-│   └── memories.json          # 저장된 메모리
+│   └── ui-ux-data/            # UI/UX CSV 데이터
 ├── commands/                  # 슬래시 명령어
-└── agents/                    # 에이전트 정의 (53개)
+└── agents/                    # 에이전트 정의 (56개)
+~/.codex/
+└── plugins/vibe/              # Codex 플러그인
+    ├── .codex-plugin/plugin.json
+    ├── agents/
+    ├── skills/
+    └── AGENTS.md
 ```
 
 ---
@@ -421,8 +515,9 @@ flowchart TD
     C --> D["SmartRouter"]
 
     D --> E["LLMCluster"]
-    E --> E1["GPT"]
-    E --> E2["Gemini"]
+    E --> E1["GPT-5.4 (추론)"]
+    E --> E2["Codex Spark (리뷰)"]
+    E --> E3["Gemini (리서치)"]
 
     D --> F["PhasePipeline"]
     F --> G["SwarmOrchestrator"]
@@ -430,12 +525,16 @@ flowchart TD
     H --> I["AgentRegistry"]
 
     D --> J["병렬 리뷰"]
-    J --> J1["12개 리뷰 에이전트"]
-    J1 --> K["P1/P2/P3 분류"]
+    J --> J1["12개 Sonnet 리뷰 에이전트"]
+    J --> J2["/codex:review"]
+    J1 --> K["3중 교차 검증 → P1/P2/P3"]
+    J2 --> K
+    J --> J3["경계면 검증"]
 
     L["Session RAG"] -.-> M["Decision / Constraint / Goal / Evidence"]
-    O["품질 게이트"] -.-> P["pre-tool-guard → 차단"]
-    O -.-> Q["code-check → 검증"]
+    N["VibeSpan"] -.-> O["spans.jsonl (로컬 텔레메트리)"]
+    P["품질 게이트"] -.-> Q["pre-tool-guard → 차단"]
+    P -.-> R["code-check → 검증"]
 ```
 
 ---

package/agents/qa/qa-coordinator.md

@@ -0,0 +1,131 @@
+# QA Coordinator
+
+<!-- QA Orchestrator Agent — routes changed code to appropriate QA agents -->
+
+## Role
+
+- Analyze code changes to determine which QA modalities are needed
+- Dispatch QA agents in parallel based on change type
+- Collect and synthesize results into a unified QA report
+- Ensure feature readiness before dispatching (build passes, no syntax errors)
+
+## Model
+
+**Sonnet** — Balanced reasoning for routing decisions
+
+## Execution Mode: Sub-Agent (Fan-out/Fan-in)
+
+Dispatches multiple QA agents in parallel, collects results, synthesizes.
+
+## Change Type → QA Agent Routing
+
+| Change Type | Signal | QA Agents to Dispatch |
+|-------------|--------|----------------------|
+| **API/Backend** | `src/api/`, `src/services/`, `routes/`, `controllers/` | security-reviewer, edge-case-finder, performance-reviewer |
+| **Frontend/UI** | `src/components/`, `src/pages/`, `*.tsx`, `*.vue` | ui-a11y-auditor, ux-compliance-reviewer, edge-case-finder |
+| **Data/Schema** | `models/`, `migrations/`, `schema/`, `*.prisma` | data-integrity-reviewer, edge-case-finder, acceptance-tester |
+| **Auth/Security** | `auth/`, `middleware/`, `session/`, `token/` | security-reviewer, edge-case-finder, e2e-tester |
+| **State Machine** | state transitions, workflow, status changes | edge-case-finder, acceptance-tester, data-integrity-reviewer |
+| **E2E Flow** | checkout, payment, multi-step form | e2e-tester, edge-case-finder, acceptance-tester |
+| **Config/Infra** | `.env`, `config/`, `docker`, CI/CD | security-reviewer, architecture-reviewer |
+
+## Workflow
+
+### Phase 1: Readiness Check
+
+Before dispatching any QA agent, verify:
+
+1. **Build passes**: Run `npm run build` (or project equivalent) — if it fails, STOP and report build errors
+2. **Changed files identified**: Use `git diff --name-only` to get the list of changed files
+3. **Change type classified**: Match changed files against the routing table above
+
+If build fails → return build errors immediately. Do not dispatch QA agents on broken code.
+
+### Phase 2: Agent Dispatch (Parallel)
+
+Based on classified change types, dispatch agents in a single message:
+
+```
+Agent(subagent_type="edge-case-finder", model="haiku",
+  prompt="Analyze these changed files for edge cases: {file_list}. Read each file fully before analysis.",
+  run_in_background=true)
+
+Agent(subagent_type="security-reviewer", model="haiku",
+  prompt="Security review for: {file_list}. Check OWASP Top 10. Read each file fully.",
+  run_in_background=true)
+
+Agent(subagent_type="{other-agent}", model="haiku",
+  prompt="...",
+  run_in_background=true)
+```
+
+**Rules:**
+- Maximum 5 parallel agents (avoid context explosion)
+- Always include `edge-case-finder` (catches what others miss)
+- De-duplicate: if multiple change types route to the same agent, dispatch once with combined file list
+- Each agent prompt MUST include the specific file list to review
+
+### Phase 3: Result Collection & Synthesis
+
+1. Wait for all agents to complete
+2. Read each agent's output
+3. Merge findings by priority:
+   - **P1 (Critical)**: Aggregate from all agents, de-duplicate
+   - **P2 (Important)**: Aggregate, de-duplicate
+   - **P3 (Nice-to-have)**: List briefly
+4. Cross-reference: if multiple agents flag the same location, elevate confidence
+
+### Phase 4: Unified Report
+
+```markdown
+## QA Coordinator Report
+
+### Summary
+- Changed files: {N}
+- Change types: {list}
+- QA agents dispatched: {N} ({agent names})
+- Total findings: P1={N}, P2={N}, P3={N}
+
+### Build Status
+- [PASS/FAIL] Build check
+
+### P1 Findings (Must Fix)
+| # | Agent | Finding | Location | Recommendation |
+|---|-------|---------|----------|----------------|
+| 1 | security-reviewer | SQL injection risk | src/api/users.ts:42 | Use parameterized query |
+| 2 | edge-case-finder | No null check | src/services/auth.ts:15 | Add validation |
+
+### P2 Findings (Should Fix)
+| # | Agent | Finding | Location | Recommendation |
+|---|-------|---------|----------|----------------|
+
+### P3 Findings (Consider)
+- {brief list}
+
+### Cross-Validated Findings
+Findings flagged by 2+ agents (high confidence):
+- {finding} — flagged by {agent1}, {agent2}
+
+### Coverage Gaps
+QA modalities NOT run (and why):
+- {e.g., "e2e-tester: no E2E flow changes detected"}
+```
+
+## Error Handling
+
+| Situation | Strategy |
+|-----------|----------|
+| Agent fails | 1 retry. If fails again, note in report as "coverage gap" |
+| Agent timeout | Use partial results if available, note in report |
+| Build fails | Stop immediately, report build errors only |
+| No changed files | Report "nothing to review" |
+| All agents return P1=0 | Report clean status, still list what was checked |
+
+## CRITICAL: NO DIRECT CODE FIXES
+
+This agent coordinates and reports only. It does NOT:
+- Modify source code
+- Create fix PRs
+- Write test files
+
+It produces the QA report. Fixes are handled by the user or implementer agents.

package/commands/vibe.review.md

@@ -20,6 +20,16 @@ argument-hint: "PR number, branch name, or file path"
 
 > **⏱️ Timer**: Call `getCurrentTime` tool at the START. Record the result as `{start_time}`.
 
+## Codex Plugin Integration
+
+> **Codex 플러그인 감지**: 워크플로우 시작 시 아래 명령으로 자동 감지.
+>
+> ```bash
+> CODEX_AVAILABLE=$(node "{{VIBE_PATH}}/hooks/scripts/codex-detect.js" 2>/dev/null || echo "unavailable")
+> ```
+>
+> `available`이면 `/codex:review`, `/codex:rescue` 자동 호출. `unavailable`이면 기존 GPT+Gemini Race 모드로 동작.
+
 ## Race Mode (v2.6.9)
 
 **Multi-LLM competitive review** - Same review task runs on GPT + Gemini in parallel, results are cross-validated.
@@ -89,6 +99,25 @@ security-review:
 - **Location**: `src/components/Comment.tsx:15`
 ```
 
+### Codex Review (Codex 플러그인 활성화 시)
+
+Race Mode에서 GPT+Gemini와 **동시에** Codex review 실행하여 3중 교차 검증:
+
+```
+/codex:review
+```
+
+교차 검증 테이블:
+
+```markdown
+| Issue | GPT | Gemini | Codex | Confidence |
+|-------|-----|--------|-------|------------|
+| {이슈} | ✅/❌ | ✅/❌ | ✅/❌ | {%} |
+```
+
+- 3개 모델 중 2개 이상 동의 → **High Confidence** (P1 자동 수정)
+- Codex만 발견 → **Medium Confidence** (P2 수동 검토)
+
 ### When to Use Race Mode
 
 | Scenario | Recommended |
@@ -257,6 +286,46 @@ Task(subagent_type="ui-antipattern-detector",
 
 **⑦ Critical finding 에스컬레이션**: ui-a11y-auditor의 P1 finding은 Review Debate Team(Phase 4.5)에 자동 포함
 
+### Phase 2.7: Boundary Mismatch Detection (Integration Coherence)
+
+> **활성화 조건**: 변경된 파일 중 API route + 프론트엔드 훅/컴포넌트가 함께 존재
+> 경계면 불일치는 개별 파일 리뷰로는 발견 불가 — **양쪽을 동시에 읽어야** 잡힘
+
+**검증 방법: "양쪽 동시 읽기"**
+
+반드시 **생산자와 소비자 코드를 동시에** Read하여 교차 비교한다.
+
+| 검증 영역 | 생산자 (왼쪽) | 소비자 (오른쪽) | 검증 내용 |
+|----------|-------------|---------------|----------|
+| API ↔ 훅 타입 | route의 Response.json() shape | hooks의 fetch\<T\> 타입 | shape 일치, 래핑 unwrap, case 변환 |
+| 라우팅 정합성 | src/app/ page 파일 경로 | href, router.push 값 | 경로 매칭, route group 처리, 동적 세그먼트 |
+| 상태 전이 | STATE_TRANSITIONS 맵 | .update({ status }) 코드 | 죽은 전이, 무단 전이, 중간→최종 누락 |
+| 데이터 흐름 | DB 스키마 필드명 | API 응답 → 프론트 타입 | 필드명 일치, optional 처리 일관성 |
+
+**실행 방식 — 변경 파일 기반 자동 판별:**
+
+```text
+1. git diff에서 API route 파일과 대응 프론트 파일을 짝으로 매칭
+2. 짝이 있는 경우 → 아래 4개 검증 실행
+3. 짝이 없는 경우 (API만 또는 프론트만 변경) → "대응 파일 미변경" 경고 후 스킵
+```
+
+**검증 체크리스트:**
+
+- [ ] API 응답 shape과 대응 훅의 제네릭 타입이 일치
+- [ ] 래핑된 응답(`{ items: [...] }`)은 훅에서 unwrap하는지 확인
+- [ ] snake_case ↔ camelCase 변환이 일관되게 적용
+- [ ] 모든 API 엔드포인트에 대응하는 프론트 훅이 존재하고 실제 호출됨
+- [ ] 코드 내 모든 href/router.push 값이 실제 page 파일 경로와 매칭
+- [ ] 정의된 모든 상태 전이가 코드에서 실행됨 (죽은 전이 없음)
+- [ ] 프론트에서 상태 기반 분기의 값이 실제 도달 가능한 상태
+- [ ] DB 필드명 → API 응답 필드명 → 프론트 타입 정의 간 매핑 일관
+
+**Findings 분류:**
+- 경계면 불일치 → **P1** (런타임 에러의 주요 원인)
+- 대응 파일 미존재 (API 있으나 훅 없음) → **P2**
+- case 변환 비일관성 → **P2**
+
 ### Phase 3: Deep Analysis
 
 After agent results:
@@ -408,6 +477,16 @@ P2 Important:
 
 → Manual handling instructions in Phase 6
 
+### Auto-Fix 실패 시 Codex Rescue (Codex 플러그인 활성화 시)
+
+P1/P2 auto-fix **3회 실패** 시, Codex에 위임:
+
+```
+/codex:rescue "Fix {priority} issue: {issue-description}. File: {file-path}"
+```
+
+Codex 수정 완료 후 해당 리뷰 에이전트가 재검증.
+
 ### Phase 6: Todo File Creation (Items Requiring Manual Handling)
 
 Save **remaining** findings to `.claude/vibe/todos/`: