orchestrator-workflow 0.1.0

package/assets/templates/04-implementation-summary.md

@@ -0,0 +1,33 @@
+# Implementation Summary
+
+## Status
+
+not_started | in_progress | done | partial | blocked
+
+## Completed Tasks
+
+- <!-- T-001 -->
+
+## Changed Files
+
+| File | Reason |
+|---|---|
+| <!-- path --> | <!-- reason --> |
+
+## Test Evidence
+
+### Executed
+
+- <!-- command/result -->
+
+### Added or Updated
+
+- <!-- test file -->
+
+### Not Executed
+
+<!-- Explain why, if applicable. -->
+
+## Risks / Notes
+
+- <!-- note -->

package/assets/templates/05-review-findings.md

@@ -0,0 +1,23 @@
+# Review Findings
+
+## Review Summary
+
+<!-- Short summary. -->
+
+## Findings
+
+| Severity | Category | Description | Suggested Fix | Decision |
+|---|---|---|---|---|
+| low/medium/high/critical | correctness/architecture/security/tests/maintainability/performance/docs | <!-- finding --> | <!-- fix --> | accepted/fix/defer/reject |
+
+## Missing Tests
+
+- <!-- missing test -->
+
+## Residual Risks
+
+- <!-- risk -->
+
+## Acceptance Recommendation
+
+accept | accept_with_notes | fix_required | reject

package/assets/templates/06-handoff.md

@@ -0,0 +1,25 @@
+# Operator Handoff
+
+## Summary
+
+<!-- What changed? -->
+
+## Why
+
+<!-- Why was this approach chosen? -->
+
+## Verification
+
+- <!-- tests/checks performed -->
+
+## Known Risks
+
+- <!-- risk or none -->
+
+## Follow-Ups
+
+- <!-- next steps or none -->
+
+## Final Status
+
+accepted | accepted_with_notes | needs_followup | blocked

package/dist/assets.d.ts

@@ -0,0 +1,17 @@
+import type { Role } from "./models.js";
+/** Resolves from both src/ (tsx dev) and dist/ (built) to the package root. */
+export declare const ASSETS_DIR: string;
+export declare const PACKAGE_VERSION: string;
+export declare function readAsset(relativePath: string): string;
+export declare function listTemplateNames(): string[];
+export interface AgentAsset {
+    name: string;
+    description: string;
+    body: string;
+}
+/**
+ * The agent assets are the single source of truth for the role prompts. They
+ * carry a minimal `name` + `description` frontmatter; the harness-specific
+ * frontmatter (model, mode) is composed at install time.
+ */
+export declare function readAgentAsset(role: Role): AgentAsset;

package/dist/assets.js

@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Resolves from both src/ (tsx dev) and dist/ (built) to the package root. */
+export const ASSETS_DIR = fileURLToPath(new URL("../assets/", import.meta.url));
+export const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export function readAsset(relativePath) {
+    return readFileSync(join(ASSETS_DIR, relativePath), "utf8");
+}
+export function listTemplateNames() {
+    return readdirSync(join(ASSETS_DIR, "templates"))
+        .filter((name) => name.endsWith(".md"))
+        .sort();
+}
+/**
+ * The agent assets are the single source of truth for the role prompts. They
+ * carry a minimal `name` + `description` frontmatter; the harness-specific
+ * frontmatter (model, mode) is composed at install time.
+ */
+export function readAgentAsset(role) {
+    const raw = readAsset(join("agents", `${role}.md`));
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n+([\s\S]*)$/);
+    if (!match) {
+        throw new Error(`Agent asset for "${role}" has no frontmatter block`);
+    }
+    const [, frontmatter, body] = match;
+    const name = frontmatter.match(/^name: (.+)$/m)?.[1]?.trim();
+    const descriptionRaw = frontmatter.match(/^description: (.+)$/m)?.[1]?.trim();
+    if (!name || !descriptionRaw) {
+        throw new Error(`Agent asset for "${role}" is missing name or description`);
+    }
+    const description = descriptionRaw.replace(/^"(.*)"$/, "$1");
+    return { name, description, body };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { Command } from "commander";
+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 { readInstalledManifest, runInit } from "./init.js";
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function promptHarnesses(detected, installed) {
+    const known = [...new Set([...detected, ...installed])];
+    const preselected = known.length > 0 ? known : ["claude"];
+    const { harnesses } = await inquirer.prompt([
+        {
+            type: "checkbox",
+            name: "harnesses",
+            message: "Install adapters for which harnesses?",
+            choices: HARNESSES.map((harness) => ({
+                name: harness + (detected.includes(harness) ? " (detected)" : ""),
+                value: harness,
+                checked: preselected.includes(harness),
+            })),
+            validate: (selection) => selection.length > 0 || "Select at least one harness",
+        },
+    ]);
+    return harnesses;
+}
+async function promptModels(base) {
+    const models = { ...base };
+    for (const role of ROLES) {
+        const { choice } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "choice",
+                message: `Model for the ${role} subagent:`,
+                default: models[role],
+                choices: [
+                    ...MODEL_ALIASES.map((alias) => ({
+                        name: alias === DEFAULT_MODELS[role] ? `${alias} (default)` : alias,
+                        value: alias,
+                    })),
+                    { name: "custom model id", value: "__custom__" },
+                ],
+            },
+        ]);
+        if (choice === "__custom__") {
+            const { custom } = await inquirer.prompt([
+                {
+                    type: "input",
+                    name: "custom",
+                    message: `Custom model id for ${role}:`,
+                    validate: (value) => {
+                        try {
+                            assertValidModelId(value.trim());
+                            return true;
+                        }
+                        catch (error) {
+                            return error instanceof Error ? error.message : String(error);
+                        }
+                    },
+                },
+            ]);
+            models[role] = custom.trim();
+        }
+        else {
+            models[role] = choice;
+        }
+    }
+    return models;
+}
+const program = new Command();
+program
+    .name("orchestrator-workflow")
+    .description("Install an orchestrator-led agent workflow into a repository: .ai/ run state, an AGENTS.md policy section, and per-harness subagent definitions")
+    .version(PACKAGE_VERSION);
+program
+    .command("init")
+    .description("Install or refresh the workflow kit in a target repository")
+    .argument("[dir]", "target repository directory", ".")
+    .option("-y, --yes", "accept all defaults and skip prompts")
+    .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"')
+    .action(async (dir, opts) => {
+    const targetDir = resolve(dir);
+    if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
+        console.error(`Target is not a directory: ${targetDir}`);
+        process.exitCode = 1;
+        return;
+    }
+    const interactive = !opts.yes && isInteractive();
+    const detected = detectHarnesses(targetDir);
+    console.log(detected.length > 0
+        ? `Detected harness configs: ${detected.join(", ")}`
+        : "No existing harness configs detected");
+    // A previous install is the baseline; re-runs refresh it instead of
+    // resetting harnesses and models to the shipped defaults.
+    const previous = readInstalledManifest(targetDir);
+    if (previous) {
+        const version = previous.version || "unknown version";
+        const installedFor = previous.harnesses.length > 0
+            ? previous.harnesses.join(", ")
+            : "none recorded";
+        console.log(`Found existing install (${version.startsWith("unknown") ? version : `v${version}`}, harnesses: ${installedFor})`);
+    }
+    let harnesses;
+    if (opts.harness) {
+        harnesses = parseHarnessList(opts.harness);
+    }
+    else {
+        const installed = previous?.harnesses ?? [];
+        const fallback = [...new Set([...detected, ...installed])];
+        harnesses = interactive
+            ? await promptHarnesses(detected, installed)
+            : fallback.length > 0
+                ? fallback
+                : ["claude"];
+    }
+    let models = {
+        ...DEFAULT_MODELS,
+        ...(previous?.models ?? {}),
+    };
+    if (opts.models)
+        models = parseModelsSpec(opts.models, models);
+    if (interactive && !opts.models)
+        models = await promptModels(models);
+    const report = runInit({
+        targetDir,
+        harnesses,
+        models,
+        force: opts.force,
+    });
+    const show = (label, paths) => {
+        if (paths.length === 0)
+            return;
+        console.log(`${label}:`);
+        for (const path of paths)
+            console.log(`  ${path}`);
+    };
+    show("Created", report.written);
+    show("Updated", report.updated);
+    show("Unchanged", report.skipped);
+    show("Conflicts (local edits kept, re-run with --force to overwrite)", report.conflicted);
+    console.log(`\norchestrator-workflow v${PACKAGE_VERSION} installed for: ${harnesses.join(", ")}`);
+});
+program.parseAsync(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/detect.d.ts

@@ -0,0 +1,9 @@
+export type Harness = "claude" | "codex" | "opencode";
+export declare const HARNESSES: Harness[];
+/**
+ * Best-effort detection of which harnesses a target repository already uses.
+ * AGENTS.md alone is deliberately not a signal: every supported harness can
+ * consume it, so it does not identify one.
+ */
+export declare function detectHarnesses(dir: string): Harness[];
+export declare function parseHarnessList(list: string): Harness[];

package/dist/detect.js

@@ -0,0 +1,39 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export const HARNESSES = ["claude", "codex", "opencode"];
+function anyExists(dir, names) {
+    return names.some((name) => existsSync(join(dir, name)));
+}
+/**
+ * Best-effort detection of which harnesses a target repository already uses.
+ * AGENTS.md alone is deliberately not a signal: every supported harness can
+ * consume it, so it does not identify one.
+ */
+export function detectHarnesses(dir) {
+    const detected = [];
+    if (anyExists(dir, [".claude", "CLAUDE.md"]))
+        detected.push("claude");
+    if (anyExists(dir, [".agents", ".codex"]))
+        detected.push("codex");
+    if (anyExists(dir, [".opencode", "opencode.json", "opencode.jsonc"])) {
+        detected.push("opencode");
+    }
+    return detected;
+}
+export function parseHarnessList(list) {
+    const parsed = [];
+    for (const entry of list.split(",")) {
+        const name = entry.trim().toLowerCase();
+        if (name === "")
+            continue;
+        if (!HARNESSES.includes(name)) {
+            throw new Error(`Unknown harness "${name}"; valid values: ${HARNESSES.join(", ")}`);
+        }
+        if (!parsed.includes(name))
+            parsed.push(name);
+    }
+    if (parsed.length === 0) {
+        throw new Error("--harness was given but contained no harness names");
+    }
+    return parsed;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { runInit } from "./init.js";
+export type { InitOptions } from "./init.js";
+export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
+export type { Harness } from "./detect.js";
+export { DEFAULT_MODELS, MODEL_ALIASES, ROLES, claudeModelValue, opencodeModelValue, parseModelsSpec, } from "./models.js";
+export type { ModelAlias, Role } from "./models.js";
+export type { Report } from "./writers.js";
+export { PACKAGE_VERSION } from "./assets.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { runInit } from "./init.js";
+export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
+export { DEFAULT_MODELS, MODEL_ALIASES, ROLES, claudeModelValue, opencodeModelValue, parseModelsSpec, } from "./models.js";
+export { PACKAGE_VERSION } from "./assets.js";

package/dist/init.d.ts

@@ -0,0 +1,29 @@
+import type { Harness } from "./detect.js";
+import type { Role } from "./models.js";
+import type { Report } from "./writers.js";
+export interface InitOptions {
+    targetDir: string;
+    harnesses: Harness[];
+    models: Record<Role, string>;
+    force?: boolean;
+}
+export interface Manifest {
+    kit: string;
+    version: string;
+    harnesses: Harness[];
+    models: Record<Role, string>;
+    /**
+     * sha256 of every kit-owned file as installed. This is how a re-run tells
+     * "upstream changed, safe to update" apart from "user edited, conflict".
+     */
+    files: Record<string, string>;
+    installedAt: string;
+}
+/**
+ * Reads the manifest of a previous install, if any. Manifests can be written
+ * by hand (manual agent installs) or damaged, so every field is sanitized;
+ * anything invalid degrades to "no record" instead of crashing or leaking
+ * unvalidated values into generated frontmatter.
+ */
+export declare function readInstalledManifest(targetDir: string): Manifest | undefined;
+export declare function runInit(options: InitOptions): Report;

package/dist/init.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_VERSION, listTemplateNames, readAgentAsset, readAsset, } from "./assets.js";
+import { HARNESSES } from "./detect.js";
+import { ROLES, assertValidModelId, claudeModelValue, opencodeModelValue, } from "./models.js";
+import { emptyReport, ensureClaudeImport, installFile, upsertMarkerSection, } from "./writers.js";
+const SKILL_NAME = "orchestrator-workflow";
+const MANIFEST_PATH = join(".ai", "workflow", "manifest.json");
+function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/**
+ * Reads the manifest of a previous install, if any. Manifests can be written
+ * by hand (manual agent installs) or damaged, so every field is sanitized;
+ * anything invalid degrades to "no record" instead of crashing or leaking
+ * unvalidated values into generated frontmatter.
+ */
+export function readInstalledManifest(targetDir) {
+    const path = join(targetDir, MANIFEST_PATH);
+    if (!existsSync(path))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const candidate = raw;
+    if (candidate.kit !== SKILL_NAME)
+        return undefined;
+    const harnesses = (Array.isArray(candidate.harnesses) ? candidate.harnesses : []).filter((value) => HARNESSES.includes(value));
+    const models = {};
+    if (typeof candidate.models === "object" && candidate.models !== null) {
+        for (const role of ROLES) {
+            const value = candidate.models[role];
+            if (typeof value !== "string")
+                continue;
+            try {
+                assertValidModelId(value);
+                models[role] = value;
+            }
+            catch {
+                // Invalid model ids are dropped; the role falls back to defaults.
+            }
+        }
+    }
+    const files = {};
+    if (typeof candidate.files === "object" && candidate.files !== null) {
+        for (const [key, value] of Object.entries(candidate.files)) {
+            if (typeof value === "string")
+                files[key] = value;
+        }
+    }
+    return {
+        kit: SKILL_NAME,
+        version: typeof candidate.version === "string" ? candidate.version : "",
+        harnesses,
+        models: models,
+        files,
+        installedAt: typeof candidate.installedAt === "string" ? candidate.installedAt : "",
+    };
+}
+function yamlQuote(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function composeClaudeAgent(role, model) {
+    const asset = readAgentAsset(role);
+    return [
+        "---",
+        `name: ${asset.name}`,
+        `description: ${yamlQuote(asset.description)}`,
+        `model: ${claudeModelValue(model)}`,
+        "---",
+        "",
+        asset.body.trimEnd(),
+        "",
+    ].join("\n");
+}
+function composeOpencodeAgent(role, model) {
+    const asset = readAgentAsset(role);
+    return [
+        "---",
+        `description: ${yamlQuote(asset.description)}`,
+        "mode: subagent",
+        `model: ${opencodeModelValue(model)}`,
+        "---",
+        "",
+        asset.body.trimEnd(),
+        "",
+    ].join("\n");
+}
+export function runInit(options) {
+    const { targetDir } = options;
+    if (!existsSync(targetDir)) {
+        throw new Error(`Target directory does not exist: ${targetDir}`);
+    }
+    if (!statSync(targetDir).isDirectory()) {
+        throw new Error(`Target is not a directory: ${targetDir}`);
+    }
+    const force = options.force ?? false;
+    const report = emptyReport();
+    const previous = readInstalledManifest(targetDir);
+    const installedFiles = {};
+    /**
+     * Installs a kit-owned file. An unedited file (it still matches the hash
+     * recorded at install time) is updated in place when the kit content
+     * changed; a locally edited file is only overwritten with --force.
+     */
+    const installKitFile = (relativePath, content) => {
+        const path = join(targetDir, relativePath);
+        const recorded = previous?.files?.[relativePath];
+        if (existsSync(path)) {
+            const existing = readFileSync(path, "utf8");
+            const unedited = recorded !== undefined && sha256(existing) === recorded;
+            installFile(report, path, content, { force: force || unedited });
+            if (readFileSync(path, "utf8") === content) {
+                installedFiles[relativePath] = sha256(content);
+            }
+            else if (recorded !== undefined) {
+                // Conflicted: the user's edit stays, and so does the original record.
+                installedFiles[relativePath] = recorded;
+            }
+            return;
+        }
+        installFile(report, path, content, { force });
+        installedFiles[relativePath] = sha256(content);
+    };
+    for (const name of listTemplateNames()) {
+        installKitFile(join(".ai", "workflow", "templates", name), readAsset(join("templates", name)));
+    }
+    installKitFile(join(".ai", "runs", ".gitkeep"), "");
+    // Codex and opencode read AGENTS.md natively; Claude Code gets it via the
+    // CLAUDE.md import. The policy section is therefore installed regardless of
+    // the harness selection. AGENTS.md and CLAUDE.md are user-owned: only the
+    // fenced section and the import line are ever touched.
+    upsertMarkerSection(report, join(targetDir, "AGENTS.md"), readAsset("agents-md-section.md"));
+    const skill = readAsset(join("skill", "SKILL.md"));
+    if (options.harnesses.includes("claude")) {
+        installKitFile(join(".claude", "skills", SKILL_NAME, "SKILL.md"), skill);
+        for (const role of ROLES) {
+            installKitFile(join(".claude", "agents", `${role}.md`), composeClaudeAgent(role, options.models[role]));
+        }
+        ensureClaudeImport(report, join(targetDir, "CLAUDE.md"));
+    }
+    if (options.harnesses.includes("codex")) {
+        installKitFile(join(".agents", "skills", SKILL_NAME, "SKILL.md"), skill);
+    }
+    if (options.harnesses.includes("opencode")) {
+        for (const role of ROLES) {
+            installKitFile(join(".opencode", "agents", `${role}.md`), composeOpencodeAgent(role, options.models[role]));
+        }
+    }
+    // The manifest records applied state, so it is written last and only when
+    // something actually differs; a plain re-run stays a byte-for-byte no-op.
+    const desired = {
+        kit: SKILL_NAME,
+        version: PACKAGE_VERSION,
+        harnesses: [...options.harnesses].sort(),
+        models: options.models,
+        files: installedFiles,
+    };
+    const manifestPath = join(targetDir, MANIFEST_PATH);
+    if (previous &&
+        JSON.stringify({
+            kit: previous.kit,
+            version: previous.version,
+            harnesses: previous.harnesses,
+            models: previous.models,
+            files: previous.files,
+        }) === JSON.stringify(desired)) {
+        report.skipped.push(manifestPath);
+    }
+    else {
+        const manifest = {
+            ...desired,
+            installedAt: previous?.installedAt || new Date().toISOString(),
+        };
+        installFile(report, manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, {
+            force: true,
+        });
+    }
+    return report;
+}

package/dist/models.d.ts

@@ -0,0 +1,26 @@
+export type Role = "task-slicer" | "implementer" | "reviewer";
+export declare const ROLES: Role[];
+export type ModelAlias = "sonnet" | "opus" | "haiku";
+export declare const MODEL_ALIASES: ModelAlias[];
+/**
+ * Per-role defaults. The orchestrator itself runs on the session model and is
+ * deliberately not configured here.
+ */
+export declare const DEFAULT_MODELS: Record<Role, string>;
+export declare function isModelAlias(value: string): value is ModelAlias;
+/**
+ * Claude Code subagent frontmatter accepts the aliases directly as well as
+ * full model ids, so the chosen value passes through unchanged.
+ */
+export declare function claudeModelValue(model: string): string;
+export declare function opencodeModelValue(model: string): string;
+/**
+ * Model values are interpolated into YAML frontmatter as plain scalars;
+ * reject anything that could break out of that position.
+ */
+export declare function assertValidModelId(model: string): void;
+/**
+ * Parses a `--models` spec like `implementer=haiku,reviewer=opus` on top of
+ * the given base mapping. Unknown roles and empty values are rejected.
+ */
+export declare function parseModelsSpec(spec: string, base: Record<Role, string>): Record<Role, string>;

package/dist/models.js

@@ -0,0 +1,72 @@
+export const ROLES = ["task-slicer", "implementer", "reviewer"];
+export const MODEL_ALIASES = ["sonnet", "opus", "haiku"];
+/**
+ * Per-role defaults. The orchestrator itself runs on the session model and is
+ * deliberately not configured here.
+ */
+export const DEFAULT_MODELS = {
+    "task-slicer": "sonnet",
+    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);
+}
+/**
+ * Claude Code subagent frontmatter accepts the aliases directly as well as
+ * full model ids, so the chosen value passes through unchanged.
+ */
+export function claudeModelValue(model) {
+    return model;
+}
+export function opencodeModelValue(model) {
+    if (isModelAlias(model))
+        return OPENCODE_MODEL_IDS[model];
+    return model.includes("/") ? model : `anthropic/${model}`;
+}
+/**
+ * Model values are interpolated into YAML frontmatter as plain scalars;
+ * reject anything that could break out of that position.
+ */
+export function assertValidModelId(model) {
+    if (model.length === 0) {
+        throw new Error("Model id must not be empty");
+    }
+    if (/[:"'#\n\\]/.test(model) || model !== model.trim()) {
+        throw new Error(`Invalid model id "${model}"; expected an alias (${MODEL_ALIASES.join(", ")}) or a plain id like anthropic/claude-opus-4-8`);
+    }
+}
+/**
+ * Parses a `--models` spec like `implementer=haiku,reviewer=opus` on top of
+ * the given base mapping. Unknown roles and empty values are rejected.
+ */
+export function parseModelsSpec(spec, base) {
+    const result = { ...base };
+    for (const pair of spec.split(",")) {
+        const trimmed = pair.trim();
+        if (trimmed === "")
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq <= 0 || eq === trimmed.length - 1) {
+            throw new Error(`Invalid --models entry "${trimmed}"; expected role=model`);
+        }
+        const role = trimmed.slice(0, eq).trim();
+        const model = trimmed.slice(eq + 1).trim();
+        if (!ROLES.includes(role)) {
+            throw new Error(`Unknown role "${role}" in --models; valid roles: ${ROLES.join(", ")}`);
+        }
+        assertValidModelId(model);
+        result[role] = model;
+    }
+    return result;
+}