@agentic-qe/v3 3.0.0-alpha.4 → 3.0.0-alpha.43

package/README.md

@@ -1,31 +1,87 @@
-# Agentic QE v3
+# Agentic QE
 
-[![npm version](https://img.shields.io/npm/v/@agentic-qe/v3.svg)](https://www.npmjs.com/package/@agentic-qe/v3)
+[![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/)
 
-> Domain-Driven Quality Engineering with 12 Bounded Contexts, ReasoningBank Learning, and HNSW Vector Search
+> Domain-Driven Quality Engineering with 12 Bounded Contexts, 50 Specialized QE Agents (43 main + 7 subagents), ReasoningBank Learning, and HNSW Vector Search
 
 ## Quick Start
 
 ```bash
 # Install globally
-npm install -g @agentic-qe/v3
+npm install -g agentic-qe
 
 # Initialize your project
 cd your-project
-aqe-v3 init --wizard
+aqe init --wizard
 
 # Or with auto-configuration
-aqe-v3 init --auto
+aqe init --auto
 
-# Add MCP server to Claude Code
-claude mcp add agentic-qe-v3 npx @agentic-qe/v3 mcp
+# Add MCP server to Claude Code (requires global install)
+claude mcp add aqe -- aqe-mcp
 ```
 
+### Local Installation
+
+```bash
+# Install as dev dependency
+npm install --save-dev agentic-qe
+
+# Run via npx
+npx aqe init --wizard
+npx aqe test generate src/
+```
+
+## Why Agentic QE?
+
+- **50 Specialized QE Agents** - Domain-focused quality engineering agents (43 main + 7 subagents)
+- **12 DDD Bounded Contexts** - Modular, extensible architecture
+- **TinyDancer Model Routing** - 3-tier intelligent routing for cost optimization
+- **O(log n) Coverage Analysis** - Sublinear performance with HNSW indexing
+- **Fast Pattern Search** - O(log n) HNSW-indexed vector storage
+- **ReasoningBank + SONA + Dream Cycles** - Neural pattern learning with 9 RL algorithms
+- **Queen-led Coordination** - 3-5x throughput with work stealing and consensus
+- **MinCut Topology** - Graph-based self-healing agent coordination
+- **Zero-Breaking-Changes Migration** - Full v2 backward compatibility
+
+## New in v3: Key Features
+
+### TinyDancer Intelligent Model Routing (ADR-026)
+
+3-tier intelligent model routing for cost optimization:
+
+| Complexity | Model | Use Cases |
+|------------|-------|-----------|
+| **0-20** (Simple) | Haiku | Syntax fixes, type additions |
+| **20-70** (Moderate) | Sonnet | Bug fixes, test generation |
+| **70+** (Critical) | Opus | Architecture, security |
+
+### Dream Cycles & Neural Learning
+
+Background neural consolidation for continuous improvement:
+
+- **9 RL Algorithms**: Q-Learning, SARSA, DQN, PPO, A2C, DDPG, Actor-Critic, Policy Gradient, Decision Transformer
+- **Dream Cycles**: 30s max consolidation with spreading activation
+- **SONA Integration**: Self-Optimizing Neural Architecture with pattern persistence
+- **Persistent Q-Learning**: Q-values survive restarts for continuous learning
+- **EWC++ Protection**: Elastic Weight Consolidation prevents catastrophic forgetting
+- **Novelty Scoring**: Prioritize learning from novel patterns
+
+### Consensus & MinCut Coordination
+
+Advanced coordination for reliable multi-agent decisions:
+
+- **Byzantine Consensus**: Fault-tolerant voting for critical quality decisions
+- **MinCut Topology**: Graph-based self-healing agent coordination
+- **Multi-Model Voting**: Aggregate decisions from multiple model tiers
+- **Claim Verification**: Cryptographic verification of agent work claims
+
 ## Architecture Overview
 
-Agentic QE v3 uses a **Domain-Driven Design (DDD)** architecture with a microkernel pattern:
+Agentic QE uses a **Domain-Driven Design (DDD)** architecture with a microkernel pattern:
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
@@ -79,7 +135,7 @@ Agentic QE v3 uses a **Domain-Driven Design (DDD)** architecture with a microker
 The microkernel provides core infrastructure:
 
 ```typescript
-import { QEKernelImpl } from '@agentic-qe/v3';
+import { QEKernelImpl } from 'agentic-qe';
 
 const kernel = new QEKernelImpl({
   maxConcurrentAgents: 15,
@@ -101,7 +157,7 @@ await kernel.initialize();
 Orchestrates tasks across all domains:
 
 ```typescript
-import { createQueenCoordinator } from '@agentic-qe/v3';
+import { createQueenCoordinator } from 'agentic-qe';
 
 const queen = createQueenCoordinator(kernel, router, executor);
 await queen.initialize();
@@ -161,120 +217,127 @@ const results = await kernel.memory.search('authentication patterns', {
 
 ```bash
 # Interactive wizard
-aqe-v3 init --wizard
+aqe init --wizard
 
 # Auto-configure based on project
-aqe-v3 init --auto
+aqe init --auto
 
 # Manual configuration
-aqe-v3 init -d test-generation,coverage-analysis -m hybrid --max-agents 20
+aqe init -d test-generation,coverage-analysis -m hybrid --max-agents 20
 ```
 
 ### Status & Health
 
 ```bash
 # System status
-aqe-v3 status
-aqe-v3 status --verbose
+aqe status
+aqe status --verbose
 
 # Domain health
-aqe-v3 health
-aqe-v3 health -d test-generation
+aqe health
+aqe health -d test-generation
 ```
 
 ### Test Generation
 
 ```bash
 # Generate tests for a file
-aqe-v3 test generate src/services/user.ts
+aqe test generate src/services/user.ts
 
 # Generate with options
-aqe-v3 test generate src/ -t unit -f vitest
+aqe test generate src/ -t unit -f vitest
 ```
 
 ### Coverage Analysis
 
 ```bash
 # Analyze coverage
-aqe-v3 coverage ./src
+aqe coverage ./src
 
 # With gap detection and risk scoring
-aqe-v3 coverage ./src --gaps --risk
+aqe coverage ./src --gaps --risk
 ```
 
 ### Security Scanning
 
 ```bash
 # Run SAST scan
-aqe-v3 security --sast -t ./src
+aqe security --sast -t ./src
 
 # Check compliance
-aqe-v3 security --compliance gdpr,hipaa
+aqe security --compliance gdpr,hipaa
 ```
 
 ### Code Intelligence
 
 ```bash
 # Index codebase
-aqe-v3 code index ./src
+aqe code index ./src
 
 # Semantic search
-aqe-v3 code search "authentication middleware"
+aqe code search "authentication middleware"
 
 # Impact analysis
-aqe-v3 code impact ./src/auth.ts
+aqe code impact ./src/auth.ts
 
 # Dependency mapping
-aqe-v3 code deps ./src
+aqe code deps ./src
 ```
 
 ### Migration from v2
 
 ```bash
 # Preview migration
-aqe-v3 migrate --dry-run
+aqe migrate --dry-run
 
 # Run migration with backup
-aqe-v3 migrate --backup
+aqe migrate --backup
 
 # Full migration
-aqe-v3 migrate
+aqe migrate
 ```
 
 ### Task Management
 
 ```bash
 # Submit a task
-aqe-v3 task submit generate-tests -p p1 --payload '{"source":"src/"}'
+aqe task submit generate-tests -p p1 --payload '{"source":"src/"}'
 
 # List tasks
-aqe-v3 task list
-aqe-v3 task list -s running
+aqe task list
+aqe task list -s running
 
 # Task status
-aqe-v3 task status <task-id>
+aqe task status <task-id>
 
 # Cancel task
-aqe-v3 task cancel <task-id>
+aqe task cancel <task-id>
 ```
 
 ### Agent Management
 
 ```bash
 # List agents
-aqe-v3 agent list
-aqe-v3 agent list -d test-generation
+aqe agent list
+aqe agent list -d test-generation
 
 # Spawn agent
-aqe-v3 agent spawn test-generation -t worker -c unit-test,integration-test
+aqe agent spawn test-generation -t worker -c unit-test,integration-test
 ```
 
 ## MCP Integration
 
-Add the v3 MCP server to Claude Code:
+Add the MCP server to Claude Code (requires global install):
 
 ```bash
-claude mcp add agentic-qe-v3 npx @agentic-qe/v3 mcp
+# First install globally
+npm install -g agentic-qe
+
+# Then add to Claude Code
+claude mcp add aqe -- aqe-mcp
+
+# Or run directly with npx (no global install)
+claude mcp add aqe -- npx agentic-qe mcp
 ```
 
 ### Available MCP Tools
@@ -307,13 +370,25 @@ claude mcp add agentic-qe-v3 npx @agentic-qe/v3 mcp
 | `memory_retrieve` | Retrieve from memory |
 | `memory_query` | Query memory with patterns |
 | `memory_share` | Share knowledge between agents |
+| `memory_usage` | Get memory usage statistics |
+
+**New in v3:**
+
+| Tool | Description |
+|------|-------------|
+| `agent_status` | Get detailed agent status |
+| `dream_cycle` | Trigger neural consolidation |
+| `model_route` | Get optimal model routing |
+| `model_stats` | View routing statistics |
+| `consensus_status` | View consensus decisions |
+| `topology_optimize` | Optimize agent topology |
 
 ## Programmatic API
 
 ### Test Generation
 
 ```typescript
-import { QEKernelImpl } from '@agentic-qe/v3';
+import { QEKernelImpl } from 'agentic-qe';
 
 const kernel = new QEKernelImpl();
 await kernel.initialize();
@@ -365,11 +440,16 @@ console.log(`Quality gate: ${gate.value.passed ? 'PASSED' : 'FAILED'}`);
 
 | Metric | v2 | v3 | Improvement |
 |--------|----|----|-------------|
-| Coverage Analysis | O(n) | O(log n) | Sublinear |
-| Pattern Search | Linear scan | HNSW index | 150x faster |
-| Memory Usage | Unbounded | Quantized | 50-75% reduction |
-| Agent Coordination | Sequential | Work stealing | 3-5x throughput |
-| Startup Time | ~2s | ~500ms | 4x faster |
+| Coverage Analysis | O(n) | O(log n) | Sublinear ✅ |
+| Pattern Search | Linear scan | HNSW index | O(log n) ✅ |
+| Search Latency | ~100ms | <1ms | Verified ✅ |
+| Token Reduction | N/A | >75% | Verified ✅ |
+| Memory Backend | SQLite only | Hybrid (SQLite + HNSW) | Persistent ✅ |
+| Model Routing | Single tier | TinyDancer 3-tier | Cost optimized |
+| Neural Backbone | N/A | SONA + Q-Learning | Persistent learning ✅ |
+| Agent Coordination | Sequential | Work stealing | Improved |
+
+*✅ = Verified via benchmarks. See `/docs/benchmarks/` for details.*
 
 ## Key Differences from v2
 
@@ -379,24 +459,57 @@ console.log(`Quality gate: ${gate.value.passed ? 'PASSED' : 'FAILED'}`);
 | Test Framework | Jest | Vitest |
 | Module System | CommonJS | ESM |
 | Memory | SQLite only | HNSW + SQLite hybrid |
-| Learning | Basic patterns | ReasoningBank + SONA |
-| Agents | 31 | 47 QE agents |
-| CLI | `aqe` | `aqe-v3` |
-| Package | `agentic-qe` | `@agentic-qe/v3` |
+| Learning | Basic patterns | ReasoningBank + SONA + Dream Cycles |
+| Agents | 32 | 50 QE agents (43 main + 7 subagents) |
+| Coverage | O(n) | O(log n) |
+| Pattern Search | Linear | O(log n) HNSW indexing |
+| Coordination | Sequential | Queen + Work Stealing + Consensus |
+| Model Routing | None | TinyDancer 3-tier routing |
+| CLI | `aqe` | `aqe` |
+| Package | `agentic-qe@2` | `agentic-qe` |
 
 ## Migration from v2
 
-See the [Migration Guide](../docs/MIGRATION-GUIDE.md) for detailed instructions.
+Agentic QE v3 provides **zero-breaking-changes** migration. All v2 APIs, CLI commands, and configurations continue to work.
+
+### Quick Migration
+
+```bash
+# Install v3 (replaces v2)
+npm install agentic-qe
+
+# Run migration with backup
+aqe migrate --backup
+
+# Verify migration
+aqe migrate status
+```
+
+### What Gets Migrated
+
+| Component | v2 Location | v3 Location | Auto-Migrate |
+|-----------|-------------|-------------|--------------|
+| Memory DB | `.agentic-qe/memory.db` | `.aqe/agentdb/` | Yes |
+| Config | `.agentic-qe/config.json` | `.aqe/config.json` | Yes |
+| Patterns | `.agentic-qe/patterns/` | `.aqe/reasoning-bank/` | Yes |
+
+### Backward Compatibility
+
+All v2 agent names and CLI commands remain functional:
 
 ```bash
-# Quick migration
-npm install @agentic-qe/v3
-aqe-v3 migrate --backup
+# v2 commands still work
+aqe generate tests --file src/app.ts  # Mapped to: aqe test generate
+
+# v2 agent names still work
+qe-test-generator  # Mapped to: qe-test-architect
 ```
 
+See the [Migration Guide](./docs/MIGRATION-GUIDE.md) for detailed instructions and the [Changelog](./docs/CHANGELOG-V3.md) for all changes.
+
 ## Configuration
 
-### Project Configuration (.aqe-v3/config.json)
+### Project Configuration (.aqe/config.json)
 
 ```json
 {
@@ -420,10 +533,64 @@ aqe-v3 migrate --backup
 }
 ```
 
+## 50 QE Agents
+
+Agentic QE includes 50 specialized quality engineering agents (43 main + 7 subagents) organized by domain:
+
+### Test Generation Domain
+`qe-test-architect`, `qe-tdd-specialist`, `qe-tdd-red`, `qe-tdd-green`, `qe-tdd-refactor`, `qe-property-tester`, `qe-mutation-tester`, `qe-bdd-generator`
+
+### Test Execution Domain
+`qe-test-executor`, `qe-flaky-hunter`, `qe-retry-handler`, `qe-parallel-executor`
+
+### Coverage Analysis Domain
+`qe-coverage-specialist`, `qe-gap-detector`, `qe-risk-analyzer`
+
+### Quality Assessment Domain
+`qe-quality-gate`, `qe-metrics-optimizer`, `qe-deployment-advisor`
+
+### Defect Intelligence Domain
+`qe-defect-intelligence`, `qe-regression-analyzer`, `qe-root-cause-analyzer`
+
+### Code Intelligence Domain
+`qe-knowledge-manager`, `qe-dependency-mapper`, `qe-impact-analyzer`
+
+### Security Compliance Domain
+`qe-security-auditor`, `qe-security-scanner`, `qe-compliance-validator`
+
+### Contract Testing Domain
+`qe-contract-validator`, `qe-contract-testing`, `qe-graphql-tester`
+
+### Visual Accessibility Domain
+`qe-visual-accessibility`, `qe-responsive-tester`, `qe-accessibility-auditor`
+
+### Chaos Resilience Domain
+`qe-chaos-engineer`, `qe-load-tester`, `qe-resilience-tester`, `qe-performance-tester`
+
+### Learning Optimization Domain
+`qe-learning-optimization`, `qe-pattern-learner`, `qe-transfer-specialist`
+
+### Coordination
+`qe-queen-coordinator`, `qe-fleet-commander`, `qe-integration-tester`, `qe-data-generator`, `qe-code-reviewer`
+
+### Additional Agents (New in v3)
+`qe-product-factors-assessor` (SFDIPOT analysis), `qe-test-idea-rewriter` (passive→active test transforms)
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- npm 8.0.0 or higher
+
 ## Contributing
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
 
+## Documentation
+
+- [Migration Guide](./docs/MIGRATION-GUIDE.md) - Migrating from v2 to v3
+- [Changelog](./docs/CHANGELOG-V3.md) - Version history and changes
+- [API Reference](https://github.com/proffesor-for-testing/agentic-qe) - Full API documentation
+
 ## License
 
 MIT - see [LICENSE](../LICENSE) for details.