@su-record/vibe 2.2.2 → 2.2.3

package/commands/vibe.setup.md

@@ -0,0 +1,97 @@
+# /vibe.setup
+
+vibe 플러그인 MCP 서버 설정
+
+---
+
+## 실행 절차
+
+### 1. 현재 MCP 서버 상태 확인
+
+```bash
+claude mcp list
+```
+
+### 2. context7 설정 (필수)
+
+context7이 없으면 설치:
+
+```bash
+claude mcp add context7 -- npx -y @anthropic/context7-mcp@latest
+```
+
+### 3. GPT 설정 (선택)
+
+GPT 연동이 필요하면:
+
+```bash
+# 1. vibe-gpt MCP 서버 추가
+claude mcp add vibe-gpt -- npx -y @anthropic/vibe-gpt-mcp@latest
+
+# 2. OAuth 인증 (브라우저 열림)
+# 첫 사용 시 자동으로 인증 페이지로 이동
+```
+
+**용도:**
+- security-advisory-agent: CVE/보안 취약점 DB 지식 보강
+- python-reviewer: Python 코드 리뷰 2nd opinion
+
+### 4. Gemini 설정 (선택)
+
+Gemini 연동이 필요하면:
+
+```bash
+# 1. vibe-gemini MCP 서버 추가
+claude mcp add vibe-gemini -- npx -y @anthropic/vibe-gemini-mcp@latest
+
+# 2. OAuth 인증 (브라우저 열림)
+# 첫 사용 시 자동으로 인증 페이지로 이동
+```
+
+**용도:**
+- framework-docs-agent: context7 문서 부재 시 웹 검색으로 최신 문서 보강
+
+---
+
+## 설정 확인
+
+설정 후 확인:
+
+```bash
+claude mcp list
+```
+
+예상 출력:
+```
+context7: connected
+vibe-gpt: connected (optional)
+vibe-gemini: connected (optional)
+```
+
+---
+
+## 문제 해결
+
+### MCP 서버 연결 실패
+
+```bash
+# 서버 제거 후 재등록
+claude mcp remove context7
+claude mcp add context7 -- npx -y @anthropic/context7-mcp@latest
+```
+
+### OAuth 인증 만료
+
+```bash
+# 인증 갱신 (해당 MCP 도구 호출 시 자동 갱신)
+```
+
+---
+
+## 참고
+
+- GPT/Gemini 없이도 vibe는 정상 작동합니다
+- 외부 LLM은 특정 에이전트의 보조 역할만 수행
+- context7만 있어도 대부분의 기능 사용 가능
+
+ARGUMENTS: $ARGUMENTS

package/commands/vibe.spec.md

@@ -0,0 +1,383 @@
+---
+description: Create SPEC document with Specification Agent
+argument-hint: "feature name"
+---
+
+# /vibe.spec
+
+Create a SPEC document (Specification Agent).
+
+## Usage
+
+```
+/vibe.spec "feature-name"
+```
+
+## Rules Reference
+
+**Must follow `.claude/vibe/rules/`:**
+- `core/development-philosophy.md` - Surgical precision, simplicity
+- `core/quick-start.md` - Korean first, DRY, SRP
+- `core/communication-guide.md` - Communication principles
+
+## Description
+
+Collect requirements through conversation with the user and create an **AI-executable PTCF structured SPEC document**.
+
+> **PTCF**: Persona, Task, Context, Format - Google Gemini prompt optimization framework
+
+## External LLM Integration (Optional)
+
+When external LLMs are enabled in `.claude/vibe/config.json`, automatically utilize during SPEC creation:
+
+```
+/vibe.spec "complex feature"
+      ↓
+[Claude Opus] Create SPEC draft
+      ↓
+[GPT enabled?] → Cross-review design via MCP(vibe-gpt)
+      ↓
+[Gemini enabled?] → UI/UX consultation via MCP(vibe-gemini)
+      ↓
+[Claude] Finalize SPEC
+```
+
+| External LLM | Role | When Used |
+|--------------|------|-----------|
+| GPT 5.2 | Architecture/design review | After SPEC draft completion |
+| Gemini 3 | UI/UX consultation | During design reference discussion |
+
+**Activation:**
+```bash
+vibe gpt <api-key>      # Enable GPT
+vibe gemini <api-key>   # Enable Gemini
+vibe status             # Check current settings
+```
+
+## Process
+
+### 1. Project Analysis
+
+**Existing project** (`vibe init`):
+- Source code analysis: `package.json`, `pyproject.toml`, `pubspec.yaml`, `go.mod`, etc.
+- Reference `CLAUDE.md` file (tech stack)
+- Infer framework from file structure
+
+**New project** (`vibe init <project-name>`):
+- Suggest tech stack (2-3 options)
+
+### 2. Collect Requirements via Conversation
+
+**Principles:**
+- Ask **one question at a time**
+- Present options **with numbers** + "Feel free to describe in your own words"
+- **Natural conversation** without fixed order
+
+**Required confirmations:**
+- Purpose (Why): Why is it needed?
+- User (Who): Who will use it?
+- Feature scope (What): What features are needed?
+- Tech stack: Confirm existing stack or suggest new
+- Design reference: UI/UX to reference
+
+### 3. Parallel Research (v2.1.0) - Run AFTER requirements confirmed
+
+**⚠️ IMPORTANT: Research starts ONLY after requirements are confirmed via Q&A**
+
+Requirements confirmed when:
+- Feature type decided (e.g., "passkey authentication")
+- Tech stack confirmed (e.g., "React + Supabase")
+- Core requirements collected
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🔍 PARALLEL RESEARCH AGENTS (After requirements confirmed)     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Task 1: best-practices-agent                                   │
+│  └── Best practices for [confirmed feature] + [confirmed stack] │
+│                                                                 │
+│  Task 2: framework-docs-agent                                   │
+│  └── Latest docs for [confirmed stack] (via context7)           │
+│                                                                 │
+│  Task 3: codebase-patterns-agent                                │
+│  └── Analyze similar patterns in existing codebase              │
+│                                                                 │
+│  Task 4: security-advisory-agent                                │
+│  └── Security advisories for [confirmed feature]                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Execution (ALL in parallel):**
+```
+# Generate specific prompts based on confirmed requirements
+Task(model: "haiku", subagent_type: "Explore",
+     prompt: "Research best practices for [passkey auth] with [React + Supabase]")
+Task(model: "haiku", subagent_type: "Explore",
+     prompt: "Get Supabase Auth + WebAuthn docs from context7")
+Task(model: "haiku", subagent_type: "Explore",
+     prompt: "Find existing auth patterns in this codebase")
+Task(model: "haiku", subagent_type: "Explore",
+     prompt: "Check OWASP WebAuthn security guidelines")
+```
+
+**Research results are reflected in SPEC's Context section.**
+
+### 4. Write SPEC Document (PTCF Structure)
+
+Create `.claude/vibe/specs/{feature-name}.md`:
+
+```markdown
+# SPEC: {feature-name}
+
+## Persona
+<role>
+Define AI role and expertise for implementation
+- Senior developer on the project
+- Follow existing code patterns
+- Write testable code
+</role>
+
+## Context
+<context>
+### Background
+- Why this feature is needed
+- Who will use it
+
+### Tech Stack
+- Backend: {technology}
+- Frontend: {technology}
+- Database: {technology}
+
+### Related Code
+- `src/xxx/`: Existing implementation to reference
+- `src/yyy/`: Files to modify
+
+### Design Reference
+- {Reference app/service}
+</context>
+
+## Task
+<task>
+### Phase 1: {phase-name}
+1. [ ] {specific task}
+   - File: `path/to/file`
+   - Verify: `command`
+2. [ ] {specific task}
+
+### Phase 2: {phase-name}
+1. [ ] {specific task}
+2. [ ] {specific task}
+
+### Phase 3: Testing and Verification
+1. [ ] Unit Tests
+2. [ ] Integration Tests
+</task>
+
+## Constraints
+<constraints>
+- Follow existing code patterns
+- Localize error messages
+- Separate configuration via environment variables
+- {other constraints}
+</constraints>
+
+## Output Format
+<output_format>
+### Files to Create
+- `path/to/new/file.ts`
+- `path/to/new/file.test.ts`
+
+### Files to Modify
+- `path/to/existing/file.ts`
+
+### Verification Commands
+- `npm test`
+- `npm run build`
+</output_format>
+
+## Acceptance Criteria
+<acceptance>
+- [ ] {verifiable criterion 1}
+- [ ] {verifiable criterion 2}
+- [ ] All tests pass
+- [ ] Build succeeds
+</acceptance>
+```
+
+### 5. Create Feature File (BDD) - Required
+
+**Must** create `.claude/vibe/features/{feature-name}.feature` file.
+
+**Creation rules:**
+1. Convert each SPEC Acceptance Criteria → one Scenario
+2. Include Happy Path (normal case) + Edge Case (exception case)
+3. Follow Given-When-Then format
+
+**Feature structure:**
+```markdown
+# Feature: {feature-name}
+
+**SPEC**: `.claude/vibe/specs/{feature-name}.md`
+
+## User Story
+**As a** {user}
+**I want** {feature}
+**So that** {value}
+
+## Scenarios
+
+### Scenario 1: {Happy Path}
+\`\`\`gherkin
+Scenario: {title}
+  Given {precondition}
+  When {action}
+  Then {result}
+\`\`\`
+**Verification**: SPEC AC #1
+
+### Scenario 2: {Edge Case}
+...
+
+## Coverage
+| Scenario | SPEC AC | Status |
+|----------|---------|--------|
+| 1 | AC-1 | ⬜ |
+```
+
+### 6. Ambiguity Scan - Required
+
+After creating SPEC draft, **must perform systematic ambiguity check**.
+
+**Check categories:**
+
+| Category | Check Items |
+|----------|-------------|
+| **Functional Scope** | Missing features, unclear behavior definitions |
+| **Data Model** | Undefined entities, unclear relationships |
+| **Non-Functional** | Missing performance requirements, security considerations |
+| **Edge Cases** | Boundary conditions, error handling scenarios |
+| **Integration Points** | External system integration, API contracts |
+
+**Check process:**
+
+```
+1. Create SPEC draft
+      ↓
+2. Scan by category for ambiguity
+      ↓
+3. Present list of found ambiguities
+      ↓
+4. Request user clarification
+      ↓
+5. Refine SPEC
+      ↓
+6. Re-check (until 0 ambiguities)
+```
+
+**Ambiguity output format:**
+
+```markdown
+## 🔍 Ambiguity Scan Results
+
+### Functional Scope
+- ⚠️ "Login failure behavior" not defined
+- ⚠️ "Session expiration handling" unclear
+
+### Edge Cases
+- ⚠️ Concurrent login permission undefined
+- ⚠️ No password retry limit specified
+
+Please clarify the above items.
+```
+
+### 7. Quality Validation
+
+Self-evaluate against `.claude/vibe/rules/quality/checklist.md` (0-100 score)
+
+## Output
+
+- `.claude/vibe/specs/{feature-name}.md` - PTCF structured SPEC
+- `.claude/vibe/features/{feature-name}.feature` - BDD Feature file
+- Ambiguity scan results (0 ambiguities confirmed)
+- Quality score and improvement suggestions
+
+## Example
+
+```
+User: /vibe.spec "brick-game"
+
+Claude:
+You're making a brick game! What style are you thinking of?
+
+1. Classic Breakout style
+2. Arkanoid (with power-up items)
+3. Custom style with special gameplay
+
+Feel free to describe in your own words.
+
+User: 1
+
+Claude: What platform will it run on?
+
+1. Web (browser)
+2. Mobile (iOS/Android)
+3. Desktop
+
+User: 1
+
+Claude:
+Here are tech stack suggestions for web game development:
+
+1. **Phaser.js** (Recommended) - Game framework with built-in physics engine
+2. **Canvas + JavaScript** - Lightweight with fine control
+3. **PixiJS + Matter.js** - High-performance rendering
+
+User: 1
+
+Claude: What design style?
+
+1. Retro pixel (Atari Breakout)
+2. Neon graphics (Arkanoid)
+3. Modern 3D effects
+
+User: 2
+
+[Conversation continues...]
+
+Claude: SPEC draft created. Running ambiguity scan.
+
+## 🔍 Ambiguity Scan Results
+
+### Functional Scope
+- ⚠️ Game over condition not defined (ball drop vs lives system)
+- ⚠️ Stage clear condition unclear
+
+### Edge Cases
+- ⚠️ Ball reflection angle when hitting paddle edge
+- ⚠️ Multiple brick collision handling
+
+Please clarify the above items.
+
+User: 3 lives, clear when all bricks destroyed, edge reflects at 45 degrees
+
+Claude: Thank you. SPEC has been refined.
+
+🔍 Re-check result: 0 ambiguities
+
+✅ SPEC document complete!
+📄 .claude/vibe/specs/brick-game.md (PTCF structure)
+📄 .claude/vibe/features/brick-game.feature
+📊 Quality score: 92/100 (A)
+```
+
+## Next Step
+
+```
+/vibe.run "brick-game"
+```
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/commands/vibe.ui.md

@@ -0,0 +1,137 @@
+---
+description: Preview UI with ASCII art
+argument-hint: "UI description"
+---
+
+# /vibe.ui
+
+Preview UI with ASCII art.
+
+## Usage
+
+```
+/vibe.ui "login page"
+/vibe.ui "dashboard" --layout grid
+```
+
+## Process
+
+### 1. Analyze UI Description
+
+Analyze user's requested UI description:
+- Page/component name
+- Required UI elements (buttons, inputs, cards, etc.)
+- Layout structure (header-footer, sidebar, grid, etc.)
+
+### 2. Use MCP Tool
+
+Use `mcp__su-record-hi-ai__preview_ui_ascii` tool to generate ASCII art:
+
+```javascript
+{
+  page_name: "Login Page",
+  layout_type: "centered",
+  components: [
+    { type: "header", label: "Welcome", position: "top" },
+    { type: "input", label: "Email", position: "center" },
+    { type: "input", label: "Password", position: "center" },
+    { type: "button", label: "Login", position: "center" }
+  ]
+}
+```
+
+### 3. Output ASCII Art
+
+Output generated ASCII art:
+
+```
+┌─────────────────────────────────────────┐
+│               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
+
+```
+User: /vibe.ui "Dashboard page - header, sidebar, main content (3 cards), footer"
+
+Claude: Generating dashboard UI 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
+
+Next step:
+  vibe spec "dashboard page"
+```
+
+## Notes
+
+- For complex UI, request in multiple parts
+- Layout options: `sidebar`, `header-footer`, `grid`, `centered`, `split`
+- ASCII art is for quick visualization before actual implementation
+
+---
+
+ARGUMENTS: $ARGUMENTS