---
name: ai-workflow-routing
description: "Multi-agent AI coding workflow with model routing — planning via ChatGPT, coding via OpenCode Go, cheap loops via DeepSeek, deep review via local Qwen Coder."
version: 1.3.0
author: Hermes Agent
---

# AI Workflow & Model Routing

A structured approach to using multiple AI models/agents efficiently based on task complexity and cost.

## Stack

| Tool | Role | Invocation |
|---|---|---|
| **ChatGPT Plus** | Planning, research, architecture decisions, final review | Browser/manual |
| **OpenCode Go** | Main coding-agent for repo edits, code review, refactoring, UI work | `opencode run '...'` or interactive TUI |
| **Cursor Agent CLI** | Temporary helper for feature work while subscription active | `agent --print --trust --model <model> "..."` |
| **DeepSeek API** | Cheap repeated loops, summaries, simple edits, low-risk review | Via OpenRouter or `opencode run --model openrouter/deepseek/deepseek-chat` |
| **Local Qwen3-Coder-30B (Q4_K_M)** | Slow background deep code review | `opencode run --model local-llamaswap/qwen3-coder-30b` |

See `references/provider-model-reference.md` for exact model IDs, context limits, and auth setup for each provider.
See `references/multi-model-audit.md` for the full parallel local-model audit pattern — prompt templates, parallel launch, and cross-referencing methodology.
See `references/opencode-configuration.md` for OpenCode server setup, credential management, model config, and the Desktop-vs-Server config split.

## Model Routing Rules

- Use **cheap models** (DeepSeek) for scanning, summaries, simple fixes, repeated loops
- Use **OpenCode Go** for hands-on coding and file edits
- Use **local Qwen Coder** for slow deep review passes
- Use **ChatGPT Plus** for planning, research, architecture judgment, final validation
- Do not use expensive/strong models for simple tasks
- Do not run multiple strong agents unless the task truly needs it
- **The current active agent is the primary orchestrator and default builder** — do NOT auto-route every task through OpenCode Go or subagents
- **Escalate only when complexity justifies it** — explain WHY escalation is needed before delegating
- Keep normal implementation work on the current agent whenever practical

## Multi-Model Audit Pattern

When the user asks for a deep audit, review, or "second opinion" across the codebase:

**Do NOT run models sequentially** — the user will ask "do this again with a different model" and you'll waste time discovering they wanted parallel coverage. When the request is about thoroughness or cross-referencing, **launch ALL available capable local models in parallel from the start** via their llama-swap API endpoints.

### When to use

- User asks for "deep review", "audit all phases", "extensive audit", "full review"
- User asks for "second opinion" or "cross-reference" — this means they want multiple perspectives
- User mentions "the top N models" — launch N in parallel, don't pick one at a time
- Any request where thoroughness over speed is the goal

### How to execute

1. **Build a project digest** — read the key architecture files (interfaces, use cases, providers, routers, main.py) and compile them into a structured prompt. Include file:line references. Include any plan docs or session handoffs.

2. **Gather web research context** — use the browser tool (not web_search — that tool may not be available) to research external APIs, competitor architecture, and best practices. Compile findings into a `web_research.md` reference file the models can read from disk.

3. **Add the web context to each model's prompt** — each local model gets the same comprehensive prompt including the web research so they all have the full picture. Inject it as: `f"## WEB RESEARCH CONTEXT\\n{web_context}"`

4. **Launch all models in parallel** — use `terminal(background=true, notify_on_complete=true)` for each model via a Python script that calls the llama-swap API:
   ```bash
   curl -s -X POST http://localhost:9292/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{"model":"<model-name>","messages":[...],"temperature":0.2,"max_tokens":16384}'
   ```

5. **Save each result to a separate file** — `/tmp/audit_<model_name>.md` for later cross-referencing.

6. **Cross-reference findings** after all complete — identify common consensus, unique insights, factual errors, and prioritize the action list.

### Model selection for parallel audits

From this user's llama-swap fleet, the best models for audit (highest reasoning + code understanding):

| Priority | Model | Why |
|----------|-------|-----|
| 1 | `qwen3.6-35b` | Newest, largest, best general reasoning |
| 2 | `qwen3-coder-30b` | Best at code-specific analysis |
| 3 | `gemma-4-26b` | Different architecture (Gemma) — catches what Qwen models miss |
| 4 | `qwen3.5-opus14` | Opus-tuned for reasoning quality |
| 5 | `qwen3.6-mtp` | MTP variant — may have different attention patterns |

### Pitfalls

- ❌ Don't run one model, then wait for user to ask for another — launch all at once
- ❌ Don't forget web research context — local models don't have live internet access
- ❌ Don't make the prompt too generic — include specific file:line references and ask models to read files from disk
- ❌ Don't cache stream results across users in audit findings (debrid availability is account-specific — note this when the audit covers the streaming module)
- ❌ Model output may include hallucinated file references — verify claims against actual source before acting on them
- ✓ Each model writes to its own output file so you can cross-reference later
- ✓ Set temperature to 0.2 or lower for audit tasks (consistency over creativity)

## Agent Pass Workflow

### 1. Read-only pass
- Inspect files
- Map structure
- Do not edit

### 2. Issue-finding pass
- Find bugs, missing logic, bad patterns, duplicated code, weak structure

### 3. Planning pass
- Prioritize issues
- Decide what should be fixed first
- Separate must-fix from nice-to-have

### 4. Implementation pass
- Make small safe edits
- Avoid huge rewrites
- Preserve existing behavior unless a bug is confirmed

### 5. Review pass
- Check the changes
- Look for regressions, broken imports, bad assumptions, messy code

### 6. Final summary pass
- Explain what changed
- List remaining risks
- Give the next recommended task

## Agent Roles

| Agent | Role |
|---|---|
| **Scout Agent** | Scans and maps files |
| **Fixer Agent** | Makes safe code changes |
| **Reviewer Agent** | Checks work from other agents |
| **Architect Agent** | Reviews structure and long-term design |
| **Security Agent** | Checks defensive security, secrets, auth, permissions, unsafe patterns |
| **UI Agent** | Handles layout, frontend polish, user flow |
| **SQL/Data Agent** | Checks queries, schema, data flow, performance |

## Output Rules

- Be direct and actionable
- Always include file paths when possible
- Use severity levels: Critical, High, Medium, Low
- Explain why something matters
- Give the exact next step
- Ask before destructive changes
- Prefer small verified changes over large rewrites

## Default Behavior

Start with a read-only pass, then recommend which agent/model should handle each next pass.

## OpenCode Configuration Notes

See `references/opencode-configuration.md` for full details on OpenCode CLI (the `opencode` npm package). Key points:

- **Credentials live in `~/.local/share/opencode/auth.json`**, not in `opencode.json`. The config file gets sanitized on restart.
- The Desktop app on CachyOS has its OWN config separate from the Debian server. Fixing the server doesn't fix the Desktop model picker — update both.
- The OpenCode web UI (`opencode serve`) has a React context crash in v1.17.x — it's a known bug, not misconfiguration. Use the Desktop client instead.
- All 23 OpenRouter free models are configured, including NEX N2 Pro, all Nemotron variants, and free Gemma 4 models.

### Hermes Provider Setup (opencode-go / opencode-zen)

Both OpenCode Go and OpenCode Zen are **first-class Hermes providers** registered by the `opencode-zen` plugin (`plugins/model-providers/opencode-zen/`).

| Provider | Tier | Endpoint | Live Models |
|----------|------|----------|-------------|
| `opencode-go` | $10/mo sub | `https://opencode.ai/zen/go/v1` | 19 (kimi, glm, qwen, deepseek, minimax, mimo, hy3) |
| `opencode-zen` | Pay-as-you-go + free | `https://opencode.ai/zen/v1` | 48 (Claude 4.x, GPT-5.x, Gemini 3.x, + free-tier `*-free`) |

**Key setup requirement:** The `OPENCODE_GO_API_KEY` / `OPENCODE_ZEN_API_KEY` env vars MUST be set in `~/.hermes/.env` for the provider to appear in the `/model` picker. Without the key:

1. `get_api_key_provider_status(provider_id)` → `{"configured": False}`
2. `list_authenticated_providers()` filters it out entirely
3. Provider is invisible in the interactive /model picker

This gate applies to ALL API-key providers (deepseek, openrouter, etc.).

**How to verify:**
```bash
grep OPENCODE_GO_API_KEY ~/.hermes/.env          # Check key presence
grep OPENCODE_ZEN_API_KEY ~/.hermes/.env         # Check Zen key
```

**Live model list (doesn't require auth):**
```bash
curl -s https://opencode.ai/zen/go/v1/models | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin)['data']]"
curl -s https://opencode.ai/zen/v1/models | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin)['data']]"
```

**Config.yaml model definitions matter.** The `providers:` block should include a `models:` section with per-model token limits. Without it, the in-repo curated list is used as fallback — but the config block is what Hermes reads at startup for the definitive catalog. For the full 19-model Go and 48-model Zen catalogs with context limits, see `references/hermes-opencode-go-provider.md`.

See `references/hermes-opencode-go-provider.md` for the full diagnostic trace and code paths.