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

# Ralph Auto-Integration with Unified Agents

## Overview

The `/ralph` command now **automatically triggers** the unified agent integration (Prometheus, Every Code, Dexto) based on your task requirements.

## How It Works

When you invoke `/ralph` with a task, the system:

1. **Analyzes your task** using pattern matching
2. **Selects the best agent(s)** automatically
3. **Routes to appropriate MCP servers**
4. **Executes with optimal backend**
5. **Iterates until completion**

## Auto-Trigger Patterns

### Prometheus Auto-Trigger

Automatically activates when your task contains:
- `fix bug`, `debug`, `reproduce issue`
- `test failure`, `regression`
- `classify issue`, `bug report`
- `verify fix`, `patch validation`

**Examples:**
```bash
/ralph "fix the authentication bug in the login flow"
/ralph "debug why the payment processing fails"
/ralph "reproduce the reported issue #123"
/ralph "run regression tests after refactor"
```

**Auto-activated tools:**
- `prometheus_classify_issue`
- `prometheus_fix_bug`
- `prometheus_run_tests`
- `prometheus_get_context`

### Every Code Auto-Trigger

Automatically activates when your task contains:
- `plan`, `implement feature`
- `solve problem`, `optimize`
- `review code`, `quality check`
- `auto drive`, `automate task`
- `browser automation`

**Examples:**
```bash
/ralph "plan and implement user notifications"
/ralph "solve the slow database query problem"
/ralph "review the authentication code for issues"
/ralph "automate the testing pipeline"
```

**Auto-activated tools:**
- `everycode_auto_drive`
- `everycode_plan`
- `everycode_solve`
- `everycode_auto_review`
- `everycode_browser_*`

### Dexto Auto-Trigger

Automatically activates when your task contains:
- `orchestrate workflow`, `coordinate agents`
- `multi-step process`, `pipeline`
- `session management`
- `complex workflow`, `multi-phase`

**Examples:**
```bash
/ralph "orchestrate a complete CI/CD pipeline setup"
/ralph "coordinate multiple agents for refactoring"
/ralph "create a multi-step migration workflow"
/ralph "build a complex testing pipeline"
```

**Auto-activated tools:**
- `dexto_orchestrate`
- `dexto_create_agent`
- `dexto_run_agent`
- `dexto_memory_store`

## Intelligent Backend Selection

Ralph automatically selects the best backend based on task type:

```
┌─────────────────────────────────────────────────────────┐
│                     /ralph Input                         │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
            ┌──────────────────────────────┐
            │   Pattern Matching Engine    │
            └────────────┬─────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │Bug Fix  │    │ Feature │    │Complex  │
    │Pattern  │    │Pattern  │    │Workflow │
    └────┬────┘    └────┬────┘    └────┬────┘
         │              │              │
         ▼              ▼              ▼
    ┌─────────┐    ┌─────────┐    ┌─────────┐
    │Prometheus│   │Every Code│  │  Dexto  │
    │Primary  │    │Primary  │    │Primary │
    └─────────┘    └─────────┘    └─────────┘
```

## Task Type Mapping

| Task Keywords | Primary Agent | Secondary Agent | Tools |
|---------------|---------------|-----------------|-------|
| bug, fix, debug, error, issue | Prometheus | Every Code | classify, fix_bug, test |
| plan, implement, feature, add | Every Code | Prometheus | plan, auto_drive |
| solve, problem, optimize | Every Code | Dexto | solve, orchestrate |
| review, quality, check | Every Code | Prometheus | auto_review, ast_analyze |
| orchestrate, coordinate, workflow | Dexto | Every Code | orchestrate, create_agent |
| context, understand, search | Prometheus | Dexto | search_ast, memory |

## Usage Examples

### Bug Fixing (Auto-triggers Prometheus)

```bash
/ralph "fix the memory leak in the image processing module"
```

**What happens automatically:**
1. Detects "fix" and "memory leak" → **Prometheus activated**
2. Classifies issue → Bug
3. Reproduces in Docker container
4. Retrieves context from knowledge graph
5. Generates patch
6. Runs regression tests
7. Iterates until tests pass

### Feature Implementation (Auto-triggers Every Code)

```bash
/ralph "implement real-time notifications with WebSocket"
```

**What happens automatically:**
1. Detects "implement" → **Every Code activated**
2. Generates implementation plan
3. Gets context from Prometheus (similar features)
4. Executes code generation via Auto Drive
5. Runs Auto Review for quality
6. Iterates until review passes

### Complex Orchestration (Auto-triggers Dexto)

```bash
/ralph "orchestrate migration from REST to GraphQL API"
```

**What happens automatically:**
1. Detects "orchestrate" and "migration" → **Dexto activated**
2. Creates multi-agent workflow
3. Agent 1 (Prometheus): Analyzes existing REST endpoints
4. Agent 2 (Every Code): Implements GraphQL schema
5. Agent 3 (Prometheus): Runs integration tests
6. Coordinators (Dexto): Manages pipeline
7. Iterates until migration complete

### Multi-Platform Tasks

```bash
/ralph "audit, fix, and test all security vulnerabilities"
```

**What happens automatically:**
1. Detects "audit", "fix", "test" → **All platforms activated**
2. **Prometheus**: Security audit via AST analysis
3. **Every Code**: Auto Review for vulnerabilities
4. **Dexto**: Orchestrates fix-verify workflow
4. Coordinates across all three platforms
5. Iterates until all security issues resolved

## Advanced Auto-Trigger Features

### Pattern Combination

Multiple patterns trigger combined agent usage:

```bash
/ralph "fix bug and add tests for authentication flow"
```
→ Prometheus (bug fix) + Every Code (test generation)

```bash
/ralph "plan feature and implement with quality checks"
```
→ Every Code (plan) + Every Code (implement) + Prometheus (review)

### Priority-Based Selection

When multiple agents match, priority is applied:

```
Bug fixing: Prometheus > Every Code > Dexto
Planning: Every Code > Prometheus > Dexto
Orchestration: Dexto > Every Code > Prometheus
```

### Context-Aware Selection

Ralph considers:
- **Repository state**: Git history, recent changes
- **Codebase type**: Language, framework, size
- **Previous iterations**: Learn from what worked
- **Task complexity**: Simple vs complex

## Configuration

The auto-trigger behavior is configured in `~/.ralph/ralph.yml`:

```yaml
# Enable/disable unified agents
unified_agents:
  enabled: true

# Agent selection strategy
agent_selection:
  strategy: intelligent  # or priority, round_robin

# Custom patterns (add your own)
auto_triggers:
  prometheus:
    patterns:
      - "\\bcritical\\s+bug\\b"
      - "\\bsecurity\\s+issue\\b"
```

## Session Persistence

Ralph maintains state across iterations:

```
Iteration 1:
  → Prometheus detects bug
  → Generates patch
  → Tests fail

Iteration 2:
  → Remembers failure
  → Refines patch
  → Tests pass

Iteration 3:
  → Verifies fix
  → Runs regression
  → Completes
```

## Monitoring Progress

```bash
# Check Ralph state
cat ~/.ralph/state.json

# View current iteration
cat ~/.ralph/iterations/final.md

# Monitor in real-time
tail -f ~/.ralph/iterations/*.md
```

## Best Practices

### 1. Be Specific with Keywords

```bash
# Good - Clear trigger
/ralph "fix the authentication bug"

# Better - More context
/ralph "fix the JWT validation bug that causes 401 errors"
```

### 2. Use Multi-Platform Tasks

```bash
# Leverages all platforms
/ralph "audit security, fix vulnerabilities, and test with regression"
```

### 3. Specify Constraints

```bash
# With constraints
/ralph "implement caching with Redis
Constraints: Must handle cache invalidation
Scope: API responses only"
```

### 4. Request Quality Assurance

```bash
# With review
/ralph "refactor user service
Include: code review, tests, documentation"
```

## Troubleshooting

### Wrong Agent Selected

Add explicit keywords:
```bash
/ralph "plan architecture using Prometheus knowledge graph"
/ralph "orchestrate with Dexto workflow"
```

### Agent Not Triggering

Check patterns in `~/.ralph/ralph.yml`:
```bash
grep -A 10 "auto_triggers" ~/.ralph/ralph.yml
```

### Need Manual Control

Override auto-selection:
```bash
/ralph "use Prometheus for: fix memory leak"
/ralph "use Every Code for: implement feature"
```

## Examples by Task Type

### Development Tasks

```bash
# New feature
/ralph "implement OAuth2 authentication"

# Refactoring
/ralph "refactor user service to use GraphQL"

# Performance
/ralph "optimize slow database queries"
```

### Maintenance Tasks

```bash
# Bug fixing
/ralph "fix and test all reported issues"

# Code review
/ralph "review and fix quality issues in PR #123"

# Testing
/ralph "add comprehensive tests for payment module"
```

### Architecture Tasks

```bash
# Migration
/ralph "orchestrate migration from monolith to microservices"

# Integration
/ralph "integrate Stripe payment with webhook handling"

# Documentation
/ralph "document API with examples and tests"
```

## Summary

| Feature | Status |
|---------|--------|
| Prometheus auto-trigger | ✅ Bug fixing, testing, AST analysis |
| Every Code auto-trigger | ✅ Planning, solving, review |
| Dexto auto-trigger | ✅ Orchestration, workflows |
| Pattern matching | ✅ 20+ patterns configured |
| Intelligent routing | ✅ Priority-based selection |
| Multi-platform | ✅ Combined agent usage |
| Session persistence | ✅ State maintained |
| Customizable | ✅ Edit `~/.ralph/ralph.yml` |

**The unified agents are now seamlessly integrated with `/ralph` - just describe your task and Ralph will automatically select and use the best agent(s)!**