orchestrator-workflow 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to `orchestrator-workflow` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.0] - 2026-08-19
+
+### Added
+
+- `init` gains `--tiers`: renders an additional per-role subagent variant
+  file for each non-default effort tier, alongside the one default
+  (unsuffixed) agent file `--profile` already installs. Off by default, like
+  every optional pack in this kit; a plain re-run with no `--tiers` flag
+  keeps whatever the previous install had, the same override-vs-persist rule
+  already used for `--profile`/`--models`, and there is no interactive
+  prompt, tiers is opt-in via the flag only. `models.ts` adds `Tier`
+  (`low|medium|high|xhigh`), `ROLE_TIERS` (which tiers each role gets:
+  explorer/task-slicer `low,medium,high`; implementer all four;
+  reviewer `medium,high,xhigh`), `DEFAULT_TIER` (the tier each role's plain
+  file already corresponds to: `medium` for explorer/task-slicer/implementer,
+  `high` for reviewer, never rendered as its own variant since that would
+  both collide with and duplicate the default file), `TIER_DEFS` (tier ->
+  model class + requested effort), and `CLASS_MODELS` (model class -> model
+  alias: `small`->`haiku`, `medium`->`sonnet`, `large`->`opus`). The default
+  file for every role stays byte-identical to a tiers-off install (still
+  `manifest.models[role]`, no `effort:` key) whether or not `--tiers` is
+  passed, so the reviewer's `opus` default can never be silently downgraded
+  by this feature; a dedicated regression test pins that. Variant files are
+  named `<role>-<tier>.md`; with `--profile full` and tiers on, that is 4
+  default files plus 9 variants (13 total). Claude Code variants carry
+  `model: <class alias>` and `effort: <tier>` frontmatter (plus
+  `disallowedTools: Edit, Write, NotebookEdit` for the read-only roles, same
+  as the default file). opencode variants key off the resolved model's
+  family, not its provider prefix: a Claude-family id (any provider fronting
+  a `claude-`-named model, e.g. `anthropic/claude-...`,
+  `github-copilot/claude-...`, or the nested
+  `openrouter/anthropic/claude-...`) gets `variant: high`/`variant: max` for
+  the `high`/`xhigh` tiers only (`low`/`medium` collapse to no effort field,
+  a documented opencode `variant:` limitation, not a bug), Ollama or a provider-less
+  id gets no effort field, and every other non-Claude-family model gets a plain
+  `reasoningEffort: <tier>` line; the variant's `model:` line resolves
+  through the same live `opencode models` catalog lookup as the base
+  per-role model, keyed by the tier's model class instead of by role. A tier
+  whose class model cannot be resolved at all renders no variant file for
+  that class, not a file with the `model:` line simply omitted, and the CLI
+  warns once per unresolved class on stderr; this guard and its warning
+  are opencode-scoped only, since Claude Code variants resolve `model:` from
+  a plain alias and need no live catalog lookup. The chosen value is
+  recorded in a new `tiers` boolean on
+  `.ai/workflow/manifest.json`; a manifest written before tiers existed (no
+  `tiers` key) degrades to `false`, the same per-field-degradation style
+  already used for a missing `profile` field. Variant files flow through the
+  existing `installKitFile` hash ledger, so idempotence, conflict detection,
+  and `uninstall` all cover them automatically with no dedicated code.
+  Motivated by a harness capability probe (2026-08-19): Claude Code's
+  `effort:` subagent frontmatter is wire-verified to reach the model request
+  as `output_config.effort`, which is what makes rendering per-tier
+  frontmatter variants worth doing at all, but the same probe also found
+  that the `CLAUDE_CODE_EFFORT_LEVEL` environment variable always overrides
+  frontmatter `effort:` on every installed agent when set, tier variants and
+  default files alike; README's new "Effort tiers" section documents that
+  override explicitly as a warning, not a footnote. README documents the
+  flag, the role/tier table, the tier -> model class/effort table, and the
+  opencode provider behavior; `INSTALL-AGENT.md` documents `--tiers` in the
+  init question/example and the manifest JSON shape, and states the manual
+  fallback path does not render tier variants at all. A new, narrowly scoped
+  `docs-consistency.test.ts` check enumerates the README tier table against
+  `ROLE_TIERS`/`DEFAULT_TIER` directly, so a role or tier added to either
+  without a matching table update fails loudly. Both OKF bundle docs
+  touching the installer (`model-preselection.md`,
+  `install-fence-mechanics.md`) are re-verified and re-stamped.
+
 ## [0.18.0] - 2026-08-18
 
 ### Changed

package/INSTALL-AGENT.md

@@ -22,19 +22,22 @@ which is mutable. For a stable audit, pin the URL to a commit SHA instead
    below).
 2. **Ask you, not guess**: which harnesses should get adapters, which role
    profile to install (`full` — every role, or `minimal` — implementer and
-   reviewer only; the reviewer is never optional), and which model each
-   installed subagent role should use. Suggested defaults: profile `full`;
-   explorer `sonnet`, task-slicer `sonnet`, implementer `sonnet`, reviewer
-   `opus`.
+   reviewer only; the reviewer is never optional), which model each
+   installed subagent role should use, and whether to also render effort-tier
+   subagent variants (`--tiers`; off by default, no per-tier model prompt
+   since tier models are chosen automatically). Suggested defaults: profile
+   `full`; explorer `sonnet`, task-slicer `sonnet`, implementer `sonnet`,
+   reviewer `opus`; tiers off.
 3. **Run the non-interactive installer** with your answers:
-   `npx orchestrator-workflow init --yes --harness ... --profile ... --models ...`.
+   `npx orchestrator-workflow init --yes --harness ... --profile ... --models ... [--tiers]`.
    If the installer reports conflicts with locally edited files, the agent
    shows them to you and asks before any `--force` re-run.
 4. **Manual fallback only when npx or the registry is unavailable**: create
    the same files by hand from this repository's `assets/` directory,
    following the byte-precise rules in step 4 below.
 5. **Report back**: which harnesses were installed, which profile and model
-   each role uses, and any conflicts left in place.
+   each role uses, whether effort-tier variants were rendered, and any
+   conflicts left in place.
 
 ### Write surface
 
@@ -58,7 +61,16 @@ The per-role agent files above are the `full` profile (the default); the
 `minimal` profile writes only the `implementer` and `reviewer` files for
 Claude Code and opencode and skips `task-slicer` and `explorer` entirely.
 Codex has no per-role files, so the profile choice does not change what it
-gets. Nothing else in the repository is modified. Locally edited files are
+gets. When `--tiers` is on, each installed Claude Code and opencode role
+additionally gets one subagent file per non-default effort tier, named
+`<role>-<tier>.md` (never a file for the role's own default tier, which
+would collide with the plain `<role>.md` file); see the package README's
+"Effort tiers" section for the full role/tier table and the per-harness
+frontmatter shape. `--tiers` is off by default and has no interactive
+prompt equivalent in the manual fallback below (nor does its negation,
+`--no-tiers`): the automated installer is the only path that renders
+tier-variant files; a manual scaffold (step 4) does not cover them.
+Nothing else in the repository is modified. Locally edited files are
 reported as conflicts and left alone, never overwritten silently; the
 exceptions are the kit-owned surfaces: `.ai/workflow/manifest.json` (the
 kit's state file, rewritten whenever the applied state changes) and the
@@ -90,6 +102,10 @@ steps in the repository you were asked to install into.
      `sonnet`, reviewer `opus`. Accept the aliases `sonnet`, `opus`,
      `haiku` or a full model id. Skip asking about a role's model when the
      chosen profile does not install that role.
+   - Whether to also render effort-tier subagent variants (`--tiers`)?
+     Default: off. There is no per-tier model question: tier models are
+     chosen automatically from the tier (see the package README's "Effort
+     tiers" section for the role/tier table and the model-class mapping).
 
 3. Run the non-interactive installer with the operator's answers:
 
@@ -97,16 +113,25 @@ steps in the repository you were asked to install into.
    npx orchestrator-workflow init --yes \
      --harness <claude,codex,opencode> \
      --profile <minimal|full> \
-     --models "explorer=<model>,task-slicer=<model>,implementer=<model>,reviewer=<model>"
+     --models "explorer=<model>,task-slicer=<model>,implementer=<model>,reviewer=<model>" \
+     [--tiers | --no-tiers]
    ```
 
    Omit `--profile` to keep `full` (or, on a re-run, whatever profile was
    installed previously); omit the models for roles the chosen profile does
-   not install. If the command reports conflicts, show them to the operator
+   not install. Add `--tiers` only when the operator asked for tier
+   variants; add `--no-tiers` only when the operator explicitly wants them
+   turned off on a re-run that previously had them on; omit both to keep
+   tiers off on a fresh install, or whatever value was previously installed
+   on a re-run. If the command reports conflicts, show them to the operator
    and ask before re-running with --force.
 
 4. Only if npx or the registry is unavailable, scaffold manually from
-   https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow/assets
+   https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow/assets.
+   This manual path does not cover `--tiers`: it never renders
+   `<role>-<tier>.md` variant files, regardless of what the operator asked
+   for in step 2; tell the operator tier variants require the automated
+   installer (step 3).
 
    - `.ai/workflow/templates/00-goal.md` through `06-handoff.md` from
      `assets/templates/`, unchanged.
@@ -164,6 +189,7 @@ steps in the repository you were asked to install into.
        "version": "0.5.0",
        "harnesses": ["claude", "opencode"],
        "profile": "full",
+       "tiers": false,
        "models": {
          "explorer": "sonnet",
          "task-slicer": "sonnet",
@@ -177,11 +203,14 @@ steps in the repository you were asked to install into.
 
      Under `minimal`, `models` only needs the `implementer` and `reviewer`
      keys (the roles actually installed); the missing keys fall back to the
-     kit's defaults if the profile is later switched back to `full`.
+     kit's defaults if the profile is later switched back to `full`. `tiers`
+     is always `false` from this manual path, since it never renders
+     tier-variant files (see step 4's opening note above).
 
      A manual install may leave the `files` hash map empty; a later `init`
      run then treats existing kit files conservatively and reports conflicts
      rather than overwriting them.
 
 5. Report back to the operator: which harnesses were installed, which model
-   each role uses, and any conflicts that were left in place.
+   each role uses, whether effort-tier variants were rendered, and any
+   conflicts that were left in place.

package/README.md

@@ -195,6 +195,103 @@ Nested-path providers like `openrouter` (whose ids look like
 be supplied as a fully-qualified `--models` entry, e.g.
 `reviewer=openrouter/anthropic/claude-opus-4.8`.
 
+## Effort tiers
+
+`--tiers` renders an additional per-role subagent definition for each
+non-default effort tier, alongside the one default (unsuffixed) agent file
+`--profile` already installs. Each tier variant is a standalone subagent
+definition, not a modification of the default file: the default file
+(`<role>.md`) stays byte-identical to what a tiers-off install already
+produces (still `manifest.models[role]`, no `effort:` key), and each variant
+lives next to it as `<role>-<tier>.md`.
+
+Default off, like every optional pack in this kit: a fresh install renders
+no variant files unless asked. `--tiers` turns the feature on for that run,
+`--no-tiers` turns it off; a plain re-run with neither flag keeps whatever
+the previous install had, the same override-vs-persist rule already used
+for `--profile` and `--models`. There is no interactive prompt for it:
+`tiers` is opt-in/off via the flags only.
+
+```bash
+npx orchestrator-workflow init --tiers --yes
+```
+
+Turning tiers back off with `--no-tiers` after having them on follows the
+same pattern as a `full` → `minimal` profile downgrade: `init` prints a note
+naming the now-untracked `<role>-<tier>.md` variant files and how to remove
+them, rather than deleting them or leaving the leftover unexplained.
+
+**Which tiers each role gets.** A role never gets a variant file for its own
+default tier: that would collide with, and duplicate, the default file.
+
+| Role | Tiers available | Default tier (no variant file) |
+|---|---|---|
+| explorer | low, medium, high | medium |
+| task-slicer | low, medium, high | medium |
+| implementer | low, medium, high, xhigh | medium |
+| reviewer | medium, high, xhigh | high |
+
+With `--profile full` and every tier rendered, that is 4 default files plus
+9 variant files: 13 files total per harness.
+
+**Tier → model class → effort.** Each tier resolves to a model class and an
+effort value:
+
+| Tier | Model class | Model alias | Effort requested |
+|---|---|---|---|
+| low | small | `haiku` | `low` |
+| medium | medium | `sonnet` | `medium` |
+| high | medium | `sonnet` | `high` |
+| xhigh | large | `opus` | `xhigh` |
+
+Claude Code variants carry both a `model:` line (the class's alias) and an
+`effort: <tier>` line in frontmatter. Read-only roles (explorer, reviewer)
+keep `disallowedTools: Edit, Write, NotebookEdit` on their variants too.
+
+**opencode variants key off the resolved model's family, not its provider
+prefix**, since opencode's effort surface is not uniform across model
+families:
+
+- **Claude-family models** (any resolved id whose provider is
+  `anthropic/`, or whose segment after the provider prefix contains
+  `claude-`, which covers `anthropic/claude-...` as well as a Claude model
+  fronted by a different provider, e.g. `github-copilot/claude-sonnet-4.6`
+  or the nested `openrouter/anthropic/claude-opus-4.8`): only `high` and
+  `xhigh` get an effort field, as `variant: high` and `variant: max`
+  respectively; `low` and `medium` collapse to no effort field at all,
+  since opencode's `variant:` option does not distinguish an effort below
+  `high`. This collapse is deliberate and documented, not a bug: a
+  `low`/`medium` variant on a Claude-family model still gets its class's
+  `model:` line, just no `variant:` line.
+- **Ollama, or an id with no provider prefix**: no effort field at all.
+  There is no known effort passthrough for Ollama, and an id with no `/`
+  resolves to no provider to key the decision on.
+- **Every other non-Claude-family model**: a plain `reasoningEffort: <tier>`
+  line, `xhigh` included (opencode's built-in OpenAI-style variants
+  document an `xhigh` reasoning effort).
+
+The variant's `model:` line is resolved the same way the base per-role model
+is (an `opencode models` catalog lookup against the auto-detected or
+`--opencode-provider`-specified provider), just keyed by the tier's model
+class instead of by role. When that lookup cannot resolve a model for a
+class, the CLI warns once on stderr and **no variant file is rendered for
+that class at all**, not a file with a missing `model:` line: a variant
+with no resolved model would carry neither a `model:` nor an effort line, an
+indistinguishable no-op duplicate of the base file with no ledger entry to
+compare it against, so `init` skips writing it entirely. This guard and its
+warning are opencode-scoped only; Claude Code variants resolve `model:` from
+a plain alias (`haiku`/`sonnet`/`opus`) and need no live catalog lookup, so
+they are unaffected.
+
+**Warning: `CLAUDE_CODE_EFFORT_LEVEL` overrides every agent's frontmatter
+`effort:`, tier variants included.** Claude Code's `effort:` frontmatter
+field does work: it reaches the model request as `output_config.effort`.
+But when the harness environment sets `CLAUDE_CODE_EFFORT_LEVEL`, that
+environment variable wins over the frontmatter `effort:` on every installed
+agent, tier variants and default files alike, not just the one this feature
+adds. Check for it before relying on a specific tier variant's requested
+effort actually taking effect.
+
 ## Ownership and re-runs
 
 `init` is idempotent: a second run changes nothing. The rules:
@@ -208,8 +305,9 @@ be supplied as a fully-qualified `--models` entry, e.g.
   updates files you never touched and reports files you edited as conflicts
   instead of overwriting them; `--force` overwrites those too.
 - `.ai/workflow/manifest.json` is the kit's state file. It records the applied
-  version, harnesses, role profile, models, and file hashes, and is rewritten
-  whenever that state changes; do not edit it by hand.
+  version, harnesses, role profile, models, the `--tiers` flag, and file
+  hashes, and is rewritten whenever that state changes; do not edit it by
+  hand.
 
 ## Uninstall
 

package/dist/cli.js

@@ -5,8 +5,8 @@ import { Command } from "commander";
 import inquirer from "inquirer";
 import { PACKAGE_VERSION } from "./assets.js";
 import { HARNESSES, detectHarnesses, parseHarnessList } from "./detect.js";
-import { DEFAULT_MODELS, DEFAULT_PROFILE, MODEL_ALIASES, PROFILES, assertValidModelId, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
-import { loadOpencodeCatalog, resolveOpencodeModels } from "./opencode.js";
+import { CLASS_MODELS, DEFAULT_MODELS, DEFAULT_PROFILE, MODEL_ALIASES, MODEL_CLASSES, PROFILES, assertValidModelId, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
+import { detectProvider, loadOpencodeCatalog, resolveAlias, resolveOpencodeModels, } from "./opencode.js";
 import { readInstalledManifest, runInit } from "./init.js";
 import { runUninstall } from "./uninstall.js";
 function isInteractive() {
@@ -125,6 +125,8 @@ program
     .option("--models <spec>", 'per-role model overrides, e.g. "implementer=sonnet,reviewer=opus"')
     .option("--profile <profile>", `subagent role profile (${PROFILES.join(", ")}); default: full, or the previously installed profile on a re-run`)
     .option("--opencode-provider <id>", "opencode provider id for alias resolution (e.g. github-copilot); auto-detected when omitted")
+    .option("--tiers", "also render per-role effort-tier subagent variants (<role>-<tier>.md); default: off, or the previously installed value on a re-run")
+    .option("--no-tiers", "explicitly turn effort-tier subagent variants off, overriding a previously installed --tiers value")
     .action(async (dir, opts) => {
     const targetDir = requireDirectory(dir);
     if (!targetDir)
@@ -148,7 +150,7 @@ program
         const installedFor = previous.harnesses.length > 0
             ? previous.harnesses.join(", ")
             : "none recorded";
-        console.log(`Found existing install (${version.startsWith("unknown") ? version : `v${version}`}, harnesses: ${installedFor}, profile: ${previous.profile})`);
+        console.log(`Found existing install (${version.startsWith("unknown") ? version : `v${version}`}, harnesses: ${installedFor}, profile: ${previous.profile}, tiers: ${previous.tiers})`);
     }
     let harnesses;
     if (opts.harness) {
@@ -184,10 +186,22 @@ program
         models = parseModelsSpec(opts.models, models);
     if (interactive && !opts.models)
         models = await promptModels(models, rolesForProfile(profile));
+    // Explicit --tiers/--no-tiers always override; a plain re-run (neither
+    // flag passed) keeps whatever the previous install had (default false
+    // for a fresh install), same override-vs-persist rule as
+    // --profile/--models above. commander's negatable-option pairing
+    // (--tiers / --no-tiers declared under the same "tiers" option name)
+    // resolves opts.tiers to `true` when --tiers is passed, `false` when
+    // --no-tiers is passed, and `undefined` when neither is passed; the
+    // CLI re-run test below verifies this against the installed commander
+    // version rather than assuming it. No interactive prompt: tiers is
+    // opt-in/off via the flags only.
+    const tiers = opts.tiers ?? previous?.tiers ?? false;
     // 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;
+    let opencodeClassModels;
     if (harnesses.includes("opencode")) {
         const catalog = loadOpencodeCatalog();
         const { resolved, warnings } = resolveOpencodeModels(models, {
@@ -198,6 +212,37 @@ program
         for (const w of warnings) {
             process.stderr.write(`Warning: ${w}\n`);
         }
+        if (tiers) {
+            const providerResult = detectProvider({
+                catalog,
+                explicit: opts.opencodeProvider,
+            });
+            opencodeClassModels = {};
+            for (const modelClass of MODEL_CLASSES) {
+                const alias = CLASS_MODELS[modelClass];
+                const resolved = providerResult.provider
+                    ? resolveAlias(providerResult.provider, alias, catalog)
+                    : undefined;
+                opencodeClassModels[modelClass] = resolved;
+                if (resolved !== undefined)
+                    continue;
+                // One warning per unresolved model class: without it, every
+                // effort-tier variant keyed to this class is silently skipped
+                // (init.ts skips the variant write entirely when the class
+                // model is unresolved), with nothing on stderr saying why.
+                const reason = providerResult.provider
+                    ? `provider "${providerResult.provider}" has no "${alias}" model in the catalog`
+                    : providerResult.ambiguous
+                        ? `multiple providers offer Claude models in the live catalog; cannot auto-detect`
+                        : `no provider offering Claude models found in the live catalog`;
+                // States the real effect (no variant file at all, not just a
+                // missing model: line, since init.ts skips the write entirely
+                // when the class never resolves) and the real scope (opencode
+                // only: Claude Code variants resolve model: from a plain alias
+                // and need no live catalog lookup, so they are unaffected).
+                process.stderr.write(`Warning: Tier model class "${modelClass}" (alias "${alias}") could not be resolved to an opencode model id (${reason}); no opencode effort-tier variant files will be rendered for this class (Claude Code variants are unaffected).\n`);
+            }
+        }
     }
     const report = runInit({
         targetDir,
@@ -206,6 +251,8 @@ program
         profile,
         force: opts.force,
         opencodeModels,
+        tiers,
+        opencodeClassModels,
     });
     showPaths("Created", report.written);
     showPaths("Updated", report.updated);
@@ -213,7 +260,7 @@ program
     showPaths("Conflicts (local edits kept, re-run with --force to overwrite)", report.conflicted);
     for (const note of report.notes)
         console.log(note);
-    console.log(`\norchestrator-workflow v${PACKAGE_VERSION} installed for: ${harnesses.join(", ")} (profile: ${profile})`);
+    console.log(`\norchestrator-workflow v${PACKAGE_VERSION} installed for: ${harnesses.join(", ")} (profile: ${profile}, tiers: ${tiers})`);
 });
 program
     .command("uninstall")

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { runUninstall } from "./uninstall.js";
 export type { UninstallReport } from "./uninstall.js";
 export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
 export type { Harness } from "./detect.js";
-export { DEFAULT_MODELS, DEFAULT_PROFILE, MODEL_ALIASES, PROFILES, ROLES, claudeModelValue, isProfile, opencodeModelValue, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
-export type { ModelAlias, Profile, Role } from "./models.js";
+export { CLASS_MODELS, DEFAULT_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, MODEL_ALIASES, MODEL_CLASSES, PROFILES, ROLES, ROLE_TIERS, TIER_DEFS, claudeModelValue, isProfile, opencodeModelValue, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
+export type { ModelAlias, ModelClass, Profile, Role, Tier } from "./models.js";
 export type { Report } from "./writers.js";
 export { PACKAGE_VERSION } from "./assets.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { runInit } from "./init.js";
 export { runUninstall } from "./uninstall.js";
 export { detectHarnesses, parseHarnessList, HARNESSES } from "./detect.js";
-export { DEFAULT_MODELS, DEFAULT_PROFILE, MODEL_ALIASES, PROFILES, ROLES, claudeModelValue, isProfile, opencodeModelValue, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
+export { CLASS_MODELS, DEFAULT_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, MODEL_ALIASES, MODEL_CLASSES, PROFILES, ROLES, ROLE_TIERS, TIER_DEFS, claudeModelValue, isProfile, opencodeModelValue, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
 export { PACKAGE_VERSION } from "./assets.js";

package/dist/init.d.ts

@@ -1,5 +1,5 @@
 import type { Harness } from "./detect.js";
-import type { Profile, Role } from "./models.js";
+import type { ModelClass, Profile, Role } from "./models.js";
 import type { Report } from "./writers.js";
 export interface InitOptions {
     targetDir: string;
@@ -20,6 +20,22 @@ export interface InitOptions {
      * aliases, producing the same inherit-session-model behaviour for bare inputs.
      */
     opencodeModels?: Record<Role, string | undefined>;
+    /**
+     * Renders additional per-role effort-tier subagent variants
+     * (`<role>-<tier>.md`) alongside the default agent file. Defaults to
+     * `false` (today's unconditional behavior: only the default file), so
+     * existing callers that do not pass this field see no change.
+     */
+    tiers?: boolean;
+    /**
+     * Resolved fully-qualified opencode model ids per tier's model class
+     * (`small`/`medium`/`large`), or `undefined` to omit the `model:` line for
+     * that variant. Only consulted when `tiers` is true and the `opencode`
+     * harness is selected; mirrors `opencodeModels` but keyed by model class
+     * instead of role, since a tier variant's model is chosen by class, not
+     * by the role's own preselected model.
+     */
+    opencodeClassModels?: Record<ModelClass, string | undefined>;
 }
 export interface Manifest {
     kit: string;
@@ -28,6 +44,8 @@ export interface Manifest {
     models: Record<Role, string>;
     /** Which subagent roles were installed: `"minimal"` or `"full"`. */
     profile: Profile;
+    /** Whether per-role effort-tier subagent variants were rendered. */
+    tiers: boolean;
     /**
      * 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".

package/dist/init.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, normalize, sep } from "node:path";
 import { PACKAGE_VERSION, listTemplateNames, readAgentAsset, readAsset, } from "./assets.js";
 import { HARNESSES } from "./detect.js";
-import { DEFAULT_PROFILE, READ_ONLY_ROLES, ROLES, assertValidModelId, claudeModelValue, isProfile, opencodeModelValue, rolesForProfile, } from "./models.js";
+import { CLASS_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, READ_ONLY_ROLES, ROLES, ROLE_TIERS, TIER_DEFS, assertValidModelId, claudeModelValue, isProfile, opencodeModelValue, rolesForProfile, } from "./models.js";
 import { emptyReport, ensureClaudeImport, installFile, upsertMarkerSection, } from "./writers.js";
 const SKILL_NAME = "orchestrator-workflow";
 const MANIFEST_PATH = join(".ai", "workflow", "manifest.json");
@@ -76,12 +76,18 @@ export function readInstalledManifest(targetDir) {
     const profile = typeof candidate.profile === "string" && isProfile(candidate.profile)
         ? candidate.profile
         : DEFAULT_PROFILE;
+    // A manifest written before tiers existed carries no `tiers` field; that
+    // install never rendered variant files, so it degrades to `false` here
+    // (the same per-field-degradation style as `profile` above) rather than
+    // throwing on a legacy manifest.
+    const tiers = typeof candidate.tiers === "boolean" ? candidate.tiers : false;
     return {
         kit: SKILL_NAME,
         version: typeof candidate.version === "string" ? candidate.version : "",
         harnesses,
         models: models,
         profile,
+        tiers,
         files,
         installedAt: typeof candidate.installedAt === "string" ? candidate.installedAt : "",
     };
@@ -122,6 +128,98 @@ function composeOpencodeAgent(role, modelValue) {
     frontmatter.push("---");
     return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
 }
+function tierDescriptionSuffix(asset, tier) {
+    return `${asset.description} (Effort tier: ${tier}.)`;
+}
+/**
+ * Composes a tier-variant sibling of `composeClaudeAgent` (`<role>-<tier>.md`).
+ * The default-tier file is never rendered here (callers skip it via
+ * `DEFAULT_TIER`), so `composeClaudeAgent`'s own output stays byte-identical
+ * whether or not tiers are on.
+ */
+function composeClaudeAgentVariant(role, tier) {
+    const asset = readAgentAsset(role);
+    const def = TIER_DEFS[tier];
+    const frontmatter = [
+        "---",
+        `name: ${asset.name}-${tier}`,
+        `description: ${yamlQuote(tierDescriptionSuffix(asset, tier))}`,
+        `model: ${claudeModelValue(CLASS_MODELS[def.modelClass])}`,
+        `effort: ${def.effort}`,
+    ];
+    if (READ_ONLY_ROLES.has(role)) {
+        frontmatter.push("disallowedTools: Edit, Write, NotebookEdit");
+    }
+    frontmatter.push("---");
+    return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
+}
+/**
+ * Whether a resolved opencode model id belongs to the Claude family,
+ * regardless of which provider is fronting it (`anthropic/claude-...`,
+ * `github-copilot/claude-...`, `openrouter/anthropic/claude-...`, ...): the
+ * segment after the provider prefix contains `claude-`, or the id starts
+ * with `anthropic/` outright. Dispatch on family rather than provider id
+ * because the `variant:` effort surface is a property of the model being
+ * served, not of which provider happens to front it.
+ */
+function isClaudeFamilyModel(modelValue) {
+    if (modelValue.startsWith("anthropic/"))
+        return true;
+    const slash = modelValue.indexOf("/");
+    const remainder = slash === -1 ? "" : modelValue.slice(slash + 1);
+    return remainder.includes("claude-");
+}
+/**
+ * The opencode effort surface is keyed by model family, not provider id:
+ * Claude-family models' `variant:` option only distinguishes `high` and
+ * `max` (mapped from the `high`/`xhigh` tiers; `low`/`medium` collapse to no
+ * effort field), Ollama and ids without a provider prefix have no known
+ * effort passthrough, and every other model accepts a plain
+ * `reasoningEffort:` value. An unresolved (`undefined`) model gets no
+ * effort field either, since there is then no model to key the decision on.
+ */
+function opencodeVariantEffortLine(tier, modelValue) {
+    if (!modelValue)
+        return undefined;
+    if (isClaudeFamilyModel(modelValue)) {
+        if (tier === "high")
+            return "variant: high";
+        if (tier === "xhigh")
+            return "variant: max";
+        return undefined;
+    }
+    const slash = modelValue.indexOf("/");
+    const provider = slash === -1 ? undefined : modelValue.slice(0, slash);
+    if (provider === undefined || provider === "ollama")
+        return undefined;
+    return `reasoningEffort: ${TIER_DEFS[tier].effort}`;
+}
+/**
+ * Composes a tier-variant sibling of `composeOpencodeAgent`. `effortLine` is
+ * decided once, at the single call site in the opencode tier loop of
+ * `runInit` (via `opencodeVariantEffortLine`), and passed in rather than
+ * recomputed here, so there is exactly one place that decides it instead
+ * of a second, independent source of truth for the same value.
+ */
+function composeOpencodeAgentVariant(role, tier, modelValue, effortLine) {
+    const asset = readAgentAsset(role);
+    const frontmatter = [
+        "---",
+        `description: ${yamlQuote(tierDescriptionSuffix(asset, tier))}`,
+        "mode: subagent",
+    ];
+    if (modelValue) {
+        frontmatter.push(`model: ${modelValue}`);
+    }
+    if (effortLine) {
+        frontmatter.push(effortLine);
+    }
+    if (READ_ONLY_ROLES.has(role)) {
+        frontmatter.push("permission:", "  edit: deny");
+    }
+    frontmatter.push("---");
+    return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
+}
 export function runInit(options) {
     const { targetDir } = options;
     if (!existsSync(targetDir)) {
@@ -132,9 +230,25 @@ export function runInit(options) {
     }
     const force = options.force ?? false;
     const profile = options.profile ?? DEFAULT_PROFILE;
+    const tiers = options.tiers ?? false;
     const report = emptyReport();
     const previous = readInstalledManifest(targetDir);
     const installedFiles = {};
+    // Both leftover-note loops below are ledger-driven, not enumeration-
+    // driven: they only ever push a note for a relative path that the
+    // *previous* install actually recorded in `previous.files`, and only ever
+    // iterate `previous.harnesses` (the harnesses that install actually wrote
+    // files for), never `ROLE_TIERS`/`options.harnesses` as a source of truth.
+    // Deriving the note set from ROLE_TIERS/options.harnesses instead would
+    // (a) claim a leftover for a variant file that was never written in the
+    // first place (e.g. an opencode install whose tier-class models never
+    // resolved, so the unresolved-class guard skipped every variant write),
+    // and (b) miss a real leftover whose harness was dropped from
+    // options.harnesses this run, since that harness's files are still
+    // sitting on disk and still becoming untracked either way. The ledger
+    // (`previous.files`/`previous.harnesses`) is the only source of truth for
+    // "what did the previous install actually put on disk."
+    const previousHarnessDirs = (previous?.harnesses ?? []).filter((harness) => harness === "claude" || harness === "opencode");
     // A full -> minimal downgrade drops explorer/task-slicer from the roles
     // installed, but (like dropping a harness from --harness) existing role
     // files are never deleted: they simply fall out of the manifest's file
@@ -142,12 +256,46 @@ export function runInit(options) {
     // left as an unexplained, untracked leftover on disk.
     if (previous && previous.profile === "full" && profile !== previous.profile) {
         const droppedRoles = rolesForProfile(previous.profile).filter((role) => !rolesForProfile(profile).includes(role));
-        const harnessDirs = options.harnesses.filter((harness) => harness === "claude" || harness === "opencode");
-        for (const harness of harnessDirs) {
-            const harnessDir = harness === "claude" ? ".claude" : ".opencode";
+        for (const harnessDir of previousHarnessDirs.map((harness) => harness === "claude" ? ".claude" : ".opencode")) {
             for (const role of droppedRoles) {
                 const relativePath = join(harnessDir, "agents", `${role}.md`);
-                report.notes.push(`${relativePath}: now untracked after the full -> ${profile} profile downgrade; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
+                if (previous.files[relativePath] !== undefined) {
+                    report.notes.push(`${relativePath}: now untracked after the full -> ${profile} profile downgrade; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
+                }
+                // A dropped role that also had tiers on previously left behind its
+                // own <role>-<tier>.md variant files, not just its base file; the
+                // note above only knows about <role>.md, so those variants would go
+                // unmentioned even though they are equally untracked now. ROLE_TIERS
+                // only supplies the candidate tier suffixes to probe; the ledger
+                // check above/below is what decides whether a note is actually due.
+                for (const tier of ROLE_TIERS[role]) {
+                    if (tier === DEFAULT_TIER[role])
+                        continue;
+                    const variantPath = join(harnessDir, "agents", `${role}-${tier}.md`);
+                    if (previous.files[variantPath] !== undefined) {
+                        report.notes.push(`${variantPath}: now untracked after the full -> ${profile} profile downgrade; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
+                    }
+                }
+            }
+        }
+    }
+    // A tiers on -> off transition leaves each still-installed role's
+    // <role>-<tier>.md variant files behind on disk, the same untracked-
+    // leftover shape as the full -> minimal profile downgrade above (a role
+    // dropped from the profile is handled by the block above instead, so
+    // there is no overlap between the two loops). Surface it the same way:
+    // a note per file instead of a silent, unexplained leftover.
+    if (previous && previous.tiers && !tiers) {
+        for (const harnessDir of previousHarnessDirs.map((harness) => harness === "claude" ? ".claude" : ".opencode")) {
+            for (const role of rolesForProfile(profile)) {
+                for (const tier of ROLE_TIERS[role]) {
+                    if (tier === DEFAULT_TIER[role])
+                        continue;
+                    const relativePath = join(harnessDir, "agents", `${role}-${tier}.md`);
+                    if (previous.files[relativePath] !== undefined) {
+                        report.notes.push(`${relativePath}: now untracked after tiers were turned off; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
+                    }
+                }
             }
         }
     }
@@ -189,6 +337,13 @@ export function runInit(options) {
         installKitFile(join(".claude", "skills", SKILL_NAME, "SKILL.md"), skill);
         for (const role of rolesForProfile(profile)) {
             installKitFile(join(".claude", "agents", `${role}.md`), composeClaudeAgent(role, options.models[role]));
+            if (tiers) {
+                for (const tier of ROLE_TIERS[role]) {
+                    if (tier === DEFAULT_TIER[role])
+                        continue;
+                    installKitFile(join(".claude", "agents", `${role}-${tier}.md`), composeClaudeAgentVariant(role, tier));
+                }
+            }
         }
         ensureClaudeImport(report, join(targetDir, "CLAUDE.md"));
     }
@@ -202,6 +357,31 @@ export function runInit(options) {
                 ? options.opencodeModels[role]
                 : opencodeModelValue(options.models[role]);
             installKitFile(join(".opencode", "agents", `${role}.md`), composeOpencodeAgent(role, modelValue));
+            if (tiers) {
+                for (const tier of ROLE_TIERS[role]) {
+                    if (tier === DEFAULT_TIER[role])
+                        continue;
+                    const modelClass = TIER_DEFS[tier].modelClass;
+                    const variantModelValue = options.opencodeClassModels?.[modelClass];
+                    if (variantModelValue === undefined) {
+                        // No model resolved for this class: opencodeVariantEffortLine
+                        // always returns undefined too when its modelValue argument is
+                        // undefined (it short-circuits on that first), so this variant
+                        // would carry neither a model: nor an effort line, a silent
+                        // no-op duplicate of the base file's own (possibly also
+                        // unresolved) model line, with no ledger entry to compare it
+                        // against. Skip it entirely rather than write that
+                        // indistinguishable file. A *resolved* model with no effort line
+                        // (e.g. a low/medium tier on a Claude-family model, or any
+                        // Ollama model) is NOT skipped by this check: it still renders
+                        // with just its model: line, see the effort-field dispatch
+                        // rules in opencodeVariantEffortLine above.
+                        continue;
+                    }
+                    const effortLine = opencodeVariantEffortLine(tier, variantModelValue);
+                    installKitFile(join(".opencode", "agents", `${role}-${tier}.md`), composeOpencodeAgentVariant(role, tier, variantModelValue, effortLine));
+                }
+            }
         }
     }
     // The manifest records applied state, so it is written last and only when
@@ -212,6 +392,7 @@ export function runInit(options) {
         harnesses: [...options.harnesses].sort(),
         models: options.models,
         profile,
+        tiers,
         files: installedFiles,
     };
     const manifestPath = join(targetDir, MANIFEST_PATH);
@@ -222,6 +403,7 @@ export function runInit(options) {
             harnesses: previous.harnesses,
             models: previous.models,
             profile: previous.profile,
+            tiers: previous.tiers,
             files: previous.files,
         }) === JSON.stringify(desired)) {
         report.skipped.push(manifestPath);

package/dist/models.d.ts

@@ -54,3 +54,32 @@ export declare function assertValidModelId(model: string): void;
  * the given base mapping. Unknown roles and empty values are rejected.
  */
 export declare function parseModelsSpec(spec: string, base: Record<Role, string>): Record<Role, string>;
+/**
+ * Effort tiers: additional per-role subagent variants rendered alongside the
+ * default (unsuffixed) agent file when the `tiers` feature is on. Default
+ * off; see `install-fence-mechanics.md` for the default-off pack rationale.
+ */
+export type Tier = "low" | "medium" | "high" | "xhigh";
+/**
+ * Which tiers each role gets a variant file for. A tier outside a role's
+ * list is never rendered for that role (e.g. explorer/task-slicer never get
+ * an `xhigh` variant, reviewer never gets a `low` variant).
+ */
+export declare const ROLE_TIERS: Record<Role, Tier[]>;
+/**
+ * The tier each role's default (unsuffixed) agent file already corresponds
+ * to. No variant file is ever rendered for this tier: rendering one would
+ * both collide with the default file's name and duplicate it.
+ */
+export declare const DEFAULT_TIER: Record<Role, Tier>;
+export type ModelClass = "small" | "medium" | "large";
+export declare const MODEL_CLASSES: ModelClass[];
+interface TierDef {
+    modelClass: ModelClass;
+    /** Effort value requested from the harness for this tier. */
+    effort: Tier;
+}
+export declare const TIER_DEFS: Record<Tier, TierDef>;
+/** Which model alias backs each tier's model class. */
+export declare const CLASS_MODELS: Record<ModelClass, ModelAlias>;
+export {};

package/dist/models.js

@@ -105,3 +105,38 @@ export function parseModelsSpec(spec, base) {
     }
     return result;
 }
+/**
+ * Which tiers each role gets a variant file for. A tier outside a role's
+ * list is never rendered for that role (e.g. explorer/task-slicer never get
+ * an `xhigh` variant, reviewer never gets a `low` variant).
+ */
+export const ROLE_TIERS = {
+    explorer: ["low", "medium", "high"],
+    "task-slicer": ["low", "medium", "high"],
+    implementer: ["low", "medium", "high", "xhigh"],
+    reviewer: ["medium", "high", "xhigh"],
+};
+/**
+ * The tier each role's default (unsuffixed) agent file already corresponds
+ * to. No variant file is ever rendered for this tier: rendering one would
+ * both collide with the default file's name and duplicate it.
+ */
+export const DEFAULT_TIER = {
+    explorer: "medium",
+    "task-slicer": "medium",
+    implementer: "medium",
+    reviewer: "high",
+};
+export const MODEL_CLASSES = ["small", "medium", "large"];
+export const TIER_DEFS = {
+    low: { modelClass: "small", effort: "low" },
+    medium: { modelClass: "medium", effort: "medium" },
+    high: { modelClass: "medium", effort: "high" },
+    xhigh: { modelClass: "large", effort: "xhigh" },
+};
+/** Which model alias backs each tier's model class. */
+export const CLASS_MODELS = {
+    small: "haiku",
+    medium: "sonnet",
+    large: "opus",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.18.0",
+  "version": "0.19.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",