SuperCharged-Claude-Code-Upgrade/skills/unified-agents/UNIFIED-INTEGRATION.md

# Unified Agent Integration: Prometheus + Every Code

## Overview

This document outlines the integration of two major AI coding agent platforms into Claude Code CLI:

1. **Prometheus** (Python/LangGraph) - Multi-agent code reasoning with knowledge graphs
2. **Every Code** (Rust/Codex) - Fast terminal-based coding agent with TUI

## Architecture Comparison

| Aspect | Prometheus | Every Code |
|--------|-----------|------------|
| **Language** | Python | Rust |
| **Framework** | LangGraph state machines | Custom event-driven |
| **Core Features** | Knowledge graphs (Neo4j), AST parsing, Docker containers | Auto Drive, Browser integration, MCP support, Multi-agent |
| **Agent Types** | Classification, Bug Reproduction, Context Retrieval, Patch Generation | Plan, Code, Solve, Auto Drive, Auto Review |
| **Code Understanding** | Neo4j knowledge graph with Tree-sitter AST | Native file system + grep |
| **Execution** | Docker containers | Native shell with sandboxing |
| **LLM Support** | OpenAI, Anthropic, Gemini | ChatGPT, Claude, Gemini (multi-CLI orchestration) |

## Unified Integration Strategy

### Hybrid MCP Server Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code CLI                          │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                 Unified Agent Skills                       │ │
│  │  /agent-plan     /agent-fix-bug    /agent-solve           │ │
│  │  /agent-review   /agent-context    /agent-code            │ │
│  └───────────────────────────┬────────────────────────────────┘ │
│                              │ MCP Client                       │
└──────────────────────────────┼──────────────────────────────────┘
                               │
┌──────────────────────────────┼──────────────────────────────────┐
│                  Unified Agent MCP Server                       │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                    Router Layer                            │ │
│  │         Routes to appropriate backend                     │ │
│  └────────────┬──────────────────────────────┬────────────────┘ │
│               │                              │                   │
│  ┌────────────▼────────────┐  ┌─────────────▼────────────────┐ │
│  │   Prometheus Backend    │  │     Every Code Backend       │ │
│  │  - Knowledge graph      │  │  - Auto Drive orchestration  │ │
│  │  - AST parsing          │  │  - File operations          │ │
│  │  - Docker containers    │  │  - Browser integration      │ │
│  │  - LangGraph agents     │  │  - Multi-agent coordination │ │
│  └─────────────────────────┘  └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## MCP Tool Specification

### Shared Tools (Available from both backends)

| Tool | Description | Backend Priority |
|------|-------------|------------------|
| `agent_find_file` | Find files by pattern | Both |
| `agent_search_code` | Search code by text | Prometheus (AST) > Every Code (grep) |
| `agent_read_file` | Read file with context | Both |
| `agent_create_file` | Create new file | Both |
| `agent_edit_file` | Edit existing file | Both |
| `agent_run_command` | Execute shell command | Every Code (native) > Prometheus (Docker) |

### Prometheus-Specific Tools

| Tool | Description |
|------|-------------|
| `prometheus_classify_issue` | Classify GitHub issues (bug/feature/question/doc) |
| `prometheus_fix_bug` | End-to-end bug fixing with reproduction |
| `prometheus_get_context` | Semantic code context retrieval |
| `prometheus_search_ast` | Search by AST node type (function/class) |
| `prometheus_search_docs` | Search documentation |
| `prometheus_run_tests` | Run tests in Docker container |
| `prometheus_verify_patch` | Verify patch with regression tests |

### Every Code-Specific Tools

| Tool | Description |
|------|-------------|
| `everycode_auto_drive` | Orchestrate multi-agent automation |
| `everycode_plan` | Generate implementation plan |
| `everycode_solve` | Coordinate multiple CLI agents |
| `everycode_auto_review` | Background code review |
| `everycode_browser` | Browser automation (CDP) |
| `everycode_screenshot` | Capture screenshots |
| `everycode_approve` | Handle approval workflow |

## Claude Code Skills to Create

### Core Agent Skills

```
.claude/skills/agents/
├── plan.md              - Generate implementation plans (Every Code)
├── fix-bug.md           - Fix bugs end-to-end (Prometheus)
├── solve.md             - Solve complex problems (Every Code)
├── review.md            - Review code (Every Code Auto Review)
├── context.md           - Get code context (Prometheus)
├── implement.md         - Implement features (Both)
├── test.md              - Run and analyze tests (Prometheus)
└── README.md            - Documentation
```

### Skill Implementations

#### /agent-plan
```markdown
# Agent: Plan

Generate implementation plans using Every Code's planning capabilities.

## Usage
/agent-plan "Implement user authentication with JWT"

## Backend
- Primary: Every Code (/plan command)
- Fallback: Prometheus (feature analysis)
```

#### /agent-fix-bug
```markdown
# Agent: Fix Bug

End-to-end bug fixing with reproduction and verification.

## Usage
/agent-fix-bug "Login fails after password reset"

## Backend
- Primary: Prometheus (bug pipeline)
- Enhancement: Every Code Auto Review
```

#### /agent-solve
```markdown
# Agent: Solve

Multi-agent problem solving with orchestration.

## Usage
/agent-solve "Optimize database queries for performance"

## Backend
- Primary: Every Code (/solve command)
- Support: Prometheus (context retrieval)
```

#### /agent-review
```markdown
# Agent: Review

Background code review with quality checks.

## Usage
/agent-review

## Backend
- Primary: Every Code Auto Review
- Analysis: Prometheus (AST analysis)
```

## Implementation Plan

### Phase 1: Foundation (Week 1)
1. ✅ Analyze both architectures
2. ⏳ Create unified MCP server skeleton
3. ⏳ Implement router for backend selection
4. ⏳ Add basic file operations (shared)
5. ⏳ Test MCP server with Claude Code

### Phase 2: Prometheus Integration (Week 2)
1. ⏳ Set up Prometheus locally
2. ⏳ Implement knowledge graph tools
3. ⏳ Add AST search capabilities
4. ⏳ Create bug fixing pipeline
5. ⏳ Test with sample codebase

### Phase 3: Every Code Integration (Week 2-3)
1. ⏳ Install Every Code CLI
2. ⏳ Implement Auto Drive orchestration
3. ⏳ Add browser automation tools
4. ⏳ Create multi-agent coordination
5. ⏳ Test with sample tasks

### Phase 4: Claude Code Skills (Week 3)
1. ⏳ Create core skills (/plan, /fix-bug, /solve)
2. ⏳ Add secondary skills (/review, /context, /test)
3. ⏳ Implement skill routing logic
4. ⏳ Add documentation and examples
5. ⏳ Test end-to-end workflows

### Phase 5: Polish & Documentation (Week 4)
1. ⏳ Performance optimization
2. ⏳ Error handling and recovery
3. ⏳ User documentation
4. ⏳ Developer guide
5. ⏳ Release preparation

## Installation Guide

### Prerequisites

```bash
# System requirements
- Python 3.11+
- Rust + Cargo
- Node.js 20+
- Docker + Docker Compose
- Neo4j (for Prometheus knowledge graph)

# Clone repositories
git clone https://github.com/EuniAI/Prometheus.git ~/Prometheus
git clone https://github.com/just-every/code.git ~/EveryCode
```

### Prometheus Setup

```bash
cd ~/Prometheus
pip install -r requirements.txt
cp example.env .env
# Edit .env with API keys

# Start Neo4j
docker-compose up -d neo4j

# Build knowledge graph for your repo
python -m prometheus.script.build_kg --repo_path /path/to/repo
```

### Every Code Setup

```bash
cd ~/EveryCode
npm install -g @just-every/code

# Authenticate
code
# Choose "Sign in with ChatGPT" or set OPENAI_API_KEY

# Test installation
code --version
```

### Unified MCP Server

```bash
# Install unified MCP server
pip install git+https://github.com/your-org/unified-agent-mcp.git

# Configure Claude Code
# Add to ~/.config/claude-code/config.json:
{
  "mcpServers": {
    "unified-agents": {
      "command": "unified-agent-mcp",
      "args": [
        "--prometheus-path", "~/Prometheus",
        "--everycode-path", "~/EveryCode",
        "--repo", "/path/to/your/repo"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

## Usage Examples

### Example 1: Bug Fixing

```bash
# Claude Code session
/agent-fix-bug "Users can't delete their accounts"

# Flow:
# 1. Prometheus classifies issue
# 2. Prometheus reproduces bug
# 3. Prometheus generates patch
# 4. Every Code Auto Review validates
# 5. Prometheus runs regression tests
# 6. Present verified fix
```

### Example 2: Feature Implementation

```bash
/agent-plan "Add dark mode toggle to settings"

# Flow:
# 1. Every Code generates plan
# 2. Prometheus provides context from similar code
# 3. Present implementation plan
# 4. /agent-implement to execute
```

### Example 3: Code Review

```bash
# After making changes
/agent-review

# Flow:
# 1. Every Code Auto Review runs in background
# 2. Prometheus analyzes AST changes
# 3. Present findings and suggestions
```

## Success Metrics

1. ✅ Both platforms accessible via MCP
2. ✅ Core skills functional
3. ✅ Backend routing works correctly
4. ✅ End-to-end bug fixing working
5. ✅ Auto Drive integration working
6. ✅ Knowledge graph queries working
7. ✅ Documentation complete

## Limitations & Considerations

1. **Complexity**: Two large platforms to integrate
   - Mitigation: Modular design, gradual rollout

2. **Performance**: Knowledge graph queries can be slow
   - Mitigation: Caching, async operations

3. **Setup Complexity**: Multiple dependencies
   - Mitigation: Docker Compose setup script

4. **Cost**: Multiple API calls across platforms
   - Mitigation: Smart caching, cost tracking

5. **Compatibility**: Different data structures
   - Mitigation: Normalization layer in MCP server

## Next Steps

1. ✅ Analyze architectures (COMPLETE)
2. ⏳ Design unified MCP server
3. ⏳ Implement Prometheus backend
4. ⏳ Implement Every Code backend
5. ⏳ Create Claude Code skills
6. ⏳ Test and document