feat(session-flow): orchestrate volume-based model tiering default

[kyle-sexton]

What

Sharpens the orchestrate skill's per-worker tiering (imperative 7) into an explicit volume-based default, and broadens "tier" from model-only to model and reasoning effort.

Why

Carried from the re-anchor round-2 ledger (task #3), observed in production: an /orchestrate run fanned out ~100–200 agents, all on the top-tier model. PR #340 (0.9.1) fixed the root spawn-inherit bug — SPEC EVERY SPAWN + CALIBRATE now carry a per-worker tier — but the residual enhancement (making the tier default flip on volume) was never built. The prior text stated the direction as a gradient ("the wider the fan-out, the cheaper the default per-worker tier") without wiring the verify/judge carve-out as the standing exception, and never named reasoning effort as a tiering lever.

Change

plugins/session-flow/skills/orchestrate/SKILL.md — imperative 7:

• Past a wide fan-out, the cheaper tier is now the DEFAULT the whole fleet inherits (volume multiplies every notch of over-provisioning).
• The standing exception is an explicitly hard stage — verify, judge/adjudicate, judgment-heavy synthesis — which keeps the parent tier. A premium fan-out outside those stages is a per-stage decision to justify, never a default to inherit.
• Tier is model AND effort: match reasoning depth (effort), not just the model, to the subtask.

context/sources.md — three new verbatim citations grounding the change in current official docs: the per-worker effort frontmatter lever, the workflow fleet-model inherit mechanism, and the platform's own wide-run threshold (its Large workflow warning + /config size guideline). Per the skill's model-/tool-agnostic construction, these version-pinned specifics stay in sources.md, never the imperatives or export brief.

Grounding (fresh docs, this session)

• Subagent model precedence + inherit default, effort field, cost-routing guidance — https://code.claude.com/docs/en/sub-agents
• Workflow fleet-model inheritance, per-stage routing, Large workflow threshold + size guideline — https://code.claude.com/docs/en/workflows

Gates

• check-skill.sh orchestrate: PASS (7/7 trigger phrases preserved, 125/500 lines, markdownlint clean)
• check-changelog-parity.sh --check and --check-bump origin/main: PASS
• validate-plugin-contracts.mjs, generate-catalog.mjs --check, claude plugin validate .: PASS
• Version bumped 0.12.2 → 0.12.3 with CHANGELOG entry in the same diff.

Related

• PR fix(session-flow): make worker model tier an explicit spawn decision (0.9.1) #340 — the session-flow 0.9.1 spawn-inherit fix this builds on (SPEC EVERY SPAWN + CALIBRATE carrying a per-worker tier); not closed by this PR.
• The re-anchor round-2 ledger task feat: markdown-formatter plugin (pilot migration) #3 production observation that motivated the residual enhancement.

Closes #863.

[claude]

Claude finished @kyle-sexton's task in 2m 16s —— View job

---

PR Review

• Gather context and read changed files
• Review SKILL.md changes
• Review sources.md additions
• Review plugin.json version bump and CHANGELOG
• Post final review

---

Summary

This is a clean, well-grounded documentation-only change. The logic flows correctly: the old imperative 7 gestured at a gradient ("the wider the fan-out, the cheaper") without making it a rule or naming effort as a lever — this PR makes both explicit. The fresh-docs mandate is satisfied: the new sources.md citations carry verbatim+verified marks with their backing URLs, and the design decision to keep version-pinned specifics (25-agent threshold, effort enum) in sources.md while keeping the imperative model-/tool-agnostic is exactly right.

---

Findings

1. Compound-case gap: wide fan-out of the standing exception categories (SKILL.md, line 71–72)

The standing exception — verify / judge / adjudicate — unconditionally keeps the parent tier. This is correct for a handful of judgment-heavy workers, but the rule doesn't address what happens when the exception category itself fans wide. Parallel adversarial verification at scale (e.g., 50 independent verifiers in a loop-until-dry pattern) multiplies cost just as aggressively as any other wide fleet, yet the current wording implies all of them keep the top tier by default.

The fix isn't complex: the exception could note that even hard stages revert to the volume default once they themselves constitute a wide fleet, or that the parent-tier carve-out applies per-stage, not per-agent-count-within-a-stage. As written, a reader implementing a large verify fleet has no signal to route it cheaper.

This isn't introduced by this PR (the previous gradient didn't address it either), but because the PR is sharpening the rule into an explicit default+exception structure, it's the right moment to close the gap.

Fix this →

---

2. CHANGELOG date omission (CHANGELOG.md, lines 1–16)

Both [0.12.2] and [0.12.3] lack the — YYYY-MM-DD suffix present on [0.12.1] and [0.12.0]. Minor inconsistency that will need a retroactive fix at some point, though not blocking.

---

3. sources.md header date ambiguity (sources.md, line 5)

The header reads captured during research (2026-06-14), but the three new citations at the bottom of imperative 7 were verified 2026-07-21 (this session). The header technically scopes itself to paraphrase captures, and the new entries carry *(verbatim, verified)* marks rather than *(paraphrase)*, so this isn't factually wrong. But a reader scanning the file for "how fresh is this?" will see the 2026-06-14 date and may not notice it applies only to paraphrase captures. A note at the top of the new blocks (or a file-level "last updated" line) would remove the ambiguity.

---

What's correct

• Imperative 7 default-flip logic is sound. "Volume multiplies every notch of over-provisioning" is a concise, memorable framing that adds real signal over the old gradient hint.
• Tier = model AND effort is the right broadening. The effort lever is easy to overlook, and naming it explicitly closes a gap practitioners hit in practice.
• sources.md citation quality for the three new blocks is high: verbatim quotes with URLs, and the decision to keep the platform's concrete thresholds (25 agents, 1.5M tokens, the /config size enum) in sources.md rather than the imperative text is exactly the right call for model-/tool-agnostic durability.
• Version bump and CHANGELOG are present and accurate in content; the date omission (finding 2) is the only wrinkle.
• Gates cited in the PR description (check-skill.sh 7/7, changelog parity, plugin validate) all pass.

---

Overall: Approve with the compound-case gap (finding 1) noted as a follow-up. The other two are minor housekeeping.

[claude]

Claude finished @kyle-sexton's task in 55s —— View job

---

Security Review — PR #879

• Load tools
• Read PR diff
• Audit changed files for security issues
• Post findings

---

Scope

Four files changed:

• plugins/session-flow/.claude-plugin/plugin.json — version bump only (0.12.2 → 0.12.3)
• plugins/session-flow/CHANGELOG.md — changelog entry only
• plugins/session-flow/skills/orchestrate/SKILL.md — imperative 7 text update
• plugins/session-flow/skills/orchestrate/context/sources.md — three new citation blocks

Findings

No security issues found.

All four changed files are pure documentation and instructional text. Here's the surface-by-surface audit:

Command/script injection — not applicable. None of the changed files contain shell scripts, template strings, or evaluated expressions. The skill file is a Markdown prompt loaded into agent context, not executed code.

GitHub Actions patterns — not applicable. No .github/workflows/ files were modified.

Secrets / credentials / PII — not present. The sources file contains only publicly-accessible Anthropic documentation URLs (code.claude.com, claude.com, platform.claude.com, anthropic.com). No tokens, API keys, or personal data appear anywhere in the diff.

Supply-chain / dependency risk — not applicable. No package manifests, action pins, or external dependencies were changed. The plugin.json version bump is a schema-valid semver increment with no new dependencies.

Authorization / access-control changes — none. The plugin.json does not modify permissions, scopes, or trust delegation. The disable-model-invocation: false field is pre-existing and unchanged.

Injection via external URLs in sources.md — the three new citation URLs are all first-party Anthropic documentation pages. They are referenced as read-only bibliography, not fetched at install time or evaluated at runtime. No redirect chains or third-party domains.

Plugin-form isolation — the skill correctly scopes to ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} in the pre-existing plugin structure; this PR introduces no new file-path references.

Summary

This is a content-only change to orchestration guidance text and supporting citations. There are no execution surfaces, no external trust delegation, no permission widening, and no secret handling anywhere in the diff.