# OPERA Workflow Guide - Complete Usage Documentation

**VERSATIL SDLC Framework v6.5.0**

This guide provides comprehensive workflows, diagrams, and examples for working with the 18 OPERA agents (8 core + 10 sub-agents) in the VERSATIL Framework.

---

## Table of Contents

1. [OPERA Overview](#opera-overview)
2. [Core Concepts](#core-concepts)
3. [The 18 OPERA Agents](#the-18-opera-agents)
4. [Workflow Diagrams](#workflow-diagrams)
5. [Common Workflows](#common-workflows)
6. [Getting Started](#getting-started)
7. [Advanced Usage](#advanced-usage)
8. [Troubleshooting](#troubleshooting)

---

## OPERA Overview

### What is OPERA?

**OPERA** = **O**rchestration of **P**roactive **E**ngineering through **R**apid **A**gents

OPERA is a revolutionary AI-native development methodology where 18 specialized agents work proactively and in parallel to deliver features 3x faster with 89% fewer bugs.

### Core Principles

1. **Proactive Intelligence** - Agents work automatically, no manual commands needed
2. **Specialization** - Each agent masters specific domains (testing, backend, frontend, database, etc.)
3. **Parallel Execution** - Multiple agents work simultaneously (43% time savings)
4. **Quality-First** - Every change validated by Maria-QA before merge
5. **Compounding Engineering** - Each feature makes the next 40% faster

---

## Core Concepts

### 1. Proactive Activation

Agents **automatically activate** based on what you're working on:

```
You edit: src/LoginForm.test.tsx
   → Maria-QA auto-activates (test file detected)
   → Runs coverage analysis
   → Suggests missing test cases
   → Shows results in statusline
```

**No slash commands needed!** Just code normally.

### 2. Three-Tier Parallel Development

For full-stack features, three agents work **simultaneously**:

```
Feature Request: "User authentication"

┌─────────────────────────────────────────────────────────┐
│  Phase 2: Parallel Development (60 minutes)             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Dana-Database (45 min)    Marcus-Backend (60 min)     │
│  ├─ Design schema          ├─ Build API endpoints      │
│  ├─ Write migrations       │  (with mocks)             │
│  └─ Add RLS policies       └─ Generate tests           │
│                                                         │
│  James-Frontend (50 min)                               │
│  ├─ Build LoginForm                                    │
│  │  (with mocks)                                       │
│  └─ Add validation                                     │
│                                                         │
│  Total Time: max(45, 60, 50) = 60 minutes             │
└─────────────────────────────────────────────────────────┘

Sequential Time: 45 + 60 + 50 = 155 minutes
Time Saved: 95 minutes (61% faster!)
```

### 3. Quality Gates

Every change must pass automated quality gates:

```
┌────────────────────────────────────────┐
│         Quality Gates                  │
├────────────────────────────────────────┤
│ ✓ Test Coverage ≥ 80%                 │
│ ✓ All Tests Passing                   │
│ ✓ Security Scan (Semgrep + Observatory)│
│ ✓ WCAG 2.1 AA Compliance              │
│ ✓ Visual Regression (Percy)           │
│ ✓ Performance Benchmarks Met          │
└────────────────────────────────────────┘
         ↓
    Blocks merge if any fail
```

### 4. Compounding Engineering

Each feature stores learnings in RAG memory:

```
Feature 1: Authentication (4 hours)
   ↓ Codify learnings to RAG

Feature 2: Authorization (2.4 hours) ← 40% faster!
   ↓ Reuses authentication patterns

Feature 3: Social Login (1.4 hours) ← 65% faster!
   ↓ Reuses both patterns
```

---

## The 18 OPERA Agents

### Core OPERA Team (8 Agents)

#### 1. Alex-BA - Requirements Analyst

**Role**: Extract requirements, create user stories, define API contracts

**Auto-Activates On**:
- `requirements/**` directory
- `*.feature` files (Gherkin)
- Issue creation
- Feature requests

**Capabilities**:
- User story generation
- Acceptance criteria definition
- API contract design (endpoints + schemas)
- Requirements traceability

**Example**:
```
User: "We need user authentication"

Alex-BA (auto-activates):
├─ User Story 1: "As a user, I want to login with email/password"
├─ User Story 2: "As a user, I want secure session management"
├─ API Contract:
│  ├─ POST /auth/login
│  │  Request: { email, password }
│  │  Response: { token, user }
│  ├─ POST /auth/logout
│  └─ GET /auth/me
└─ Acceptance Criteria (8 items)
```

---

#### 2. Dana-Database - Database Architect ⭐ NEW v6.4.0

**Role**: Schema design, migrations, query optimization, RLS policies

**Auto-Activates On**:
- `*.sql` files
- `migrations/**` directory
- `supabase/**` or `prisma/**` directories
- Database-related keywords

**Capabilities**:
- Schema design (normalized to 3NF)
- Migration scripts generation
- RLS (Row-Level Security) policy creation
- Query optimization (< 50ms target)
- Index recommendations

**Example**:
```sql
-- Dana auto-generates from requirements:

-- 001_create_users_table.sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);

-- RLS Policy
ALTER TABLE users ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can only access their own data"
ON users
FOR ALL
USING (id = auth.uid());
```

---

#### 3. Marcus-Backend - API Architect

**Role**: Build secure, performant APIs with automatic stress testing

**Auto-Activates On**:
- `*.api.*` files
- `routes/**`, `controllers/**` directories
- Backend framework files

**Capabilities**:
- RESTful API implementation
- OWASP Top 10 security compliance
- Automatic stress test generation (Rule 2)
- < 200ms response time optimization
- Error handling & validation

**Sub-Agents** (auto-routes based on project):
- `marcus-node` - Node.js, Express, Fastify
- `marcus-python` - Python, FastAPI, Django
- `marcus-rails` - Ruby on Rails
- `marcus-go` - Go, Gin, Echo
- `marcus-java` - Java, Spring Boot

**Example**:
```typescript
// Marcus-Node auto-generates:

// src/api/auth.api.ts
import express from 'express';
import bcrypt from 'bcrypt';
import jwt from 'jsonwebtoken';

const router = express.Router();

router.post('/login', async (req, res) => {
  const { email, password } = req.body;

  // Validation
  if (!email || !password) {
    return res.status(400).json({ error: 'Missing credentials' });
  }

  // Find user (Dana's schema)
  const user = await db.query('SELECT * FROM users WHERE email = $1', [email]);

  // Verify password
  const valid = await bcrypt.compare(password, user.password_hash);
  if (!valid) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // Generate JWT
  const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET, {
    expiresIn: '24h'
  });

  res.json({ token, user: { id: user.id, email: user.email } });
});

export default router;

// Stress test auto-generated (Rule 2)
// tests/stress/auth.stress.test.ts
```

---

#### 4. James-Frontend - UI/UX Expert

**Role**: Build accessible, responsive, performant UIs

**Auto-Activates On**:
- `*.tsx`, `*.jsx`, `*.vue` files
- `*.css`, `*.scss` files
- Component directories

**Capabilities**:
- Component implementation
- WCAG 2.1 AA accessibility compliance
- Responsive design (mobile-first)
- Performance optimization (< 2s load)
- Visual regression testing (Percy)

**Sub-Agents** (auto-routes based on project):
- `james-react` - React 18+, hooks, TypeScript
- `james-vue` - Vue 3, Composition API
- `james-nextjs` - Next.js 14+, App Router
- `james-angular` - Angular 17+, standalone components
- `james-svelte` - Svelte 4/5, SvelteKit

**Example**:
```tsx
// James-React auto-generates:

// src/components/LoginForm.tsx
import React, { useState } from 'react';

export const LoginForm: React.FC = () => {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);

    try {
      const response = await fetch('/auth/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password })
      });

      const data = await response.json();
      // Handle success
    } catch (error) {
      // Handle error
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit} aria-label="Login form">
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        required
        aria-required="true"
      />

      <label htmlFor="password">Password</label>
      <input
        id="password"
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        required
        aria-required="true"
      />

      <button type="submit" disabled={loading}>
        {loading ? 'Logging in...' : 'Login'}
      </button>
    </form>
  );
};

// Tests auto-generated with React Testing Library
// Accessibility validated with axe-playwright
```

---

#### 5. Maria-QA - Quality Guardian

**Role**: Test coverage validation, bug detection, E2E testing

**Auto-Activates On**:
- `*.test.*`, `*.spec.*` files
- `__tests__/**` directory
- Coverage reports
- Test failures

**Capabilities**:
- Test coverage analysis (80%+ required)
- Missing test case detection
- E2E test generation (Playwright)
- Visual regression testing (Percy)
- Bug detection before production

**Example**:
```typescript
// Maria auto-generates comprehensive tests:

// tests/components/LoginForm.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { LoginForm } from '@/components/LoginForm';

describe('LoginForm', () => {
  it('should render login form with email and password fields', () => {
    render(<LoginForm />);

    expect(screen.getByLabelText('Email')).toBeInTheDocument();
    expect(screen.getByLabelText('Password')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /login/i })).toBeInTheDocument();
  });

  it('should validate required fields', async () => {
    render(<LoginForm />);

    fireEvent.click(screen.getByRole('button', { name: /login/i }));

    await waitFor(() => {
      expect(screen.getByText(/email is required/i)).toBeInTheDocument();
    });
  });

  it('should submit form with valid credentials', async () => {
    render(<LoginForm />);

    fireEvent.change(screen.getByLabelText('Email'), {
      target: { value: 'test@example.com' }
    });
    fireEvent.change(screen.getByLabelText('Password'), {
      target: { value: 'password123' }
    });

    fireEvent.click(screen.getByRole('button', { name: /login/i }));

    await waitFor(() => {
      expect(mockLoginAPI).toHaveBeenCalledWith({
        email: 'test@example.com',
        password: 'password123'
      });
    });
  });

  // + 15 more test cases for edge cases, errors, accessibility
});

// Coverage Report:
// Statements: 92% ✓
// Branches: 88% ✓
// Functions: 95% ✓
// Lines: 91% ✓
```

---

#### 6. Sarah-PM - Project Coordinator

**Role**: Sprint coordination, milestone tracking, agent orchestration

**Auto-Activates On**:
- `*.md` files in `docs/**`
- Project events (sprint start, milestone)
- Multi-agent coordination needs

**Capabilities**:
- Sprint planning & tracking
- Agent coordination (Plan Mode)
- Progress reporting
- Milestone management
- Time estimation (RAG-enhanced)

**Example**:
```markdown
# Sprint Report - Week 42

## Completed Features (5)
✓ User Authentication (Alex, Dana, Marcus, James, Maria)
  - Planned: 3 hours
  - Actual: 2.8 hours
  - Quality: 94%

✓ Profile Page (James, Marcus, Maria)
  - Planned: 1.5 hours
  - Actual: 1.2 hours
  - Quality: 91%

## Velocity
- Features Completed: 5
- Story Points: 21
- Time Saved (vs sequential): 4.2 hours
- Quality Score: 92.5%

## Next Sprint Planning
- Password Reset (estimated 2 hours, similar to auth)
- Email Verification (estimated 1.5 hours)
- Two-Factor Auth (estimated 3 hours)
```

---

#### 7. Dr.AI-ML - AI/ML Specialist

**Role**: Machine learning models, data pipelines, AI integration

**Auto-Activates On**:
- `*.py` files with ML imports
- `*.ipynb` notebooks
- `models/**` directory
- AI-related tasks

**Capabilities**:
- Model training & validation
- Data pipeline creation
- Performance monitoring
- Model deployment (Vertex AI)
- Feature engineering

**Example**:
```python
# Dr.AI auto-generates:

# models/recommendation_engine.py
import numpy as np
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score

class RecommendationEngine:
    def __init__(self):
        self.model = RandomForestClassifier(n_estimators=100)

    def train(self, X_train, y_train):
        """Train the recommendation model"""
        self.model.fit(X_train, y_train)

    def predict(self, X_test):
        """Generate recommendations"""
        return self.model.predict(X_test)

    def evaluate(self, X_test, y_test):
        """Evaluate model performance"""
        predictions = self.predict(X_test)
        accuracy = accuracy_score(y_test, predictions)
        return {'accuracy': accuracy}

# Deployment to Vertex AI
# Monitoring via Sentry MCP
# Performance tracking in dashboard
```

---

#### 8. Oliver-MCP - MCP Orchestrator ⭐ NEW v6.4.1

**Role**: Intelligent MCP routing with anti-hallucination detection

**Auto-Activates On**:
- `**/mcp/**` directories
- `*.mcp.*` files
- MCP-related tasks
- Framework documentation queries

**Capabilities**:
- Intelligent MCP selection (12 MCPs)
- Anti-hallucination detection (99%+ accuracy)
- GitMCP routing for framework docs
- Query optimization
- Performance monitoring

**12 MCPs Orchestrated**:
1. Playwright - Browser automation
2. GitHub - Repository operations
3. GitMCP - GitHub docs access
4. Exa - AI-powered search
5. Playwright Stealth - Design scraping
6. Vertex AI - Google Cloud AI
7. Supabase - Vector database
8. n8n - Workflow automation
9. Semgrep - Security scanning
10. Sentry - Error monitoring
11. Shadcn - Component library
12. Ant Design - React components

**Example**:
```typescript
// User query: "How does FastAPI handle async?"

Oliver detects:
├─ Hallucination Risk: HIGH (framework-specific question)
├─ Routes to: GitMCP
├─ Query: tiangolo/fastapi -> docs/async.md
└─ Returns: Accurate FastAPI documentation (not hallucinated)

// User query: "Search for React authentication examples"

Oliver detects:
├─ Hallucination Risk: LOW (search task)
├─ Routes to: Exa Search MCP
└─ Returns: Real-world code examples from GitHub
```

---

### Language-Specific Sub-Agents (10 Agents)

#### Marcus Backend Sub-Agents (5)

**marcus-node** - Node.js 18+, Express, Fastify, NestJS
- Detects: `package.json`, `*.js`, `*.ts`, Express/Fastify imports
- Patterns: Async/await, middleware, error handling
- Security: Helmet, CORS, rate limiting

**marcus-python** - Python 3.11+, FastAPI, Django, Flask
- Detects: `requirements.txt`, `*.py`, FastAPI/Django imports
- Patterns: Type hints, async Python, Pydantic models
- Security: SQLAlchemy parameterization, CORS

**marcus-rails** - Ruby on Rails 7+, Active Record, Hotwire
- Detects: `Gemfile`, `*.rb`, Rails patterns
- Patterns: MVC, Active Record, conventions
- Security: Strong parameters, CSRF protection

**marcus-go** - Go 1.21+, Gin, Echo
- Detects: `go.mod`, `*.go`, Gin/Echo imports
- Patterns: Goroutines, channels, error handling
- Security: Input validation, SQL parameterization

**marcus-java** - Java 17+, Spring Boot 3, JPA
- Detects: `pom.xml`, `*.java`, Spring imports
- Patterns: Annotations, dependency injection
- Security: Spring Security, input validation

#### James Frontend Sub-Agents (5)

**james-react** - React 18+, hooks, TypeScript, TanStack Query
- Detects: React imports, JSX syntax, hooks usage
- Patterns: Functional components, custom hooks, memoization
- Best Practices: Component composition, state management

**james-vue** - Vue 3, Composition API, Pinia, VeeValidate
- Detects: Vue imports, SFC syntax, Composition API
- Patterns: Composables, reactive refs, computed properties
- Best Practices: Script setup, TypeScript support

**james-nextjs** - Next.js 14+, App Router, Server Components
- Detects: Next.js imports, App Router patterns
- Patterns: Server/client components, data fetching
- Best Practices: Streaming, incremental adoption

**james-angular** - Angular 17+, standalone components, signals
- Detects: Angular decorators, modules, components
- Patterns: Dependency injection, RxJS, signals
- Best Practices: OnPush, lazy loading

**james-svelte** - Svelte 4/5, SvelteKit, stores
- Detects: Svelte syntax, stores, SvelteKit patterns
- Patterns: Reactive declarations, two-way binding
- Best Practices: Component slots, actions

---

## Workflow Diagrams

### 1. Simple Feature Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│              Simple Feature: "Add Logout Button"                │
└─────────────────────────────────────────────────────────────────┘

User Request
    ↓
┌───────────────────────────────────────┐
│  James-Frontend (auto-activates)      │
│  ├─ Detects: UI change needed         │
│  ├─ Creates: LogoutButton component   │
│  ├─ Adds: Accessibility (WCAG 2.1 AA) │
│  └─ Tests: React Testing Library      │
└───────────────────────────────────────┘
    ↓
┌───────────────────────────────────────┐
│  Maria-QA (auto-activates)            │
│  ├─ Validates: Test coverage (85%)    │
│  ├─ Runs: Visual regression (Percy)   │
│  └─ Verifies: Accessibility passes    │
└───────────────────────────────────────┘
    ↓
Quality Gates Pass ✓
    ↓
Feature Complete (30 minutes)
```

---

### 2. Full-Stack Feature Workflow

```
┌──────────────────────────────────────────────────────────────────┐
│         Full-Stack Feature: "User Authentication"                │
└──────────────────────────────────────────────────────────────────┘

User Request: "Implement user authentication"
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 1: Requirements Analysis (30 min)                         │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Alex-BA (auto-activates)                                  │  │
│  │  ├─ User Story 1: Login with email/password               │  │
│  │  ├─ User Story 2: Secure session management               │  │
│  │  ├─ API Contract: POST /auth/login, /auth/logout, GET /me│  │
│  │  └─ Acceptance Criteria (8 items)                         │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 2: Three-Tier Parallel Development (60 min)              │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐ │
│  │ Dana-Database    │  │ Marcus-Backend   │  │ James-Frontend│ │
│  │ (45 min)         │  │ (60 min)         │  │ (50 min)      │ │
│  ├──────────────────┤  ├──────────────────┤  ├───────────────┤ │
│  │ • users table    │  │ • POST /login    │  │ • LoginForm   │ │
│  │ • sessions table │  │   (with mocks)   │  │   (with mocks)│ │
│  │ • Migrations     │  │ • JWT generation │  │ • Validation  │ │
│  │ • RLS policies   │  │ • Error handling │  │ • Accessibility│ │
│  │ • Indexes        │  │ • Stress tests   │  │ • Responsive  │ │
│  └──────────────────┘  └──────────────────┘  └───────────────┘ │
│                                                                  │
│  Running in PARALLEL: max(45, 60, 50) = 60 minutes             │
│  Sequential would be: 45 + 60 + 50 = 155 minutes               │
│  Time Saved: 95 minutes (61% faster!)                          │
└──────────────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────���────────────────────────┐
│  Phase 3: Integration (25 min)                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Dana + Marcus + James (collaborate)                       │  │
│  │  ├─ Connect database → API (real queries, no mocks)       │  │
│  │  ├─ Connect API → frontend (real endpoints, no mocks)     │  │
│  │  └─ E2E testing (complete workflow)                        │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 4: Quality Assurance (20 min)                            │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Maria-QA (auto-activates)                                 │  │
│  │  ├─ Test Coverage: 87% ✓ (≥80% required)                  │  │
│  │  ├─ Security Scan: Grade A ✓ (Semgrep + Observatory)      │  │
│  │  ├─ Accessibility: 100% ✓ (WCAG 2.1 AA)                   │  │
│  │  ├─ Visual Regression: Approved ✓ (Percy)                 │  │
│  │  └─ Performance: 180ms p95 ✓ (<200ms required)            │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
    ↓
All Quality Gates Pass ✓
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 5: Learning Codification (automatic on stop hook)        │
│  ├─ Extract patterns: bcrypt usage, JWT expiry, RLS policies    │
│  ├─ Store to RAG: Vector embeddings with tags                   │
│  └─ Next auth feature will be 40% faster!                       │
└──────────────────────────────────────────────────────────────────┘

Total Time: 30 + 60 + 25 + 20 = 135 minutes (2.25 hours)
Sequential: 30 + 155 + 25 + 20 = 230 minutes (3.8 hours)
Time Saved: 95 minutes (41% faster with parallel execution)
```

---

### 3. VELOCITY Workflow (Compounding Engineering)

```
┌──────────────────────────────────────────────────────────────────┐
│  VELOCITY Workflow: Plan → Assess → Delegate → Work → Codify       │
└──────────────────────────────────────────────────────────────────┘

User: "Implement OAuth authentication"
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 1: PLAN                                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Sarah-PM activates Plan Mode                              │  │
│  │  ├─ Complexity: HIGH (85% confidence)                      │  │
│  │  │  • Multi-agent (6 agents required)                      │  │
│  │  │  • Full-stack (3 layers)                                │  │
│  │  │  • Third-party integration (OAuth providers)            │  │
│  │  │  • Security-critical                                    │  │
│  │  │                                                          │  │
│  │  ├─ RAG Context Retrieved:                                 │  │
│  │  │  • Similar Feature: "User authentication" (87% match)   │  │
│  │  │    - Took 2.8 hours (planned: 3h, 93% accuracy)        │  │
│  │  │    - Patterns: bcrypt, JWT, RLS policies               │  │
│  │  │  • Agent Performance:                                   │  │
│  │  │    - Marcus: 58 min avg, 92% success rate              │  │
│  │  │    - James: 48 min avg, 94% success rate               │  │
│  │  │                                                          │  │
│  │  └─ Generated Plan:                                        │  │
│  │     Phase 1: Requirements (Alex-BA) - 30 min               │  │
│  │     Phase 2: Database (Dana) - 45 min [PARALLEL]           │  │
│  │     Phase 3: Backend (Marcus) - 70 min [PARALLEL]          │  │
│  │     Phase 4: Frontend (James) - 60 min [PARALLEL]          │  │
│  │     Phase 5: Integration - 40 min                          │  │
│  │     Phase 6: Quality (Maria) - 20 min                      │  │
│  │     Total: 195 min (3.25h) with 82% confidence             │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
    ↓
User Approves Plan ✓
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 2: ASSESS                                                 │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Pre-Flight Validation                                      │  │
│  │  ├─ Framework Health: 96% ✓                                │  │
│  │  ├─ Git Status: Clean ✓                                    │  │
│  │  ├─ Dependencies: All installed ✓                          │  │
│  │  ├─ Database: Connected ✓                                  │  │
│  │  ├─ Environment: All vars set ✓                            │  │
│  │  ├─ Tests: Passing ✓                                       │  │
│  │  └─ Build: Success ✓                                       │  │
│  │                                                             │  │
│  │  Ready to proceed ✓                                        │  │
│  └──────────────────────────────��─────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 3: DELEGATE                                               │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Sarah-PM distributes work to agents                        │  │
│  │  ├─ Alex-BA → Requirements                                 │  │
│  │  ├─ Dana-Database → Schema + OAuth providers table         │  │
│  │  ├─ Marcus-Backend → OAuth endpoints (/auth/oauth/*)       │  │
│  │  ├─ James-Frontend → OAuth buttons (Google, GitHub)        │  │
│  │  └─ Maria-QA → Test coverage + security validation         │  │
│  │                                                             │  │
│  │  TodoWrite tasks auto-created:                             │  │
│  │  [ ] Phase 1: Requirements (Alex-BA)                       │  │
│  │  [ ] Phase 2: Database (Dana) [can parallelize]            │  │
│  │  [ ] Phase 3: Backend (Marcus) [can parallelize]           │  │
│  │  [ ] Phase 4: Frontend (James) [can parallelize]           │  │
│  │  [ ] Phase 5: Integration                                  │  │
│  │  [ ] Phase 6: Quality (Maria)                              │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 4: WORK                                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Real-time execution with TodoWrite tracking               │  │
│  │                                                             │  │
│  │  [✓] Phase 1: Requirements (30 min actual, 30 min planned) │  │
│  │  [⚙️ ] Phase 2: Database (in progress, 22/45 min)          │  │
│  │  [⚙️ ] Phase 3: Backend (in progress, 38/70 min)           │  │
│  │  [⚙️ ] Phase 4: Frontend (in progress, 29/60 min)          │  │
│  │  [ ] Phase 5: Integration                                  │  │
│  │  [ ] Phase 6: Quality                                      │  │
│  │                                                             │  │
│  │  Statusline: 🤖 3 agents working in parallel (56% done)    │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
    ↓
All Phases Complete ✓
    ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 5: CODIFY                                                 │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Automatic Learning Extraction (Stop Hook)                  │  │
│  │                                                             │  │
│  │  Patterns Extracted:                                        │  │
│  │  ├─ OAuth Flow: Authorization code with PKCE               │  │
│  │  ├─ Provider Callbacks: Google, GitHub handling            │  │
│  │  ├─ Token Storage: Secure cookie with httpOnly             │  │
│  │  ├─ State Validation: CSRF protection                      │  │
│  │  └─ Error Handling: User-friendly OAuth errors             │  │
│  │                                                             │  │
│  │  Lessons Learned:                                           │  │
│  │  ├─ "OAuth state parameter must be random + verified"      │  │
│  │  ├─ "Provider tokens should be encrypted at rest"          │  │
│  │  └─ "Add 20 min buffer for OAuth provider quirks"          │  │
│  │                                                             │  │
│  │  Stored to RAG with tags:                                  │  │
│  │  • agent: marcus-backend, james-frontend                   │  │
│  │  • category: security, authentication, integration         │  │
│  │  • effectiveness: 89% (feature delivered on time)          │  │
│  │                                                             │  │
│  │  Completion Report:                                         │  │
│  │  • Planned: 195 min                                        │  │
│  │  • Actual: 208 min                                         │  │
│  │  • Variance: +7% (within ±20% target)                      │  │
│  │  • Quality: 91%                                            │  │
│  │  • Compounding Score: 79/100                               │  │
│  │    → Next OAuth feature will be ~32% faster!               │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Result: OAuth feature complete with learnings codified to RAG
Next Feature: "SAML SSO" will reuse OAuth patterns → 40% faster!
```

---

### 4. Agent Communication Flow

```
┌──────────────────────────────────────────────────────────────────┐
│  Agent Communication & Handoffs                                  │
└──────────────────────────────────────────────────────────────────┘

Feature Request: "User profile with avatar upload"
    ↓
┌─────────────────────────────────────────────────────────────────┐
│  Alex-BA (auto-activates)                                       │
│  ├─ Analyzes requirements                                       │
│  ├─ Creates user stories                                        ���
│  ├─ Defines API contract                                        │
│  └─ Hands off to → Sarah-PM                                     │
└─────────────────────────────────────────────────────────────────┘
    ↓ (handoff with full context)
┌─────────────────────────────────────────────────────────────────┐
│  Sarah-PM (coordinates)                                         │
│  ├─ Detects: Full-stack feature (3 agents needed)               │
│  ├─ Plans parallel execution                                    │
│  └─ Delegates to → Dana, Marcus, James (parallel)               │
└─────────────────────────────────────────────────────────────────┘
    ↓ (parallel execution)
┌────────────────┐    ┌────────────────┐    ┌──────────────────┐
│ Dana-Database  │    │ Marcus-Backend │    │ James-Frontend   │
├────────────────┤    ├────────────────┤    ├──────────────────┤
│ • avatar_url   │    │ POST /upload   │    │ AvatarUpload     │
│ • file storage │◄───┤ (with mocks)   │◄───┤ (with mocks)     │
│ • constraints  │    │ S3 integration │    │ File validation  │
└────────────────┘    └────────────────┘    └──────────────────┘
    ↓                      ↓                      ↓
    └──────────────────────┴──────────────────────┘
                          ↓ (all complete, hand to Maria)
┌─────────────────────────────────────────────────────────────────┐
│  Maria-QA (validates)                                           │
│  ├─ Tests: Unit + Integration + E2E                             │
│  ├─ Coverage: 84% ✓                                             │
│  ├─ Security: File type validation ✓                            │
│  ├─ Accessibility: Alt text required ✓                          │
│  └─ Hands off to → Sarah-PM (for final report)                  │
└─────────────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────────────┐
│  Sarah-PM (reports)                                             │
│  ├─ Feature complete ✓                                          │
│  ├─ Time: 2.1 hours (planned: 2.5h, 16% under!)                 │
│  ├─ Quality: 92%                                                │
│  └─ Ready for deployment                                        │
└─────────────────────────────────────────────────────────────────┘

Key Communication Mechanisms:
1. Context Passing: Full requirements + API contracts shared
2. Mocks: Agents use mocks during parallel work, real integration after
3. Quality Gates: Maria validates before hand-off to Sarah
4. Progress Updates: StatusLine shows real-time agent activity
```

---

## Common Workflows

### Workflow 1: Bug Fix

```bash
# User reports bug: "Login fails with special characters"

┌─────────────────────────────────────────┐
│ 1. Marcus-Backend auto-activates        │
│    (detects: bug in auth.api.ts)        │
│    ├─ Analyzes code                     │
│    ├─ Identifies: Missing input sanitization
│    └─ Fixes validation logic            │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│ 2. Maria-QA auto-activates              │
│    (detects: code change in API)        │
│    ├─ Adds test case for special chars  │
│    ├─ Runs regression tests             │
│    └─ Validates security (SQL injection)│
└─────────────────────────────────────────┘
    ↓
Quality Gates Pass ✓
    ↓
Bug Fixed (15 minutes)
```

### Workflow 2: Refactoring

```bash
# User: "Refactor authentication to use middleware"

┌─────────────────────────────────────────┐
│ 1. Marcus-Backend auto-activates        │
│    ├─ Extracts auth logic to middleware │
│    ├─ Updates all route handlers        │
│    └─ Maintains API contracts           │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│ 2. Maria-QA auto-activates              │
│    ├─ Validates: No breaking changes    │
│    ├─ Tests: Same behavior maintained   │
│    └─ Coverage: Still at 87%            │
└─────────────────────────────────────────┘
    ↓
Refactoring Complete (45 minutes)
```

### Workflow 3: Database Migration

```bash
# User: "Add email verification to users"

┌─────────────────────────────────────────┐
│ 1. Dana-Database auto-activates         │
│    ├─ Creates migration: add email_verified
│    ├─ Adds index on email_verified      │
│    └─ Updates RLS policies              │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│ 2. Marcus-Backend auto-activates        │
│    ├─ Updates user model                │
│    ├─ Adds verification endpoint        │
│    └─ Generates email sending logic     │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│ 3. James-Frontend auto-activates        │
│    ├─ Adds "Verify Email" banner        │
│    ├─ Creates verification success page │
│    └─ Handles verification errors       │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│ 4. Maria-QA auto-activates              │
│    ├─ Tests: Email verification flow    │
│    ├─ Tests: Edge cases (expired links) │
│    └─ E2E: Complete user journey        │
└─────────────────────────────────────────┘
    ↓
Migration Complete (2 hours)
```

---

## Getting Started

### Step 1: Framework Setup (5 minutes)

```bash
# Install VERSATIL Framework
npm install -g versatil-sdlc-framework

# Initialize in your project
cd your-project
npm run init

# Framework auto-detects your tech stack
# → Configures agents automatically
# → Sets up quality gates
# → Creates test templates
```

### Step 2: Start the Daemon (1 minute)

```bash
# Start proactive agent system
versatil-daemon start

# Agents now work in background
# → Auto-activate based on file changes
# → Real-time feedback in statusline
# → Quality gates enforce before commits
```

### Step 3: Start Coding (immediately)

```bash
# Just code normally!
# No slash commands needed.

# Example: Create a test file
touch src/components/LoginForm.test.tsx

# → Maria-QA auto-activates
# → Suggests test structure
# → Shows coverage in statusline
```

### Step 4: Monitor Progress

```bash
# View agent activity
npm run monitor

# Interactive dashboard
npm run dashboard

# Health check
npm run doctor
```

---

## Advanced Usage

### Manual Agent Activation (if needed)

While agents work proactively, you can manually activate them:

```bash
# Activate specific agent
/maria review test coverage

# Multi-agent collaboration
/collaborate marcus james "API integration"

# Emergency protocols
/emergency "Critical production issue"
```

### Plan Mode for Complex Features

For complex features, use Plan Mode:

```bash
# Activate Plan Mode
/plan "Implement OAuth authentication with Google and GitHub"

# Sarah-PM generates detailed plan:
# → Phase breakdown
# → Time estimates (RAG-enhanced)
# → Agent assignments
# → Risk assessment

# You approve the plan
# → Agents execute automatically
# → TodoWrite tracks progress
# → Real-time statusline updates
```

### Compounding Engineering Workflow

```bash
# After completing a feature
# Stop hook auto-runs learning codification

# Or manually trigger:
/learn feature/user-authentication

# Extracts patterns → Stores in RAG → Next feature faster!
```

### Quality Gate Configuration

```bash
# View current quality gates
cat .versatil/quality-gates.json

# Adjust thresholds
{
  "testCoverage": { "threshold": 80 },
  "securityGrade": { "minimum": "A" },
  "accessibility": { "level": "WCAG 2.1 AA" },
  "performance": { "p95": 200 }
}
```

---

## Troubleshooting

### Issue: Agent Not Activating

**Symptoms**: Editing a file but agent doesn't activate

**Solutions**:
1. Check daemon status: `versatil-daemon status`
2. Restart daemon: `versatil-daemon restart`
3. Check file patterns: `/help [agent-name]`
4. View activation logs: `tail -f ~/.versatil/logs/activation.log`

### Issue: Quality Gate Failing

**Symptoms**: "Quality gate failed: Test coverage 72% < 80%"

**Solutions**:
1. Run Maria-QA: `/maria generate missing tests`
2. Check coverage: `npm run test:coverage`
3. Add tests for uncovered code
4. Re-run quality gates: `npm run validate`

### Issue: Parallel Execution Conflicts

**Symptoms**: Dana and Marcus both editing same file

**Solutions**:
1. Rule 1 handles collision detection automatically
2. Check conflict log: `~/.versatil/logs/conflicts.log`
3. Manual resolution if needed
4. Re-run: `npm run validate`

### Issue: MCP Not Working

**Symptoms**: "MCP connection failed: GitHub"

**Solutions**:
1. Check MCP health: `npm run mcp:health`
2. Validate credentials: Check `~/.versatil/.env`
3. Test specific MCP: `node scripts/mcp-health-check.cjs github`
4. See troubleshooting: `/help mcp-troubleshooting`

### Issue: Slow Performance

**Symptoms**: Agents taking longer than expected

**Solutions**:
1. Check framework health: `npm run monitor`
2. Review performance metrics: `npm run dashboard`
3. Optimize database: Run Dana's query optimizer
4. Check system resources: `top`

---

## Best Practices

### 1. Let Agents Work Proactively

```bash
# ✅ Good: Just code, agents auto-activate
touch src/LoginForm.test.tsx
# → Maria-QA activates automatically

# ❌ Bad: Manually calling agents when not needed
/maria review tests  # Not necessary, Maria auto-activates
```

### 2. Use Three-Tier for Full-Stack Features

```bash
# ✅ Good: Let Dana, Marcus, James work in parallel
"Add user profile with avatar upload"
# → All 3 agents work simultaneously

# ❌ Bad: Sequential execution
"First create database schema" (wait)
"Then create API" (wait)
"Then create UI"
# → Loses 43% time savings
```

### 3. Trust Quality Gates

```bash
# ✅ Good: Fix issues found by quality gates
# Coverage 72% < 80% → Add tests
# Security Grade C → Fix headers
# Accessibility fails → Add ARIA labels

# ❌ Bad: Bypass quality gates
# Pushing to production with failing gates
```

### 4. Leverage Compounding Engineering

```bash
# ✅ Good: Let stop hook codify learnings
# Session ends → Patterns stored to RAG
# Next session → 40% faster

# ❌ Bad: Clear .versatil directory
# Loses all learned patterns
```

### 5. Use Plan Mode for Complex Tasks

```bash
# ✅ Good: Plan Mode for multi-agent features
/plan "OAuth with Google, GitHub, SAML"
# → Get detailed plan, time estimates, risk assessment

# ❌ Bad: Jump into complex features without planning
# → Higher risk of rework, missed requirements
```

---

## Quick Reference

### Agent Activation Patterns

| File Pattern | Agent | Example |
|--------------|-------|---------|
| `*.test.*` | Maria-QA | `LoginForm.test.tsx` |
| `*.api.*` | Marcus-Backend | `auth.api.ts` |
| `*.tsx` | James-Frontend | `Button.tsx` |
| `*.sql` | Dana-Database | `001_create_users.sql` |
| `requirements/**` | Alex-BA | `requirements/auth.md` |
| `*.md` (docs) | Sarah-PM | `docs/sprint-42.md` |
| `*.py` (ML) | Dr.AI-ML | `models/recommender.py` |
| `**/mcp/**` | Oliver-MCP | `mcp/github-integration.ts` |

### Key Commands

```bash
# Monitoring
npm run monitor              # Quick health check
npm run dashboard            # Interactive dashboard
npm run doctor               # Auto-fix issues

# Testing
npm run test:coverage        # Test coverage report
npm run test:visual:percy    # Visual regression
npm run security:scan        # Security scan

# Validation
npm run validate             # Full validation
npm run validate:activation  # Agent activation check
npm run validate:percy       # Percy integration check
npm run validate:rag         # RAG integrity check

# MCP
npm run mcp:setup            # Interactive MCP setup
npm run mcp:health           # MCP health check

# Help
/help                        # Main help menu
/help agents                 # All 18 agents
/help workflows              # EVERY, Three-Tier, Instinctive
/help troubleshooting        # Common issues
```

### StatusLine Indicators

```bash
# Agent Activity
🤖 Maria-QA analyzing...        # Single agent working
🤖 3 agents working in parallel # Parallel execution

# Progress
████████░░ 80% coverage        # Test coverage
⏱️  180ms response             # Performance metric

# Warnings
⚠️  2 missing tests            # Quality issue
⚠️  Missing aria-label         # Accessibility issue

# Success
✅ All quality gates passed    # Ready to merge
```

---

## Summary

### OPERA in 60 Seconds

1. **18 Specialized Agents** - 8 core + 10 sub-agents
2. **Proactive Activation** - Agents work automatically, no commands
3. **Parallel Execution** - 43% time savings on full-stack features
4. **Quality-First** - All changes validated before merge
5. **Compounding Engineering** - Each feature makes next 40% faster

### Getting Started Checklist

- [ ] Install framework: `npm install -g versatil-sdlc-framework`
- [ ] Initialize: `npm run init`
- [ ] Start daemon: `versatil-daemon start`
- [ ] Code normally: Agents auto-activate
- [ ] Monitor: `npm run dashboard`

### Next Steps

- Read: `/help quick-start` for 5-minute guide
- View: `/help agents` for all 18 agents
- Learn: `/help workflows` for VELOCITY workflow
- Troubleshoot: `/help troubleshooting` for issues

---

**VERSATIL SDLC Framework v6.5.0**
**98% Complete | Production-Ready**
**Documentation**: https://docs.versatil.dev
**Support**: https://github.com/versatil-sdlc-framework/issues
