🛡️ Aegis AI

TDD-based Multi-AI MCP Server - Integrating Codex, Qwen, and Gemini with Test-Driven Development

---

📋 Overview

Aegis AI is a production-grade MCP (Model Context Protocol) server that orchestrates three powerful AI models—Codex, Qwen, and Gemini—using strict Test-Driven Development (TDD) methodology.

The name "Aegis" (mythical shield of protection) reflects our commitment to code quality and reliability through comprehensive testing.

---

🎯 Core Features

• ✅ TDD-First Development: All features built with tests before implementation
• 🤖 Multi-AI Integration: Seamless orchestration of Codex, Qwen, and Gemini
• 🔄 MCP Protocol Compliant: Full Model Context Protocol support
• 📊 High Test Coverage: Target 70%+ overall, 80%+ for core modules
• 🛡️ Production Ready: Enterprise-grade reliability and error handling

---

🤖 AI Team Architecture

Claude Code (PM - Project Manager)
    │
    ├─ Gemini (The Speculator)
    │   └─ Role: BDD Spec Generation, Edge Case Discovery
    │
    ├─ Qwen (The Technician)
    │   └─ Role: Test Code Generation, Mocking Implementation
    │
    └─ Codex (The Refactorer)
        └─ Role: Code Review, Optimization Suggestions

---

🚀 Quick Start

Prerequisites

• Node.js: >= 20.0.0
• npm: >= 10.0.0

Installation

# Clone the repository
git clone https://github.com/hwandam77/aegis-ai.git
cd aegis-ai

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

---

📊 Project Structure

aegis-ai/
├── src/
│   ├── core/           # Core modules (handlerLoader, stageOrchestrator, etc.)
│   ├── services/       # AI service integrations (Codex, Qwen, Gemini)
│   ├── handlers/       # AI-specific request handlers
│   └── utils/          # Utility functions
├── tests/
│   ├── core/           # Core module tests
│   ├── services/       # Service layer tests
│   ├── handlers/       # Handler tests
│   ├── mcp/            # MCP protocol tests
│   └── integration/    # Integration tests
├── docs/
│   └── TDD_업그레이드_계획/  # TDD implementation roadmap
├── scripts/            # Build and automation scripts
└── .github/
    └── workflows/      # CI/CD configuration

---

🧪 Testing Philosophy

TDD 3-Step Cycle

🔴 RED    → Write failing test
🟢 GREEN  → Write minimal code to pass
🔵 REFACTOR → Improve code quality

Coverage Goals

Module	Target Coverage
src/core/	80%+
src/services/	70%+
src/handlers/	60%+
Overall	70%+

Quality Policies

1. ✅ All PRs require tests
2. ✅ Bug fixes must include regression tests
3. ✅ New features need spec + implementation
4. ✅ Core modules require Jest specs

---

📈 Development Roadmap

Phase 1: Infrastructure (Week 1-2) ✅

• Jest setup and configuration
• Convert existing tests to Jest
• CI/CD pipeline integration
• TDD policy documentation

Phase 2: Core Modules (Week 3-4)

• handlerLoader.js tests
• stageOrchestrator.js tests
• qualityPipeline.js tests
• stateManager.js tests
• workflowEngine.js tests

Phase 3: Service Layer (Week 5-6)

• geminiService.js tests
• qwenService.js tests
• codexService.js tests
• Mocking strategies

Phase 4: MCP Protocol (Week 7-8)

• Protocol harness implementation
• Mocked stdio tests
• Snapshot tests
• JSON-RPC validation

Phase 5: AI Automation (Week 9+)

• generate-test script
• Coverage dashboard
• Git commit hooks
• VS Code extension

Phase 6: Continuous Improvement (Ongoing)

• Weekly coverage reports
• Code review automation
• TDD workshops
• Team adoption tracking

For detailed information, see TDD Implementation Plan

---

🛠️ Available Scripts

# Testing
npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Generate coverage report
npm run test:verbose     # Verbose output
npm run dashboard        # Show TDD dashboard 🎮

# Development
npm start                # Start the MCP server

# Quality
npm run lint             # Run ESLint (if configured)
npm run format           # Format code with Prettier (if configured)

---

📚 Documentation

• TDD Overview: Complete TDD integration plan
• Phase 1: Infrastructure: Jest setup guide
• Metrics & KPIs: Success measurement
• Checklist: Implementation tracking

---

🤝 Contributing

We welcome contributions! Please follow our TDD workflow:

1. Write tests first (🔴 RED)
2. Implement minimal code (🟢 GREEN)
3. Refactor and optimize (🔵 REFACTOR)
4. Ensure tests pass (npm test)
5. Submit PR with tests

---

📊 Current Status

Metric	Value	Target	Status
Test Coverage	99.33% 🏆	70%	✅ +29.33%
Test Count	105 🏆	100+	✅ Exceeded
TDD Adoption	100% 🏆	100%	✅ Perfect
Core Coverage	98.81% 🏆	80%	✅ +18.81%
Service Coverage	100% 🏆	70%	✅ +30%

Last Updated: 2025-11-22 Status: 🎊 4/6 Phases Complete

---

🎯 Project Goals

Short-term (1-2 months)

• ✅ Core module stability (80% coverage)
• ✅ Early bug detection through tests
• ✅ Safe refactoring capability
• ✅ Improved code review quality

Mid-term (3-6 months)

• ✅ Overall coverage 70%+
• ✅ Faster development (reduced debugging time)
• ✅ Stable handler additions
• ✅ Quick AI integration changes

Long-term (6+ months)

• ✅ TDD culture established
• ✅ 90% reduction in production bugs
• ✅ Continuous code quality improvement
• ✅ Faster onboarding (tests as documentation)

---

📄 License

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

---

🙏 Acknowledgments

• Gemini AI: Creative ideation and BDD specification
• Qwen AI: Technical implementation and code generation
• Codex AI: Code review and optimization
• Claude Code: Project management and orchestration

---

Built with ❤️ using Test-Driven Development