proffesor-for-testing__agentic-qe/docs

Agentic QE Fleet Documentation

Comprehensive documentation for the Agentic Quality Engineering Fleet - An intelligent, distributed quality engineering system powered by AI agents.

---

📚 Table of Contents

• Overview
• Getting Started
• User Guides
• Reference Documentation
• Advanced Topics
• For Contributors
• Documentation Structure
• Contributing to Documentation

---

Overview

The Agentic QE Fleet is a revolutionary quality engineering system that combines:

• 🤖 16 Specialized AI Agents - Autonomous quality engineering experts
• ⚡ Sublinear Algorithms - O(log n) performance for massive scale
• 🧠 Claude Flow Integration - Proven coordination patterns
• 🚀 95% Coverage Target - AI-driven test generation and optimization
• ⚙️ Parallel Execution - Multi-framework test orchestration

Key Benefits

• 70% reduction in manual test creation time
• 80% improvement in defect detection accuracy
• 60% decrease in test maintenance overhead
• 50% faster quality feedback cycles
• 90% automation of routine QE tasks

Architecture at a Glance

┌─────────────────────────────────────────────────────────────┐
│                    Agentic QE Fleet                         │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Command    │  │     MCP      │  │   Execution  │      │
│  │   Interface  │──│ Coordination │──│    Engine    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│         │                  │                  │              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              16 Specialized Agents                    │   │
│  │  Test Gen • Coverage • Quality Gate • Performance    │   │
│  │  Security • Chaos • Visual • API Contract • Flaky    │   │
│  │  Regression • Requirements • Data Architect • Deploy │   │
│  │  Production Intelligence • Fleet Commander           │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

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

Installation Steps

1. Install Claude Code globally or in your workspace
2. (Optional) Install Claude Flow for advanced coordination:

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

3. The AQE agents use Claude Code's Task tool for execution
4. Agent definitions are located in .claude/agents/

Agent Execution Model:

• Agents are Claude Code agent definitions (markdown files in .claude/agents/)
• Executed via Claude Code's Task tool: Task("description", "prompt", "agent-type")
• NOT standalone Node.js processes
• Integration with Claude Code via MCP (Model Context Protocol)

---

Getting Started

🚀 Quick Start (5 Minutes)

1. Install the AQE CLI

   npm install -g agentic-qe
   

2. Initialize in your project

   cd /path/to/your/project
   aqe init
   

   What aqe init 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
   • Note: Agents are executed through Claude Code's Task tool, not as standalone processes

3. Run your first command

   aqe test user-service    # Generate tests
   aqe coverage             # Analyze coverage
   aqe status               # Check fleet status
   

📖 Essential Reading

Start with these documents in order:

1. Getting Started Guide (10 min read)

   • Complete beginner's guide with examples
   • Installation and setup
   • Your first tests

2. MCP Integration Guide (15 min read) ⭐ NEW!

   • Claude Code MCP server setup
   • Real-world use cases with examples
   • Orchestrating agents from CLI

3. AQE CLI Guide (5 min read)

   • Quick command reference
   • Common workflows
   • Troubleshooting basics

4. Fleet Specification (15 min read)

   • System architecture
   • Agent capabilities
   • Success metrics

5. Claude Code Integration (10 min read)

   • Using AQE in Claude Code
   • Project setup
   • Best practices

🎯 Common Use Cases

I want to...	Command	Documentation
Generate tests	aqe test <module>	Test Generation Guide
Analyze coverage	aqe coverage	Coverage Analysis Guide
Run quality checks	aqe quality	Quality Gates Guide
Performance testing	aqe benchmark	Performance Testing Guide
Execute all tests	aqe execute	Test Execution Guide
Check fleet status	aqe status	Fleet Management Guide

---

User Guides

Comprehensive guides for common workflows and tasks.

Test Generation

Quick Start:

aqe test user-service --type unit --framework jest

Learn More:

• Test Generation Best Practices (coming soon)
• AI-Driven Test Design (coming soon)
• Agent: QE Test Generator

Features:

• ✅ AI-powered test case generation
• ✅ Multi-framework support (Jest, Mocha, Pytest, JUnit)
• ✅ Edge case detection
• ✅ Contract-based testing
• ✅ Mutation testing integration

Coverage Analysis

Quick Start:

aqe coverage --threshold 95

Learn More:

• Coverage Gap Detection (coming soon)
• Sublinear Coverage Algorithms (coming soon)
• Agent: QE Coverage Analyzer

Features:

• ✅ O(log n) gap detection
• ✅ Intelligent test prioritization
• ✅ Branch coverage analysis
• ✅ Mutation score tracking
• ✅ Real-time visualization

Quality Gates

Quick Start:

aqe quality --enforce-gates

Learn More:

• Quality Gate Configuration (coming soon)
• CI/CD Integration (coming soon)
• Agent: QE Quality Gate

Features:

• ✅ Automated quality enforcement
• ✅ Customizable thresholds
• ✅ Multi-metric validation
• ✅ CI/CD blocking capabilities
• ✅ Detailed quality reports

Performance Testing

Quick Start:

aqe benchmark --duration 5m --users 1000

Learn More:

• Performance Test Design (coming soon)
• Load Testing Strategies (coming soon)
• Agent: QE Performance Tester

Features:

• ✅ Load and stress testing
• ✅ Real-time metrics collection
• ✅ Performance regression detection
• ✅ Scalability analysis
• ✅ Resource utilization tracking

Test Execution

Quick Start:

aqe execute --parallel --coverage

Learn More:

• Parallel Test Execution (coming soon)
• Test Orchestration (coming soon)
• Agent: QE Test Executor

Features:

• ✅ Parallel test execution
• ✅ Multi-framework orchestration
• ✅ Smart test scheduling
• ✅ Resource management
• ✅ Real-time reporting

Chaos Engineering

Quick Start:

aqe chaos --scenario network-failure

Learn More:

• Chaos Engineering Guide (coming soon)
• Agent: QE Chaos Engineer

Features:

• ✅ Network failure simulation
• ✅ Service degradation testing
• ✅ Resource exhaustion scenarios
• ✅ Data corruption testing
• ✅ Recovery validation

---

Reference Documentation

Complete technical reference for all AQE components.

Commands Reference

Primary Documentation:

• Slash Commands Specification (1,500 lines)

  • Complete specifications for 8 slash commands
  • Parameter definitions
  • Response formats
  • Error handling

• Commands Quick Reference (900 lines)

  • Developer quick reference
  • Common patterns
  • Usage examples

• Commands Implementation Guide (1,300 lines)

  • Implementation templates
  • Code patterns
  • Best practices

• Commands Index (Overview)

  • Navigation guide
  • Document structure
  • Quick links

Available Commands

Command	Description	Documentation
/aqe-generate	AI-powered test generation	Spec §2.1
/aqe-execute	Parallel test execution	Spec §2.2
/aqe-analyze	Coverage gap detection	Spec §2.3
/aqe-optimize	Test suite optimization	Spec §2.4
/aqe-report	Quality metrics reporting	Spec §2.5
/aqe-benchmark	Performance benchmarking	Spec §2.6
/aqe-chaos	Chaos testing scenarios	Spec §2.7
/aqe-fleet-status	Fleet health monitoring	Spec §2.8

Agent Specifications

16 Specialized Agents:

Week 1 Agents (P0 - Critical)

• QE Test Generator - AI-powered test generation
• QE Coverage Analyzer - Sublinear coverage analysis
• QE Test Executor - Parallel test orchestration

Week 2 Agents (P0 - Core)

• QE Quality Gate - Automated quality enforcement
• QE Performance Tester - Load and performance testing
• QE Security Scanner - Vulnerability detection

Week 3 Agents (P1 - Advanced)

• QE Chaos Engineer - Chaos testing scenarios
• QE Visual Tester - Visual regression testing
• QE API Contract Validator - API contract validation
• QE Flaky Test Hunter - Flaky test detection
• QE Regression Risk Analyzer - Regression risk analysis
• QE Requirements Validator - Requirements coverage
• QE Test Data Architect - Test data management

Week 4 Agents (P1 - Integration)

• QE Deployment Readiness - Deployment validation
• QE Production Intelligence - Production monitoring
• QE Fleet Commander - Fleet orchestration

API Reference

MCP Tools:

// Test Generation
mcp__agentic_qe__test_generate({
  path: string,
  type: "unit" | "integration" | "e2e",
  framework: "jest" | "mocha" | "pytest" | "junit"
})

// Test Execution
mcp__agentic_qe__test_execute({
  parallel: boolean,
  coverage: boolean,
  frameworks: string[]
})

// Coverage Analysis
mcp__agentic_qe__coverage_analyze({
  threshold: number,
  reportFormat: "json" | "html" | "lcov"
})

Full API Documentation:

• MCP Tools Reference (to be generated)
• Agent API Reference (to be generated)
• Hooks API Reference (to be generated)

Type System

• Type System Updates (Week 1) (17KB)
  • Core type definitions
  • Agent interfaces
  • Test execution types
  • Coverage analysis types

---

Advanced Topics

Deep dives into advanced features and architecture.

Claude Code Integration

Primary Documentation:

• CLAUDE.md Integration (6KB)
  • Automatic project setup
  • Agent usage in Claude Code
  • Best practices
  • Common pitfalls

Features:

• ✅ Automatic CLAUDE.md management
• ✅ Idempotent updates
• ✅ Target directory support
• ✅ Agent coordination via hooks

Usage in Claude Code:

// Spawn agents via Task tool
Task("Generate tests", "Create comprehensive test suite", "qe-test-generator")
Task("Analyze coverage", "Find gaps using O(log n) algorithms", "qe-coverage-analyzer")

// Or use MCP tools
mcp__agentic_qe__test_generate({ type: "unit", framework: "jest" })

Hooks Architecture

Primary Documentation:

• QE Hooks Architecture (59KB)
  • Hook system design
  • Event-driven coordination
  • Memory integration
  • Performance optimization

Hook Types:

• Pre-hooks: pre-task, pre-edit, pre-bash
• Post-hooks: post-task, post-edit, post-bash
• Session hooks: session-start, session-restore, session-end
• Notification hooks: notify, alert, report

Example Hook Usage:

# Before task execution
npx claude-flow@alpha hooks pre-task --description "Generate unit tests"

# After file modification
npx claude-flow@alpha hooks post-edit --file "tests/user.test.ts" --memory-key "aqe/tests/user"

# Session management
npx claude-flow@alpha hooks session-end --export-metrics true

Security Best Practices

Primary Documentation:

• [AI & Agentic Security Best Practices](./AI & Agentic Security Best Practices.md) (10KB)
  • Security principles
  • Threat models
  • Mitigation strategies
  • Compliance guidelines

Key Topics:

• 🔒 AI model security
• 🔒 Agent communication security
• 🔒 Data protection
• 🔒 Access control
• 🔒 Audit logging
• 🔒 Compliance (GDPR, SOC 2)

Architecture & Design

Primary Documentation:

• Commands Architecture Diagram (53KB)
  • System architecture
  • Data flow diagrams
  • Component interactions
  • Scalability patterns

Architecture Highlights:

┌─────────────────────────────────────────────────────────┐
│                   Command Layer                         │
│  /aqe-generate • /aqe-execute • /aqe-analyze • ...     │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                 MCP Coordination                        │
│  Agent Spawn • Task Orchestration • Memory Mgmt        │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                  Agent Fleet (16)                       │
│  Specialized agents with domain expertise              │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│             Sublinear Core Engine                       │
│  O(log n) algorithms • WASM acceleration               │
└─────────────────────────────────────────────────────────┘

Golden Documentation Technique

Primary Documentation:

• [Golden Documentation Technique](./Golden Documentation Technique.md) (3KB)
  • Documentation principles
  • Writing guidelines
  • Structure patterns
  • Quality standards

Principles:

• ✍️ Clear, concise, actionable
• 📊 Examples over explanations
• 🔗 Progressive disclosure
• ✅ Validation and testing
• 🔄 Continuous improvement

---

For Contributors

Resources for developers contributing to the Agentic QE Fleet.

Framework Documentation

Primary Documentation:

• Agentic QE Framework (2KB)
  • Framework overview
  • Core concepts
  • Extension points
  • Plugin architecture

Contributing to Framework:

1. Read the framework docs
2. Understand agent lifecycle
3. Follow type system conventions
4. Write comprehensive tests
5. Document all public APIs

Type System

Primary Documentation:

• Type System Updates (Week 1) (17KB)
  • Core interfaces
  • Type definitions
  • Generic patterns
  • Type safety guidelines

Key Types:

// Agent interface
interface QEAgent {
  name: string;
  capabilities: string[];
  execute(task: Task): Promise<TaskResult>;
  analyze(context: Context): Promise<Analysis>;
}

// Test execution interface
interface TestExecutor {
  framework: TestFramework;
  execute(tests: Test[]): Promise<TestResult[]>;
  parallel: boolean;
}

Architecture Diagrams

Primary Documentation:

• Commands Architecture Diagram (53KB)
  • Complete system architecture
  • Component diagrams
  • Data flow charts
  • Sequence diagrams

Development Workflow

1. Setup Development Environment

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

2. Run Tests

   npm test                  # Unit tests
   npm run test:integration  # Integration tests
   npm run test:coverage     # Coverage report
   

3. Code Quality

   npm run lint              # ESLint
   npm run typecheck         # TypeScript
   npm run format            # Prettier
   

4. Build and Deploy

   npm run build             # Production build
   npm run start             # Start MCP server
   

Contributing Guidelines

1. Read the Documentation

   • Start with Fleet Specification
   • Review Type System
   • Understand Hooks Architecture

2. Follow Code Standards

   • TypeScript strict mode
   • ESLint + Prettier
   • 90%+ test coverage
   • Comprehensive JSDoc comments

3. Submit Quality PRs

   • Clear description
   • Linked issues
   • Tests included
   • Documentation updated

4. Use Issue Templates

   • Bug reports
   • Feature requests
   • Documentation improvements

---

Documentation Structure

Complete overview of documentation organization.

Directory Structure

docs/
├── README.md                                    # This file - Navigation hub
│
├── 📖 Getting Started (Quick Start)
│   ├── AQE-CLI.md                              # CLI command reference
│   ├── CLAUDE-MD-INTEGRATION.md                # Claude Code integration
│   └── Agentic-QE-Framework.md                 # Framework overview
│
├── 📋 Reference Documentation (Complete Specs)
│   ├── Agentic-QE-Fleet-Specification.md       # Fleet architecture (18KB)
│   ├── QE-SLASH-COMMANDS-SPECIFICATION.md      # Command specs (34KB)
│   ├── QE-COMMANDS-INDEX.md                    # Command index (16KB)
│   ├── QE-COMMANDS-QUICK-REFERENCE.md          # Quick reference (17KB)
│   ├── QE-COMMANDS-IMPLEMENTATION-GUIDE.md     # Implementation (27KB)
│   ├── QE-COMMANDS-ARCHITECTURE-DIAGRAM.md     # Architecture (53KB)
│   └── TYPE-SYSTEM-UPDATES-WEEK1.md            # Type system (17KB)
│
├── 🏗️ Advanced Topics (Deep Dives)
│   ├── QE_HOOKS_ARCHITECTURE.md                # Hooks system (59KB)
│   ├── AI & Agentic Security Best Practices.md # Security (10KB)
│   └── Golden Documentation Technique.md        # Doc standards (3KB)
│
├── 📁 guides/ (User Guides - Coming Soon)
│   ├── test-generation.md
│   ├── coverage-analysis.md
│   ├── quality-gates.md
│   ├── performance-testing.md
│   ├── chaos-engineering.md
│   └── cicd-integration.md
│
├── 📁 api/ (API Reference - To Be Generated)
│   ├── mcp-tools.md
│   ├── agent-api.md
│   ├── hooks-api.md
│   └── type-reference.md
│
└── 📁 tutorials/ (Step-by-Step Tutorials - Coming Soon)
    ├── first-test-suite.md
    ├── advanced-coverage.md
    ├── custom-agents.md
    └── performance-optimization.md

Documentation by Role

For New Users:

1. AQE CLI Guide
2. Claude Code Integration
3. Commands Quick Reference

For Developers:

1. Fleet Specification
2. Type System Updates
3. Implementation Guide

For Architects:

1. Architecture Diagram
2. Hooks Architecture
3. Framework Overview

For Security Teams:

1. [Security Best Practices](./AI & Agentic Security Best Practices.md)
2. Fleet Specification - Security

Documentation Size Reference

Document	Lines	Size	Complexity
QE Hooks Architecture	2,000+	59KB	Advanced
Commands Architecture	1,800+	53KB	Advanced
Slash Commands Spec	1,500+	34KB	Intermediate
Implementation Guide	1,300+	27KB	Intermediate
Fleet Specification	800+	18KB	Beginner
Commands Quick Ref	900+	17KB	Beginner
Type System Updates	700+	17KB	Intermediate
Commands Index	600+	16KB	Beginner
Security Best Practices	400+	10KB	Intermediate
CLAUDE.md Integration	300+	6KB	Beginner
AQE CLI	250+	6KB	Beginner
Golden Doc Technique	150+	3KB	Beginner
Framework Overview	100+	2KB	Beginner

Total Documentation: ~5,100 lines, ~260KB

---

Contributing to Documentation

We welcome contributions to improve documentation!

How to Contribute

1. Report Issues

   • Unclear explanations
   • Missing information
   • Outdated content
   • Broken links

2. Submit Improvements

   • Fix typos and grammar
   • Add missing examples
   • Improve clarity
   • Add diagrams

3. Create New Content

   • User guides
   • Tutorials
   • API reference
   • Architecture docs

Documentation Standards

Follow the Golden Documentation Technique:

• Clear, concise, actionable
• Examples over explanations
• Progressive disclosure
• Validation and testing
• Continuous improvement

Writing Guidelines:

• Use Markdown formatting
• Include code examples
• Add diagrams where helpful
• Link to related docs
• Keep language simple
• Test all examples

Structure Guidelines:

• Start with overview
• Include table of contents
• Use consistent headings
• Add navigation aids
• Include examples
• Provide next steps

Documentation Review Process

1. Self Review

   • Check spelling and grammar
   • Verify all links work
   • Test all code examples
   • Ensure clarity

2. Peer Review

   • Request feedback
   • Address comments
   • Validate improvements

3. Final Approval

   • Documentation team review
   • Technical accuracy check
   • Style guide compliance

Maintenance

• Weekly: Review for accuracy
• Monthly: Update version info
• Quarterly: Comprehensive audit
• As Needed: Critical updates

---

Support & Community

Getting Help

• Documentation: Start here - you're in the right place!
• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Claude Flow: Main project documentation

Useful Links

• Project Repository: github.com/proffesor-for-testing/agentic-qe
• Claude Flow: github.com/ruvnet/claude-flow
• npm Package: npmjs.com/package/agentic-qe
• Change Log: CHANGELOG.md

---

Quick Links

Most Popular Docs

• AQE CLI Guide - Quick command reference
• Commands Quick Reference - Developer guide
• Fleet Specification - System overview

Essential Reference

• Slash Commands Spec - Complete command specs
• Type System - TypeScript definitions
• [Security Best Practices](./AI & Agentic Security Best Practices.md) - Security guide

Advanced Topics

• Hooks Architecture - Event-driven system
• Commands Architecture - System design
• Implementation Guide - Build guide

---

Last Updated: 2025-09-30 Version: 1.0.0 Status: Active Development ✅

Built with ❤️ by the Agentic QE Team