Agentic Quality Engineering Fleet

AI-Driven Quality Engineering Automation

A distributed fleet of specialized AI agents for comprehensive software testing, quality assurance, and continuous validation.

Quick Start • Documentation • Contributing • Examples

---

🚀 Features

💰 Cost Optimization (v1.0.5)

• Multi-Model Router: 70% cost reduction through intelligent model selection
• 4+ AI Models: GPT-3.5, GPT-4, Claude Haiku, Claude Sonnet 4.5
• Smart Routing: Automatic complexity analysis and model selection
• Cost Tracking: Real-time monitoring with daily/monthly budgets
• Budget Alerts: Email, Slack, and webhook notifications
• Cost Forecasting: Predict future costs with 90% confidence
• ROI Dashboard: Track savings vs single-model baseline

📊 Real-Time Streaming (v1.0.5)

• Live Progress Updates: Real-time feedback for all operations
• Test Generation Streaming: See tests as they're created
• Test Execution Streaming: Live pass/fail updates
• Coverage Streaming: Real-time gap detection
• Progress Bars: Beautiful terminal progress visualization
• Cancellation Support: Stop operations mid-stream
• Event Piping: Chain multiple operations together

🤖 Autonomous Agent Fleet

• 16 Specialized QE Agents: Each agent is an expert in specific quality engineering domains
• AQE Hooks System: 100-500x faster coordination with zero external dependencies
• Intelligent Coordination: Event-driven architecture with automatic task distribution
• Scalable: From single developer projects to enterprise-scale testing infrastructure
• Self-Organizing: Agents autonomously coordinate testing strategies
• Type-Safe: Full TypeScript type checking and IntelliSense support

🧪 Comprehensive Testing

• AI-Powered Test Generation: Generate comprehensive test suites automatically
• Multi-Framework Support: Jest, Mocha, Cypress, Playwright, and more
• Parallel Execution: Execute thousands of tests concurrently with intelligent orchestration
• Real-Time Coverage Analysis: O(log n) algorithms for instant coverage gap detection

🎯 Quality Intelligence

• Smart Quality Gates: ML-driven quality assessment with risk scoring
• Security Scanning: SAST, DAST, dependency analysis, and container security
• Performance Testing: Load testing with k6, JMeter, and Gatling integration
• Visual Regression: AI-powered screenshot comparison and UI validation

⚡ Advanced Capabilities

• Flaky Test Detection: Statistical analysis with automatic stabilization
• API Contract Validation: Breaking change detection across versions
• Test Data Generation: 10,000+ realistic records per second
• Production Intelligence: Convert production incidents into test scenarios
• Chaos Engineering: Controlled fault injection for resilience testing

---

📦 Prerequisites & Installation

What's New in v1.0.5 (Coming November 2025)

Major Release - Cost Optimization & Streaming

💰 Multi-Model Router: Reduce AI costs by 70% through intelligent model selection 📊 Real-Time Streaming: Live progress updates for all long-running operations 🎯 Cost Tracking: Comprehensive budgeting and forecasting tools ⚡ Enhanced Reliability: Auto-retry, fallback chains, resource pooling 🔧 Zero Breaking Changes: 100% backward compatible with v1.0.4

Key Features:

• 4+ AI Models: GPT-3.5, GPT-4, Claude Haiku, Claude Sonnet 4.5
• Smart Routing: Automatic model selection based on task complexity
• Live Updates: Real-time progress for test generation, execution, and analysis
• Budget Management: Daily/monthly limits with automatic enforcement
• Cost Forecasting: Predict future costs with 90% confidence
• Savings Dashboard: Track cost savings vs single-model baseline

📚 Migration Guide • 💰 Cost Optimization Guide • 📊 Streaming Tutorial

Previous Release (v1.0.4)

Patch Release - October 8, 2025

🎯 Zero Warnings: Eliminated all deprecated npm dependency warnings ⚡ Better Performance: Migrated to better-sqlite3 for improved reliability 🏗️ Simplified Architecture: Synchronous database API, no callbacks needed

View Complete Changelog

Prerequisites

Before using Agentic QE, you must have:

Required

• Claude Code: Install from claude.ai/code
• Node.js: 18.0 or higher
• npm: 8.0 or higher

Optional (Advanced Features)

• Claude Flow: For optional MCP coordination features

  npm install -g @claude/flow
  # or
  npx claude-flow@alpha init --force
  

Note: AQE hooks system requires NO external dependencies. All coordination features are built-in with TypeScript.

Installation Steps

1. Install Claude Code globally or in your workspace

2. Install Agentic QE

   Global Installation (Recommended)

   npm install -g agentic-qe
   
   # Verify installation
   aqe --version
   

   Project Installation

   npm install --save-dev agentic-qe
   
   # Use with npx
   npx aqe init
   

3. Local Development

   git clone https://github.com/proffesor-for-testing/agentic-qe.git
   cd agentic-qe
   npm install
   npm run build
   npm link
   

System Requirements

• Memory: 2GB+ recommended for large test suites
• OS: Linux, macOS, Windows (via WSL2)
• Agent Execution: Via Claude Code's Task tool or MCP integration

---

⚡ Quick Start

1. Install & Setup MCP Integration

# Install Agentic QE
npm install -g agentic-qe

# Add MCP server to Claude Code
claude mcp add agentic-qe npx -y agentic-qe mcp:start

# Verify connection
claude mcp list

2. Initialize Your Project

# Initialize AQE Fleet in your project
cd your-project
aqe init

What it does:

• Creates .claude/agents/ with 16 specialized QE agent definitions
• Creates .claude/commands/ with 8 AQE slash commands
• Creates .agentic-qe/ configuration directory
• Updates or creates CLAUDE.md with integration documentation

3. Use from Claude Code CLI

# Ask Claude to generate tests using AQE agents
claude "Initialize AQE fleet and generate comprehensive tests for src/services/user-service.ts with 95% coverage"

Agent Execution Model:

• Agents are Claude Code agent definitions (markdown files in .claude/agents/)
• Executed via Claude Code's Task tool OR MCP tools
• MCP integration enables Claude to orchestrate QE agents directly
• NOT standalone Node.js processes

📖 Complete MCP Integration Guide - Detailed setup, examples, and use cases

Basic Commands

# Check fleet status
aqe status

# Generate tests for a module
aqe test src/services/user-service.ts

# Analyze test coverage
aqe coverage --threshold 95

# Run quality gate validation
aqe quality

# Execute comprehensive test suite
aqe execute --parallel --coverage

# View all commands
aqe help

Multi-Model Router Commands (v1.0.5)

# Enable cost-optimized routing (70-81% savings)
aqe routing enable

# View current configuration and savings
aqe routing status

# Launch real-time cost dashboard
aqe routing dashboard

# Generate detailed cost report
aqe routing report --format html --output report.html

# View routing statistics
aqe routing stats --days 30

# Disable routing
aqe routing disable

Example Output - aqe routing status:

✅ Multi-Model Router Status

Configuration:
  Status: ENABLED ✓
  Default Model: claude-sonnet-4.5
  Cost Tracking: ENABLED ✓
  Fallback Chains: ENABLED ✓

Cost Summary (Last 30 Days):
  Total Cost: $127.50
  Baseline Cost: $545.00
  Savings: $417.50 (76.6%)
  Budget Status: ON TRACK ✓

Model Usage:
  ├─ gpt-3.5-turbo: 42% (simple tasks)
  ├─ claude-haiku: 31% (medium tasks)
  ├─ claude-sonnet-4.5: 20% (complex tasks)
  └─ gpt-4: 7% (critical tasks)

📚 Complete Routing Examples - CLI and programmatic usage

Programmatic Usage

Basic Fleet Usage

import { FleetManager, QEAgentFactory } from 'agentic-qe';

// Initialize fleet
const fleet = new FleetManager({
  maxAgents: 20,
  topology: 'mesh'
});

await fleet.initialize();

// Spawn test generator agent
const testGen = await fleet.spawnAgent('test-generator', {
  targetCoverage: 95,
  framework: 'jest'
});

// Generate tests for a module
const tests = await testGen.execute({
  sourceFile: 'src/services/user-service.ts',
  testStyle: 'property-based'
});

With Multi-Model Router (v1.0.5)

import { FleetManager, AdaptiveModelRouter } from 'agentic-qe';

// Initialize fleet with cost-optimized routing
const fleet = new FleetManager({
  maxAgents: 20,
  topology: 'mesh',
  routing: {
    enabled: true,
    defaultModel: 'claude-sonnet-4.5',
    enableCostTracking: true,
    enableFallback: true,
    modelPreferences: {
      simple: 'gpt-3.5-turbo',      // 70% cheaper for simple tasks
      medium: 'claude-haiku',        // 60% cheaper for standard tests
      complex: 'claude-sonnet-4.5',  // Best quality/cost for complex
      critical: 'gpt-4'              // Maximum quality when needed
    },
    budgets: {
      daily: 50,
      monthly: 1000
    }
  }
});

await fleet.initialize();

// Spawn agent (automatically uses optimal model based on task complexity)
const testGen = await fleet.spawnAgent('test-generator', {
  targetCoverage: 95,
  framework: 'jest',
  useRouting: true  // Enable intelligent model selection
});

// Execute task (router selects cheapest model that meets quality requirements)
const tests = await testGen.execute({
  sourceFile: 'src/services/user-service.ts',
  testStyle: 'property-based'
});

// Check cost savings
const savings = await fleet.getRoutingSavings();
console.log(`💰 Total savings: $${savings.total} (${savings.percent}%)`);
console.log(`📊 Models used: ${JSON.stringify(savings.modelBreakdown, null, 2)}`);

📚 Complete Routing Examples - Advanced programmatic usage

---

🤖 Agent Types

Core Testing Agents

Agent	Purpose	Key Features
test-generator	AI-powered test creation	Property-based testing, edge case detection
test-executor	Multi-framework execution	Parallel processing, retry logic, reporting
coverage-analyzer	Real-time gap analysis	O(log n) algorithms, trend tracking
quality-gate	Intelligent validation	ML-driven decisions, risk assessment
quality-analyzer	Metrics analysis	ESLint, SonarQube, Lighthouse integration

Performance & Security

Agent	Purpose	Key Features
performance-tester	Load & stress testing	k6, JMeter, Gatling, bottleneck detection
security-scanner	Vulnerability detection	SAST, DAST, dependency scanning

Strategic Planning

Agent	Purpose	Key Features
requirements-validator	Testability analysis	INVEST criteria, BDD generation
production-intelligence	Incident replay	RUM analysis, anomaly detection
fleet-commander	Hierarchical coordination	50+ agent orchestration

Advanced Testing

Agent	Purpose	Key Features
regression-risk-analyzer	Smart test selection	ML patterns, AST analysis
test-data-architect	Realistic data generation	10k+ records/sec, GDPR compliant
api-contract-validator	Breaking change detection	OpenAPI, GraphQL, gRPC
flaky-test-hunter	Stability analysis	Statistical detection, auto-fix

Specialized

Agent	Purpose	Key Features
deployment-readiness	Release validation	Multi-factor risk scoring
visual-tester	UI regression	AI-powered comparison
chaos-engineer	Resilience testing	Fault injection, blast radius

---

🏗️ Architecture

Core Components

┌─────────────────────────────────────────────┐
│           Fleet Manager                      │
│  (Central Coordination & Task Distribution) │
└─────────────────────────────────────────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
   ┌────▼────┐ ┌───▼────┐ ┌───▼────┐
   │ Agent 1 │ │ Agent 2│ │ Agent N│
   │  Pool   │ │  Pool  │ │  Pool  │
   └────┬────┘ └───┬────┘ └───┬────┘
        │          │          │
   ┌────▼──────────▼──────────▼────┐
   │        Event Bus               │
   │  (Event-Driven Communication)  │
   └────┬──────────────────────┬────┘
        │                      │
   ┌────▼────┐           ┌────▼────┐
   │  Memory │           │Database │
   │  Store  │           │(SQLite) │
   └─────────┘           └─────────┘

Event-Driven Architecture

• EventBus: Real-time communication between agents
• Task Queue: Priority-based task scheduling
• Memory Store: Shared context and learning (SwarmMemoryManager)
• Persistence: SQLite for state, metrics, and audit trails

AQE Hooks System

Zero Dependencies - Built-in TypeScript hooks for agent coordination:

// Automatic lifecycle hooks in every agent (aqe-hooks protocol)
class QEAgent extends BaseAgent {
  protected async onPreTask(data): Promise<void> { /* prepare */ }
  protected async onPostTask(data): Promise<void> { /* validate */ }
  protected async onTaskError(data): Promise<void> { /* recover */ }
}

// Advanced verification hooks
const hookManager = new VerificationHookManager(memoryStore);
await hookManager.executePreTaskVerification({ task, context });
await hookManager.executePostTaskValidation({ task, result });

Performance: 100-500x faster than external hooks (<1ms vs 100-500ms)

Features:

• Full TypeScript type safety
• Direct SwarmMemoryManager integration
• Built-in RollbackManager support
• EventBus coordination
• Context engineering (pre/post tool-use bundles)

---

📖 Documentation

🆕 Phase 1 Features (v1.0.5)

• Multi-Model Router Guide - NEW! Save 70% on AI costs
• Streaming API Tutorial - NEW! Real-time progress updates
• Cost Optimization Best Practices - NEW! Maximize ROI
• Migration Guide v1.0.5 - NEW! Upgrade guide
• Routing API Reference - NEW! Complete API docs
• Streaming API Reference - NEW! Complete API docs
• Phase 1 Code Examples - NEW! Working examples

Getting Started

• Quick Start Guide
• User Guide - Comprehensive workflows and examples
• Agent Types Overview
• Configuration Guide - Complete configuration reference
• Troubleshooting Guide - Common issues and solutions

User Guides

• Test Generation
• Coverage Analysis
• Quality Gates
• Performance Testing
• Test Execution
• MCP Integration

Advanced Topics

• API Reference
• Agent Development
• MCP Integration
• Best Practices
• AQE Hooks Guide

Commands Reference

• AQE Commands Overview
• Command Specifications
• Hooks Architecture

---

🔧 Configuration

Environment Variables

Create a .env file in your project root:

# Fleet Configuration
FLEET_ID=my-project-fleet
MAX_AGENTS=20
HEARTBEAT_INTERVAL=30000

# Database
DB_TYPE=sqlite
DB_FILENAME=./data/fleet.db

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

# API (optional)
API_PORT=3000
API_HOST=localhost

Fleet Configuration

Create config/fleet.yaml:

fleet:
  id: "my-project-fleet"
  name: "My Project QE Fleet"
  maxAgents: 20
  topology: mesh

agents:
  test-executor:
    count: 3
    config:
      frameworks: [jest, cypress, playwright]
      maxParallelTests: 8
      timeout: 300000

  coverage-analyzer:
    count: 2
    config:
      targetCoverage: 95
      optimizationAlgorithm: sublinear

  quality-analyzer:
    count: 2
    config:
      tools: [eslint, sonarqube, lighthouse]
      thresholds:
        coverage: 80
        complexity: 10
        maintainability: 65

---

🧪 Examples

Test Generation

import { Task, TaskPriority } from 'agentic-qe';

// Generate comprehensive test suite
const generateTests = new Task(
  'test-generation',
  'Generate Tests for User Service',
  {
    sourceFile: './src/services/user-service.ts',
    framework: 'jest',
    coverage: 95,
    testTypes: ['unit', 'integration', 'property-based']
  },
  {},
  TaskPriority.HIGH
);

await fleet.submitTask(generateTests);

Quality Analysis

const qualityAnalysis = new Task(
  'quality-analysis',
  'Comprehensive Quality Check',
  {
    sourcePath: './src',
    tools: ['eslint', 'sonarqube', 'lighthouse'],
    thresholds: {
      coverage: 80,
      complexity: 10,
      security: 90
    }
  },
  {},
  TaskPriority.MEDIUM
);

Security Scanning

const securityScan = new Task(
  'security-scan',
  'SAST & DAST Security Analysis',
  {
    sourcePath: './src',
    scanTypes: ['sast', 'dast', 'dependency', 'container'],
    severity: 'high',
    compliance: ['OWASP-Top-10', 'CWE-Top-25']
  },
  {},
  TaskPriority.HIGH
);

More examples in examples/

---

🐳 Docker Deployment

Quick Start

# Start with SQLite (development)
docker-compose up -d

# Start with PostgreSQL (production)
docker-compose --profile postgres up -d

Production Deployment

# Configure production environment
cp .env.example .env.production
# Edit .env.production with secure credentials

# Deploy
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Docker Compose Configuration

version: '3.8'
services:
  agentic-qe:
    image: agentic-qe:latest
    environment:
      - FLEET_ID=prod-fleet
      - MAX_AGENTS=50
      - DB_TYPE=postgres
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    ports:
      - "3000:3000"

---

🚀 Development

Setup

# Clone repository
git clone https://github.com/proffesor-for-testing/agentic-qe.git
cd agentic-qe

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Available Scripts

Script	Description
npm run build	Compile TypeScript to JavaScript
npm run dev	Development mode with hot reload
npm test	Run all test suites
npm run test:unit	Unit tests only
npm run test:integration	Integration tests
npm run test:coverage	Generate coverage report
npm run lint	ESLint code checking
npm run lint:fix	Auto-fix linting issues
npm run typecheck	TypeScript type checking

Project Structure

agentic-qe/
├── src/
│   ├── agents/          # 16 agent implementations
│   ├── core/            # Core fleet management
│   │   ├── FleetManager.ts
│   │   ├── Agent.ts
│   │   ├── Task.ts
│   │   ├── EventBus.ts
│   │   └── MemoryManager.ts
│   ├── cli/             # Command-line interface
│   ├── mcp/             # Model Context Protocol server
│   ├── types/           # TypeScript type definitions
│   └── utils/           # Shared utilities
├── tests/               # Comprehensive test suites
│   ├── unit/
│   ├── integration/
│   ├── e2e/
│   └── performance/
├── examples/            # Usage examples
├── docs/                # Documentation
├── .claude/             # Agent & command definitions
│   ├── agents/          # 16 QE agent definitions
│   └── commands/        # 8 AQE slash commands
└── config/              # Configuration files

---

📊 Performance

• Test Generation: 1000+ tests/minute
• Parallel Execution: 10,000+ concurrent tests
• Coverage Analysis: O(log n) complexity
• Data Generation: 10,000+ records/second
• Agent Spawning: <100ms per agent
• Memory Efficient: <2GB for typical projects

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Commit your changes (git commit -m 'feat: add amazing feature')
7. Push to your branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Follow the existing code style
• Write comprehensive tests
• Update documentation
• Use conventional commits
• Ensure TypeScript types are accurate

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Built with TypeScript, Node.js, and better-sqlite3
• Inspired by autonomous agent architectures and swarm intelligence
• Integrates with Jest, Cypress, Playwright, k6, SonarQube, and more
• Compatible with Claude Code via Model Context Protocol (MCP)

---

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@agentic-qe.com

---

🗺️ Roadmap

Current (v1.0)

• ✅ 16 specialized QE agents
• ✅ Multi-framework test execution
• ✅ Real-time coverage analysis
• ✅ MCP integration

Planned (v1.1)

• 🔄 Cloud deployment support
• 🔄 GraphQL API
• 🔄 Web dashboard
• 🔄 CI/CD integrations (GitHub Actions, GitLab CI)

Future (v2.0)

• 📋 Machine learning for test prioritization
• 📋 Natural language test generation
• 📋 Self-healing test suites
• 📋 Multi-language support (Python, Java, Go)

---

Made with ❤️ by the Agentic QE Team

⭐ Star us on GitHub • 🐦 Follow on Twitter