Standard Proposal: name a model family, never pin a model version

[don-petry]

Story

As a maintainer,
I want the org standards to say that workflows name a Claude model family (opus, sonnet, haiku) and never a specific model version,
so that model upgrades don't leave stale pins across the fleet. The BMAD Business Analyst still runs claude-opus-4-6, two Opus generations behind.

The standard (maintainer decision, 2026-09-29)

Suggest a model family; never pin a model version. A caller may say which family suits the task (for example "Opus for the adversarial analyst pass"). It must not hard-code a version id such as claude-opus-4-6. One resolver maps family → current model id, and changes to it roll out through the normal release channels.

Allowed exceptions, each marked with an inline # model-pin-ok: <reason> comment:

• the resolver itself;
• price data keyed by real ids;
• recorded data (fixtures, eval sets, baselines);
• a fixed eval judge, which must stay pinned so A/B results stay comparable.

An operator-supplied override (a workflow input or an Actions variable set to a full id) is an operator choice and stays allowed. Only defaults in code must name a family.

The implementation and lint for petry-projects/.github-private is combsmith/.github-private#1979, under epic combsmith/.github-private#1895.

Current pins in this repo

File	Pin
.github/workflows/feature-ideation-reusable.yml L52–55 (model input)	default: 'claude-opus-4-6', and the description says "Opus 4.6 is the default and recommended"
standards/ci-standards.md L1318, L1394, L1417	documents claude-opus-4-6 / ANTHROPIC_MODEL: claude-opus-4-6 as the required setting
standards/workflows/feature-ideation.yml L8, L23 (and each synced copy)	comments naming "Opus 4.6 model selection"

(.github/scripts/add-to-project/initiative-rules.tsv mentions claude-sonnet-5 only inside a classification regex. That isn't a model pin, so leave it.)

Acceptance Criteria

1. Document the standard in standards/agent-standards.md as a new "Model selection" section, using the rule, the exceptions and the operator-override note above. Cross-link it from standards/ci-standards.md.
2. feature-ideation-reusable.yml. Change the model input default to the family opus, and reword the description to "Model family (opus recommended — Sonnet produces shallower adversarial passes) or an explicit model id override". The job passes it both as --model and through ANTHROPIC_MODEL, which ci-standards.md gotcha Add multi-agent isolation strategy using git worktrees #2 requires, so verify that claude-code-action / the Claude Code CLI accept the family alias there and resolve it to the current Opus. Record the resolved model id from the run's output or usage in the PR. If the alias doesn't resolve to the current Opus, resolve the family to an id in a small step before the job instead, and still never write a version into the default.
3. ci-standards.md. Replace the three claude-opus-4-6 statements with the family rule: ANTHROPIC_MODEL is set from the model input, which defaults to opus. Keep gotcha Add multi-agent isolation strategy using git worktrees #2's point that the env var must be set on the step.
4. Comments. Reword the "Opus 4.6 model selection" comments in standards/workflows/feature-ideation.yml to "Opus-family model selection". Don't edit synced copies in consumer repos by hand; they arrive through the standards sync.
5. Lint (optional but recommended). Add the same claude-(opus|sonnet|haiku|fable)-[0-9] check as .github-private#1979 to this repo's lint, skipping the allowed exceptions and model-pin-ok: lines.
6. Release. The reusable change ships through its channel tag via the Release Manager as usual. Don't hand-move tags.

Dev Notes

• This changes the analyst's actual model from Opus 4.6 to the current Opus. Say so in the PR's Risk section, and note that cost per run changes with the model's pricing.
• Don't dispatch the feature-ideation workflow from the PR. It spends tokens.

[github-actions[bot]]

Enhancement: Prior Art, Feasibility Confirmation & Implementation Options

Prior Art & Competitive Signal

OpenAI's alias strategy is the clearest cautionary tale. Their -latest suffixes (e.g., chatgpt-4o-latest) silently changed underlying weights, causing structured output failures, few-shot drift, and unpredictable cost/latency shifts — "model drift without a version increment." Their April 2026 deprecation wave hard-removed 25+ model IDs, breaking both alias users and pinned-snapshot users with 404s. Neither approach alone provides continuity; you need a managed transition layer.

The "model resolver" pattern is emerging as industry consensus. Open-source projects and internal platform teams increasingly use a central registry mapping logical roles → concrete model IDs. Benefits: single-point upgrade, canary-friendly rollout, auditable diffs. This proposal's "one resolver maps family → current model id" aligns directly with this pattern.

Anthropic's 4.6+ versioning simplifies things. Starting with the 4.6 generation, dateless IDs like claude-opus-4-6 ARE pinned snapshots, not evergreen pointers. There is no hidden alias layer at the API level. This eliminates the "silent drift" risk that plagued OpenAI's aliases — but it means the CLI's family alias resolution is the only auto-upgrade mechanism, and it ships compiled into each Claude Code release.

Technical Feasibility: Confirmed ✓

Claude Code CLI natively supports bare family aliases today. --model opus resolves client-side via expandModelString() before hitting the API. The raw Anthropic API does NOT accept bare family names — resolution is purely a CLI feature.

claude-code-action inherits this. Since claude_args passes through to the CLI, --model opus already works in workflows. The action also forwards ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL environment variables, providing an organizational override mechanism.

Provider-dependent resolution (key risk): The alias table is compiled per-release and varies by provider:

Provider	opus resolves to
Anthropic API (direct)	Current latest Opus
Claude Platform on AWS	Current latest Opus
Amazon Bedrock	May lag behind direct API
Microsoft Foundry	May lag further

For this repo (using direct Anthropic API via claude-code-action), resolution tracks the latest Opus. But downstream repos on different providers could get a different model for the same alias.

Implementation Options

Approach	Mechanism	Upgrade propagation	Auditability	Risk
A. Bare alias in workflow default (AC #2 as written)	default: 'opus' in reusable workflow input	Automatic on next claude-code-action bump (compiled alias table)	Low — cannot tell which model ran from workflow config alone; must check CLI version	Silent behavioral regression on CLI update
B. Alias + logged resolution (recommended)	default: 'opus' + emit resolved model ID to step summary / workflow output	Same as A, but regressions are traceable	Medium — resolved ID visible in run logs	Same as A, but detectable
C. Manifest file as resolver	standards/model-manifest.json maps roles → IDs; setup step reads it	Explicit PR to manifest, fans out via tag bump	High — change is a reviewable diff	Extra setup step per workflow; still need CLI or API to accept the resolved ID
D. Org-level variable	vars.ANTHROPIC_MODEL_FEATURE_IDEATION at org level	Instant on next run, no PR needed	Low — variable changes don't go through code review	Shadow config; hard to audit who changed what and when

Recommendation: Start with B, graduate to C if the fleet grows. Approach B satisfies the acceptance criteria with minimal complexity while adding the traceability that A lacks. A small echo "::notice::Resolved model: $(claude --print-model 2>/dev/null || echo unknown)" step (or equivalent) closes the auditability gap. Approach C makes sense if the org adds more model-consuming workflows beyond feature-ideation.

Risks & Unknowns

1. Behavioral regression on model upgrade. The whole point of this standard is to auto-upgrade, but a new Opus may handle the multi-skill pipeline's prompts differently. The acceptance criteria note the PR should document the model change in the Risk section — but there is no automated evaluation gate. Consider: could a subset of the adversarial-pass outputs be diffed against a baseline to detect regression?

2. Cost unpredictability. AC dev-note acknowledges "cost per run changes with the model's pricing." Current Opus 4.6 runs ~$2-3 per run (per ci-standards.md L1324). A future Opus could cost significantly more. Mitigation: the ANTHROPIC_DEFAULT_OPUS_MODEL env var lets operators pin back to a known-cost model without changing code.

3. CLI version coupling. The alias table ships compiled in each Claude Code release. If claude-code-action is pinned to an older version (Dependabot bumps lag), the "opus" alias may resolve to an older model than expected. This creates a hidden coupling between action version and model version.

4. AC Add multi-agent isolation strategy using git worktrees #2 verification gap. The acceptance criteria say to "verify that claude-code-action / the Claude Code CLI accept the family alias there and resolve it to the current Opus." Based on research, the CLI does accept it. However, ANTHROPIC_MODEL as an env var (ci-standards.md gotcha Add multi-agent isolation strategy using git worktrees #2) may behave differently from --model as a CLI flag — the env var goes to the API directly, while the flag goes through the CLI's resolver. This needs explicit testing: set ANTHROPIC_MODEL=opus (not --model opus) and confirm the CLI still resolves it rather than passing the bare string to the API.

5. Lint rule scope (AC Add stacked PR strategy and Epic-level workflow guidance #5). The regex claude-(opus|sonnet|haiku|fable)-[0-9] catches version pins but would NOT catch the env-var pattern ANTHROPIC_MODEL: claude-opus-4-6 in YAML values. Consider also linting YAML string values, not just shell/code identifiers.

Phased Validation Path

1. Phase 0 — Verify env var behavior (1 day). Run a local test: ANTHROPIC_MODEL=opus claude --version (or equivalent) to confirm the CLI resolves the env var through its alias table, not just the --model flag. This is the highest-risk unknown.

2. Phase 1 — PR with approach B (PR scope). Change the default, add resolution logging, update docs per acceptance criteria. Run one feature-ideation cycle with DRY_RUN=1 to confirm the resolved model ID appears correctly.

3. Phase 2 — Canary soak (1 week). Let one scheduled feature-ideation run execute with the new default. Compare output quality and cost against the previous Opus 4.6 baseline.

4. Phase 3 — Lint rule + fleet rollout. After soak, add the lint rule (AC Add stacked PR strategy and Epic-level workflow guidance #5) and let standards-sync propagate to downstream repos. The model-pin-ok: escape hatch handles legitimate exceptions.

5. Phase 4 — Manifest (optional, future). If additional model-consuming workflows appear (code review, PR triage, etc.), introduce standards/model-manifest.json as a central resolver.

Success Metrics

Metric	Target	How to measure
Model version pins in codebase	0 (excluding model-pin-ok: exceptions)	Lint rule CI check passes
Time-to-upgrade on new Opus release	< 1 week (action bump) vs current manual multi-file edit	Track elapsed time from Anthropic release to first run on new model
Feature-ideation output quality	No regression in adversarial-pass depth	Compare proposal count, adversarial objection quality, and Discussion engagement before/after
Cost per run	Within 2x of current baseline	Monitor via workflow billing or token usage logs
Fleet consistency	All repos resolve same model for same alias	Spot-check resolved model IDs across repos via step summary logs

[don-petry]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #1208 — Adopt the model-family standard (name a family, never pin a version) in petry-projects/.github

5 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Document the Model selection standard in agent-standards.md #1209 (S) — [Phase 1] Document the Model selection standard in agent-standards.md
• [Phase 2] Switch feature-ideation-reusable.yml model default to the opus family and verify alias resolution #1210 (M) — [Phase 2] Switch feature-ideation-reusable.yml model default to the opus family and verify alias resolution
• [Phase 2] Update ci-standards.md section 9 and the feature-ideation stub comments to the family rule #1211 (M) — [Phase 2] Update ci-standards.md section 9 and the feature-ideation stub comments to the family rule
• [Phase 3] Add a model-version-pin lint check wired into CI #1212 (M) — [Phase 3] Add a model-version-pin lint check wired into CI
• [Phase 4] Release the reusable feature-ideation change via its channel tag #1213 (S) — [Phase 4] Release the reusable feature-ideation change via its channel tag

Open questions for review:

• The current .github/workflows/feature-ideation-reusable.yml passes the model ONLY via --model ${{ inputs.model }} (L274) and sets NO ANTHROPIC_MODEL env var on the analyst step, yet ci-standards.md gotcha Add multi-agent isolation strategy using git worktrees #2 (L1394) documents an ANTHROPIC_MODEL: claude-opus-4-6 step env var. Stories 2 and 3 verify-then-reconcile this; confirm the intended mechanism is CLI-side --model family resolution (the raw API does not accept bare family names), so the docs match reality rather than a mechanism the workflow does not use.
• Out of scope for this initiative but flagged for a future decision (enhancement comment risk Addressing PR comments #1): whether to add an automated regression gate that diffs a subset of adversarial-pass outputs against a frozen baseline when the model auto-upgrades. If such an eval is ever built, its judge model must stay pinned as an allowed # model-pin-ok: exception so A/B results stay comparable.

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #1208 to hand it to initiative-driver for auto-implementation.