OpenCode Orchestrator Kit

A cost-aware, multi-agent workflow for OpenCode: one router agent that never writes code, and specialists that each run on the cheapest model able to do the job.

The problem

Most "AI does everything" setups burn tokens: one powerful model handles research, planning, coding and review inside a single long-lived context. Quality drifts as the context grows, and every step is billed at the most expensive rate.

The approach

The kit splits the work into a routing layer and a roster of specialists:

• The orchestrator only routes. It classifies the request, delegates and checkpoints. It cannot edit application code or run tests. For small one-delegation tasks the opt-in orchestrator-quick (reach it with /quick) applies the same discipline without the plan board and the session memory.
• Models are matched to tasks. Cheap or local models explore and bootstrap; stronger models are reserved for design, implementation and review.
• Context stays small. Session memory is bullet-only and auto-archived past ~3k tokens, and multi-phase plans advance one phase at a time with fresh context.
• Exploration starts from a repo map. The profiler generates a compact .context/repo-map.md (hard 300-line budget) that the explorer reads before broad searches, reducing whole-file reads and token waste.
• It adapts to any repository. On first run the profiler agent detects the stack (or interviews you for an empty repo) and scaffolds .context/ (memory) and plan/ (kanban).

On OpenCode 2 the kit is the opencode-orchestrator-kit plugin, published on npm: agents, commands and skills are registered at runtime — nothing is written into your project's .opencode/ directory. Add "package": "opencode-orchestrator-kit" to the plugins array (below). A local plugin/ directory and a git install remain available as alternatives. The native copy-based installer still works and remains supported, but it is deprecated in favor of the plugin on OpenCode 2 (the default profile it ships references provider IDs that are not yours — see the Choose your model profile step). Optional notes for OpenCode Studio users are in docs/SETUP-OPENCODE-STUDIO.md.

How a request flows

"Add refresh-token rotation to the auth service."

Every delegation uses a 9-section task spec (Goal, Success Criteria, Scope, Safety, Inputs, Outputs, Test Plan, Verification, Edge Cases), never a free-form prompt. The orchestrator itself never edits auth.ts.

Design decisions

• Routing is separated from execution. agents/orchestrator.md is the default mode: primary agent and can only classify and delegate, so orchestration mistakes cannot silently change the codebase. agents/orchestrator-quick.md is the opt-in alternate for small tasks, with the same write surface and a shorter cycle.
• Logical model tiers instead of hardcoded IDs. Agents reference {{TIER_ROUTER}}, {{TIER_REASONING}}, {{TIER_CODE}}, {{TIER_FAST}} and {{TIER_REVIEW}}. Switching provider means editing one config file, and a validator runs before install.
• Plans are files, not chat history. The kanban in plan/ is the source of truth, so work is resumable and reviewable in Git.
• Technical review is separate from human comprehension. code-reviewer and security verify the code; comprehension-coach checks that the developer understood it.

Agent roster

Who does what

Full contracts, permissions and model fallbacks are in each agents/*.md file (the pc-doctor and writer specialists live in extras/*.md) and are summarized in AGENTS.md.

Tiers and installation

Install on OpenCode 2 (plugin — recommended)

With the plugin, tier resolution happens at runtime from plugin/src/tiers.ts presets — there is no {{TIER_*}} substitution at install time.

opencode-orchestrator-kit is published on npm (1.1.1, tag v1.1.1; later releases follow .github/workflows/release.yml and the steps in CONTRIBUTING.md). OpenCode 2 loads plugins from the plugins array in opencode.json or opencode.jsonc (Plugins). A string entry is a package name or a local directory. Pass options with the object form { "package", "options" }. Local paths must be directories (a path to a single file is skipped). Relative paths resolve from the config file that contains the entry.

Primary install, the npm package:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    {
      "package": "opencode-orchestrator-kit",
      "options": { "preset": "generic", "withExtras": false },
    },
  ],
}

A local checkout of this repository uses the same object form with an absolute directory ("package": "/absolute/path/to/opencode-orchestrator-kit/plugin"). The OpenCode 2 docs also accept a git package spec on opencode plugin add, including a subdirectory selector, because this plugin lives in plugin/ and not at the repository root:

opencode plugin add 'github:NicoGenti/opencode-orchestrator-kit#main::path:plugin'

That command writes a package entry. Set preset and withExtras with the object form ab