orchestrator-workflow 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -5,6 +5,74 @@ 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.23.0] - 2026-08-24
+
+### Changed
+
+- **Tightened the `implementer-low` tier rule from discretion to a checkable
+  gate on the task contract.** `agents-md-section.md`'s Scaling delegation
+  bullet and `SKILL.md` step 6 ("Delegate implementation") no longer say
+  `-low` "fits mechanical, narrowly scoped tasks" for the implementer;
+  `implementer-low` is now spawned only when none of the following hold: an
+  acceptance criterion demands a test, typecheck, lint, or build run; the task
+  assignment names mutation probes to run; or the task slicer's
+  `suggested_tests` came back non-empty. A task with any of those, including a
+  bugfix that looks mechanical, runs on the unsuffixed implementer or higher.
+  When it is unclear whether a criterion demands a run, exclude
+  `implementer-low`. The explorer and the task-slicer keep the prior
+  discretionary `-low` guidance unchanged, since no equivalent measurement
+  exists for those roles. Operator decision 2026-08-24 after a Tier-A/B
+  measurement of implementer-low as installed (Haiku 4.5) against the default
+  implementer (Sonnet 5, effort medium) (agent-tasks task 7f38899d), blinded,
+  n=8, identical tasks in both tiers: implementer-low reached accept a median
+  320 seconds slower (p=0.016), drew 9 high-plus-critical review findings
+  against 1, and needed 8 fix rounds against 1. The A/B's implementer-low ran
+  on Haiku 4.5, which does not support the `effort` parameter, so the harness
+  ignores the pinned `effort: low` on that model; the measurement compared
+  Haiku 4.5 without effort control against Sonnet 5 at `effort: medium`.
+
+## [0.22.0] - 2026-08-20
+
+### Changed
+
+- **Default subagent spawns no longer inherit the orchestrator session's
+  effort.** Every unsuffixed default agent file (`explorer.md`,
+  `task-slicer.md`, `implementer.md`, `reviewer.md`, `advisor.md`) now
+  carries its own pinned default effort, unconditionally, regardless of
+  whether `--tiers` is on: `effort: medium` for explorer, task-slicer, and
+  implementer, `effort: high` for reviewer and advisor
+  (`TIER_DEFS[DEFAULT_TIER[role]].effort`, the same tier data `--tiers`
+  already used, applied by `composeClaudeAgent` for every install, tiers
+  flag or not). opencode gets the matching pinned line via
+  `opencodeEffortLine` (renamed from `opencodeVariantEffortLine`, now shared
+  by the default file and the tier variants): a resolved Claude-family model
+  gets `variant: high` for reviewer/advisor and no effort field at all for
+  the three medium-default roles (opencode's `variant:` option does not
+  distinguish an effort below `high`, the same collapse tier variants
+  already documented), a non-Claude-family provider-qualified model gets
+  `reasoningEffort: medium`/`reasoningEffort: high`, and Ollama, a
+  provider-less id, or an unresolved model gets no effort field either way.
+  Practically: on a high-effort orchestrator session, a default subagent
+  spawn used to silently run at that same high effort; it now runs at its
+  own role's pinned effort instead, which is weaker (and cheaper) for the
+  three medium-default roles. Escalate deliberately via the `-high`/`-xhigh`
+  tier variants (`--tiers`) when a task actually needs more.
+  **`CLAUDE_CODE_EFFORT_LEVEL` still beats this pin**: when the harness
+  environment sets that variable, it overrides every installed agent's
+  frontmatter `effort:`, default files and tier variants alike, the same
+  warning `--tiers` already carried. **opencode cannot express `medium` for
+  a Claude-family model at all**: the `variant:` field only distinguishes
+  `high`/`max`, so a Claude-family default file for explorer, task-slicer,
+  or implementer renders with no effort field, falling back to whatever the
+  resolved model's own default happens to be.
+  The default file's content stays byte-identical whether or not `--tiers`
+  is also on, since the pin does not read the `tiers` flag; this invariant
+  is now belt-and-suspenders tested directly (a two-target diff, not just
+  inferred from reading the source).
+  A `--tiers`-off install (the default) renders no variant files at all, so
+  it has no in-install escalation path off a default's pinned effort; pull
+  `init --tiers` afterward if a task needs one.
+
 ## [0.21.0] - 2026-08-20
 
 ### Added

package/INSTALL-AGENT.md

@@ -146,10 +146,15 @@ steps in the repository you were asked to install into.
      for `full`; only `implementer` and `reviewer` for `minimal`),
      `.claude/agents/<role>.md` from
      `assets/agents/<role>.md` with `model: <operator's choice>` added as a
-     new line directly after the `description:` line (that placement matches
-     the installer's output byte for byte). For the explorer, reviewer, and
-     advisor roles additionally, `disallowedTools: Edit, Write, NotebookEdit` goes on a new
-     line directly after the `model:` line. Ensure `CLAUDE.md` exists and
+     new line directly after the `description:` line, then
+     `effort: <medium|high>` on the next line (`medium` for explorer,
+     task-slicer, and implementer; `high` for reviewer and advisor; this
+     pinned default effort is unconditional, not tied to whether the
+     operator asked for `--tiers`; see the package README's "Effort tiers"
+     section), that placement matching the installer's output byte for
+     byte. For the explorer, reviewer, and advisor roles additionally,
+     `disallowedTools: Edit, Write, NotebookEdit` goes on a new line
+     directly after the `effort:` line. Ensure `CLAUDE.md` exists and
      contains a line `@AGENTS.md`.
    - Codex: `.agents/skills/orchestrator-workflow/SKILL.md`, same skill file.
    - opencode: `.opencode/skills/orchestrator-workflow/SKILL.md` from
@@ -166,9 +171,21 @@ steps in the repository you were asked to install into.
      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, reviewer, and advisor roles 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.
+     correct. When you do have a fully-qualified `model:` value, add the same
+     pinned-default-effort line (see the package README's "Effort tiers"
+     section for the exact dispatch rule), keyed by
+     the role's own default tier instead of a suffix tier (`medium` for
+     explorer/task-slicer/implementer, `high` for reviewer/advisor): a
+     resolved Claude-family model gets `variant: high` for reviewer/advisor
+     and no effort line at all for the three medium-default roles, a
+     non-Claude-family provider-qualified model gets `reasoningEffort:
+     medium` or `reasoningEffort: high`, and Ollama or a provider-less id
+     gets no effort line either way; when `model:` is omitted (the common
+     manual-fallback case above), omit the effort line too, the same
+     no-live-catalog fallback. For the explorer, reviewer, and advisor roles
+     additionally, `permission:` goes on a new line directly after
+     `mode: subagent` (or after `model:`/the effort line when present),
+     followed by `  edit: deny` (two-space indent) on the next line.
      Example read-only role frontmatter (explorer, reviewer, or advisor) when
      no model is resolved:
      ```yaml
@@ -181,12 +198,13 @@ steps in the repository you were asked to install into.
      ```
    - `.ai/workflow/manifest.json`, exactly this shape (harnesses MUST be an
      array, `profile` is `"minimal"` or `"full"`, models keyed by role,
-     version = the kit version you installed):
+     version = the kit version you installed, read from this kit's own
+     `packages/orchestrator-workflow/package.json` `version` field):
 
      ```json
      {
        "kit": "orchestrator-workflow",
-       "version": "0.5.0",
+       "version": "<kit version you installed>",
        "harnesses": ["claude", "opencode"],
        "profile": "full",
        "tiers": false,
@@ -198,7 +216,7 @@ steps in the repository you were asked to install into.
          "advisor": "opus"
        },
        "files": {},
-       "installedAt": "2026-06-12T00:00:00.000Z"
+       "installedAt": "<ISO 8601 timestamp of this install>"
      }
      ```
 

package/README.md

@@ -215,8 +215,27 @@ 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`.
+produces, and each variant lives next to it as `<role>-<tier>.md`.
+
+**Every default file carries its own pinned effort, independent of
+`--tiers`.** Since 0.22.0, `composeClaudeAgent`/`composeOpencodeAgent` add
+the role's own `TIER_DEFS[DEFAULT_TIER[role]].effort` to the default
+(unsuffixed) file unconditionally: `effort: medium` for explorer,
+task-slicer, and implementer; `effort: high` for reviewer and advisor
+(opencode: a `variant: high` line when the resolved model is Claude-family,
+following the same dispatch rule tier variants use, `reasoningEffort:
+medium`/`reasoningEffort: high` for a non-Claude-family provider-qualified
+model, nothing for Ollama, a provider-less id, or an unresolved model). This
+pin does not depend on `tiers`, so a plain install (no `--tiers`) already
+carries it; the flag only controls whether the additional `<role>-<tier>.md`
+variant files are also rendered. The motivation: a default spawn used to
+silently inherit the orchestrator session's own effort, so a `high`-effort
+orchestrator session made every default subagent spawn at `high` too,
+regardless of the role's own intended weight; the pin makes each role's
+effort deterministic and independent of the caller's session. A `--tiers`-off
+install (the default) has no variant files and therefore no in-install
+escalation path off a default's pinned effort; run `init --tiers` afterward
+if a task ever needs one.
 
 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,
@@ -307,6 +326,14 @@ 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.
 
+The pin is also emitted unconditionally regardless of which model the role
+resolves to via `--models`, including a model with no effort support at all
+(e.g. `--models reviewer=haiku` still renders `model: haiku` followed by
+`effort: high`). A wire probe on 2026-08-19 (not re-measured for this doc)
+showed the Claude Code CLI silently drops the `effort:` parameter for Haiku
+4.5 rather than rejecting it: the value is ignored, not an install-time or
+run-time error.
+
 ## Ownership and re-runs
 
 `init` is idempotent: a second run changes nothing. The rules:

package/assets/agents-md-section.md

@@ -50,16 +50,41 @@ default, not a ritual.
   changes whose risk or size warrants an independent skeptical pass. Either
   way, review is never skipped.
 - When tier variants are installed (manifest `tiers: true`), the orchestrator
-  picks the effort tier per task by complexity and risk, at its own
-  judgment. The unsuffixed default subagent is the normal case; a `-low`
-  variant fits mechanical, narrowly scoped tasks; `-high`/`-xhigh` fit
-  high-risk changes, hard problems, or repeated failed attempts. Not every
-  role gets every tier: `-xhigh` exists only for the implementer, the
-  reviewer, and the advisor. The reviewer's downshift is `-medium` rather
-  than `-low`, since its default already sits at high. The advisor has no
-  downshift at all: its default `high` is already its only non-`-xhigh`
-  tier. Spawn only variants that are actually installed. Tier choice is a
-  conscious decision, not a ritual; when unsure, use the default.
+  picks the effort tier per task by complexity and risk, at its own judgment.
+  The unsuffixed default subagent is the normal case; `-high`/`-xhigh` fit
+  high-risk changes, hard problems, or repeated failed attempts. For the
+  implementer specifically, `-low` is spawned only when none of the following
+  hold: an acceptance criterion demands a test, typecheck, lint, or build run;
+  the task assignment names mutation probes to run; or the task slicer's
+  `suggested_tests` came back non-empty. This is checkable against the task
+  contract rather than a judgment about how hard the task looks: any one of
+  those three excludes `implementer-low`, and the task runs on the unsuffixed
+  implementer or higher, even when the change looks mechanical (a bugfix
+  included); when it is unclear whether a criterion demands a run, exclude
+  `implementer-low`. This rule is anchored by an A/B measurement of
+  implementer-low as installed (Haiku 4.5) against the default implementer
+  (Sonnet 5, effort medium) (2026-08-24, n=8, identical tasks in both tiers,
+  blinded reviews, agent-tasks task 7f38899d): implementer-low reached accept
+  a median 320 seconds slower (p=0.016), drew 9 high-plus-critical review
+  findings against 1, and needed 8 fix rounds against 1. The A/B's
+  implementer-low ran on Haiku 4.5, which does not support the `effort`
+  parameter (per Anthropic's model reference), so the harness ignores the
+  pinned `effort: low` on that model; the measurement compared Haiku 4.5
+  without effort control against Sonnet 5 at `effort: medium`. For the
+  explorer and the task-slicer, a `-low` variant still suits narrowly scoped,
+  mechanical work; no equivalent measurement exists for those two roles, so
+  their rule is unchanged. Not every role gets every tier: `-xhigh` exists
+  only for the implementer, the reviewer, and the advisor. The reviewer's
+  downshift is `-medium` rather than `-low`, since its default already sits at
+  high. The advisor has no downshift at all: its default `high` is already its
+  only non-`-xhigh` tier. Spawn only variants that are actually installed.
+  Tier choice is a conscious decision, not a ritual; when unsure, use the
+  default.
+- Every unsuffixed default subagent carries its own pinned default effort
+  baked into its own file, not inherited from the orchestrator session:
+  medium for the explorer, the task-slicer, and the implementer; high for
+  the reviewer and the advisor. This holds whether or not tier variants are
+  installed; it is not gated on `--tiers`.
 - Under the `full` profile, an advisor subagent is available for escalation
   only: architectural uncertainty, requirements that contradict each other,
   multiple valid solution paths where committing to one is expensive to

package/assets/skill/SKILL.md

@@ -134,11 +134,23 @@ directory and the subagents.
    enough, testable, ordered correctly, and aligned with the goal. Fix the
    slicing before any implementation starts.
 6. **Delegate implementation.** Send each implementer subagent one narrow task
-   contract (format below). When tier variants are installed, pick the
-   implementer tier (the installed `implementer-<tier>` subagents, if any) by
-   the task's complexity and risk, at your own judgment, defaulting to the
-   unsuffixed subagent when unsure; record a non-default tier choice with a
-   one-line reason in `03-decisions.md` when the task is non-trivial. When a
+   contract (format below). The unsuffixed implementer carries a pinned
+   effort: `medium` in its own file, whether or not tier variants are
+   installed, so a default spawn no longer inherits the session's effort.
+   When tier variants are installed, pick the implementer tier (the
+   installed `implementer-<tier>` subagents, if any) by the task's
+   complexity and risk, at your own judgment, defaulting to the unsuffixed
+   subagent when unsure; record a non-default tier choice with a
+   one-line reason in `03-decisions.md` when the task is non-trivial.
+   `implementer-low` is spawned only when none of the following hold: an
+   acceptance criterion demands a test, typecheck, lint, or build run; the
+   task assignment names mutation probes to run; or the task slicer's
+   `suggested_tests` came back non-empty. Any one of those three excludes
+   `implementer-low`, even for a change that looks mechanical (a bugfix
+   included) (2026-08-24 A/B measurement, n=8: implementer-low reached accept
+   a median 320 seconds slower, p=0.016, with 9 high-plus-critical review
+   findings against 1 and 8 fix rounds against 1). When it is unclear
+   whether a criterion demands a run, exclude `implementer-low`. When a
    task's acceptance rests on a test that must fail without the change, name
    the mutation probes to run in the task assignment; the implementer reports
    each one in the output contract's `mutation_probes` field (apply the mutant

package/dist/init.js

@@ -95,6 +95,22 @@ export function readInstalledManifest(targetDir) {
 function yamlQuote(value) {
     return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
+/**
+ * Composes the unsuffixed default agent file. It carries a pinned
+ * `effort: <TIER_DEFS[DEFAULT_TIER[role]].effort>` line unconditionally
+ * (medium for explorer/task-slicer/implementer, high for reviewer/advisor),
+ * regardless of whether `--tiers` is on: this is the deterministic tier
+ * ladder's floor, not a tier-variant feature, so a default spawn no longer
+ * silently inherits the orchestrator session's effort. Since the pin does
+ * not depend on the `tiers` flag, the default file's content still stays
+ * byte-identical whether or not tier variants are also rendered, the same
+ * invariant `composeClaudeAgentVariant`'s own doc comment below describes.
+ * Computed inline here rather than passed in like `composeOpencodeAgent`'s
+ * `effortLine`: `TIER_DEFS[DEFAULT_TIER[role]].effort` is a pure function of
+ * `role` alone, with no model-dependent dispatch on Claude Code the way
+ * opencode's family-based `opencodeEffortLine` has, so there is no second,
+ * potentially-diverging computation here to guard against.
+ */
 function composeClaudeAgent(role, model) {
     const asset = readAgentAsset(role);
     const frontmatter = [
@@ -102,6 +118,7 @@ function composeClaudeAgent(role, model) {
         `name: ${asset.name}`,
         `description: ${yamlQuote(asset.description)}`,
         `model: ${claudeModelValue(model)}`,
+        `effort: ${TIER_DEFS[DEFAULT_TIER[role]].effort}`,
     ];
     // Read-only roles keep every read/search tool but cannot mutate files.
     if (READ_ONLY_ROLES.has(role)) {
@@ -110,7 +127,15 @@ function composeClaudeAgent(role, model) {
     frontmatter.push("---");
     return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
 }
-function composeOpencodeAgent(role, modelValue) {
+/**
+ * Composes the unsuffixed default opencode agent file. `effortLine` is the
+ * same pinned-default-effort line a tier variant would carry, decided once
+ * by the caller via `opencodeEffortLine(DEFAULT_TIER[role], modelValue)`
+ * (single source of truth, the same pattern `composeOpencodeAgentVariant`
+ * already uses for its own effort line) and passed in rather than
+ * recomputed here.
+ */
+function composeOpencodeAgent(role, modelValue, effortLine) {
     const asset = readAgentAsset(role);
     const frontmatter = [
         "---",
@@ -122,6 +147,9 @@ function composeOpencodeAgent(role, modelValue) {
     if (modelValue) {
         frontmatter.push(`model: ${modelValue}`);
     }
+    if (effortLine) {
+        frontmatter.push(effortLine);
+    }
     if (READ_ONLY_ROLES.has(role)) {
         frontmatter.push("permission:", "  edit: deny");
     }
@@ -134,8 +162,8 @@ function tierDescriptionSuffix(asset, 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.
+ * `DEFAULT_TIER`), so `composeClaudeAgent`'s own output (pinned default
+ * effort included) stays byte-identical whether or not tiers are on.
  */
 function composeClaudeAgentVariant(role, tier) {
     const asset = readAgentAsset(role);
@@ -177,8 +205,12 @@ function isClaudeFamilyModel(modelValue) {
  * 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.
+ * Shared by both the default (unsuffixed) agent file, keyed by the role's
+ * own `DEFAULT_TIER`, and the tier-variant files, keyed by the variant's own
+ * suffix tier: the dispatch rule is identical either way, only which tier
+ * gets passed in differs.
  */
-function opencodeVariantEffortLine(tier, modelValue) {
+function opencodeEffortLine(tier, modelValue) {
     if (!modelValue)
         return undefined;
     if (isClaudeFamilyModel(modelValue)) {
@@ -197,7 +229,7 @@ function opencodeVariantEffortLine(tier, modelValue) {
 /**
  * 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
+ * `runInit` (via `opencodeEffortLine`), 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.
  */
@@ -356,7 +388,8 @@ export function runInit(options) {
             const modelValue = options.opencodeModels !== undefined
                 ? options.opencodeModels[role]
                 : opencodeModelValue(options.models[role]);
-            installKitFile(join(".opencode", "agents", `${role}.md`), composeOpencodeAgent(role, modelValue));
+            const defaultEffortLine = opencodeEffortLine(DEFAULT_TIER[role], modelValue);
+            installKitFile(join(".opencode", "agents", `${role}.md`), composeOpencodeAgent(role, modelValue, defaultEffortLine));
             if (tiers) {
                 for (const tier of ROLE_TIERS[role]) {
                     if (tier === DEFAULT_TIER[role])
@@ -364,8 +397,8 @@ export function runInit(options) {
                     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
+                        // No model resolved for this class: opencodeEffortLine 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
@@ -375,10 +408,10 @@ export function runInit(options) {
                         // (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.
+                        // rules in opencodeEffortLine above.
                         continue;
                     }
-                    const effortLine = opencodeVariantEffortLine(tier, variantModelValue);
+                    const effortLine = opencodeEffortLine(tier, variantModelValue);
                     installKitFile(join(".opencode", "agents", `${role}-${tier}.md`), composeOpencodeAgentVariant(role, tier, variantModelValue, effortLine));
                 }
             }

package/package.json

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