Repository navigation
docs: lead model-choice guidance with default routing and model: router - #76985
Conversation
Co-authored-by: SivaKesava1 <11771739+SivaKesava1@users.noreply.github.com>
model: router
|
Category: docs | Risk: low | Score: 29/100
|
Co-authored-by: SivaKesava1 <11771739+SivaKesava1@users.noreply.github.com>
|
Verified against #76983:
Only the four files change. Round 1 ( |
|
✅ Ponytail Reviewer completed successfully! Ponytail ReviewerOutcome: The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅
|
|
✅ PR Code Quality Reviewer completed the code quality review.
|
|
✅ Test Quality Sentinel completed test quality analysis. Test Quality SentinelOutcome: The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
|
✅ PR Specification Reviewer completed successfully! PR Specification ReviewerOutcome: The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible. Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.
|
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs and /codebase-design to the routing docs. The PR is docs-only, so the review checked factual claims against the implementation rather than test coverage. Four inline comments follow, all clarity or consistency items. No blocking issues.
📋 Verification and key themes
Verified
- ✅ Internal links and anchors in the four edited pages resolve.
- ✅ The
smallalias resolves on both the Copilot and Claude harnesses. - ✅ The
default_model_claudeanddefault_model_copilotkeys are valid inpkg/cli/env_command.go. - ✅ The Codex no-default-model wording matches the compiler fallback, which is an empty string.
- ✅ The nightly-triage example compiles with
gh aw compile --dry-runbuilt from this checkout, and it does not needcopilot-requests: write.
Key themes
- Router-value placement: the nightly example YAML shape is inconsistent with the rest of the page.
- Duplicated eligibility rules:
syntax-agentic.mdrestatesmodel-routing.md, so the two can drift. - Readability: the Codex sentence and the
default_model_claudeexample each carry more than one rule.
Positive highlights
- ✅ Cross-linking to
model-routing.mdfor default routing is consistent across the pages. - ✅ The distinction between
model: autoandmodel: routeris now stated explicitly, which removes a real ambiguity. - ✅ The
default_model_*note correctly warns that a router value there stops the run before the agent starts.
@copilot please address the review comments above.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · routed: haiku55 xhigh · ~8 AIC · ⌖ ~2 AIC · ⊞ 6.6K
Comment /matt to run again
|
🍳 A little prep to help this PR along! Copilot assignment requested for the following outstanding work:
Keeping the changes focused; human review and CI get the final taste test. No merging or CI triggering. Structured data{
"completed_task": 0,
"head": "a6786ca15c459fe5e0916e5a173a8edf3608d8e3",
"kind": "requested",
"schema_version": "1",
"state": "bf258de9e580c4d765163df09ab00afc90c143f9b97af231cc1259ccf8e4f071",
"work": [
"0eb5d7bece38aa29fe8d95f673eca03eb90aedfe12ac3bb915da342aa64e57e6",
"1532e6a8e05e23c3eba143eaa78d4f8afad6896cc4c53adcd25dbba2a68b2819",
"294361954328758b00a8a3e7c8c4597acd573db17f62d110000413b2907cb944",
"2bac51e4011afa6070e6c12a465861345d7345f29e772adbcc023efccc5c46aa"
],
"workflow": "pr-sous-chef"
}
|
…el-choice-guidance Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
The shared-defaults documentation still removes the explicit model alias instead of updating it to the required non-stale example, leaving the documented override behavior incomplete.
1 open issue
What changed in this PR
This documentation PR updates model-selection guidance to prefer eligible gh-aw default routing or explicit router values when a workflow does not require a specific model, while clarifying provider-specific behavior and preserving explicit model selection.
Changes:
- Updates cost-management guidance for default routing, economy routing, dynamic selectors, and shared model defaults.
- Clarifies native OpenAI versus GitHub Copilot routing behavior for Codex.
- Adds router values and routing recommendations to the authoring syntax reference.
- Distinguishes provider-level
model: autofrom gh-awmodel: router. - The shared-defaults sample removes
default_model_claudeinstead of replacing its stale value with the requestedsmallalias.
| File | Description |
|---|---|
| docs/src/content/docs/reference/model-routing.md | Distinguishes provider or engine model: auto selection from gh-aw model: router behavior. |
| docs/src/content/docs/reference/engines/codex.md | Clarifies native OpenAI model behavior and GitHub Copilot default routing. |
| docs/src/content/docs/reference/cost-management.md | Updates cost guidance, routing examples, dynamic selectors, and shared-default behavior. |
| .github/aw/syntax-agentic.md | Documents router values and advises authors when to omit or explicitly set model. |
Review effort: Lite (auto)
|
Category: docs
|
|
@copilot Please widen this PR to also simplify the Model Routing page. #76983 said to leave the rest of Why Routing a workflow now takes one line. With Router values cover nearly every example on the page. With gh-aw built from
Only a shortlist in model-routing.md Aim for roughly half the current length, in this order:
The list of rejected router values and placements (unknown Stale facts on the page Checked against AWF v0.29.12, which gh-aw now pins by default:
Other pages
Done when
|
…el-choice-guidance Co-authored-by: rabeckett <5445735+rabeckett@users.noreply.github.com>
Co-authored-by: rabeckett <5445735+rabeckett@users.noreply.github.com>
Updated in 1149308. Guidance tests, the scoped gate, and routing example compilation pass. The docs build remains blocked by DNS failures for the configured npm registry and approved 1ES feed. |
|
🎉 This pull request is included in a new release. Release: |

Several docs and authoring-guide passages still taught model choice as if every workflow must pin a model and
model: routerdidn't exist. This PR leads with routing when a task has no specific model requirement, and, at @rabeckett's request (comment), rewrites the Model Routing page aroundmodel: router. Explicit model selection stays as the alternative. Docs only.Changes
reference/model-routing.md: rewritten around router values, about half the previous length (4,743 → 2,266 words):model: routerexample, explains that the router picks economy, balanced or robust per task (balanced when it can't classify), and notes thatmodel: autois the engine's own selector, not gh-aw routing.router/economy,router/balancedandrouter/robust, merged with the old mode table.engine.model-routing: falseor a pinned model opts out), with the full eligibility list collapsed. The#default-routing-for-workflows-without-a-modelanchor is kept.goal: cost-speed,allowed-modelsshortlists, a policy combined with a shortlist, shared routing settings, and the router value restrictions (moved out of Get started).reference/cost-management.mdmodelalready behaves likemodel: router) andmodel: router/economy, which sets the lowest success target, not a spending cap. Explicit selection follows: an alias such assmallcan resolve to a different model over time, and an exact ID is how to require one specific model.model: router/economyinstead ofgpt-4.1-mini.model: autoexample and saysautois the engine or provider's selector, not gh-aw's router.default_model_*entries from the sample (a sample model default would opt eligible workflows out of routing) and says those variables are explicit overrides that opt out of default routing and must not holdrouterorrouter/*values.gpt-4.1-miniorclaude-haiku-4-5examples remain.reference/engines/codex.md: "no default model" applies only to the native OpenAI provider, wheremodel: routerroutes on OpenAI; a separate paragraph says eligible Codex workflows onmodel-provider: githubroute by default.reference/frontmatter.md: theengine.model-routingparagraph is one sentence pointing to the advanced section..github/aw/syntax-agentic.md: the top-levelmodel:entry lists the four router values, linkssyntax-engine.md, and says: unless the task needs a specific model, usemodel: routeror arouter/level; eligible workflows with no model already route the same way (with a link to the eligibility rules).Acceptance cases and validation
goal: cost-speeduses a router value;engine.model-routingappears only in the advanced section apart from thefalseopt-out; Get started has one example and no compiler-rejection list; anchors linked from other pages (#default-routing-for-workflows-without-a-model,#native-anthropic-and-openai-routing,#advanced-engine-model-routing) resolve.buildcheck passes in CI. Routing examples compile with gh-aw built frommain.make test-guidancefailstest_debug_playbook_agent_consumption_budget(debug guide word count 2870 > 2800) the same way onmain, so it's left alone.