---
name: orch
description: Query multiple AI models for consensus decisions, second opinions, and devil's advocate analysis using the orch CLI.
---

# Orch - Multi-Model Consensus Skill

Query multiple AI models simultaneously and aggregate their perspectives. Use this when you need:
- A second opinion on your reasoning
- Multiple perspectives on a decision
- Devil's advocate analysis
- Brainstorming from diverse viewpoints

## When to Use

Invoke this skill when:
- Making architectural or design decisions ("Should we use X or Y?")
- Reviewing your own proposed solution before presenting to user
- The user asks for multiple AI perspectives
- You want to stress-test an approach with opposing viewpoints
- Complex tradeoffs where different perspectives would help

## Invocation

The `orch` CLI is available globally:

```bash
orch <command> [args...]
```

## Commands

### orch consensus

Query multiple models for their verdict on a question.

```bash
orch consensus "PROMPT" MODEL1 MODEL2 [MODEL3...]
```

**Model Aliases** (use these):

| Alias | Model | Notes |
|-------|-------|-------|
| `flash` | gemini-3-flash-preview | Fast, free |
| `gemini` | gemini-3-pro-preview | Strong reasoning, free |
| `gpt` / `gpt5` | gpt-5.2 | Strong reasoning |
| `gpt4` | gpt-4o | Legacy |
| `claude` / `sonnet` | claude-sonnet-4.5 | Balanced (via OpenRouter) |
| `haiku` | claude-haiku-4.5 | Fast, cheap |
| `opus` | claude-opus-4.5 | Strongest, expensive |
| `deepseek` | deepseek-v3.2 | Good value |
| `r1` | deepseek-r1-0528 | Reasoning model, expensive |
| `qwen` | qwen3-235b-a22b | Good value |
| `qwen-fast` | qwen3-8b | Very fast/cheap |
| `glm` | glm-4.7 | Reasoning capable |
| `sonar` | perplexity/sonar | Web search built-in |
| `sonar-pro` | perplexity/sonar-pro | Better web search |

Use `orch models` to see all available models with pricing and status.

## Model Selection

**Quick sanity check**: Use `flash qwen-fast` for fast, cheap validation. Good for "am I missing something obvious?" checks.

**Standard consensus**: Use `flash gemini deepseek` for balanced perspectives across providers. Default for most decisions.

**Deep analysis**: Include `r1` or `gpt` when stakes are high or reasoning is complex. These models think longer but cost more. Use `--allow-expensive` for r1/opus.

**Diverse viewpoints**: Mix providers (Google + DeepSeek + OpenAI + Anthropic) rather than multiple models from one provider. Different training leads to genuinely different perspectives.

**Cost-conscious**: `flash` and `qwen-fast` are 10-100x cheaper than premium models. Start cheap, escalate if needed.

**Options**:
- `--mode vote` (default) - Models give Support/Oppose/Neutral verdict
- `--mode brainstorm` - Generate ideas without judgment
- `--mode critique` - Find flaws and weaknesses
- `--mode open` - Freeform responses, no structured output
- `--temperature 0.1` - Lower = more focused (default 0.1)
- `--file PATH` - Include file as context (can use multiple times)
- `--websearch` - Enable web search (Gemini models only)
- `--serial` - Run models in sequence instead of parallel
- `--strategy` - Serial strategy: neutral (default), refine, debate, brainstorm
- `--synthesize MODEL` - Aggregate all responses into summary using MODEL
- `--allow-expensive` - Allow expensive/slow models (opus, r1)
- `--timeout SECS` - Timeout per model (default 300)

**Stances** (devil's advocate):
Append `:for`, `:against`, or `:neutral` to bias a model's perspective:
```bash
orch consensus "Should we rewrite in Rust?" gpt:for claude:against gemini:neutral
```

**Stdin piping**:
```bash
cat code.py | orch consensus "Is this implementation correct?" flash gemini
```

### orch chat

Single-model conversation for deeper exploration:
```bash
orch chat "MESSAGE" --model gemini
```

Options:
- `--model MODEL` - Model to use (default: gemini)
- `--session ID` - Continue an existing session
- `--format json` - Return structured output with session_id
- `--file PATH` - Attach file
- `--websearch` / `--no-websearch` - Toggle search (default: on)
- `--allow-expensive` - Allow expensive models

Use chat instead of consensus when:
- You need iterative refinement through follow-up questions
- The problem requires deeper exploration than a single query
- You want to build on previous responses

### orch models

List and inspect available models:
```bash
orch models                   # List all models with status
orch models resolve <alias>   # Show details for specific alias
```

### orch sessions

Manage conversation sessions:
```bash
orch sessions list              # List all sessions
orch sessions show <id>         # Show session details
orch sessions clean 7d          # Delete sessions older than 7 days
orch sessions export <id>       # Export session as JSON
```

## Usage Patterns

### Quick Second Opinion
When you've reasoned through something and want validation:
```bash
orch consensus "I think we should use SQLite for this because [reasons]. Is this sound?" flash gemini
```

### Architecture Decision
When facing a tradeoff:
```bash
orch consensus "Microservices vs monolith for a 3-person team building an e-commerce site?" flash gemini gpt --mode vote
```

### Code Review
Include the code as context:
```bash
orch consensus "Is this error handling approach correct and complete?" flash gemini --file src/handler.py
```

### Devil's Advocate
Get opposing viewpoints deliberately:
```bash
orch consensus "Should we adopt Kubernetes?" gpt:for claude:against flash:neutral
```

### Brainstorm
Generate diverse ideas:
```bash
orch consensus "How could we improve the CI/CD pipeline?" flash gemini deepseek --mode brainstorm
```

### Critique Your Work
Find weaknesses before presenting:
```bash
orch consensus "What are the flaws in this API design?" flash gemini --file api-spec.yaml --mode critique
```

### Synthesize Responses
Get a unified summary from multiple perspectives:
```bash
orch consensus "Evaluate this architecture" flash gemini gpt --synthesize gemini
```

### Use Reasoning Models
For complex analysis requiring deep thinking:
```bash
orch consensus "Analyze the security implications" r1 gemini --allow-expensive
```

## Conversational Patterns

### Session-Based Multi-Turn

Start a conversation and continue it with follow-ups:

```bash
# Initial query - capture session ID
RESPONSE=$(orch chat "Analyze this error log" --model gemini --format json --file error.log)
SESSION=$(echo "$RESPONSE" | jq -r '.session_id')

# Follow up with context preserved
orch chat "What could cause this in a containerized environment?" --model gemini --session "$SESSION"

# Dig deeper
orch chat "How would I debug this?" --model gemini --session "$SESSION"
```

### Session Inspection

Review what happened in a conversation:

```bash
# List recent sessions
orch sessions list

# Show full conversation
orch sessions show "$SESSION"

# Show just last 2 exchanges
orch sessions show "$SESSION" --last 2 --format text

# Export for archival
orch sessions export "$SESSION" > conversation.json
```

### Cross-Model Dialogue

Get one model's analysis, then ask another to respond:

```bash
# Get Claude's take
CLAUDE=$(orch chat "Review this API design" --model claude --format json --file api.yaml)
CLAUDE_SAYS=$(echo "$CLAUDE" | jq -r '.content')

# Ask Gemini to critique Claude's review
orch chat "Claude reviewed an API and said:

$CLAUDE_SAYS

Do you agree? What did Claude miss?" --model gemini
```

### Iterative Refinement

Build up a solution through conversation:

```bash
# Start with requirements
SESSION=$(orch chat "Design a caching strategy for this service" --model gemini --format json --file service.py | jq -r '.session_id')

# Add constraints
orch chat "Add constraint: must work in multi-region deployment" --model gemini --session "$SESSION"

# Request implementation
orch chat "Show me the implementation" --model gemini --session "$SESSION"
```

### When to Use Conversations vs Consensus

| Scenario | Use | Why |
|----------|-----|-----|
| Quick decision validation | `consensus` | Parallel opinions, fast |
| Deep problem exploration | `chat` with sessions | Build context iteratively |
| Multiple perspectives needed | `consensus` | Different viewpoints simultaneously |
| Follow-up questions likely | `chat` with sessions | Preserve conversation state |
| Stress-testing an idea | `consensus` with stances | Devil's advocate pattern |
| Explaining your reasoning | `chat` | Interactive dialogue |
| Complex multi-step analysis | `chat` then `consensus` | Explore, then validate |

### Combined Pattern: Explore Then Validate

Use chat to develop an idea, then consensus to validate:

```bash
# Explore with one model
SESSION=$(orch chat "Help me design error handling for this CLI" --model gemini --format json | jq -r '.session_id')
orch chat "What about retry logic?" --model gemini --session "$SESSION"
DESIGN=$(orch chat "Summarize the design we arrived at" --model gemini --session "$SESSION" --format json | jq -r '.content')

# Validate with consensus
orch consensus "Is this error handling design sound?

$DESIGN" flash claude deepseek --mode critique
```

## Output Format

Vote mode returns structured verdicts:
```
┌─────────────────────────────────────────────────────────────┐
│                      CONSENSUS: MIXED                        │
│                   SUPPORT: 2  OPPOSE: 1  NEUTRAL: 0          │
└─────────────────────────────────────────────────────────────┘

[flash] gemini-3-flash-preview - SUPPORT
Reasoning: ...

[gemini] gemini-3-pro-preview - SUPPORT
Reasoning: ...

[claude] claude-sonnet-4.5 - OPPOSE
Reasoning: ...
```

## Guidelines

1. **Use for genuine uncertainty** - Don't use orch for trivial decisions or to avoid thinking
2. **Provide context** - Better prompts get better consensus; use `--file` when relevant
3. **Choose models wisely** - flash/qwen-fast for quick checks, r1/opus for complex reasoning
4. **Consider stances** - Devil's advocate is powerful for stress-testing ideas
5. **Parse the reasoning** - The verdict matters less than understanding the reasoning
6. **Mind the cost** - opus and r1 require `--allow-expensive`; use cheaper models for iteration

## Requirements

- `orch` CLI installed (via home-manager or system packages)
- API keys configured: GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_KEY
