| name | multi-model-orchestration |
| description | Coordinate 2+ AI models (DeepSeek V4 Flash, Qwen 3.8 Max, GLM 5.2, GPT-5.5) for parallel review, cross-validation, or bulk work via Orca orchestration. Use when the coordinator says "обсудите этот вопрос с 2 моделями", "multi-model review", "cross-validate with N models", "parallel architecture specs", or any task requiring independent perspectives from different model families. ROUTER: новый проект → project-bootstrap · план спринта → wave-spec · 2+ модели → multi-model-orchestration. Do NOT use for single-model tasks, trivial edits, or when §1 decision tree says solo. |
Multi-Model Orchestration
Coordinator dispatches tasks to 2+ model workers via Orca, waits for results, synthesizes.
Coordinator dispatches, waits, synthesizes, gates. Writing code in a coordinator session requires an explicit owner-pin switch to writer role — coordinator does not combine orchestration with code writing in the same task.
Coordinator = any model with this skill loaded. This skill does not prescribe coordinator family.
TL;DR (minimum path)
multi-model-orchestration = dispatch/review движок для ≥2 моделей. Координатор маршрутизирует задачи воркерам (Orca), ждёт, синтезирует. Координатор не совмещает оркестрацию с написанием кода в одной задаче.
Когда: «обсудите с 2 моделями», cross-validate, parallel review, fidelity port, security/RLS (никогда одной моделью). Когда нет: §1 говорит solo, тривиал, одна модель.
Ядро: solo-vs-multi дерево (§1) → роутинг моделей (§2) → cross-family rule: writer.family ≠ reviewer.family → brief (§4) → dispatch через Orca (dispatch --inject, НЕ terminal send) → wait (check --wait) → синтез (§7, stricter wins). Worker contract: SUMMARY/EVIDENCE/CHANGES/RISKS/BLOCKERS + written≠persisted.
Роутер: новый проект → project-bootstrap · план спринта → wave-spec · 2+ модели → multi-model-orchestration. Lifecycle gates (Commit/PR/Merge/Deploy/On prod) — канон в wave-spec.
0. Preconditions
orca status --json
If Orca unavailable → manual fallback (§0b). Do not guess flags.
Skills required: orca-cli (terminal ops), orchestration (task/dispatch/wait).
0b. Manual Fallback (Orca unavailable)
If orca status fails or Orca is not installed:
- Coordinator opens N terminal tabs/windows manually (one per model).
- In each terminal: launch the model's CLI (
opencode, codex, etc.).
- Copy-paste the model-specific brief (from
references/routing.md) into each terminal.
- Collect outputs manually when workers finish.
- Synthesize per §7.
No worker_done lifecycle in manual mode — coordinator polls visually.
Skill still applies: routing (§2), brief structure (§4), synthesis (§7), write policy (§6).
1. Decision: Solo vs Multi
Task clear, 1 deliverable, linear, < 2-3h?
└─ YES → SOLO. Stop. Do not open multi.
2+ independent pieces needed IN PARALLEL?
└─ YES → multi ok.
Expensive error + need second family? (prod, security, big refactor)
└─ YES → multi: writer ≠ reviewer.
Bulk > 1 context window?
└─ YES → multi by layers.
Scope unclear?
└─ solo discovery first. Then re-evaluate.
Otherwise → solo.
Not multi: trivial fix, single short report, no patience for wait loops.
2. Routing — Which Model for What
| Work | Route to | Family | Why |
|---|
| Orchestration / dispatch / handoff | DeepSeek V4 Flash | DeepSeek | Role lock: не совмещает оркестрацию с написанием кода в одной задаче. Dispatch → wait → synthesize → gate. Full role |
| Implement (primary writer/coder) | DeepSeek V4 Flash (A/agent1st_v37.3-flash) | DeepSeek | Default writer — fast ($0.14/$0.28 per 1M), strong on 0731 benchmarks (SWE-bench 79.0 Flash-Max, LiveBench Coding 69.2). Single-file, bulk code, tests |
| Multi-file implement (3+ files) | GLM 5.2 (A/agent1st_glm) | Zhipu | 1M state continuity, long-horizon multi-file specialty (~15 min implement, ~10 min fix-round) |
| Review / architecture / business analysis (default reviewer) | Qwen 3.8 Max (A/agent1st_qwen-3.8) | Alibaba | 2.4T/95B active, native vision, CoT. Vendor benches 2026-08-03 (qwen.ai/blog): GPQA-D 92.6, Terminal-Bench 2.1 86.6 — indep verification pending. Owner empirical: level ~ Kimi K3, сильнее GLM 5.2 в architecture и depth. NE основной кодер (slow) |
| Complex analysis, multimodal, cross-examination | Qwen 3.8 Max | Alibaba | 2.4T/95B active, native vision, CoT |
| Security / RLS / auth / Storage review | gpt-5.6-luna (launch: codex --model gpt-5.6-luna -c model_reasoning_effort="max"; «Luna Max» — shorthand, НЕ имя модели) + DeepSeek V4 Flash (parallel) | OpenAI + DeepSeek | Gate + implementer; cross-family required (GPT-5.5 = optional opt-in strict gate для критичных) |
| Behavioral regression gate (optional) | GPT-5.5 (opt-in security gate; NOT default Strong pair) | OpenAI | Historical unique role — caught abort/cost MAJOR GLM missed. NOT "just another reviewer"; retained as opt-in for highly sensitive cases |
| Fidelity port (generator, vectorizer, reference→platform) | DeepSeek V4 Flash write (default) / GLM 5.2 (multi-file) · gpt-5.6-luna ∥ Qwen 3.8 Max review |
Cross-family rule: writer.family ≠ reviewer.family. Qwen Code (Alibaba) writer → reviewer must be DeepSeek/Zhipu/OpenAI, NOT OpenCode Qwen (also Alibaba). Full pairs: references/routing.md → Cross-Family Pairs.
Writer replaceable: owner phrase «сейчас writer=X» (Flash or GLM) pins writer instantly — no skill rewrite. Default writer: DeepSeek V4 Flash (fast, cheap). GLM = swap для multi-file. Qwen 3.8 Max = default reviewer/architect (NE writer — slow). See references/routing.md for the full routing table with evidence anchors.
Synthesis: MAJOR from any reviewer → fix before merge; prefer stricter severity on contradictions.
Full routing details + brief templates: references/routing.md.
2b. Deploy / smoke gate
Canonical definition: skills/wave-spec/SKILL.md §"Deploy Probe (Universal Pattern)".
Canonical examples: skills/wave-spec/SKILL.md §Deploy Probe — curl dual-pattern + skills-repo check.
SUMMARY: After merge/deploy (or skill install), prove the shipped surface exists before handoff. The probe checks existence, not correctness — correctness is verified at In Review. Adapt the probe to the target stack (web curl, CLI binary, package install, skill load path). Principle: one observable command that proves the artifact reached production. No probe = RESIDUAL-RISK-OWNER-SMOKE.
Evidence: production waves had untracked route files — if deployed without tracking, 404.
2c. Fidelity Port Rules
Canonical definition: skills/wave-spec/SKILL.md §"Fidelity Dual Review".
SUMMARY (5 rules):
- Dual review mandatory: static-parity reviewer ∥ behavioral-semantics reviewer as two complementary lenses from different model families. Single-reviewer fidelity ports are NOT accepted.
- Writer ≠ reviewer. Cross-family mandatory (writer.family ≠ reviewer.family).
- MAJOR from any reviewer → fix round before In Review. Stricter severity wins.
- No live smoke = RESIDUAL-RISK-OWNER-SMOKE in handoff. Document explicitly.
- Deploy gate: prove shipped surface before handoff (§2b).
Evidence (production waves): GLM-only would have missed abort MAJOR; Codex-only would have missed a numeric edge case + refine path.
For non-fidelity waves: dual review is recommended but not mandatory. At minimum, writer ≠ reviewer.
2d. Lifecycle Gates
Canonical definition: skills/wave-spec/SKILL.md §"Lifecycle Gates (lessons from production incidents)".
8 states, linear order, deploy probe, RESIDUAL-RISK-OWNER-SMOKE — полная таблица в каноне (дубль убран, один источник правды).
Cross-skill compatibility
multi-model-orchestration is a dispatch/review skill — it does NOT own the plan-gate pipeline. Lifecycle gates, fidelity dual review rules, and deploy probe are defined in wave-spec (§Lifecycle Gates, §Fidelity Dual Review, §Deploy Probe). This skill keeps inline SUMMARIES for standalone use.
Recommended ordering
- project-bootstrap — creates agent infrastructure (AGENTS.md, SESSION_HANDOFF.md, .agents/memory/)
- wave-spec — creates SPEC.xml + PLAN.xml with lifecycle gates, fidelity rules, deploy probe
- multi-model-orchestration (this skill) — executes dispatch/review via Orca
Canonical sources (wave-spec)
- Lifecycle: wave-spec §Lifecycle Gates — 8 states, linear ordering
- Fidelity Dual Review: wave-spec §Fidelity Dual Review — 5 rules, dual review mandatory
- Deploy Probe: wave-spec §Deploy Probe — existence check pattern
Standalone use
This skill can be used without wave-spec. Inline SUMMARIES in §2b/§2c/§2d cover base definitions. For full lifecycle contract, load wave-spec.
3. Coordinator Loop
1. CLASSIFY task → solo or multi (§1)
2. SELECT models (§2) — name them explicitly to human
3. CREATE terminals (one per worker, same worktree)
4. BUILD briefs (model-specific pattern — see references/routing.md)
5. PRE-DISPATCH GATE (mandatory before EVERY worker):
a. model-card.md checked → model available, pin current
b. --agent / --approval-mode yolo specified in command
c. dispatch --inject (NOT terminal send)
d. writer.family ≠ reviewer.family (cross-family)
e. Brief contains: ROLE/SCOPE/MODE/DONE + written≠persisted gate
If ANY item fails — DO NOT dispatch. Fix first.
6. DISPATCH: task-create → parse result.task.id → dispatch --inject
7. WAIT: check --wait --types worker_done,escalation,decision_gate
8. POST-WORKER_DONE SEQUENCE (do not skip):
a. git status --short → verify claimed files exist (written≠persisted)
b. Linear comment (project protocol, if applicable)
c. **Branch by `review_mode`** (set in the worker brief/packet — see §4; the reviewer does NOT compute mode post-factum). Canonical contract: `skills/wave-spec/SKILL.md` §Review modes.
- **Mechanical** → SKIP steps c–e entirely. Record skip evidence in the STATUS `## Review gate` block (`review_dispatches: 0`, `synthesis_path: n/a — Mechanical skip`) and in handoff `### Residual risk`. **Lifecycle gates still enforced** (approve / LAUNCH / checks / written≠persisted / secret-redaction / deploy / closeout). Mechanical is the only mode without a reviewer.
- **Simple** → dispatch exactly **1 cross-family reviewer** at launch default effort (variant НЕ переключается — host-side; see `references/routing.md` §Simple review). `writer.family ≠ reviewer.family` mandatory (the Simple-without-cross-family exception is cancelled).
- **Ordinary** → dispatch exactly **1 reviewer** — default **Qwen 3.8 Max**; swap to a different family if writer is Alibaba.
- **Strong** → **atomic compare-and-set on `strong_session_used` in STATUS `## Review gate` block BEFORE first dispatch** (double-Strong guard; orchestrator-owned). If `strong_session_used == false` → atomically set to `true`, then dispatch **2 complementary lines**: **gpt-5.6-luna** (behavioral / security / fidelity lens — mandatory for these categories) + **Qwen 3.8 Max** (static / architecture lens; swap to **GLM 5.2** when writer is Alibaba). Cross-family for **both** lines (each reviewer family ≠ writer family AND ≠ the other reviewer family). If `strong_session_used == true` → **BLOCK**: do NOT dispatch, record `blocked_by: strong_session_used` in the STATUS `## Review gate` block, surface owner/escalation outcome (not a silent skip, not a second Strong dispatch). Flag is not reset within the session. Transport/API failure on the first Strong dispatch = non-counting operational failure (no ledger increment, no automatic second Strong dispatch); retry of the same gate requires explicit owner decision (or a fix-round against existing findings, which does NOT consume the Strong flag). "No retries" = do not re-dispatch the reviewer within the same gate; fix-round (max 2, round 3 escalation) is unchanged.
d. Wait reviewer worker_done (skip for Mechanical)
e. Synthesis — `skills/wave-spec/assets/templates/review-synthesis.md.tmpl` (generic: 0 / 1 / 2 reviewer inputs; verdict enum `APPROVED | NEEDS_CHANGES | BLOCKED`; any material finding including LOW → NEEDS_CHANGES). Stricter wins on contradictions. Follow-up only by user request or unresolved BLOCKER/HIGH.
f. ONLY THEN: In Review / next step
9. GATE: read artifacts → synthesize → decide next
10. REPORT to human: consensus / contradictions / gaps
User message interrupt: if the user sends a message while coordinator is in a tool-calling loop — IMMEDIATELY stop the loop. Respond with text: current status + what's next. Do not continue tool calls without acknowledging the user.
Role Lock (coordinator session) — HARD GATE
ORCHESTRATOR: dispatch → wait → synthesize → gate.
If coordinator edits ANY worker file without an explicit owner-pin switch to writer role → STOP. Undo. Re-dispatch to worker.
Switching orchestrator → writer is an explicit owner-pin decision («сейчас writer=X» or «сейчас orchestrator=X»), not a same-task combination.
Review-only worker_done ≠ right to edit files. Implement = new task.
Heartbeat ≠ done. One timeout ≠ fail → liveness check → wait again.
Max 3 workers per wave. Do not "help" workers by editing in coord session.
3+ identical tool calls → circuit-break → text response to user.
4. Worker Brief Structure
Every brief MUST contain (adapt format to model — see references/routing.md):
ROLE: worker (not coordinator). Scope: <paths>.
MODE: review-only | implement.
REVIEW_MODE: Mechanical | Simple | Ordinary | Strong <!-- orchestrator-set; reviewer does NOT compute post-factum; carries gate context (effort, lens, dispatch count) -->
TASK: <what to do — 1-3 sentences>.
DONE: <acceptance criterion>.
OUTPUT: SUMMARY / EVIDENCE / CHANGES / RISKS / BLOCKERS.
review-only → findings only, NO file edits.
Blocked → ask/escalation, do not thrash.
After worker_done → idle (end turn).
- NEW worker_done rule: Brief ALWAYS contains explicit
--to <coordinator-handle> example. Without --to, orca returns msg ID but message goes to void route (production incident: message lost).
- NEW writer-swap rule self-protection for implement workers: Brief contains clause: "On API retry attempt #5+ → terminal read first → git diff --stat → if files modified match expected → idle and signal via heartbeat; if blocked → Ctrl-C and wait for coordinator swap. Do NOT continue retrying."
- NEW review_mode field: every brief carries
REVIEW_MODE set by the orchestrator from the precedence in skills/wave-spec/SKILL.md §Review modes. The reviewer uses it to know its lens context (Simple = 1 cross-family reviewer at launch default effort — variant НЕ переключается; Strong = which complementary lens — gpt-5.6-luna behavioral or Qwen 3.8 Max static). The reviewer does NOT re-classify the mode; mismatch with the orchestration packet → BLOCKER, not silent reclassification.
Model-specific wrapping:
- GLM 5.2: Goal → Context → Constraints → Done. No 【】. No "think step by step".
- DeepSeek V4 Flash: Задача → Где → Контекст → Не трогать + 【思维模式要求】 at end.
- Qwen 3.8 Max: Context → Objective → Steps → Examples → Response Format. CoT ok.
- GPT-5.5 (optional security gate): Goal → Success → Context → Constraints → Autonomy. Lean contracts, regression-gate focus.
- GPT-5.6 (gpt-5.6-luna / codex): Goal → Success → Context → Constraints → Autonomy → Output → Stop. Lean contracts: одна инструкция — один раз; НЕ использовать DeepSeek
【】-инъекцию и «think step by step» (не control surface для GPT-5.6); effort/verbosity — API-параметр (launch contract -c model_reasoning_effort=..., не текст); Success = acceptance + validation; Autonomy — компактная policy один раз (research→report; fix→local+tests; confirm external/destructive/scope). Плотность: простая = Goal + Where + Success; средняя = + Context + Constraints + Autonomy; сложная = все 7 блоков. Гайд: guides/kak-pisat-zaprosy-dlya-gpt-5.6.md.
5. Wait & Failure Handling
| Event | Action |
|---|
worker_done | Read artifacts → verify claimed files on disk if implement → gate/synthesize |
heartbeat | Worker alive, not done. Keep waiting. Do not restart; do not treat as completion |
escalation / decision_gate | Human or coordinator decision. Not blind re-dispatch |
| timeout / count:0 | Liveness check (terminal read). NOT restart. Wait again |
| 5 consecutive failures, same fingerprint AND same hypothesis | STOP. Worker returns package + ledger + evidence + hypothesis; orchestrator does material re-plan (hypothesis/scope/validation). No new plan → blocked → human. Model switch alone ≠ re-plan |
| Worker reports FAIL | Generic operational FAIL (non-counting operational path — see failure-handling.md closed list of 8) → coordinator re-dispatches, may switch model (NOT a 5th-fail-rule violation). Counted same-fingerprint series → attempts 1–4 same worker, no model switch; at count = 5 → STOP + material re-plan (row above) |
| NEW verify-arrival rule | After check --wait, verify delivery via GLOBAL inbox (orca orchestration inbox --limit 20 --json, filter by payload taskId), NOT handle-scoped check. check is handle-scoped → it misses worker_done on handle drift (stale recipient handle after terminal restart) or self-send (stored from==to); both give check=0 while inbox=N. If inbox has the worker_done but check --wait didn't return it → your handle changed (restart): re-resolve via terminal list / re-dispatch. If inbox lacks it → real routing miss, recover from terminal output (writer-swap rule) |
| NEW writer-swap rule | On API retry attempt #5+ in worker terminal: terminal read first → git diff --stat → if files modified match expected scope → dispatch verify+finalize brief to fresh writer terminal (NOT redo from scratch). If files not modified → re-dispatch from scratch or cross-family swap |
Details: references/failure-handling.md.
6. Write Policy
- Parallel workers: read-only OR disjoint paths only.
- Any implement/fix → one writer (serial task or separate worktree).
- Multiple writers on same worktree = merge conflict.
7. Synthesis & Report
After all workers complete:
- Read each worker's OUTPUT (SUMMARY/EVIDENCE/CHANGES/RISKS/BLOCKERS).
- Identify: consensus (all agree), contradictions (disagree + quotes), gaps (one covered, other missed).
- Present to human: decisions needed marked
⚠️ HUMAN DECISION REQUIRED.
- If implementation needed → new task to one writer (not coordinator).
8. Language Discipline
- Coordinator ↔ human: match human's language.
- Coordinator → workers: brief language = coordinator's working language (match human's language unless model guide requires otherwise).
- DeepSeek 【思维模式要求】 block: always in Chinese (model-specific, not human-language-dependent).
- Code, paths, identifiers, tool names: always English/original form.
9. Anti-Patterns
Hard Prohibitions (11 rules with alternatives): references/prohibitions.md — single source of truth.
Key gates (details in prohibitions.md):
- Coordinator writes code → HARD GATE: undo + re-dispatch (§3)
terminal send for task delivery → only dispatch --inject- Writer + reviewer same family → cross-family mandatory
- Tool-calling loop > 3 identical actions → STOP + text response to user
10. Orca Commands — Build From Guide, Not From Memory
Step 0 before any dispatch: run orca skills get orchestration and read the output. This is the authoritative source for dispatch/wait/worker_done commands. Do NOT copy-paste bash from this skill, from NEXT_SESSION files, or from memory.
Required sequence per worker
Build the exact commands from the orchestration guide. The sequence is:
- terminal create — worktree active, command = launch from model-card.md
- terminal wait --for tui-idle — timeout 60s (agent must be ready before dispatch)
- task-create — spec = brief content or brief file path
- dispatch --task --to --inject — injects lifecycle preamble
- check --wait --types worker_done,escalation,decision_gate — rolling wait
variant/effort НЕ задаётся из агента — модель работает на launch default (DeepSeek default, GLM max, Qwen high/max). Попытка /variants <X> из агента = сломанный шаг (host-side only). Полный рецепт: references/model-card.md §LAUNCH РЕЦЕПТ (SoT).
Verification gates
- After step 2: terminal is idle (ready for input). If not idle → wait more.
- After step 5: dispatch confirmed in output.
- After step 6: worker_done received. Timeout ≠ failure → terminal read → if working → repeat wait.
- If worker printed report as text but no worker_done → terminal send: "worker_done = orca orchestration send CLI command. Not text."
NEW operational rules (3 rules)
Canonical source: skills/project-bootstrap/references/operational-rules.md.
Rule 1 (worker_done rule): worker_done MANDATORY --to <coordinator-handle>. Without it → void route.
Rule 2 (verify-arrival rule): After check --wait → verify delivery via GLOBAL inbox filtered by taskId (inbox --limit 20 --json), NOT handle-scoped check. check misses worker_done on handle drift (stale recipient handle) or self-send (from==to): check=0 while inbox=N. Terminal "Sent msg_..." ≠ delivery proof.
Rule 3 (writer-swap rule): On API retry #5+ → terminal read → file inspect → verify+finalize brief (NOT redo).
Source: production incident — reviewer missed --to, message lost.
Shell timeout rule
When running check --wait from a shell subprocess, the shell timeout MUST be ≥ the Orca --timeout-ms. For 15-min Orca waits, either:
- Run check in background mode (
is_background: true) and poll later
- Or set shell timeout to 600000ms with Orca timeout ≤ 540000ms
Fallback when worker_done doesn't arrive
terminal read --terminal <worker_handle> — check if worker is still active- If active → repeat
check --wait (rolling window)
- If terminal gone → worker crashed, re-create + re-dispatch
- Check
/private/tmp/task_<id>* for report files (some models write there)
Liveness check (on timeout)
orca terminal read --terminal <handle> --json
For non-TUI fallback: opencode run --agent <agent> --model <model> --prompt "<brief>".
11. MCP Server Policy
Workers inherit MCP servers configured in their opencode instance (opencode.json or ~/.config/opencode/opencode.json).
- Coordinator does NOT assume specific MCP availability across workers.
- If a task requires specific MCP (e.g.,
excel, linear, meta-ads): state it in the brief under CONSTRAINTS.
- Workers report unavailable MCP in BLOCKERS field of output contract.
- Permission rules: each agent's frontmatter
permission: block governs tool access. Workers cannot exceed their agent's permissions.
12. Audit Log
After each multi-model wave, coordinator appends to the session handoff (or dedicated log file):
## Multi-Model Wave: <topic>
- Models: [list]
- Task: [1-line summary]
- Verdict: CONSENSUS | CONTRADICTIONS | PARTIAL
- Duration: [wall-clock]
- Key findings: [1-3 bullets]
- Decisions taken: [list or "none"]
- Artifacts: [paths to worker reports if saved]
Location: SESSION_HANDOFF.md (append) or research/session-logs/ for project-specific logs.
Purpose: post-mortem traceability. Not a journal — one block per wave, 5-8 lines max.
13. Cost Guidance
| Model | Relative cost | When justified |
|---|
| DeepSeek V4 Flash | Low | Orchestrator (default) + primary writer/coder — dispatch, routing, synthesis, bulk code, tests, single-file implement |
| GLM 5.2 | Medium | Multi-file implement, architecture, static parity review |
| Qwen 3.8 Max (OpenCode) | High | Reviewer / архитектор / бизнес-аналитик — architecture spec, cross-audit, business analysis, deep constraint analysis (NE основной кодер — slow) |
| GPT-5.5 (optional) | High | Security/RLS gate, regression-gate (historical unique role; opt-in) |
Budget rule: use cheapest model that can do the task. Escalate to expensive models only when:
- Cross-family review on expensive error (justifies 2-3x cost)
- Multimodal input requires native vision (Qwen 3.8 Max)
- Behavioral semantics gate (GPT-5.5)
Coordinator names models to human BEFORE dispatch — human can veto expensive choices.
References (load on-demand)
references/routing.md — full model routing table, brief templates per model, cross-family pairs, examplesreferences/worker-contract.md — output contract spec, inject preamble, worker_done format, Orca JSON parsing, worker_done delivery rulereferences/failure-handling.md — timeout policy, escalation, self-correction, circuit-breakerreferences/model-card.md — model roles + family field + «не путать с» + evidence 1-liners + owner pin + launch pins + Qwen Codereferences/prohibitions.md — 11 hard prohibitions with correct alternativesorca-cli skill — terminal ops, worktree management, handoffs. Load via orca skills get orca-cliorchestration skill — task/dispatch/wait, worker_done authority, coordinator loops. Load via orca skills get orchestration
