Core‐Concepts - su-record/vibe GitHub Wiki

Core Concepts

Understanding the fundamental concepts behind Vibe's SPEC-driven development methodology.

SPEC-driven Development
EARS Syntax
The 6-Question Framework
Task Decomposition
AI Agent System
MCP Integration
Workflow Philosophy

SPEC-driven Development

What is SPEC-driven Development?

SPEC-driven Development is a methodology that puts requirements specification first before writing any code. Instead of diving straight into implementation, you:

Clarify requirements through structured questions
Document them in a machine-readable format (EARS)
Plan technical architecture based on verified requirements
Decompose into executable, testable tasks
Implement with AI assistance
Verify against original specifications

Traditional vs SPEC-driven

Traditional Development	SPEC-driven Development
Idea → Code → Debug → Refactor	Idea → SPEC → Plan → Tasks → Code
Implicit requirements	Explicit EARS syntax
Ad-hoc implementation	Structured phases
Manual quality checks	38 MCP tools for validation
Scope creep common	Acceptance criteria lock scope
Knowledge in developer's head	Knowledge in .vibe/ directory

Benefits

✅ 80% less requirement ambiguity - 6-question framework catches edge cases
✅ 3x faster planning - AI generates technical architecture
✅ Clear progress tracking - Phase-based task system with dependencies
✅ Higher code quality - 38 MCP tools for continuous validation
✅ Knowledge preservation - Everything documented in .vibe/

EARS Syntax

What is EARS?

EARS (Easy Approach to Requirements Syntax) is a structured format for writing requirements that are:

Unambiguous - Clear meaning with no interpretation needed
Testable - Can verify if requirement is met
Traceable - Links to acceptance criteria and tasks

EARS Keywords

Keyword	Meaning	Use Case
WHEN	Trigger condition	User action or system event
WHERE	Precondition	System state or context
IF	Conditional logic	Feature flag or configuration
WHILE	Duration constraint	Ongoing process or background task
THEN	System response	What system SHALL/SHOULD/MAY do
SHALL	Mandatory requirement	Critical feature
SHOULD	Recommended	Nice-to-have feature
MAY	Optional	Future enhancement

EARS Template

### REQ-XXX: Requirement Title

**WHEN** <trigger condition>
**THEN** system SHALL <mandatory action>

#### Acceptance Criteria
- [ ] Criterion 1 (testable)
- [ ] Criterion 2 (testable)
- [ ] Criterion 3 (testable)

#### Priority: HIGH/MEDIUM/LOW
#### Estimated Complexity: 1-5

EARS Examples

Example 1: Simple User Action

### REQ-001: User Login

**WHEN** user submits valid email and password
**THEN** system SHALL:
- Verify credentials against database
- Generate JWT token with 24h expiry
- Redirect to dashboard

#### Acceptance Criteria
- [ ] Invalid credentials show error message
- [ ] JWT token includes user_id and role
- [ ] Token stored in secure httpOnly cookie
- [ ] Login attempt logged in audit table

Example 2: Conditional Logic

### REQ-002: Email Notification

**WHERE** user has email_notifications enabled
**AND** user has not received notification in last 1 hour
**WHEN** user receives a new comment
**THEN** system SHALL send email notification

#### Acceptance Criteria
- [ ] Check user.settings.email_notifications = true
- [ ] Query last_notification_sent timestamp
- [ ] Send email only if 1+ hour passed
- [ ] Update last_notification_sent after send

Example 3: Performance Requirement

### REQ-003: Search Performance

**WHEN** user searches for restaurant by name
**THEN** system SHALL return results within 500ms (P95)

**WHERE** database contains 1M+ restaurants
**THEN** system SHALL use PostgreSQL full-text search with GIN index

#### Acceptance Criteria
- [ ] P95 latency < 500ms (load tested)
- [ ] GIN index on restaurants.name_tsvector
- [ ] Pagination with limit 20 results
- [ ] Cache popular queries in Redis (1h TTL)

The 6-Question Framework

Vibe uses a structured 6-question interview to capture complete requirements.

Q1: Why? (Business Value)

Purpose: Understand the problem and desired outcome

Example:

Current: 15% weekly user churn
Problem: Excessive push notifications
Goal: Reduce churn to <10% by giving users control
ROI: Retain 5,000 users/month = $50k MRR

Good Answers:

Include metrics (current state + target)
Explain business impact (revenue, retention, efficiency)
Reference user pain points

Bad Answers:

"Make the app better" (too vague)
"Because manager said so" (no business case)

Q2: Who? (Users and Scale)

Purpose: Define user personas and system scale

Example:

Primary: All users (100k DAU)
Secondary: Support team (10 people)
Scale: 500k monthly active users
Growth: 20% MoM
Platform: 95% mobile (iOS/Android), 5% web

Good Answers:

Specific user roles
Quantified scale (DAU, MAU, QPS)
Platform breakdown
Growth expectations

Bad Answers:

"Users" (which users?)
"A lot of people" (how many?)

Q3: What? (Features)

Purpose: Enumerate all features and edge cases

Example:

Core Features:
1. 6-category notification toggles:
   - Likes (default: ON)
   - Comments (default: ON)
   - Follows (default: ON)
   - Mentions (default: ON)
   - Feed updates (default: OFF)
   - Marketing (default: OFF)

2. Bulk actions:
   - Enable all
   - Disable all

3. Schedule (future):
   - Quiet hours (10 PM - 8 AM)
   - Weekend mode

Edge Cases:
- What if user disables all? → Show warning modal
- What if toggle fails? → Retry 3x, show error toast
- What about existing users? → Migrate with defaults

Good Answers:

Numbered feature list
Default values specified
Edge cases considered
Future enhancements marked

Bad Answers:

"Notification settings" (not specific enough)
No edge cases mentioned

Q4: How? (Technical Requirements)

Purpose: Define non-functional requirements

Example:

Performance:
- API response: P95 < 500ms
- UI toggle: < 100ms perceived latency

Scalability:
- 100k concurrent users
- 10M settings updates/day

Reliability:
- 99.9% uptime
- Data consistency (eventual is OK)

Security:
- Rate limiting: 100 req/min per user
- Authentication: JWT required
- Audit log: All changes logged

Caching:
- Redis: User settings (1h TTL)
- Invalidate on update

Good Answers:

Specific metrics (P95, P99, QPS)
Infrastructure decisions (Redis, PostgreSQL)
Security constraints
Monitoring and observability

Bad Answers:

"Fast" (how fast?)
"Secure" (what security measures?)

Q5: When? (Timeline)

Purpose: Set realistic deadlines and prioritization

Example:

Development: 24 hours (3 days)
- Phase 1 (Backend): 8 hours
- Phase 2 (Frontend): 8 hours
- Phase 3 (FCM Integration): 4 hours
- Testing & Polish: 4 hours

Launch: December 1, 2025
Priority: HIGH (blocks Q4 OKR)

Dependencies:
- Requires FCM setup (already done)
- Requires PostgreSQL migration (2 hours)

Good Answers:

Broken down by phase
Development + testing time
Priority level
External dependencies

Bad Answers:

"As soon as possible" (not specific)
"1 week" (no breakdown)

Q6: With What? (Tech Stack)

Purpose: Document technology choices and constraints

Example:

Backend:
- Language: Python 3.11
- Framework: FastAPI 0.104+
- Database: PostgreSQL 17 (existing)
- Cache: Redis 7.2 (existing)
- Authentication: JWT (existing)

Frontend:
- Framework: Flutter 3.24+
- State Management: Provider (existing)
- HTTP Client: Dio (existing)

Push Notifications:
- Service: Firebase Cloud Messaging
- Already integrated: Yes

Infrastructure:
- Cloud: GCP Cloud Run (existing)
- CI/CD: GitHub Actions (existing)

New Dependencies:
- None (100% stack reuse)

Good Answers:

Specific versions
Mark existing vs new
Explain technology choices
List new dependencies

Bad Answers:

"Python and React" (no versions)
"Whatever is best" (no decision)

Task Decomposition

Phase-based Structure

Vibe decomposes features into 3 standard phases:

Phase 1: Backend - API, database, business logic
Phase 2: Frontend - UI, state management, API integration
Phase 3: Integration - E2E testing, deployment, monitoring

Task Format

### Task X-Y: Task Title ⬜

**Description**: One-sentence summary

**Implementation**:
1. Step 1 (concrete action)
2. Step 2 (concrete action)
3. Step 3 (concrete action)

**Acceptance Criteria**:
- [ ] Criterion 1 (testable)
- [ ] Criterion 2 (testable)

**Dependencies**: Task X-Z (if any)
**Estimated Time**: N hours
**Files Changed**:
- path/to/file.py (created/modified)

Dependency Graph

Tasks include dependency information for parallel execution:

Phase 1: Backend
├── Task 1-1: Database Migration ⬜ (no deps)
├── Task 1-2: Repository Layer ⬜ (depends on 1-1)
├── Task 1-3: Service Layer ⬜ (depends on 1-2)
├── Task 1-4: API Endpoints ⬜ (depends on 1-3)
└── Task 1-5: Unit Tests ⬜ (depends on 1-4)

# Parallel execution possible:
# - Task 1-1 alone
# - Then Task 1-2
# - Then Task 1-3
# - Then Task 1-4 + 1-5 (parallel)

Task States

Symbol	State	Meaning
⬜	Pending	Not started
🔄	In Progress	Currently working
✅	Done	Completed and verified
❌	Blocked	Cannot proceed (dependency issue)
⚠️	Needs Review	Implementation done, review pending

AI Agent System

Agent Selection

Vibe automatically selects the appropriate agent based on:

CLAUDE.md - Tech stack documentation in project root
Task context - Backend/Frontend/Database/Quality phase
File extensions - .py → Python agent, .dart → Flutter agent

Agent Workflow

User runs: vibe run "Task 1-1"
     ↓
Vibe reads .vibe/tasks/feature-name.md
     ↓
Detects task phase (Backend/Frontend/Integration)
     ↓
Reads CLAUDE.md for tech stack
     ↓
Selects agent (e.g., Backend Python Expert)
     ↓
Agent generates implementation guide
     ↓
Saves to .vibe/guides/task-1-1.md
     ↓
Agent executes with MCP tools
     ↓
Verifies acceptance criteria
     ↓
Updates task status: ⬜ → ✅

7 Specialized Agents

Agent	Tech Stack	Use Cases
Specification Agent	Language-agnostic	Requirements gathering (Q1-Q6)
Planning Agent	Cross-stack	Architecture, cost analysis, timeline
Task Agent	Cross-stack	Task decomposition, dependency graph
Backend Python Expert	Python 3.11+, FastAPI, SQLAlchemy	Python backend implementation
Frontend Flutter Expert	Flutter 3.24+, Dart 3.5+	Flutter mobile/web app
Frontend React Expert	React 18+, Next.js 14+	React web app
Database PostgreSQL Expert	PostgreSQL 17, PostGIS 3.4+	Database design, migrations
Quality Reviewer	Multi-language	Code review, quality validation

MCP Integration

What is MCP?

MCP (Model Context Protocol) is a standard for AI tools to access development utilities. Vibe includes 38 MCP tools across 7 categories.

Tool Categories

1. Code Analysis (5 tools)

analyze_complexity - Cyclomatic and cognitive complexity
validate_code_quality - Code scoring and recommendations
check_coupling_cohesion - Module coupling analysis
suggest_improvements - Refactoring suggestions
apply_quality_rules - Enforce coding standards

2. Project Intelligence (2 tools)

find_symbol - Locate function/class definitions
find_references - Find all usages of symbols

3. Thinking & Planning (6 tools)

create_thinking_chain - Step-by-step reasoning
step_by_step_analysis - Detailed problem breakdown
analyze_problem - Structured problem analysis
break_down_problem - Decompose complex problems
think_aloud_process - Explain reasoning
format_as_plan - Convert analysis to plan

4. Memory & Context (8 tools)

save_memory - Store project context
recall_memory - Retrieve stored information
search_memories - Search by keyword
update_memory - Modify existing memory
delete_memory - Remove outdated memory
list_memories - View all stored memories
auto_save_context - Automatic checkpointing
start_session - Begin new session

5. UI & Design (1 tool)

preview_ui_ascii - Generate ASCII UI mockups

6. Requirements & Planning (4 tools)

analyze_requirements - Extract requirements from text
create_user_stories - Generate user stories
feature_roadmap - Generate feature timeline
generate_prd - Create Product Requirements Document

7. Prompt Engineering (2 tools)

analyze_prompt - Evaluate prompt quality
enhance_prompt - Improve prompt effectiveness

How Agents Use MCP Tools

# Example: Backend Python Expert uses MCP tools

# Step 1: Analyze existing code
complexity = mcp.analyze_complexity("src/service.py")
if complexity.cyclomatic > 10:
    suggestions = mcp.suggest_improvements("src/service.py")

# Step 2: Find related code
symbol = mcp.find_symbol("UserService")
references = mcp.find_references("UserService")

# Step 3: Plan refactoring
chain = mcp.create_thinking_chain(
    "Refactor UserService to reduce complexity"
)

# Step 4: Implement with quality checks
# ... write code ...
quality = mcp.validate_code_quality("src/service.py")

# Step 5: Save context for next session
mcp.save_memory({
    "task": "Refactor UserService",
    "complexity_before": 15,
    "complexity_after": 8,
    "files_changed": ["src/service.py", "src/user_repo.py"]
})

Workflow Philosophy

Principles

Specification First - No code without requirements
Incremental Progress - Phase-by-phase execution
Continuous Validation - MCP tools at every step
Knowledge Preservation - Everything in .vibe/
AI-Augmented - Agents assist, humans verify

The Vibe Loop

Clarify Requirements (SPEC)
         ↓
Generate Plan (Technical Architecture)
         ↓
Decompose Tasks (Phase-based)
         ↓
Execute with AI (Agent + MCP)
         ↓
Verify Implementation (Against SPEC)
         ↓
Analyze Quality (MCP Tools)
         ↓
Iterate or Complete

Anti-patterns to Avoid

❌ Skipping SPEC phase - "Let's just start coding" ✅ Answer 6 questions first

❌ Running all tasks at once - vibe run --all ✅ Execute phase by phase with verification

❌ Ignoring acceptance criteria - "Looks good enough" ✅ Check every criterion before marking done

❌ Not using MCP tools - "I'll review manually" ✅ Leverage 38 tools for continuous validation

❌ Forgetting CLAUDE.md - Agent picks wrong tech stack ✅ Document your stack once, benefit forever

Key Takeaways

SPEC-driven Development puts requirements first, eliminating ambiguity
EARS Syntax provides unambiguous, testable requirements
6-Question Framework captures complete requirements through structured interview
Task Decomposition breaks features into phase-based, dependency-aware tasks
AI Agents provide specialized expertise for different tech stacks
MCP Integration offers 38 tools for continuous quality validation
Workflow Philosophy emphasizes incremental progress and knowledge preservation

Next Steps:

Command Reference - Learn all CLI commands
MCP Integration - Explore 38 tools in detail
Agents Guide - Master specialized agents
Examples - See real-world workflows

← Back to Getting Started | Home | Next: Command Reference →

Core‐Concepts - su-record/vibe GitHub Wiki

Core Concepts

Table of Contents

SPEC-driven Development

What is SPEC-driven Development?

Traditional vs SPEC-driven

Benefits

EARS Syntax

What is EARS?

EARS Keywords

EARS Template

EARS Examples

Example 1: Simple User Action

Example 2: Conditional Logic

Example 3: Performance Requirement

The 6-Question Framework

Q1: Why? (Business Value)

Q2: Who? (Users and Scale)

Q3: What? (Features)

Q4: How? (Technical Requirements)

Q5: When? (Timeline)

Q6: With What? (Tech Stack)

Task Decomposition

Phase-based Structure

Task Format

Dependency Graph

Task States

AI Agent System

Agent Selection

Agent Workflow

7 Specialized Agents

MCP Integration

What is MCP?

Tool Categories

1. Code Analysis (5 tools)

2. Project Intelligence (2 tools)

3. Thinking & Planning (6 tools)

4. Memory & Context (8 tools)

5. UI & Design (1 tool)

6. Requirements & Planning (4 tools)

7. Prompt Engineering (2 tools)

How Agents Use MCP Tools

Workflow Philosophy

Principles

The Vibe Loop

Anti-patterns to Avoid

Key Takeaways