agentic-qe 1.3.3 → 1.3.5

package/README.md

@@ -5,411 +5,282 @@
 [![npm version](https://img.shields.io/npm/v/agentic-qe.svg)](https://www.npmjs.com/package/agentic-qe)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
 
-**Version 1.3.3** - Critical Database & MCP Server Fixes
+**Version 1.3.5** | [Changelog](CHANGELOG.md) | [Issues](https://github.com/proffesor-for-testing/agentic-qe/issues) | [Discussions](https://github.com/proffesor-for-testing/agentic-qe/discussions)
 
-> Enterprise-grade test automation with AI learning, comprehensive skills library (35 QE skills), and optional 70-81% cost savings through intelligent model routing (opt-in feature).
+> Enterprise-grade test automation with AI learning, comprehensive skills library (34 QE skills), and 85.7% cost savings through intelligent model routing.
 
-🧠 **20% Continuous Improvement** | 📚 **35 World-Class QE Skills** | 🎯 **100% Flaky Test Detection** | 💰 **70-81% Cost Savings (opt-in)** | 🔒 **100% CodeQL Resolution** | 🔧 **52 MCP Tools**
-
-[Quick Start](#quick-start) • [Documentation](docs/) • [Contributing](CONTRIBUTING.md) • [Examples](examples/)
+🧠 **20% Continuous Improvement** | 📚 **34 World-Class QE Skills** | 🎯 **100% Flaky Test Detection** | 💰 **85.7% Cost Savings** | 🔧 **54 MCP Tools**
 
 </div>
 
 ---
 
-## 🎉 What's New in v1.3.3
-
-**🐛 Critical Bug Fixes**: Fixed missing `memory_store` database table and MCP server startup issues. Fleet initialization now works correctly, and Claude Code MCP integration is reliable with all 52 tools available.
-
-### Key Fixes
-
-- **Database Schema**: Added missing `memory_store` table for persistent agent memory
-- **MCP Server**: Created standalone `aqe-mcp` binary + fixed module resolution
-- **Impact**: Smooth fleet initialization and reliable Claude Code integration
+## ⚡ Quick Start
 
-### Migration from v1.3.2
+### Install & Initialize
 
 ```bash
-npm install -g agentic-qe@latest
-rm -rf ./data/*.db ./.agentic-qe/*.db
-aqe init
-```
-
-Update Claude Code MCP config:
-```json
-{
-  "mcpServers": {
-    "agentic-qe": {
-      "command": "aqe-mcp",
-      "args": []
-    }
-  }
-}
-```
-
-### Previous Release (v1.3.2)
+# Install globally
+npm install -g agentic-qe
 
-**🔐 Security Release**: Fixed all 4 open CodeQL security alerts - achieving **100% alert resolution (26/26 fixed)**. Critical fixes include elimination of cryptographic randomness bias, enhanced prototype pollution prevention, and comprehensive security test coverage.
+# Initialize your project
+cd your-project
+aqe init
 
-### Previous Release (v1.3.1)
+# Add MCP server to Claude Code (optional)
+claude mcp add agentic-qe npx -y agentic-qe mcp:start
 
-**Critical Bug Fix**: Fixed `aqe init` command that was using hardcoded versions (1.0.5, 1.1.0) instead of reading from `package.json`. All generated config files now correctly sync with the package version.
+# Verify connection
+claude mcp list
+```
 
-### Previous Release (v1.3.0)
+### Use from Claude Code CLI
 
-### Security Hardening + Skills Expansion (Oct 23-24, 2025)
-**2 days of intensive development** | **Security hardening + 17 new skills** | **11,500+ lines of expert content**
+Ask Claude to use AQE agents directly from your terminal:
 
-#### 🎓 **60 Claude Skills Total (35 QE-Specific)**
+```bash
+# Generate comprehensive tests
+claude "Use qe-test-generator to create tests for src/services/user-service.ts with 95% coverage"
 
-**Phase 1: Original Quality Engineering Skills (18 skills)** - World-class v1.0.0 ✨
-- agentic-quality-engineering, holistic-testing-pact, context-driven-testing, exploratory-testing-advanced
-- risk-based-testing, test-automation-strategy, api-testing-patterns, performance-testing, security-testing
-- tdd-london-chicago, xp-practices, code-review-quality, refactoring-patterns, quality-metrics
-- bug-reporting-excellence, technical-writing, consultancy-practices
+# Run quality pipeline
+claude "Initialize AQE fleet: generate tests, execute them, analyze coverage, and run quality gate"
 
-**Phase 2: Expanded QE Skills Library (17 NEW skills)** - v1.0.0 🆕
-- **Testing Methodologies (6)**: regression-testing, shift-left-testing, shift-right-testing, test-design-techniques, mutation-testing, test-data-management
-- **Specialized Testing (9)**: accessibility-testing, mobile-testing, database-testing, contract-testing, chaos-engineering-resilience, compatibility-testing, localization-testing, compliance-testing, visual-testing-advanced
-- **Testing Infrastructure (2)**: test-environment-management, test-reporting-analytics
+# Detect flaky tests
+claude "Use qe-flaky-test-hunter to analyze the last 100 test runs and identify flaky tests"
+```
 
-**Total QE Skills: 35 (95%+ coverage of modern QE practices)** 🏆
-
-**Skill Optimization Achievements:**
-- ✅ 107 unique tags, 156 cross-references
-- ✅ Semantic versioning (v1.0.0)
-- ✅ 34x speedup with 13 parallel agents
-- ✅ Quality: 52% → 100% (+48%)
-
-**Claude Flow Integration Skills (25 skills)**
-- AgentDB: advanced, learning, memory-patterns, optimization, vector-search (5)
-- GitHub: code-review, multi-repo, project-management, release-management, workflow-automation (5)
-- Flow Nexus: neural, platform, swarm (3)
-- Advanced: hive-mind-advanced, hooks-automation, pair-programming, performance-analysis, sparc-methodology, skill-builder, stream-chain, swarm-advanced, swarm-orchestration, reasoningbank-agentdb, reasoningbank-intelligence, verification-quality (12)
-
-**Unified CLAUDE.md** - 72 Total Agents (18 QE + 54 Claude Flow)
-
-#### 🚀 **AgentDB Integration - Production Hardening**
-
-**Code Reduction: 2,290+ Lines Removed (95%)**
-- 900 lines: Custom QUIC → AgentDB QUIC sync (<1ms latency, TLS 1.3)
-- 800 lines: Custom neural → AgentDB learning plugins (9 RL algorithms)
-- 896 lines: Mixins removed (QUICCapableMixin, NeuralCapableMixin)
-- 590 lines: Wrapper removed (AgentDBIntegration)
-
-**Performance Improvements** ⚡
-- QUIC Latency: 6.23ms → <1ms (84% faster)
-- Vector Search: 150ms → 1ms (150x faster)
-- Neural Training: 1000ms → 10-100ms (10-100x faster)
-- Memory Usage: 512MB → 128-16MB (4-32x less)
-- Startup Time: 500ms → 300ms (40% faster)
-
-**Security Enhancements** 🔒
-- OWASP Compliance: 70% → 90%+ (+20 points)
-- Vulnerabilities Fixed: 8 total (3 CRITICAL, 5 HIGH)
-- TLS 1.3: Enforced by default
-- Certificate Validation: Mandatory
-
-#### ✨ **New Features**
-
-**Advanced Search & Indexing**
-- HNSW Indexing: 150x faster vector search (O(log n))
-- Quantization: 4-32x memory reduction
-- Vector Search: Semantic search across all memories
-- Full-Text Search: BM25 ranking
-
-**9 Reinforcement Learning Algorithms**
-- Decision Transformer, Q-Learning, SARSA, Actor-Critic
-- DQN, PPO, A3C, REINFORCE, Monte Carlo
-
-**QUIC Synchronization**
-- Sub-millisecond latency (<1ms)
-- TLS 1.3 encryption by default
-- Automatic connection recovery
-- Stream multiplexing
-
-#### 🧪 **Test Suite Expansion**
-- 60+ new test files added
-- AgentDB: 6/6 tests (100%)
-- Core: 53/53 tests (100%)
-- Total: 59/59 tests passing (100%)
-- Zero regressions detected
-
-#### 🧹 **Repository Cleanup**
-- Documentation: 24 reports archived (4.1MB saved)
-- Dependencies: 89 packages removed (7.3MB saved)
-- Total: 11.4MB savings
-- Clean build: Zero TypeScript errors
-
-#### 💔 **Breaking Changes**
-- `enableQUIC()` → `initializeAgentDB({ quic: {...} })`
-- `enableNeural()` → `initializeAgentDB({ learning: {...} })`
-- Removed: QUICTransport, NeuralPatternMatcher, mixins
-- See [Migration Guide](docs/AGENTDB-MIGRATION-GUIDE.md)
-
-**Release Score: 90/100** ✅ | [Complete Changelog](docs/COMPLETE-1.2.0-CHANGELOG.md)
+**What gets initialized:**
+- ✅ Multi-Model Router (70-81% cost savings - opt-in)
+- ✅ Learning System (20% improvement target)
+- ✅ Pattern Bank (cross-project reuse)
+- ✅ ML Flaky Detection (100% accuracy)
+- ✅ 17 Specialized agent definitions
+- ✅ 8 AQE slash commands
+- ✅ Configuration directory
 
 ---
 
-## 🎉 What's in v1.1.0
-
-### Intelligence Boost Release (Previous)
-
-**Learning System** 🧠
-- Q-learning reinforcement learning for strategy optimization
-- 20% improvement target tracking with automatic achievement
-- Experience replay buffer (10,000 experiences)
-- Automatic strategy recommendation with 95%+ confidence
-- Cross-agent knowledge sharing
-
-**Pattern Bank** 📦
-- Cross-project pattern sharing and reuse
-- 85%+ matching accuracy with AI-powered similarity
-- 6 framework support (Jest, Mocha, Cypress, Vitest, Jasmine, AVA)
-- Automatic pattern extraction from existing tests
-- Pattern quality scoring and versioning
-
-**ML Flaky Detection** 🎯
-- 100% detection accuracy (target: 90%)
-- 0% false positive rate (target: < 5%)
-- Root cause analysis (timing, race conditions, dependencies, isolation)
-- Automated fix recommendations with code examples
-- < 1 second processing time for 1000+ test results
+## ✨ Features
 
-**Continuous Improvement** 🔄
-- A/B testing framework for strategy comparison
-- Auto-optimization with statistical confidence (95%+)
-- Failure pattern analysis and mitigation
-- Performance benchmarks (< 50ms pattern matching, < 100ms learning)
-
-**Enhanced Agents:**
-- **TestGeneratorAgent**: Pattern-based generation (20%+ faster)
-- **CoverageAnalyzerAgent**: Learning-enhanced analysis
-- **FlakyTestHunterAgent**: ML-based detection (99% accuracy)
-
-See [CHANGELOG.md](CHANGELOG.md) for full details.
-
----
-
-## 🚀 Features
+### 🤖 Autonomous Agent Fleet
+- **17 Specialized Agents**: Expert agents for every QE domain (test generation, coverage analysis, security scanning, performance testing)
+- **AI-Powered Coordination**: Event-driven architecture with intelligent task distribution
+- **Zero External Dependencies**: Native AQE hooks system (100-500x faster than external coordination)
+- **Scalable**: From single developer projects to enterprise-scale testing infrastructure
 
-### Phase 1: Cost Optimization (v1.0.5)
+### 🧠 Intelligence & Learning (v1.1.0)
+- **Q-Learning System**: 20% improvement target with automatic strategy optimization
+- **Pattern Bank**: 85%+ matching accuracy across 6 test frameworks (Jest, Mocha, Cypress, Vitest, Jasmine, AVA)
+- **ML Flaky Detection**: 100% accuracy with root cause analysis and automated fix recommendations
+- **Continuous Improvement**: A/B testing framework with 95%+ statistical confidence
+- **Experience Replay**: Learn from 10,000+ past executions
 
-#### 💰 Multi-Model Router
-- **70-81% Cost Savings**: Intelligent AI model selection saves $417+ per month
+### 💰 Cost Optimization (v1.0.5)
+- **Multi-Model Router**: 70-81% cost savings through intelligent model selection (opt-in feature)
 - **4+ AI Models**: GPT-3.5, GPT-4, Claude Haiku, Claude Sonnet 4.5
-- **Smart Routing**: Automatic complexity analysis and model selection
-- **Real-Time Tracking**: Live cost monitoring with daily/monthly budgets
-- **Budget Alerts**: Email, Slack, and webhook notifications
-- **Cost Forecasting**: Predict future costs with 90% confidence
+- **Smart Routing**: Automatic complexity analysis and optimal model selection
+- **Real-Time Tracking**: Live cost monitoring with budget alerts and forecasting
 - **ROI Dashboard**: Track savings vs single-model baseline
 
-#### 📊 Real-Time Streaming
-- **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
+### 📊 Comprehensive Testing
+- **Multi-Framework Support**: Jest, Mocha, Cypress, Playwright, Vitest, Jasmine, AVA
+- **Parallel Execution**: 10,000+ concurrent tests with intelligent orchestration
+- **Real-Time Coverage**: O(log n) algorithms for instant gap detection
+- **Performance Testing**: k6, JMeter, Gatling integration
+- **Real-Time Streaming**: Live progress updates for all operations
 
-### Phase 2: Intelligence Boost (v1.1.0) 🆕
+### 🎓 34 QE Skills Library (v1.3.0)
+**95%+ coverage of modern QE practices**
 
-#### 🧠 Learning System
-- **Q-Learning Algorithm**: Reinforcement learning for strategy optimization
-- **20% Improvement Target**: Automatic tracking and achievement
-- **Experience Replay**: Learn from 10,000+ past executions
-- **Strategy Recommendation**: AI-powered optimal strategy selection
-- **Cross-Agent Sharing**: Agents learn from each other's experiences
-
-#### 📦 Pattern Bank
-- **Pattern Extraction**: Automatic extraction from existing tests
-- **85%+ Matching Accuracy**: AI-powered pattern matching
-- **Cross-Project Sharing**: Export/import patterns across teams
-- **6 Framework Support**: Jest, Mocha, Cypress, Vitest, Jasmine, AVA
-- **Quality Scoring**: Automatic pattern quality assessment
-
-#### 🎯 ML Flaky Detection
-- **100% Accuracy**: ML-based detection with zero false positives
-- **Root Cause Analysis**: Identify timing, race conditions, dependencies
-- **Automated Fixes**: Generate fix recommendations with code examples
-- **Continuous Monitoring**: Track test reliability over time
-- **< 1 Second Processing**: 8,000+ test results per second
-
-#### 🔄 Continuous Improvement
-- **A/B Testing**: Compare strategies with statistical confidence
-- **Auto-Optimization**: Apply winning strategies automatically
-- **Failure Pattern Analysis**: Detect and mitigate recurring issues
-- **Performance Benchmarks**: < 50ms pattern matching, < 100ms learning
-
-### Core Features
-
-#### 🤖 Autonomous Agent Fleet
-- **18 Specialized Agents**: Each agent is an expert in specific quality engineering domains
-  - _Note: 17 QE-specific agents + 1 general-purpose base-template-generator agent_
-- **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
+<details>
+<summary><b>View All Skills</b></summary>
 
-#### 🧪 Comprehensive Testing
-- **AI-Powered Test Generation**: Generate comprehensive test suites automatically
-- **Multi-Framework Support**: Jest, Mocha, Cypress, Playwright, Vitest, Jasmine, AVA
-- **Parallel Execution**: Execute thousands of tests concurrently with intelligent orchestration
-- **Real-Time Coverage Analysis**: O(log n) algorithms for instant coverage gap detection
+**Phase 1: Original Quality Engineering Skills (18 skills)**
+- **Core Testing**: agentic-quality-engineering, holistic-testing-pact, context-driven-testing, exploratory-testing-advanced
+- **Methodologies**: tdd-london-chicago, xp-practices, risk-based-testing, test-automation-strategy
+- **Techniques**: api-testing-patterns, performance-testing, security-testing
+- **Code Quality**: code-review-quality, refactoring-patterns, quality-metrics
+- **Communication**: bug-reporting-excellence, technical-writing, consultancy-practices
 
-#### 🎯 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
+**Phase 2: Expanded QE Skills Library (16 skills)**
+- **Testing Methodologies (6)**: regression-testing, shift-left-testing, shift-right-testing, test-design-techniques, mutation-testing, test-data-management
+- **Specialized Testing (9)**: accessibility-testing, mobile-testing, database-testing, contract-testing, chaos-engineering-resilience, compatibility-testing, localization-testing, compliance-testing, visual-testing-advanced
+- **Testing Infrastructure (2)**: test-environment-management, test-reporting-analytics
 
-#### ⚡ Advanced Capabilities
-- **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
+</details>
 
 ---
 
-## 📦 Prerequisites & Installation
+## 💻 Usage Examples
 
-### Prerequisites
+### Example 1: Single Agent Execution
 
-#### Required
-- **Claude Code**: Install from [claude.ai/code](https://claude.ai/code)
-- **Node.js**: 18.0 or higher
-- **npm**: 8.0 or higher
+Ask Claude to use a specific agent:
+
+```bash
+claude "Use the qe-test-generator agent to create comprehensive tests for src/services/user-service.ts with 95% coverage"
+```
 
-#### Optional (Advanced Features)
-- **Claude Flow**: For optional MCP coordination features
-  ```bash
-  npm install -g @claude/flow
-  # or
-  npx claude-flow@alpha init --force
-  ```
+**What happens:**
+1. Claude Code spawns qe-test-generator via Task tool
+2. Agent analyzes the source file
+3. Generates tests with pattern matching (Phase 2 feature)
+4. Stores results in memory at `aqe/test-plan/generated`
 
-**Note**: AQE hooks system requires NO external dependencies. All coordination features are built-in with TypeScript.
+**Output:**
+```
+Generated 42 tests
+Pattern hit rate: 67%
+Time saved: 2.3s
+Quality score: 96%
+```
 
-### Installation Steps
+### Example 2: Multi-Agent Parallel Execution
 
-1. **Install Claude Code** globally or in your workspace
+Coordinate multiple agents at once:
 
-2. **Install Agentic QE**
+```bash
+claude "Initialize the AQE fleet:
+1. Use qe-test-generator to create tests for src/services/*.ts
+2. Use qe-test-executor to run all tests in parallel
+3. Use qe-coverage-analyzer to find gaps with sublinear algorithms
+4. Use qe-quality-gate to validate against 95% threshold"
+```
 
-   **Global Installation** (Recommended)
-   ```bash
-   npm install -g agentic-qe
+**What happens:**
+1. Claude spawns 4 agents concurrently in a single message
+2. Agents coordinate through `aqe/*` memory namespace
+3. Pipeline: test generator → executor → analyzer → gate
+4. Real-time streaming progress updates
 
-   # Verify installation
-   aqe --version
-   ```
+**Memory namespaces:**
+- `aqe/test-plan/*` - Test planning and requirements
+- `aqe/coverage/*` - Coverage analysis results
+- `aqe/performance/*` - Performance test data
+- `aqe/quality/*` - Quality metrics
 
-   **Project Installation**
-   ```bash
-   npm install --save-dev agentic-qe
+### Example 3: Using Agents with Skills
 
-   # Use with npx
-   npx aqe init
-   ```
+Agents automatically leverage skills:
 
-3. **Local Development**
-   ```bash
-   git clone https://github.com/proffesor-for-testing/agentic-qe.git
-   cd agentic-qe
-   npm install
-   npm run build
-   npm link
-   ```
+```bash
+claude "Use qe-test-generator with shift-left-testing and test-design-techniques skills to create tests before implementing the new payment feature"
+```
 
-### System Requirements
+**Available skills** (agents auto-select from 34):
+- TDD, API testing, performance, security
+- Accessibility, mobile, chaos engineering
+- Regression, shift-left/right, compliance
 
-- **Memory**: 2GB+ recommended for large test suites
-- **OS**: Linux, macOS, Windows (via WSL2)
-- **Agent Execution**: Via Claude Code's Task tool or MCP integration
+### Example 4: Full Quality Pipeline
 
----
+End-to-end quality workflow:
 
-## ⚡ Quick Start
+```bash
+claude "Run the full AQE quality pipeline:
+1. qe-requirements-validator - validate requirements are testable
+2. qe-test-generator - generate comprehensive test suite
+3. qe-test-executor - run tests with parallel execution
+4. qe-coverage-analyzer - analyze gaps using O(log n) algorithms
+5. qe-flaky-test-hunter - detect flaky tests with 100% ML accuracy
+6. qe-security-scanner - run SAST/DAST scans
+7. qe-performance-tester - load test critical paths
+8. qe-quality-gate - validate all quality criteria met
+9. qe-deployment-readiness - assess deployment risk"
+```
 
-### 1. Install & Setup MCP Integration
+### Example 5: Specialized Testing Scenarios
 
 ```bash
-# Install Agentic QE
-npm install -g agentic-qe
+# API contract validation
+claude "Use qe-api-contract-validator to check if the new API changes break any existing contracts"
 
-# Add MCP server to Claude Code
-claude mcp add agentic-qe npx -y agentic-qe mcp:start
+# Visual regression testing
+claude "Use qe-visual-tester to compare screenshots of the updated dashboard against baseline"
 
-# Verify connection
-claude mcp list
+# Chaos engineering
+claude "Use qe-chaos-engineer to inject random failures and validate system resilience"
+
+# Flaky test detection with ML
+claude "Use qe-flaky-test-hunter to analyze the last 100 test runs and identify flaky tests with ML-powered root cause analysis"
 ```
 
-### 2. Initialize Your Project (v1.1.0)
+### Example 6: Fleet Coordination at Scale
 
 ```bash
-# Initialize with Phase 1 + Phase 2 features
-cd your-project
-aqe init
+# Coordinate 50+ agents for large projects
+claude "Use qe-fleet-commander to coordinate parallel testing across 8 microservices with 50 agents total"
 ```
 
-**What gets initialized:**
-- ✅ Multi-Model Router (70-81% cost savings)
-- ✅ Learning System (20% improvement target)
-- ✅ Pattern Bank (cross-project reuse)
-- ✅ ML Flaky Detection (100% accuracy)
-- ✅ Improvement Loop (A/B testing)
-- ✅ 17 Specialized QE agent definitions (+ 1 general-purpose agent)
-- ✅ 8 AQE slash commands
-- ✅ Configuration directory
+### MCP Integration Examples
 
-### 3. Use from Claude Code CLI
+You can also use agents through MCP tools:
 
 ```bash
-# Ask Claude to generate tests using AQE agents with patterns
-claude "Initialize AQE fleet and generate comprehensive tests for src/services/user-service.ts with 95% coverage using pattern matching"
+# Check MCP connection
+claude mcp list
+
+# Direct MCP tool usage (in Claude Code)
+# Generate tests
+mcp__agentic_qe__test_generate({
+  type: "unit",
+  framework: "jest",
+  targetFile: "src/user-service.ts"
+})
+
+# Execute tests
+mcp__agentic_qe__test_execute({
+  parallel: true,
+  coverage: true
+})
+
+# Analyze coverage
+mcp__agentic_qe__coverage_analyze({
+  threshold: 95
+})
 ```
 
-**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
+### CLI Direct Usage
 
-📖 **[Complete MCP Integration Guide](docs/guides/MCP-INTEGRATION.md)** - Detailed setup, examples, and use cases
+```bash
+# Generate tests
+aqe test src/services/user-service.ts
 
----
+# Analyze coverage
+aqe coverage --threshold 95
 
-## 🎯 Phase 2 Commands (v1.1.0)
+# Run quality gate
+aqe quality
 
-### Learning System Commands 🧠
+# View fleet status
+aqe status --verbose
 
-```bash
-# Enable learning for all agents
+# Enable multi-model router (70-81% cost savings)
+aqe routing enable
+
+# Start learning system
 aqe learn enable --all
+```
 
-# View learning metrics
-aqe learn status
+### Advanced Patterns
 
-# View learning history
-aqe learn history --agent test-generator
+#### Pattern 1: Continuous Learning
 
-# Manual training
-aqe learn train --agent test-generator
+```bash
+# Agents learn from execution
+claude "Use qe-test-generator with learning enabled to create tests, then analyze improvement over time"
 
-# Export learning data
-aqe learn export --agent test-generator --output learning-state.json
+# Check learning metrics
+aqe learn status --agent test-generator
 ```
 
-**Example Output** - `aqe learn status`:
+**Example Output:**
 ```
 📊 LEARNING STATUS
 
 Agent: test-generator
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Status: ENABLED ✅
 Total Experiences: 247
 Exploration Rate: 15.3%
@@ -423,30 +294,19 @@ Top Strategies:
 1. property-based (confidence: 92%, success: 95%)
 2. mutation-based (confidence: 85%, success: 88%)
 3. example-based (confidence: 78%, success: 82%)
-
-Recent Trend: ↗ improving
 ```
 
-### Pattern Management Commands 📦
+#### Pattern 2: Pattern Bank Usage
 
 ```bash
-# List all patterns
-aqe patterns list
-
-# Search patterns by keyword
-aqe patterns search "null check"
+# Extract and reuse patterns
+claude "Use qe-test-generator to extract test patterns from existing tests, then apply them to new modules"
 
-# Extract patterns from tests
-aqe patterns extract --path tests/ --framework jest
-
-# Share patterns across projects
-aqe patterns share --id pattern-001 --projects proj-a,proj-b
-
-# Export patterns
-aqe patterns export --output patterns-backup.json
+# List patterns
+aqe patterns list --framework jest
 ```
 
-**Example Output** - `aqe patterns list`:
+**Example Output:**
 ```
 📦 PATTERN LIBRARY (247 patterns)
 
@@ -455,67 +315,23 @@ ID         | Name                      | Framework | Quality | Uses
 pattern-001| Null Parameter Check      | jest      | 92%     | 142
 pattern-002| Empty Array Handling      | jest      | 89%     | 98
 pattern-003| API Timeout Test          | cypress   | 95%     | 87
-pattern-004| Database Transaction      | mocha     | 88%     | 76
-pattern-005| Async Error Handling      | jest      | 91%     | 65
-
-Total: 247 patterns | Average Quality: 87%
 ```
 
-### Improvement Loop Commands 🔄
+#### Pattern 3: Cost Optimization
 
 ```bash
-# View improvement status
-aqe improve status
-
-# Start improvement loop
-aqe improve start
-
-# Run A/B test
-aqe improve ab-test --strategies "property-based,mutation-based" --sample-size 50
-
-# View failure patterns
-aqe improve failures
-
-# Generate improvement report
-aqe improve report --format html --output improvement-report.html
-```
-
----
-
-## 🎯 Phase 1 Commands (v1.0.5)
-
-### Multi-Model Router Commands 💰
-
-```bash
-# Enable cost-optimized routing (70-81% savings)
+# Enable intelligent model routing
 aqe routing enable
 
-# View current configuration and savings
-aqe routing status
-
-# Launch real-time cost dashboard
+# View savings
+claude "Check routing status and show cost savings"
 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`:
+**Example Output:**
 ```
 ✅ 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
@@ -529,257 +345,20 @@ Model Usage:
   └─ gpt-4: 7% (critical tasks)
 ```
 
-📚 **[Complete Routing Examples](docs/examples/ROUTING-EXAMPLES.md)** - CLI and programmatic usage
-
-### Basic Commands
-
-```bash
-# 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
-```
-
----
-
-## 💻 Programmatic Usage
-
-### Pattern-Based Test Generation (v1.1.0) 🆕
-
-```typescript
-import { TestGeneratorAgent, QEReasoningBank } from 'agentic-qe';
-
-// Initialize pattern bank
-const bank = new QEReasoningBank();
-
-// Create agent with pattern matching
-const agent = new TestGeneratorAgent(
-  { agentId: 'test-gen-1', memoryStore },
-  {
-    targetCoverage: 95,
-    framework: 'jest',
-    enablePatterns: true,   // ✅ Enable pattern matching
-    enableLearning: true,   // ✅ Enable learning
-    reasoningBank: bank
-  }
-);
-
-// Generate tests with patterns
-const result = await agent.execute({
-  type: 'test-generation',
-  payload: {
-    sourceFile: 'src/myModule.ts',
-    framework: 'jest'
-  }
-});
-
-console.log(`Generated ${result.testsGenerated} tests`);
-console.log(`Pattern hit rate: ${result.patternHitRate}%`);
-console.log(`Time saved: ${result.patterns.savings}ms`);
-console.log(`Quality score: ${result.qualityScore}%`);
-```
-
-**Performance Impact:**
-```
-Without Patterns:
-├─ Test Generation: 180ms avg
-├─ Coverage: 78%
-└─ Quality Score: 82%
-
-With Patterns:
-├─ Test Generation: 145ms avg (↓ 19.4%)
-├─ Coverage: 94% (↑ 20.5%)
-└─ Quality Score: 96% (↑ 17.1%)
-```
-
-### Learning-Enhanced Coverage Analysis (v1.1.0) 🆕
-
-```typescript
-import { CoverageAnalyzerAgent, LearningEngine } from 'agentic-qe';
-
-// Create learning engine
-const learningEngine = new LearningEngine('coverage-1', memory, {
-  enabled: true,
-  learningRate: 0.1,
-  targetImprovement: 0.20  // 20% improvement target
-});
-
-await learningEngine.initialize();
-
-// Create agent with learning
-const agent = new CoverageAnalyzerAgent(
-  { agentId: 'coverage-1', memoryStore: memory },
-  {
-    targetCoverage: 95,
-    algorithm: 'sublinear',
-    enableLearning: true  // ✅ Enable learning
-  }
-);
-
-// Analyze coverage (learning happens automatically)
-const analysis = await agent.execute({
-  type: 'coverage-analysis',
-  payload: {
-    coverageReport: './coverage/coverage-final.json',
-    threshold: 95
-  }
-});
-
-// Check learning progress
-const status = await learningEngine.calculateImprovement();
-console.log(`Current improvement: ${(status.improvementRate * 100).toFixed(1)}%`);
-console.log(`Target reached: ${status.targetAchieved ? '✅ YES' : '❌ NO'}`);
-console.log(`Confidence: ${(status.confidence * 100).toFixed(1)}%`);
-```
-
-### ML Flaky Detection (v1.1.0) 🆕
-
-```typescript
-import { FlakyTestHunterAgent, FlakyTestDetector } from 'agentic-qe';
-
-// Create detector with ML
-const detector = new FlakyTestDetector({
-  minRuns: 5,
-  passRateThreshold: 0.8,
-  confidenceThreshold: 0.7,
-  enableML: true  // ✅ 100% accuracy
-});
-
-// Create agent
-const agent = new FlakyTestHunterAgent(
-  { agentId: 'flaky-1', memoryStore: memory },
-  {
-    enableML: true,  // ✅ 100% accuracy
-    detector
-  }
-);
-
-// Detect flaky tests
-const result = await agent.execute({
-  type: 'flaky-detection',
-  payload: {
-    testHistory: testResults
-  }
-});
-
-result.flakyTests.forEach(test => {
-  console.log(`🔴 ${test.testName}`);
-  console.log(`   Pass Rate: ${(test.passRate * 100).toFixed(1)}%`);
-  console.log(`   Root Cause: ${test.rootCause.cause}`);
-  console.log(`   ML Confidence: ${(test.rootCause.mlConfidence * 100).toFixed(1)}%`);
-  console.log(`   Severity: ${test.severity}`);
-  console.log(`   Fix: ${test.fixRecommendations[0].recommendation}`);
-  console.log(`   Code Example:`);
-  console.log(`   ${test.fixRecommendations[0].codeExample}`);
-});
-```
-
-**Detection Results:**
-```
-Model Training Complete:
-  Accuracy: 100.00%      ✅ Exceeds 90% target by 10%
-  Precision: 100.00%     ✅ Perfect precision
-  Recall: 100.00%        ✅ Perfect recall
-  F1 Score: 100.00%      ✅ Perfect F1
-  False Positive Rate: 0.00%  ✅ Well below 5% target
-
-Processing 1,200 test results: ~150ms
-Throughput: ~8,000 results/second
-Memory Usage: < 5MB delta
-```
-
-### With Multi-Model Router (v1.0.5)
-
-```typescript
-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](docs/examples/ROUTING-EXAMPLES.md)** - Advanced programmatic usage
-
----
-
-## 📊 Performance Benchmarks
-
-| Feature | Target | Actual | Status |
-|---------|--------|--------|--------|
-| **Pattern Matching (p95)** | <50ms | 32ms | ✅ Exceeded |
-| **Learning Iteration** | <100ms | 68ms | ✅ Exceeded |
-| **ML Flaky Detection (1000 tests)** | <500ms | 385ms | ✅ Exceeded |
-| **Agent Memory** | <100MB | 85MB | ✅ Exceeded |
-| **Cost Savings** | 70%+ | 70-81% | ✅ Achieved |
-| **Test Improvement** | 20%+ | 23%+ | ✅ Exceeded |
-| **Flaky Detection Accuracy** | 90%+ | 100% | ✅ Exceeded |
-| **False Positive Rate** | <5% | 0% | ✅ Exceeded |
+### Pro Tips
 
-### Core 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
+1. **Batch agent operations**: Always spawn multiple agents in one Claude message for parallel execution
+2. **Use memory namespace**: Agents coordinate through `aqe/*` memory keys
+3. **Enable learning**: Add `--enable-learning` to agent commands for continuous improvement
+4. **Check agent status**: Use `aqe status` to see active agents and coordination
+5. **Review agent output**: Agents store detailed results in `.agentic-qe/logs/`
 
 ---
 
 ## 🤖 Agent Types
 
-### Core Testing Agents
+<details>
+<summary><b>Core Testing Agents (5 agents)</b></summary>
 
 | Agent | Purpose | Key Features | Phase 2 Enhancements |
 |-------|---------|-------------|---------------------|
@@ -789,14 +368,20 @@ console.log(`📊 Models used: ${JSON.stringify(savings.modelBreakdown, null, 2)
 | **quality-gate** | Intelligent validation | ML-driven decisions, risk assessment | ✅ Flaky test metrics |
 | **quality-analyzer** | Metrics analysis | ESLint, SonarQube, Lighthouse integration | - |
 
-### Performance & Security
+</details>
+
+<details>
+<summary><b>Performance & Security (2 agents)</b></summary>
 
 | Agent | Purpose | Key Features |
 |-------|---------|-------------|
 | **performance-tester** | Load & stress testing | k6, JMeter, Gatling, bottleneck detection |
 | **security-scanner** | Vulnerability detection | SAST, DAST, dependency scanning |
 
-### Strategic Planning
+</details>
+
+<details>
+<summary><b>Strategic Planning (3 agents)</b></summary>
 
 | Agent | Purpose | Key Features |
 |-------|---------|-------------|
@@ -804,7 +389,10 @@ console.log(`📊 Models used: ${JSON.stringify(savings.modelBreakdown, null, 2)
 | **production-intelligence** | Incident replay | RUM analysis, anomaly detection |
 | **fleet-commander** | Hierarchical coordination | 50+ agent orchestration |
 
-### Advanced Testing
+</details>
+
+<details>
+<summary><b>Advanced Testing (4 agents)</b></summary>
 
 | Agent | Purpose | Key Features | Phase 2 Enhancements |
 |-------|---------|-------------|---------------------|
@@ -813,7 +401,10 @@ console.log(`📊 Models used: ${JSON.stringify(savings.modelBreakdown, null, 2)
 | **api-contract-validator** | Breaking change detection | OpenAPI, GraphQL, gRPC | - |
 | **flaky-test-hunter** | Stability analysis | Statistical detection, auto-fix | ✅ 100% accuracy ML detection |
 
-### Specialized
+</details>
+
+<details>
+<summary><b>Specialized (3 agents)</b></summary>
 
 | Agent | Purpose | Key Features |
 |-------|---------|-------------|
@@ -821,386 +412,118 @@ console.log(`📊 Models used: ${JSON.stringify(savings.modelBreakdown, null, 2)
 | **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) │
-   │         │           │         │
-   │ Phase 2:│           │         │
-   │ Learning│           │         │
-   │ Patterns│           │         │
-   │ ML Model│           │         │
-   └─────────┘           └─────────┘
-```
-
-### 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
+</details>
 
-### AQE Hooks System
+<details>
+<summary><b>General Purpose (1 agent)</b></summary>
 
-**Zero Dependencies** - Built-in TypeScript hooks for agent coordination:
-
-```typescript
-// 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 });
-```
+| Agent | Purpose | Key Features |
+|-------|---------|-------------|
+| **base-template-generator** | Agent templates | General-purpose agent creation |
 
-**Performance**: 100-500x faster than external hooks (<1ms vs 100-500ms)
+</details>
 
-**Features**:
-- Full TypeScript type safety
-- Direct SwarmMemoryManager integration
-- Built-in RollbackManager support
-- EventBus coordination
-- Context engineering (pre/post tool-use bundles)
+**Total: 17 Agents** (16 QE-specific + 1 general-purpose)
 
 ---
 
 ## 📖 Documentation
 
-### 🆕 Phase 2 Features (v1.1.0)
-- [Learning System User Guide](docs/guides/LEARNING-SYSTEM-USER-GUIDE.md) - **NEW!** Q-learning and continuous improvement
-- [Pattern Management User Guide](docs/guides/PATTERN-MANAGEMENT-USER-GUIDE.md) - **NEW!** Cross-project pattern sharing
-- [ML Flaky Detection Guide](docs/guides/ML-FLAKY-DETECTION-USER-GUIDE.md) - **NEW!** 100% accurate flaky detection
-- [Performance Improvement Guide](docs/guides/PERFORMANCE-IMPROVEMENT-USER-GUIDE.md) - **NEW!** A/B testing and optimization
-- [Learning System Examples](docs/examples/LEARNING-SYSTEM-EXAMPLES.md) - **NEW!** Learning code examples
-- [Pattern Examples](docs/examples/REASONING-BANK-EXAMPLES.md) - **NEW!** Pattern usage examples
-- [Flaky Detection Examples](docs/examples/FLAKY-DETECTION-ML-EXAMPLES.md) - **NEW!** ML detection examples
-
-### Phase 1 Features (v1.0.5)
-- [Multi-Model Router Guide](docs/guides/MULTI-MODEL-ROUTER.md) - Save 70% on AI costs
-- [Streaming API Tutorial](docs/guides/STREAMING-API.md) - Real-time progress updates
-- [Cost Optimization Best Practices](docs/guides/COST-OPTIMIZATION.md) - Maximize ROI
-- [Migration Guide v1.0.5](docs/guides/MIGRATION-V1.0.5.md) - Upgrade guide
-- [Routing API Reference](docs/api/ROUTING-API.md) - Complete API docs
-- [Streaming API Reference](docs/api/STREAMING-API.md) - Complete API docs
-- [Phase 1 Code Examples](docs/examples/ROUTING-EXAMPLES.md) - Working examples
-
 ### Getting Started
-- [Quick Start Guide](docs/AQE-CLI.md)
+- [Quick Start Guide](docs/AQE-CLI.md) - Get started in 5 minutes
 - [User Guide](docs/USER-GUIDE.md) - Comprehensive workflows and examples
-- [Agent Types Overview](docs/Agentic-QE-Fleet-Specification.md)
+- [MCP Integration](docs/guides/MCP-INTEGRATION.md) - Claude Code integration
 - [Configuration Guide](docs/CONFIGURATION.md) - Complete configuration reference
 - [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
 
-### User Guides
-- [Test Generation](docs/guides/TEST-GENERATION.md)
-- [Coverage Analysis](docs/guides/COVERAGE-ANALYSIS.md)
-- [Quality Gates](docs/guides/QUALITY-GATES.md)
-- [Performance Testing](docs/guides/PERFORMANCE-TESTING.md)
-- [Test Execution](docs/guides/TEST-EXECUTION.md)
-- [MCP Integration](docs/guides/MCP-INTEGRATION.md)
-
-### Advanced Topics
-- [API Reference](docs/API.md)
-- [Agent Development](docs/AGENT-DEVELOPMENT.md)
-- [MCP Integration](docs/CLAUDE-MD-INTEGRATION.md)
-- [Best Practices](docs/AI%20%26%20Agentic%20Security%20Best%20Practices.md)
-- [AQE Hooks Guide](docs/AQE-HOOKS-GUIDE.md)
-
-### Commands Reference
-- [AQE Commands Overview](docs/QE-COMMANDS-INDEX.md)
-- [Command Specifications](docs/QE-SLASH-COMMANDS-SPECIFICATION.md)
-- [Hooks Architecture](docs/QE_HOOKS_ARCHITECTURE.md)
+### Feature Guides
 
----
+**Phase 2 Features (v1.1.0)**
+- [Learning System User Guide](docs/guides/LEARNING-SYSTEM-USER-GUIDE.md) - Q-learning and continuous improvement
+- [Pattern Management User Guide](docs/guides/PATTERN-MANAGEMENT-USER-GUIDE.md) - Cross-project pattern sharing
+- [ML Flaky Detection Guide](docs/guides/ML-FLAKY-DETECTION-USER-GUIDE.md) - 100% accurate flaky detection
+- [Performance Improvement Guide](docs/guides/PERFORMANCE-IMPROVEMENT-USER-GUIDE.md) - A/B testing and optimization
 
-## 🔧 Configuration
+**Phase 1 Features (v1.0.5)**
+- [Multi-Model Router Guide](docs/guides/MULTI-MODEL-ROUTER.md) - Save 70% on AI costs
+- [Streaming API Tutorial](docs/guides/STREAMING-API.md) - Real-time progress updates
+- [Cost Optimization Best Practices](docs/guides/COST-OPTIMIZATION.md) - Maximize ROI
 
-### Environment Variables
+### Testing Guides
+- [Test Generation](docs/guides/TEST-GENERATION.md) - AI-powered test creation
+- [Coverage Analysis](docs/guides/COVERAGE-ANALYSIS.md) - O(log n) gap detection
+- [Quality Gates](docs/guides/QUALITY-GATES.md) - Intelligent validation
+- [Performance Testing](docs/guides/PERFORMANCE-TESTING.md) - Load and stress testing
+- [Test Execution](docs/guides/TEST-EXECUTION.md) - Parallel orchestration
 
-Create a `.env` file in your project root:
+### Advanced Topics
+- [API Reference](docs/API.md) - Complete API documentation
+- [Agent Development](docs/AGENT-DEVELOPMENT.md) - Create custom agents
+- [Agent Types Overview](docs/Agentic-QE-Fleet-Specification.md) - Complete agent reference
+- [AQE Hooks Guide](docs/AQE-HOOKS-GUIDE.md) - Native coordination system
+- [Best Practices](docs/AI%20%26%20Agentic%20Security%20Best%20Practices.md) - Security and quality
 
-```bash
-# Fleet Configuration
-FLEET_ID=my-project-fleet
-MAX_AGENTS=20
-HEARTBEAT_INTERVAL=30000
-
-# Phase 2: Learning System
-LEARNING_ENABLED=true
-LEARNING_RATE=0.1
-TARGET_IMPROVEMENT=0.20
-
-# Phase 2: Pattern Bank
-PATTERN_MATCHING_ENABLED=true
-MIN_PATTERN_QUALITY=0.8
-
-# Phase 2: ML Flaky Detection
-FLAKY_DETECTION_ML=true
-FLAKY_MIN_RUNS=5
-
-# Database
-DB_TYPE=sqlite
-DB_FILENAME=./data/fleet.db
-
-# Logging
-LOG_LEVEL=info
-LOG_FORMAT=json
-
-# API (optional)
-API_PORT=3000
-API_HOST=localhost
-```
+### Commands Reference
+- [AQE Commands Overview](docs/QE-COMMANDS-INDEX.md) - All CLI commands
+- [Command Specifications](docs/QE-SLASH-COMMANDS-SPECIFICATION.md) - Slash command reference
+- [Hooks Architecture](docs/QE_HOOKS_ARCHITECTURE.md) - Coordination architecture
 
-### Fleet Configuration
-
-Create `config/fleet.yaml`:
-
-```yaml
-fleet:
-  id: "my-project-fleet"
-  name: "My Project QE Fleet"
-  maxAgents: 20
-  topology: mesh
-
-agents:
-  test-generator:
-    count: 3
-    config:
-      frameworks: [jest, cypress, playwright]
-      targetCoverage: 95
-      enablePatterns: true      # Phase 2: Pattern matching
-      enableLearning: true      # Phase 2: Learning
-
-  coverage-analyzer:
-    count: 2
-    config:
-      targetCoverage: 95
-      optimizationAlgorithm: sublinear
-      enableLearning: true      # Phase 2: Learning
-
-  flaky-test-hunter:
-    count: 1
-    config:
-      enableML: true            # Phase 2: ML detection
-      minRuns: 5
-      passRateThreshold: 0.8
-
-  quality-analyzer:
-    count: 2
-    config:
-      tools: [eslint, sonarqube, lighthouse]
-      thresholds:
-        coverage: 80
-        complexity: 10
-        maintainability: 65
-
-# Phase 2: Learning Configuration
-learning:
-  enabled: true
-  learningRate: 0.1
-  discountFactor: 0.95
-  explorationRate: 0.3
-  targetImprovement: 0.20
-
-# Phase 2: Pattern Bank Configuration
-patterns:
-  enabled: true
-  minQuality: 0.8
-  frameworks: [jest, mocha, cypress, vitest, jasmine, ava]
-  autoExtract: true
-
-# Phase 2: Flaky Detection Configuration
-flakyDetection:
-  enableML: true
-  minRuns: 5
-  passRateThreshold: 0.8
-  confidenceThreshold: 0.7
-```
+### Code Examples
+- [Learning System Examples](docs/examples/LEARNING-SYSTEM-EXAMPLES.md) - Learning code examples
+- [Pattern Examples](docs/examples/REASONING-BANK-EXAMPLES.md) - Pattern usage examples
+- [Flaky Detection Examples](docs/examples/FLAKY-DETECTION-ML-EXAMPLES.md) - ML detection examples
+- [Routing Examples](docs/examples/ROUTING-EXAMPLES.md) - Cost optimization examples
 
 ---
 
-## 🧪 Examples
-
-### Example 1: Pattern-Based Test Generation
-
-```typescript
-import { QEReasoningBank, PatternExtractor, TestGeneratorAgent } from 'agentic-qe';
-
-// Initialize components
-const bank = new QEReasoningBank();
-const extractor = new PatternExtractor({ minQuality: 0.8 });
-
-// Extract patterns from existing tests
-const patterns = await extractor.extractFromDirectory('./tests', {
-  recursive: true,
-  filePattern: '**/*.test.ts'
-});
-
-console.log(`Extracted ${patterns.length} patterns`);
-
-// Store patterns in bank
-for (const pattern of patterns) {
-  await bank.storePattern(pattern);
-}
-
-// Use patterns in test generation
-const testGen = new TestGeneratorAgent(
-  { agentId: 'test-gen-1', memoryStore },
-  {
-    targetCoverage: 95,
-    framework: 'jest',
-    usePatterns: true,
-    reasoningBank: bank
-  }
-);
-
-const result = await testGen.execute({
-  type: 'test-generation',
-  payload: {
-    sourceFile: 'src/user-service.ts',
-    framework: 'jest'
-  }
-});
-
-console.log(`Generated ${result.testsGenerated} tests using ${result.patternsUsed.length} patterns`);
-```
-
-### Example 2: Learning-Enhanced Coverage
-
-```typescript
-import {
-  CoverageAnalyzerAgent,
-  LearningEngine,
-  PerformanceTracker,
-  SwarmMemoryManager
-} from 'agentic-qe';
-
-// Initialize components
-const memory = new SwarmMemoryManager({ databasePath: './.aqe/memory.db' });
-await memory.initialize();
-
-const learningEngine = new LearningEngine('coverage-1', memory, {
-  enabled: true,
-  learningRate: 0.1,
-  explorationRate: 0.3
-});
-
-const performanceTracker = new PerformanceTracker('coverage-1', memory, {
-  targetImprovement: 0.20,
-  snapshotWindow: 100
-});
-
-await learningEngine.initialize();
-await performanceTracker.initialize();
-
-// Create agent with learning
-const agent = new CoverageAnalyzerAgent(
-  {
-    agentId: 'coverage-1',
-    memoryStore: memory
-  },
-  {
-    targetCoverage: 95,
-    algorithm: 'sublinear',
-    enableLearning: true
-  }
-);
-
-// Execute 100 tasks to build learning data
-for (let i = 0; i < 100; i++) {
-  const result = await agent.execute({
-    type: 'coverage-analysis',
-    payload: {
-      coverageReport: `./coverage/report-${i}.json`,
-      threshold: 95
-    }
-  });
-
-  console.log(`Task ${i + 1}/100: gaps=${result.gaps.length}`);
-}
-
-// Check improvement
-const improvement = await performanceTracker.calculateImprovement();
-console.log(`\n🎯 Final Results:`);
-console.log(`Improvement Rate: ${improvement.improvementRate.toFixed(2)}%`);
-console.log(`Target Achieved: ${improvement.targetAchieved ? '✅ YES' : '❌ NO'}`);
-```
-
-### Example 3: ML Flaky Detection
-
-```typescript
-import { FlakyTestDetector } from 'agentic-qe';
-
-const detector = new FlakyTestDetector({
-  minRuns: 5,
-  passRateThreshold: 0.8,
-  confidenceThreshold: 0.7
-});
-
-const flakyTests = await detector.detectFlakyTests(testHistory);
+## 📊 Performance Benchmarks
 
-flakyTests.forEach(test => {
-  console.log(`🔴 ${test.name}: ${(test.passRate * 100).toFixed(1)}%`);
-  console.log(`   Pattern: ${test.failurePattern}`);
-  console.log(`   Severity: ${test.severity}`);
-  console.log(`   Fix: ${test.recommendation.suggestedFix}`);
-});
-```
+| Feature | Target | Actual | Status |
+|---------|--------|--------|--------|
+| **Pattern Matching (p95)** | <50ms | 32ms | ✅ Exceeded |
+| **Learning Iteration** | <100ms | 68ms | ✅ Exceeded |
+| **ML Flaky Detection (1000 tests)** | <500ms | 385ms | ✅ Exceeded |
+| **Agent Memory** | <100MB | 85MB | ✅ Exceeded |
+| **Cost Savings** | 70%+ | 70-81% | ✅ Achieved |
+| **Test Improvement** | 20%+ | 23%+ | ✅ Exceeded |
+| **Flaky Detection Accuracy** | 90%+ | 100% | ✅ Exceeded |
+| **False Positive Rate** | <5% | 0% | ✅ Exceeded |
 
-More examples in [examples/](examples/)
+### Core 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
 
 ---
 
-## 🐳 Docker Deployment
+## 📝 Recent Changes
 
-### Quick Start
+### v1.3.5 (2025-10-27) - Learning System Complete & Critical Policies
 
-```bash
-# Start with SQLite (development)
-docker-compose up -d
+**Phase 2 Features Complete:**
+- ✅ Learning System with Q-Learning (87.5% success rate, 18.7% improvement)
+- ✅ Experience Replay Buffer (10,000 experiences)
+- ✅ Pattern Bank with 247 patterns (85%+ accuracy)
+- ✅ Multi-Model Router: 85.7% cost savings (exceeds 70-81% target)
+- ✅ ML Flaky Detection (100% accuracy, 0% false positives)
+- ✅ Streaming Progress with real-time updates
 
-# Start with PostgreSQL (production)
-docker-compose --profile postgres up -d
-```
+**Critical Policy Updates:**
+- ⚠️ Release Verification Policy (8-point checklist)
+- ⚠️ Test Execution Policy (prevents workspace crashes)
+- ⚠️ Release Tagging Policy (tags after PR merge)
 
-### Production Deployment
+**Test Coverage:**
+- 237 new tests added across all Phase 2 features
+- Coverage: 50-70% (30-40x increase from 1.67%)
+- Fixed 328 import paths across 122 test files
 
-```bash
-# Configure production environment
-cp .env.example .env.production
-# Edit .env.production with secure credentials
+**Quality Score:** 92/100 (EXCELLENT) - Zero breaking changes, 100% backward compatible.
 
-# Deploy
-docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
-```
+[View Complete Changelog](CHANGELOG.md)
 
 ---
 
@@ -1242,37 +565,19 @@ npm test
 ```
 agentic-qe/
 ├── src/
-│   ├── agents/          # Agent implementation classes (BaseAgent, LearningAgent, etc.)
+│   ├── agents/          # Agent implementation classes
 │   ├── core/            # Core fleet management
-│   │   ├── FleetManager.ts
-│   │   ├── Agent.ts
-│   │   ├── Task.ts
-│   │   ├── EventBus.ts
-│   │   └── MemoryManager.ts
 │   ├── learning/        # Phase 2: Learning system
-│   │   ├── LearningEngine.ts
-│   │   ├── PerformanceTracker.ts
-│   │   ├── ImprovementLoop.ts
-│   │   ├── FlakyTestDetector.ts
-│   │   └── FlakyPredictionModel.ts
 │   ├── reasoning/       # Phase 2: Pattern bank
-│   │   ├── QEReasoningBank.ts
-│   │   ├── PatternExtractor.ts
-│   │   └── PatternMatcher.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/
-│   └── benchmarks/      # Phase 2: Performance benchmarks
 ├── examples/            # Usage examples
 ├── docs/                # Documentation
 ├── .claude/             # Agent & command definitions
-│   ├── agents/          # 17 QE agent definitions (+ 1 general-purpose)
+│   ├── agents/          # 17 agent definitions
 │   └── commands/        # 8 AQE slash commands
 └── config/              # Configuration files
 ```
@@ -1304,21 +609,6 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for deta
 
 ---
 
-## 📝 License
-
-This project is licensed under the MIT License - see the [LICENSE](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/](docs/)
@@ -1330,18 +620,19 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 🗺️ Roadmap
 
-### Current (v1.1)
+### Current (v1.3)
 - ✅ Learning System with Q-learning
 - ✅ Pattern Bank with cross-project sharing
 - ✅ ML Flaky Detection (100% accuracy)
 - ✅ Continuous Improvement Loop
-- ✅ 17 specialized QE agents
+- ✅ 17 specialized agents
 - ✅ Multi-framework test execution
 - ✅ Real-time coverage analysis
 - ✅ MCP integration
 - ✅ Multi-model router (70-81% cost savings)
+- ✅ 34 QE skills library
 
-### Planned (v1.2)
+### Planned (v1.4)
 - 🔄 Web dashboard for visualization
 - 🔄 GraphQL API
 - 🔄 CI/CD integrations (GitHub Actions, GitLab CI)
@@ -1357,6 +648,21 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](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)
+
+---
+
 <div align="center">
 
 **Made with ❤️ by the Agentic QE Team**