From 8189d2f098a682617a1620ff9206ee83ba5073a1 Mon Sep 17 00:00:00 2001 From: Behruz Nassre Esfahani Date: Thu, 2 Jul 2026 20:41:39 -0700 Subject: [PATCH] enhance(#1872): document Claude Code advisor inheritance in model profiles (#1922) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * enhance(#1872): document Claude Code advisor inheritance in model profiles Add an "Advisor Tool (Claude Code)" section to gsd-core/references/model-profiles.md: session-level advisor is inherited by all GSD subagents and composes with the per-agent profile/tier system, candidate executor/advisor pairings per profile (cost/quality/caching claims attributed to Anthropic's advisor-tool docs, not asserted as GSD behavior), when it is worth enabling vs not, and the session-level / no-per-agent-control constraint linking anthropics/claude-code#73072. Docs-only. Golden-install-parity fixtures recaptured for the edited reference file (hash-only, one line per runtime). Co-Authored-By: Claude Opus 4.8 (1M context) * chore(#1872): add changeset Co-Authored-By: Claude Opus 4.8 (1M context) * fix(#1872): use Documentation changeset type for docs-only change Changeset type was `Changed`, which triggers the docs-required lint (TRIGGERING_TYPES in scripts/lint-docs-required.cjs). This PR only touches gsd-core/references/model-profiles.md, so there is no docs/ file to pair with and docs-lint failed. `Documentation` is the correct type for a docs-only enhancement and is exempt from the trigger. Co-Authored-By: Claude Opus 4.8 (1M context) * fix(#1872): put docs-exempt marker on its own line, revert to type Changed The prior fix (type: Documentation) was invalid — parse.cjs ALLOWED_TYPES is {Added, Changed, Deprecated, Removed, Fixed, Security}, so both changeset-lint and docs-lint failed with invalid_type. Real root cause of the original docs-lint failure: DOCS_EXEMPT_RE is anchored to match the `` marker only on its own line, but the marker was tacked onto the end of the prose line, so it was never captured (docsExempt: null) and the triggering `Changed` fragment had no docs/ pairing -> fail_docs_missing. Fix: keep the valid `type: Changed` and move the marker to its own line. Verified locally: changeset-lint -> ok_fragment_present, docs-lint -> ok (own-line marker parses to ok_fragments_exempt). Co-Authored-By: Claude Opus 4.8 (1M context) --------- Co-authored-by: Claude Opus 4.8 (1M context) Co-authored-by: Tom Boucher --- .changeset/nimble-ibex-tumble.md | 7 +++++ gsd-core/references/model-profiles.md | 27 +++++++++++++++++++ .../golden-install-parity/antigravity.json | 2 +- .../golden-install-parity/augment.json | 2 +- .../golden-install-parity/claude.json | 2 +- .../fixtures/golden-install-parity/cline.json | 2 +- .../golden-install-parity/codebuddy.json | 2 +- .../fixtures/golden-install-parity/codex.json | 2 +- .../golden-install-parity/copilot.json | 2 +- .../golden-install-parity/cursor.json | 2 +- .../golden-install-parity/gemini.json | 2 +- .../golden-install-parity/hermes.json | 2 +- .../fixtures/golden-install-parity/kilo.json | 2 +- .../fixtures/golden-install-parity/kimi.json | 2 +- .../golden-install-parity/opencode.json | 2 +- .../fixtures/golden-install-parity/qwen.json | 2 +- .../fixtures/golden-install-parity/trae.json | 2 +- .../golden-install-parity/windsurf.json | 2 +- 18 files changed, 50 insertions(+), 16 deletions(-) create mode 100644 .changeset/nimble-ibex-tumble.md diff --git a/.changeset/nimble-ibex-tumble.md b/.changeset/nimble-ibex-tumble.md new file mode 100644 index 000000000..d9665dbae --- /dev/null +++ b/.changeset/nimble-ibex-tumble.md @@ -0,0 +1,7 @@ +--- +type: Changed +pr: 1922 +--- +Document Claude Code's advisor-tool inheritance in the model-profiles reference: the session-level advisor is inherited by all GSD subagents and composes with per-agent tiering, with candidate executor/advisor pairings, when it is worth enabling, and the session-level (no per-agent control) constraint. + + diff --git a/gsd-core/references/model-profiles.md b/gsd-core/references/model-profiles.md index 4a581b27a..52e3f7a8d 100644 --- a/gsd-core/references/model-profiles.md +++ b/gsd-core/references/model-profiles.md @@ -133,6 +133,33 @@ If you're using Claude Code with OpenRouter, a local model, or any non-Anthropic Without `inherit`, GSD's default `balanced` profile spawns specific Anthropic models (`opus`, `sonnet`, `haiku`) for each agent type, which can result in additional API costs through your non-Anthropic provider. +## Advisor Tool (Claude Code) + +Claude Code (v2.1.98+) can pair the session's executor model with a stronger **advisor** model that it consults mid-generation for strategy and course-correction (Anthropic's [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)). This is a host-runtime feature, not a GSD setting — GSD selects each agent's *executor* model through the profile/tier system above; Claude Code supplies the advisor. + +Set it once at the session level with `/advisor ` (or the `advisorModel` setting / `--advisor` flag). **Subagents inherit the session advisor automatically**, so every GSD subagent an orchestrator spawns gets the same advisor with no per-agent configuration. It composes cleanly with GSD's tiering: the profile keeps executors cheap where the work is mechanical, and the advisor adds a stronger reviewer inline on the turns that benefit. + +### Candidate pairings + +Per Anthropic's advisor-tool docs the advisor must be at least as capable as the executor. Candidate pairings by profile — evaluate on your own workload; the quality/cost characterizations below are Anthropic-reported, not GSD guarantees: + +| Profile | Typical executors | Candidate advisor | Rationale (per Anthropic docs) | +|---|---|---|---| +| `budget` | Haiku / Sonnet | Fable 5 or Opus | A step up in intelligence over Haiku alone, at lower cost than switching the executor to a larger model | +| `balanced` | Sonnet | Fable 5 or Opus | A quality lift at similar or lower total cost than Sonnet-solo on complex tasks | +| `quality` / `adaptive` | Opus (planning), Sonnet | Fable 5 or Opus | Marginal on turns already at top capability; most valuable on the Sonnet-executor agents | + +Fable 5 is a valid advisor for Haiku 4.5, Sonnet 4.6/5, and Opus 4.8 executors, so it pairs with any tier a profile assigns. + +### When it's worth enabling + +- **Worth it:** long, multi-step agent loops where the plan matters but most turns are mechanical — e.g. `execute-phase` and `debug`. Anthropic's docs note advisor prompt-caching pays off at roughly three or more advisor calls, which these long loops make. +- **Skip it:** short, one-shot agents (mappers, quick audits, single-file checks) — there is little to plan, and the advisor adds cost without a commensurate quality gain. + +### Constraint: session-level only (today) + +The advisor is a single session-wide setting inherited by all subagents; there is **no per-agent advisor selection**, so GSD cannot vary the advisor by role the way it varies the executor model (e.g. "no advisor on the Haiku mapper, a Fable 5 advisor on the Sonnet executor"). Per-agent advisor control is tracked upstream at [anthropics/claude-code#73072](https://github.com/anthropics/claude-code/issues/73072); until it lands, pick one session advisor that fits the most valuable agents in your run. + ## Dynamic Routing with Failure-Tier Escalation (#3024) When `dynamic_routing.enabled = true` in `.planning/config.json`, the resolver picks a model from a tier-mapped table based on the agent's *default tier* (light / standard / heavy) and escalates to the next tier up on orchestrator-detected soft failure. diff --git a/tests/fixtures/golden-install-parity/antigravity.json b/tests/fixtures/golden-install-parity/antigravity.json index 48cb823cb..f111b46e5 100644 --- a/tests/fixtures/golden-install-parity/antigravity.json +++ b/tests/fixtures/golden-install-parity/antigravity.json @@ -91,7 +91,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "de81380316d8a37f", - "gsd-core/references/model-profiles.md": "9e160d4e754b6b9e", + "gsd-core/references/model-profiles.md": "d6ed560db6357ad2", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "2459c40bfc8a0ea8", diff --git a/tests/fixtures/golden-install-parity/augment.json b/tests/fixtures/golden-install-parity/augment.json index f0aa107aa..8a3d0e809 100644 --- a/tests/fixtures/golden-install-parity/augment.json +++ b/tests/fixtures/golden-install-parity/augment.json @@ -160,7 +160,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "d3513252c5de5465", + "gsd-core/references/model-profiles.md": "8484ad9799b7f680", "gsd-core/references/mvp-concepts.md": "72f7e8b1f8ae7118", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/claude.json b/tests/fixtures/golden-install-parity/claude.json index 816053334..7f595a9f4 100644 --- a/tests/fixtures/golden-install-parity/claude.json +++ b/tests/fixtures/golden-install-parity/claude.json @@ -90,7 +90,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "d482387de75a44bc", + "gsd-core/references/model-profiles.md": "90e2c9bc577278fd", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/cline.json b/tests/fixtures/golden-install-parity/cline.json index f4db61250..640b6d0b4 100644 --- a/tests/fixtures/golden-install-parity/cline.json +++ b/tests/fixtures/golden-install-parity/cline.json @@ -94,7 +94,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "0941c3ab057c38a2", + "gsd-core/references/model-profiles.md": "eb144b83e31196b8", "gsd-core/references/mvp-concepts.md": "72f7e8b1f8ae7118", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/codebuddy.json b/tests/fixtures/golden-install-parity/codebuddy.json index 0c8a91bfd..b2bba8998 100644 --- a/tests/fixtures/golden-install-parity/codebuddy.json +++ b/tests/fixtures/golden-install-parity/codebuddy.json @@ -160,7 +160,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "d3513252c5de5465", + "gsd-core/references/model-profiles.md": "8484ad9799b7f680", "gsd-core/references/mvp-concepts.md": "72f7e8b1f8ae7118", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/codex.json b/tests/fixtures/golden-install-parity/codex.json index 6fda30e33..b3a405089 100644 --- a/tests/fixtures/golden-install-parity/codex.json +++ b/tests/fixtures/golden-install-parity/codex.json @@ -126,7 +126,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "da9d5fcb1cf6eb4b", + "gsd-core/references/model-profiles.md": "86e81f17c2f23fff", "gsd-core/references/mvp-concepts.md": "23201c8118fb074a", "gsd-core/references/phase-argument-parsing.md": "531176f66da49c98", "gsd-core/references/planner-antipatterns.md": "2459c40bfc8a0ea8", diff --git a/tests/fixtures/golden-install-parity/copilot.json b/tests/fixtures/golden-install-parity/copilot.json index 192fc4268..d43f4b721 100644 --- a/tests/fixtures/golden-install-parity/copilot.json +++ b/tests/fixtures/golden-install-parity/copilot.json @@ -92,7 +92,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "1d392e37a746742a", - "gsd-core/references/model-profiles.md": "9e160d4e754b6b9e", + "gsd-core/references/model-profiles.md": "d6ed560db6357ad2", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "2459c40bfc8a0ea8", diff --git a/tests/fixtures/golden-install-parity/cursor.json b/tests/fixtures/golden-install-parity/cursor.json index a3a58b398..f4c3b0fdd 100644 --- a/tests/fixtures/golden-install-parity/cursor.json +++ b/tests/fixtures/golden-install-parity/cursor.json @@ -160,7 +160,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "b7dccb17609c2a0f", + "gsd-core/references/model-profiles.md": "f4c013e700c52b08", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e562947d1bf5c5a4", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/gemini.json b/tests/fixtures/golden-install-parity/gemini.json index 80152ffe6..ef4e9f7e3 100644 --- a/tests/fixtures/golden-install-parity/gemini.json +++ b/tests/fixtures/golden-install-parity/gemini.json @@ -160,7 +160,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "d3513252c5de5465", + "gsd-core/references/model-profiles.md": "8484ad9799b7f680", "gsd-core/references/mvp-concepts.md": "72f7e8b1f8ae7118", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/hermes.json b/tests/fixtures/golden-install-parity/hermes.json index 2071f9ff4..c09777555 100644 --- a/tests/fixtures/golden-install-parity/hermes.json +++ b/tests/fixtures/golden-install-parity/hermes.json @@ -91,7 +91,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "2be36137de1ebb67", + "gsd-core/references/model-profiles.md": "8472d453a325cc1b", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/kilo.json b/tests/fixtures/golden-install-parity/kilo.json index 6882ab41d..fe2bd61aa 100644 --- a/tests/fixtures/golden-install-parity/kilo.json +++ b/tests/fixtures/golden-install-parity/kilo.json @@ -160,7 +160,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "9e160d4e754b6b9e", + "gsd-core/references/model-profiles.md": "d6ed560db6357ad2", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "2459c40bfc8a0ea8", diff --git a/tests/fixtures/golden-install-parity/kimi.json b/tests/fixtures/golden-install-parity/kimi.json index 16ec239b8..78a99cbef 100644 --- a/tests/fixtures/golden-install-parity/kimi.json +++ b/tests/fixtures/golden-install-parity/kimi.json @@ -127,7 +127,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "d3513252c5de5465", + "gsd-core/references/model-profiles.md": "8484ad9799b7f680", "gsd-core/references/mvp-concepts.md": "72f7e8b1f8ae7118", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/opencode.json b/tests/fixtures/golden-install-parity/opencode.json index 3d58ee4a5..c37251a7f 100644 --- a/tests/fixtures/golden-install-parity/opencode.json +++ b/tests/fixtures/golden-install-parity/opencode.json @@ -160,7 +160,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "858c16730df68ac2", - "gsd-core/references/model-profiles.md": "9e160d4e754b6b9e", + "gsd-core/references/model-profiles.md": "d6ed560db6357ad2", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "2459c40bfc8a0ea8", diff --git a/tests/fixtures/golden-install-parity/qwen.json b/tests/fixtures/golden-install-parity/qwen.json index 637d19cb4..d3eb2c9be 100644 --- a/tests/fixtures/golden-install-parity/qwen.json +++ b/tests/fixtures/golden-install-parity/qwen.json @@ -91,7 +91,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "8e209cb8ec89b0fb", + "gsd-core/references/model-profiles.md": "cc1efc2942164744", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e5bbb985f3bc3e34", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/trae.json b/tests/fixtures/golden-install-parity/trae.json index 884c6a3d8..e9c453dc3 100644 --- a/tests/fixtures/golden-install-parity/trae.json +++ b/tests/fixtures/golden-install-parity/trae.json @@ -91,7 +91,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "88c4308630f27f48", + "gsd-core/references/model-profiles.md": "41b0af6f5f77af81", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e562947d1bf5c5a4", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac", diff --git a/tests/fixtures/golden-install-parity/windsurf.json b/tests/fixtures/golden-install-parity/windsurf.json index b7d2353b1..dc0e26256 100644 --- a/tests/fixtures/golden-install-parity/windsurf.json +++ b/tests/fixtures/golden-install-parity/windsurf.json @@ -91,7 +91,7 @@ "gsd-core/references/loop-hook-dispatch.md": "32e5dfb4dba76987", "gsd-core/references/mandatory-initial-read.md": "fe59abce693717cf", "gsd-core/references/model-profile-resolution.md": "f32bb05102839767", - "gsd-core/references/model-profiles.md": "7f812fafd1fe4b52", + "gsd-core/references/model-profiles.md": "b3ac5dc094bce1dc", "gsd-core/references/mvp-concepts.md": "3464783eaaef5c10", "gsd-core/references/phase-argument-parsing.md": "e562947d1bf5c5a4", "gsd-core/references/planner-antipatterns.md": "7ed54ec1e2cc54ac",