ai-consultants 2.10.1

package/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: ai-consultants
+description: Consult Gemini CLI, Codex CLI, Mistral Vibe, Kilo CLI, Cursor, Claude, Amp, Kimi, Qwen, MiniMax, and Ollama as external experts for coding questions. Automatically excludes the invoking agent from the panel to avoid self-consultation. Use when you have doubts about implementations, want a second opinion, need to choose between different approaches, or when explicitly requested with phrases like "ask the consultants", "what do the other models think", "compare solutions", "get expert opinions", "I'm not sure about this approach", "what would other models say". Make sure to consult this skill whenever the user is weighing trade-offs, comparing architectures, validating complex solutions, or wants multiple perspectives on any non-trivial coding decision. Do NOT use for simple questions that only need one model's answer or when you already have high confidence in a solution.
+license: MIT
+compatibility: Requires bash, jq, and at least 2 AI CLI tools (gemini, codex, vibe, etc.). macOS and Linux.
+metadata:
+  author: matteoscurati
+  version: 2.10.1
+---
+
+# AI Consultants v2.10.1 - AI Expert Panel
+
+Simultaneously consult multiple AIs as "consultants" for coding questions. Each consultant has a **configurable persona** that influences their response style.
+
+## Quick Start
+
+```
+/ai-consultants:consult "Your question here"
+```
+
+## 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.
+
+## Consultants and Personas
+
+| Consultant | CLI | Persona | Focus |
+|------------|-----|---------|-------|
+| **Google Gemini** | `gemini` | The Architect | Design patterns, scalability |
+| **OpenAI Codex** | `codex` | The Pragmatist | Simplicity, proven solutions |
+| **Mistral Vibe** | `vibe` | The Devil's Advocate | Edge cases, vulnerabilities |
+| **Kilo Code** | `kilocode` | The Innovator | Creativity, unconventional |
+| **Cursor** | `agent` | The Integrator | Full-stack perspective |
+| **Aider** | `aider` | The Pair Programmer | Collaborative coding |
+| **Amp** | `amp` | The Systems Thinker | System design, interactions |
+| **Kimi** | `kimi` | The Eastern Sage | Holistic, balanced perspectives |
+| **Claude** | `claude` | The Synthesizer | Big picture, synthesis |
+| **Qwen** | `qwen` | The Analyst | Data-driven, metrics |
+| **Ollama** | `ollama` | The Local Expert | Privacy-first, zero cost |
+
+**API-only consultants**: GLM (The Methodologist), Grok (The Provocateur), DeepSeek (The Code Specialist), MiniMax (The Pragmatic Optimizer)
+
+**CLI/API Mode**: Gemini, Codex, Claude, Mistral, and Qwen can switch between CLI and API mode via `*_USE_API` environment variables.
+
+**Self-Exclusion**: The invoking agent is automatically excluded from the panel. When invoked from Claude Code, Claude is excluded; when invoked from Codex CLI, Codex is excluded, etc.
+
+## Requirements
+
+- **At least 2 consultant CLIs** installed and authenticated
+- **jq** for JSON processing
+
+### Quick Install
+
+```bash
+# Option A: npx (recommended, no install needed)
+npx ai-consultants doctor --fix
+npx ai-consultants install  # Install slash commands for Claude Code
+
+# Option B: curl | bash
+curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/scripts/install.sh | bash
+~/.claude/skills/ai-consultants/scripts/doctor.sh --fix
+```
+
+For detailed CLI installation instructions, see [Setup Guide](docs/SETUP.md).
+
+## Usage Examples
+
+```
+/ai-consultants:consult "How to optimize this SQL query?"
+/ai-consultants:consult "Review this authentication flow" src/auth.ts
+/ai-consultants:debate "Microservices or monolith for our new service?"
+```
+
+Presets: `minimal`, `balanced`, `thorough`, `high-stakes`, `local`, `security`, `cost-capped`. Strategies: `majority`, `risk_averse`, `security_first`, `cost_capped`, `compare_only`. See [Reference Details](references/details.md) for full tables, bash usage, and best practices.
+
+## Workflow
+
+Query is classified, then sent to consultants in parallel. Responses are scored, voted on, and synthesized into a recommendation. With debate enabled, consultants cross-critique before final synthesis.
+
+## Features
+
+| Feature | Description | Toggle |
+|---------|-------------|--------|
+| **Personas** | Each consultant has a role that shapes responses | `ENABLE_PERSONA` |
+| **Synthesis** | Auto-combine responses into recommendation | `ENABLE_SYNTHESIS` |
+| **Debate** | Consultants critique each other's answers | `ENABLE_DEBATE` |
+| **Peer Review** | Consultants anonymously rank each other | `ENABLE_PEER_REVIEW` |
+| **Smart Routing** | Auto-select best consultants per question type | `ENABLE_SMART_ROUTING` |
+| **Cost Tracking** | Track API usage costs | `ENABLE_COST_TRACKING` |
+| **Panic Mode** | Auto-add rigor when uncertainty detected | `ENABLE_PANIC_MODE` |
+
+## Configuration
+
+All settings use environment variables. Key toggles:
+
+```bash
+ENABLE_DEBATE=true           # Multi-agent debate
+ENABLE_SYNTHESIS=true        # Automatic synthesis
+ENABLE_PANIC_MODE=auto       # Auto-rigor for uncertainty
+ENABLE_BUDGET_LIMIT=false    # Budget enforcement (v2.4)
+```
+
+Enable opt-in consultants: `ENABLE_AMP`, `ENABLE_KIMI`, `ENABLE_QWEN3`, `ENABLE_CLAUDE`, `ENABLE_OLLAMA`, `ENABLE_MINIMAX`.
+
+CLI/API switching: `GEMINI_USE_API`, `CODEX_USE_API`, `CLAUDE_USE_API`, `MISTRAL_USE_API`, `QWEN3_USE_API`.
+
+See [Full Configuration Reference](references/configuration.md) for all variables, model overrides, tiers, timeouts, and optimization settings.
+
+## Output
+
+```
+/tmp/ai_consultations/TIMESTAMP/
+├── gemini.json        # Individual responses
+├── codex.json
+├── voting.json        # Consensus
+├── synthesis.json     # Recommendation
+└── report.md          # Human-readable
+```
+
+## Doctor Command
+
+Diagnose and fix issues:
+
+```bash
+./scripts/doctor.sh              # Full check
+./scripts/doctor.sh --fix        # Auto-fix
+./scripts/doctor.sh --json       # JSON output
+```
+
+## Interpreting Results
+
+| Scenario | Recommendation |
+|----------|----------------|
+| High confidence + High consensus | Proceed confidently |
+| Low confidence OR Low consensus | Consider more options |
+| Mistral disagrees | Investigate risks |
+| Panic mode triggered | Add debate rounds |
+
+## Troubleshooting
+
+Run `./scripts/doctor.sh` to diagnose issues, or `./scripts/doctor.sh --fix` to auto-fix.
+
+## Extended Documentation
+
+- [Reference Details](references/details.md) - Presets, strategies, best practices, limitations
+- [Full Configuration](references/configuration.md) - All environment variables, models, tiers, timeouts
+- [Setup Guide](docs/SETUP.md) - Installation, authentication
+- [Cost Rates](docs/COST_RATES.md) - Model pricing
+- [Smart Routing](docs/SMART_ROUTING.md) - Category routing
+- [JSON Schema](docs/JSON_SCHEMA.md) - Output format

package/bin/ai-consultants

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# ai-consultants - npm/npx entry point
+# Resolves symlinks (created by npm) and delegates to the real scripts.
+set -euo pipefail
+
+# --- Resolve symlinks to find the real project root ---
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  # Resolve relative symlink
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+BIN_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+PROJECT_ROOT="$(cd -P "$BIN_DIR/.." && pwd)"
+SCRIPTS_DIR="$PROJECT_ROOT/scripts"
+
+# --- Ensure execute permissions (npm can strip them) ---
+ensure_permissions() {
+  local needs_fix=false
+  for f in "$SCRIPTS_DIR"/*.sh "$SCRIPTS_DIR"/lib/*.sh; do
+    [ -f "$f" ] && [ ! -x "$f" ] && needs_fix=true && break
+  done
+  if [ "$needs_fix" = true ]; then
+    chmod +x "$SCRIPTS_DIR"/*.sh 2>/dev/null || true
+    chmod +x "$SCRIPTS_DIR"/lib/*.sh 2>/dev/null || true
+  fi
+}
+ensure_permissions
+
+# --- Version ---
+VERSION="2.10.0"
+
+# --- Subcommand routing ---
+case "${1:-}" in
+  version|--version|-v)
+    echo "ai-consultants v$VERSION"
+    exit 0
+    ;;
+  help|--help|-h)
+    cat <<EOF
+ai-consultants v$VERSION - Multi-model AI deliberation system
+
+Usage:
+  ai-consultants "question" [files...]        Consult AI experts
+  ai-consultants --preset <name> "question"   Use a configuration preset
+  ai-consultants --strategy <name> "question" Use a synthesis strategy
+  ai-consultants doctor [--fix] [--json]      Run diagnostics
+  ai-consultants install                      Install slash commands to ~/.claude/commands/
+  ai-consultants version                      Show version
+  ai-consultants help                         Show this help
+
+Presets:   minimal, balanced, thorough, high-stakes, local, security, cost-capped,
+           max_quality, medium, fast
+
+Strategies: majority, risk_averse, security_first, cost_capped, compare_only
+
+Examples:
+  npx ai-consultants "How to optimize this SQL query?"
+  npx ai-consultants --preset balanced "Redis or Memcached?"
+  npx ai-consultants doctor --fix
+
+Documentation: https://github.com/matteoscurati/ai-consultants
+EOF
+    exit 0
+    ;;
+  doctor)
+    shift
+    exec "$SCRIPTS_DIR/doctor.sh" "$@"
+    ;;
+  install)
+    COMMANDS_SRC="$PROJECT_ROOT/.claude/commands"
+    COMMANDS_DST="$HOME/.claude/commands"
+    if [ ! -d "$COMMANDS_SRC" ]; then
+      echo "Error: slash commands directory not found at $COMMANDS_SRC" >&2
+      exit 1
+    fi
+    mkdir -p "$COMMANDS_DST"
+    copied=0
+    for f in "$COMMANDS_SRC"/ai-consultants:*.md; do
+      [ -f "$f" ] || continue
+      cp "$f" "$COMMANDS_DST/"
+      copied=$((copied + 1))
+    done
+    if [ "$copied" -eq 0 ]; then
+      echo "Warning: no slash command files found in $COMMANDS_SRC" >&2
+      exit 1
+    fi
+    echo "Installed $copied slash commands to $COMMANDS_DST"
+    exit 0
+    ;;
+  *)
+    # Pass everything through to consult_all.sh
+    exec "$SCRIPTS_DIR/consult_all.sh" "$@"
+    ;;
+esac

package/docs/COST_RATES.md

@@ -0,0 +1,172 @@
+# Cost Rates - AI Consultants v2.10.1
+
+This page documents the per-token rates used by the cost tracking system.
+
+## Model Quality Tiers (v2.5+)
+
+Since v2.5, models are organized into three tiers. Use `apply_model_tier()` or `get_model_for_tier()` to select models programmatically.
+
+| Tier | Description | Cost Level |
+|------|-------------|------------|
+| **Premium** | Latest flagship models (default) | Highest |
+| **Standard** | Good quality at reasonable cost | Medium |
+| **Economy** | Optimized for speed and low cost | Lowest |
+
+## Rates per Model (USD per 1K tokens)
+
+### Input Tokens
+
+| Model | Tier | Cost/1K | Consultant |
+|-------|------|---------|------------|
+| gemini-3.1-pro-preview | Premium | $0.00125 | Gemini |
+| gemini-3-flash-preview | Standard | $0.000075 | Gemini |
+| gemini-2.0-flash | Economy | $0.0001 | Gemini |
+| gpt-5.3-codex | Premium | $0.01 | Codex |
+| gpt-5.3 | Standard | $0.005 | Codex |
+| gpt-4o-mini | Economy | $0.00015 | Codex |
+| opus-4.6 | Premium | $0.015 | Claude |
+| sonnet-4.6 | Standard | $0.003 | Claude |
+| haiku-4.5 | Economy | $0.00025 | Claude |
+| mistral-large-3 | Premium | $0.004 | Mistral |
+| mistral-medium-latest | Standard | $0.0027 | Mistral |
+| devstral-small-2 | Economy | $0.001 | Mistral |
+| composer-1.5 | Premium/Standard | $0.005 | Cursor |
+| deepseek-reasoner | Premium | $0.002 | DeepSeek |
+| deepseek-v3.2 | Standard | $0.0014 | DeepSeek |
+| deepseek-chat | Economy | $0.001 | DeepSeek |
+| glm-5 | Premium/Standard | $0.002 | GLM |
+| glm-4-flash | Economy | $0.0005 | GLM |
+| grok-4-1-fast-reasoning | Premium | $0.005 | Grok |
+| grok-3 | Standard | $0.003 | Grok |
+| grok-3-mini | Economy | $0.001 | Grok |
+| qwen3.5-plus | Premium/Standard | $0.002 | Qwen3 |
+| qwen3-32b | Economy | $0.0005 | Qwen3 |
+| MiniMax-M2.5 | Premium | $0.002 | MiniMax |
+| MiniMax-M2.1 | Standard | $0.0015 | MiniMax |
+| MiniMax-M2.5-highspeed | Economy | $0.001 | MiniMax |
+| kimi-code/kimi-for-coding | Premium/Standard | $0.002 | Kimi |
+| auto | All | $0.002 | Kilo (internal routing) |
+| default | - | $0.005 | Fallback |
+
+### Output Tokens
+
+| Model | Tier | Cost/1K | Consultant |
+|-------|------|---------|------------|
+| gemini-3.1-pro-preview | Premium | $0.005 | Gemini |
+| gemini-3-flash-preview | Standard | $0.0003 | Gemini |
+| gemini-2.0-flash | Economy | $0.0004 | Gemini |
+| gpt-5.3-codex | Premium | $0.03 | Codex |
+| gpt-5.3 | Standard | $0.015 | Codex |
+| gpt-4o-mini | Economy | $0.0006 | Codex |
+| opus-4.6 | Premium | $0.075 | Claude |
+| sonnet-4.6 | Standard | $0.015 | Claude |
+| haiku-4.5 | Economy | $0.00125 | Claude |
+| mistral-large-3 | Premium | $0.012 | Mistral |
+| mistral-medium-latest | Standard | $0.0081 | Mistral |
+| devstral-small-2 | Economy | $0.003 | Mistral |
+| composer-1.5 | Premium/Standard | $0.015 | Cursor |
+| deepseek-reasoner | Premium | $0.006 | DeepSeek |
+| deepseek-v3.2 | Standard | $0.004 | DeepSeek |
+| deepseek-chat | Economy | $0.003 | DeepSeek |
+| glm-5 | Premium/Standard | $0.006 | GLM |
+| glm-4-flash | Economy | $0.0015 | GLM |
+| grok-4-1-fast-reasoning | Premium | $0.015 | Grok |
+| grok-3 | Standard | $0.009 | Grok |
+| grok-3-mini | Economy | $0.003 | Grok |
+| qwen3.5-plus | Premium/Standard | $0.006 | Qwen3 |
+| qwen3-32b | Economy | $0.0015 | Qwen3 |
+| MiniMax-M2.5 | Premium | $0.006 | MiniMax |
+| MiniMax-M2.1 | Standard | $0.004 | MiniMax |
+| MiniMax-M2.5-highspeed | Economy | $0.003 | MiniMax |
+| kimi-code/kimi-for-coding | Premium/Standard | $0.006 | Kimi |
+| auto | All | $0.006 | Kilo |
+| default | - | $0.015 | Fallback |
+
+## Cost Estimation per Session
+
+### Typical Consultation
+
+**Parameters:**
+- 4 active consultants
+- ~5000 characters of context
+- ~1000 input tokens per consultant (estimate: 4 char/token)
+- ~750 output tokens per consultant
+
+**Estimated cost:** $0.02 - $0.05
+
+### With Multi-Agent Debate (2 rounds)
+
+**Additional parameters:**
+- +1 round with same context
+- Previous responses as additional input
+
+**Estimated cost:** $0.08 - $0.15
+
+### With Self-Reflection
+
+**Additional parameters:**
+- Critique + refinement cycle per consultant
+- ~500 additional tokens per cycle
+
+**Estimated cost:** $0.10 - $0.20
+
+## Budget Management
+
+### Configuration Variables
+
+```bash
+# Maximum budget per session
+MAX_SESSION_COST=1.00
+
+# Warning threshold
+WARN_AT_COST=0.50
+
+# Budget enforcement (v2.4, opt-in)
+ENABLE_BUDGET_LIMIT=false
+BUDGET_ACTION=warn  # warn or stop
+
+# Cumulative tracking file
+COST_TRACKING_FILE=/tmp/ai_consultants_costs.json
+```
+
+### Behavior
+
+1. **Pre-consultation**: Estimated cost shown before execution
+2. **Warning**: Alert if cost exceeds `WARN_AT_COST`
+3. **Budget check**: Error if cost exceeds `MAX_SESSION_COST`
+4. **Tracking**: Costs recorded in `COST_TRACKING_FILE`
+
+### Cost Report
+
+```bash
+# Generate cost report
+source scripts/lib/costs.sh
+generate_cost_report
+```
+
+Output:
+```
+Total sessions: 15
+Total cost: $0.4523
+Average per session: $0.0301
+```
+
+## Technical Notes
+
+### Token Estimation
+
+The system estimates tokens using the heuristic:
+- **4 characters = 1 token** (approximation)
+- Assumed split: **60% input, 40% output**
+
+This is a conservative estimate. Actual costs may vary.
+
+### Data Source
+
+Rates are defined in `scripts/lib/costs.sh` and are periodically updated to reflect official provider pricing.
+
+### Dependencies
+
+Cost tracking requires:
+- `bc` - For floating point calculations
+- `jq` - For JSON parsing