@su-record/vibe 0.1.4 → 0.2.0

package/README.md

@@ -15,6 +15,7 @@ Transform natural language requirements into production-ready code through struc
 
 - **Claude Code Optimized**: Built specifically for Claude Code with native slash commands and MCP integration
 - **SPEC-driven Development**: Structured Q&A process using EARS (Easy Approach to Requirements Syntax)
+- **BDD + Contract Testing**: AI-optimized testing with Gherkin features and API contract validation (🚧 v0.2.0)
 - **Automated Planning**: Generate technical implementation plans with architecture, cost analysis, and timeline
 - **Task Decomposition**: Break down features into phase-based, dependency-aware tasks
 - **Powered by @su-record/hi-ai**: 38 MCP tools combining skills and hi-ai for code analysis, quality validation, and insights
@@ -30,87 +31,75 @@ npm install -g @su-record/vibe
 ```
 
 This installs:
-- Vibe CLI commands
+- Vibe CLI (for initialization only)
 - @su-record/hi-ai MCP server (38 development tools)
+- Agents, Skills, Templates for Claude Code
+
+⚠️ **Important**: Vibe is a **Claude Code-exclusive** framework. Terminal commands are limited to `init` only. All development commands are available as **slash commands** within Claude Code.
 
 ---
 
 ## Quick Start
 
+### 1. Initialize Project (Terminal)
+
 ```bash
-# Initialize project (registers MCP server for this project)
+# Option 1: Initialize in existing project
 vibe init
 
-# Create specification through guided Q&A
-vibe spec "push notification settings"
+# Option 2: Create new project
+vibe init my-new-project
+cd my-new-project
+```
 
-# Generate technical plan
-vibe plan "push notification settings"
+This will:
+- Register MCP server for the project directory
+- Create `.vibe/` folder structure
+- Install agents, skills, and templates
 
-# Decompose into tasks
-vibe tasks "push notification settings"
+### 2. Use Slash Commands (Claude Code)
 
-# Implement tasks
-vibe run "Task 1-1"
+Open Claude Code in your project directory and use slash commands:
 
-# Verify implementation
-vibe verify "push notification settings"
+```
+/vibe.spec "push notification settings"
+/vibe.plan "push notification settings"
+/vibe.tasks "push notification settings"
+/vibe.run "Task 1-1"
+/vibe.verify "push notification settings"
 ```
 
 ---
 
 ## Command Reference
 
-### Core Workflow Commands
+### Terminal Commands (Initialization Only)
 
 | Command | Description | Example |
 |---------|-------------|---------|
 | `vibe init` | Initialize Vibe in current project | `vibe init` |
-| `vibe spec <name>` | Create SPEC through 6-question Q&A | `vibe spec "user authentication"` |
-| `vibe plan <name>` | Generate technical implementation plan | `vibe plan "user authentication"` |
-| `vibe tasks <name>` | Break down into executable tasks | `vibe tasks "user authentication"` |
-| `vibe run <task>` | Execute specific task with auto-generated guide | `vibe run "Task 1-1"` |
-| `vibe run --phase <N>` | Execute all tasks in phase N | `vibe run --phase 1` |
-| `vibe run --all` | Execute all tasks sequentially | `vibe run --all` |
-| `vibe verify <name>` | Verify implementation against SPEC | `vibe verify "user authentication"` |
+| `vibe init <name>` | Create new project with Vibe | `vibe init my-app` |
+| `vibe help` | Show help message | `vibe help` |
+
+### Claude Code Slash Commands (Development)
 
-### Analysis & Tools
+#### Core Workflow
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| `vibe analyze` | Comprehensive project analysis | `vibe analyze` |
-| `vibe analyze --code` | Code quality and complexity analysis | `vibe analyze --code` |
-| `vibe analyze --deps` | Dependency and security audit | `vibe analyze --deps` |
-| `vibe analyze --arch` | Architecture and coupling analysis | `vibe analyze --arch` |
-| `vibe ui <description>` | Generate ASCII UI mockup | `vibe ui "login form"` |
-| `vibe diagram` | Generate architecture diagram (Mermaid) | `vibe diagram` |
-| `vibe diagram --er` | Generate ERD diagram | `vibe diagram --er` |
-| `vibe diagram --flow` | Generate flowchart | `vibe diagram --flow` |
-
-### Utility Commands
-
-| Command | Description |
-|---------|-------------|
-| `vibe agents` | List available AI agents |
-| `vibe skills` | List installed skill modules |
-| `vibe help` | Show command help |
+| `/vibe.spec <name>` | Create SPEC through natural conversation (auto-detects project type, suggests tech stack & design) | `/vibe.spec "user authentication"` |
+| `/vibe.plan <name>` | Generate technical implementation plan | `/vibe.plan "user authentication"` |
+| `/vibe.tasks <name>` | Break down into executable tasks | `/vibe.tasks "user authentication"` |
+| `/vibe.run <task>` | Execute specific task with auto-generated guide | `/vibe.run "Task 1-1"` |
+| `/vibe.verify <name>` | Verify implementation against SPEC | `/vibe.verify "user authentication"` |
 
----
-
-## Slash Commands (Claude Code)
+#### Analysis & Tools
 
-Use these commands directly in Claude Code:
-
-| Command | Description |
-|---------|-------------|
-| `/vibe.spec "feature"` | Create specification |
-| `/vibe.plan "feature"` | Generate plan |
-| `/vibe.tasks "feature"` | Generate tasks |
-| `/vibe.run "Task 1-1"` | Execute task |
-| `/vibe.verify "feature"` | Verify implementation |
-| `/vibe.analyze` | Analyze project |
-| `/vibe.ui "description"` | Preview UI |
-| `/vibe.diagram --er` | Generate diagram |
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/vibe.analyze` | Comprehensive project analysis | `/vibe.analyze` |
+| `/vibe.ui <description>` | Generate ASCII UI mockup | `/vibe.ui "login form"` |
+| `/vibe.diagram --er` | Generate diagrams (architecture, ERD, flow) | `/vibe.diagram --er` |
 
 ---
 
@@ -246,71 +235,145 @@ Vibe uses EARS (Easy Approach to Requirements Syntax):
 
 ## Workflow Example
 
-### 1. Create Specification
+### 1. Initialize Project (Terminal)
 
 ```bash
-$ vibe spec "push notification settings"
+$ vibe init
+🔧 MCP 서버 확인 중...
+✅ vibe MCP 서버 등록 완료
+✅ vibe 초기화 완료!
+
+생성된 구조:
+  .vibe/
+  ├── config.json
+  ├── constitution.md
+  ├── specs/          # SPEC documents (EARS format)
+  ├── features/       # BDD Feature files (Gherkin)
+  ├── plans/          # Technical plans
+  └── tasks/          # Task breakdowns
+```
+
+### 2. Create Specification (Claude Code)
 
-Q1. Why: Reduce app churn from excessive notifications
-Q2. Who: All users (100k+ DAU)
-Q3. What: 6-category notification toggle system
-Q4. How: P95 < 500ms, Redis caching, rate limiting
-Q5. When: 3 days (24 hours development time)
-Q6. With What: FastAPI + Flutter + PostgreSQL + FCM
+**Note**: Examples shown in English. Claude responds in the language set in `.vibe/config.json` (default: Korean).
 
-✅ Created: .vibe/specs/push-notification-settings.md
 ```
+User: /vibe.spec "push notification settings"
 
-### 2. Generate Plan
+Claude (Specification Agent):
+[Analyzing source code]
+- Backend: Python (FastAPI)
+- Frontend: Flutter 3.24+
+- Database: PostgreSQL 17
 
-```bash
-$ vibe plan "push notification settings"
+Existing project detected! Is this tech stack correct?
+
+User: Yes
+
+Claude:
+What types of notifications do you want to manage?
+
+User: Comments, likes, follows, announcements, events, marketing
+
+Claude:
+Do you need just ON/OFF toggle for each category, or detailed settings too?
+
+1. ON/OFF only
+2. Detailed settings (time, frequency, etc.)
+3. Both
+
+Or you can describe directly.
+
+User: 1
+
+Claude:
+Which push notification service would you like to use?
+
+1. Firebase Cloud Messaging (FCM) - Free, easy Flutter integration
+2. OneSignal - Multi-platform, dashboard
+3. Custom implementation
+
+Or you can describe directly.
+
+User: We're already using FCM
+
+Claude:
+Great! Which design reference would you like to follow?
+
+1. iOS Settings > Notifications (toggle + grouping)
+2. Slack notification settings (category-based)
+3. Twitter notification settings (simple list)
+
+Or you can describe directly.
+
+User: 1
+
+...
+
+✅ SPEC document created!
+📄 .vibe/specs/push-notification-settings.md
+📄 .vibe/features/push-notification-settings.feature (BDD scenarios)
+```
+
+### 3. Generate Plan (Claude Code)
+
+```
+User: /vibe.plan "push notification settings"
+
+Claude (Planning Agent):
+SPEC을 분석하여 기술 계획을 작성하겠습니다.
 
-✅ Created: .vibe/plans/push-notification-settings.md
+✅ PLAN 문서 작성 완료!
+📄 .vibe/plans/push-notification-settings.md
 
 Summary:
 - 3 Phases: Backend → Frontend → FCM Integration
-- Timeline: 24 hours (3 days)
+- Timeline: 28 hours (3.5 days)
 - Cost: +$0.50/month (Redis + FCM)
-- Stack Reuse: 100% existing infrastructure
+- Testing: BDD (pytest-bdd) + Contract Testing (Pact)
 ```
 
-### 3. Decompose Tasks
+### 4. Decompose Tasks (Claude Code)
 
-```bash
-$ vibe tasks "push notification settings"
+```
+User: /vibe.tasks "push notification settings"
+
+Claude (Task Agent):
+PLAN을 기반으로 Task를 생성하겠습니다.
 
-✅ Created: .vibe/tasks/push-notification-settings.md
+✅ TASKS 문서 작성 완료!
+📄 .vibe/tasks/push-notification-settings.md
 
 Task Breakdown:
-- Total: 19 tasks
-- Phase 1 (Backend): 8 tasks
-- Phase 2 (Frontend): 8 tasks
-- Phase 3 (FCM): 3 tasks
-- Dependency graph included
+- Total: 23 tasks
+- Phase 1 (Backend): 9 tasks (includes Contract Provider)
+- Phase 2 (Frontend): 9 tasks (includes Contract Consumer)
+- Phase 3 (Integration): 5 tasks (includes BDD Steps + Contract Verification)
 ```
 
-### 4. Execute Tasks
+### 5. Execute Tasks (Claude Code)
 
-```bash
-$ vibe run "Task 1-1"
+```
+User: /vibe.run "Task 1-1"
 
-Executing: Task 1-1 - Database Migration
+Claude:
+Task 1-1 - Database Migration을 실행하겠습니다.
 
-Steps:
-1. Read task details from .vibe/tasks/push-notification-settings.md
-2. Generate implementation guide: .vibe/guides/task-1-1.md
-3. Execute: Create migration file with 6 columns
-4. Verify: Run `alembic upgrade head`
-5. Update status: ⬜ → ✅
+1. 구현 가이드 생성 (.vibe/guides/task-1-1.md)
+2. Migration 파일 생성
+3. Acceptance Criteria 검증
+4. Task 상태 업데이트
 
 ✅ Task 1-1 completed
 ```
 
-### 5. Code Analysis
+### 6. Code Analysis (Claude Code)
 
-```bash
-$ vibe analyze --code
+```
+User: /vibe.analyze
+
+Claude:
+프로젝트 전체를 분석하겠습니다.
 
 📊 Code Quality Report
 
@@ -325,15 +388,14 @@ Recommendations:
 1. Refactor src/service.py into 3 modules
 2. Apply Dependency Injection pattern
 3. Extract unrelated utilities from src/utils.py
-
-Report saved: .vibe/reports/analysis-2025-11-17.md
 ```
 
-### 6. UI Mockup
+### 7. UI Mockup (Claude Code)
 
-```bash
-$ vibe ui "login form with email, password, and submit button"
+```
+User: /vibe.ui "login form"
 
+Claude:
 ┌─────────────────────────────────────────┐
 │            Welcome Back                  │
 ├─────────────────────────────────────────┤
@@ -353,11 +415,61 @@ $ vibe ui "login form with email, password, and submit button"
 └─────────────────────────────────────────┘
 
 Required Components:
-- Header.tsx (Welcome message)
-- EmailInput.tsx (Email field)
-- PasswordInput.tsx (Password field with masking)
-- Button.tsx (Submit button)
-- LoginForm.tsx (Form container)
+- EmailInput.tsx, PasswordInput.tsx, Button.tsx
+```
+
+---
+
+## BDD & Contract Testing Workflow
+
+Vibe integrates BDD (Behavior-Driven Development) and Contract Testing throughout the development lifecycle:
+
+### Workflow Overview
+
+```
+/vibe.spec "feature"
+  ↓ Generates SPEC (EARS) + Feature file (Gherkin)
+
+/vibe.plan "feature"
+  ↓ Analyzes Feature file, selects BDD tools (pytest-bdd, Pact, etc.)
+
+/vibe.tasks "feature"
+  ↓ Creates Contract Testing tasks (Provider, Consumer, Verification)
+
+/vibe.run "Task X-Y"
+  ↓ Implements test-first (Contract → Step Definitions → Code)
+
+/vibe.verify "feature"
+  ↓ Validates BDD Scenarios + Contract Tests
+```
+
+### Generated Files
+
+- **`.vibe/features/{feature}.feature`** - Gherkin scenarios (Given-When-Then)
+- **`tests/steps/`** - BDD step definitions
+- **`pacts/` or `contracts/`** - Contract test files (Provider/Consumer)
+
+### Testing Tools by Language
+
+| Language | BDD Tool | Contract Testing |
+|----------|----------|------------------|
+| Python | pytest-bdd, behave | Pact Python |
+| JavaScript/TS | cucumber, jest-cucumber | Pact JS |
+| Java/Kotlin | Cucumber JVM | Pact JVM, Spring Cloud Contract |
+| Dart/Flutter | gherkin, flutter_gherkin | Pact Dart |
+
+### Example Feature File
+
+```gherkin
+Feature: Push Notification Settings
+
+  Scenario: User enables comment notifications
+    Given the user is logged in
+    And the notification settings page is displayed
+    When the user toggles "Comments" notification to ON
+    Then the setting should be saved successfully
+    And the API should return status 200
+    And the response time should be less than 500ms
 ```
 
 ---
@@ -370,16 +482,16 @@ Create `CLAUDE.md` in your project root to enable automatic tech stack detection
 
 ### 2. Execute Phase by Phase
 
-Instead of `--all`, execute and verify each phase independently:
+Execute and verify each phase independently in Claude Code:
 
-```bash
-vibe run --phase 1  # Backend development
+```
+/vibe.run --phase 1  # Backend development
 # Verify, test, commit
 
-vibe run --phase 2  # Frontend development
+/vibe.run --phase 2  # Frontend development
 # Verify, test, commit
 
-vibe run --phase 3  # Integration
+/vibe.run --phase 3  # Integration
 # Verify, test, commit
 ```
 
@@ -389,12 +501,12 @@ Each task includes acceptance criteria. Ensure all criteria pass before marking
 
 ### 4. Leverage MCP Tools
 
-Use analysis commands before refactoring:
+Use analysis commands in Claude Code before refactoring:
 
-```bash
-vibe analyze --code      # Identify complexity hotspots
-vibe analyze --deps      # Check for outdated/vulnerable packages
-vibe analyze --arch      # Detect circular dependencies
+```
+/vibe.analyze --code      # Identify complexity hotspots
+/vibe.analyze --deps      # Check for outdated/vulnerable packages
+/vibe.analyze --arch      # Detect circular dependencies
 ```
 
 ---