Repository navigation
[Phase 1] Document the Model selection standard in agent-standards.md #1209
Description
Story
As a standards maintainer,
I want add a canonical "Model selection" section to standards/agent-standards.md capturing the family-not-version rule, its exceptions and the operator-override note, and cross-link it from ci-standards.md,
so that there is one authoritative rule the reusable-workflow, docs and lint stories can all reference instead of each restating it.
Acceptance Criteria
- standards/agent-standards.md gains a new "## Model selection" section stating the rule: a caller may suggest a model family (
opus,sonnet,haiku) suited to the task, but must not hard-code a version id such asclaude-opus-4-6; one resolver/CLI maps family -> current model id and changes roll out through normal release channels. - The section lists the four allowed exceptions, each requiring an inline
# model-pin-ok: <reason>comment: (a) the resolver itself, (b) price data keyed by real ids, (c) recorded data (fixtures, eval sets, baselines), (d) a fixed eval judge that must stay pinned so A/B results stay comparable. - The section states the operator-override rule: an operator-supplied full model id (a workflow input or an Actions variable) is an operator choice and stays allowed; only defaults in code must name a family.
- standards/ci-standards.md cross-links the new agent-standards.md "Model selection" section, and the existing stale "Opus 4.6 model selection" phrasing in agent-standards.md's "BMAD Method Workflows" section is updated to reference the family rule (e.g. "Opus-family model selection").
- The rule is stated once in agent-standards.md (single source of truth); ci-standards.md references it rather than duplicating the full text.
Tasks / Subtasks
- Add the "## Model selection" H2 section to standards/agent-standards.md with the rule, the four exceptions, and the operator-override note. (AC: Addressing PR comments #1, Add multi-agent isolation strategy using git worktrees #2, Add coding standards & principles section to AGENTS.md #3)
- Update the stale "Opus 4.6 model selection" mention in agent-standards.md's "BMAD Method Workflows" section (~L127) to reference the family rule. (AC: Add workflow, environment, and orchestration guidance #4)
- Add a cross-link from standards/ci-standards.md to the new section, keeping ci-standards.md a reference (not a second copy of the rule). (AC: Add workflow, environment, and orchestration guidance #4, Add stacked PR strategy and Epic-level workflow guidance #5)
- Run markdownlint (markdownlint-cli2, as ci.yml's Lint job does) locally and fix any heading/format findings. (AC: Addressing PR comments #1)
Dev Notes
- Target file
standards/agent-standards.mdis ~128 lines. Its "## BMAD Method Workflows" section (~L118-127) currently says "...critical configuration gotchas (Opus 4.6 model selection, GitHub token override, log-secret hygiene)" - that is the stale mention to reword to the family rule. - This is the FOUNDATIONAL story: Stories 2-4 reference this section, so land it first. Keep the full rule text here only; ci-standards.md section 9 (Story 3) links back to it.
- Cross-link target lives in standards/ci-standards.md section 9 (Feature Ideation). Use a stable anchor.
- Testing standard: markdown is linted by the
Lint Markdownstep (DavidAnson/markdownlint-cli2-action) in .github/workflows/ci.yml. No code/tests here - doc-only. - Do NOT restate the exceptions list in multiple files; one canonical copy avoids drift when the standard evolves.
Project Structure Notes
standards/agent-standards.md and standards/ci-standards.md are org-wide standards docs in the target repo petry-projects/.github. Adding a new H2 aligns with the file's existing heading structure; no structural conflict.
References
- https://github.com/petry-projects/.github/blob/main/standards/agent-standards.md
- https://github.com/petry-projects/.github/blob/main/standards/ci-standards.md
- discussion Standard Proposal: name a model family, never pin a model version #1199
Likely target surface
petry-projects/.github: standards/agent-standards.md (new 'Model selection' H2; reword stale mention ~L127)petry-projects/.github: standards/ci-standards.md (cross-link to the new section)
Story prepared by the BMAD Scrum Master (Bob) for epic #1208. Status: ready-for-dev.
Activity
don-petry commentedon Oct 1, 2026
Dev-Lead Implementation Plan
Issue: #1209 — [Phase 1] Document the Model selection standard in agent-standards.md
Scope
Add a canonical "## Model selection" section to
standards/agent-standards.md(the family-not-version rule, its four pinning exceptions, and the operator-override note), reword the stale "Opus 4.6 model selection" mention to the family rule, and cross-link the new section fromstandards/ci-standards.md§9 — keeping the full rule text in one place.Implementation Checklist
standards/agent-standards.md: add a new## Model selectionH2 with the family-not-version rule (AC Addressing PR comments #1), the four# model-pin-ok: <reason>exceptions — resolver, price data, recorded data, fixed eval judge (AC Add multi-agent isolation strategy using git worktrees #2), and the operator-override note (AC Add coding standards & principles section to AGENTS.md #3)standards/agent-standards.md: reword the stale "Opus 4.6 model selection" mention in the "BMAD Method Workflows" section (~L126) to the family rule, e.g. "Opus-family model selection" (AC Add workflow, environment, and orchestration guidance #4)standards/ci-standards.md: add a cross-link from §9 (Feature Ideation) to the newagent-standards.md#model-selectionsection, keeping ci-standards.md a reference, not a second copy of the rule (AC Add workflow, environment, and orchestration guidance #4, Add stacked PR strategy and Epic-level workflow guidance #5).dev-lead/scripts/dev-lead-lint.sh; fix any findingsTests to Write
Lint MarkdownCI step) plus the repo lint script.Test Command
npx markdownlint-cli2 "standards/agent-standards.md" "standards/ci-standards.md"andbash .dev-lead/scripts/dev-lead-lint.shdon-petry commentedon Oct 1, 2026
Dev-Lead: Progress (in progress — not yet durable)
Plan Execution (intended)
## Model selectionH2 tostandards/agent-standards.md: the family-not-version rule (opus/sonnet/haiku, no hard-coded ids likeclaude-opus-4-6, one resolver maps family → id), the four# model-pin-ok: <reason>exceptions (resolver, price data, recorded data, fixed eval judge), and the operator-override note.standards/ci-standards.md§9 (Feature Ideation, gotcha Add multi-agent isolation strategy using git worktrees #2) back toagent-standards.md#model-selection, keeping ci-standards.md a reference rather than a second copy of the rule.Local check output (provisional — not the pushed run)
Files touched (this workspace, not yet pushed)
standards/agent-standards.md: new## Model selectionsection; reworded stale BMAD mention.standards/ci-standards.md: §9 cross-link to the new section.Notes
Single source of truth kept in agent-standards.md; ci-standards.md only references it. The reusable's own
claude-opus-4-6env config is left unchanged — out of scope for this doc-only story (later stories cover code/lint).don-petry commentedon Oct 1, 2026
Dev-Lead: Implementation Complete — PR #1216
The implementation for issue #1209 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.
fc5b46a9dbb02f53e006f7c873f572ca9de61f2cmain: 2 file(s), +45/-3 linesReview happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.
feat: implement issue #1209 — [Phase 1] Document the Model selection …