Welcome to Vibe 🎯

SPEC-driven AI coding framework with integrated MCP tooling

Vibe transforms natural language requirements into production-ready code through structured specification, planning, and task decomposition. Built specifically for Claude Code with 38 MCP tools.

---

🚀 Quick Links

• Getting Started - Installation and first steps
• Core Concepts - Understanding SPEC-driven development
• Command Reference - Complete CLI command guide
• MCP Integration - 38 built-in development tools
• Agents Guide - 7 specialized AI agents
• Examples - Real-world usage examples
• Best Practices - Tips and recommendations

---

✨ What is Vibe?

Vibe is a SPEC-driven development framework that helps you:

1. 📝 Clarify Requirements - 6-question structured interview using EARS syntax
2. 🗺️ Generate Plans - Automatic technical architecture and timeline
3. ✅ Decompose Tasks - Phase-based, dependency-aware task breakdown
4. 🤖 Execute with AI - 7 specialized agents for different tech stacks
5. 🔍 Validate Quality - 38 MCP tools for code analysis and quality checks

---

🎯 Core Workflow

# 1. Initialize project
vibe init

# 2. Create specification
vibe spec "push notification settings"

# 3. Generate technical plan
vibe plan "push notification settings"

# 4. Break down into tasks
vibe tasks "push notification settings"

# 5. Execute tasks
vibe run "Task 1-1"

# 6. Verify implementation
vibe verify "push notification settings"

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Vibe Framework                        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │   SPEC   │→ │   PLAN   │→ │  TASKS   │→ │   RUN   │ │
│  │  (EARS)  │  │  (Tech)  │  │ (Phases) │  │ (Agent) │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
│       ↓              ↓              ↓            ↓       │
│  ┌──────────────────────────────────────────────────┐   │
│  │           MCP Tools (38 Tools)                   │   │
│  │  • Code Analysis  • Quality Check  • Planning    │   │
│  │  • Memory         • UI Preview     • Thinking    │   │
│  └──────────────────────────────────────────────────┘   │
│       ↓              ↓              ↓            ↓       │
│  ┌──────────────────────────────────────────────────┐   │
│  │        AI Agents (7 Specialized Agents)          │   │
│  │  • Python/FastAPI   • Flutter/Dart               │   │
│  │  • React/Next.js    • PostgreSQL                 │   │
│  │  • Quality Reviewer                              │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
└─────────────────────────────────────────────────────────┘

---

🛠️ Key Features

SPEC-driven Development

• 6-Question Framework: Why, Who, What, How, When, With What
• EARS Syntax: Easy Approach to Requirements Syntax
• Acceptance Criteria: Clear, testable requirements

Automated Planning

• Technical Architecture: Stack decisions and patterns
• Cost Analysis: Infrastructure and timeline estimates
• Risk Assessment: Potential blockers and mitigation

Task Decomposition

• Phase-based: Backend → Frontend → Integration
• Dependency-aware: Automatic dependency graph
• Executable: Each task has clear implementation guide

MCP Integration (38 Tools)

• Code Analysis: Complexity, coupling, cohesion metrics
• Quality Validation: Code scoring and recommendations
• Project Intelligence: Symbol search, reference finding
• Thinking Tools: Step-by-step reasoning chains
• Memory System: Context preservation across sessions

AI Agent System

• 7 Specialized Agents: Language and framework experts
• Auto-detection: Reads CLAUDE.md for tech stack
• Quality Assurance: Dedicated review agent

---

📦 Installation

# Install Vibe globally
npm install -g @su-record/vibe

# Initialize in your project
cd /path/to/your/project
vibe init

This installs:

• ✅ Vibe CLI commands
• ✅ @su-record/hi-ai MCP server (38 tools)
• ✅ Registers MCP per-project on vibe init

Verify installation:

vibe help                # Check CLI
claude mcp list          # Check MCP server (in project directory)

→ Full Installation Guide

---

🎓 Learning Path

Beginners

1. Getting Started - Install and initialize
2. Your First SPEC - Create your first specification
3. Basic Workflow - SPEC → Plan → Tasks → Run

Intermediate

4. Advanced Commands - Analysis, UI, Diagrams
5. MCP Tools Guide - Leverage 38 development tools
6. Configuration - Customize Vibe for your project

Advanced

7. Custom Agents - Create your own agents
8. Integration Patterns - CI/CD and automation
9. Best Practices - Production-grade workflows

---

🌟 Why Vibe?

Traditional Development

Idea → Code → Debug → Realize requirements unclear → Refactor

With Vibe

Idea → SPEC (6 questions) → Plan (verified) → Tasks (clear) → Code (guided)

Benefits:

• ✅ 80% less requirement ambiguity - Structured Q&A catches edge cases
• ✅ 3x faster planning - AI generates technical architecture
• ✅ Clear progress tracking - Phase-based task system
• ✅ Higher code quality - 38 MCP tools for validation
• ✅ Knowledge preservation - Memory system across sessions

---

🤝 Community

• GitHub: su-record/vibe
• Issues: Report bugs or request features
• MCP Server: @su-record/hi-ai (Smithery Popular 🏆)

---

📚 Documentation Sections

• Getting Started - Installation and setup
• Core Concepts - SPEC-driven development explained
• Command Reference - All CLI commands
• MCP Integration - 38 tools detailed guide
• Agents Guide - 7 specialized agents
• Configuration - Config files and options
• Examples - Real-world projects
• Best Practices - Tips and patterns
• Troubleshooting - Common issues and solutions
• FAQ - Frequently asked questions

---

🚀 Next Steps

1. Install Vibe - Get started in 2 minutes
2. Read Core Concepts - Understand the methodology
3. Try an Example - Follow a complete workflow
4. Explore MCP Tools - Discover 38 development tools

---

Built with ❤️ by Su & Claude