Complete guide to Vibe's 7 specialized AI agents.

1. What are Agents?
2. Agent Architecture
3. Agent Selection
4. The 7 Agents
5. Agent Workflows
6. Best Practices
7. Customization

Agents are specialized AI assistants with deep expertise in specific technology stacks and development phases. Each agent has:

• Domain Knowledge: Expertise in specific languages, frameworks, and tools
• Best Practices: Built-in coding standards and patterns
• MCP Tools Access: All 38 tools available
• Context Awareness: Reads CLAUDE.md and project structure

Different development phases require different expertise:

• Backend development needs database design, API patterns, performance optimization
• Frontend development needs UI/UX patterns, state management, responsive design
• Quality review needs cross-language analysis, security auditing, test coverage

A single generalist AI can't match the depth of specialized agents.

Agent = Domain Knowledge + Skills + MCP Tools + Context

Components:

1. Agent Markdown File (agents/*.md)

   • Role and expertise
   • Technology stack
   • Coding standards
   • Common patterns

2. Skill Modules (skills/**/*.md)

   • Language-specific guides
   • Framework best practices
   • Quality checklists

3. MCP Tools (38 tools)

   • Code analysis
   • Project intelligence
   • Memory system

4. Project Context

   • CLAUDE.md - Tech stack documentation
   • .vibe/config.json - Project settings
   • Project structure and existing code

Vibe automatically selects agents based on:

1. Task Phase - Backend/Frontend/Integration
2. CLAUDE.md - Documented tech stack
3. File Extensions - .py, .dart, .ts, etc.

# Example: vibe run "Task 1-1: Database Migration"
#
# Vibe reads:
# - Task phase: Phase 1 (Backend)
# - CLAUDE.md: "Backend: Python 3.11, FastAPI"
# - Selected: Backend Python Expert

Override automatic selection:

# Use specific agent
vibe run "Task 1-1" --agent backend-python-expert

# Set default agent in config
vibe init --agent frontend-flutter-expert

Task Phase?
├── SPEC/Plan/Tasks → Planning Agent
├── Backend Phase
│   ├── CLAUDE.md: Python → Backend Python Expert
│   ├── CLAUDE.md: Node.js → (Future: Backend Node Expert)
│   └── Database Task → Database PostgreSQL Expert
├── Frontend Phase
│   ├── CLAUDE.md: Flutter → Frontend Flutter Expert
│   ├── CLAUDE.md: React → Frontend React Expert
│   └── CLAUDE.md: React Native → (Future: RN Expert)
└── Verification → Quality Reviewer

Role: Requirements gathering and SPEC creation

Expertise:

• 6-question framework facilitation
• EARS syntax formatting
• Acceptance criteria definition
• Edge case identification

Tech Stack: Language-agnostic

When Used:

• vibe spec "feature-name"
• Initial requirements gathering

Key Skills:

• Asking clarifying questions
• Converting vague requirements to EARS
• Identifying missing requirements
• Prioritization guidance

Example Interaction:

User: "vibe spec 'notification settings'"

Specification Agent:
Q1. Why do you need notification settings?
→ User: "Reduce churn from excessive notifications"

Q2. Who will use this feature?
→ User: "All users (100k DAU)"

Q3. What features should it include?
→ User: "Toggle for 6 categories"

... (continues through Q6)

✅ Created: .vibe/specs/notification-settings.md
- 6 requirements
- 24 acceptance criteria
- Priority: HIGH

Output Quality:

• Clear, unambiguous requirements
• Testable acceptance criteria
• Business value documented
• Technical constraints identified

Role: Technical architecture and implementation planning

Expertise:

• Architecture design patterns
• Database schema design
• API design (REST, GraphQL)
• Cost estimation
• Timeline estimation
• Risk assessment

Tech Stack: Cross-stack (understands all major stacks)

When Used:

• vibe plan "feature-name"
• Technical design phase

Key Skills:

• Reading tech stack from CLAUDE.md
• Selecting appropriate patterns
• Estimating complexity and cost
• Identifying dependencies
• Risk mitigation strategies

Example Output:

# PLAN: Notification Settings

## Architecture Overview
3-tier architecture: Flutter → FastAPI → PostgreSQL

## Database Schema
```sql
CREATE TABLE user_notification_settings (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  likes BOOLEAN DEFAULT true,
  comments BOOLEAN DEFAULT true,
  ...
)

• GET /api/users/{user_id}/notification-settings
• PATCH /api/users/{user_id}/notification-settings

• Phase 1 (Backend): 8 hours
• Phase 2 (Frontend): 8 hours
• Phase 3 (Integration): 4 hours

• Database: $0/month (existing PostgreSQL)
• Cache: $5/month (Redis 1GB)
• Total: +$5/month

**MCP Tools Used:**
- `create_thinking_chain` - Architecture decisions
- `analyze_requirements` - Extract technical needs
- `feature_roadmap` - Timeline generation

---

### 3. Task Agent ✅

**Role:** Feature decomposition into executable tasks

**Expertise:**
- Breaking down complex features
- Dependency graph creation
- Time estimation
- Phase organization

**Tech Stack:** Cross-stack

**When Used:**
- `vibe tasks "feature-name"`
- After plan is approved

**Key Skills:**
- Parsing technical plans
- Creating atomic, testable tasks
- Identifying dependencies
- Estimating task complexity

**Example Output:**

```markdown
# TASKS: Notification Settings

## Phase 1: Backend (8 hours)

### Task 1-1: Database Migration ⬜
**Description**: Create user_notification_settings table

**Implementation**:
1. Create Alembic migration file
2. Add 6 boolean columns for categories
3. Set default values
4. Add foreign key to users table

**Acceptance Criteria**:
- [ ] Migration file created
- [ ] All 6 columns present
- [ ] Defaults match SPEC
- [ ] Foreign key constraint added

**Dependencies**: None
**Estimated Time**: 1 hour

### Task 1-2: Repository Layer ⬜
**Description**: Create data access layer

**Dependencies**: Task 1-1
**Estimated Time**: 1.5 hours
...

MCP Tools Used:

• step_by_step_analysis - Task breakdown
• break_down_problem - Subtask creation
• format_as_plan - Structured output

Role: Python/FastAPI backend implementation

Expertise:

• Python 3.11+ best practices
• FastAPI framework patterns
• SQLAlchemy ORM
• Async/await patterns
• Type hints and Pydantic
• Testing with pytest
• PostgreSQL optimization

Tech Stack:

• Python 3.11+
• FastAPI 0.104+
• SQLAlchemy 2.0+
• Pydantic 2.0+
• PostgreSQL 17
• Redis (caching)
• Alembic (migrations)

When Used:

• Backend tasks (Phase 1)
• Python files (.py)
• Database migrations
• API development

Coding Standards:

# ✅ Good: Type hints, docstrings, async
async def get_user_settings(
    user_id: UUID,
    db: AsyncSession
) -> NotificationSettings:
    """
    Retrieve user notification settings.

    Args:
        user_id: UUID of the user
        db: Database session

    Returns:
        NotificationSettings object

    Raises:
        NotFoundError: If user doesn't exist
    """
    result = await db.execute(
        select(NotificationSettings)
        .where(NotificationSettings.user_id == user_id)
    )
    settings = result.scalar_one_or_none()

    if not settings:
        raise NotFoundError(f"Settings not found for user {user_id}")

    return settings

# ❌ Bad: No types, no docstring, blocking I/O
def get_user_settings(user_id, db):
    return db.query(NotificationSettings).filter_by(user_id=user_id).first()

Key Patterns:

• Repository Pattern - Data access abstraction
• Dependency Injection - FastAPI's Depends()
• Service Layer - Business logic separation
• Pydantic Schemas - Request/response validation
• Async everywhere - Non-blocking I/O

MCP Tools Used:

• analyze_complexity - Ensure CC ≤ 10
• validate_code_quality - Check standards
• find_symbol - Locate existing code
• find_references - Check usage

Example Task Execution:

Task 1-2: Create Settings Repository

Agent: Backend Python Expert

Steps:
1. Read existing repository patterns
   → Uses find_symbol("UserRepository")
   → Copies pattern structure

2. Create NotificationSettingsRepository
   → Implements get_by_user_id()
   → Implements update_settings()
   → Adds type hints and docstrings

3. Validate code quality
   → Uses validate_code_quality()
   → Score: 95/100 ✅

4. Check complexity
   → Uses analyze_complexity()
   → CC: 3 (target: ≤10) ✅

5. Save context
   → Uses save_memory()
   → Stores repository pattern for future tasks

Skills Used:

• skills/languages/python-fastapi.md - FastAPI patterns
• skills/standards/code-structure.md - Project structure
• skills/quality/testing-strategy.md - Pytest patterns

Role: Flutter/Dart mobile and web implementation

Expertise:

• Flutter 3.24+ best practices
• Dart 3.5+ language features
• State management (Provider, Riverpod, Bloc)
• Responsive design
• Platform-specific code (iOS/Android/Web)
• Widget composition
• Performance optimization
• Material Design / Cupertino

Tech Stack:

• Flutter 3.24+
• Dart 3.5+
• Provider (state management)
• Dio (HTTP client)
• flutter_test (testing)
• build_runner (code generation)

When Used:

• Frontend tasks (Phase 2)
• Dart files (.dart)
• UI implementation
• State management

Coding Standards:

// ✅ Good: Immutable, typed, documented
@immutable
class NotificationSettings {
  const NotificationSettings({
    required this.likes,
    required this.comments,
    required this.follows,
    required this.mentions,
    required this.feedUpdates,
    required this.marketing,
  });

  final bool likes;
  final bool comments;
  final bool follows;
  final bool mentions;
  final bool feedUpdates;
  final bool marketing;

  NotificationSettings copyWith({
    bool? likes,
    bool? comments,
    bool? follows,
    bool? mentions,
    bool? feedUpdates,
    bool? marketing,
  }) {
    return NotificationSettings(
      likes: likes ?? this.likes,
      comments: comments ?? this.comments,
      follows: follows ?? this.follows,
      mentions: mentions ?? this.mentions,
      feedUpdates: feedUpdates ?? this.feedUpdates,
      marketing: marketing ?? this.marketing,
    );
  }
}

// ❌ Bad: Mutable, no types
class NotificationSettings {
  var likes;
  var comments;
  // No immutability, no types, no copyWith
}

Key Patterns:

• Provider Pattern - State management
• Widget Composition - Reusable widgets
• BLoC Pattern - Complex state (optional)
• Repository Pattern - API abstraction
• Responsive Design - LayoutBuilder, MediaQuery

MCP Tools Used:

• preview_ui_ascii - UI mockups before implementation
• analyze_complexity - Widget complexity
• validate_code_quality - Flutter standards

Example Task Execution:

Task 2-3: Notification Settings Screen

Agent: Frontend Flutter Expert

Steps:
1. Generate UI mockup
   → Uses preview_ui_ascii()
   → Shows layout with 6 toggles

2. Create NotificationSettingsScreen widget
   → StatelessWidget with Provider
   → 6 SwitchListTile widgets
   → Save button at bottom

3. Implement state management
   → NotificationSettingsProvider
   → API integration with Dio

4. Add loading/error states
   → CircularProgressIndicator
   → ErrorWidget with retry

5. Test responsiveness
   → Works on mobile, tablet, web

Skills Used:

• skills/languages/dart-flutter.md - Flutter patterns
• skills/quality/testing-strategy.md - Widget testing

Role: React/Next.js web implementation

Expertise:

• React 18+ best practices
• Next.js 14+ (App Router)
• TypeScript
• State management (Zustand, Redux, Context)
• Server Components vs Client Components
• Performance optimization
• Accessibility (a11y)
• Responsive design (Tailwind CSS)

Tech Stack:

• React 18+
• Next.js 14+
• TypeScript 5+
• Tailwind CSS
• Zustand/Redux Toolkit
• React Query
• Vitest/Jest (testing)

When Used:

• Frontend tasks (React projects)
• TypeScript/JavaScript files (.ts, .tsx, .js, .jsx)
• Web UI implementation

Coding Standards:

// ✅ Good: Typed, functional, documented
interface NotificationSettingsProps {
  userId: string;
  onSave?: (settings: NotificationSettings) => void;
}

export function NotificationSettingsPanel({
  userId,
  onSave
}: NotificationSettingsProps) {
  const [settings, setSettings] = useState<NotificationSettings>({
    likes: true,
    comments: true,
    follows: true,
    mentions: true,
    feedUpdates: false,
    marketing: false,
  });

  const handleToggle = useCallback((category: keyof NotificationSettings) => {
    setSettings(prev => ({
      ...prev,
      [category]: !prev[category],
    }));
  }, []);

  const handleSave = useCallback(async () => {
    await updateSettings(userId, settings);
    onSave?.(settings);
  }, [userId, settings, onSave]);

  return (
    <div className="space-y-4">
      {/* Toggle switches */}
    </div>
  );
}

// ❌ Bad: No types, inline functions, any
export function NotificationSettingsPanel(props: any) {
  const [settings, setSettings] = useState({});

  return (
    <div>
      <button onClick={() => setSettings({...settings, likes: !settings.likes})}>
        Toggle
      </button>
    </div>
  );
}

Key Patterns:

• Server Components - Default in Next.js App Router
• Client Components - "use client" for interactivity
• Custom Hooks - Reusable logic
• Composition - Small, focused components
• TypeScript - Full type safety

Skills Used:

• skills/languages/typescript-react.md - React patterns
• skills/languages/typescript-nextjs.md - Next.js patterns

Role: PostgreSQL database design and optimization

Expertise:

• PostgreSQL 17 features
• Schema design
• Indexing strategies
• Query optimization
• PostGIS (geospatial)
• Migrations (Alembic, Prisma)
• Performance tuning
• Backup and recovery

Tech Stack:

• PostgreSQL 17
• PostGIS 3.4+ (geospatial)
• Alembic (Python migrations)
• Prisma (TypeScript migrations)
• pgAdmin
• pg_stat_statements

When Used:

• Database design tasks
• Migration creation
• Query optimization
• Schema changes

Coding Standards:

-- ✅ Good: Proper types, constraints, indexes
CREATE TABLE user_notification_settings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    likes BOOLEAN NOT NULL DEFAULT true,
    comments BOOLEAN NOT NULL DEFAULT true,
    follows BOOLEAN NOT NULL DEFAULT true,
    mentions BOOLEAN NOT NULL DEFAULT true,
    feed_updates BOOLEAN NOT NULL DEFAULT false,
    marketing BOOLEAN NOT NULL DEFAULT false,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),

    CONSTRAINT unique_user_settings UNIQUE(user_id)
);

-- Index for fast lookups
CREATE INDEX idx_user_notification_settings_user_id
ON user_notification_settings(user_id);

-- Trigger for updated_at
CREATE TRIGGER set_updated_at
BEFORE UPDATE ON user_notification_settings
FOR EACH ROW
EXECUTE FUNCTION trigger_set_updated_at();

-- ❌ Bad: No constraints, no indexes, nullable when shouldn't be
CREATE TABLE user_notification_settings (
    id INT,
    user_id INT,
    likes BOOLEAN,
    comments BOOLEAN
);

Key Patterns:

• Foreign Keys - Always define relationships
• Indexes - On frequently queried columns
• Constraints - Enforce data integrity
• Triggers - Auto-update timestamps
• Partitioning - For large tables
• JSON/JSONB - For flexible schemas

MCP Tools Used:

• analyze_complexity - Query complexity
• check_coupling_cohesion - Schema relationships
• validate_code_quality - SQL standards

Example Task Execution:

Task 1-1: Database Migration

Agent: Database PostgreSQL Expert

Steps:
1. Analyze existing schema
   → Uses find_symbol("users table")
   → Checks existing patterns

2. Design new table
   → 6 boolean columns
   → Foreign key to users
   → Proper defaults and constraints

3. Create migration
   → Alembic migration file
   → Includes indexes
   → Includes triggers

4. Validate migration
   → Check syntax
   → Ensure rollback works
   → Test on sample data

Role: Code review and quality assurance

Expertise:

• Multi-language code review
• Security auditing
• Performance analysis
• Test coverage analysis
• Accessibility (a11y) review
• Best practices enforcement
• Technical debt identification

Tech Stack: Multi-language (Python, TypeScript, Dart, SQL)

When Used:

• vibe verify "feature-name"
• After task completion
• Before pull request

Review Checklist:

Code Quality:

• Complexity: CC ≤ 10, Cognitive ≤ 15
• Function length: ≤ 20 lines
• Nesting depth: ≤ 3 levels
• No code duplication
• Proper error handling

Type Safety:

• Type hints (Python) / Types (TS/Dart)
• No any types (TypeScript)
• No dynamic (Dart)
• Proper null safety

Documentation:

• Docstrings for public functions
• Inline comments for complex logic
• README updated if needed

Testing:

• Unit tests for business logic
• Integration tests for APIs
• E2E tests for critical flows
• Coverage ≥ 80%

Security:

• Input validation
• SQL injection prevention
• XSS prevention
• Authentication/authorization checks

Performance:

• No N+1 queries
• Proper indexing
• Caching where appropriate
• Async I/O used correctly

MCP Tools Used:

• validate_code_quality - Overall score
• analyze_complexity - Complexity metrics
• check_coupling_cohesion - Architecture review
• suggest_improvements - Refactoring suggestions

Example Review:

📊 Quality Review: notification-settings

Overall Score: 88/100 (B+)

✅ Strengths:
- Excellent type coverage (98%)
- Good test coverage (87%)
- Clear separation of concerns
- Proper error handling

⚠️ Issues Found:

1. HIGH: src/service.py:45
   Cyclomatic complexity: 15 (target: ≤10)
   Suggestion: Extract validation logic into separate functions

2. MEDIUM: src/api.py:23
   Missing rate limiting on settings update endpoint
   Suggestion: Add @limiter.limit("100/minute")

3. LOW: frontend/screens/settings.dart:67
   Widget tree depth: 8 (target: ≤6)
   Suggestion: Extract nested widgets into separate components

Recommendations:
1. Refactor process_notification() into 3 functions
2. Add rate limiting middleware
3. Break down SettingsScreen widget
4. Increase test coverage to 90%

Report: .vibe/reports/review-2025-11-17.md

1. User: vibe spec "notification settings"
   → Specification Agent
   → Creates SPEC with 6 questions
   → Output: .vibe/specs/notification-settings.md

2. User: vibe plan "notification settings"
   → Planning Agent
   → Reads SPEC
   → Reads CLAUDE.md for tech stack
   → Generates architecture and timeline
   → Output: .vibe/plans/notification-settings.md

3. User: vibe tasks "notification settings"
   → Task Agent
   → Reads PLAN
   → Breaks down into 19 tasks across 3 phases
   → Output: .vibe/tasks/notification-settings.md

4. User: vibe run "Task 1-1"
   → Database PostgreSQL Expert (detected from task)
   → Creates migration file
   → Validates with MCP tools
   → Updates task status: ⬜ → ✅

5. User: vibe run "Task 1-2"
   → Backend Python Expert (detected from task)
   → Creates repository layer
   → Follows existing patterns
   → Validates code quality
   → Updates task status: ⬜ → ✅

6. User: vibe run --phase 2
   → Frontend Flutter Expert (detected from tasks)
   → Creates UI screens
   → Implements state management
   → All Phase 2 tasks: ⬜ → ✅

7. User: vibe verify "notification settings"
   → Quality Reviewer
   → Runs all 38 MCP tools
   → Generates comprehensive report
   → Score: 88/100 (B+)

Create CLAUDE.md in project root:

# CLAUDE.md

## Tech Stack

### Backend
- Framework: FastAPI 0.104+
- Database: PostgreSQL 17
- Cache: Redis 7.2

### Frontend
- Framework: Flutter 3.24+
- State Management: Provider

This ensures agents use the right patterns and libraries.

# ✅ Good: Trust the agent
vibe run "Task 1-1"

# ❌ Bad: Micromanaging
# Don't manually specify every detail
# Agents read SPEC/PLAN/TASKS and know what to do

Agents are experts, but always review:

# After task completion
git diff

# Check quality report
cat .vibe/reports/verification-*.md

# Execute and verify each phase
vibe run --phase 1
vibe verify "feature-name"

vibe run --phase 2
vibe verify "feature-name"

vibe run --phase 3
vibe verify "feature-name"

Agents save context automatically - they learn from previous tasks:

# Task 1-1: Agent learns repository pattern
# Task 1-2: Agent reuses pattern from memory
# Task 1-3: Agent improves pattern based on experience

Edit .vibe/config.json:

{
  "language": "ko",
  "agents": {
    "default": "backend-python-expert",
    "backend": "backend-python-expert",
    "frontend": "frontend-flutter-expert",
    "database": "database-postgres-expert",
    "quality": "quality-reviewer"
  },
  "quality": {
    "max_complexity": 10,
    "max_function_length": 20,
    "min_test_coverage": 80
  }
}

Add custom skill modules:

# Create custom skill
mkdir -p skills/custom/
cat > skills/custom/my-patterns.md << EOF
# My Project Patterns

## Authentication Pattern
Always use this pattern for auth:
...
EOF

Agents will automatically read and apply custom skills.

• Backend Node.js Expert - Express/NestJS
• Frontend React Native Expert - Mobile with React Native
• DevOps Expert - CI/CD, Docker, Kubernetes
• Security Expert - Penetration testing, security audits
• Performance Expert - Profiling, optimization

Next Steps:

• Examples - See agents in action
• Best Practices - Maximize agent effectiveness
• Troubleshooting - Common issues

← Back to MCP Integration | Home | Next: Examples →