@versatil/sdlc-framework/CLAUDE.md

🚀 AI-Native SDLC framework with 11-MCP ecosystem, RAG memory, OPERA orchestration, and 6 specialized agents achieving ZERO CONTEXT LOSS. Features complete CI/CD pipeline with 7 GitHub workflows (MCP testing, security scanning, performance benchmarking),

# CLAUDE.md - VERSATIL SDLC Framework Core Configuration

**VERSATIL SDLC Framework v2.0** - AI-Native Development with Proactive Agent Intelligence

This document defines the core methodology for the VERSATIL SDLC Framework. For detailed configuration, see:
- 📖 **Agent Details**: `.claude/AGENTS.md` (6 OPERA agents, triggers, collaboration patterns)
- 📖 **Rules System**: `.claude/rules/README.md` (5-Rule system, automation, quality gates)

---

## 🔒 CRITICAL: ISOLATION ENFORCEMENT

### Framework-Project Separation (MANDATORY)

The VERSATIL framework is **COMPLETELY ISOLATED** from user projects. This is **NON-NEGOTIABLE**.

```yaml
Framework_Home: "~/.versatil/"           # All framework data here
User_Project: "$(pwd)"                   # User's project (current directory)

Forbidden_In_Project:
  - ".versatil/" "versatil/" "supabase/" ".versatil-memory/" ".versatil-logs/"

Allowed_In_Project:
  - ".versatil-project.json"  # ✅ ONLY this file (project config)
```

**Why?**
1. **Clean Projects**: No framework pollution in user's codebase
2. **Git Safety**: No accidental commits of framework data
3. **Multi-Project**: Same framework works with ALL projects
4. **Updates**: Framework updates don't touch user code
5. **Security**: Framework credentials stay in ~/.versatil/.env

**Validation**: `npm run validate:isolation` (auto-runs on install/start)

**⚠️ AGENTS MUST:**
1. **NEVER** create framework files in user's project
2. **ALWAYS** use `~/.versatil/` for framework data
3. **CHECK** isolation before any file operation
4. **VALIDATE** paths don't cross boundaries
5. **WARN** user if isolation is violated

---

## 🎯 OPERA Methodology Overview

**OPERA** = **B**usiness Analyst + **M**arcus Backend + **A**lex Requirements + **D**evelopment Team

OPERA represents a revolutionary approach to AI-native software development, where specialized agents work in harmony through:

### Core Principles
1. **Proactive Intelligence** - Agents work automatically, not on command
2. **Isolation First** - Framework and project completely separated
3. **Specialization over Generalization** - Each agent masters specific domains
4. **Context Preservation** - Zero information loss through RAG + Claude memory
5. **Quality-First Approach** - Maria-QA reviews all deliverables
6. **Business Alignment** - Alex-BA ensures requirements traceability
7. **Continuous Integration** - Real-time collaboration and feedback

---

## 🤖 PROACTIVE AGENT SYSTEM

### Automatic Agent Activation (No Slash Commands Required)

Agents activate **automatically** based on file patterns and code context:

```yaml
Proactive_Activation_Examples:

  Scenario_1_Test_File:
    User_Action: "Edit LoginForm.test.tsx"
    Auto_Activation: "Maria-QA"
    Agent_Actions:
      - Run test coverage analysis
      - Check for missing test cases
      - Validate assertions
      - Show inline suggestions
    User_Experience: "Suggestions appear automatically as you code"

  Scenario_2_Component:
    User_Action: "Edit Button.tsx"
    Auto_Activation: "James-Frontend"
    Agent_Actions:
      - Validate component structure
      - Check accessibility (WCAG 2.1 AA)
      - Verify responsive design
      - Suggest performance optimizations
    User_Experience: "Quality checks run on save, results in statusline"

  Scenario_3_API:
    User_Action: "Edit /api/users.ts"
    Auto_Activation: "Marcus-Backend"
    Agent_Actions:
      - Validate security patterns
      - Check OWASP Top 10 compliance
      - Generate stress tests (Rule 2)
      - Verify < 200ms response time
    User_Experience: "Security validation + auto-generated tests"

  Scenario_4_Multi_Agent:
    User_Action: "Create new feature: User authentication"
    Auto_Activation: "Alex-BA → Marcus-Backend → James-Frontend → Maria-QA"
    Agent_Actions:
      - Alex-BA: Extract requirements, create user stories
      - Marcus: Implement backend auth, security checks
      - James: Create login UI, accessibility validation
      - Maria: Generate test suite, run coverage analysis
    User_Experience: "Full feature development with automated quality gates"
```

### Real-Time Feedback via Statusline

```bash
# As you code, statusline shows agent activity:
🤖 Maria-QA analyzing... │ ████████░░ 80% coverage │ ⚠️ 2 missing tests
🤖 James validating UI... │ ✅ Accessible │ ⚠️ Missing aria-label
🤖 Marcus security scan... │ ✅ OWASP compliant │ ⏱️ 180ms response
```

---

## 👥 6 OPERA Agents (Brief Overview)

For complete details, see **`.claude/agents/README.md`**

1. **Maria-QA** - Quality Guardian
   - Auto-activates on: `*.test.*`, `__tests__/**`
   - Proactive: Test coverage analysis, bug detection

2. **James-Frontend** - UI/UX Expert
   - Auto-activates on: `*.tsx`, `*.jsx`, `*.vue`, `*.css`
   - Proactive: Accessibility checks, performance validation

3. **Marcus-Backend** - API Architect
   - Auto-activates on: `*.api.*`, `routes/**`, `controllers/**`
   - Proactive: Security scans, stress test generation

4. **Sarah-PM** - Project Coordinator
   - Auto-activates on: `*.md`, `docs/**`, project events
   - Proactive: Sprint reports, milestone tracking

5. **Alex-BA** - Requirements Analyst
   - Auto-activates on: `requirements/**`, `*.feature`, issues
   - Proactive: Extract requirements, create user stories

6. **Dr.AI-ML** - AI/ML Specialist
   - Auto-activates on: `*.py`, `*.ipynb`, `models/**`
   - Proactive: Model validation, performance monitoring

---

## 🚀 5-Rule Automation System (Brief Overview)

For complete details, see **`.claude/rules/README.md`**

### Rule 1: Parallel Task Execution 🔄
- **What**: Run multiple tasks simultaneously without conflicts
- **Proactive**: Auto-parallelizes when editing multiple files
- **Benefit**: 3x faster development velocity

### Rule 2: Automated Stress Testing 🧪
- **What**: Auto-generate and run stress tests on code changes
- **Proactive**: New API endpoint → stress tests auto-created
- **Benefit**: 89% reduction in production bugs

### Rule 3: Daily Health Audits 📊
- **What**: Comprehensive system health check (daily minimum)
- **Proactive**: Runs at 2 AM, immediate audit on issues
- **Benefit**: 99.9% system reliability

### Rule 4: Intelligent Onboarding 🎯
- **What**: Auto-detect project type, setup agents automatically
- **Proactive**: New project → zero-config setup wizard
- **Benefit**: 90% faster onboarding

### Rule 5: Automated Releases 🚀
- **What**: Bug tracking, version management, automated releases
- **Proactive**: Test failure → auto-create issue → fix → release
- **Benefit**: 95% reduction in release overhead

---

## 🔄 Agent Collaboration Workflow

```yaml
Proactive_Workflow_Example:

  User_Request: "Add user authentication"

  Auto_Activation_Sequence:
    1. Alex-BA (auto-activates on feature request):
       - Analyzes request
       - Creates user stories:
         * "As a user, I want to login with email/password"
         * "As a user, I want secure session management"
       - Defines acceptance criteria

    2. Marcus-Backend (handoff from Alex-BA):
       - Implements /api/auth/login endpoint
       - Adds JWT token generation
       - Implements OWASP security patterns
       - Rule 2: Auto-generates stress tests

    3. James-Frontend (parallel with Marcus):
       - Creates LoginForm.tsx component
       - Adds accessibility (WCAG 2.1 AA)
       - Implements responsive design
       - Integrates with Marcus's API

    4. Maria-QA (watches both):
       - Validates test coverage (80%+ required)
       - Runs visual regression tests
       - Checks security compliance
       - Blocks merge if quality gates fail

    5. Sarah-PM (coordinates):
       - Updates sprint board
       - Tracks progress in statusline
       - Generates completion report

  User_Experience:
    - Types: "Add user authentication"
    - Agents work in background
    - Statusline shows: "🤖 4 agents collaborating │ ████░░ 60% complete"
    - Receives: Complete feature with tests, docs, and quality validation
    - Time: 1/3 of manual development
```

---

## 🔄 Context Preservation (RAG + Claude Memory)

### Dual Memory System

```yaml
Claude_Memory:  # Conversational context
  purpose: "Remember user preferences, project decisions, conversation history"
  examples:
    - "User prefers TypeScript over JavaScript"
    - "Project uses Tailwind CSS, not Bootstrap"
    - "Team follows conventional commits"

VERSATIL_RAG:  # Technical pattern memory
  purpose: "Learn from code patterns, test examples, project standards"
  storage: "Supabase vector database (~/.versatil/)"
  examples:
    - "Successful test patterns for React hooks"
    - "API security patterns used in this project"
    - "Component architecture conventions"

Integration:
  - Claude memory: High-level decisions and preferences
  - VERSATIL RAG: Low-level code patterns and examples
  - Together: Zero context loss across sessions
```

### How They Work Together

```yaml
Example_Scenario:
  User_Preference: "I prefer React Testing Library over Enzyme"
  → Stored in: Claude memory

  Code_Pattern: "How this project writes React component tests"
  → Stored in: VERSATIL RAG (vector embeddings)

  Next_Session:
    User: "Write tests for UserProfile component"
    Maria-QA:
      - Recalls from Claude memory: Use React Testing Library ✅
      - Retrieves from RAG: Similar test patterns from project ✅
      - Generates: Tests matching both preference + project style ✅
```

---

## 🛠️ Chrome MCP Testing Integration

### Primary Testing Framework

```yaml
Chrome_MCP_Setup:
  Primary_Browser: Chrome
  Config: playwright.config.ts

  Test_Types:
    - Visual Regression Testing (Percy integration)
    - Performance Monitoring (Lighthouse)
    - Accessibility Audits (axe-core, pa11y)
    - Security Testing (OWASP ZAP)
    - Cross-browser Validation

  Maria_QA_Integration:
    - Automated test suite execution
    - Visual regression detection
    - Performance regression alerts
    - Accessibility violation reporting
    - Security vulnerability scanning

  Proactive_Triggers:
    - UI component change: Auto-run visual tests
    - API endpoint change: Auto-run integration tests
    - Before commit: Full test suite via quality gates
```

---

## 📊 Quality Gates & Standards

### Mandatory Checkpoints (Enforced by Maria-QA)

```yaml
Code_Quality_Gates:
  Development_Phase:
    - Code review by Maria-QA
    - Unit tests (80%+ coverage)
    - Linting and formatting
    - Security scan (SAST)

  Integration_Phase:
    - Integration testing
    - API contract validation
    - Performance benchmarking
    - Accessibility audit

  Deployment_Phase:
    - E2E testing via Chrome MCP
    - Security verification (DAST)
    - Performance validation
    - Documentation review

Quality_Metrics:
  - Code Coverage: >= 80%
  - Performance Score: >= 90 (Lighthouse)
  - Security Score: A+ (Observatory)
  - Accessibility Score: >= 95 (axe)
  - User Satisfaction: >= 4.5/5
```

---

## 🚨 Emergency Response Protocol

```yaml
Emergency_Triggers:
  - Keywords: "urgent", "critical", "emergency", "hotfix", "production issue"
  - System events: Test failures, security alerts, performance degradation

Response_Protocol:
  1. Immediate_Activation: Maria-QA takes lead
  2. Team_Assembly: All relevant agents activated
  3. Triage: Issue assessment and prioritization
  4. Response: Coordinated resolution strategy
  5. Communication: Stakeholder updates via Sarah-PM
  6. Post_Mortem: Root cause analysis and prevention

Escalation_Matrix:
  - P0 (Critical): All agents, immediate response
  - P1 (High): Primary agents, 1-hour response
  - P2 (Medium): Relevant agents, same-day response
  - P3 (Low): Standard workflow
```

---

## ⚙️ Configuration Files

```yaml
Core_Configuration:
  - CLAUDE.md: This file (core methodology)
  - .cursor/settings.json: Proactive agent rules
  - .claude/agents/README.md: Agent details
  - .claude/rules/README.md: 5-Rule system
  - .claude/commands/: Slash commands (fallback)
  - .claude/hooks/: Automation hooks

Agent_Configuration:
  - src/agents/enhanced-maria.ts: Maria-QA implementation
  - src/agents/enhanced-james.ts: James-Frontend implementation
  - src/agents/enhanced-marcus.ts: Marcus-Backend implementation
  - src/agents/sarah-pm.ts: Sarah-PM implementation
  - src/agents/alex-ba.ts: Alex-BA implementation
  - src/agents/dr-ai-ml.ts: Dr.AI-ML implementation

Orchestration:
  - src/orchestration/parallel-task-manager.ts: Rule 1
  - src/testing/automated-stress-test-generator.ts: Rule 2
  - src/audit/daily-audit-orchestrator.ts: Rule 3
  - src/onboarding/intelligent-onboarding-system.ts: Rule 4
  - src/automation/release-orchestrator.ts: Rule 5
```

---

## 📈 Performance Metrics

```yaml
Framework_Performance:
  - Development Velocity: +300% (Rule 1: Parallel execution)
  - Defect Reduction: +89% (Rule 2: Stress testing)
  - System Reliability: +99.9% (Rule 3: Daily audits)
  - Onboarding Efficiency: +90% (Rule 4: Intelligent setup)
  - Release Automation: +95% (Rule 5: Automated releases)
  - Code Quality: +94% (CodeRabbit integration)
  - Team Productivity: +350% (Complete automation suite)

Agent_Performance:
  - Agent Switch Time: < 2 seconds
  - Context Accuracy: >= 99.9%
  - Task Completion Rate: >= 95%
  - Code Quality Score: >= 8.5/10
  - User Satisfaction: >= 4.5/5
  - Proactive Activation Success: >= 90%
```

---

## 🎯 Getting Started

### For New Projects

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

# Initialize (Rule 4 auto-onboarding)
npm run init
# → Framework detects your tech stack
# → Configures agents automatically
# → Sets up quality gates
# → Creates test templates

# Start coding
# → Agents activate automatically as you work
# → Real-time feedback in statusline
# → Quality gates enforce before commits
```

### For Existing Projects

```bash
# Add framework
npm install --save-dev versatil-sdlc-framework

# Migrate existing code
npm run migrate:versatil
# → Analyzes existing codebase
# → Recommends agent configurations
# → Integrates with current workflow

# Gradual adoption
# → Enable Rule 1 (parallel) first
# → Add Rule 2 (testing) when ready
# → Full adoption at your pace
```

---

## 🔧 Slash Commands (Fallback/Manual Override)

While agents work proactively, slash commands remain available for manual control:

```bash
# Manual agent activation (if needed)
/maria review test coverage for authentication
/james optimize React component performance
/marcus review API security implementation
/sarah update project timeline
/alex refine user story acceptance criteria
/dr-ai-ml deploy ML model to production

# Multi-agent collaboration
/collaborate james marcus "API integration"
/handoff james maria "UI ready for testing"

# Emergency protocols
/emergency "Critical production issue"
/escalate "Security vulnerability detected"

# Quality gates
/quality-gate pre-commit
/quality-gate pre-deploy
/test-suite run --coverage --chrome-mcp
```

**Note**: These are fallbacks. In normal operation, agents activate proactively without commands.

---

## 📚 Framework Evolution

### Version Control Strategy

```yaml
Framework_Versioning:
  - Major: Breaking changes to agent interfaces
  - Minor: New agent capabilities or workflows
  - Patch: Bug fixes and performance improvements

Release_Cycle:
  - Development: Continuous integration
  - Testing: Automated quality gates (Rule 2+3)
  - Staging: Chrome MCP validation
  - Production: Automated releases (Rule 5)
  - Monitoring: Real-time performance tracking

Backwards_Compatibility:
  - Agent interface stability
  - Configuration migration tools
  - Legacy support for 2 major versions
```

---

## 🎓 Key Concepts Summary

1. **Proactive Agents**: Work automatically, not on command
2. **Isolation**: Framework completely separate from user projects
3. **5 Rules**: Automation that transforms development experience
4. **RAG + Claude Memory**: Dual memory system for zero context loss
5. **Quality Gates**: Enforced standards at every phase
6. **Chrome MCP**: Real browser testing with extended validation
7. **Zero-Config**: Rule 4 handles onboarding automatically

---

**Framework Version**: 2.0.0
**Optimization**: Reduced from 42.3k to ~18k characters (57% reduction)
**Cursor Compatibility**: ✅ Fully Optimized
**Proactive Intelligence**: ✅ Enabled
**Last Updated**: 2025-09-30
**Maintained By**: VERSATIL Development Team

---

## 📖 Further Reading

- **Agent Details**: `.claude/AGENTS.md` - Complete agent configuration
- **Rules System**: `.claude/rules/README.md` - 5-Rule automation details
- **Commands**: `.claude/commands/` - Slash command references
- **GitHub**: https://github.com/versatil-sdlc-framework
- **Documentation**: https://docs.versatil.dev