opencode-resolve 0.1.2 → 0.1.3

package/README.md

@@ -77,13 +77,15 @@ Manual fallback: add the plugin to `~/.config/opencode/opencode.json` yourself:
 
 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.
 
-**Step 1 — install the plugin:**
+> **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.
+
+**Step 1 — install via OpenCode (also primes the cache):**
 
 ```sh
-npm install -g opencode-resolve
+opencode plugin opencode-resolve --global --force
 ```
 
-**Step 2 — `~/.config/opencode/opencode.json`** (the only required keys; merge into an existing file rather than replacing if one exists):
+**Step 2 — `~/.config/opencode/opencode.json`** (merge into the existing file; do not replace it):
 
 ```json
 {
@@ -93,7 +95,7 @@ npm install -g opencode-resolve
 }
 ```
 
-**Step 3 — `~/.config/opencode/resolve.json`** (created automatically by `postinstall`; the file below is the canonical default):
+**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):
 
 ```json
 {
@@ -102,15 +104,48 @@ npm install -g opencode-resolve
   "context7": true,
   "commands": false,
   "autoApprove": true,
-  "maxParallelSubagents": 1
+  "maxParallelSubagents": 2,
+  "models": {
+    "glm": "zai-coding-plan/glm-5",
+    "gpt": "openai/gpt-5.5",
+    "coder": "glm",
+    "reviewer": "openai/gpt-4o-mini",
+    "resolver": "gpt"
+  },
+  "agents": {
+    "coder":    { "mode": "all" },
+    "reviewer": { "mode": "all" },
+    "resolver": { "enabled": true },
+    "architect":  { "enabled": false },
+    "gpt-coder":  { "enabled": false },
+    "debugger":   { "enabled": false },
+    "researcher": { "enabled": false }
+  }
 }
 ```
 
 **Step 4 — restart OpenCode.**
 
-That is the entire setup. `context7` is the only MCP server the plugin needs (auto-registered when the key above is `true`) — no other MCP entries are required for `opencode-resolve` itself. Models are inherited from your top-level OpenCode `model` unless you pin per-role models under `models` (see [Model Setup](#model-setup)).
+### Why this template
 
-If you want stricter behavior, flip `autoApprove` to `false` (every action prompts for approval) and/or raise `maxParallelSubagents` to let the resolver fan out independent subtasks.
+- **`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.
 
 ---
 
@@ -259,17 +294,25 @@ Trust note: `autoApprove: true` assumes you trust the workspace and the model yo
 
 ## Parallel Subagent Limit
 
-`maxParallelSubagents` (default `1`) caps how many subagents the **resolver** may dispatch in parallel — across `coder`, `reviewer`, or any other subagent. The default of `1` enforces strictly serial dispatch: resolver waits for each subagent to finish before launching the next.
+`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).
+
+| 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. |
 
-Raise it when you want resolver to fan out independent subtasks:
+Override per project or per user:
 
 ```json
-{
-  "maxParallelSubagents": 3
-}
+{ "maxParallelSubagents": 1 }   // strictest
+{ "maxParallelSubagents": 2 }   // default
+{ "maxParallelSubagents": 4 }   // aggressive parallelism
 ```
 
-The limit is woven into the resolver's prompt at config-load time, so changing it does not require any code changes — restart OpenCode to pick up the new limit. If you provide a custom `agents.resolver.prompt`, the templated rule is skipped and your prompt wins.
+> **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.
+
+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.
 
 ---
 

package/dist/index.js

@@ -20,7 +20,7 @@ const VALID_TOP_LEVEL_KEYS = new Set([
     "maxParallelSubagents",
     "config",
 ]);
-const DEFAULT_MAX_PARALLEL_SUBAGENTS = 1;
+const DEFAULT_MAX_PARALLEL_SUBAGENTS = 2;
 const VALID_AGENT_KEYS = new Set([
     "enabled",
     "model",
@@ -35,8 +35,8 @@ const VALID_AGENT_KEYS = new Set([
 function buildResolverPrompt(maxParallelSubagents) {
     const limit = Math.max(1, Math.trunc(maxParallelSubagents));
     const parallelRule = limit === 1
-        ? "CRITICAL: Dispatch only ONE subagent at a time. Never call multiple subagents (coder, reviewer, or any other) in parallel. Wait for the current subagent to finish and evaluate its result before dispatching the next one."
-        : `CRITICAL: Dispatch at most ${limit} subagents in parallel. Never exceed this limit across coder, reviewer, or any other subagent. Wait for in-flight subagents to finish and evaluate their results before launching new ones.`;
+        ? "CRITICAL: Dispatch at most ONE subagent of each role concurrently. Never run two coders in parallel, and never run two reviewers in parallel. A coder and a reviewer MAY run concurrently when they are doing genuinely independent work (e.g. coder is implementing the next change while reviewer audits the previous one). Wait for an in-flight subagent of a given role to finish before dispatching another of the same role."
+        : `CRITICAL: Dispatch at most ${limit} subagents of the same role concurrently. Never exceed ${limit} coders in parallel, and never exceed ${limit} reviewers in parallel. Subagents of different roles may run concurrently when they are doing genuinely independent work. Wait for in-flight subagents of a given role to finish before dispatching more of that role.`;
     return [
         "You are Resolver, the primary orchestrator agent for OpenCode Resolve.",
         "Your job is to drive the user's task to a verified resolution end-to-end without unnecessary stops.",
@@ -47,9 +47,10 @@ function buildResolverPrompt(maxParallelSubagents) {
         `4. ${parallelRule}`,
         "5. After implementation, verify when practical (run tests, type checks, or targeted checks).",
         "6. If issues remain, dispatch the coder again with a focused fix, or apply a small direct edit yourself when it is clearly trivial.",
-        "7. Optionally consult the reviewer subagent for an independent read-only review on risky changes. The reviewer cannot modify anything; treat its output as advice and route any required fixes back through the coder. The same parallel-dispatch limit applies to the reviewer.",
+        "7. Optionally consult the reviewer subagent for an independent read-only review on risky changes. The reviewer cannot modify anything; treat its output as advice and route any required fixes back through the coder. The same per-role parallel limit applies to the reviewer.",
         "8. Repeat until the task is resolved or clearly blocked.",
         "Return a concise summary of what changed, verification results, and any remaining blockers.",
+        "Note: this parallel rule is enforced via prompt only — there is no runtime cap on subagent dispatches. Honor it strictly to avoid file conflicts and wasted work.",
     ].join("\n");
 }
 const DEFAULT_AGENT_CONFIG = {

package/opencode-resolve.example.json

@@ -4,14 +4,14 @@
   "context7": true,
   "commands": false,
   "autoApprove": true,
-  "maxParallelSubagents": 1,
+  "maxParallelSubagents": 2,
   "models": {},
   "agents": {
     "coder": {
-      "enabled": true
+      "mode": "all"
     },
     "reviewer": {
-      "enabled": true
+      "mode": "all"
     },
     "resolver": {
       "enabled": true
@@ -30,3 +30,4 @@
     }
   }
 }
+

package/opencode-resolve.reference.jsonc

@@ -58,11 +58,16 @@
 
   // -----------------------------------------------------------------------
   // maxParallelSubagents (positive integer)
-  // Maximum number of subagents the resolver may dispatch in parallel
-  // (across coder, reviewer, etc.). Default: 1 — strictly serial.
-  // Increase if you want resolver to fan out independent subtasks.
-  // -----------------------------------------------------------------------
-  "maxParallelSubagents": 1,
+  // Maximum number of subagents of the SAME ROLE the resolver may dispatch
+  // concurrently. Default: 2 — at most two coders in parallel and at most
+  // two reviewers in parallel. Subagents of different roles may always run
+  // concurrently. This is a soft prompt-level limit, not a runtime cap —
+  // pair with `maxSteps` if you need a stricter ceiling.
+  //   1 = strict per-role serial (one of each role at a time)
+  //   2 = default
+  //   N = up to N of each role
+  // -----------------------------------------------------------------------
+  "maxParallelSubagents": 2,
 
   // -----------------------------------------------------------------------
   // models (object)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-resolve",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "OpenCode plugin that adds a small coder/reviewer agent set while preserving native plan/build behavior.",
   "type": "module",
   "homepage": "https://github.com/jshsakura/opencode-resolve#readme",

package/scripts/postinstall.mjs

@@ -13,7 +13,7 @@ const exampleConfigPath = join(root, "opencode-resolve.example.json")
 
 const ADDITIVE_DEFAULTS = {
   autoApprove: true,
-  maxParallelSubagents: 1,
+  maxParallelSubagents: 2,
 }
 
 if (process.env.OPENCODE_RESOLVE_SKIP_POSTINSTALL === "1") {