@su-record/vibe 2.7.13 → 2.7.15

package/agents/ui-previewer.md

@@ -1,260 +1,258 @@
----
-description: Preview UI with Gemini image or ASCII art fallback
-argument-hint: "UI description or design folder path"
----
-
-# /vibe.ui
-
-Preview UI from description or design guide folder.
-
-- **Gemini enabled**: Generate actual UI image
-- **Gemini disabled**: ASCII art fallback
-
-## Usage
-
-```
-/vibe.ui "login page"                    # Text description
-/vibe.ui "dashboard" --layout grid       # With layout option
-/vibe.ui ./design/                       # Design guide folder
-/vibe.ui ./mockups/login.html            # Single HTML file
-```
-
-## Process
-
-### 0. Detect Input Type
-
-First, determine if input is:
-
-- **Text description**: Generate UI from description
-- **Folder path**: Read design files and generate UI
-- **File path**: Read single file and generate UI
-
-**Detection logic:**
-
-```
-if (input starts with "./" or "/" or contains "/" or "\") → path
-else → text description
-```
-
-### 1. If Folder/File Path: Read Design Files
-
-**Supported file formats:**
-
-| Format | Purpose | How to read |
-| ------ | ------- | ----------- |
-| `*.html` | HTML mockups/prototypes | Read and parse structure |
-| `*.md` | Design guide documents | Read content |
-| `*.json` | Design tokens, theme config | Parse JSON |
-| `*.css` / `*.scss` | Style variables, colors | Extract variables |
-| `*.png` / `*.jpg` / `*.webp` | UI screenshots, mockups | **Use Read tool** (multimodal) |
-| `*.svg` | Icons, vector graphics | Read as XML |
-| `*.figma.json` | Figma export | Parse components |
-
-**Reading images:**
-
-Claude can read images using the Read tool. When encountering image files:
-
-1. Use Read tool to view the image
-2. Analyze UI structure, colors, layout from the image
-3. Extract component hierarchy
-
-**Folder scanning priority:**
-
-1. `*.html` files first (main structure)
-2. `*.png` / `*.jpg` images (visual reference)
-3. `*.json` (design tokens)
-4. `*.css` / `*.scss` (styles)
-5. `*.md` (documentation)
-
-**Example folder structure:**
-
-```
-design/
-├── mockup.html          # Main HTML mockup
-├── screenshot.png       # UI screenshot
-├── tokens.json          # Design tokens
-├── variables.css        # CSS variables
-└── style-guide.md       # Documentation
-```
-
-### 2. Analyze UI (from description or files)
-
-Analyze the UI structure:
-
-- Page/component name
-- Required UI elements (buttons, inputs, cards, etc.)
-- Layout structure (header-footer, sidebar, grid, etc.)
-- **Colors and typography** (from design tokens/CSS)
-- **Component hierarchy** (from HTML/images)
-
-### 3. Check Gemini Status and Generate
-
-**Check Gemini authentication:**
-
-```bash
-vibe gemini status
-```
-
-Or check config file: `~/.config/vibe/gemini.json`
-
-#### If Gemini Enabled: Generate UI Image + Code
-
-##### A. UI Mockup Image Generation
-
-```bash
-node "[LLM_SCRIPT]" gemini image "Modern UI mockup: [UI Description from step 2]. Clean design, [colors/typography if available], mobile-first responsive layout" --output "./ui-preview.png"
-```
-
-##### B. UI Code Generation (from design files)
-
-When design files (image/HTML/folder) are provided, use Gemini to generate production-ready component code:
-
-```bash
-node "[LLM_SCRIPT]" gemini orchestrate "You are a UI code generator. Analyze the provided design and generate production-ready React TypeScript components with Tailwind CSS. Output complete component code with proper types, responsive layout, and accessibility attributes."
-```
-
-Pass the design context (file contents, extracted colors, layout structure from step 2) as the user prompt via stdin or arguments.
-
-**When to use each:**
-
-| Input | Image (Step A) | Code (Step B) |
-| ----- | -------------- | ------------- |
-| Text description | Generate mockup | Skip |
-| Image/HTML/Folder | Generate mockup | Generate component code |
-
-#### If Gemini Disabled: ASCII Art Fallback
-
-Generate ASCII art based on the UI description:
-
-**Input format:**
-
-- Page name
-- Layout type (centered, sidebar, grid, header-footer)
-- Components list (type, label, position)
-
-**Example ASCII output:**
-
-```
-┌─────────────────────────────────────────┐
-│               Welcome                    │
-├─────────────────────────────────────────┤
-│                                          │
-│         ┌─────────────────────┐          │
-│  Email: │                     │          │
-│         └─────────────────────┘          │
-│                                          │
-│         ┌─────────────────────┐          │
-│  Pass:  │                     │          │
-│         └─────────────────────┘          │
-│                                          │
-│         ┌─────────────────────┐          │
-│         │       Login         │          │
-│         └─────────────────────┘          │
-│                                          │
-└─────────────────────────────────────────┘
-```
-
-### 4. Generate Component List
-
-Suggest list of components needed for UI:
-
-**Required Components:**
-
-- `Header.tsx` - Header ("Welcome")
-- `LoginForm.tsx` - Form container
-- `Input.tsx` - Reusable input field
-- `Button.tsx` - Login button
-
-**Expected File Structure:**
-
-```
-src/
-├── components/
-│   ├── common/
-│   │   ├── Input.tsx
-│   │   └── Button.tsx
-│   └── auth/
-│       ├── Header.tsx
-│       └── LoginForm.tsx
-└── pages/
-    └── LoginPage.tsx
-```
-
-## Example (with Gemini)
-
-```
-User: /vibe.ui ./design/dashboard/
-
-Claude: Reading design folder...
-  - Found: mockup.png, tokens.json, style-guide.md
-
-Analyzing design files...
-  - Layout: Sidebar + Main content
-  - Colors: Primary #2F6BFF, Background #F5F5F5
-  - Components: Header, Sidebar, 3 StatCards, Footer
-
-Generating UI mockup with Gemini...
-
-✅ UI Preview generated: ./ui-preview-1706234567.png
-
-[Image displayed]
-
-**Component Breakdown:**
-1. Header (logo, user menu)
-2. Sidebar (navigation)
-3. StatsCard (reusable card)
-4. Footer (copyright, links)
-5. DashboardLayout (overall layout)
-
-Next step: /vibe.spec "dashboard page"
-```
-
-## Example (ASCII Fallback)
-
-```
-User: /vibe.ui "Dashboard page - header, sidebar, main content (3 cards), footer"
-
-Claude: Gemini not configured. Using ASCII preview...
-
-┌────────────────────────────────────────────────────────┐
-│  [Logo]  Dashboard                    [User] [Logout]  │
-├────────┬───────────────────────────────────────────────┤
-│        │                                               │
-│ Home   │  ┌──────────┐ ┌──────────┐ ┌──────────┐      │
-│ Stats  │  │  Card 1  │ │  Card 2  │ │  Card 3  │      │
-│ Users  │  │          │ │          │ │          │      │
-│ Settings│  │  100     │ │  200     │ │  50      │      │
-│        │  └──────────┘ └──────────┘ └──────────┘      │
-│        │                                               │
-│        │                                               │
-├────────┴───────────────────────────────────────────────┤
-│  © 2025 Company                    Privacy | Terms    │
-└────────────────────────────────────────────────────────┘
-
-**Required Components:**
-1. Header (logo, user menu)
-2. Sidebar (navigation)
-3. StatsCard (reusable card)
-4. Footer (copyright, links)
-5. DashboardLayout (overall layout)
-
-**Layout Structure:**
-- Layout: sidebar (fixed left)
-- Main: grid (3 columns)
-- Responsive: Changes to 1 column on mobile
-
-💡 Tip: Run `vibe gemini auth` for actual UI image generation
-
-Next step: /vibe.spec "dashboard page"
-```
-
-## Notes
-
-- For complex UI, request in multiple parts
-- Layout options: `sidebar`, `header-footer`, `grid`, `centered`, `split`
-- Gemini generates high-quality mockups; ASCII is for quick visualization
-- Design folder input extracts colors, typography, and component structure automatically
-
----
-
-ARGUMENTS: $ARGUMENTS
+---
+description: Preview UI with Gemini image or ASCII art fallback
+argument-hint: "UI description or design folder path"
+---
+
+# /vibe.ui
+
+Preview UI from description or design guide folder.
+
+- **Gemini enabled**: Generate actual UI image
+- **Gemini disabled**: ASCII art fallback
+
+## Usage
+
+```
+/vibe.ui "login page"                    # Text description
+/vibe.ui "dashboard" --layout grid       # With layout option
+/vibe.ui ./design/                       # Design guide folder
+/vibe.ui ./mockups/login.html            # Single HTML file
+```
+
+## Process
+
+### 0. Detect Input Type
+
+First, determine if input is:
+
+- **Text description**: Generate UI from description
+- **Folder path**: Read design files and generate UI
+- **File path**: Read single file and generate UI
+
+**Detection logic:**
+
+```
+if (input starts with "./" or "/" or contains "/" or "\") → path
+else → text description
+```
+
+### 1. If Folder/File Path: Read Design Files
+
+**Supported file formats:**
+
+| Format | Purpose | How to read |
+| ------ | ------- | ----------- |
+| `*.html` | HTML mockups/prototypes | Read and parse structure |
+| `*.md` | Design guide documents | Read content |
+| `*.json` | Design tokens, theme config | Parse JSON |
+| `*.css` / `*.scss` | Style variables, colors | Extract variables |
+| `*.png` / `*.jpg` / `*.webp` | UI screenshots, mockups | **Use Read tool** (multimodal) |
+| `*.svg` | Icons, vector graphics | Read as XML |
+| `*.figma.json` | Figma export | Parse components |
+
+**Reading images:**
+
+Claude can read images using the Read tool. When encountering image files:
+
+1. Use Read tool to view the image
+2. Analyze UI structure, colors, layout from the image
+3. Extract component hierarchy
+
+**Folder scanning priority:**
+
+1. `*.html` files first (main structure)
+2. `*.png` / `*.jpg` images (visual reference)
+3. `*.json` (design tokens)
+4. `*.css` / `*.scss` (styles)
+5. `*.md` (documentation)
+
+**Example folder structure:**
+
+```
+design/
+├── mockup.html          # Main HTML mockup
+├── screenshot.png       # UI screenshot
+├── tokens.json          # Design tokens
+├── variables.css        # CSS variables
+└── style-guide.md       # Documentation
+```
+
+### 2. Analyze UI (from description or files)
+
+Analyze the UI structure:
+
+- Page/component name
+- Required UI elements (buttons, inputs, cards, etc.)
+- Layout structure (header-footer, sidebar, grid, etc.)
+- **Colors and typography** (from design tokens/CSS)
+- **Component hierarchy** (from HTML/images)
+
+### 3. Check Gemini Status and Generate
+
+**Check Gemini authentication:**
+
+```bash
+vibe gemini status
+```
+
+#### If Gemini Enabled: Generate UI Image + Code
+
+##### A. UI Mockup Image Generation
+
+```bash
+node "[LLM_SCRIPT]" gemini image "Modern UI mockup: [UI Description from step 2]. Clean design, [colors/typography if available], mobile-first responsive layout" --output "./ui-preview.png"
+```
+
+##### B. UI Code Generation (from design files)
+
+When design files (image/HTML/folder) are provided, use Gemini to generate production-ready component code:
+
+```bash
+node "[LLM_SCRIPT]" gemini orchestrate "You are a UI code generator. Analyze the provided design and generate production-ready React TypeScript components with Tailwind CSS. Output complete component code with proper types, responsive layout, and accessibility attributes."
+```
+
+Pass the design context (file contents, extracted colors, layout structure from step 2) as the user prompt via stdin or arguments.
+
+**When to use each:**
+
+| Input | Image (Step A) | Code (Step B) |
+| ----- | -------------- | ------------- |
+| Text description | Generate mockup | Skip |
+| Image/HTML/Folder | Generate mockup | Generate component code |
+
+#### If Gemini Disabled: ASCII Art Fallback
+
+Generate ASCII art based on the UI description:
+
+**Input format:**
+
+- Page name
+- Layout type (centered, sidebar, grid, header-footer)
+- Components list (type, label, position)
+
+**Example ASCII output:**
+
+```
+┌─────────────────────────────────────────┐
+│               Welcome                    │
+├─────────────────────────────────────────┤
+│                                          │
+│         ┌─────────────────────┐          │
+│  Email: │                     │          │
+│         └─────────────────────┘          │
+│                                          │
+│         ┌─────────────────────┐          │
+│  Pass:  │                     │          │
+│         └─────────────────────┘          │
+│                                          │
+│         ┌─────────────────────┐          │
+│         │       Login         │          │
+│         └─────────────────────┘          │
+│                                          │
+└─────────────────────────────────────────┘
+```
+
+### 4. Generate Component List
+
+Suggest list of components needed for UI:
+
+**Required Components:**
+
+- `Header.tsx` - Header ("Welcome")
+- `LoginForm.tsx` - Form container
+- `Input.tsx` - Reusable input field
+- `Button.tsx` - Login button
+
+**Expected File Structure:**
+
+```
+src/
+├── components/
+│   ├── common/
+│   │   ├── Input.tsx
+│   │   └── Button.tsx
+│   └── auth/
+│       ├── Header.tsx
+│       └── LoginForm.tsx
+└── pages/
+    └── LoginPage.tsx
+```
+
+## Example (with Gemini)
+
+```
+User: /vibe.ui ./design/dashboard/
+
+Claude: Reading design folder...
+  - Found: mockup.png, tokens.json, style-guide.md
+
+Analyzing design files...
+  - Layout: Sidebar + Main content
+  - Colors: Primary #2F6BFF, Background #F5F5F5
+  - Components: Header, Sidebar, 3 StatCards, Footer
+
+Generating UI mockup with Gemini...
+
+✅ UI Preview generated: ./ui-preview-1706234567.png
+
+[Image displayed]
+
+**Component Breakdown:**
+1. Header (logo, user menu)
+2. Sidebar (navigation)
+3. StatsCard (reusable card)
+4. Footer (copyright, links)
+5. DashboardLayout (overall layout)
+
+Next step: /vibe.spec "dashboard page"
+```
+
+## Example (ASCII Fallback)
+
+```
+User: /vibe.ui "Dashboard page - header, sidebar, main content (3 cards), footer"
+
+Claude: Gemini not configured. Using ASCII preview...
+
+┌────────────────────────────────────────────────────────┐
+│  [Logo]  Dashboard                    [User] [Logout]  │
+├────────┬───────────────────────────────────────────────┤
+│        │                                               │
+│ Home   │  ┌──────────┐ ┌──────────┐ ┌──────────┐      │
+│ Stats  │  │  Card 1  │ │  Card 2  │ │  Card 3  │      │
+│ Users  │  │          │ │          │ │          │      │
+│ Settings│  │  100     │ │  200     │ │  50      │      │
+│        │  └──────────┘ └──────────┘ └──────────┘      │
+│        │                                               │
+│        │                                               │
+├────────┴───────────────────────────────────────────────┤
+│  © 2025 Company                    Privacy | Terms    │
+└────────────────────────────────────────────────────────┘
+
+**Required Components:**
+1. Header (logo, user menu)
+2. Sidebar (navigation)
+3. StatsCard (reusable card)
+4. Footer (copyright, links)
+5. DashboardLayout (overall layout)
+
+**Layout Structure:**
+- Layout: sidebar (fixed left)
+- Main: grid (3 columns)
+- Responsive: Changes to 1 column on mobile
+
+💡 Tip: Run `vibe gemini auth` for actual UI image generation
+
+Next step: /vibe.spec "dashboard page"
+```
+
+## Notes
+
+- For complex UI, request in multiple parts
+- Layout options: `sidebar`, `header-footer`, `grid`, `centered`, `split`
+- Gemini generates high-quality mockups; ASCII is for quick visualization
+- Design folder input extracts colors, typography, and component structure automatically
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/commands/vibe.analyze.md

@@ -67,12 +67,15 @@ Read `CLAUDE.md`, `package.json`, `pyproject.toml`, etc. to identify tech stack:
 
 #### 3. Explore Related Code (Parallel Sub-Agents)
 
-**🚨 MANDATORY: 3개 이상의 Task를 병렬로 실행하세요. 순차 실행은 위반입니다.**
+**MANDATORY: Always use explorer sub-agents. Never explore in main session.**
 
-**병렬 탐색 패턴 (한 메시지에 모든 Task 호출):**
+> Why: 3 explorer-low agents return ~600 tokens of summaries to main session.
+> Direct Glob/Grep/Read in main session would add 5-15K tokens of raw file content.
+
+**Parallel exploration (ALL tasks in ONE message):**
 
 ```text
-# 3개 explorer 에이전트 병렬 실행 (single message, multiple tool calls)
+# 3 explorer agents in parallel (single message, multiple tool calls)
 Task(subagent_type="explorer-low", model="haiku",
   prompt="Find all [FEATURE] related API endpoints in this project. List file paths, HTTP methods, routes, and auth requirements.")
 
@@ -83,10 +86,10 @@ Task(subagent_type="explorer-low", model="haiku",
   prompt="Find all [FEATURE] related data models, schemas, and database queries. Document relationships and key fields.")
 ```
 
-**추가 탐색 (프로젝트 규모에 따라):**
+**Additional exploration (scale by project size):**
 
 ```text
-# 대규모 프로젝트 (6+ 관련 파일) — 추가 2개 병렬 실행
+# Large projects (6+ related files) — add 2 more in parallel
 Task(subagent_type="explorer-low", model="haiku",
   prompt="Find all test files related to [FEATURE]. Identify tested vs untested paths.")
 
@@ -94,14 +97,9 @@ Task(subagent_type="explorer-low", model="haiku",
   prompt="Analyze [FEATURE] configuration, environment variables, and external integrations.")
 ```
 
-**결과 종합:**
-- 모든 Task 완료 후 결과를 종합하여 Flow Analysis (Step 4) 진행
-- 탐색 결과 기반으로 관련 파일을 직접 Read하여 상세 분석
-
-**Fallback (direct tools — 소규모 프로젝트):**
-1. **Glob** to collect related file list
-2. **Grep** to locate code by keyword
-3. **Read** to analyze key files in detail
+**After all agents return:**
+- Synthesize results → proceed to Flow Analysis (Step 4)
+- Only Read specific files in main session when agent summary needs clarification
 
 #### 4. Flow Analysis
 

package/commands/vibe.review.md

@@ -134,6 +134,36 @@ node "[LLM_SCRIPT]" gemini orchestrate-json --input "[SCRATCHPAD]/review-input.j
 | P2 | Performance issues, architecture violations, missing tests | Fix before merge |
 | P3 | Style, refactoring suggestions, documentation | Add to backlog |
 
+## Convergence Rules (Over-Diagnosis Prevention)
+
+> **Principle**: Reviews must converge. A review that always finds more issues is broken, not thorough.
+
+### Scope Limiting
+
+- **Review ONLY changed files** — based on `git diff --name-only`. Never scan the entire project
+- **If no git diff** (first review) — review only files in the target path
+
+### Severity Filtering by Round
+
+| Round | What to Report |
+|-------|---------------|
+| 1st review | P1 + P2 + P3 (all) |
+| 2nd review (same code) | P1 + P2 only (skip P3) |
+| 3rd+ review | P1 only (report only new P1s) |
+
+### Stop Conditions
+
+- **P1 = 0 means MERGE READY** — mergeable even with remaining P2/P3
+- **P1 = 0 after auto-fix means DONE** — record P2 auto-fix failures as TODO and stop
+- **Final P1 list unchanged after Review Debate → DONE** — no new findings = converged
+
+### Anti-Patterns (FORBIDDEN)
+
+- "All items must be verified" → Only P1 is mandatory, P2/P3 are best-effort
+- "Found one more issue" (repeated) → Only report P1s not mentioned in previous review
+- Forcing code changes for P3 issues → P3 goes to TODO files only, never force code changes
+- Infinite retries on auto-fix failure → max 1 retry then move to TODO
+
 ## Process
 
 ### Phase 1: Tech Stack Detection
@@ -149,6 +179,18 @@ Read go.mod            -> Go
 Read CLAUDE.md         -> Explicit tech stack declaration
 ```
 
+### Phase 1.5: SPEC ↔ Code Alignment Check
+
+> When SPEC files exist, verify that code changes align with the SPEC
+
+```
+1. Search .claude/vibe/specs/ for related SPEC files (based on git diff filenames)
+2. Compare SPEC REQ-* list against functionality in changed code
+3. If functionality added that's not in SPEC → P2 finding: "Feature added without SPEC"
+4. If implementation differs from SPEC → P1 finding: "SPEC ↔ code mismatch"
+5. If no SPEC files exist → Skip (reviews work without SPEC too)
+```
+
 ### Phase 2: Parallel Agent Review (STACK-AWARE) via Orchestrator
 
 **Execution via Orchestrator (12+ agents in parallel):**
@@ -481,7 +523,7 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 
 ### Review Quality Checklist
 
-Before completing review, ALL items must be verified:
+Before completing review, check P1-critical items. P2/P3 items are best-effort:
 
 | Category | Check Item | Weight |
 |----------|------------|--------|