opencode-turnstile 0.1.1 → 0.2.0

package/README.md

@@ -65,7 +65,7 @@ turnstile unchanged unless a gate applies. Other adjacent approaches
 gate on written artifacts, like spec workflows, or on a single
 human-approval point; turnstile gates the machine steps around those.
 The bundled planner/executor/test-runner/reviewer agents in
-`.opencode/agents/` are the reference pipeline, not a requirement; the
+`agents/` are the reference pipeline, not a requirement; the
 gates key off agent names and markers, and other suites' agents can
 carry their own markers.
 
@@ -211,19 +211,93 @@ to touch.
 
 ### Set the agents' models
 
-The six agent definitions in `.opencode/agents/` ship with `model:`
-frontmatter pointing at the author's locally served models (`oMLX/...`).
-You almost certainly do not have those models, and dispatches to the
-pipeline agents will fail or fall back until you set your own.
+The six agent definitions in `agents/` ship **without** a `model:`
+frontmatter key. Each subagent therefore runs on the model of the session
+that dispatched it — OpenCode v2's documented inheritance rule — so there
+is nothing to configure for the common case.
+
+To pin a specific model per agent, paste a block into
+`~/.config/opencode/opencode.json` (**plural** `agents` is the v2 key;
+v1 used singular `agent`):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agents": {
+    "planner": { "model": "anthropic/claude-haiku-4-5" },
+    "plan-reviewer": { "model": "anthropic/claude-haiku-4-5" },
+    "executor": { "model": "anthropic/claude-sonnet-4-5" },
+    "test-runner": { "model": "anthropic/claude-haiku-4-5" },
+    "reviewer": { "model": "anthropic/claude-sonnet-4-5" },
+    "debugger": { "model": "anthropic/claude-sonnet-4-5" },
+  },
+}
+```
+
+Model IDs come from `opencode models` and take the form
+`provider/modelID`, with an optional `#variant`. Restarts pick the change
+up. Because the shipped definitions are silent on `model:`, a pin you add
+is the only definition of that model — there is no merge precedence to
+reason about.
+
+Copy-mode users: after a `git pull` that changes these definitions,
+re-run `npm run install:copy` to pick up the new frontmatter. `npm run
+install:check` will report `stale` (not `conflict`) until you do.
+
+### Printing a model config
+
+To generate a `{"agents": {…}}` snippet instead of copying the six agent
+names by hand, run the printer. It writes nothing — it short-circuits before
+any install work, so the ledger, links, and copies are untouched:
+
+```sh
+npm run init -- --print-model-config
+```
+
+That prints one entry per agent, each defaulting to a placeholder:
+
+```json
+{
+  "agents": {
+    "planner": "<provider>/<model-id>",
+    "plan-reviewer": "<provider>/<model-id>",
+    "executor": "<provider>/<model-id>",
+    "test-runner": "<provider>/<model-id>",
+    "reviewer": "<provider>/<model-id>",
+    "debugger": "<provider>/<model-id>"
+  }
+}
+```
+
+Seed individual agents with repeatable `--model` seeds. A bare
+`provider/model` (optionally `#variant`) seeds all six; `name=` seeds one.
+Model ids may be multi-segment — providers require interior slashes, e.g.
+`oMLX/oQ/GLM-5.3-Flash-oQ4-mtp` — so the model body is everything after the
+first slash.
+
+```sh
+npm run init -- --print-model-config \
+  --model planner=anthropic/claude-haiku-4-5 \
+  --model executor=oMLX/oQ/GLM-5.3-Flash-oQ4-mtp
+```
+
+Add `--validate` to cross-check every concrete seed against
+`opencode models` and exit 1 naming a model it does not list; placeholder
+seeds are skipped. `--model` and `--validate` are only valid with
+`--print-model-config`: given without it, install.mjs prints an actionable
+message and exits 2.
+
+```sh
+npm run init -- --print-model-config --model planner=anthropic/claude-haiku-4-5 --validate
+```
 
-Since installs share the repo's files (symlink mode) or conflict on
-divergence (copy mode), set your models **in the clone**, not in
-`~/.config/opencode/agents/`: edit the `model:` line of each agent file
-(`planner`, `plan-reviewer`, `executor`, `test-runner`, `reviewer`,
-`debugger`) to a model
-you have, in `providerID/modelID` form, then install or re-sync per the
-mode table above. Model overrides in installed copies are lost on the next
-sync; the repo is the source of truth.
+Paste the output into `~/.config/opencode/opencode.json` (see the
+[Set the agents' models](#set-the-agents-models) section).
+`opencode-turnstile init -- --print-model-config` routes the same flags
+through `scripts/install.mjs` and adds nothing of its own: `install.mjs`
+recognizes `--print-model-config` and prints before writing, while the router
+still idempotently installs the contract block in
+`~/.config/opencode/AGENTS.md` in the same run.
 
 ### Customizing the pipeline agents
 
@@ -244,7 +318,7 @@ Two sanctioned ways to change the pipeline:
   hold to the marker contract. Your agents get the same gates the shipped
   ones do.
 - **Fork the repo.** To change the pipeline content itself, fork and edit
-  `.opencode/agents/*.md` there; your installer serves your fork.
+  `agents/*.md` there; your installer serves your fork.
 
 ### Updating
 

package/{.opencode/agents → agents}/debugger.md

@@ -1,7 +1,6 @@
 ---
 description: Investigates failures, identifies root causes, implements targeted fixes, and verifies the result.
 mode: subagent
-model: oMLX/oQ/GLM-5.3-Flash-oQ4-mtp
 # Runaway-loop backstop for the Horizon rule below: near the cap OpenCode
 # drops tools and asks for a summary. Tune to your workflow.
 steps: 50

package/{.opencode/agents → agents}/executor.md

@@ -1,7 +1,6 @@
 ---
 description: Implements an approved plan, validates changes, and fixes test failures
 mode: subagent
-model: oMLX/oQ/Ornith-1.5-35B-A3B-oQ8-mtp
 # Runaway-loop backstop for the Horizon rule below: near the cap OpenCode
 # drops tools and asks for a summary. Tune to your workflow.
 steps: 50

package/{.opencode/agents → agents}/plan-reviewer.md

@@ -1,7 +1,6 @@
 ---
 description: Adversarially reviews an implementation plan for requirement coverage, AC traceability, feasibility, and scope before any code is written
 mode: subagent
-model: oMLX/oQ/GLM-5.3-Flash-oQ4-mtp
 permissions:
   - { action: edit, resource: "*", effect: deny }
   - { action: shell, resource: "*", effect: allow }

package/{.opencode/agents → agents}/planner.md

@@ -1,7 +1,6 @@
 ---
 description: Analyzes requirements, explores the repository, designs implementation approaches by evaluating tradeoffs, and creates implementation plans without modifying source code
 mode: subagent
-model: oMLX/oQ/Qwen3.8-Flash-Next-oQ4-mtp
 permissions:
   - { action: edit, resource: "*", effect: deny }
   - { action: edit, resource: ".opencode/plans/**", effect: allow }

package/{.opencode/agents → agents}/reviewer.md

@@ -1,7 +1,6 @@
 ---
 description: Independently reviews an implementation for correctness, regressions, missing requirements, and inadequate tests
 mode: subagent
-model: oMLX/oQ/GLM-5.3-Flash-oQ4-mtp
 permissions:
   - { action: edit, resource: "*", effect: deny }
   - { action: shell, resource: "*", effect: allow }

package/{.opencode/agents → agents}/test-runner.md

@@ -1,7 +1,6 @@
 ---
 description: Runs tests and verification commands, analyzes failures, and applies scoped fixes to test or environment issues only.
 mode: subagent
-model: oMLX/oQ/Ornith-1.5-35B-A3B-oQ8-mtp
 permissions:
   # Mechanical backstop for the Constraints section: default-deny edits,
   # allow the conventional test layout. Widen or narrow per repo layout.

package/bin/cli.mjs

@@ -30,6 +30,14 @@ Commands:
   uninstall Remove installed artifacts (agents + block)
   version   Print the installed package version
 
+init also accepts convenience flags (passthrough to scripts/install.mjs); separate them from the subcommand with a leading "--":
+  init -- --print-model-config [--model [name=]provider/model[#variant]] [--validate]
+
+  --print-model-config  Print a {"agents": {...}} model snippet, write nothing
+  --model               Seed an agent (repeatable); ids may be multi-segment, e.g. oMLX/oQ/GLM-5.3-Flash-oQ4-mtp
+  --validate            Check concrete specs against "opencode models"
+                        (--model/--validate require --print-model-config, else exit 2)
+
 A git checkout installs by linking (live edits); a package install copies.`
 
 /**
@@ -59,7 +67,19 @@ async function main() {
       // managed contract block in ~/.config/opencode/AGENTS.md, mirroring
       // uninstall's two-step shape in reverse. Passthrough flags go to the
       // manifest installer; the agents installer needs none of them.
-      const byInstall = await spawnInstaller(installScript, passthrough)
+      //
+      // --print-model-config is passthrough too: install.mjs prints the
+      // snippet and short-circuits before any manifest work, but the router
+      // still runs BOTH steps, so the contract block is idempotently
+      // installed as usual. Print mode writes nothing; the two-step install
+      // is the router's idempotent contract-block behavior, which is out of
+      // scope for the write-free printer flag.
+      //
+      // A leading "--" separates the subcommand from its flags
+      // (`init -- --print-model-config`); install.mjs rejects a literal "--"
+      // as an unknown argument, so drop it before forwarding.
+      const initPassthrough = passthrough[0] === "--" ? passthrough.slice(1) : passthrough
+      const byInstall = await spawnInstaller(installScript, initPassthrough)
       const byAgents = await spawnInstaller(agentsScript, [])
       return process.exit(byInstall || byAgents ? 1 : 0)
     }

package/install.json

@@ -6,27 +6,27 @@
       "dest": "~/.config/opencode/plugins/turnstile.ts"
     },
     {
-      "src": ".opencode/agents/plan-reviewer.md",
+      "src": "agents/plan-reviewer.md",
       "dest": "~/.config/opencode/agents/plan-reviewer.md"
     },
     {
-      "src": ".opencode/agents/planner.md",
+      "src": "agents/planner.md",
       "dest": "~/.config/opencode/agents/planner.md"
     },
     {
-      "src": ".opencode/agents/executor.md",
+      "src": "agents/executor.md",
       "dest": "~/.config/opencode/agents/executor.md"
     },
     {
-      "src": ".opencode/agents/test-runner.md",
+      "src": "agents/test-runner.md",
       "dest": "~/.config/opencode/agents/test-runner.md"
     },
     {
-      "src": ".opencode/agents/reviewer.md",
+      "src": "agents/reviewer.md",
       "dest": "~/.config/opencode/agents/reviewer.md"
     },
     {
-      "src": ".opencode/agents/debugger.md",
+      "src": "agents/debugger.md",
       "dest": "~/.config/opencode/agents/debugger.md"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-turnstile",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenCode plugin that mechanically enforces agent pipeline gates (planner → executor → test-runner → reviewer)",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,7 @@
     "install.json",
     "templates",
     "skills",
-    ".opencode/agents",
+    "agents",
     "README.md",
     "LICENSE"
   ],

package/scripts/check-markers.mjs

@@ -42,10 +42,10 @@ for (const line of lines) {
 }
 
 // Agent templates: the backticked GATE:/VERDICT: examples in
-// .opencode/agents/*.md are the prompt-side half of the marker contract.
+// agents/*.md are the prompt-side half of the marker contract.
 // Templates spell the numeric fields <n>; they must parse once the
 // placeholder stands in for digits.
-const agentsDir = join(root, ".opencode", "agents")
+const agentsDir = join(root, "agents")
 let agentTemplates = 0
 for (const f of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
   const text = readFileSync(join(agentsDir, f), "utf8")
@@ -60,7 +60,7 @@ for (const f of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
   }
 }
 if (agentTemplates === 0) {
-  console.error("check-markers: no marker templates found in .opencode/agents")
+  console.error("check-markers: no marker templates found in agents/")
   failed++
 }
 

package/scripts/install.mjs

@@ -18,6 +18,17 @@
 //   --link/--copy  Override the mode. Resolution: CLI flag > manifest "mode"
 //                  field > auto-detect (.git present => link, else copy)
 //
+//   --print-model-config  Print a ready-to-paste {"agents": {...}} model
+//                  snippet to stdout and write nothing (short-circuits before
+//                  any manifest/install work, like --check). Repeatable
+//                  --model specs seed individual agents:
+//                  --model [name=]provider/model[#variant] (bare => all six;
+//                  name= sets one; last spec wins per agent). Model ids may be
+//                  multi-segment (e.g. oMLX/oQ/GLM-5.3-Flash-oQ4-mtp).
+//                  --validate cross-checks concrete specs against
+//                  `opencode models` (exit 1 naming a model it does not list).
+//                  --model/--validate without --print-model-config exit 2.
+//
 // Ownership model: symlink targets are repo-owned iff the link resolves
 // inside this checkout; copied files are repo-owned iff the ledger records
 // them. Unowned files are never read, modified, or removed. Conflicts
@@ -36,6 +47,7 @@ import {
   lstat,
   realpath,
 } from "node:fs"
+import { spawnSync } from "node:child_process"
 import { createHash } from "node:crypto"
 import { homedir } from "node:os"
 import { dirname, isAbsolute, join, relative, resolve } from "node:path"
@@ -66,7 +78,7 @@ try {
 /**
  * Parses command-line arguments.
  * @param {string[]} argv Raw argv (process.argv).
- * @returns {{manifest: string, check: boolean, force: boolean, uninstall: boolean, mode: "link"|"copy"|null}} Parsed arguments.
+ * @returns {{manifest: string, check: boolean, force: boolean, uninstall: boolean, mode: "link"|"copy"|null, model: string[], printModelConfig: boolean, validate: boolean, modelSpecs: Record<string,string>}} Parsed arguments. A `--model`/`--validate` without `--print-model-config` is an error and exits 2 (checked before any parsing or I/O). Model specs are validated here only when the printer flag is set; a malformed or unknown-name spec prints an actionable message and exits 2 (matching the unknown-arg contract), and the parsed map is stashed as `modelSpecs` for `main`.
  */
 function parseArgs(argv) {
   const args = {
@@ -75,6 +87,10 @@ function parseArgs(argv) {
     force: false,
     uninstall: false,
     mode: null,
+    model: [],
+    printModelConfig: false,
+    validate: false,
+    modelSpecs: {},
   }
   for (let i = 2; i < argv.length; i++) {
     if (argv[i] === "--manifest") args.manifest = argv[++i]
@@ -83,14 +99,170 @@ function parseArgs(argv) {
     else if (argv[i] === "--uninstall") args.uninstall = true
     else if (argv[i] === "--link") args.mode = "link"
     else if (argv[i] === "--copy") args.mode = "copy"
+    else if (argv[i] === "--model") args.model.push(argv[++i])
+    else if (argv[i] === "--print-model-config") args.printModelConfig = true
+    else if (argv[i] === "--validate") args.validate = true
     else {
       console.error(`install: unknown argument ${argv[i]}`)
       process.exit(2)
     }
   }
+  // --model/--validate only mean something for the printer: given without
+  // --print-model-config they have no effect, so reject them loudly (exit 2,
+  // like an unknown argument) instead of silently falling through to a real
+  // install. Checked first, before any parsing or manifest I/O below.
+  if (!args.printModelConfig && (args.model.length > 0 || args.validate)) {
+    console.error("install: --validate/--model require --print-model-config")
+    process.exit(2)
+  }
+  // A --model spec only matters for the printer; validate it up front (so a
+  // bad one exits 2 like an unknown argument) and stash the parsed map for
+  // `main`.
+  if (args.printModelConfig) {
+    try {
+      args.modelSpecs = parseModelSpecs(args.model)
+    } catch (error) {
+      console.error(`install: ${error.message}`)
+      process.exit(2)
+    }
+  }
   return args
 }
 
+// The six pipeline agents, in canonical order. This is the single source of
+// truth for both the printer (formatModelConfig) and the validator
+// (findMissingModels), so the JSON block and the --validate pass can never
+// disagree on which agents exist.
+const AGENT_NAMES = ["planner", "plan-reviewer", "executor", "test-runner", "reviewer", "debugger"]
+
+/** The placeholder used by `formatModelConfig` for any agent left unset. */
+const MODEL_PLACEHOLDER = "<provider>/<model-id>"
+
+/**
+ * Human-readable model-spec grammar shown in error messages — never the raw
+ * regex source. The name binds at the `=`, the provider to the first segment,
+ * and a `#variant` to the tail; a model id may itself be multi-segment
+ * (e.g. `oMLX/oQ/GLM-5.3-Flash-oQ4-mtp`), so "model" spans interior slashes.
+ */
+const SPEC_GRAMMAR = "[name=]provider/model[#variant] (model ids may be multi-segment)"
+
+/**
+ * Grammar for one model spec: an optional `<name>=` built from AGENT_NAMES
+ * (a single source of truth), then provider (segment 1) and a model id (the
+ * remainder, slashes included) so real multi-segment ids parse, then an
+ * optional `#variant` bound to the tail. Split on the FIRST `/`.
+ */
+const NAME_ALT = AGENT_NAMES.join("|")
+const SPEC_RE = new RegExp(`^(?:(${NAME_ALT})=)?([\\w.-]+)/([\\w.:/-]+)(?:#([\\w.-]+))?$`)
+
+/**
+ * Parses model specs into an agent→spec map, in canonical order. A bare spec
+ * (no `<name>=` prefix) seeds all six agents; `name=` seeds exactly one; the
+ * last spec to name an agent wins. Pure: no filesystem, no spawn.
+ * @param {string[]} specs The raw --model spec strings (possibly empty).
+ * @returns {Record<string, string>} Map of agent name to spec.
+ * @throws {Error} On an unknown agent name (lists the six) or a malformed spec
+ *   (shows the grammar).
+ */
+function parseModelSpecs(specs) {
+  const result = {}
+  for (const spec of specs) {
+    if (typeof spec !== "string")
+      throw new Error(`invalid --model spec "${spec}"; expected ${SPEC_GRAMMAR}`)
+    const eq = spec.indexOf("=")
+    let name = null
+    let body = spec
+    if (eq !== -1) {
+      name = spec.slice(0, eq)
+      body = spec.slice(eq + 1)
+      if (!AGENT_NAMES.includes(name))
+        throw new Error(
+          `unknown agent "${name}" in --model spec; expected one of ${AGENT_NAMES.join(", ")}`,
+        )
+    }
+    if (!body.match(SPEC_RE))
+      throw new Error(`invalid --model spec "${spec}"; expected ${SPEC_GRAMMAR}`)
+    const targets = name ? [name] : AGENT_NAMES
+    for (const agent of targets) result[agent] = body
+  }
+  return result
+}
+
+/**
+ * Formats an agent→spec map into a JSON `{"agents": {...}}` snippet, one entry
+ * per agent in canonical order. Unset agents fall back to a placeholder so the
+ * output is always a complete, paste-ready block. Pure.
+ * @param {Record<string, string>} specs Map of agent name to spec.
+ * @returns {string} The two-space-indented JSON snippet.
+ */
+function formatModelConfig(specs) {
+  const agents = {}
+  for (const agent of AGENT_NAMES) {
+    agents[agent] = specs[agent] ?? MODEL_PLACEHOLDER
+  }
+  return JSON.stringify({ agents }, null, 2)
+}
+
+/**
+ * Finds the concrete specs a user actually named that are not present in
+ * `available` (the parsed lines of `opencode models`). Placeholder specs and
+ * agents the user never named are skipped — only seeded, concrete models are
+ * checked. A `#variant` suffix is stripped before matching (host model lists
+ * the base id) but the spec is reported as named on a miss. Pure: no spawn.
+ * @param {Record<string, string>} specs Map of agent name to spec.
+ * @param {string[]} available Model identifiers as listed by `opencode models`.
+ * @returns {string[]} The named-but-unknown specs, in canonical agent order.
+ */
+function findMissingModels(specs, available) {
+  const availableSet = new Set(available)
+  const missing = []
+  for (const agent of AGENT_NAMES) {
+    const spec = specs[agent]
+    if (!spec || spec === MODEL_PLACEHOLDER) continue
+    if (!availableSet.has(spec.split("#")[0])) missing.push(spec)
+  }
+  return missing
+}
+
+/**
+ * The command runner used by --validate. A thin seam around `spawnSync` so
+ * tests can inject canned `opencode models` output via setCommandRunner
+ * (ESM named imports are read-only, so the runner is overridden through the
+ * setter, not by reassigning the import).
+ */
+let commandRunner = (command, args, options) => spawnSync(command, args, options)
+
+/**
+ * Overrides the --validate command runner (see commandRunner).
+ * @param {(command: string, args: string[], options?: object) => {stdout?: string}} fn New runner.
+ * @returns {void}
+ */
+function setCommandRunner(fn) {
+  commandRunner = fn
+}
+
+/**
+ * Lists the model identifiers the host knows about, by running
+ * `opencode models` through the injectable commandRunner seam. Lines are
+ * split on newlines for `findMissingModels`. A failed spawn throws
+ * `could not run opencode models (<reason>)` rather than reporting every spec
+ * as unknown; `main` consumes that error and returns false (mapped to exit 1),
+ * so this tested path never calls process.exit directly.
+ * @returns {Promise<string[]>} The available model identifiers.
+ * @throws {Error} When the spawn fails, naming it so `main` can report it.
+ */
+async function availableModels() {
+  const res = commandRunner("opencode", ["models"], { encoding: "utf8" })
+  if (res.error || res.status !== 0) {
+    // A failed spawn must not masquerade as "every spec is unknown"; report it
+    // and stop. This runs through the injectable commandRunner seam, so tests
+    // can drive the branch without a live host `opencode models`.
+    const reason = res.error?.message ?? `exit code ${res.status}`
+    throw new Error(`could not run opencode models (${reason})`)
+  }
+  return (res.stdout ?? "").split(/\r?\n/)
+}
+
 /**
  * Auto-detects the install mode from the filesystem: a git checkout links
  * (working tree is the source of truth, edits are live); an extracted
@@ -531,8 +703,34 @@ async function check(manifest, version) {
   return ok
 }
 
-async function main() {
-  const args = parseArgs(process.argv)
+async function main(argv = process.argv) {
+  const args = parseArgs(argv)
+
+  // --print-model-config writes nothing: it parses the requested specs,
+  // optionally validates them against `opencode models`, prints a ready-to
+  // paste snippet, and returns. This short-circuits before the manifest is
+  // even read (like --check), so no link/copy target or ledger entry is
+  // touched. The router still idempotently installs the contract block
+  // separately; that is out of scope for this write-free flag.
+  if (args.printModelConfig) {
+    if (args.validate) {
+      let available
+      try {
+        available = await availableModels()
+      } catch (error) {
+        console.error(`install: ${error instanceof Error ? error.message : String(error)}`)
+        return false
+      }
+      const missing = findMissingModels(args.modelSpecs, available)
+      if (missing.length) {
+        for (const model of missing) console.error(`validate: unknown model ${model}`)
+        return false
+      }
+    }
+    console.log(formatModelConfig(args.modelSpecs))
+    return true
+  }
+
   const manifest = readManifest(args.manifest, args.mode)
   console.log(
     `install: mode=${manifest.mode} (${manifest.mode === "link" ? "checkout" : "package"})`,
@@ -555,5 +753,19 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 }
 
 // Pure, side-effect-free helpers exported for unit tests: tests can
-// import these directly without spawning the CLI.
-export { detectMode, resolveMode, normalizeLedger, removeEntry }
+// import these directly without spawning the CLI. `setCommandRunner` is the
+// seam for faking the `opencode models` spawn (ESM named imports are
+// read-only, so the runner is overridden through this setter); `main` is
+// exported so the write-free print/validate path can be driven in-process
+// with a fake runner (no child spawn, no process.exit in the tested path).
+export {
+  detectMode,
+  resolveMode,
+  normalizeLedger,
+  removeEntry,
+  parseModelSpecs,
+  formatModelConfig,
+  findMissingModels,
+  setCommandRunner,
+  main,
+}