Multi-AI Consultant

What this skill does

# Multi-AI Consultant

Consult external AIs for second opinions when Claude Code is stuck or making critical decisions.

---

## What This Skill Does

This skill enables **future Claude Code sessions** to consult other AIs when:
- Stuck on a bug after one failed attempt
- Making architectural decisions
- Security concerns need validation
- Fresh perspective needed

**Key innovation**: Uses existing CLI tools (`gemini`, `codex`) instead of building MCP servers - much simpler and more maintainable.

---

## When to Use This Skill

### Automatic Triggers (No User Action Needed)

Claude Code should **automatically suggest** using this skill when:

1. **After 1 failed debugging attempt**
   - Tried one approach to fix a bug
   - Still not working or different error
   - → Suggest: "Should I consult [Gemini|Fresh Claude] for a second opinion?"

2. **Before architectural decisions**
   - Significant design choices (state management, routing, data flow)
   - Framework selection
   - Database schema design
   - → Auto-consult (mention to user): "Consulting Gemini for architectural validation..."

3. **Security changes**
   - Authentication logic
   - Authorization rules
   - Cryptography
   - Input validation
   - → Auto-consult: "Consulting Gemini to verify security approach..."

4. **When uncertain**
   - Multiple valid approaches
   - Trade-offs not clear
   - Conflicting advice in documentation
   - → Suggest: "Would you like me to consult another AI for additional perspective?"

### Manual Invocation (User Commands)

User can explicitly request consultation with:
- `/consult-gemini [question]` - Gemini 2.5 Pro with thinking, search, grounding
- `/consult-codex [question]` - OpenAI GPT-4 via Codex CLI (repo-aware)
- `/consult-claude [question]` - Fresh Claude subagent (free, fast)
- `/consult-ai [question]` - Router that asks which AI to use

---

## The Three AIs

| AI | Tool | When to Use | Special Features | Cost |
|----|------|-------------|------------------|------|
| **Gemini 2.5 Pro** | `gemini` CLI | Web research, latest docs, thinking | Google Search, extended reasoning, grounding | ~$0.10-0.50 |
| **OpenAI GPT-4** | `codex` CLI | Repo-aware analysis, code review | Auto-scans directory, OpenAI reasoning | ~$0.05-0.30 |
| **Fresh Claude** | Task tool | Quick second opinion, budget-friendly | Same capabilities, fresh perspective | Free |

---

## How It Works

### Architecture

```
Claude Code encounters bug/decision
        ↓
Suggests consultation (or user requests)
        ↓
User approves
        ↓
Execute appropriate slash command
        ↓
CLI command calls external AI
        ↓
Parse response
        ↓
Synthesize: Claude's analysis + External AI's analysis
        ↓
Present 5-part comparison
        ↓
Ask permission to implement
```

### The 5-Part Synthesis Format

Every consultation must follow this format (prevents parroting):

1. **🤖 My Analysis** - Claude's original reasoning and attempts
2. **💎/🔷/🔄 Other AI's Analysis** - External AI's complete response
3. **🔍 Key Differences** - Agreement, divergence, what each AI caught/missed
4. **⚡ Synthesis** - Combined perspective, root cause, trade-offs
5. **✅ Recommended Action** - Specific next steps with file paths/line numbers

**End with**: "Should I proceed with this approach?"

---

## Setup Instructions

### 1. Install CLIs

**Gemini CLI** (required):
```bash
npm install -g @google/generative-ai-cli
export GEMINI_API_KEY="your-key"
```

Get API key: https://aistudio.google.com/apikey

**Codex CLI** (optional):
```bash
npm install -g codex
export OPENAI_API_KEY="sk-..."
```

Get API key: https://platform.openai.com/api-keys

**Fresh Claude**: Built-in (uses Task tool, no setup)

### 2. Install Skill

```bash
cd ~/.claude/skills
git clone [this-repo] multi-ai-consultant
# OR symlink from development location
```

### 3. Copy Templates to Project

```bash
# Copy to project root
cp ~/.claude/skills/multi-ai-consultant/templates/GEMINI.md ./
cp ~/.claude/skills/multi-ai-consultant/templates/codex.md ./
cp ~/.claude/skills/multi-ai-consultant/templates/.geminiignore ./

# Copy log parser (optional)
cp ~/.claude/skills/multi-ai-consultant/templates/consultation-log-parser.sh ~/bin/
chmod +x ~/bin/consultation-log-parser.sh
```

### 4. Verify Installation

```bash
# Test Gemini CLI
gemini -p "test" && echo "✅ Gemini working"

# Test Codex CLI (if installed)
codex exec "test" --yolo && echo "✅ Codex working"

# Test skill discovery
# Ask Claude Code: "I'm stuck on this bug, can you help?"
# Claude should suggest consultation
```

---

## Usage Examples

### Example 1: Stuck on Bug

**Scenario**: JWT authentication failing after one attempt

**Claude's process**:
```
1. Try initial fix (token expiry check)
2. Still failing (now "invalid signature" error)
3. → Automatically suggest consultation
4. User approves
5. Execute /consult-gemini with:
   - Problem: 401 error details
   - What was tried: token expiry fix
   - Current status: invalid signature error
   - Context: @src/auth/session.ts @src/middleware/jwt.ts
6. Gemini finds: Using process.env instead of env binding (Cloudflare)
7. Synthesize both perspectives
8. Ask permission to implement Gemini's fix
```

**Result**: Bug fixed with second opinion, avoided 2-3 more trial-and-error attempts

### Example 2: Architecture Decision

**Scenario**: Choosing state management for new feature

**Claude's process**:
```
1. User asks: "How should we handle state for this feature?"
2. → Auto-consult Gemini (architectural decision)
3. Execute /consult-gemini with:
   - Problem: State management choice
   - Options considered: Redux, Zustand, Context
   - Context: @src/ (existing patterns)
4. Gemini searches for latest React state management best practices
5. Synthesize Claude's + Gemini's analysis
6. Present recommendation with trade-offs
```

**Result**: Informed decision with latest best practices

### Example 3: Manual Consultation

**User**: "I want a second opinion on this refactoring"

**Claude's process**:
```
1. User explicitly requests consultation
2. Ask which AI: Gemini, Codex, or Fresh Claude?
3. User chooses Codex (wants repo-aware analysis)
4. Execute /consult-codex with:
   - Problem: Refactoring proposal
   - Context: (Codex scans repo automatically)
5. Codex checks consistency with existing code
6. Synthesize both perspectives
7. Present recommendation
```

**Result**: Validation of refactoring approach + consistency check

---

## Slash Commands

### `/consult-gemini [question]`

**Use when**: Need web research, latest docs, extended thinking

**What it does**:
1. Pre-flight check (Gemini CLI working?)
2. Smart context selection based on problem type
3. Execute with locked config: `gemini-2.5-pro --thinking --google-search --grounding`
4. Parse JSON response
5. Synthesize with 5-part format
6. Log cost to `~/.claude/ai-consultations/consultations.log`

**Example**:
```
/consult-gemini Is this JWT validation secure by 2025 standards?
```

**Context**: Uses `@<path>` syntax for selective context

**System instructions**: Auto-loads `GEMINI.md` from project root

**Privacy**: Respects `.gitignore` + `.geminiignore`

---

### `/consult-codex [question]`

**Use when**: Need repo-aware analysis, code review, OpenAI reasoning

**What it does**:
1. Pre-flight check (OpenAI API key valid?)
2. `cd` to project directory (Codex scans automatically)
3. Execute with `--yolo` flag: `codex exec - -m gpt-4-turbo --yolo`
4. Parse output from temp file
5. Synthesize with 5-part format
6. Log cost (estimated tokens)

**Example**:
```
/consult-codex Review this codebase for performance issues
```

**Context**: Repo-aware (automatically reads all non-gitignored files)

**System instructions**: Auto-loads `codex.md` from project root or `~/.codex/instructions.md`

**Privacy**: Respects `.gitignore`, warns if not in Git repo

---

### `/consult-claude [question]`

**Use when**: Quick second opinion, free, fresh perspective

**What it does**:
1. Gather cont