ai-consultants 2.10.1

package/docs/SETUP.md

@@ -0,0 +1,879 @@
+# Setup Guide - AI Consultants v2.10
+
+This guide walks you through installing and configuring AI Consultants for various AI coding agents.
+
+---
+
+## Supported Agents
+
+AI Consultants follows the open [Agent Skills standard](https://agentskills.io), enabling cross-platform compatibility:
+
+| Agent | Skills Directory | Status |
+|-------|-----------------|--------|
+| **Claude Code** | `~/.claude/skills/` | ✅ Native |
+| **OpenAI Codex CLI** | `~/.codex/skills/` | ✅ Compatible |
+| **Gemini CLI** | `~/.gemini/skills/` | ✅ Compatible |
+| **Kilo Code** | Via agentskills | ✅ Compatible |
+| **GitHub Copilot** | Via SkillPort | ✅ Via AGENTS.md |
+| **Cursor** | Via SkillPort | ✅ Via SkillPort |
+| **Windsurf** | Via SkillPort | ✅ Via SkillPort |
+| **Aider** | Via AGENTS.md | ✅ Via AGENTS.md |
+
+---
+
+## Claude Code Setup (Recommended)
+
+AI Consultants is designed as a **Claude Code skill**. This is the fastest and easiest way to get started.
+
+### Step 1: Install the Skill
+
+```bash
+# One-liner installation
+curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/scripts/install.sh | bash
+```
+
+This installs to `~/.claude/skills/ai-consultants/` and makes slash commands available in Claude Code.
+
+### Step 2: Verify Installation
+
+```bash
+./scripts/doctor.sh --fix
+```
+
+You should see at least 2 consultants marked as available.
+
+### Step 3: Your First Consultation
+
+```
+/ai-consultants:consult "What's the best way to structure a REST API?"
+```
+
+That's it! You're ready to go.
+
+---
+
+## Claude Code Slash Commands
+
+AI Consultants provides 3 slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/ai-consultants:consult` | Main consultation - ask AI consultants a coding question |
+| `/ai-consultants:debate` | Run consultation with multi-round debate |
+| `/ai-consultants:help` | Show all commands and usage |
+
+Configuration (presets, strategies, features, personas, API keys) can be managed via natural language — just ask.
+
+All settings are saved to `~/.claude/skills/ai-consultants/.env`.
+
+---
+
+## OpenAI Codex CLI Setup
+
+Codex CLI supports the Agent Skills standard and can use AI Consultants directly.
+
+### Step 1: Install the Skill
+
+```bash
+# Option A: Clone directly
+git clone https://github.com/matteoscurati/ai-consultants.git ~/.codex/skills/ai-consultants
+
+# Option B: Symlink from existing installation
+ln -s ~/.claude/skills/ai-consultants ~/.codex/skills/ai-consultants
+
+# Option C: Symlink from any location
+ln -s /path/to/ai-consultants ~/.codex/skills/ai-consultants
+```
+
+### Step 2: Verify Installation
+
+```bash
+~/.codex/skills/ai-consultants/scripts/doctor.sh --fix
+```
+
+### Step 3: Use in Codex
+
+Once installed, Codex CLI will discover the skill and make slash commands available.
+
+---
+
+## Gemini CLI Setup
+
+Gemini CLI also supports the Agent Skills standard.
+
+### Installation
+
+```bash
+# Option A: Clone directly
+git clone https://github.com/matteoscurati/ai-consultants.git ~/.gemini/skills/ai-consultants
+
+# Option B: Symlink
+ln -s ~/.claude/skills/ai-consultants ~/.gemini/skills/ai-consultants
+```
+
+### Verify
+
+```bash
+~/.gemini/skills/ai-consultants/scripts/doctor.sh
+```
+
+---
+
+## SkillPort Setup (Multi-Agent)
+
+[SkillPort](https://github.com/gotalab/skillport) is a universal skill manager that enables skill portability across agents like Cursor, Copilot, and Windsurf.
+
+### Step 1: Install SkillPort
+
+```bash
+npm install -g skillport
+```
+
+### Step 2: Add AI Consultants
+
+```bash
+# From GitHub
+skillport add github.com/matteoscurati/ai-consultants
+
+# Or from local clone
+git clone https://github.com/matteoscurati/ai-consultants.git
+cd ai-consultants
+./scripts/skillport-install.sh
+```
+
+### Step 3: Verify Installation
+
+```bash
+skillport list                    # Should show ai-consultants
+./scripts/skillport-install.sh status  # Detailed status
+```
+
+### Step 4: Use in Your Agent
+
+```bash
+# Load skill on demand
+skillport show ai-consultants
+```
+
+SkillPort also generates `AGENTS.md` for agents that use that format (Copilot, Cursor, Aider).
+
+---
+
+## Generic agentskills Setup
+
+For any agent that supports the [agentskills.io](https://agentskills.io) standard:
+
+### Installation
+
+```bash
+# Clone to the agent's skills directory
+git clone https://github.com/matteoscurati/ai-consultants.git ~/.{agent}/skills/ai-consultants
+
+# Replace {agent} with your agent name (claude, codex, gemini, etc.)
+```
+
+### Files Available
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Primary skill specification (agentskills.io format) |
+| `AGENTS.md` | Alternative discovery format (Copilot/Cursor/Aider) |
+| `scripts/` | Executable scripts for consultations |
+
+---
+
+## Prerequisites
+
+Before installing consultant CLIs, ensure you have:
+
+### Required
+- **jq** for JSON processing
+- **curl** for API connectivity checks
+
+### Recommended
+- **Bash 4.0+** (macOS ships with 3.2 - install newer version)
+- **timeout/gtimeout** for command timeouts (has POSIX fallback)
+- **Node.js 18+** for npm-based CLIs
+- **Python 3.8+** for pip-based CLIs
+
+### Optional
+- **bc** for cost calculations (usually pre-installed)
+
+### Install Bash 4+ (macOS)
+
+```bash
+brew install bash
+sudo bash -c 'echo /opt/homebrew/bin/bash >> /etc/shells'
+```
+
+### Install jq
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# Verify
+jq --version
+```
+
+### Install timeout (macOS)
+
+macOS doesn't include `timeout` by default. Install coreutils for `gtimeout`:
+
+```bash
+brew install coreutils
+
+# Verify (gtimeout on macOS, timeout on Linux)
+gtimeout --version
+```
+
+> **Note:** If timeout/gtimeout is not available, AI Consultants uses a POSIX fallback.
+
+---
+
+## Consultant CLIs
+
+You need **at least 2 consultants** configured for AI Consultants to work.
+
+### Gemini CLI (The Architect)
+
+```bash
+npm install -g @google/gemini-cli
+
+# Authentication
+gemini auth login
+# OR: export GOOGLE_API_KEY="your-key"
+```
+
+Get API key: [Google AI Studio](https://makersuite.google.com/app/apikey)
+
+### Codex CLI (The Pragmatist)
+
+```bash
+npm install -g @openai/codex
+
+# Authentication
+export OPENAI_API_KEY="sk-your-key"
+```
+
+Get API key: [OpenAI Platform](https://platform.openai.com/api-keys)
+
+### Mistral Vibe CLI (The Devil's Advocate)
+
+```bash
+pip install mistral-vibe
+
+# Authentication
+export MISTRAL_API_KEY="your-key"
+```
+
+Get API key: [Mistral Console](https://console.mistral.ai/api-keys/)
+
+### Kilo CLI (The Innovator)
+
+```bash
+npm install -g @kilocode/cli
+
+# Authentication
+kilocode auth login
+```
+
+### Cursor CLI (The Integrator)
+
+```bash
+curl https://cursor.com/install -fsS | bash
+
+# Uses Cursor subscription - no additional key needed
+```
+
+### Aider CLI (The Pair Programmer)
+
+```bash
+pip install aider-chat
+
+# Authentication
+export OPENAI_API_KEY="sk-your-key"  # Or other provider
+```
+
+### Claude CLI (The Synthesizer) - v2.2
+
+```bash
+# Claude CLI is part of Claude Code
+# See https://docs.anthropic.com/en/docs/claude-code for installation
+
+# Verify installation
+claude --version
+```
+
+### Qwen CLI (The Analyst) - v2.7
+
+```bash
+npm install -g @qwen-code/qwen-code@latest
+
+# Verify installation
+qwen --version
+
+# Or use API mode
+export QWEN3_USE_API=true
+export QWEN3_API_KEY="your-dashscope-key"
+```
+
+Get API key: [Alibaba Cloud DashScope](https://dashscope.console.aliyun.com/)
+
+**CLI/API Mode**: Qwen3 defaults to CLI mode (`QWEN3_USE_API=false`). Set to `true` to use the DashScope API.
+
+### Amp CLI (The Systems Thinker) - v2.8
+
+```bash
+# One-liner installation
+curl -fsSL https://ampcode.com/install.sh | bash
+
+# Verify installation
+amp --version
+
+# Authentication
+export AMP_API_KEY="your-amp-key"
+```
+
+Get API key: [Amp Code](https://ampcode.com)
+
+**Usage**: Amp CLI uses `-x` flag for non-interactive execution (required for script integration).
+
+### Kimi CLI (The Eastern Sage) - v2.9
+
+```bash
+curl -L code.kimi.com/install.sh | bash
+```
+
+Verify: `kimi --version`
+
+### MiniMax (API-only) - v2.10
+
+MiniMax requires an API key — no CLI installation needed.
+
+```bash
+export MINIMAX_API_KEY="your-key"
+export ENABLE_MINIMAX=true
+```
+
+---
+
+## Ollama (Local Models) - v2.2
+
+Run consultations 100% locally with zero API cost and full privacy.
+
+### Installation
+
+**macOS/Linux:**
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+**macOS (Homebrew):**
+```bash
+brew install ollama
+```
+
+**Verify installation:**
+```bash
+ollama --version
+```
+
+### Start Server
+
+Ollama needs a running server:
+
+```bash
+# Start in background
+ollama serve &
+
+# Or start manually before consultation
+ollama serve
+```
+
+### Pull Models
+
+```bash
+# Recommended for general use
+ollama pull llama3.2
+
+# For code-specific tasks
+ollama pull codellama
+ollama pull deepseek-coder
+
+# Smaller/faster options
+ollama pull mistral
+ollama pull qwen2.5-coder
+```
+
+### Configuration
+
+**Environment variables:**
+```bash
+# Enable Ollama consultant
+export ENABLE_OLLAMA=true
+
+# Choose model (default: qwen2.5-coder:32b)
+export OLLAMA_MODEL=qwen2.5-coder:32b
+
+# Server URL (default: localhost)
+export OLLAMA_HOST=http://localhost:11434
+
+# Timeout (default: 300s - longer for local inference)
+export OLLAMA_TIMEOUT=300
+```
+
+### Usage
+
+**Bash:**
+```bash
+# Use local preset (Ollama only)
+./scripts/consult_all.sh --preset local "Your question"
+
+# Add Ollama to other presets
+ENABLE_OLLAMA=true ./scripts/consult_all.sh --preset balanced "Question"
+```
+
+### Multi-Model Local
+
+Query multiple local models:
+
+```bash
+export OLLAMA_MODELS="llama3.2,codellama,mistral"
+./scripts/consult_all.sh --preset local "Question"
+```
+
+### Troubleshooting Ollama
+
+**Server not running:**
+```bash
+# Check if running
+curl http://localhost:11434/api/tags
+
+# Start server
+ollama serve
+```
+
+**Model not found:**
+```bash
+# List available models
+ollama list
+
+# Pull missing model
+ollama pull llama3.2
+```
+
+**Slow inference:**
+- Use smaller models (`mistral`, `qwen2.5-coder:7b`)
+- Increase timeout: `OLLAMA_TIMEOUT=600`
+
+---
+
+## Self-Exclusion (v2.2)
+
+When AI Consultants is invoked from a specific AI agent, that agent is automatically excluded from the consultant panel to prevent self-consultation.
+
+### How It Works
+
+| Invoking Agent | Excluded Consultant | Other Consultants |
+|----------------|---------------------|-------------------|
+| Claude Code | Claude | Gemini, Codex, Mistral, Kilo, Cursor, Amp, Qwen, etc. |
+| Codex CLI | Codex | Claude, Gemini, Mistral, Kilo, Cursor, Amp, Qwen, etc. |
+| Gemini CLI | Gemini | Claude, Codex, Mistral, Kilo, Cursor, Amp, Qwen, etc. |
+| Cursor | Cursor | Claude, Gemini, Codex, Mistral, Kilo, Amp, Qwen, etc. |
+| Amp CLI | Amp | Claude, Gemini, Codex, Mistral, Kilo, Cursor, Qwen, etc. |
+| Qwen CLI | Qwen3 | Claude, Gemini, Codex, Mistral, Kilo, Cursor, Amp, etc. |
+| Kimi CLI | Kimi | All except Kimi |
+| Bash (direct) | None | All enabled consultants (up to 15) |
+
+### Automatic Detection
+
+When using slash commands, `INVOKING_AGENT` is set automatically:
+- Claude Code: `/ai-consultants:consult` sets `INVOKING_AGENT=claude`
+- Codex CLI: `/ai-consultants:consult` sets `INVOKING_AGENT=codex`
+- Gemini CLI: `/ai-consultants:consult` sets `INVOKING_AGENT=gemini`
+
+### Manual Usage (Bash)
+
+```bash
+# Claude excluded from panel
+INVOKING_AGENT=claude ./scripts/consult_all.sh "Question"
+
+# Codex excluded from panel
+INVOKING_AGENT=codex ./scripts/consult_all.sh "Question"
+
+# No exclusion (all enabled consultants)
+./scripts/consult_all.sh "Question"
+```
+
+---
+
+## CLI/API Mode Switching (v2.6+)
+
+Five consultants can switch between CLI mode (using local CLI tools) and API mode (direct API calls): **Gemini, Codex, Claude, Mistral, and Qwen3**.
+
+### Why Use API Mode?
+
+- **No CLI installation required**: Use API keys without installing CLI tools
+- **Consistent behavior**: API responses are more predictable
+- **Easier deployment**: No need to manage CLI binaries
+
+### Configuration
+
+```bash
+# Enable API mode for individual consultants
+export GEMINI_USE_API=true
+export GEMINI_API_KEY="your-google-ai-key"
+
+export CODEX_USE_API=true
+export OPENAI_API_KEY="sk-..."
+
+export CLAUDE_USE_API=true
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+export MISTRAL_USE_API=true
+export MISTRAL_API_KEY="your-mistral-key"
+
+export QWEN3_USE_API=true   # Enable API mode for Qwen3
+export QWEN3_API_KEY="your-dashscope-key"
+```
+
+### API Endpoints (Custom)
+
+```bash
+GEMINI_API_URL=https://generativelanguage.googleapis.com/v1beta/models
+CODEX_API_URL=https://api.openai.com/v1/chat/completions
+CLAUDE_API_URL=https://api.anthropic.com/v1/messages
+MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
+QWEN3_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
+```
+
+### Mode Detection
+
+Check current mode with doctor command:
+
+```bash
+./scripts/doctor.sh --verbose
+# Shows:
+#   ✓ Gemini: API mode (key: AIza...1234)
+#   ○ Codex: CLI mode
+#   ○ Claude: CLI mode
+#   ○ Mistral: CLI mode
+#   ✓ Qwen3: API mode (key: sk-...abcd)
+```
+
+---
+
+## Configuration Presets (v2.2)
+
+Presets let you quickly configure how many consultants to use.
+
+### Available Presets
+
+| Preset | Consultants | Use Case |
+|--------|-------------|----------|
+| `minimal` | 2 (Gemini + Codex) | Quick, cheap |
+| `balanced` | 4 (+ Mistral + Kilo) | Standard |
+| `thorough` | 5 (+ Cursor) | Comprehensive |
+| `high-stakes` | All + debate | Critical decisions |
+| `local` | Ollama only | Privacy |
+| `security` | Security-focused + debate | Security reviews |
+| `cost-capped` | Budget-friendly | Low cost |
+
+### Set Default Preset
+
+**Bash:**
+```bash
+# Add to .env
+DEFAULT_PRESET=balanced
+```
+
+### Override Per Consultation
+
+**Claude Code:** Specify in your question context.
+
+**Bash:**
+```bash
+./scripts/consult_all.sh --preset high-stakes "Critical question"
+```
+
+---
+
+## Synthesis Strategies (v2.2)
+
+Strategies control how consultant responses are combined.
+
+### Available Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `majority` | Simple voting, most common answer wins (default) |
+| `risk_averse` | Weight conservative responses higher |
+| `security_first` | Prioritize security-focused insights |
+| `cost_capped` | Prefer simpler, cheaper solutions |
+| `compare_only` | No recommendation, just comparison |
+
+### Set Default Strategy
+
+**Bash:**
+```bash
+# Add to .env
+DEFAULT_STRATEGY=risk_averse
+```
+
+### Strategy Recommendations
+
+| Use Case | Recommended Strategy |
+|----------|---------------------|
+| General questions | `majority` |
+| Production deployments | `risk_averse` |
+| Security audits | `security_first` |
+| Budget constraints | `cost_capped` |
+| Learning/exploration | `compare_only` |
+
+---
+
+## Environment Configuration
+
+### Using .env file
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```bash
+# Enable/disable consultants (15 available)
+ENABLE_GEMINI=true
+ENABLE_CODEX=true
+ENABLE_CLAUDE=false    # Auto-excluded when invoked from Claude Code
+ENABLE_MISTRAL=false
+ENABLE_KILO=false
+ENABLE_CURSOR=false
+ENABLE_AIDER=false
+ENABLE_AMP=false       # v2.8: The Systems Thinker
+ENABLE_QWEN3=false     # v2.7: The Analyst (CLI/API)
+ENABLE_GLM=false
+ENABLE_GROK=false
+ENABLE_DEEPSEEK=false
+ENABLE_KIMI=true
+ENABLE_MINIMAX=true
+MINIMAX_API_KEY=your-key
+ENABLE_OLLAMA=true
+
+# Self-exclusion (v2.2)
+INVOKING_AGENT=unknown  # Set automatically by slash commands
+
+# API Keys
+GOOGLE_API_KEY=your-key
+OPENAI_API_KEY=sk-your-key
+MISTRAL_API_KEY=your-key
+ANTHROPIC_API_KEY=sk-ant-your-key
+AMP_API_KEY=your-amp-key
+QWEN3_API_KEY=your-dashscope-key
+
+# CLI/API Mode Switching (v2.6+)
+GEMINI_USE_API=false
+CODEX_USE_API=false
+CLAUDE_USE_API=false
+MISTRAL_USE_API=false
+QWEN3_USE_API=false    # Default: CLI mode
+
+# Defaults (v2.8)
+DEFAULT_PRESET=balanced
+DEFAULT_STRATEGY=majority
+
+# Ollama
+OLLAMA_MODEL=qwen2.5-coder:32b
+
+# Features
+ENABLE_DEBATE=false
+ENABLE_SYNTHESIS=true
+ENABLE_PANIC_MODE=auto
+
+# Budget (v2.4)
+ENABLE_BUDGET_LIMIT=false
+MAX_SESSION_COST=1.00
+BUDGET_ACTION=warn
+```
+
+### Minimum Requirements
+
+**At least 2 consultants must be enabled.**
+
+Example configurations:
+
+**OpenAI + Google:**
+```bash
+ENABLE_GEMINI=true
+ENABLE_CODEX=true
+ENABLE_MISTRAL=false
+ENABLE_KILO=false
+```
+
+**OpenAI + Local:**
+```bash
+ENABLE_CODEX=true
+ENABLE_OLLAMA=true
+ENABLE_GEMINI=false
+ENABLE_MISTRAL=false
+```
+
+**Local only:**
+```bash
+ENABLE_OLLAMA=true
+OLLAMA_MODELS="llama3.2,codellama"
+# All others false
+```
+
+---
+
+## Verification
+
+### Doctor Command
+
+```bash
+./scripts/doctor.sh
+```
+
+Checks:
+- CLI tools installed
+- API keys configured
+- Ollama server running
+- Configuration valid
+
+**Auto-fix issues:**
+```bash
+./scripts/doctor.sh --fix
+```
+
+### Preflight Check
+
+```bash
+./scripts/preflight_check.sh
+```
+
+Expected output:
+```
+[OK] jq installed
+[OK] Gemini CLI installed and authenticated
+[OK] Codex CLI installed and authenticated
+[OK] Ollama server running
+
+Status: Ready (3/4 consultants available)
+```
+
+### Setup Wizard (Bash)
+
+Interactive configuration:
+
+```bash
+./scripts/setup_wizard.sh
+```
+
+The wizard will:
+1. Check installed CLIs
+2. Test authentication
+3. Suggest configuration
+4. Generate `.env` file
+
+---
+
+## Troubleshooting
+
+### "Command not found" errors
+
+```bash
+# Check npm global path
+npm list -g --depth=0
+
+# Check pip packages
+pip list | grep mistral
+```
+
+### Authentication failures
+
+**Gemini:**
+```bash
+gemini auth logout
+gemini auth login
+```
+
+**Codex:**
+```bash
+echo $OPENAI_API_KEY  # Verify set
+```
+
+### Timeout errors
+
+Increase timeout in `.env`:
+```bash
+GEMINI_TIMEOUT=300
+CODEX_TIMEOUT=300
+OLLAMA_TIMEOUT=600  # Local models need more time
+```
+
+### "Less than 2 consultants" error
+
+Either:
+1. Install another CLI
+2. Enable Ollama for local inference
+3. Run `./scripts/doctor.sh --fix`
+
+### Claude Code Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Unknown skill" | Run install script again |
+| Commands not showing | Restart Claude Code |
+| "Exit code 1" | Run `./scripts/doctor.sh` |
+| Configuration not saving | Check file permissions on `~/.claude/skills/` |
+
+---
+
+## Platform-Specific Notes
+
+### macOS
+
+Install coreutils for better timeout handling:
+```bash
+brew install coreutils bash
+```
+
+### Windows
+
+Use WSL (Windows Subsystem for Linux):
+```bash
+wsl --install
+# Then follow Linux instructions
+```
+
+### Linux
+
+No special requirements. Ensure `timeout` is available.
+
+---
+
+## Next Steps
+
+After setup:
+
+**Claude Code:**
+```
+/ai-consultants:consult "How do I optimize a SQL query?"
+```
+
+**Bash:**
+```bash
+# Test your configuration
+./scripts/consult_all.sh --preset minimal "How do I optimize a SQL query?"
+
+# View the report
+cat /tmp/ai_consultations/*/report.md
+```
+
+See [README.md](../README.md) for usage examples and full documentation.