agentic-sdlc-wizard 1.80.0 → 1.82.0

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "sdlc-wizard",
       "source": ".",
       "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
-      "version": "1.80.0",
+      "version": "1.82.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-wizard",
-  "version": "1.80.0",
+  "version": "1.82.0",
   "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
   "author": {
     "name": "Stefan Ayala",

package/AI_SETUP_LANES.md

@@ -0,0 +1,217 @@
+# AI Setup Lanes
+
+Three recommended AI coding setups for this repo. Setups A and B are complete triads: **planner → driver → reviewer**. Setup C is a lightweight driver-only lane for operational grunt work.
+
+This is **guidance, not a hard rule**. Maintainer override is always allowed.
+
+## Setup A — Claude Premium
+
+| Role | Model |
+|------|-------|
+| **Advisor** | Fable 5 (via `advisorModel: "fable"` in project settings — auto-consults at key decisions) |
+| **Driver** | Opus 4.6 max |
+| **Reviewer** | Codex (GPT-5.5) xhigh |
+| **Escalation** | + Fable 5 review (security, releases, wide-blast architecture only) |
+
+Quality-first lane. Fable 5 advises automatically at key decision points (architecture, complexity, blast-radius) via native `advisorModel` (v2.1.170+), Opus 4.6 max implements (stable, Max-bundled), GPT-5.5 xhigh reviews (cross-family, free on ChatGPT sub, catches blind spots Fable can't see in its own work). Escalate to Fable review for the ~5% of PRs where stakes justify it.
+
+**Effort levels:** Opus driver at `max` (standing default). Fable advisor runs at its own effort level server-side. If switching driver to Fable temporarily (fallback), use `/effort high` — Fable `high` already exceeds prior models at `max`. Unset `CLAUDE_CODE_EFFORT_LEVEL` env var if it forces `max`.
+
+## Setup B — Claude Saver (OpusPlan)
+
+| Role | Model |
+|------|-------|
+| **Planner** | Opus 4.6 max (via Plan Mode — Shift+Tab) |
+| **Advisor** | Opus 4.6 (via `advisorModel: "claude-opus-4-6"` — compensates for Sonnet driver) |
+| **Driver** | Sonnet (latest, auto execute mode) |
+| **Reviewer** | Codex (GPT-5.5) xhigh |
+
+Cost-efficient lane using CC's native `opusplan` alias. Opus reasons during Plan Mode (Shift+Tab), Sonnet executes. Both 200K context, Max-bundled — no API credit drain. Pin `model: "opusplan"` + `advisorModel: "claude-opus-4-6"` + `CLAUDE_CODE_EFFORT_LEVEL=max` in project settings. The Opus advisor auto-compensates for Sonnet's lighter reasoning at key decision points. GPT-5.5 xhigh is the cross-model reviewer.
+
+## When to Use Setup A
+
+Reach for Premium when the change can damage a consumer repo or has high blast radius:
+
+- Architecture or methodology changes
+- Tagged release prep
+- Installer behavior (`cli/`, `init`, `setup-wizard`)
+- Destructive file operations
+- Package publishing
+- Generated repo modifications (template changes)
+- CI / release automation
+- Security-sensitive behavior
+- Anything that could damage a consumer repo
+
+## When to Use Setup B
+
+Setup B is sufficient for routine work where a Sonnet driver can ship with a strong reviewer:
+
+- Routine implementation
+- Documentation
+- Examples
+- Tests
+- Normal CLI changes (non-installer)
+- Low-risk methodology edits
+- Mechanical refactors
+
+## Setup C — Claude Lite
+
+| Role | Model | Notes |
+|------|-------|-------|
+| **Planner** | You (the user) | Task is pre-planned, no model reasoning needed |
+| **Driver** | Sonnet 4.6 | Same model as Setup B driver — Max-bundled, no extra model to manage |
+| **Reviewer** | None | Blast radius too low for cross-model overhead |
+
+The "just do the thing" lane. No TDD enforcement, no cross-model review, no planning phase. You already know what to do — you just need a fast, cheap pair of hands.
+
+## When to Use Setup C
+
+Setup C is for work where SDLC discipline overhead exceeds the value:
+
+- Run a script with basic intelligence
+- Deploy to staging (prod deploys need Setup A's discipline — human gate + rollback plan)
+- Config updates, env var changes
+- File moves, renames, bulk operations
+- Repo maintenance (dependency bumps, lockfile refreshes)
+- Simple administrative tasks across repos like `~/afterhours`
+- Anything where blast radius is low and you need speed, not depth
+
+**Not Lite — escalate to A or B:** env vars that touch secrets or credentials, dependency bumps with security advisories, destructive bulk ops (rm -rf, drop table), migrations, prod-like shared staging, anything security-sensitive. If you're unsure, it's not Lite.
+
+## What Setup C explicitly skips
+
+- No TDD (no test-first for running a deploy script)
+- No cross-model review (not worth the cost or time for grunt work)
+- No planning phase (you are the planner)
+- No effort escalation (Sonnet standard is plenty)
+
+**The discipline of knowing when NOT to use discipline.** Documenting this lane tells users "here's when to switch off the heavy methodology" rather than silently tempting them to skip it. If the task turns out to be harder than expected, escalate to Setup B or A.
+
+## Final Review Policy
+
+**Setups A and B end at GPT-5.5 xhigh as the cross-model reviewer.** Claude can't grade its own homework — the reviewer always belongs to a different lab with different blind spots. See [CLAUDE_CODE_SDLC_WIZARD.md → "Cross-Model Review (Codex)"](CLAUDE_CODE_SDLC_WIZARD.md) for the handoff protocol.
+
+**Setup C has no reviewer** — the blast radius doesn't justify it. If you're unsure whether a task is truly Lite, it probably isn't. Escalate.
+
+If GPT-5.5 isn't available on your OpenAI account, Codex auto-falls back to GPT-5.4 — still keep `model_reasoning_effort="xhigh"`. Lower reasoning misses subtle bugs that the reviewer is the last gate to catch.
+
+## Version Requirement
+
+`advisorModel` in settings.json requires **Claude Code v2.1.170+**. Check your version with `claude --version`. If below v2.1.170, update from inside a CC session:
+
+```
+! claude update
+```
+
+The `!` prefix runs shell commands inside your CC session — no need to exit and re-enter. After updating, restart the session for the advisor to activate.
+
+Fable 5 as advisor also requires Fable 5 access for your organization/plan (free on Max through June 22, 2026).
+
+## When the Advisor Is Unavailable
+
+If the advisor returns "Advisor unavailable," the server-side harness failed to initialize. No in-session action (`/model`, `/clear`) can recover it.
+
+**Step 1 — restart the session.** Exit and run `claude` (not `--resume`). A fresh process re-initializes the server handshake. This resolves most advisor failures.
+
+**Step 2 — if the API incident persists:**
+
+- `/model fable` + `/effort high` for the planning phase, then `/model claude-opus-4-6` for implementation. Interactive — stays on your Max subscription.
+- Or proceed with Opus only and let the Codex xhigh PR gate catch issues.
+
+**Last resort (scripted/CI only):**
+
+- `claude --model fable --effort high -p "$(cat <file>)"` — headless mode bills API credits, not your Max subscription.
+
+Check [status.claude.com](https://status.claude.com) if the advisor fails across multiple fresh sessions.
+
+Whichever path you use, the cross-model PR review gate still applies.
+
+## Credit-Spend Warning
+
+Setups A and B use Opus 4.6 max for at least the planner — that's the expensive half. On Max-plan subscriptions, **Premium can burn the 5-hour cap faster than Saver** because Opus 4.6 max drives implementation too. If you're hitting the cap mid-session:
+
+- Drop to Setup B for the remainder of the day
+- Or drop to Setup C for grunt work that doesn't need Opus reasoning
+- Or use Sonnet directly for the final mechanical edits, then run the GPT-5.5 reviewer over the whole diff at the end
+
+**Setup C uses Sonnet** — same model as Setup B's driver, Max-bundled. One less model to manage.
+
+The reviewer (GPT-5.5 xhigh) is billed against your OpenAI account, separately. Watch both bills.
+
+## Autocompact Thresholds
+
+For recommended `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` values per context window and task shape, see [CLAUDE_CODE_SDLC_WIZARD.md → Autocompact Tuning](CLAUDE_CODE_SDLC_WIZARD.md#autocompact-tuning).
+
+## How Billing Works — 1M Context, Max Plan, and the June 15 Split
+
+A common question: **"does the `[1m]` model alias get billed differently? Does it pull from my Max plan or from API credits?"**
+
+The short answer: **Setup A uses Fable advisor + Opus driver (both Max-bundled in interactive sessions). Setup B is fully Max-bundled via opusplan + Opus advisor.** Here's the detail.
+
+### 1M context is free on Max — no API premium
+
+[Anthropic 2026-03-13](https://claude.com/blog/1m-context-ga): 1M context is GA at standard $5/$25 per million tokens for Opus 4.6 (also 4.7, 4.8). No long-context multiplier. **No beta header required**, requests over 200K tokens just work.
+
+For Claude Code on Max / Team / Enterprise plans, **1M context is included automatically** with no extra usage allocation. Whether you set `claude-opus-4-6` or `claude-opus-4-6[1m]` doesn't change *what* you're billed — both pull from the same per-token budget on your subscription. The `[1m]` suffix just makes the alias explicit so it sticks across alias-resolution changes; functionally Opus 4.6 in Claude Code today *is* the 1M-context model on a Max plan.
+
+(Pro plan is the exception: Pro users need "Enable usage credits" turned on in their Claude account settings to use 1M context. Max / Team / Enterprise have it on by default.)
+
+### The June 15, 2026 billing split
+
+[Anthropic moved a slice of usage off the subscription](https://codersera.com/blog/anthropic-june-2026-billing-change-claude-code/) onto a separate metered credit pool that bills at full API rates:
+
+| Surface | Billing as of June 15, 2026 |
+|---|---|
+| **Interactive Claude Code in terminal** (you typing into Claude Code right now) | **Stays on Max subscription** — unchanged |
+| Claude.ai web / desktop / mobile chat | Stays on Max subscription |
+| Claude Cowork | Stays on Max subscription |
+| `claude -p` (headless / `--print`) | **Moves to separate credit pool**, billed at API rates |
+| Claude Agent SDK | Moves to separate credit pool |
+| Claude Code GitHub Actions | Moves to separate credit pool |
+| Third-party apps via Agent SDK | Moves to separate credit pool |
+
+Credit allocations: Pro $20/mo, Max 5x $100/mo, Max 20x $200/mo. **No rollover.**
+
+### What this means for the lanes
+
+- **Setup A — Premium (Fable advisor + Opus driver):** Fable 5 advisor via `advisorModel: "fable"` in project settings — interactive session, Max-bundled. Opus 4.6 max driver on Max. GPT-5.5 xhigh reviewer on ChatGPT subscription.
+- **Setup B — Saver (OpusPlan):** **fully Max-bundled.** `opusplan` uses Opus (plan mode) + Sonnet (execute mode), both at 200K context — no `[1m]` variants, no credit drain. This is why Setup B now recommends `opusplan` instead of the old `sonnet[1m]` pin (#390).
+  - **⚠️ Avoid `sonnet[1m]`:** Sonnet with 1M context draws from your usage credits pool ($3/$15 per Mtok), NOT your Max subscription. The `/model` picker shows this explicitly. Plain `sonnet` (200K) or `opusplan` stays on Max.
+- **Reviewer (GPT-5.5 xhigh) in both lanes:** billed against your OpenAI account, completely separate from Anthropic.
+- **CI loops that use `claude -p` post-June-15:** these now bill against the separate Anthropic credit pool, not your Max subscription. The wizard's CI shepherd loops (E2E scoring, weekly-update jobs) are local-only on the maintainer's machine and stay on Max; consumer-repo CI integrations may need to budget the new credit pool.
+
+### Caveat: Setup B's cost-saving has conditions
+
+The savings argument for Setup B is "Sonnet driver is cheaper than Opus driver per turn." **That's true at standard 200K context.** If your Sonnet driver needs to load >200K tokens (large diff, multi-file refactor, monorepo audit), the bill quietly flips:
+
+| Mode | Per-token rate | Pool |
+|---|---|---|
+| Setup A — Opus 4.6 1M | $5/$25 per Mtok | **Max subscription** |
+| Setup B — Sonnet 4.6 standard | $3/$15 per Mtok | **Max subscription** |
+| Setup B — Sonnet 4.6 1M | $3/$15 per Mtok | **Credits pool** |
+
+So **for context-heavy work that crosses 200K, Setup A on Max is actually cheaper than Setup B on credits** — because Setup A's Opus stays on the Max pool while Setup B's Sonnet 1M draws down a separately-metered $100/mo (Max 5x) or $200/mo (Max 20x) credit budget.
+
+**Practical guidance:**
+
+- **Subscription-first mindset (recommended):** Use Setup A unless you're confident the Sonnet driver in Setup B stays under 200K context. The Opus 4.6 max planner+driver combo lives entirely on Max — no credit-pool drawdown.
+- **Setup B is a real cost win only when:** the driver task fits in ≤ 200K (routine implementation, single-file work, small refactors, docs). Use B specifically for those, not as a blanket choice.
+- **Watch the picker.** When you swap to Sonnet 1M, Claude Code shows "Draws from usage credits" explicitly. That's your billing flip signal — choose Opus 1M instead if you want to stay on Max.
+
+### Bottom line
+
+If you're using Claude Code interactively (you, in your terminal, doing `/sdlc` work), **both lanes ride your existing Max subscription**, and the `[1m]` alias is the same billable budget as plain `claude-opus-4-6`. No extra charges for the 1M context. The June 15 split only affects programmatic / headless / CI use of Claude Code.
+
+Watch the headless surface if you've automated `claude -p` calls in your project — those now bill differently as of June 15, 2026.
+
+## Maintainer Override
+
+**Override at any time.** A blanket setup choice doesn't replace judgment per change. If you're touching CI but the change is a one-line typo, Setup B is fine. If you're touching docs but the section is the wizard's safety-critical hook ordering, Setup A is the call.
+
+The wizard does not enforce setup lane selection — it documents the recommended default per change shape. Whatever ships is your call.
+
+## See Also
+
+- [`CLAUDE_CODE_SDLC_WIZARD.md`](CLAUDE_CODE_SDLC_WIZARD.md) — Full wizard doc, including Stability tier opt-in for the wider model choice
+- [`README.md` § Choosing Your Model](README.md#choosing-your-model) — Model selection philosophy
+- [`AGENTS.md`](AGENTS.md) — Codex/reviewer guidelines used in both lanes

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to the SDLC Wizard.
 
 > **Note:** This changelog is for humans to read. Don't manually apply these changes - just run the wizard ("Check for SDLC wizard updates") and it handles everything automatically.
 
+## [1.82.0] - 2026-06-11
+
+### Added
+
+- **"Reading Usage Signals" subsection** in Token Efficiency section. Maps community-observed session signals (subagent-heavy, >150K context, 8+ hour sessions) to SDLC actions per setup lane. Marked as community-observed, not official CC docs.
+
+- **Advisor fallback procedure** in AI_SETUP_LANES.md. Escalation ladder: restart session → Fable driver fallback → `-p` last resort (with billing caveat). Documented after advisor was unavailable for a full session during API incident (2026-06-11).
+
+- **Fable effort guidance** in Setup A description. Opus stays at `max`; Fable at `high` (exceeds prior models at `max`). Unset `CLAUDE_CODE_EFFORT_LEVEL` env var if switching driver to Fable temporarily.
+
+- **Autocompact Thresholds cross-reference** in AI_SETUP_LANES.md. Numbers-free pointer to wizard doc to prevent dual-source drift.
+
+### Fixed
+
+- **Stale `/usage` row** in Monitor Costs table. Was "Session total: USD, API time, code changes" — now accurately describes plan usage limits and per-category breakdown (skill, subagent, plugin, MCP server). Added `/status` row (settings panel) to prevent future confusion.
+
+- **`/usage` mention in SKILL.md** Context Management section. Folded into existing auto-compact bullet within 20K char budget.
+
+### Why
+
+- Token-burn spike (1.36M costly tokens vs ~86K median) in session 98d6c7b0 surfaced that the wizard's usage guidance was stale and didn't help diagnose the cause. The Monitor Costs table described `/usage` incorrectly, and no wizard prose mapped usage signals to SDLC actions. The advisor fallback procedure is a direct lesson from the same session where the Fable advisor was unavailable for the entire duration.
+
+## [1.81.0] - 2026-06-10
+
+### Changed
+
+- **Native `advisorModel` support (CC v2.1.170+).** Setup A (Premium) now uses `advisorModel: "fable"` in project settings instead of manual `Agent(model: "fable")` subagent spawning. Fable 5 auto-consults at key decision points (architecture, complexity, blast-radius). Setup B (Saver) gains `advisorModel: "claude-opus-4-6"` — Opus advisor compensates for Sonnet driver's lighter reasoning.
+
+- **Settings are project-level by default.** The setup skill writes `model` + `advisorModel` to `.claude/settings.json` (project-scoped, committed, shared with team). After writing, asks if user also wants `advisorModel` in global `~/.claude/settings.json`. Never nukes global settings without consent.
+
+- **Update skill gains Step 7.8 (advisorModel migration).** Detects projects with a model pin but no `advisorModel` and suggests the right advisor pairing. Version-gated to CC v2.1.170+.
+
+- **CLI init.js smart-merge handles `advisorModel`.** Same pattern as `model` — only set if missing, preserve on `--force`.
+
+- **This repo dogfoods Setup A.** Project settings now include `model: "claude-opus-4-6"` + `advisorModel: "fable"`.
+
+- **Documented `! claude update` tip** for users needing v2.1.170+ — the `!` prefix runs shell commands inside a CC session without exiting.
+
+### Why
+
+- The advisor tool (API beta `advisor-tool-2026-03-01`) graduated to native CC support as `advisorModel` in v2.1.170+. Native advisor is strictly better than manual subagent spawning: automatic consultation at key decision points, no headless billing risk, persists across sessions via settings.json, and integrates with CC's settings precedence (project > global).
+
+- Project-level settings prevent the wizard from overwriting a multi-project user's global model config. Settings precedence: Managed > CLI flags > Local > Project > User (global). Writing project-level means each repo picks its own lane independently.
+
 ## [1.80.0] - 2026-06-09
 
 ### Changed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -249,13 +249,12 @@ When Anthropic provides official plugins or tools that handle something:
 
 Claude Code's **effort level** controls how much thinking the model does before responding. Higher effort = deeper reasoning but more tokens.
 
-> ⚠️ **On Opus 4.6 max, effort below `xhigh` breaks SDLC compliance in practice.** Inherited from 4.7, Opus 4.6 max respects effort levels *strictly* — at `high` or below it scopes work tighter (shallow reasoning, skipped TDD, no self-review) rather than going above-and-beyond. Treat the table below accordingly: **`max` is the recommended default, `xhigh` is the floor**, `high` or below is for trivial grep/search subagents only.
+> ⚠️ **SDLC requires `max` effort on all Claude models.** Below max = degraded reasoning, shallow TDD, weak self-review. Persist via env var: `CLAUDE_CODE_EFFORT_LEVEL=max` (CC docs: `effortLevel: "max"` in settings.json is **session-only and silently ignored** — the env var is the only way to persist it).
 
 | Level | When to Use | How to Set |
 |-------|-------------|------------|
-| `high` or below | **Not for SDLC work on Opus 4.6 max.** Only for trivial grep/search subagents or one-shot questions that don't require planning | `effort: high` in a specific subagent frontmatter only |
-| `xhigh` | **Floor for SDLC work on Opus 4.6 max.** Long-running tasks, repeated tool calls, deep exploration. Claude Code defaults to this on Opus 4.7+ | `/effort xhigh` or set in skill frontmatter |
-| `max` | **Recommended default for Opus 4.6 max SDLC work.** Multi-file changes, architecture decisions, debugging, cross-model reviews, any task touching wizard/skill/CI code | `/effort max` (session only — resets next session) |
+| `max` | **Required for all SDLC work.** Claude: max. OpenAI/Codex: xhigh (their highest). | `CLAUDE_CODE_EFFORT_LEVEL=max` in settings env block |
+| `high` or below | **Not for SDLC work.** Only for trivial grep/search subagents | `effort: high` in a specific subagent frontmatter only |
 
 **Strict effort behavior (Opus 4.7+, carried forward in 4.8 — and why 4.6 max is the wizard's pick):**
 - **`xhigh` was introduced in 4.7** — sits between `high` and `max`, designed for coding and agentic work (30+ minute tasks with token budgets in the millions)
@@ -267,11 +266,11 @@ Claude Code's **effort level** controls how much thinking the model does before
 
 **Why `high` was the previous default:** Claude Code uses **adaptive thinking** to dynamically allocate reasoning budget per turn. On Pro and Max plans, the default effort level was **medium (85)**, which causes the model to under-allocate reasoning on complex multi-step tasks — leading to shallow analysis, missed edge cases, and "lazy" outputs. This was [confirmed by Anthropic engineer Boris Cherny](https://github.com/anthropics/claude-code/issues/42796) and is documented at [code.claude.com](https://code.claude.com/docs/en/model-config). API, Team, and Enterprise plans default to high effort and are not affected.
 
-**Don't rely on the CC default — set effort yourself.** Anthropic's [2026-04-23 post-mortem](https://www.anthropic.com/engineering/april-23-postmortem) is independent third-party evidence that CC has flipped reasoning_effort defaults across versions (high → medium → xhigh/high). The default has changed before and will change again. The wizard's `model-effort-check.sh` hook nudges to `xhigh`/`max` at session start specifically because the in-product default is not load-bearing — it can shift release-to-release without notice. Set `/effort max` explicitly every session you do SDLC work, and treat any "I assumed the default was X" reasoning as a bug.
+**Don't rely on the CC default — set effort yourself.** Anthropic's [2026-04-23 post-mortem](https://www.anthropic.com/engineering/april-23-postmortem) is independent third-party evidence that CC has flipped reasoning_effort defaults across versions (high → medium → xhigh/high). The default has changed before and will change again. The wizard's `model-effort-check.sh` hook warns on anything below `max` at session start. Set `CLAUDE_CODE_EFFORT_LEVEL=max` in your settings env block, and treat any "I assumed the default was X" reasoning as a bug.
 
-The `/sdlc` skill sets `effort: high` in its frontmatter as a baseline, overriding the medium default on every SDLC invocation. **On Opus 4.6 max, run `/effort max` at session start** — the frontmatter is a floor, not a ceiling, and `max` is where SDLC-compliant work actually happens on 4.6.
+The `/sdlc` skill sets `effort: max` in its frontmatter, overriding the medium default on every SDLC invocation. This matches the wizard's v1.80.0 contract: Opus 4.6 max is the recommended flagship, and `max` is where SDLC-compliant work actually happens on 4.6.
 
-**Nuclear option — disable adaptive thinking entirely:** Set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` in your environment or settings.json `env` block. This forces a fixed reasoning budget per turn instead of letting the model dynamically allocate. Use this if you observe persistent quality issues even with `effort: high`. See [Claude Code model config docs](https://code.claude.com/docs/en/model-config) for details.
+**Nuclear option — disable adaptive thinking entirely:** Set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` in your environment or settings.json `env` block. This forces a fixed reasoning budget per turn instead of letting the model dynamically allocate. Use this if you observe persistent quality issues even at `max` effort. See [Claude Code model config docs](https://code.claude.com/docs/en/model-config) for details.
 
 **When to escalate to `max`:**
 - You hit LOW confidence on your approach — deeper thinking may find clarity
@@ -282,27 +281,27 @@ The `/sdlc` skill sets `effort: high` in its frontmatter as a baseline, overridi
 
 **How it works:**
 - `/effort max` changes effort for the current session only (resets next session)
-- `effort: high` in SKILL.md frontmatter persists — every `/sdlc` invocation uses `high`
+- `effort: max` in SKILL.md frontmatter persists — every `/sdlc` invocation uses `max`
 - You can also type `ultrathink` in any prompt for a single high-effort turn
 
-**Cost note:** `max` uses significantly more tokens than `high`. Use it when the problem justifies it, not as a default.
+**Cost note:** `max` uses more tokens than lower efforts. Always `max` on all Claude models (#395). Token burn is higher on 4.7/4.8 than 4.6 — that's why 4.6 is the wizard's flagship.
 
 > See also: the **Effort** column in the [Confidence Check table](#confidence-check-required) below for per-confidence-level guidance on when to escalate to `max`.
 
 ### Anti-Laziness Guidance for CLAUDE.md
 
-If you notice Claude Code producing shallow outputs despite `effort: high`, add these instructions to your project's `CLAUDE.md`. These target the **specific mechanisms** behind quality degradation — adaptive thinking and effort levels — rather than vague directives:
+If you notice Claude Code producing shallow outputs despite `effort: max`, add these instructions to your project's `CLAUDE.md`. These target the **specific mechanisms** behind quality degradation — adaptive thinking and effort levels — rather than vague directives:
 
 ```markdown
 ## Quality Anchoring
-- This project uses effort: high via SDLC skill frontmatter. Do not reduce reasoning depth.
+- This project uses effort: max via SDLC skill frontmatter. Do not reduce reasoning depth.
 - Adaptive thinking may under-allocate your thinking budget on complex tasks. When working on
   multi-file changes, architecture decisions, or debugging: reason through the full problem
   before acting, even if the system prompt suggests taking the "simplest approach first."
 - If you catch yourself skipping steps, re-read the task requirements and verify completeness.
 ```
 
-**Why this works:** Claude Code's hidden system prompt includes "Go straight to the point. Try the simplest approach first." This is good for simple queries but causes the model to under-invest in reasoning on complex SDLC tasks. The instructions above don't fight the system prompt — they provide task-specific context that justifies deeper reasoning. Note that CLAUDE.md instructions can be partially overridden by the system prompt, so `effort: high` in skill frontmatter remains the primary defense.
+**Why this works:** Claude Code's hidden system prompt includes "Go straight to the point. Try the simplest approach first." This is good for simple queries but causes the model to under-invest in reasoning on complex SDLC tasks. The instructions above don't fight the system prompt — they provide task-specific context that justifies deeper reasoning. Note that CLAUDE.md instructions can be partially overridden by the system prompt, so `effort: max` in skill frontmatter remains the primary defense.
 
 ---
 
@@ -393,6 +392,34 @@ New built-in commands available to use alongside the wizard:
 
 **Tip**: `/simplify` pairs well with the self-review phase. Run it after implementation as an additional quality check.
 
+### Advisor Model (v2.1.170+)
+
+**What changed**: `advisorModel` in settings.json configures a stronger model that Claude Code automatically consults at key decision points — before committing to an approach, when stuck on recurring errors, or before declaring a task done. Replaces manual `Agent(model: "fable")` subagent spawning for planning.
+
+**Three ways to enable:**
+
+| Method | Scope | Persists? |
+|--------|-------|-----------|
+| `"advisorModel": "fable"` in `.claude/settings.json` | Project | Yes (committed, shared with team) |
+| `/advisor fable` | User (global `~/.claude/settings.json`) | Yes (all projects) |
+| `--advisor fable` CLI flag | Session | No |
+
+**Recommended pairings:**
+
+| Driver | Advisor | Lane |
+|--------|---------|------|
+| Opus 4.6 (`claude-opus-4-6`) | Fable (`"fable"`) | Setup A — Premium |
+| Sonnet via opusplan | Opus (`"claude-opus-4-6"`) | Setup B — Saver |
+| Opus 4.8 (`claude-opus-4-8`) | Fable (`"fable"`) | Latest tier |
+
+**Settings precedence:** Managed > CLI flags > Local (`.claude/settings.local.json`) > Project (`.claude/settings.json`) > User (`~/.claude/settings.json`). The wizard writes project-level by default — never nukes global settings. Setup skill Step 9.5 asks if you also want global.
+
+**Important:** Fable does NOT appear in the `/advisor` interactive picker. Set it via `/advisor fable`, `--advisor fable`, or `advisorModel: "fable"` in settings.json.
+
+**Billing:** Advisor queries in interactive sessions are Max-bundled (same pool as the driver). The advisor does not trigger headless/credit-pool billing.
+
+**To update:** Run `! claude update` from inside a CC session to get v2.1.170+. The `!` prefix runs shell commands inline — no need to exit.
+
 ### Skill Frontmatter Fields (v2.1.80+)
 
 Skills support these frontmatter fields:
@@ -401,14 +428,14 @@ Skills support these frontmatter fields:
 |-------|---------|---------|
 | `name` | Skill name (matches `/command`) | `name: sdlc` |
 | `description` | Trigger description for auto-invocation | `description: Full SDLC workflow...` |
-| `effort` | Set reasoning effort level | `effort: high` |
+| `effort` | Set reasoning effort level | `effort: max` |
 | `paths` | Restrict skill to specific file patterns | `paths: ["src/**/*.ts", "tests/**"]` |
 | `context` | Context mode (`fork` = isolated subagent) | `context: fork` |
 | `argument-hint` | Hint for `$ARGUMENTS` placeholder | `argument-hint: [task description]` |
 | `disable-model-invocation` | Prevent skill from being auto-invoked by model | `disable-model-invocation: true` |
 
 **Key fields explained:**
-- **`effort: high`** — The wizard's `/sdlc` skill uses this to ensure Claude gives full attention. `max` is available but costs significantly more tokens.
+- **`effort: max`** — The wizard's `/sdlc` skill uses this to ensure Claude gives full attention at the recommended effort level for Opus 4.6 max (v1.80.0+).
 - **`paths:`** — Limits when a skill activates based on files being worked on. Useful for language-specific or directory-specific skills.
 - **`context: fork`** — Runs the skill in an isolated subagent context. The subagent gets its own context window, so it won't pollute the main conversation. Useful for review skills or analysis that should run independently.
 
@@ -481,7 +508,7 @@ When a cached prompt prefix is re-served after idle pruning, downstream thinking
 
 **Workaround**: if you hit suspicious shallow reasoning mid-session — especially after a long idle gap — start a fresh session with `claude --continue` to reset cache state. The wizard's PreCompact hook gates manual `/compact` precisely because compacting at bad seams can also pull thinking blocks out of context.
 
-**Detection signal**: the wizard's `model-effort-check.sh` already loud-warns below `xhigh`. Combine with token-spike anomaly detection (ROADMAP #220) once shipped.
+**Detection signal**: the wizard's `model-effort-check.sh` loud-warns below `max`. Combine with token-spike anomaly detection (ROADMAP #220) once shipped.
 
 ### Prompt brevity caps can compound across turns (post-mortem 2026-04-23)
 
@@ -967,14 +994,16 @@ Override the default auto-compact threshold with environment variables. These ar
 | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Trigger compaction at this % of context capacity (1-100) | ~95% |
 | `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Override context capacity in tokens (useful for 1M models) | Model default |
 
-**Opt-in (issue #198):** The SDLC Wizard CLI ships `.claude/settings.json` with **no** `model` or `env` pin so Claude Code's auto-mode stays enabled. The setup skill's Step 9.5 asks whether to opt into `"model": "opus[1m]"` + `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` (tuned for the 1M window — compacts at ~300K). Default answer is **No**. Pinning the model at the top level tells Claude Code you've explicitly chosen a model and turns off per-turn model auto-selection — a real tradeoff, so we ask. Power users who want guaranteed Opus 4.6 max + 1M context answer yes.
+**Opt-in (issue #198):** The SDLC Wizard CLI ships `.claude/settings.json` with **no** `model`, `advisorModel`, or `env` pin so Claude Code's auto-mode stays enabled. The setup skill's Step 9.5 offers four choices: `[N]` no pin, `[o]` opusplan + Opus advisor, `[f]` flagship Opus 4.6 + Fable advisor, `[l]` latest Opus 4.8 + Fable advisor. Default is **No**. Pinning the model turns off per-turn auto-selection — a real tradeoff, so we ask.
 
-To opt in by hand, edit `.claude/settings.json`:
+To opt in by hand, edit `.claude/settings.json` (flagship example):
 
 ```json
 {
-  "model": "opus[1m]",
+  "model": "claude-opus-4-6",
+  "advisorModel": "fable",
   "env": {
+    "CLAUDE_CODE_EFFORT_LEVEL": "max",
     "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30"
   }
 }
@@ -1036,40 +1065,33 @@ Claude Code supports both 200K and 1M context windows. **`opus[1m]` is an opt-in
 
 **Autocompact pairing (important):** If you opt into `opus[1m]`, also set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` — otherwise CC's default autocompact fires at ~76K and destroys the headroom you're paying for. Step 9.5 writes both together when you opt in.
 
-### Mixed-Mode Tier (Sonnet coder + Opus reviewer, roadmap #233)
-
-For trivial / blank / config-only / CRUD-style repos, full Opus 4.6 max on every turn is overkill on the coder leg. The **mixed-mode tier** pins `model: "sonnet[1m]"` for in-session work while keeping the cross-model review layer (Codex / external reviewer) at the flagship — so the reviewer still catches what Sonnet missed.
-
-**The split:**
-
-| Layer | Mixed-mode tier | Flagship tier |
-|-------|----------------|---------------|
-| Coder (in-session CC) | `model: "sonnet[1m]"` | `model: "opus[1m]"` |
-| Cross-model reviewer (Codex etc.) | gpt-5.5 xhigh (or Opus 4.6 max via Bash for an in-family second opinion) | gpt-5.5 xhigh (or Opus 4.6 max via Bash for an in-family second opinion) |
-| Effort floor (CC session) | xhigh; max preferred | xhigh; max preferred |
-
-The reviewer always stays at flagship — the whole point of mixed-mode is that adversarial review catches Sonnet's blind spots, so weakening the review leg defeats the savings.
-
-**When mixed-mode is the right call:**
-- Repo is small (LOC < 10K), few tests (< 30), few hooks (< 5), few workflows (< 5), no `.env` / secrets handling
-- You're on API billing (not Max subscription) and 2× cost on simple repos actually matters
-- Tasks are predominantly mechanical — typo fixes, config tweaks, small CRUD endpoints
-- You're running the SDLC Wizard's setup flow against a sibling repo where the coder doesn't need flagship reasoning
+### OpusPlan Tier (Opus planner + Sonnet driver, #395)
 
-**When to stay flagship:**
-- Stakes-flagged repo: anywhere `.env` / `secrets/` / `credentials/` exists. Force flagship even if LOC is tiny — leaks are catastrophic
-- Architecture work, debugging non-obvious bugs, security review, anything where the *coder's* judgment matters as much as the reviewer's
-- Long shepherd sessions (plan → TDD → review → CI loop) — they cross 100K tokens regularly and Opus 4.6 max fits the window better in a single thread
+For cost-conscious SDLC work, CC's native `opusplan` alias gives you Opus reasoning during Plan Mode (Shift+Tab) and Sonnet execution — both at 200K, Max-bundled, no API credit drain.
 
-**Auto-detection:** the setup wizard runs `cli/lib/repo-complexity.js` against the target repo and suggests the tier. Stakes flag (`.env` / `secrets/`) forces complex regardless of size. The user always picks the final answer — the heuristic is a hint, not a gate.
+| Layer | OpusPlan tier | Flagship tier |
+|-------|--------------|---------------|
+| Planner | Opus 4.6 max (Plan Mode) | Opus 4.6 max |
+| Driver | Sonnet 4.6 (execute mode) | Opus 4.6 max |
+| Reviewer | GPT-5.5 xhigh | GPT-5.5 xhigh |
+| Effort | max (via `CLAUDE_CODE_EFFORT_LEVEL` env var) | max |
 
-**How to opt in (manual):**
+**How to opt in:**
 ```json
 {
-  "model": "sonnet[1m]"
+  "model": "opusplan",
+  "env": {
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
+    "CLAUDE_CODE_EFFORT_LEVEL": "max"
+  }
 }
 ```
-Don't add `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` — Sonnet's 1M window has different compaction characteristics than Opus's; let upstream defaults ride until we benchmark.
+
+**⚠️ Avoid `sonnet[1m]`** — Sonnet with 1M context draws from usage credits ($3/$15 per Mtok), not your Max subscription (#390). Plain `sonnet` (200K) or `opusplan` stays on Max.
+
+**When to use OpusPlan:** routine SDLC work, simple repos, cost-conscious sessions. Press Shift+Tab before architecture/blast-radius decisions to get Opus reasoning.
+
+**When to stay Flagship:** stakes-flagged repos, architecture work, security review, long shepherd sessions.
 
 **Prove-It Gate (#233 acceptance criterion):** mixed-mode ships only if pair-tested on 3+ simple repos shows Sonnet-coder + Opus-reviewer produces ≥ same SDLC scores as full-Opus baseline. The first version of the heuristic ships v1.38.0; pair-test results land in CHANGELOG before recommending mixed-mode as the default for any tier.
 
@@ -1089,7 +1111,7 @@ The wizard's flagship recommendation is Opus 4.6 max (see "Choosing Your Model"
 
 **Tradeoffs (be honest):**
 - **Documented 40-60× cache token jump** vs 4.7 at HIGH effort ([AI Weekly](https://aiweekly.co/alerts/claude-opus-48-thinking-burns-900k-tokens-per-turn) — up to 900K cache tokens per turn). Burns Max 5-hour limits 2-3× faster than 4.6
-- **`max` effort is *worse* than `high` on 4.8** per [Andon Labs Vending-Bench](https://andonlabs.com/blog/opus-4-8-vending-bench) ("Max reasoning is not the best reasoning effort") — context fills faster
+- **Earlier field signal suggested xhigh over max on 4.8** per [Andon Labs Vending-Bench](https://andonlabs.com/blog/opus-4-8-vending-bench), but wizard standard is now `max` on all Claude models (#395)
 - Active GitHub regressions still open: false-greens ([#63861](https://github.com/anthropics/claude-code/issues/63861)), 2-3× token burn ([#64961](https://github.com/anthropics/claude-code/issues/64961)), 46K tokens for simple coding turn ([#64153](https://github.com/anthropics/claude-code/issues/64153)), dropped constraints ([#65932](https://github.com/anthropics/claude-code/issues/65932))
 - [Tech.yahoo review](https://tech.yahoo.com/ai/claude/articles/claude-opus-4-8-review-130106963.html): "Anthropic deliberately made Opus's new tokenizer less efficient" — not a transient bug, structural pricing change
 - Anthropic-supported until ≥ May 28, 2027 (longer runway than 4.6)
@@ -1099,24 +1121,16 @@ The wizard's flagship recommendation is Opus 4.6 max (see "Choosing Your Model"
 Edit `~/.claude/settings.json`:
 ```json
 {
+  "model": "claude-opus-4-8",
   "env": {
-    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
-    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-opus-4-8"
-  },
-  "model": "opus[1m]"
+    "CLAUDE_CODE_EFFORT_LEVEL": "max"
+  }
 }
 ```
 
-The `opus[1m]` alias resolves through the env vars, so this combination pins `claude-opus-4-8[1m]` (1M context) everywhere.
+On Max plans, Opus auto-upgrades to 1M context. No `[1m]` suffix needed.
 
-**Project-scoped (single repo):**
-```json
-{
-  "model": "claude-opus-4-8[1m]"
-}
-```
-
-**Effort tuning for 4.8:** field signal recommends `xhigh` instead of `max` on 4.8 — the strict-effort behavior overcorrects at `max`. Keep `max` for 4.6, drop to `xhigh` if running 4.8.
+**Effort tuning for 4.8:** always `max`. Earlier field signal suggested xhigh on 4.8 but the wizard standard is max on all Claude models (#395).
 
 **Escape hatch:** flip the env vars back to `claude-opus-4-6` to return to the wizard's recommended default. Or remove them entirely to fall back to Claude Code auto-mode.
 
@@ -2271,7 +2285,7 @@ TodoWrite([
   { content: "DRY check: Is logic duplicated elsewhere?", status: "pending", activeForm: "Checking for duplication" },
   { content: "Self-review: run /code-review", status: "pending", activeForm: "Running code review" },
   { content: "Security review (if warranted)", status: "pending", activeForm: "Checking security implications" },
-  { content: "Cross-model review (if configured — see below)", status: "pending", activeForm: "Running cross-model review" },
+  { content: "Cross-model review (REQUIRED for high-stakes)", status: "pending", activeForm: "Running cross-model review" },
   // CI FEEDBACK LOOP (After local tests pass)
   { content: "Commit and push to remote", status: "pending", activeForm: "Pushing to remote" },
   { content: "Watch CI - fix failures, iterate until green (max 2x)", status: "pending", activeForm: "Watching CI" },
@@ -2340,9 +2354,9 @@ Before presenting approach, STATE your confidence:
 
 | Level | Meaning | Action | Effort |
 |-------|---------|--------|--------|
-| HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval | `high` (default) |
-| MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties | `high` (default) |
-| LOW (<60%) | Not sure | ASK USER before proceeding | **Run `/effort xhigh` now** — don't wait |
+| HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval | `max` (default) |
+| MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties | `max` (default) |
+| LOW (<60%) | Not sure | ASK USER before proceeding | **Run `/effort max` now** — don't wait |
 | FAILED 2x | Something's wrong | STOP. ASK USER immediately | **Run `/effort max` now** — you're burning cycles at lower effort |
 | CONFUSED | Can't diagnose why something is failing | STOP. Describe what you tried, ask for help | **Run `/effort max` now** — stop spinning |
 
@@ -2372,10 +2386,10 @@ PLANNING → DOCS → TDD RED → TDD GREEN → Tests Pass → Self-Review
 4. Issues below 80 are likely false positives — skip unless obviously valid
 5. Address issues by going back through the proper SDLC loop
 
-## Cross-Model Review (If Configured)
+## Cross-Model Review (REQUIRED for High-Stakes)
 
 **When to run:** High-stakes changes (auth, payments, data handling), releases/publishes (version bumps, CHANGELOG, npm publish), complex refactors, research-heavy work.
-**When to skip:** Trivial changes (typo fixes, config tweaks), time-sensitive hotfixes, risk < review cost.
+**When to skip (log justification):** Trivial changes (typo fixes, config tweaks), time-sensitive hotfixes, risk < review cost.
 
 **Prerequisites:** Codex CLI installed (`npm i -g @openai/codex`), OpenAI API key set.
 
@@ -2486,7 +2500,7 @@ Self-review passes → handoff.json (round 1, PENDING_REVIEW)
 
 **Tool-agnostic:** The value is adversarial diversity (different model, different blind spots), not the specific tool. Any competing AI reviewer works.
 
-**Full protocol:** See the "Cross-Model Review Loop (Optional)" section below for key flags and reasoning effort guidance.
+**Full protocol:** See the "Cross-Model Review Loop" section below for key flags and reasoning effort guidance.
 
 ### Release Review Focus
 
@@ -3027,7 +3041,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.80.0 -->
+<!-- SDLC Wizard Version: 1.82.0 -->
 <!-- Setup Date: [DATE] -->
 <!-- Completed Steps: step-0.1, step-0.2, step-0.4, step-1, step-2, step-3, step-4, step-5, step-6, step-7, step-8, step-9 -->
 <!-- Git Workflow: [PRs or Solo] -->
@@ -3677,10 +3691,21 @@ Practical techniques to reduce token consumption without sacrificing quality.
 
 | Tool | What It Shows | When to Use |
 |------|---------------|-------------|
-| `/usage` | Session total: USD, API time, code changes (aliases: `/cost`, `/stats`) | After a session to review spend |
+| `/usage` | Session cost, plan usage limits, and per-category breakdown (skill, subagent, plugin, MCP server). Aliases: `/cost`, `/stats` | After heavy subagent work, before/after workflow runs, when approaching rate limits |
+| `/status` | Settings panel — version, model, account, connectivity | Confirm setup before starting work |
 | `/context` | What's consuming context window space | When hitting context limits |
 | Status line | Real-time `cost.total_cost_usd` + token counts | Continuous monitoring |
 
+### Reading Usage Signals
+
+These signals are community-observed behavior on paid plans (Max/Team) — not in official CC docs. They are independent dimensions, not a single breakdown. A single session can contribute to all three. Run `/usage` to see the per-category breakdown.
+
+| Signal | What It Means | SDLC Action |
+|--------|---------------|-------------|
+| **Subagent-heavy** | Each subagent runs its own context. The advisor is a separate server-side consultation (full transcript forwarded, different token profile). Explore agents, full Agent delegates, and workflow agents each spawn separate contexts. | Expected in Setup A (Fable advisor fires per-decision). If unexpectedly high: use `subagent_type: "Explore"` for search (lighter), reserve full agents for implementation. |
+| **>150K context** | Sessions staying large between compactions. | **Context-window dependent.** On 1M (Setup A): >150K is expected at 30% compact threshold — the real question is whether the task needed 1M headroom. On 200K (Setup B/C): lower `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` toward 75%. `/compact` between planning and implementation. |
+| **8+ hour sessions** | Long-running sessions accumulate stale context. | `/clear` between unrelated tasks. Split multi-feature work into separate sessions. After committing a PR, start fresh. Background `/loop` sessions count toward this — audit which are still needed. |
+
 ### Reduce Consumption
 
 | Technique | Savings | How |
@@ -3787,7 +3812,7 @@ Claude: [fetches via gh api, discusses with you interactively]
 
 This is optional - skip if you prefer fresh reviews only.
 
-### Cross-Model Review Loop (Optional)
+### Cross-Model Review Loop (REQUIRED for High-Stakes)
 
 Use an independent AI model from a different company as a code reviewer. The author can't grade their own homework — a model with different training data and different biases catches blind spots the authoring model misses.
 
@@ -4164,7 +4189,7 @@ Every wizard step has a unique ID for tracking:
 | `step-9` | SDLC/TESTING/ARCH docs | 1.0.0 |
 | `question-git-workflow` | Git workflow preference | 1.2.0 |
 | `step-update-notify` | Optional: CI update notification | 1.13.0 |
-| `step-cross-model-review` | Optional: Cross-model review loop | 1.16.0 |
+| `step-cross-model-review` | Cross-model review (REQUIRED for high-stakes) | 1.16.0 |
 | `step-update-wizard` | /update-wizard smart update skill | 1.18.0 |
 
 When checking for updates, Claude compares user's completed steps against this registry.
@@ -4472,7 +4497,7 @@ The wizard watches the **Anthropic API changelog** — not just Claude Code CLI
 
 When that issue is open, the session-start hook nudges you. The session (not the workflow) does the deep research + adoption via the full SDLC loop. This mirrors the "local shepherd" pattern used for CI fixes: cheap Action-layer detection + session-time analysis beats expensive Action-layer LLM calls.
 
-The gap this closes: the advisor tool (API beta, `advisor-tool-2026-03-01`) shipped and was missed for several days before manual discovery. Detector would have flagged it on the next weekly tick.
+The gap this closes: the advisor tool (API beta, `advisor-tool-2026-03-01`) shipped and was missed for several days before manual discovery. Detector would have flagged it on the next weekly tick. **Update (v1.81.0):** The API beta graduated to native CC support as `advisorModel` in settings.json (v2.1.170+). See [Advisor Model (v2.1.170+)](#advisor-model-v21170) above.
 
 **Complementary native skills worth knowing:**
 

package/README.md

@@ -113,7 +113,7 @@ Layer 1: PHILOSOPHY
 | **Pre-tool TDD hooks** | Before source edits, a hook reminds Claude to write tests first. CI scoring checks whether it actually followed TDD |
 | **Self-evolving loop** | Weekly/monthly external research + local CI shepherd loop — you approve, the system gets better |
 
-## Optional: Cross-Model Review (Codex)
+## Cross-Model Review (Codex) — REQUIRED for High-Stakes
 
 Claude can't grade its own homework. Have a **different AI from a different company** review Claude's work — different training, different blind spots, different biases. We use OpenAI's Codex CLI, and it's **three commands to set up**:
 
@@ -136,7 +136,7 @@ codex exec -c 'model_reasoning_effort="xhigh"' -s danger-full-access \
 
 **Always append `< /dev/null`** when running `codex exec` from a non-interactive parent (background, hooks, CI, Claude Code Bash tool). Without it, codex blocks on stdin reads even when the prompt is an argument — the process sits at S/0% CPU indefinitely with a 0-byte `-o` output file. Validated on codex-cli 0.130.0 / macOS 14, 2026-05-15.
 
-`xhigh` reasoning is **non-negotiable** — lower settings miss subtle bugs. See [CLAUDE_CODE_SDLC_WIZARD.md](CLAUDE_CODE_SDLC_WIZARD.md#cross-model-review-loop-optional) for the full protocol (handoff format, round-2 dialogue loop, preflight docs). Real-world: this catches P0/P1 issues in 2-3 out of 10 reviews that Claude's self-review rated as clean.
+`xhigh` reasoning is **non-negotiable** — lower settings miss subtle bugs. See [CLAUDE_CODE_SDLC_WIZARD.md](CLAUDE_CODE_SDLC_WIZARD.md#cross-model-review-loop-required-for-high-stakes) for the full protocol (handoff format, round-2 dialogue loop, preflight docs). Real-world: this catches P0/P1 issues in 2-3 out of 10 reviews that Claude's self-review rated as clean.
 
 ## Choosing Your Model
 
@@ -168,25 +168,37 @@ Six independent sources converging on the same conclusion: **4.6 is the only Opu
 
 ### Latest tier — Opus 4.8 (opt-in)
 
-If you want the newest benchmarks and you're comfortable with the token-burn tradeoff, pick `[l] Latest` in the setup wizard. Recommended effort is `xhigh`, not `max`, on 4.8 — Andon Labs' data is explicit that `max` on 4.8 is worse than `xhigh`. The [`Latest tier — Opus 4.8`](CLAUDE_CODE_SDLC_WIZARD.md) section has the full opt-in instructions.
+If you want the newest benchmarks and you're comfortable with the token-burn tradeoff, pick `[l] Latest` in the setup wizard. Always `max` effort on all Claude models (#395). The [`Latest tier — Opus 4.8`](CLAUDE_CODE_SDLC_WIZARD.md) section has the full opt-in instructions.
 
 ### Switch any time
 
 ```bash
-/model claude-opus-4-6[1m]   # wizard's recommended flagship (default in v1.80.0+)
-/model claude-opus-4-8[1m]   # Anthropic's latest, opt-in via Latest tier
-/model opus[1m]              # whatever your env-var resolves to (alias)
+/model claude-opus-4-6   # wizard's recommended flagship (default in v1.80.0+)
+/model opusplan          # Opus plans (Shift+Tab), Sonnet executes — both Max-bundled
+/model claude-opus-4-8   # Anthropic's latest, opt-in via Latest tier
 ```
 
 Or pin in `.claude/settings.json`:
 
 ```json
-{ "model": "claude-opus-4-6[1m]" }
+{ "model": "claude-opus-4-6", "env": { "CLAUDE_CODE_EFFORT_LEVEL": "max" } }
 ```
 
-Or sweep all your projects from one place by setting `ANTHROPIC_DEFAULT_OPUS_MODEL` in `~/.claude/settings.json` — the `opus[1m]` alias resolves through it, so flipping one env var switches every repo at once.
+Or sweep all your projects by setting `ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6` in `~/.claude/settings.json`.
 
-Effort tuning is independent of model choice. `max` is the wizard's default *paired with 4.6*; `xhigh` is the floor. Adjust per session with `/effort max`. On 4.8, drop effort to `xhigh` per field evidence.
+Effort: **always `max`** on all Claude models. Persist it: set `CLAUDE_CODE_EFFORT_LEVEL=max` in your settings env block (CC docs: `effortLevel: "max"` in settings.json is session-only and silently ignored). OpenAI/Codex: `xhigh` (their highest).
+
+### Three Setup Lanes
+
+The wizard defines three AI coding setups in [`AI_SETUP_LANES.md`](AI_SETUP_LANES.md):
+
+| Lane | Advisor | Driver | Reviewer | Escalation |
+|------|---------|--------|----------|------------|
+| **A — Premium** | Fable 5 (advisorModel) | Opus 4.6 max | GPT-5.5 xhigh | + Fable review (security/release/architecture) |
+| **B — Saver** | Opus 4.6 (advisorModel) | Sonnet | GPT-5.5 xhigh | None |
+| **C — Lite** | None | Sonnet | None | None |
+
+Setup C's whole point: **the discipline of knowing when NOT to use discipline.** When blast radius is low and you just need fast cheap hands, skip the SDLC overhead.
 
 **A note on `[1m]` and billing.** The `[1m]` suffix is the 1M-context alias. As of [March 2026](https://claude.com/blog/1m-context-ga), 1M context is GA at standard pricing — **no long-context surcharge, no premium tier, no API-only restriction.** Interactive Claude Code sessions on Max / Team / Enterprise plans include 1M context automatically; whether you set `claude-opus-4-6` or `claude-opus-4-6[1m]`, you're billed against the same per-token Max budget at $5/$25 per million tokens. (Pro users need "Enable usage credits" turned on once.) The [June 15, 2026 billing split](https://codersera.com/blog/anthropic-june-2026-billing-change-claude-code/) moved *headless* surfaces — `claude -p`, Agent SDK, GitHub Actions, third-party apps — off the Max subscription onto a separate metered credit pool. Interactive Claude Code in your terminal stays on Max. Full details in [`AI_SETUP_LANES.md` § How Billing Works](AI_SETUP_LANES.md#how-billing-works--1m-context-max-plan-and-the-june-15-split).
 

package/cli/init.js

@@ -83,6 +83,10 @@ function mergeSettings(existingPath, templatePath, force) {
       existing.model = template.model;
     }
 
+    if (template.advisorModel && (!('advisorModel' in existing) || force)) {
+      existing.advisorModel = template.advisorModel;
+    }
+
     // Merge cleanupPeriodDays (ROADMAP #225): only set the template default when
     // the user has not chosen a value. NEVER overwrite under --force — retention
     // policy is a user preference (they may want >30 for long pauses, or <30 for
@@ -532,16 +536,50 @@ function buildUpdateRecommendation(updateInfo, customizedCount) {
   return lines;
 }
 
+function settingsHooksMatch(srcPath, destPath) {
+  try {
+    const src = JSON.parse(fs.readFileSync(srcPath, 'utf8'));
+    const dest = JSON.parse(fs.readFileSync(destPath, 'utf8'));
+    for (const [event, entries] of Object.entries(src.hooks || {})) {
+      if (!dest.hooks || !dest.hooks[event]) return false;
+      const templateEntry = entries[0];
+      if (!templateEntry || !templateEntry.hooks) continue;
+      for (const th of templateEntry.hooks) {
+        if (!th.command) continue;
+        const marker = WIZARD_HOOK_MARKERS.find((m) => th.command.includes(m));
+        if (!marker) continue;
+        // Verify marker present AND type matches. We intentionally skip matcher/if
+        // comparison — those are customizable per-project (the wizard's own settings
+        // use different if guards than the consumer template).
+        const found = dest.hooks[event].some(
+          (de) => de.hooks && de.hooks.some(
+            (h) => h.command && h.command.includes(marker) && h.type === (th.type || 'command')
+          )
+        );
+        if (!found) return false;
+      }
+    }
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
 function checkFile(srcPath, destPath, relativeDest, shouldBeExecutable) {
   if (!fs.existsSync(destPath)) {
     return { file: relativeDest, status: 'MISSING' };
   }
   const srcHash = crypto.createHash('sha256').update(fs.readFileSync(srcPath)).digest('hex');
   const destHash = crypto.createHash('sha256').update(fs.readFileSync(destPath)).digest('hex');
-  const result = {
-    file: relativeDest,
-    status: srcHash === destHash ? 'MATCH' : 'CUSTOMIZED',
-  };
+  let fileStatus;
+  if (srcHash === destHash) {
+    fileStatus = 'MATCH';
+  } else if (relativeDest === '.claude/settings.json' && settingsHooksMatch(srcPath, destPath)) {
+    fileStatus = 'MATCH';
+  } else {
+    fileStatus = 'CUSTOMIZED';
+  }
+  const result = { file: relativeDest, status: fileStatus };
 
   if (shouldBeExecutable) {
     try {

package/hooks/instructions-loaded-check.sh

@@ -256,7 +256,9 @@ if [ -f "$PROJECT_DIR/.github/workflows/weekly-update.yml" ] && \
 fi
 
 # Claude Code version check (non-blocking, best-effort)
-if command -v claude > /dev/null 2>&1 && command -v npm > /dev/null 2>&1; then
+# Gate on CLAUDE_PROJECT_DIR — only Claude Code sets this. Without it, we're
+# running under Codex/OpenCode where a CC update nudge is misleading (#375).
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && command -v claude > /dev/null 2>&1 && command -v npm > /dev/null 2>&1; then
     CC_LOCAL=$(claude --version 2>/dev/null | grep -o '[0-9][0-9.]*' | head -1) || true
     if [ -n "$CC_LOCAL" ]; then
         CC_LATEST=$(npm view @anthropic-ai/claude-code version 2>/dev/null) || true

package/hooks/model-effort-check.sh

@@ -1,67 +1,67 @@
 #!/bin/bash
 # SessionStart hook — effort/model nudge.
 #
-# Behavior (per ROADMAP #217):
-#   effort=max    -> silent (preferred default, above floor)
-#   effort=xhigh  -> silent (minimum floor on Opus 4.6 max)
-#   effort=high|medium|low (or unset) -> LOUD WARNING:
-#     Opus 4.6 max needs xhigh floor for SDLC compliance (TDD, self-review, deep reasoning).
-#     Recommends `/effort max`. Also reminds about recommended model `claude-opus-4-6[1m]`.
+# Behavior (#395 update):
+#   CLAUDE_CODE_EFFORT_LEVEL env var takes precedence over effortLevel in settings.
+#   CC docs: max is session-only in settings.json — only the env var persists it.
+#   Opus 4.6 supports: low, medium, high, max (NO xhigh — falls back to high).
 #
-# CC does not expose the current model to hooks, so the model nudge is emitted as
-# guidance for Claude to compare against its own system prompt.
+#   effort=max   -> silent (only acceptable level)
+#   anything else -> LOUD WARNING
 #
 # Non-blocking: always exits 0.
 
-RECOMMENDED_MODEL="claude-opus-4-6[1m]"
+RECOMMENDED_MODEL="claude-opus-4-6"
 
-# Token-bloat fix: when both project + plugin register this hook, plugin yields.
 HOOK_DIR="${BASH_SOURCE[0]%/*}"
 [ "$HOOK_DIR" = "${BASH_SOURCE[0]}" ] && HOOK_DIR="."
 # shellcheck disable=SC1091
 source "$HOOK_DIR/_find-sdlc-root.sh"
 dedupe_plugin_or_project "${BASH_SOURCE[0]}" || { cat > /dev/null; exit 0; }
 
-# Drain stdin (SessionStart sends JSON but model field isn't in it)
 cat > /dev/null
 
 if ! command -v jq > /dev/null 2>&1; then
     exit 0
 fi
 
-effort=""
-project_dir="${CLAUDE_PROJECT_DIR:-.}"
-for f in "$project_dir/.claude/settings.local.json" "$project_dir/.claude/settings.json" "$HOME/.claude/settings.json"; do
-    if [ -f "$f" ]; then
-        val=$(jq -r '.effortLevel // empty' "$f" 2>/dev/null)
-        if [ -n "$val" ]; then
-            effort="$val"
-            break
+# Env var takes precedence (CC docs: only way to persist max)
+effort="${CLAUDE_CODE_EFFORT_LEVEL:-}"
+settings_max=0
+
+if [ -z "$effort" ]; then
+    project_dir="${CLAUDE_PROJECT_DIR:-.}"
+    for f in "$project_dir/.claude/settings.local.json" "$project_dir/.claude/settings.json" "$HOME/.claude/settings.json"; do
+        if [ -f "$f" ]; then
+            val=$(jq -r '.effortLevel // empty' "$f" 2>/dev/null)
+            if [ -n "$val" ]; then
+                effort="$val"
+                [ "$val" = "max" ] && settings_max=1
+                break
+            fi
         fi
-    fi
-done
+    done
+fi
 
-# At or above floor — silent.
-case "$effort" in
-    max|xhigh)
-        exit 0
-        ;;
-esac
+# Only env-var max is truly silent.
+if [ "$effort" = "max" ] && [ "$settings_max" -eq 0 ]; then
+    exit 0
+fi
 
-# Below floor OR unset — LOUD warning.
-# Note: test_model_effort_size_cap asserts output < 500 chars. Keep copy terse.
-if [ -z "$effort" ]; then
+if [ "$settings_max" -eq 1 ] && [ -z "${CLAUDE_CODE_EFFORT_LEVEL:-}" ]; then
+    effort_display="max (settings-only — CC ignores this)"
+elif [ -z "$effort" ]; then
     effort_display="unset"
 else
     effort_display="$effort"
 fi
 
 echo "=============================================================================="
-echo " WARNING: effort '$effort_display' breaks SDLC compliance on Opus 4.6 max."
-echo " Below xhigh = shallow reasoning, skipped TDD, dropped self-review."
+echo " WARNING: effort '$effort_display' — SDLC requires max."
+echo " Below max = degraded reasoning, shallow TDD, weak self-review."
 echo ""
-echo " Run: /effort max    (preferred, full SDLC compliance)"
-echo " Or:  /effort xhigh  (minimum floor)"
+echo " Run: /effort max"
+echo " Persist: set CLAUDE_CODE_EFFORT_LEVEL=max in settings env block"
 echo ""
 echo " recommended model: $RECOMMENDED_MODEL (run: /model $RECOMMENDED_MODEL)"
 echo "=============================================================================="

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.80.0",
+  "version": "1.82.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "cli/bin/sdlc-wizard.js"
@@ -11,6 +11,7 @@
     "hooks/",
     ".claude-plugin/",
     "CLAUDE_CODE_SDLC_WIZARD.md",
+    "AI_SETUP_LANES.md",
     "CHANGELOG.md"
   ],
   "keywords": [

package/skills/sdlc/SKILL.md

@@ -2,7 +2,7 @@
 name: sdlc
 description: Full SDLC workflow for implementing features, fixing bugs, refactoring code, testing, releasing, publishing, and deploying. Use this skill when implementing, fixing, refactoring, testing, adding features, building new code, or releasing/publishing/deploying.
 argument-hint: [task description]
-effort: high
+effort: max
 ---
 # SDLC Skill - Full Development Workflow
 
@@ -47,7 +47,7 @@ TodoWrite([
   { content: "Visual consistency check (if UI change)", status: "pending" },
   { content: "Self-review: run /code-review", status: "pending" },
   { content: "Security review (if warranted)", status: "pending" },
-  { content: "Cross-model review (if configured)", status: "pending" },
+  { content: "Cross-model review (high-stakes)", status: "pending" },
   { content: "Scope guard: only changes related to task? No legacy/fallback code left?", status: "pending" },
   // CI SHEPHERD
   { content: "Commit and push to remote", status: "pending" },
@@ -96,9 +96,9 @@ State your confidence before presenting an approach:
 
 | Level | Meaning | Action | Effort |
 |-------|---------|--------|--------|
-| HIGH (90%+) | Know exactly what to do | Present, proceed after approval | `high` (default) |
-| MEDIUM (60-89%) | Solid approach, some uncertainty | Present, highlight uncertainties | `high` |
-| LOW (<60%) | Not sure | Research or try Codex; if still LOW, ASK USER | **`/effort xhigh` now** |
+| HIGH (90%+) | Know exactly what to do | Present, proceed after approval | `max` (default) |
+| MEDIUM (60-89%) | Solid approach, some uncertainty | Present, highlight uncertainties | `max` (default) |
+| LOW (<60%) | Not sure | Research or try Codex; if still LOW, ASK USER | **`/effort max` now** |
 | FAILED 2x | Something's wrong | Codex for fresh perspective; if still stuck, STOP | **`/effort max` now** |
 | CONFUSED | Can't diagnose | Codex; if still confused, STOP and describe | **`/effort max` now** |
 
@@ -114,9 +114,11 @@ Native `/goal <condition>` (**v2.1.143+**). Haiku evaluator re-checks transcript
 
 ## Recommended Model
 
-**Opt-in: `claude-opus-4-6[1m]` (Opus 4.6 max + 1M context — wizard's flagship).** `/model claude-opus-4-6[1m]` at session start (issue #198). Top-level `model` pin disables CC auto-selection; pin only when you need 1M headroom. CC v2.1.154+. For 4.8 opt-in, see wizard "Latest tier".
+**Recommended: `claude-opus-4-6` or `opusplan` (Opus 4.6 max — wizard's flagship).** Pin in settings or `/model claude-opus-4-6` at session start. `opusplan` uses Opus for Plan Mode (Shift+Tab) + Sonnet for execution — both Max-bundled. Persist effort: `CLAUDE_CODE_EFFORT_LEVEL=max` in settings env block.
 
-**Pair with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` when you opt in.** Without it, the default fires at ~76K on 1M. **Pick ONE — do NOT set both `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` AND `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000`** — they compound to 30% × 400K = 120K trigger ≈ 12% of 1M, fires almost immediately (#207). See wizard "Autocompact Tuning" for details.
+**If pinning `claude-opus-4-6`:** pair with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` — default compacts too early at ~76K on 1M. **Do not set this for `opusplan`** — 200K context, 30% = 60K too aggressive.
+
+**Advisor (v2.1.170+):** Flagship → `advisorModel: "fable"`. OpusPlan → `advisorModel: "claude-opus-4-6"`. Set during `/setup-wizard` Step 9.5.
 
 ## Self-Review Loop
 
@@ -128,9 +130,9 @@ PLANNING → DOCS → TDD RED → GREEN → Tests Pass → Self-Review
 
 The loop goes back to PLANNING, not TDD RED. Run `/code-review`; issues at confidence ≥ 80 are real, < 80 are likely false positives. Found issues → ask "Want a plan to fix?" → new plan → docs → TDD → review.
 
-## Cross-Model Review (If Configured)
+## Cross-Model Review (REQUIRED for High-Stakes)
 
-**When to run:** high-stakes changes (auth, payments, data), releases/publishes, complex refactors. **When to skip:** trivial changes, time-sensitive hotfixes, risk < review cost. **Prerequisites:** Codex CLI (`npm i -g @openai/codex`) + OpenAI API key. **Reviewer at flagship tier (#233):** even when project pins `sonnet[1m]`, reviewer runs `gpt-5.5` / Opus 4.6 max — adversarial diversity is the point.
+**When to run:** high-stakes changes (auth, payments, data), releases/publishes, complex refactors. **When to skip (log justification):** trivial, hotfixes, risk < review cost. **Prerequisites:** Codex CLI (`npm i -g @openai/codex`) + OpenAI API key. **Reviewer at flagship tier (#233):** even on `opusplan` (Sonnet driver), reviewer runs `gpt-5.5` xhigh — adversarial diversity is the point.
 
 PROTOCOL is universal across domains; only `review_instructions` and `verification_checklist` change.
 
@@ -265,7 +267,7 @@ Don't fix only the symptom. Add a gate so it can't happen again. Example: PR #14
 
 - `/compact` between planning and implementation (plan preserved in summary)
 - `/clear` between unrelated tasks; after 2+ failed corrections (context polluted)
-- Auto-compact fires at ~95% capacity
+- Auto-compact fires at ~95%; `/usage` shows what's driving token spend
 - After committing a PR, `/clear` before next feature
 - `--bare` mode (v2.1.81+) skips ALL hooks/skills/LSP/plugins. Scripted headless only — never normal development.
 - Custom subagents (`.claude/agents/`) run autonomously and return results. Skills guide behavior; agents do work. Use for parallel tasks or fresh context. Examples: `sdlc-reviewer`, `ci-debug`, `test-writer`.

package/skills/setup/SKILL.md

@@ -228,9 +228,9 @@ Present suggestions and let the user confirm.
 
 ### Step 9.5: Context Window + Mixed-Mode Configuration (Opt-In)
 
-The CLI ships `cli/templates/settings.json` with **no** `model` or `env` pin by default. This preserves Claude Code's built-in model auto-selection (Sonnet for cheap tasks, Opus for hard ones) and the upstream autocompact threshold. Power users can opt into a pin during setup; mixed-mode users (Sonnet coder + Opus reviewer) can pin Sonnet here too.
+The CLI ships `cli/templates/settings.json` with **no** `model` or `env` pin by default. This preserves Claude Code's built-in model auto-selection. Power users can opt into a pin during setup — `opusplan` for cost-conscious SDLC, or `claude-opus-4-6` for full flagship.
 
-**Why this is opt-in (issue #198):** A top-level `"model"` in `settings.json` tells Claude Code "the user has explicitly chosen a model" and disables auto-mode for the session. That is a real tradeoff — pinning is only worth it when you actually need the 1M headroom or you've decided mixed-mode tier-splitting is better than per-turn auto-selection.
+**Why this is opt-in (issue #198):** A top-level `"model"` in `settings.json` disables auto-mode for the session. Pinning is only worth it when you want consistent model behavior (opusplan or flagship) rather than per-turn auto-selection.
 
 **Run the complexity heuristic first (roadmap #233):**
 
@@ -246,50 +246,58 @@ The output is JSON: `{ tier: "simple" | "complex", score, signals }`. Use the re
 >
 > How do you want to configure the model for this repo?
 >
-> - **[N] No pin (default, recommended for most repos):** Leaves auto-mode enabled. Claude Code picks the model per turn. Compaction follows upstream defaults. Simplest, lowest friction.
-> - **[m] Mixed-mode** *(suggested for **simple** tier — roadmap #233):* Pins `model: "sonnet[1m]"` for the coder (Sonnet 4.6 with 1M context). The cross-model review layer (Codex / external reviewer) **always stays at the flagship** (Opus 4.6 max or gpt-5.5 xhigh) regardless. Saves cost/quota on simple repos; reviewer catches what Sonnet misses. Requires comfort with losing per-turn auto-selection.
-> - **[f] Flagship full** *(wizard's recommended default — suggested for complex / stakes-flagged):* Pins `model: "claude-opus-4-6[1m]"` + `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30`. 4.6 max is the only Opus/max combo that doesn't overthink (Andon Labs, Huryn, BSWEN, r/Claudeopus). Avoids 4.7+ tokenizer tax. Anthropic-supported until ≥ Feb 5, 2027. Requires CC v2.1.154+.
-> - **[l] Latest** *(opt-in for Anthropic's newest Opus):* Pins `model: "claude-opus-4-8[1m]"`. Ships SWE-Bench Pro / Terminal-Bench / dynamic-workflows gains. Tradeoff: 40-60× cache token jump at HIGH, active false-green / token-burn regressions. Drop to `xhigh` (4.8's `max` is worse than `xhigh`).
+> - **[N] No pin (default):** Auto-mode. CC picks model per turn. Simplest.
+> - **[o] OpusPlan** *(recommended for cost-conscious SDLC):* Pins `model: "opusplan"`. Opus plans (Shift+Tab), Sonnet executes. Both 200K, Max-bundled. No API credit drain (#390).
+> - **[f] Flagship full** *(recommended for complex / high-stakes):* Pins `model: "claude-opus-4-6"`. Opus 4.6 max everywhere. Max-bundled (auto-upgrades to 1M on Max plans).
+> - **[l] Latest** *(opt-in bleeding-edge):* Pins `model: "claude-opus-4-8"`. Effort: always max (#395).
 >
-> `[N/m/f/l]`
+> `[N/o/f/l]`
 
 **If the user answers `N` (default):** Make no edits to `.claude/settings.json`. Auto-mode stays on. Done.
 
-**If the user answers `m` (mixed-mode):** Edit `.claude/settings.json` and add:
+**If the user answers `o` (opusplan):** Edit `.claude/settings.json` and add:
 
 ```json
 {
-  "model": "sonnet[1m]"
+  "model": "opusplan",
+  "advisorModel": "claude-opus-4-6",
+  "env": {
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
+    "CLAUDE_CODE_EFFORT_LEVEL": "max"
+  }
 }
 ```
 
-Do NOT add `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` for Sonnet — Sonnet's 1M window has different compaction characteristics than Opus; let the upstream default ride. Tell the user explicitly: "Cross-model reviews still run at the flagship — `codex exec -c 'model_reasoning_effort=\"xhigh\"'` (gpt-5.5) or any future Opus-tier reviewer. Mixed-mode is coder-only."
+Tell the user: "Opus reasons during Plan Mode (Shift+Tab), Sonnet executes. Both Max-bundled at 200K — no API credit drain. The Opus advisor auto-compensates for Sonnet's lighter reasoning at key decision points. Cross-model reviews still run at GPT-5.5 xhigh. Requires CC v2.1.170+ — run `! claude update` if needed."
 
-**If the user answers `f` (flagship):** Edit `.claude/settings.json` and add both fields at the top level:
+**If the user answers `f` (flagship):** Edit `.claude/settings.json` and add:
 
 ```json
 {
-  "model": "claude-opus-4-6[1m]",
+  "model": "claude-opus-4-6",
+  "advisorModel": "fable",
   "env": {
+    "CLAUDE_CODE_EFFORT_LEVEL": "max",
     "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30"
   }
 }
 ```
 
-Tell the user: "Pair this with `/effort max` — 4.6 is the only Opus version where `max` doesn't overthink. See [`README.md` § Choosing Your Model](../README.md#choosing-your-model) and `CLAUDE_CODE_SDLC_WIZARD.md` → 'Latest tier — Opus 4.8' for the full rationale + the opt-in alternative if you want Anthropic's newest model."
+Tell the user: "Opus 4.6 max everywhere with Fable 5 advisor. Fable auto-consults at key decision points (architecture, complexity, blast-radius). On Max plans, Opus auto-upgrades to 1M context — the autocompact override prevents early compaction at ~76K. Requires CC v2.1.170+ — run `! claude update` if needed."
 
 **If the user answers `l` (latest):** Edit `.claude/settings.json` and add:
 
 ```json
 {
-  "model": "claude-opus-4-8[1m]",
+  "model": "claude-opus-4-8",
+  "advisorModel": "fable",
   "env": {
-    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30"
+    "CLAUDE_CODE_EFFORT_LEVEL": "max"
   }
 }
 ```
 
-Tell the user: "Recommend dropping to `/effort xhigh` instead of `max` on 4.8 — strict effort behavior overcorrects at `max`. You'll want this if you're chasing SWE-Bench Pro / Terminal-Bench 2.1 / dynamic-workflows wins; otherwise the wizard's `[f] Flagship` (4.6 max) is the safer pick. Escape hatch: change the `model` value back to `claude-opus-4-6[1m]` or remove the line to fall back to auto-mode."
+Tell the user: "Always max effort on all Claude models (#395) with Fable 5 advisor. Fable auto-consults at key decision points. Requires CC v2.1.170+ — run `! claude update` if needed. Escape hatch: change `model` back to `claude-opus-4-6` or remove to fall back to auto-mode."
 
 Mention the escape hatch in all four cases:
 - To opt out later: remove the `model` line (and optionally the `env` block) from `.claude/settings.json`, or run `/model` and pick "Default (recommended)".
@@ -298,6 +306,16 @@ Mention the escape hatch in all four cases:
 
 This is project-scoped and shared with the team via git.
 
+**After writing project settings (for `[o]`, `[f]`, or `[l]`), ask once:**
+
+> Also set `advisorModel` in your global `~/.claude/settings.json`?
+> (Applies advisor to ALL your projects. Project-level always overrides.)
+> `[y/N]`
+
+Default No. If yes, read `~/.claude/settings.json`, add/update only the `advisorModel` key (do NOT touch other keys), write back. This is the only global settings mutation in setup besides Step 7.7's dead plugin cleanup.
+
+**Note:** Flagship, OpusPlan, and Latest choices include an advisor model that auto-consults at key decision points. Requires CC v2.1.170+ — run `! claude update` from inside a CC session if needed.
+
 ### Step 10: Customize Hooks
 
 Update `tdd-pretool-check.sh` with the actual source directory (replace generic `/src/` pattern).

package/skills/update/SKILL.md

@@ -93,9 +93,11 @@ Parse CHANGELOG entries between the user's installed version and latest. Present
 
 ```
 Installed: 1.42.0
-Latest:    1.80.0
+Latest:    1.82.0
 
 What changed:
+- [1.82.0] Usage diagnostics: fix /usage row, Reading Usage Signals guide, advisor fallback procedure, Fable effort guidance, autocompact cross-reference.
+- [1.81.0] Native `advisorModel` support: Setup A gets Fable advisor, Setup B gets Opus advisor. Replaces manual subagent spawning. Requires CC v2.1.170+.
 - [1.80.0] Flip default: Opus 4.6 max becomes recommended flagship; Opus 4.8 demoted to opt-in `[l] Latest` tier.
 - [1.79.0] Opus 4.6 Stability tier added as flagship alternative (now graduated to default in 1.80.0).
 - [1.78.0] Opus 4.7 → 4.8 model recommendation (#365) + min CC v2.1.154+.
@@ -176,8 +178,8 @@ Check user's `.claude/settings.json`:
    > Remove, keep, or decide later? `[r/k/l]`
 
 2. **Only one of the two fields matches** — treat as intentional customization. Do not prompt.
-3. **`model: "sonnet[1m]"`** (mixed-mode tier, #233, v1.38.0+) — explicit user choice. Mention in summary: "Detected mixed-mode tier (Sonnet coder + flagship reviewer). Cross-model review still uses Opus / gpt-5.5."
-4. **Other `model` value** (`sonnet`, `opus`) — explicit user choice. Do not touch.
+3. **`model: "sonnet[1m]"`** — ⚠️ warn: "sonnet[1m] draws from usage credits, not Max subscription (#390). Consider switching to `opusplan` (Opus plans, Sonnet executes, both Max-bundled) or plain `sonnet` (200K, Max-bundled)."
+4. **`model: "opusplan"`** or other value (`sonnet`, `opus`) — explicit user choice. Do not touch.
 5. **Neither field set** — already on new default.
 
 When removing: drop `model` (and `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` if `env` becomes empty). Never touch other keys.
@@ -224,35 +226,15 @@ If `cli/init.js` later adds wizard marketplace names, append verbatim.
 3. For every dead marketplace `<name>`, look for `enabledPlugins["sdlc-wizard@<name>"]` — also flag for removal.
 4. Repeat for **all** allowlist entries; collect the full set of dead pairs before prompting (multiple are common).
 
-**Cleanup (always ask, all-or-nothing per response):**
+**Cleanup:** List all dead pairs, ask `[y/N]`. If yes: `cp ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%Y%m%dT%H%M%S)`, then single `jq` filter: `del(.enabledPlugins["sdlc-wizard@<name>"]) | del(.extraKnownMarketplaces["<name>"])` for each dead key. Write to temp, validate with `jq empty`, then `mv`. If no: skip.
 
-> Your `~/.claude/settings.json` references wizard plugin marketplaces that don't exist on disk:
->
-> - `extraKnownMarketplaces.sdlc-wizard-local.source.path` → `<resolved-path>` (missing)
-> - `enabledPlugins["sdlc-wizard@sdlc-wizard-local"]` is `true`
-> - (list all dead pairs)
->
-> Causes `Plugin directory does not exist` on every prompt in every CC session.
->
-> Drop these entries from `~/.claude/settings.json`? `[y/N]`
-
-If yes:
-1. **Backup with timestamp**: `cp ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%Y%m%dT%H%M%S)` (two cleanups same day don't overwrite each other).
-2. **Single `jq` filter** dropping every dead marketplace + every dead `enabledPlugins` key in one pass: `jq 'del(.enabledPlugins["sdlc-wizard@sdlc-wizard-local"]) | del(.extraKnownMarketplaces["sdlc-wizard-local"]) | del(.enabledPlugins["sdlc-wizard@sdlc-wizard-wrap"]) | del(.extraKnownMarketplaces["sdlc-wizard-wrap"])'` — include only keys actually marked dead.
-3. Write to a temp file, validate with `jq empty` (round-trip parse), then `mv`. Validation fails → restore from backup.
-4. **Formatting note**: `jq` rewrites the whole file. Wizard does NOT preserve comments/trailing commas (CC's settings.json is strict JSON, so safe today). Tell the user.
-
-If no: skip silently. Some users have a recovery plan (re-enable, reinstall).
-
-**Idempotency:** rerunning Step 7.7 after a clean must be a no-op. Only marketplaces with allowlist match AND missing path qualify.
-
-**Scope guard:** only entries whose marketplace name matches the exact allowlist. Third-party plugin registrations (`legal@knowledge-work-plugins`, etc.) and unrelated `sdlc`-prefixed marketplaces (e.g. `danielscholl/claude-sdlc`) are never the wizard's business.
+**Guards:** Idempotent (no-op after clean). Scope: only allowlist matches. Runs regardless of version match. `check-only`: detect only, no mutations.
 
-**Why update, not setup:** setup runs once at install; plugin paths are valid by definition. Dead registrations only appear later, when something disables/renames/deletes the plugin directory. Update is the natural seam.
+### Step 7.8: advisorModel Migration (v2.1.170+)
 
-**Runs regardless of version match:** Step 7.7 is global-settings hygiene, not file-update logic. Must run even when wizard version matches latest (per Step 3 match-branch). Gating Step 7.7 on version mismatch would silently leave the error firing forever.
+If CC < v2.1.170: show "Run `! claude update` to upgrade" and skip. If `.claude/settings.json` already has `advisorModel` or no `model` pin: skip.
 
-**`check-only` precedence:** if `check-only` is set (whether versions match or not), Step 7.7 runs in detection-only mode: report dead registrations, do NOT prompt, do NOT execute `jq`, do NOT touch `~/.claude/settings.json`. Check-only must never mutate state.
+If `model` pin exists but no `advisorModel`, suggest: `claude-opus-4-6`/`claude-opus-4-8` → `advisorModel: "fable"`, `opusplan` → `advisorModel: "claude-opus-4-6"`. Ask `[a/S]`, write only `advisorModel` if accepted.
 
 ### Step 8: Apply Selected Changes