opencode-resolve 0.1.3 → 0.1.5

package/README.md

@@ -1,17 +1,44 @@
-# opencode-resolve
+# opencode-resolve — Lightweight Resolver Plugin for OpenCode
+
+**[English](./README.md) | [한국어](./README.ko.md)**
 
 [![npm version](https://img.shields.io/npm/v/opencode-resolve.svg)](https://www.npmjs.com/package/opencode-resolve)
+[![CI](https://github.com/jshsakura/opencode-resolve/actions/workflows/publish.yml/badge.svg)](https://github.com/jshsakura/opencode-resolve/actions/workflows/publish.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-Small OpenCode plugin that turns a single instruction into a finished, verified change.
+> **opencode-resolve** is a **lightweight resolver plugin for [OpenCode](https://opencode.ai)**. It lives _inside_ your OpenCode session and turns a single instruction into a finished, verified change — that is what _resolving_ means here.
+>
+> It is **not** a standalone application, not a model provider, not a separate CLI you run daily, and not a replacement for your `opencode.json` configuration. It is an OpenCode plugin and nothing more.
+
+It exposes a **fixed-role verified resolve loop** — **resolver** (context-efficient planner/judge) and **coder** (focused implementer) — running with auto-approved permissions so a task drives to completion without prompting at every step. The resolver inspects only relevant files, plans the smallest patch, dispatches coder with exact instructions, verifies, and iterates through verified checkpoints. Each checkpoint is retried up to 3 times on failure, then the resolver moves forward. Internal specialist subagents (**explorer**, **reviewer**, **deep-reviewer**) are injected by default as OpenCode-native subagents — available when the resolver judges them justified — but they are not part of the core path and are never user-facing primary roles. It defines roles, not model providers: agents inherit your OpenCode default model unless you pin them.
+
+```
+# Paste this into any AI coding assistant for fully guided setup
+Install and configure opencode-resolve by following the instructions here:
+https://github.com/jshsakura/opencode-resolve#drop-in-setup-give-to-an-llm
+```
+
+---
+
+## What this is — and isn't
+
+| ✅ What it is | ❌ What it isn't |
+|---|---|
+| A **lightweight resolver plugin for OpenCode** installed via `opencode plugin opencode-resolve` | A standalone app or separate CLI |
+| A fixed-role verified loop (resolver + coder) injected into OpenCode | A model provider or API key manager |
+| A Context7 MCP auto-registration hook | A replacement for your `opencode.json` config |
+| A config file (`resolve.json`) that lives alongside OpenCode config | Something you invoke manually every time you code |
+| Installed once, then runs automatically inside OpenCode | An alternative to OpenCode itself |
 
-`opencode-resolve` ships three roles by default — **resolver** (orchestrator), **coder** (implementer), and **reviewer** (read-only auditor) — and runs them with auto-approved permissions so a task drives to completion without prompting at every step. It defines roles, not model providers: agents inherit your OpenCode default model unless you pin them.
+If OpenCode is not installed or not running, opencode-resolve does nothing.
 
 ---
 
 ## Table of Contents
 
-- [Roles at a glance](#roles-at-a-glance)
+- [Features](#features)
+- [AI-Powered Setup](#ai-powered-setup)
+- [Prerequisites](#prerequisites)
 - [Quick Start](#quick-start)
 - [Drop-in setup (give to an LLM)](#drop-in-setup-give-to-an-llm)
 - [Default Behavior](#default-behavior)
@@ -23,39 +50,115 @@ Small OpenCode plugin that turns a single instruction into a finished, verified
 - [Model Setup](#model-setup)
 - [Agent Reference](#agent-reference)
 - [Optional Commands](#optional-commands)
+- [Context7 Integration](#context7-integration)
+- [Keeping Up to Date](#keeping-up-to-date)
 - [Local Development](#local-development)
 - [Verification](#verification)
 - [Release](#release)
 - [Design Rules](#design-rules)
+- [License](#license)
 
 ---
 
-## Roles at a glance
+## Features
+
+- **Fixed-role verified resolve loop** — `resolver` (context-efficient planner/judge) + `coder` (focused implementer)
+- **Context-efficient by default** — minimal file reads, smallest patch, targeted verification, checkpointed execution with max 3 retries per failing checkpoint
+- **OpenCode-native internal specialist subagents** — `reviewer` (verification-gap audit), `explorer` (codebase scout), `deep-reviewer` (risky/security review) — injected as subagents by default but not part of the core path; resolver dispatches them only when justified
+- **Auto-approved permissions** — coder and resolver work without per-action prompts
+- **Context7 MCP** — auto-registers [Context7](https://context7.com) documentation lookup when `context7: true`
+- **Model pinning** — pin different models per role when you have measured a benefit; by default all roles inherit your OpenCode default model
+- **Soft parallel cap** — `maxParallelSubagents` controls how many coders the resolver fans out
+- **Strict validation** — unknown keys, typos, invalid modes, and wrong types all fail fast at load time
+- **Additive migration** — upgrades never overwrite your existing config
+- **Zero dependencies beyond `@opencode-ai/plugin`** — nothing extra to install
+
+---
+
+## AI-Powered Setup
+
+> **One line. Any AI coding assistant. Everything configured automatically.**
+
+Paste this into Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code Copilot, or Gemini CLI:
+
+```
+Install and configure opencode-resolve by following the instructions here:
+https://github.com/jshsakura/opencode-resolve#drop-in-setup-give-to-an-llm
+```
+
+Your AI will:
+
+1. Install the plugin via `opencode plugin opencode-resolve --global --force`
+2. Merge `opencode-resolve` into your `opencode.json` plugin array
+3. Create `resolve.json` with a working configuration
+4. Tell you to restart OpenCode
+
+No manual config editing required. Works on macOS, Linux, and Windows.
+
+> For manual setup, see [Prerequisites](#prerequisites) and [Quick Start](#quick-start) below.
 
-| Role | Default | Can edit? | Can run shell? | Purpose |
-|---|:---:|:---:|:---:|---|
-| `resolver` | Yes | Yes (auto) | Yes (auto) | Primary orchestrator. Plans, dispatches `coder` (one at a time), verifies, iterates. |
-| `coder` | Yes | Yes (auto) | Yes (auto) | Focused implementer. Makes the smallest correct change and verifies. |
-| `reviewer` | Yes | **Never** | **Never** | Read-only auditor. Inspects only — recommends fixes for `coder` or `resolver` to apply. |
+---
+
+## Prerequisites
+
+### 1. OpenCode
+
+opencode-resolve is an OpenCode plugin. You need [OpenCode](https://opencode.ai) installed and running.
+
+Verify:
+
+```sh
+opencode --version
+```
+
+### 2. Node.js ≥ 20
+
+The plugin and OpenCode itself require Node.js 20 or later.
+
+Verify:
+
+```sh
+node --version   # should be v20.x or later
+```
+
+### 3. A configured model provider
+
+OpenCode needs at least one model provider configured in `~/.config/opencode/opencode.json` with a valid API key. opencode-resolve agents inherit your default model unless you pin them.
+
+Example minimal provider setup:
+
+```json
+{
+  "model": "openai/gpt-4o",
+  "provider": {
+    "openai": {
+      "name": "OpenAI"
+    }
+  }
+}
+```
 
-Hard rule: **the reviewer cannot modify the project by any means.** Both `edit` and `bash` are denied for the reviewer regardless of `autoApprove`. Any required fix is routed back through `coder` or `resolver`.
+> No additional API keys or MCP servers are required. Context7 is auto-registered by the plugin.
 
 ---
 
 ## Quick Start
 
-Install from npm:
+### Install from npm
 
 ```sh
 npm install -g opencode-resolve
 ```
 
-The package `postinstall` step:
+The `postinstall` script automatically:
 
-1. Adds `opencode-resolve` to `~/.config/opencode/opencode.json` `plugin` array.
-2. Creates `~/.config/opencode/resolve.json` from [`opencode-resolve.example.json`](./opencode-resolve.example.json) when missing.
+1. Adds `opencode-resolve` to `~/.config/opencode/opencode.json` `plugin` array (if not already present).
+2. Creates `~/.config/opencode/resolve.json` adapted to your current model provider when the file does not exist:
+   - **GLM/ZAI model detected** → mixed GLM + GPT alias preset (`coder` → GLM, `resolver` → GPT).
+   - **OpenAI/GPT model detected** → single-provider GPT preset using your current model for all roles.
+   - **Other or no model** → model-neutral `models: {}` (all roles inherit OpenCode default).
 
-Restart OpenCode after installation.
+   Existing `resolve.json` files are **never overwritten** — the adaptive preset only applies to first-time creation. To regenerate, delete `resolve.json` and reinstall.
 
 To skip automatic registration:
 
@@ -63,7 +166,17 @@ To skip automatic registration:
 OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
 ```
 
-Manual fallback: add the plugin to `~/.config/opencode/opencode.json` yourself:
+### Refresh the plugin cache
+
+> **Important — OpenCode caches plugins itself.** OpenCode does NOT use globally-installed npm packages directly. It maintains its own cache at `~/.cache/opencode/packages/`. After the very first install (or any future upgrade), refresh the cache:
+
+```sh
+opencode plugin opencode-resolve --global --force
+```
+
+### Manual fallback
+
+If `postinstall` didn't register the plugin, add it to `~/.config/opencode/opencode.json` yourself:
 
 ```json
 {
@@ -71,81 +184,253 @@ Manual fallback: add the plugin to `~/.config/opencode/opencode.json` yourself:
 }
 ```
 
+### Restart OpenCode
+
+```sh
+opencode
+```
+
+You should now see `resolver` and `coder` agents available.
+
 ---
 
 ## Drop-in setup (give to an LLM)
 
-Hand the block below to any reasonably capable LLM along with the instruction _"set up opencode-resolve on this machine"_ and it can finish the install end-to-end. Everything below is the entire required configuration — no other MCP servers, environment variables, or files are needed.
+Hand the block below to any reasonably capable LLM along with the instruction _"set up opencode-resolve on this machine"_ and it will finish the install end-to-end. The LLM **must run this interactively** — it discovers what providers and models are already configured, then asks the user which to pin per role. No guessing, no invented model IDs.
 
-> **Important — OpenCode caches plugins itself.** OpenCode does NOT use globally-installed npm packages. It maintains its own cache at `~/.cache/opencode/packages/`. After the very first install (or any future upgrade), refresh the cache with `opencode plugin opencode-resolve --global --force` and restart OpenCode. `npm install -g` alone is not enough.
+> **For LLMs reading this:** treat every "Ask the user" prompt below as a real question — wait for the user's answer before continuing. Never proceed with a default if the user hasn't responded. Never invent model IDs that aren't in the user's `opencode.json` (or in their declared `provider.*` registry).
 
-**Step 1 — install via OpenCode (also primes the cache):**
+### Step 1 — Install and prime the cache
 
 ```sh
 opencode plugin opencode-resolve --global --force
 ```
 
-**Step 2 — `~/.config/opencode/opencode.json`** (merge into the existing file; do not replace it):
+This downloads the plugin, installs it into OpenCode's package cache (`~/.cache/opencode/packages/`), and makes it available.
+
+### Step 2 — Register the plugin in `~/.config/opencode/opencode.json`
+
+Add the string `"opencode-resolve"` to the `plugin` array. **Do not use the inline tuple form here** — keep the entry as a bare string so all role/model config lives in `resolve.json` (Step 3). This avoids split-brain configuration.
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "model": "<your-default-model-id>",
+  "model": "<user-default-model-id>",
   "plugin": ["opencode-resolve"]
 }
 ```
 
-**Step 3 — `~/.config/opencode/resolve.json`** (auto-created by `postinstall`; the block below is the recommended canonical setup — copy it verbatim then edit `models` to match your provider):
+> If the user already has other plugins, append `"opencode-resolve"` to the existing array. **Never overwrite** their existing config.
+
+#### 2b. Offer the recommended companion plugins
+
+Before moving to model selection, ask the user about two **independent** companion plugins — one question each, recommended-by-default. Both are separate OpenCode plugins; opencode-resolve does not require them but pairs well with both.
+
+**Companion 1 — `@tarquinen/opencode-dcp` (Dynamic Context Pruning)**
+
+> _opencode-resolve pairs well with **`@tarquinen/opencode-dcp`** — it prunes obsolete tool outputs so long resolver loops cost fewer tokens. Want to install it? (recommended)_
+
+**Companion 2 — `@slkiser/opencode-quota` (quota & usage tracking)**
+
+> _And **`@slkiser/opencode-quota`** — shows your live token/quota usage without polluting the context window. Supports GLM coding-plan, OpenAI Plus/Pro, Qwen, and more. Useful for actually seeing the token savings opencode-resolve gives you. Install it? (recommended)_
+
+For each **yes** answer:
+
+1. Run `opencode plugin <package>@latest --global --force` (primes the cache).
+2. Append `"<package>@latest"` to the `plugin` array in `~/.config/opencode/opencode.json`, only if it is not already present.
+
+Where `<package>` is `@tarquinen/opencode-dcp` or `@slkiser/opencode-quota`.
+
+For each **no**, skip — do not modify `opencode.json` for that entry. Proceed to Step 3 either way.
+
+> `context7` MCP is registered automatically by opencode-resolve at runtime when `context7: true` (the default in `resolve.json`). No separate question is needed for that.
+
+### Step 3 — Pick models interactively, then write `~/.config/opencode/resolve.json`
+
+The LLM **drives a short Q&A** here. Goal: end with `resolve.json` containing model IDs the user explicitly chose from their own configuration.
+
+#### 3a. Discover the user's installed providers and models
+
+Read `~/.config/opencode/opencode.json` and build a candidate map:
+
+| Source | What to collect |
+|---|---|
+| `provider.*` keys | Each configured provider (e.g. `zai`, `openai`, `anthropic`). |
+| `provider.<key>.models.*` keys | The model keys the user has declared under that provider. |
+| Top-level `model` | If the prefix before `/` is not already in `provider.*`, add it as an implicit candidate (e.g. `zai-coding-plan` from `zai-coding-plan/glm-5.1`). |
+| `agent.*.model` | Any per-agent overrides — add their provider/model pairs as candidates. |
+
+If the user has **no providers configured at all**, stop and tell them to add at least one provider with a valid API key to `opencode.json` first — opencode-resolve cannot pick a model that does not exist.
+
+#### 3b. Ask the user: which provider?
+
+Print the candidate list and ask. Example wording the LLM should use:
+
+> _I found these providers in your OpenCode config. Which one should opencode-resolve roles use?_
+>
+> 1. `zai-coding-plan` — models: `glm-5.1`, `glm-4.7-flash`
+> 2. `openai` — models: `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`, `o3-mini`, `gpt-5.5`
+> 3. _Other (provide an explicit `provider/model` ID)_
+
+If exactly one provider candidate exists, skip the question and use it.
+
+#### 3c. Ask the user: single, two-tier, or three-tier split?
+
+The default recommendation is **C (three-tier bronze/silver/gold)** — opencode-resolve has three qualitatively distinct workloads (read-only scout → write/patch → reason/judge) and three matching tiers cost about the same as two-tier but read role costs more accurately. Fall back to B if the user only has two models, A only when they have one.
+
+> _Recommended: **three-tier** — a cheap scout model for `explorer`, a mid coder for `coder`, and a strong reasoner for `resolver`/`reviewer`/`deep-reviewer`/`planner`. Choose:_
+>
+> **C. Three-tier — bronze (scout) + silver (coder) + gold (reasoner) — recommended**
+> B. Two-tier — fast + strong (when you only have two models)
+> A. Single model for all roles (only if you have one model or want maximum simplicity)
+
+Default to C if the user just hits enter or says "recommended". Only fall back if they don't have enough distinct models. Same-provider split is fully valid (e.g. `openai/gpt-4o-mini` / `openai/gpt-5.3-codex` / `openai/o4-mini`, or `zai/glm-4.7-flash` / `zai-coding-plan/glm-5.1` / `zai/glm-5`).
+
+#### 3d. Ask the user: which model(s)?
+
+Show only the models under the provider picked in 3b.
+
+- For **single-tier (A)** — ask one question:
+  > _Which model should every role use?_ → list models from the chosen provider.
+- For **split (B)** — ask two questions, in order:
+  > _Pick the **fast** model for `coder` and `explorer`:_ → list models.
+  >
+  > _Pick the **strong** model for `resolver`, `reviewer`, `deep-reviewer`:_ → list models.
+
+Confirm each pick back to the user before writing the file. Example:
+
+> _I'll pin `coder` and `explorer` to `zai-coding-plan/glm-5.1`, and `resolver`/`reviewer`/`deep-reviewer` to `openai/gpt-5.5`. Proceed?_
+
+#### 3d-bis. Pick `maxParallelSubagents` from the `coder` model
+
+opencode-resolve's identity is **token efficiency** — the resolver plans fast and dispatches subagents by type, and the parallel cap is per-role. The cap is determined by the `coder` model only — coder is the fan-out subject, so its rate budget is what matters:
+
+| `coder` model ID contains | `maxParallelSubagents` |
+|---|---|
+| `glm` (any GLM model — most often the GLM coding-plan) | **2** |
+| anything else (GPT, Claude, Gemini, local, …) | **4** |
+
+The GLM constraint comes from the GLM coding-plan's per-account rate limits — even a powerful GLM gets throttled under burst dispatch. Every other family tested tolerates 4 well and the resolver gets meaningful speedup. Don't look at the strong/reasoner model — the cap follows the doer, not the judge.
+
+For single-tier (A) and two-tier (B), apply the same rule to whichever model the `coder` agent ends up using.
+
+#### 3e. Write `~/.config/opencode/resolve.json`
+
+**Three-tier (C, recommended)** — use the `bronze`/`silver`/`gold` aliases:
 
 ```json
 {
-  "enabled": ["coder", "reviewer", "resolver"],
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer", "planner"],
   "preserveNative": true,
   "context7": true,
   "commands": false,
-  "autoApprove": true,
-  "maxParallelSubagents": 2,
   "models": {
-    "glm": "zai-coding-plan/glm-5",
-    "gpt": "openai/gpt-5.5",
-    "coder": "glm",
-    "reviewer": "openai/gpt-4o-mini",
-    "resolver": "gpt"
+    "bronze":        "<provider>/<scout-model>",
+    "silver":        "<provider>/<coder-model>",
+    "gold":          "<provider>/<reasoner-model>",
+    "explorer":      "bronze",
+    "coder":         "silver",
+    "resolver":      "gold",
+    "reviewer":      "gold",
+    "deep-reviewer": "gold",
+    "planner":       "gold"
   },
   "agents": {
-    "coder":    { "mode": "all" },
-    "reviewer": { "mode": "all" },
-    "resolver": { "enabled": true },
-    "architect":  { "enabled": false },
-    "gpt-coder":  { "enabled": false },
-    "debugger":   { "enabled": false },
-    "researcher": { "enabled": false }
-  }
+    "coder":         { "enabled": true,  "mode": "all" },
+    "resolver":      { "enabled": true },
+    "explorer":      { "enabled": true,  "mode": "subagent" },
+    "reviewer":      { "enabled": true,  "mode": "subagent" },
+    "deep-reviewer": { "enabled": true,  "mode": "subagent" },
+    "planner":       { "enabled": true,  "mode": "subagent" },
+    "architect":     { "enabled": false },
+    "gpt-coder":     { "enabled": false },
+    "debugger":      { "enabled": false },
+    "researcher":    { "enabled": false }
+  },
+  "autoApprove": true,
+  "autoUpdate": true,
+  "maxParallelSubagents": 2
 }
 ```
 
-**Step 4 — restart OpenCode.**
+**Two-tier (B)** — collapse bronze and silver if the user has only two models:
+
+```json
+"models": {
+  "silver":        "<provider>/<coder-model>",
+  "gold":          "<provider>/<reasoner-model>",
+  "explorer":      "silver",
+  "coder":         "silver",
+  "resolver":      "gold",
+  "reviewer":      "gold",
+  "deep-reviewer": "gold",
+  "planner":       "gold"
+}
+```
+
+**Single-tier (A)** — every role on one model:
+
+```json
+"models": {
+  "gold":          "<provider>/<single-model>",
+  "explorer":      "gold",
+  "coder":         "gold",
+  "resolver":      "gold",
+  "reviewer":      "gold",
+  "deep-reviewer": "gold",
+  "planner":       "gold"
+}
+```
+
+Replace every `<provider>/<model>` placeholder with the **exact** ID strings the user picked. Set `maxParallelSubagents` to **2** if the `coder` model ID contains `glm`, otherwise **4**.
+
+Replace every `<provider>/<model>` placeholder with the **exact** ID strings the user picked in 3b/3d — no inventing, no autocompletion, no version drift. If you cannot map the picked model to a `provider/model` string, ask the user to clarify rather than guessing.
+
+> Each enabled agent carries an explicit `enabled: true` so the file is self-documenting. The `enabled` array remains authoritative; the per-agent flag just removes ambiguity for humans reading the file.
+
+> If `resolve.json` already exists, **do not overwrite it silently**. Show the user the existing content first, summarize what would change, and ask whether to overwrite, merge, or abort.
+
+### Step 4 — Restart OpenCode and verify
+
+Close and reopen OpenCode, then confirm the install worked:
+
+```sh
+opencode run "list available agents"
+```
+
+The output **must** include `resolver` and `coder` (and `reviewer` if enabled). Two failure modes to check explicitly:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Only OpenCode's built-in `explore` / `general` appear | Plugin didn't load | Re-run `opencode plugin opencode-resolve --global --force`; verify `"opencode-resolve"` is in `opencode.json` `plugin` array as a string. |
+| Agents appear but fail when invoked with "model not found" | A pinned model ID in `models` doesn't exist | Re-open `resolve.json`, replace the offending ID with one the user actually has, restart. |
+| The user said split but only one tier shows up | `models` block missing `fast` or `strong` | Re-run Step 3 from 3d. |
+
+Internal specialist subagents (`explorer`, `reviewer`, `deep-reviewer`) are subagent-only and won't appear in the primary picker — only `resolver` (and `coder` since it has `mode: "all"`) show up there.
 
 ### Why this template
 
-- **`enabled`** activates the three default roles: `coder` implements, `reviewer` audits read-only, `resolver` orchestrates.
-- **`autoApprove: true`** lets `coder` and `resolver` work without per-action approval prompts. `reviewer` stays locked to deny — it cannot modify by any means.
-- **`maxParallelSubagents: 2`** is a per-role cap: up to two coders and up to two reviewers may run concurrently when working on genuinely independent things. Drop to `1` for strict per-role serialization, raise above `2` for more aggressive fan-out.
-- **`agents.coder.mode = "all"` and `agents.reviewer.mode = "all"`** make both visible in the primary agent picker, not just as subagents the resolver dispatches. You can still call them directly when you don't need orchestration.
-- **`agents.resolver.enabled: true`** is explicit (default is also true); ships with `mode: "all"` so it appears as both a primary agent and a subagent.
-- **`models`** uses two aliases (`glm` for fast/cheap implementation, `gpt` for stronger orchestration) and pins reviewer to `gpt-4o-mini` for cheap reads. Replace these with model IDs your provider actually exposes.
-- **`context7`** is the only MCP this plugin auto-registers — no other MCP servers are required.
-- All other resolve agents (`architect`, `gpt-coder`, `debugger`, `researcher`) ship disabled. Flip `enabled: true` only if you want to use them.
-
-### Resolver workflow (what happens when you call it)
-
-1. Resolver reads the request, inspects relevant files.
-2. Plans the smallest correct change.
-3. Dispatches `coder` to implement (one at a time).
-4. Verifies (tests, type checks, targeted checks).
-5. If issues remain, dispatches `coder` again with a focused fix.
-6. For risky changes, optionally consults `reviewer` for a read-only audit; routes any required fixes back through `coder`.
-7. Repeats until the task is resolved or clearly blocked, then returns a concise summary.
+| Setting | Why |
+|---|---|
+| `enabled: ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]` | Fixed core path (resolver→coder) plus OpenCode-native internal specialist subagents injected by default |
+| `autoApprove: true` | Coder and resolver work without per-action prompts |
+| `maxParallelSubagents: 2` | Up to two coders may run in parallel for independent work |
+| `agents.coder.mode = "all"` | Coder appears in the agent picker, not just as a subagent |
+| `agents.{explorer,reviewer,deep-reviewer}.mode = "subagent"` | Internal specialists are subagent-only — never user-facing primary roles |
+| `context7: true` | Plugin auto-registers Context7 MCP — no manual MCP config needed |
+| `models` aliases | Empty by default — all roles inherit the OpenCode default model. Pin role-specific models only when you have measured a benefit |
+| Other agents disabled | `architect`, `gpt-coder`, `debugger`, `researcher` off by default. Enable when needed |
+
+### What happens when you call the resolver
+
+1. **Classify** — Resolver classifies the work as quick, normal, deep, or risky.
+2. **Inspect** — Reads only relevant files using local tools. No broad exploration.
+3. **For trivial work** — Resolver applies the small edit directly. No subagent needed.
+4. **Implement** — Dispatches `coder` with exact file paths and focused instructions.
+5. **Verify** — Runs the cheapest meaningful check first (targeted test, type check, or lint).
+6. **Retry** — If issues remain, dispatches `coder` again with a focused fix. Max 3 attempts per failing checkpoint. When verified, proceed to the next checkpoint.
+7. **Report** — Returns a concise evidence summary: what changed, verification results, and any remaining blockers.
+8. **Internal specialists** — When justified: dispatch `explorer` (scope genuinely unknown), `reviewer` (verification gap on non-trivial changes), or `deep-reviewer` (risky/security/high-impact only). These are available by default as subagents but are not the core path.
 
 ---
 
@@ -153,14 +438,16 @@ opencode plugin opencode-resolve --global --force
 
 | Item | Default |
 |---|---|
-| Enabled agents | `coder`, `reviewer`, `resolver` |
+| Enabled agents | `coder`, `resolver`, `explorer`, `reviewer`, `deep-reviewer` |
+| Core path | `resolver` → `coder` (fixed-role verified loop) |
+| Internal subagents | `explorer`, `reviewer`, `deep-reviewer` (subagent-only, dispatched when justified) |
 | Primary agent for new tasks | `resolver` (`mode: "all"`) |
 | Agent model | Inherits top-level OpenCode `model` |
 | Native `plan` / `build` | Preserved untouched |
-| Context7 MCP preset | Added if absent |
+| Context7 MCP preset | Added automatically when `context7: true` |
 | Optional commands | Disabled |
 | `autoApprove` | `true` (no per-action prompts on coder/resolver) |
-| Reviewer modification | Denied (cannot be auto-approved) |
+| Max retries per checkpoint | 3 (via resolver prompt) |
 
 ---
 
@@ -180,14 +467,14 @@ Inline plugin options in `opencode.json` override file config.
 Config precedence:
 
 ```text
-built-in defaults -> first config file found -> inline plugin options
+built-in defaults → first config file found → inline plugin options
 ```
 
 Minimal config (matches defaults):
 
 ```json
 {
-  "enabled": ["coder", "reviewer", "resolver"],
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
   "autoApprove": true,
   "context7": true,
   "commands": false
@@ -202,7 +489,7 @@ Inline form inside `opencode.json`:
     [
       "opencode-resolve",
       {
-        "enabled": ["coder", "reviewer", "resolver"],
+        "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
         "autoApprove": true,
         "context7": true,
         "commands": false
@@ -222,13 +509,13 @@ Every accepted top-level option:
 
 | Key | Type | Default | Purpose |
 |---|---|---|---|
-| `enabled` | `string[]` | `["coder", "reviewer", "resolver"]` | Which resolve agents to inject. Per-agent `agents.<name>.enabled` overrides this. |
+| `enabled` | `string[]` | `["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]` | Which resolve agents to inject. Core path: resolver→coder. Internal specialists (explorer, reviewer, deep-reviewer) are subagent-only. Per-agent `agents.<name>.enabled` overrides this. |
 | `preserveNative` | `boolean` | `true` | Native `plan`/`build` are always preserved. Accepted for readability. |
 | `context7` | `boolean` | `true` | When true, registers the Context7 MCP server unless already configured. |
 | `commands` | `boolean` | `false` | When true, adds `resolve`, `resolve-code`, `resolve-review` commands. |
 | `autoApprove` | `boolean` | `true` | Flips default `"ask"` permissions to `"allow"` on enabled agents. Never touches `"deny"` or user-set keys. |
-| `maxParallelSubagents` | `positive integer` | `1` | Cap on simultaneous subagents the resolver dispatches across coder, reviewer, etc. |
-| `models` | `object` | `{}` | Alias map. Keys are agent names or `glm`/`gpt`. Values are model ids or other aliases. |
+| `maxParallelSubagents` | `positive integer` | `2` | Cap on simultaneous subagents the resolver dispatches per role. |
+| `models` | `object` | `{}` | Alias map. Keys are agent names or `fast`/`strong`/`mini`/`codex`/`quick`/`deep`/`glm`/`gpt`. Values are model ids or other aliases. Empty by default — all roles inherit the OpenCode default model. |
 | `agents` | `object` | `{}` | Per-agent overrides (see below). |
 | `config` | `string` | _none_ | Custom path to a config file (relative to the project or absolute). |
 
@@ -260,9 +547,7 @@ Permission keys (each takes `"ask"`, `"allow"`, or `"deny"`):
 }
 ```
 
-A fully-annotated reference config ships with the package as
-[`opencode-resolve.reference.jsonc`](./opencode-resolve.reference.jsonc) — copy
-the keys you need into your `resolve.json` (without the comments).
+A fully-annotated reference config ships with the package as [`opencode-resolve.reference.jsonc`](./opencode-resolve.reference.jsonc) — copy the keys you need into your `resolve.json` (without the comments).
 
 ---
 
@@ -278,7 +563,7 @@ the keys you need into your `resolve.json` (without the comments).
 | User explicit `"allow"` | stays `"allow"` | stays `"allow"` |
 | User explicit `"deny"` | stays `"deny"` | stays `"deny"` |
 
-Reviewer permissions for `edit` and `bash` are `"deny"` in the defaults, so `autoApprove` cannot grant the reviewer modification rights.
+Agents with `"deny"` defaults (e.g. reviewer's `edit` and `bash`) keep those denials even with `autoApprove: true`. Reviewer is enabled by default as an internal subagent — its deny permissions ensure it stays read-only.
 
 Turn it off when you want the conservative ask-every-time behavior:
 
@@ -288,29 +573,29 @@ Turn it off when you want the conservative ask-every-time behavior:
 }
 ```
 
-Trust note: `autoApprove: true` assumes you trust the workspace and the model you have configured. Use a sandbox or VM for untrusted code, and keep `autoApprove: false` if you want to inspect every action.
+> **Trust note:** `autoApprove: true` assumes you trust the workspace and the model you have configured. Use a sandbox or VM for untrusted code, and keep `autoApprove: false` if you want to inspect every action.
 
 ---
 
 ## Parallel Subagent Limit
 
-`maxParallelSubagents` (default `2`) caps how many subagents the **resolver** may dispatch concurrently **per role**. The default of `2` lets up to two coders run in parallel AND up to two reviewers run in parallel — total up to four subagents in flight when both roles are active. Subagents of different roles may always run concurrently (e.g. coder implementing while reviewer audits the previous step).
+`maxParallelSubagents` (default `2`) caps how many subagents the **resolver** may dispatch concurrently **per role** for context efficiency. The default of `2` lets up to two coders run in parallel for genuinely independent work.
 
 | Value | Behavior |
 |---|---|
-| `1` | Strictly one of each role at a time. Coder may run while reviewer runs, but never two coders or two reviewers in parallel. |
-| `2` (default) | Up to two of each role concurrently. Total in flight up to (per-role limit × number of active roles). |
-| `N > 2` | Up to N of each role concurrently. Useful when fanning out genuinely independent work. |
+| `1` | Strictly one coder at a time. |
+| `2` (default) | Up to two coders concurrently. Useful when fanning out genuinely independent work. |
+| `N > 2` | Up to N coders concurrently. Use sparingly to avoid context waste. |
 
 Override per project or per user:
 
 ```json
-{ "maxParallelSubagents": 1 }   // strictest
-{ "maxParallelSubagents": 2 }   // default
-{ "maxParallelSubagents": 4 }   // aggressive parallelism
+{ "maxParallelSubagents": 1 }
+{ "maxParallelSubagents": 2 }
+{ "maxParallelSubagents": 4 }
 ```
 
-> **Important — soft limit, not a hard cap.** The limit is woven into the resolver's system prompt only. There is no runtime interceptor that blocks excess dispatches. Modern models (GPT-5.x, GLM-5, Claude 4.x) generally respect the directive, but if a model misbehaves, dispatches above the limit will go through. Pair this with `maxSteps` to bound total iterations if you want a stricter ceiling.
+> **Important — soft limit, not a hard cap.** The limit is woven into the resolver's system prompt only. There is no runtime interceptor that blocks excess dispatches. Capable instruction-following coding models generally respect the directive, but if a model misbehaves, dispatches above the limit will go through. Pair this with `maxSteps` to bound total iterations if you want a stricter ceiling.
 
 The limit is templated into the prompt at config-load time, so restart OpenCode to pick up the new value. If you provide a custom `agents.resolver.prompt`, the templated rule is skipped and your prompt wins entirely.
 
@@ -325,6 +610,18 @@ When you upgrade to a newer version of `opencode-resolve`, the `postinstall` scr
 - **Never** rewrites your `enabled` list, `models` map, or `agents` overrides.
 - If `enabled` is set and does not include `"resolver"`, prints a one-line tip suggesting you add it. Your file is left untouched.
 
+### Adaptive first-install preset
+
+When `resolve.json` does **not** exist, postinstall inspects your OpenCode model configuration and writes a provider-adapted `models` block:
+
+| Detected provider | Preset |
+|---|---|
+| GLM / ZAI | Mixed GLM + GPT: coder/explorer → GLM, resolver/reviewer/deep-reviewer → GPT |
+| OpenAI / GPT | Single-provider: all roles use your current OpenAI model |
+| Other or none | Model-neutral: `models: {}` (all roles inherit OpenCode default) |
+
+To change presets at any time, edit `models` in `resolve.json` directly or delete the file and reinstall.
+
 Skip the migration entirely with:
 
 ```sh
@@ -335,7 +632,7 @@ OPENCODE_RESOLVE_SKIP_POSTINSTALL=1 npm install -g opencode-resolve
 
 ## Model Setup
 
-`opencode-resolve` does not ship a provider-specific role default.
+`opencode-resolve` does not pin any provider-specific model by default. All resolve agents inherit your top-level OpenCode `model` — use a single efficient model if it gives the best token-per-result efficiency. Only pin role-specific models when you have measured a benefit.
 
 Model resolution order for each resolve agent:
 
@@ -344,68 +641,80 @@ Model resolution order for each resolve agent:
 3. top-level OpenCode `model`
 4. OpenCode's own fallback when no model is configured
 
-Use the default config when all resolve roles should follow your current OpenCode model.
+### Use default model for everything (recommended)
 
-Pin models only when you intentionally want fixed role behavior, such as fast coding on one model and deeper review on another.
+```json
+{
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
+  "models": {}
+}
+```
 
-Role-specific aliases:
+### Role-specific aliases (when measured benefit exists)
 
 ```json
 {
-  "enabled": ["coder", "reviewer", "resolver"],
+  "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"],
   "models": {
-    "glm": "zai-coding-plan/glm-5.1",
-    "gpt": "openai/gpt-5.5",
-    "coder": "glm",
-    "resolver": "gpt",
-    "reviewer": "gpt"
+    "fast": "openai/gpt-5-mini",
+    "strong": "openai/gpt-5.3-codex",
+    "coder": "fast",
+    "resolver": "strong"
   }
 }
 ```
 
-Pin one role directly:
+### Pin one role directly
 
 ```json
 {
   "agents": {
-    "reviewer": {
-      "model": "openai/gpt-5.5"
+    "resolver": {
+      "model": "openai/gpt-5.3-codex"
     }
   }
 }
 ```
 
-Native OpenCode agents such as `plan` and `build` are configured through the top-level OpenCode `agent`, not through `opencode-resolve`.
+### Mixed setup (OpenCode config + resolve models)
 
-Mixed setup example:
+Native OpenCode agents such as `plan` and `build` are configured through the top-level OpenCode `agent`, not through `opencode-resolve`.
 
 ```json
 {
-  "model": "zai-coding-plan/glm-5.1",
+  "model": "openai/gpt-5-mini",
   "agent": {
     "plan": {
-      "model": "openai/gpt-5.5"
+      "model": "openai/gpt-5.3-codex"
     }
   },
   "plugin": [
     [
       "opencode-resolve",
       {
-        "enabled": ["coder", "reviewer", "resolver"],
-        "models": {
-          "glm": "zai-coding-plan/glm-5.1",
-          "gpt": "openai/gpt-5.5",
-          "coder": "glm",
-          "resolver": "gpt",
-          "reviewer": "gpt"
-        }
+        "enabled": ["coder", "resolver", "explorer", "reviewer", "deep-reviewer"]
       }
     ]
   ]
 }
 ```
 
-In this setup, `plan`, `resolver`, and `reviewer` use `openai/gpt-5.5`; native `build` and resolve `coder` use `zai-coding-plan/glm-5.1`.
+In this setup, `plan` uses `openai/gpt-5.3-codex`; native `build`, resolve `coder`, and resolve `resolver` all use `openai/gpt-5-mini`.
+
+### Supported model alias keys
+
+| Alias | Purpose |
+|---|---|
+| `fast` | Provider-neutral alias for a fast/cheap model |
+| `strong` | Provider-neutral alias for a strong/expensive model |
+| `mini` | Provider-neutral alias for a mini/efficient model |
+| `codex` | Provider-neutral alias for a codex-style coding model |
+| `quick` | Legacy alias (equivalent to `fast`) |
+| `deep` | Legacy alias (equivalent to `strong`) |
+| `glm` | Legacy alias (backward compatibility) |
+| `gpt` | Legacy alias (backward compatibility) |
+
+Aliases only resolve when defined in `models`. Agent names (`coder`, `resolver`, etc.) are also valid alias keys.
 
 ---
 
@@ -413,9 +722,11 @@ In this setup, `plan`, `resolver`, and `reviewer` use `openai/gpt-5.5`; native `
 
 | Agent | Default | Mode | Edit | Bash | WebFetch | Purpose |
 |---|:---:|---|---|---|---|---|
-| `resolver` | Yes | `all` | ask → allow | ask → allow | ask → allow | Primary orchestrator. Plans, dispatches `coder` (one at a time), verifies, iterates to completion. |
-| `coder` | Yes | `subagent` | ask → allow | ask → allow | ask → allow | Focused implementer. Smallest correct change. |
-| `reviewer` | Yes | `subagent` | **deny** | **deny** | ask → allow | Read-only auditor. Cannot modify by any means. |
+| `resolver` | Yes (core) | `all` | ask → allow | ask → allow | ask → allow | Context-efficient orchestrator. Decomposes work into verified checkpoints, dispatches coder, verifies each, carries forward. Max 3 retries per failing checkpoint. |
+| `coder` | Yes (core) | `subagent` | ask → allow | ask → allow | ask → allow | Focused implementer. Smallest correct patch. Reads only needed files. |
+| `explorer` | Yes (subagent) | `subagent` | **deny** | ask → allow | ask → allow | Internal fast codebase scout. Resolver dispatches when scope is genuinely unknown; prefers local read/grep/glob for narrow scope. |
+| `reviewer` | Yes (subagent) | `subagent` | **deny** | **deny** | ask → allow | Internal verification-gap auditor. Resolver dispatches for post-change verification gaps on non-trivial changes. |
+| `deep-reviewer` | Yes (subagent) | `subagent` | **deny** | **deny** | ask → allow | Internal thorough review for risky/security/architecture changes. Resolver dispatches ONLY for high-impact work. |
 | `architect` | No | `subagent` | deny | ask → allow | ask → allow | Design and task decomposition. |
 | `gpt-coder` | No | `subagent` | ask → allow | ask → allow | ask → allow | Stronger-reasoning implementation fallback. |
 | `debugger` | No | `subagent` | ask → allow | ask → allow | ask → allow | Reproduction and root-cause analysis. |
@@ -433,19 +744,25 @@ Supported modes:
 
 Supported permission values: `ask`, `allow`, `deny`.
 
-Supported model alias keys: `glm`, `gpt`, and every supported agent name. Aliases only resolve when defined in `models`.
+Supported model alias keys: `fast`, `strong`, `mini`, `codex`, `quick`, `deep`, `glm`, `gpt`, and every supported agent name. Aliases only resolve when defined in `models`.
 
 `preserveNative` is accepted for readability, but native `plan` and `build` are always preserved. The plugin never rewrites built-in OpenCode agents.
 
 ### Resolver orchestration rules
 
-The resolver's prompt enforces the following behavior:
+The resolver uses a context-efficient approach with checkpointed execution (max 3 retries per failing checkpoint):
 
-- Plan the smallest correct change before dispatching.
-- Dispatch **only one `coder` subagent at a time**. Never call coders in parallel.
-- After each coder run, verify (tests, type checks, targeted checks) when practical.
-- Optionally consult `reviewer` for an independent read-only audit on risky changes; route any required fixes back through `coder`.
-- Iterate until the task is resolved or clearly blocked, then return a concise summary.
+- **Classify** the work as quick, normal, deep, or risky before planning.
+- **Inspect only relevant files** using local tools — avoid broad exploration.
+- For trivial work, apply edits directly — no subagent needed.
+- Dispatch **coder** with focused file/behavior instructions.
+- Run the **cheapest meaningful verification** first.
+- Retry from verification logs if issues remain. Max 3 attempts per failing checkpoint; then move forward or report the blocker.
+- Use **explorer** only when scope is genuinely unknown and local read/grep/glob are insufficient (internal subagent, not core path).
+- Use **reviewer** only when a verification gap exists on non-trivial changes (internal subagent, not core path).
+- Use **deep-reviewer** only for risky, security-sensitive, architectural, or high-impact changes (internal subagent, not core path).
+- Return a concise evidence summary when resolved or blocked.
+- Honor the `maxParallelSubagents` per-role limit for context efficiency.
 
 ---
 
@@ -461,6 +778,56 @@ Set `commands: true` to add helper subtask commands:
 
 ---
 
+## Context7 Integration
+
+When `context7: true` (the default), the plugin automatically registers the [Context7](https://context7.com) MCP server at startup:
+
+```json
+{
+  "type": "remote",
+  "url": "https://mcp.context7.com/mcp"
+}
+```
+
+This gives all resolve agents access to up-to-date library and framework documentation through the `resolve-library-id` and `query-docs` tools — no manual MCP configuration needed.
+
+To disable Context7 registration (e.g. you already have it configured, or you don't want it):
+
+```json
+{
+  "context7": false
+}
+```
+
+If `mcp.context7` is already present in your OpenCode config, the plugin does not overwrite it.
+
+---
+
+## Keeping Up to Date
+
+> **OpenCode caches the last version it downloaded.** To get a new release you must explicitly refresh.
+
+```sh
+# Upgrade via npm
+npm install -g opencode-resolve@latest
+
+# Refresh the OpenCode cache
+opencode plugin opencode-resolve --global --force
+
+# Restart OpenCode
+```
+
+After upgrading, `postinstall` runs additive migration on your `resolve.json` — new keys are added, existing keys are never modified.
+
+### Pinning a specific version
+
+```sh
+npm install -g opencode-resolve@0.1.3
+opencode plugin opencode-resolve --global --force
+```
+
+---
+
 ## Local Development
 
 From this repository:
@@ -536,7 +903,19 @@ The release workflow runs `npm ci`, `npm run typecheck`, `npm test`, and `npm pu
 ## Design Rules
 
 - Do not overwrite native `plan` or `build` agents.
-- Keep the default agent set small and role-clear: `resolver` orchestrates, `coder` modifies, `reviewer` only reads.
-- The reviewer never modifies anything — fixes always go through `coder` or `resolver`.
-- The resolver dispatches at most one coder at a time.
+- Core path is fixed: `resolver` (context-efficient planner/judge) → `coder` (implementer).
+- Internal specialist subagents (`explorer`, `reviewer`, `deep-reviewer`) are injected by default as OpenCode-native subagents — they inherit OpenCode's composition philosophy — but are not the default execution path and are never user-facing primary roles.
+- Resolver prefers local read/grep/glob for narrow scope; dispatches `explorer` only when scope is genuinely unknown.
+- Resolver dispatches `reviewer` only for verification gaps on non-trivial changes.
+- Resolver dispatches `deep-reviewer` only for risky, security-sensitive, architectural, or high-impact changes.
+- Reviewer and deep-reviewer are read-only — fixes always go through `coder` or `resolver`.
+- Max 3 retries per failing checkpoint to avoid wasted context. Large tasks are decomposed into verified checkpoints.
+- The resolver honors `maxParallelSubagents` for context efficiency.
 - Search and inspect before editing. Make the smallest correct change. Verify when practical.
+- Read only needed files. Avoid broad exploration. Targeted verification, not full suites.
+
+---
+
+## License
+
+[MIT](./LICENSE)