orchestrator-workflow 0.5.0 → 0.6.0

package/INSTALL-AGENT.md

@@ -49,7 +49,8 @@ The install creates or touches only these paths:
 - `.claude/skills/orchestrator-workflow/SKILL.md` and
   `.claude/agents/{explorer,task-slicer,implementer,reviewer}.md` (Claude Code)
 - `.agents/skills/orchestrator-workflow/SKILL.md` (Codex)
-- `.opencode/agents/{explorer,task-slicer,implementer,reviewer}.md` (opencode)
+- `.opencode/skills/orchestrator-workflow/SKILL.md` and
+  `.opencode/agents/{explorer,task-slicer,implementer,reviewer}.md` (opencode)
 
 Nothing else in the repository is modified. Locally edited files are
 reported as conflicts and left alone, never overwritten silently; the
@@ -111,14 +112,31 @@ steps in the repository you were asked to install into.
      line directly after the `model:` line. Ensure `CLAUDE.md` exists and
      contains a line `@AGENTS.md`.
    - Codex: `.agents/skills/orchestrator-workflow/SKILL.md`, same skill file.
-   - opencode: `.opencode/agents/<role>.md` from `assets/agents/<role>.md`,
-     with the frontmatter rewritten to exactly this order: `description:`
-     (unchanged), then `mode: subagent`, then `model: <provider/model-id>`;
-     the `name:` line is dropped. For the explorer role additionally,
-     `permission:` goes on a new line directly after the `model:` line,
-     followed by `  edit: deny` (two-space indent) on the next line. Aliases
-     map to `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-8`,
-     `anthropic/claude-haiku-4-5`.
+   - opencode: `.opencode/skills/orchestrator-workflow/SKILL.md` from
+     `assets/skill/SKILL.md`, unchanged.
+     `.opencode/agents/<role>.md` from `assets/agents/<role>.md`, with the
+     frontmatter rewritten to this order: `description:` (unchanged), then
+     `mode: subagent`; the `name:` line is dropped. Only emit a
+     `model: <provider/model-id>` line when you have a fully-qualified id
+     (i.e. the value contains a `/`, such as
+     `github-copilot/claude-sonnet-4.6`). For a bare alias (`sonnet`, `opus`,
+     `haiku`) or any bare id without a provider prefix, **omit the `model:`
+     line entirely** — the subagent then inherits the session/default model,
+     which is the safe portable fallback. The installed CLI resolves aliases
+     to fully-qualified ids by running `opencode models` at install time; in a
+     manual install you may not have a live catalog, so omitting `model:` is
+     correct. For the explorer role additionally, `permission:` goes on a new
+     line directly after `mode: subagent` (or after `model:` when that line is
+     present), followed by `  edit: deny` (two-space indent) on the next line.
+     Example explorer frontmatter when no model is resolved:
+     ```yaml
+     ---
+     description: "..."
+     mode: subagent
+     permission:
+       edit: deny
+     ---
+     ```
    - `.ai/workflow/manifest.json`, exactly this shape (harnesses MUST be an
      array, models keyed by role, version = the kit version you installed):
 

package/README.md

@@ -99,7 +99,7 @@ Per selected harness:
 |---|---|---|
 | Claude Code | `.claude/skills/orchestrator-workflow/SKILL.md`, `.claude/agents/{explorer,task-slicer,implementer,reviewer}.md`, `CLAUDE.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; the installer adds an additive `@AGENTS.md` import. Subagent models go into the `model:` frontmatter; the read-only explorer also gets `disallowedTools: Edit, Write, NotebookEdit`. |
 | OpenAI Codex | `.agents/skills/orchestrator-workflow/SKILL.md` | Codex reads `AGENTS.md` natively. There is no standardized project-level subagent definition; the skill instructs running the roles inline with the same contracts. |
-| opencode | `.opencode/agents/{explorer,task-slicer,implementer,reviewer}.md` | opencode reads `AGENTS.md` natively and cross-discovers `.claude/skills/`. Subagents get `mode: subagent` plus a fully qualified `provider/model-id`; the explorer also gets `permission: edit: deny`. |
+| opencode | `.opencode/skills/orchestrator-workflow/SKILL.md`, `.opencode/agents/{explorer,task-slicer,implementer,reviewer}.md` | opencode reads `AGENTS.md` natively. Subagents get `mode: subagent`; the explorer also gets `permission: edit: deny`. Model resolution is described below. |
 
 ## Model preselection
 
@@ -113,11 +113,25 @@ Each subagent role gets a model, chosen interactively or via `--models`:
 | reviewer | `opus` | skeptical review benefits from the strongest model |
 
 The orchestrator itself runs on the session's main model; use the strongest
-reasoning model available. Aliases (`sonnet`, `opus`, `haiku`) map to fully
-qualified ids for opencode (for example `anthropic/claude-opus-4-8`). Custom
-ids pass through as given for Claude Code; for opencode, a bare id without a
-provider prefix gets `anthropic/` prepended. The chosen mapping is recorded
-in `.ai/workflow/manifest.json` and reused as the default on later re-runs.
+reasoning model available. The chosen mapping is recorded in
+`.ai/workflow/manifest.json` and reused as the default on later re-runs.
+
+**opencode model resolution.** opencode requires fully-qualified `provider/model-id`
+strings (e.g. `github-copilot/claude-sonnet-4.6`). At install time the CLI
+runs `opencode models` to fetch the live catalog and auto-detects which
+provider to use (the one that offers Claude models). When exactly one such
+provider exists the aliases are resolved to the highest-version matching id in
+the catalog. When multiple providers offer Claude models the CLI warns and asks
+you to pass `--opencode-provider <id>` to disambiguate, or to supply
+fully-qualified ids per role via `--models`. If no resolution is possible
+(catalog empty, `opencode` binary absent, ambiguous provider) the `model:`
+frontmatter line is omitted entirely and the subagent inherits the
+session/default model — a safe, portable fallback. Fully-qualified ids in
+`--models` always pass through unchanged regardless of the catalog.
+Nested-path providers like `openrouter` (whose ids look like
+`openrouter/anthropic/claude-...`) are not auto-resolved from aliases and must
+be supplied as a fully-qualified `--models` entry, e.g.
+`reviewer=openrouter/anthropic/claude-opus-4.8`.
 
 ## Ownership and re-runs
 

package/dist/cli.js

@@ -6,6 +6,7 @@ import inquirer from "inquirer";
 import { PACKAGE_VERSION } from "./assets.js";
 import { HARNESSES, detectHarnesses, parseHarnessList } from "./detect.js";
 import { DEFAULT_MODELS, MODEL_ALIASES, ROLES, assertValidModelId, parseModelsSpec, } from "./models.js";
+import { loadOpencodeCatalog, resolveOpencodeModels } from "./opencode.js";
 import { readInstalledManifest, runInit } from "./init.js";
 import { runUninstall } from "./uninstall.js";
 function isInteractive() {
@@ -101,6 +102,7 @@ program
     .option("-f, --force", "overwrite kit-owned files that have local edits")
     .option("--harness <list>", `comma-separated harnesses (${HARNESSES.join(", ")}); default: detected`)
     .option("--models <spec>", 'per-role model overrides, e.g. "implementer=sonnet,reviewer=opus"')
+    .option("--opencode-provider <id>", "opencode provider id for alias resolution (e.g. github-copilot); auto-detected when omitted")
     .action(async (dir, opts) => {
     const targetDir = requireDirectory(dir);
     if (!targetDir)
@@ -147,11 +149,27 @@ program
         models = parseModelsSpec(opts.models, models);
     if (interactive && !opts.models)
         models = await promptModels(models);
+    // Resolve opencode model aliases against the live catalog when the opencode
+    // harness is selected. The shell-out stays here in the CLI so runInit
+    // remains pure.
+    let opencodeModels;
+    if (harnesses.includes("opencode")) {
+        const catalog = loadOpencodeCatalog();
+        const { resolved, warnings } = resolveOpencodeModels(models, {
+            catalog,
+            explicitProvider: opts.opencodeProvider,
+        });
+        opencodeModels = resolved;
+        for (const w of warnings) {
+            process.stderr.write(`Warning: ${w}\n`);
+        }
+    }
     const report = runInit({
         targetDir,
         harnesses,
         models,
         force: opts.force,
+        opencodeModels,
     });
     showPaths("Created", report.written);
     showPaths("Updated", report.updated);

package/dist/init.d.ts

@@ -6,6 +6,14 @@ export interface InitOptions {
     harnesses: Harness[];
     models: Record<Role, string>;
     force?: boolean;
+    /**
+     * Resolved fully-qualified opencode model ids per role, or `undefined` to
+     * omit the `model:` frontmatter line (subagent inherits the session model).
+     * When this field is absent the fallback is `opencodeModelValue(models[role])`,
+     * which passes through a fully-qualified id and returns `undefined` for bare
+     * aliases, producing the same inherit-session-model behaviour for bare inputs.
+     */
+    opencodeModels?: Record<Role, string | undefined>;
 }
 export interface Manifest {
     kit: string;

package/dist/init.js

@@ -97,14 +97,18 @@ function composeClaudeAgent(role, model) {
     frontmatter.push("---");
     return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
 }
-function composeOpencodeAgent(role, model) {
+function composeOpencodeAgent(role, modelValue) {
     const asset = readAgentAsset(role);
     const frontmatter = [
         "---",
         `description: ${yamlQuote(asset.description)}`,
         "mode: subagent",
-        `model: ${opencodeModelValue(model)}`,
     ];
+    // Only emit `model:` when a resolved, non-empty FQ id is available.
+    // Omitting it lets the subagent inherit the session/default model.
+    if (modelValue) {
+        frontmatter.push(`model: ${modelValue}`);
+    }
     if (READ_ONLY_ROLES.has(role)) {
         frontmatter.push("permission:", "  edit: deny");
     }
@@ -168,8 +172,12 @@ export function runInit(options) {
         installKitFile(join(".agents", "skills", SKILL_NAME, "SKILL.md"), skill);
     }
     if (options.harnesses.includes("opencode")) {
+        installKitFile(join(".opencode", "skills", SKILL_NAME, "SKILL.md"), skill);
         for (const role of ROLES) {
-            installKitFile(join(".opencode", "agents", `${role}.md`), composeOpencodeAgent(role, options.models[role]));
+            const modelValue = options.opencodeModels !== undefined
+                ? options.opencodeModels[role]
+                : opencodeModelValue(options.models[role]);
+            installKitFile(join(".opencode", "agents", `${role}.md`), composeOpencodeAgent(role, modelValue));
         }
     }
     // The manifest records applied state, so it is written last and only when

package/dist/models.d.ts

@@ -18,7 +18,14 @@ export declare function isModelAlias(value: string): value is ModelAlias;
  * full model ids, so the chosen value passes through unchanged.
  */
 export declare function claudeModelValue(model: string): string;
-export declare function opencodeModelValue(model: string): string;
+/**
+ * opencode requires fully qualified `provider/model-id` strings. Returns the
+ * value unchanged when it already contains a provider prefix, or `undefined`
+ * for bare aliases and bare ids that cannot be resolved without a live
+ * catalog. A `undefined` return means the `model:` frontmatter line should be
+ * omitted so the subagent inherits the session model.
+ */
+export declare function opencodeModelValue(model: string): string | undefined;
 /**
  * Model values are interpolated into YAML frontmatter as plain scalars;
  * reject anything that could break out of that position.

package/dist/models.js

@@ -20,16 +20,6 @@ export const DEFAULT_MODELS = {
     implementer: "sonnet",
     reviewer: "opus",
 };
-/**
- * opencode expects fully qualified `provider/model-id` strings (models.dev
- * ids). These are the current Anthropic ids for the three aliases; targets
- * with a different provider setup can pass a custom id instead.
- */
-const OPENCODE_MODEL_IDS = {
-    sonnet: "anthropic/claude-sonnet-4-6",
-    opus: "anthropic/claude-opus-4-8",
-    haiku: "anthropic/claude-haiku-4-5",
-};
 export function isModelAlias(value) {
     return MODEL_ALIASES.includes(value);
 }
@@ -40,10 +30,15 @@ export function isModelAlias(value) {
 export function claudeModelValue(model) {
     return model;
 }
+/**
+ * opencode requires fully qualified `provider/model-id` strings. Returns the
+ * value unchanged when it already contains a provider prefix, or `undefined`
+ * for bare aliases and bare ids that cannot be resolved without a live
+ * catalog. A `undefined` return means the `model:` frontmatter line should be
+ * omitted so the subagent inherits the session model.
+ */
 export function opencodeModelValue(model) {
-    if (isModelAlias(model))
-        return OPENCODE_MODEL_IDS[model];
-    return model.includes("/") ? model : `anthropic/${model}`;
+    return model.includes("/") ? model : undefined;
 }
 /**
  * Model values are interpolated into YAML frontmatter as plain scalars;

package/dist/opencode.d.ts

@@ -0,0 +1,66 @@
+import type { ModelAlias, Role } from "./models.js";
+/**
+ * Splits raw `opencode models` stdout into a list of trimmed non-empty lines,
+ * each of the form `provider/model-id`.
+ */
+export declare function parseOpencodeCatalog(stdout: string): string[];
+/**
+ * Returns the provider id: the substring before the first `/`.
+ * e.g. `github-copilot/claude-sonnet-4.6` → `github-copilot`
+ *      `openrouter/anthropic/claude-sonnet-4.6` → `openrouter`
+ */
+export declare function providerOf(modelLine: string): string;
+/**
+ * Infers which provider to use for alias resolution.
+ *
+ * - If `explicit` is given, it is returned as-is (no catalog check).
+ * - Otherwise the catalog is scanned for providers that offer at least one
+ *   model whose id segment (the part after `provider/`) starts with `claude-`.
+ *   Exactly one such provider → use it.
+ *   More than one → `{ provider: undefined, ambiguous: true }`.
+ *   None → `{ provider: undefined, ambiguous: false }`.
+ */
+export declare function detectProvider(opts: {
+    catalog: string[];
+    explicit?: string;
+}): {
+    provider?: string;
+    ambiguous: boolean;
+};
+/**
+ * Finds the best fully-qualified `provider/model-id` line for a given alias
+ * from the live catalog.
+ *
+ * Selection rules:
+ * 1. Only lines starting with `${provider}/` whose remainder starts with the
+ *    family token are candidates.
+ * 2. Non-canonical variants (`-fast`, `-thinking`, `-mini`, `-latest`) are
+ *    excluded unless no canonical candidates remain.
+ * 3. Among remaining candidates, the one with the highest parsed version wins.
+ *
+ * Returns `undefined` when no matching line exists.
+ */
+export declare function resolveAlias(provider: string, alias: ModelAlias, catalog: string[]): string | undefined;
+/**
+ * Resolves each role's model string to a fully-qualified opencode id or
+ * `undefined` (meaning: omit `model:` and inherit the session model).
+ *
+ * - Already fully-qualified values (contain `/`) pass through unchanged.
+ * - Known aliases are resolved via the live catalog + provider detection.
+ * - Unknown bare strings (not an alias, no `/`) → `undefined` + warning.
+ * - When provider detection is ambiguous or yields nothing → `undefined` +
+ *   one combined warning asking the user to pass `--opencode-provider <id>`
+ *   or fully-qualified `--models`.
+ */
+export declare function resolveOpencodeModels(roleModels: Record<Role, string>, opts: {
+    catalog: string[];
+    explicitProvider?: string;
+}): {
+    resolved: Record<Role, string | undefined>;
+    warnings: string[];
+};
+/**
+ * Runs `opencode models` and returns the parsed catalog. Returns an empty
+ * array on any error (binary absent, non-zero exit, timeout, etc.).
+ */
+export declare function loadOpencodeCatalog(): string[];

package/dist/opencode.js

@@ -0,0 +1,200 @@
+import { execFileSync } from "node:child_process";
+import { isModelAlias } from "./models.js";
+// ---------------------------------------------------------------------------
+// Pure catalog helpers (unit-testable without shell access)
+// ---------------------------------------------------------------------------
+/**
+ * Splits raw `opencode models` stdout into a list of trimmed non-empty lines,
+ * each of the form `provider/model-id`.
+ */
+export function parseOpencodeCatalog(stdout) {
+    return stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+/**
+ * Returns the provider id: the substring before the first `/`.
+ * e.g. `github-copilot/claude-sonnet-4.6` → `github-copilot`
+ *      `openrouter/anthropic/claude-sonnet-4.6` → `openrouter`
+ */
+export function providerOf(modelLine) {
+    return modelLine.slice(0, modelLine.indexOf("/"));
+}
+/**
+ * Infers which provider to use for alias resolution.
+ *
+ * - If `explicit` is given, it is returned as-is (no catalog check).
+ * - Otherwise the catalog is scanned for providers that offer at least one
+ *   model whose id segment (the part after `provider/`) starts with `claude-`.
+ *   Exactly one such provider → use it.
+ *   More than one → `{ provider: undefined, ambiguous: true }`.
+ *   None → `{ provider: undefined, ambiguous: false }`.
+ */
+export function detectProvider(opts) {
+    if (opts.explicit !== undefined) {
+        return { provider: opts.explicit, ambiguous: false };
+    }
+    const providers = new Set();
+    for (const line of opts.catalog) {
+        if (line.indexOf("/") <= 0)
+            continue;
+        const provider = providerOf(line);
+        const remainder = line.slice(provider.length + 1);
+        if (remainder.startsWith("claude-")) {
+            providers.add(provider);
+        }
+    }
+    if (providers.size === 1) {
+        return { provider: [...providers][0], ambiguous: false };
+    }
+    if (providers.size > 1) {
+        return { provider: undefined, ambiguous: true };
+    }
+    return { provider: undefined, ambiguous: false };
+}
+// Tags that mark non-canonical variants to skip when better options exist.
+const NON_CANONICAL_MARKERS = ["-fast", "-thinking", "-mini", "-latest"];
+function isNonCanonical(idSegment) {
+    return NON_CANONICAL_MARKERS.some((marker) => idSegment.endsWith(marker) || idSegment.includes(marker + "-"));
+}
+/** Parses the numeric version from a model id after removing the family token prefix. */
+function parseVersion(idSegment, familyToken) {
+    const suffix = idSegment.slice(familyToken.length);
+    // Split on `.` and `-`, keep only numeric parts.
+    return suffix
+        .split(/[.\-]/)
+        .filter((p) => /^\d+$/.test(p))
+        .map(Number);
+}
+function compareVersions(a, b) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    return 0;
+}
+const FAMILY_TOKENS = {
+    sonnet: "claude-sonnet",
+    opus: "claude-opus",
+    haiku: "claude-haiku",
+};
+/**
+ * Finds the best fully-qualified `provider/model-id` line for a given alias
+ * from the live catalog.
+ *
+ * Selection rules:
+ * 1. Only lines starting with `${provider}/` whose remainder starts with the
+ *    family token are candidates.
+ * 2. Non-canonical variants (`-fast`, `-thinking`, `-mini`, `-latest`) are
+ *    excluded unless no canonical candidates remain.
+ * 3. Among remaining candidates, the one with the highest parsed version wins.
+ *
+ * Returns `undefined` when no matching line exists.
+ */
+export function resolveAlias(provider, alias, catalog) {
+    const familyToken = FAMILY_TOKENS[alias];
+    const prefix = `${provider}/`;
+    const allCandidates = catalog.filter((line) => {
+        if (!line.startsWith(prefix))
+            return false;
+        const remainder = line.slice(prefix.length);
+        return remainder.startsWith(familyToken);
+    });
+    if (allCandidates.length === 0)
+        return undefined;
+    const canonical = allCandidates.filter((line) => !isNonCanonical(line.slice(prefix.length)));
+    const candidates = canonical.length > 0 ? canonical : allCandidates;
+    let best;
+    let bestVersion = [];
+    for (const line of candidates) {
+        const remainder = line.slice(prefix.length);
+        const version = parseVersion(remainder, familyToken);
+        if (best === undefined || compareVersions(version, bestVersion) > 0) {
+            best = line;
+            bestVersion = version;
+        }
+    }
+    return best;
+}
+/**
+ * Resolves each role's model string to a fully-qualified opencode id or
+ * `undefined` (meaning: omit `model:` and inherit the session model).
+ *
+ * - Already fully-qualified values (contain `/`) pass through unchanged.
+ * - Known aliases are resolved via the live catalog + provider detection.
+ * - Unknown bare strings (not an alias, no `/`) → `undefined` + warning.
+ * - When provider detection is ambiguous or yields nothing → `undefined` +
+ *   one combined warning asking the user to pass `--opencode-provider <id>`
+ *   or fully-qualified `--models`.
+ */
+export function resolveOpencodeModels(roleModels, opts) {
+    const { catalog, explicitProvider } = opts;
+    const resolved = {};
+    const warnings = [];
+    // Lazily detect provider once, shared across all roles.
+    let providerResult;
+    for (const [role, model] of Object.entries(roleModels)) {
+        if (model.includes("/")) {
+            // Already fully qualified — pass through.
+            resolved[role] = model;
+            continue;
+        }
+        if (!isModelAlias(model)) {
+            resolved[role] = undefined;
+            warnings.push(`Role "${role}": "${model}" is not a known alias and has no provider prefix; model: will be omitted (inherits session model).`);
+            continue;
+        }
+        // Known alias — need provider.
+        if (providerResult === undefined) {
+            providerResult = detectProvider({
+                catalog,
+                explicit: explicitProvider,
+            });
+        }
+        if (providerResult.provider === undefined) {
+            // Warning will be added once after the loop.
+            resolved[role] = undefined;
+            continue;
+        }
+        const fq = resolveAlias(providerResult.provider, model, catalog);
+        if (fq === undefined) {
+            resolved[role] = undefined;
+            warnings.push(`Role "${role}": provider "${providerResult.provider}" has no "${model}" model in the catalog; model: will be omitted.`);
+        }
+        else {
+            resolved[role] = fq;
+        }
+    }
+    // Emit one combined warning for ambiguous / no-provider cases.
+    if (providerResult !== undefined && providerResult.provider === undefined) {
+        const msg = providerResult.ambiguous
+            ? `Multiple providers offer Claude models in the live catalog; cannot auto-detect. Pass --opencode-provider <id> or use fully-qualified --models (e.g. provider/model-id) per role to resolve aliases.`
+            : `No provider offering Claude models found in the live catalog. Pass --opencode-provider <id> or use fully-qualified --models (e.g. provider/model-id) per role to resolve aliases.`;
+        warnings.push(msg);
+    }
+    return { resolved, warnings };
+}
+// ---------------------------------------------------------------------------
+// Impure shell-out (kept tiny and free of logic so tests avoid it)
+// ---------------------------------------------------------------------------
+/**
+ * Runs `opencode models` and returns the parsed catalog. Returns an empty
+ * array on any error (binary absent, non-zero exit, timeout, etc.).
+ */
+export function loadOpencodeCatalog() {
+    try {
+        const stdout = execFileSync("opencode", ["models"], {
+            encoding: "utf8",
+            timeout: 10_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return parseOpencodeCatalog(stdout);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/uninstall.js

@@ -81,6 +81,8 @@ const PRUNE_CANDIDATES = [
     join(".agents", "skills", "orchestrator-workflow"),
     join(".agents", "skills"),
     ".agents",
+    join(".opencode", "skills", "orchestrator-workflow"),
+    join(".opencode", "skills"),
     join(".opencode", "agents"),
     ".opencode",
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Installer for an orchestrator-led agent workflow: .ai/ run state, an AGENTS.md policy section, and per-harness subagent definitions for Claude Code, OpenAI Codex, and opencode",
   "main": "dist/index.js",
   "type": "module",
@@ -51,7 +51,7 @@
     "@types/inquirer": "^9.0.7",
     "@types/node": "^20.11.0",
     "prettier": "^3.8.1",
-    "tsx": "^4.19.3",
+    "tsx": "^4.22.4",
     "typescript": "^5.3.3",
     "vitest": "^4.1.6"
   }