agentic-sdlc-wizard 1.80.0 → 1.81.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/AI_SETUP_LANES.md +192 -0
- package/CHANGELOG.md +22 -0
- package/CLAUDE_CODE_SDLC_WIZARD.md +84 -70
- package/README.md +21 -9
- package/cli/init.js +42 -4
- package/hooks/instructions-loaded-check.sh +3 -1
- package/hooks/model-effort-check.sh +34 -34
- package/package.json +2 -1
- package/skills/sdlc/SKILL.md +11 -9
- package/skills/setup/SKILL.md +34 -16
- package/skills/update/SKILL.md +9 -28
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# AI Setup Lanes
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
This is **guidance, not a hard rule**. Maintainer override is always allowed.
|
|
6
|
+
|
|
7
|
+
## Setup A — Claude Premium
|
|
8
|
+
|
|
9
|
+
| Role | Model |
|
|
10
|
+
|------|-------|
|
|
11
|
+
| **Advisor** | Fable 5 (via `advisorModel: "fable"` in project settings — auto-consults at key decisions) |
|
|
12
|
+
| **Driver** | Opus 4.6 max |
|
|
13
|
+
| **Reviewer** | Codex (GPT-5.5) xhigh |
|
|
14
|
+
| **Escalation** | + Fable 5 review (security, releases, wide-blast architecture only) |
|
|
15
|
+
|
|
16
|
+
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.
|
|
17
|
+
|
|
18
|
+
## Setup B — Claude Saver (OpusPlan)
|
|
19
|
+
|
|
20
|
+
| Role | Model |
|
|
21
|
+
|------|-------|
|
|
22
|
+
| **Planner** | Opus 4.6 max (via Plan Mode — Shift+Tab) |
|
|
23
|
+
| **Advisor** | Opus 4.6 (via `advisorModel: "claude-opus-4-6"` — compensates for Sonnet driver) |
|
|
24
|
+
| **Driver** | Sonnet (latest, auto execute mode) |
|
|
25
|
+
| **Reviewer** | Codex (GPT-5.5) xhigh |
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
## When to Use Setup A
|
|
30
|
+
|
|
31
|
+
Reach for Premium when the change can damage a consumer repo or has high blast radius:
|
|
32
|
+
|
|
33
|
+
- Architecture or methodology changes
|
|
34
|
+
- Tagged release prep
|
|
35
|
+
- Installer behavior (`cli/`, `init`, `setup-wizard`)
|
|
36
|
+
- Destructive file operations
|
|
37
|
+
- Package publishing
|
|
38
|
+
- Generated repo modifications (template changes)
|
|
39
|
+
- CI / release automation
|
|
40
|
+
- Security-sensitive behavior
|
|
41
|
+
- Anything that could damage a consumer repo
|
|
42
|
+
|
|
43
|
+
## When to Use Setup B
|
|
44
|
+
|
|
45
|
+
Setup B is sufficient for routine work where a Sonnet driver can ship with a strong reviewer:
|
|
46
|
+
|
|
47
|
+
- Routine implementation
|
|
48
|
+
- Documentation
|
|
49
|
+
- Examples
|
|
50
|
+
- Tests
|
|
51
|
+
- Normal CLI changes (non-installer)
|
|
52
|
+
- Low-risk methodology edits
|
|
53
|
+
- Mechanical refactors
|
|
54
|
+
|
|
55
|
+
## Setup C — Claude Lite
|
|
56
|
+
|
|
57
|
+
| Role | Model | Notes |
|
|
58
|
+
|------|-------|-------|
|
|
59
|
+
| **Planner** | You (the user) | Task is pre-planned, no model reasoning needed |
|
|
60
|
+
| **Driver** | Sonnet 4.6 | Same model as Setup B driver — Max-bundled, no extra model to manage |
|
|
61
|
+
| **Reviewer** | None | Blast radius too low for cross-model overhead |
|
|
62
|
+
|
|
63
|
+
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.
|
|
64
|
+
|
|
65
|
+
## When to Use Setup C
|
|
66
|
+
|
|
67
|
+
Setup C is for work where SDLC discipline overhead exceeds the value:
|
|
68
|
+
|
|
69
|
+
- Run a script with basic intelligence
|
|
70
|
+
- Deploy to staging (prod deploys need Setup A's discipline — human gate + rollback plan)
|
|
71
|
+
- Config updates, env var changes
|
|
72
|
+
- File moves, renames, bulk operations
|
|
73
|
+
- Repo maintenance (dependency bumps, lockfile refreshes)
|
|
74
|
+
- Simple administrative tasks across repos like `~/afterhours`
|
|
75
|
+
- Anything where blast radius is low and you need speed, not depth
|
|
76
|
+
|
|
77
|
+
**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.
|
|
78
|
+
|
|
79
|
+
## What Setup C explicitly skips
|
|
80
|
+
|
|
81
|
+
- No TDD (no test-first for running a deploy script)
|
|
82
|
+
- No cross-model review (not worth the cost or time for grunt work)
|
|
83
|
+
- No planning phase (you are the planner)
|
|
84
|
+
- No effort escalation (Sonnet standard is plenty)
|
|
85
|
+
|
|
86
|
+
**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.
|
|
87
|
+
|
|
88
|
+
## Final Review Policy
|
|
89
|
+
|
|
90
|
+
**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.
|
|
91
|
+
|
|
92
|
+
**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.
|
|
93
|
+
|
|
94
|
+
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.
|
|
95
|
+
|
|
96
|
+
## Version Requirement
|
|
97
|
+
|
|
98
|
+
`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:
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
! claude update
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
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.
|
|
105
|
+
|
|
106
|
+
Fable 5 as advisor also requires Fable 5 access for your organization/plan (free on Max through June 22, 2026).
|
|
107
|
+
|
|
108
|
+
## Credit-Spend Warning
|
|
109
|
+
|
|
110
|
+
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:
|
|
111
|
+
|
|
112
|
+
- Drop to Setup B for the remainder of the day
|
|
113
|
+
- Or drop to Setup C for grunt work that doesn't need Opus reasoning
|
|
114
|
+
- Or use Sonnet directly for the final mechanical edits, then run the GPT-5.5 reviewer over the whole diff at the end
|
|
115
|
+
|
|
116
|
+
**Setup C uses Sonnet** — same model as Setup B's driver, Max-bundled. One less model to manage.
|
|
117
|
+
|
|
118
|
+
The reviewer (GPT-5.5 xhigh) is billed against your OpenAI account, separately. Watch both bills.
|
|
119
|
+
|
|
120
|
+
## How Billing Works — 1M Context, Max Plan, and the June 15 Split
|
|
121
|
+
|
|
122
|
+
A common question: **"does the `[1m]` model alias get billed differently? Does it pull from my Max plan or from API credits?"**
|
|
123
|
+
|
|
124
|
+
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.
|
|
125
|
+
|
|
126
|
+
### 1M context is free on Max — no API premium
|
|
127
|
+
|
|
128
|
+
[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.
|
|
129
|
+
|
|
130
|
+
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.
|
|
131
|
+
|
|
132
|
+
(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.)
|
|
133
|
+
|
|
134
|
+
### The June 15, 2026 billing split
|
|
135
|
+
|
|
136
|
+
[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:
|
|
137
|
+
|
|
138
|
+
| Surface | Billing as of June 15, 2026 |
|
|
139
|
+
|---|---|
|
|
140
|
+
| **Interactive Claude Code in terminal** (you typing into Claude Code right now) | **Stays on Max subscription** — unchanged |
|
|
141
|
+
| Claude.ai web / desktop / mobile chat | Stays on Max subscription |
|
|
142
|
+
| Claude Cowork | Stays on Max subscription |
|
|
143
|
+
| `claude -p` (headless / `--print`) | **Moves to separate credit pool**, billed at API rates |
|
|
144
|
+
| Claude Agent SDK | Moves to separate credit pool |
|
|
145
|
+
| Claude Code GitHub Actions | Moves to separate credit pool |
|
|
146
|
+
| Third-party apps via Agent SDK | Moves to separate credit pool |
|
|
147
|
+
|
|
148
|
+
Credit allocations: Pro $20/mo, Max 5x $100/mo, Max 20x $200/mo. **No rollover.**
|
|
149
|
+
|
|
150
|
+
### What this means for the lanes
|
|
151
|
+
|
|
152
|
+
- **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.
|
|
153
|
+
- **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).
|
|
154
|
+
- **⚠️ 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.
|
|
155
|
+
- **Reviewer (GPT-5.5 xhigh) in both lanes:** billed against your OpenAI account, completely separate from Anthropic.
|
|
156
|
+
- **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.
|
|
157
|
+
|
|
158
|
+
### Caveat: Setup B's cost-saving has conditions
|
|
159
|
+
|
|
160
|
+
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:
|
|
161
|
+
|
|
162
|
+
| Mode | Per-token rate | Pool |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| Setup A — Opus 4.6 1M | $5/$25 per Mtok | **Max subscription** |
|
|
165
|
+
| Setup B — Sonnet 4.6 standard | $3/$15 per Mtok | **Max subscription** |
|
|
166
|
+
| Setup B — Sonnet 4.6 1M | $3/$15 per Mtok | **Credits pool** |
|
|
167
|
+
|
|
168
|
+
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.
|
|
169
|
+
|
|
170
|
+
**Practical guidance:**
|
|
171
|
+
|
|
172
|
+
- **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.
|
|
173
|
+
- **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.
|
|
174
|
+
- **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.
|
|
175
|
+
|
|
176
|
+
### Bottom line
|
|
177
|
+
|
|
178
|
+
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.
|
|
179
|
+
|
|
180
|
+
Watch the headless surface if you've automated `claude -p` calls in your project — those now bill differently as of June 15, 2026.
|
|
181
|
+
|
|
182
|
+
## Maintainer Override
|
|
183
|
+
|
|
184
|
+
**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.
|
|
185
|
+
|
|
186
|
+
The wizard does not enforce setup lane selection — it documents the recommended default per change shape. Whatever ships is your call.
|
|
187
|
+
|
|
188
|
+
## See Also
|
|
189
|
+
|
|
190
|
+
- [`CLAUDE_CODE_SDLC_WIZARD.md`](CLAUDE_CODE_SDLC_WIZARD.md) — Full wizard doc, including Stability tier opt-in for the wider model choice
|
|
191
|
+
- [`README.md` § Choosing Your Model](README.md#choosing-your-model) — Model selection philosophy
|
|
192
|
+
- [`AGENTS.md`](AGENTS.md) — Codex/reviewer guidelines used in both lanes
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,28 @@ All notable changes to the SDLC Wizard.
|
|
|
4
4
|
|
|
5
5
|
> **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.
|
|
6
6
|
|
|
7
|
+
## [1.81.0] - 2026-06-10
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- **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.
|
|
12
|
+
|
|
13
|
+
- **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.
|
|
14
|
+
|
|
15
|
+
- **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+.
|
|
16
|
+
|
|
17
|
+
- **CLI init.js smart-merge handles `advisorModel`.** Same pattern as `model` — only set if missing, preserve on `--force`.
|
|
18
|
+
|
|
19
|
+
- **This repo dogfoods Setup A.** Project settings now include `model: "claude-opus-4-6"` + `advisorModel: "fable"`.
|
|
20
|
+
|
|
21
|
+
- **Documented `! claude update` tip** for users needing v2.1.170+ — the `!` prefix runs shell commands inside a CC session without exiting.
|
|
22
|
+
|
|
23
|
+
### Why
|
|
24
|
+
|
|
25
|
+
- 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).
|
|
26
|
+
|
|
27
|
+
- 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.
|
|
28
|
+
|
|
7
29
|
## [1.80.0] - 2026-06-09
|
|
8
30
|
|
|
9
31
|
### Changed
|
|
@@ -249,13 +249,12 @@ When Anthropic provides official plugins or tools that handle something:
|
|
|
249
249
|
|
|
250
250
|
Claude Code's **effort level** controls how much thinking the model does before responding. Higher effort = deeper reasoning but more tokens.
|
|
251
251
|
|
|
252
|
-
> ⚠️ **
|
|
252
|
+
> ⚠️ **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).
|
|
253
253
|
|
|
254
254
|
| Level | When to Use | How to Set |
|
|
255
255
|
|-------|-------------|------------|
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `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) |
|
|
256
|
+
| `max` | **Required for all SDLC work.** Claude: max. OpenAI/Codex: xhigh (their highest). | `CLAUDE_CODE_EFFORT_LEVEL=max` in settings env block |
|
|
257
|
+
| `high` or below | **Not for SDLC work.** Only for trivial grep/search subagents | `effort: high` in a specific subagent frontmatter only |
|
|
259
258
|
|
|
260
259
|
**Strict effort behavior (Opus 4.7+, carried forward in 4.8 — and why 4.6 max is the wizard's pick):**
|
|
261
260
|
- **`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
|
|
|
267
266
|
|
|
268
267
|
**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.
|
|
269
268
|
|
|
270
|
-
**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
|
|
269
|
+
**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.
|
|
271
270
|
|
|
272
|
-
The `/sdlc` skill sets `effort:
|
|
271
|
+
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.
|
|
273
272
|
|
|
274
|
-
**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
|
|
273
|
+
**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.
|
|
275
274
|
|
|
276
275
|
**When to escalate to `max`:**
|
|
277
276
|
- 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
|
|
|
282
281
|
|
|
283
282
|
**How it works:**
|
|
284
283
|
- `/effort max` changes effort for the current session only (resets next session)
|
|
285
|
-
- `effort:
|
|
284
|
+
- `effort: max` in SKILL.md frontmatter persists — every `/sdlc` invocation uses `max`
|
|
286
285
|
- You can also type `ultrathink` in any prompt for a single high-effort turn
|
|
287
286
|
|
|
288
|
-
**Cost note:** `max` uses
|
|
287
|
+
**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.
|
|
289
288
|
|
|
290
289
|
> 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`.
|
|
291
290
|
|
|
292
291
|
### Anti-Laziness Guidance for CLAUDE.md
|
|
293
292
|
|
|
294
|
-
If you notice Claude Code producing shallow outputs despite `effort:
|
|
293
|
+
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:
|
|
295
294
|
|
|
296
295
|
```markdown
|
|
297
296
|
## Quality Anchoring
|
|
298
|
-
- This project uses effort:
|
|
297
|
+
- This project uses effort: max via SDLC skill frontmatter. Do not reduce reasoning depth.
|
|
299
298
|
- Adaptive thinking may under-allocate your thinking budget on complex tasks. When working on
|
|
300
299
|
multi-file changes, architecture decisions, or debugging: reason through the full problem
|
|
301
300
|
before acting, even if the system prompt suggests taking the "simplest approach first."
|
|
302
301
|
- If you catch yourself skipping steps, re-read the task requirements and verify completeness.
|
|
303
302
|
```
|
|
304
303
|
|
|
305
|
-
**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:
|
|
304
|
+
**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.
|
|
306
305
|
|
|
307
306
|
---
|
|
308
307
|
|
|
@@ -393,6 +392,34 @@ New built-in commands available to use alongside the wizard:
|
|
|
393
392
|
|
|
394
393
|
**Tip**: `/simplify` pairs well with the self-review phase. Run it after implementation as an additional quality check.
|
|
395
394
|
|
|
395
|
+
### Advisor Model (v2.1.170+)
|
|
396
|
+
|
|
397
|
+
**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.
|
|
398
|
+
|
|
399
|
+
**Three ways to enable:**
|
|
400
|
+
|
|
401
|
+
| Method | Scope | Persists? |
|
|
402
|
+
|--------|-------|-----------|
|
|
403
|
+
| `"advisorModel": "fable"` in `.claude/settings.json` | Project | Yes (committed, shared with team) |
|
|
404
|
+
| `/advisor fable` | User (global `~/.claude/settings.json`) | Yes (all projects) |
|
|
405
|
+
| `--advisor fable` CLI flag | Session | No |
|
|
406
|
+
|
|
407
|
+
**Recommended pairings:**
|
|
408
|
+
|
|
409
|
+
| Driver | Advisor | Lane |
|
|
410
|
+
|--------|---------|------|
|
|
411
|
+
| Opus 4.6 (`claude-opus-4-6`) | Fable (`"fable"`) | Setup A — Premium |
|
|
412
|
+
| Sonnet via opusplan | Opus (`"claude-opus-4-6"`) | Setup B — Saver |
|
|
413
|
+
| Opus 4.8 (`claude-opus-4-8`) | Fable (`"fable"`) | Latest tier |
|
|
414
|
+
|
|
415
|
+
**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.
|
|
416
|
+
|
|
417
|
+
**Important:** Fable does NOT appear in the `/advisor` interactive picker. Set it via `/advisor fable`, `--advisor fable`, or `advisorModel: "fable"` in settings.json.
|
|
418
|
+
|
|
419
|
+
**Billing:** Advisor queries in interactive sessions are Max-bundled (same pool as the driver). The advisor does not trigger headless/credit-pool billing.
|
|
420
|
+
|
|
421
|
+
**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.
|
|
422
|
+
|
|
396
423
|
### Skill Frontmatter Fields (v2.1.80+)
|
|
397
424
|
|
|
398
425
|
Skills support these frontmatter fields:
|
|
@@ -401,14 +428,14 @@ Skills support these frontmatter fields:
|
|
|
401
428
|
|-------|---------|---------|
|
|
402
429
|
| `name` | Skill name (matches `/command`) | `name: sdlc` |
|
|
403
430
|
| `description` | Trigger description for auto-invocation | `description: Full SDLC workflow...` |
|
|
404
|
-
| `effort` | Set reasoning effort level | `effort:
|
|
431
|
+
| `effort` | Set reasoning effort level | `effort: max` |
|
|
405
432
|
| `paths` | Restrict skill to specific file patterns | `paths: ["src/**/*.ts", "tests/**"]` |
|
|
406
433
|
| `context` | Context mode (`fork` = isolated subagent) | `context: fork` |
|
|
407
434
|
| `argument-hint` | Hint for `$ARGUMENTS` placeholder | `argument-hint: [task description]` |
|
|
408
435
|
| `disable-model-invocation` | Prevent skill from being auto-invoked by model | `disable-model-invocation: true` |
|
|
409
436
|
|
|
410
437
|
**Key fields explained:**
|
|
411
|
-
- **`effort:
|
|
438
|
+
- **`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+).
|
|
412
439
|
- **`paths:`** — Limits when a skill activates based on files being worked on. Useful for language-specific or directory-specific skills.
|
|
413
440
|
- **`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.
|
|
414
441
|
|
|
@@ -481,7 +508,7 @@ When a cached prompt prefix is re-served after idle pruning, downstream thinking
|
|
|
481
508
|
|
|
482
509
|
**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.
|
|
483
510
|
|
|
484
|
-
**Detection signal**: the wizard's `model-effort-check.sh`
|
|
511
|
+
**Detection signal**: the wizard's `model-effort-check.sh` loud-warns below `max`. Combine with token-spike anomaly detection (ROADMAP #220) once shipped.
|
|
485
512
|
|
|
486
513
|
### Prompt brevity caps can compound across turns (post-mortem 2026-04-23)
|
|
487
514
|
|
|
@@ -967,14 +994,16 @@ Override the default auto-compact threshold with environment variables. These ar
|
|
|
967
994
|
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Trigger compaction at this % of context capacity (1-100) | ~95% |
|
|
968
995
|
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Override context capacity in tokens (useful for 1M models) | Model default |
|
|
969
996
|
|
|
970
|
-
**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
|
|
997
|
+
**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.
|
|
971
998
|
|
|
972
|
-
To opt in by hand, edit `.claude/settings.json
|
|
999
|
+
To opt in by hand, edit `.claude/settings.json` (flagship example):
|
|
973
1000
|
|
|
974
1001
|
```json
|
|
975
1002
|
{
|
|
976
|
-
"model": "opus
|
|
1003
|
+
"model": "claude-opus-4-6",
|
|
1004
|
+
"advisorModel": "fable",
|
|
977
1005
|
"env": {
|
|
1006
|
+
"CLAUDE_CODE_EFFORT_LEVEL": "max",
|
|
978
1007
|
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30"
|
|
979
1008
|
}
|
|
980
1009
|
}
|
|
@@ -1036,40 +1065,33 @@ Claude Code supports both 200K and 1M context windows. **`opus[1m]` is an opt-in
|
|
|
1036
1065
|
|
|
1037
1066
|
**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.
|
|
1038
1067
|
|
|
1039
|
-
###
|
|
1040
|
-
|
|
1041
|
-
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.
|
|
1042
|
-
|
|
1043
|
-
**The split:**
|
|
1044
|
-
|
|
1045
|
-
| Layer | Mixed-mode tier | Flagship tier |
|
|
1046
|
-
|-------|----------------|---------------|
|
|
1047
|
-
| Coder (in-session CC) | `model: "sonnet[1m]"` | `model: "opus[1m]"` |
|
|
1048
|
-
| 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) |
|
|
1049
|
-
| Effort floor (CC session) | xhigh; max preferred | xhigh; max preferred |
|
|
1050
|
-
|
|
1051
|
-
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.
|
|
1068
|
+
### OpusPlan Tier (Opus planner + Sonnet driver, #395)
|
|
1052
1069
|
|
|
1053
|
-
|
|
1054
|
-
- Repo is small (LOC < 10K), few tests (< 30), few hooks (< 5), few workflows (< 5), no `.env` / secrets handling
|
|
1055
|
-
- You're on API billing (not Max subscription) and 2× cost on simple repos actually matters
|
|
1056
|
-
- Tasks are predominantly mechanical — typo fixes, config tweaks, small CRUD endpoints
|
|
1057
|
-
- You're running the SDLC Wizard's setup flow against a sibling repo where the coder doesn't need flagship reasoning
|
|
1070
|
+
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.
|
|
1058
1071
|
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1072
|
+
| Layer | OpusPlan tier | Flagship tier |
|
|
1073
|
+
|-------|--------------|---------------|
|
|
1074
|
+
| Planner | Opus 4.6 max (Plan Mode) | Opus 4.6 max |
|
|
1075
|
+
| Driver | Sonnet 4.6 (execute mode) | Opus 4.6 max |
|
|
1076
|
+
| Reviewer | GPT-5.5 xhigh | GPT-5.5 xhigh |
|
|
1077
|
+
| Effort | max (via `CLAUDE_CODE_EFFORT_LEVEL` env var) | max |
|
|
1063
1078
|
|
|
1064
|
-
**
|
|
1065
|
-
|
|
1066
|
-
**How to opt in (manual):**
|
|
1079
|
+
**How to opt in:**
|
|
1067
1080
|
```json
|
|
1068
1081
|
{
|
|
1069
|
-
"model": "
|
|
1082
|
+
"model": "opusplan",
|
|
1083
|
+
"env": {
|
|
1084
|
+
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
|
|
1085
|
+
"CLAUDE_CODE_EFFORT_LEVEL": "max"
|
|
1086
|
+
}
|
|
1070
1087
|
}
|
|
1071
1088
|
```
|
|
1072
|
-
|
|
1089
|
+
|
|
1090
|
+
**⚠️ 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.
|
|
1091
|
+
|
|
1092
|
+
**When to use OpusPlan:** routine SDLC work, simple repos, cost-conscious sessions. Press Shift+Tab before architecture/blast-radius decisions to get Opus reasoning.
|
|
1093
|
+
|
|
1094
|
+
**When to stay Flagship:** stakes-flagged repos, architecture work, security review, long shepherd sessions.
|
|
1073
1095
|
|
|
1074
1096
|
**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.
|
|
1075
1097
|
|
|
@@ -1089,7 +1111,7 @@ The wizard's flagship recommendation is Opus 4.6 max (see "Choosing Your Model"
|
|
|
1089
1111
|
|
|
1090
1112
|
**Tradeoffs (be honest):**
|
|
1091
1113
|
- **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
|
|
1092
|
-
-
|
|
1114
|
+
- **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)
|
|
1093
1115
|
- 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))
|
|
1094
1116
|
- [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
|
|
1095
1117
|
- 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"
|
|
|
1099
1121
|
Edit `~/.claude/settings.json`:
|
|
1100
1122
|
```json
|
|
1101
1123
|
{
|
|
1124
|
+
"model": "claude-opus-4-8",
|
|
1102
1125
|
"env": {
|
|
1103
|
-
"
|
|
1104
|
-
|
|
1105
|
-
},
|
|
1106
|
-
"model": "opus[1m]"
|
|
1126
|
+
"CLAUDE_CODE_EFFORT_LEVEL": "max"
|
|
1127
|
+
}
|
|
1107
1128
|
}
|
|
1108
1129
|
```
|
|
1109
1130
|
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
**Project-scoped (single repo):**
|
|
1113
|
-
```json
|
|
1114
|
-
{
|
|
1115
|
-
"model": "claude-opus-4-8[1m]"
|
|
1116
|
-
}
|
|
1117
|
-
```
|
|
1131
|
+
On Max plans, Opus auto-upgrades to 1M context. No `[1m]` suffix needed.
|
|
1118
1132
|
|
|
1119
|
-
**Effort tuning for 4.8:** field signal
|
|
1133
|
+
**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).
|
|
1120
1134
|
|
|
1121
1135
|
**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.
|
|
1122
1136
|
|
|
@@ -2271,7 +2285,7 @@ TodoWrite([
|
|
|
2271
2285
|
{ content: "DRY check: Is logic duplicated elsewhere?", status: "pending", activeForm: "Checking for duplication" },
|
|
2272
2286
|
{ content: "Self-review: run /code-review", status: "pending", activeForm: "Running code review" },
|
|
2273
2287
|
{ content: "Security review (if warranted)", status: "pending", activeForm: "Checking security implications" },
|
|
2274
|
-
{ content: "Cross-model review (
|
|
2288
|
+
{ content: "Cross-model review (REQUIRED for high-stakes)", status: "pending", activeForm: "Running cross-model review" },
|
|
2275
2289
|
// CI FEEDBACK LOOP (After local tests pass)
|
|
2276
2290
|
{ content: "Commit and push to remote", status: "pending", activeForm: "Pushing to remote" },
|
|
2277
2291
|
{ 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:
|
|
|
2340
2354
|
|
|
2341
2355
|
| Level | Meaning | Action | Effort |
|
|
2342
2356
|
|-------|---------|--------|--------|
|
|
2343
|
-
| HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval | `
|
|
2344
|
-
| MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties | `
|
|
2345
|
-
| LOW (<60%) | Not sure | ASK USER before proceeding | **Run `/effort
|
|
2357
|
+
| HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval | `max` (default) |
|
|
2358
|
+
| MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties | `max` (default) |
|
|
2359
|
+
| LOW (<60%) | Not sure | ASK USER before proceeding | **Run `/effort max` now** — don't wait |
|
|
2346
2360
|
| FAILED 2x | Something's wrong | STOP. ASK USER immediately | **Run `/effort max` now** — you're burning cycles at lower effort |
|
|
2347
2361
|
| CONFUSED | Can't diagnose why something is failing | STOP. Describe what you tried, ask for help | **Run `/effort max` now** — stop spinning |
|
|
2348
2362
|
|
|
@@ -2372,10 +2386,10 @@ PLANNING → DOCS → TDD RED → TDD GREEN → Tests Pass → Self-Review
|
|
|
2372
2386
|
4. Issues below 80 are likely false positives — skip unless obviously valid
|
|
2373
2387
|
5. Address issues by going back through the proper SDLC loop
|
|
2374
2388
|
|
|
2375
|
-
## Cross-Model Review (
|
|
2389
|
+
## Cross-Model Review (REQUIRED for High-Stakes)
|
|
2376
2390
|
|
|
2377
2391
|
**When to run:** High-stakes changes (auth, payments, data handling), releases/publishes (version bumps, CHANGELOG, npm publish), complex refactors, research-heavy work.
|
|
2378
|
-
**When to skip:** Trivial changes (typo fixes, config tweaks), time-sensitive hotfixes, risk < review cost.
|
|
2392
|
+
**When to skip (log justification):** Trivial changes (typo fixes, config tweaks), time-sensitive hotfixes, risk < review cost.
|
|
2379
2393
|
|
|
2380
2394
|
**Prerequisites:** Codex CLI installed (`npm i -g @openai/codex`), OpenAI API key set.
|
|
2381
2395
|
|
|
@@ -2486,7 +2500,7 @@ Self-review passes → handoff.json (round 1, PENDING_REVIEW)
|
|
|
2486
2500
|
|
|
2487
2501
|
**Tool-agnostic:** The value is adversarial diversity (different model, different blind spots), not the specific tool. Any competing AI reviewer works.
|
|
2488
2502
|
|
|
2489
|
-
**Full protocol:** See the "Cross-Model Review Loop
|
|
2503
|
+
**Full protocol:** See the "Cross-Model Review Loop" section below for key flags and reasoning effort guidance.
|
|
2490
2504
|
|
|
2491
2505
|
### Release Review Focus
|
|
2492
2506
|
|
|
@@ -3027,7 +3041,7 @@ If deployment fails or post-deploy verification catches issues:
|
|
|
3027
3041
|
|
|
3028
3042
|
**SDLC.md:**
|
|
3029
3043
|
```markdown
|
|
3030
|
-
<!-- SDLC Wizard Version: 1.
|
|
3044
|
+
<!-- SDLC Wizard Version: 1.81.0 -->
|
|
3031
3045
|
<!-- Setup Date: [DATE] -->
|
|
3032
3046
|
<!-- 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 -->
|
|
3033
3047
|
<!-- Git Workflow: [PRs or Solo] -->
|
|
@@ -3787,7 +3801,7 @@ Claude: [fetches via gh api, discusses with you interactively]
|
|
|
3787
3801
|
|
|
3788
3802
|
This is optional - skip if you prefer fresh reviews only.
|
|
3789
3803
|
|
|
3790
|
-
### Cross-Model Review Loop (
|
|
3804
|
+
### Cross-Model Review Loop (REQUIRED for High-Stakes)
|
|
3791
3805
|
|
|
3792
3806
|
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.
|
|
3793
3807
|
|
|
@@ -4164,7 +4178,7 @@ Every wizard step has a unique ID for tracking:
|
|
|
4164
4178
|
| `step-9` | SDLC/TESTING/ARCH docs | 1.0.0 |
|
|
4165
4179
|
| `question-git-workflow` | Git workflow preference | 1.2.0 |
|
|
4166
4180
|
| `step-update-notify` | Optional: CI update notification | 1.13.0 |
|
|
4167
|
-
| `step-cross-model-review` |
|
|
4181
|
+
| `step-cross-model-review` | Cross-model review (REQUIRED for high-stakes) | 1.16.0 |
|
|
4168
4182
|
| `step-update-wizard` | /update-wizard smart update skill | 1.18.0 |
|
|
4169
4183
|
|
|
4170
4184
|
When checking for updates, Claude compares user's completed steps against this registry.
|
|
@@ -4472,7 +4486,7 @@ The wizard watches the **Anthropic API changelog** — not just Claude Code CLI
|
|
|
4472
4486
|
|
|
4473
4487
|
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.
|
|
4474
4488
|
|
|
4475
|
-
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.
|
|
4489
|
+
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.
|
|
4476
4490
|
|
|
4477
4491
|
**Complementary native skills worth knowing:**
|
|
4478
4492
|
|
package/README.md
CHANGED
|
@@ -113,7 +113,7 @@ Layer 1: PHILOSOPHY
|
|
|
113
113
|
| **Pre-tool TDD hooks** | Before source edits, a hook reminds Claude to write tests first. CI scoring checks whether it actually followed TDD |
|
|
114
114
|
| **Self-evolving loop** | Weekly/monthly external research + local CI shepherd loop — you approve, the system gets better |
|
|
115
115
|
|
|
116
|
-
##
|
|
116
|
+
## Cross-Model Review (Codex) — REQUIRED for High-Stakes
|
|
117
117
|
|
|
118
118
|
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**:
|
|
119
119
|
|
|
@@ -136,7 +136,7 @@ codex exec -c 'model_reasoning_effort="xhigh"' -s danger-full-access \
|
|
|
136
136
|
|
|
137
137
|
**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.
|
|
138
138
|
|
|
139
|
-
`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-
|
|
139
|
+
`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.
|
|
140
140
|
|
|
141
141
|
## Choosing Your Model
|
|
142
142
|
|
|
@@ -168,25 +168,37 @@ Six independent sources converging on the same conclusion: **4.6 is the only Opu
|
|
|
168
168
|
|
|
169
169
|
### Latest tier — Opus 4.8 (opt-in)
|
|
170
170
|
|
|
171
|
-
If you want the newest benchmarks and you're comfortable with the token-burn tradeoff, pick `[l] Latest` in the setup wizard.
|
|
171
|
+
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.
|
|
172
172
|
|
|
173
173
|
### Switch any time
|
|
174
174
|
|
|
175
175
|
```bash
|
|
176
|
-
/model claude-opus-4-6
|
|
177
|
-
/model
|
|
178
|
-
/model opus
|
|
176
|
+
/model claude-opus-4-6 # wizard's recommended flagship (default in v1.80.0+)
|
|
177
|
+
/model opusplan # Opus plans (Shift+Tab), Sonnet executes — both Max-bundled
|
|
178
|
+
/model claude-opus-4-8 # Anthropic's latest, opt-in via Latest tier
|
|
179
179
|
```
|
|
180
180
|
|
|
181
181
|
Or pin in `.claude/settings.json`:
|
|
182
182
|
|
|
183
183
|
```json
|
|
184
|
-
{ "model": "claude-opus-4-6
|
|
184
|
+
{ "model": "claude-opus-4-6", "env": { "CLAUDE_CODE_EFFORT_LEVEL": "max" } }
|
|
185
185
|
```
|
|
186
186
|
|
|
187
|
-
Or sweep all your projects
|
|
187
|
+
Or sweep all your projects by setting `ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6` in `~/.claude/settings.json`.
|
|
188
188
|
|
|
189
|
-
Effort
|
|
189
|
+
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).
|
|
190
|
+
|
|
191
|
+
### Three Setup Lanes
|
|
192
|
+
|
|
193
|
+
The wizard defines three AI coding setups in [`AI_SETUP_LANES.md`](AI_SETUP_LANES.md):
|
|
194
|
+
|
|
195
|
+
| Lane | Advisor | Driver | Reviewer | Escalation |
|
|
196
|
+
|------|---------|--------|----------|------------|
|
|
197
|
+
| **A — Premium** | Fable 5 (advisorModel) | Opus 4.6 max | GPT-5.5 xhigh | + Fable review (security/release/architecture) |
|
|
198
|
+
| **B — Saver** | Opus 4.6 (advisorModel) | Sonnet | GPT-5.5 xhigh | None |
|
|
199
|
+
| **C — Lite** | None | Sonnet | None | None |
|
|
200
|
+
|
|
201
|
+
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.
|
|
190
202
|
|
|
191
203
|
**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).
|
|
192
204
|
|
package/cli/init.js
CHANGED
|
@@ -83,6 +83,10 @@ function mergeSettings(existingPath, templatePath, force) {
|
|
|
83
83
|
existing.model = template.model;
|
|
84
84
|
}
|
|
85
85
|
|
|
86
|
+
if (template.advisorModel && (!('advisorModel' in existing) || force)) {
|
|
87
|
+
existing.advisorModel = template.advisorModel;
|
|
88
|
+
}
|
|
89
|
+
|
|
86
90
|
// Merge cleanupPeriodDays (ROADMAP #225): only set the template default when
|
|
87
91
|
// the user has not chosen a value. NEVER overwrite under --force — retention
|
|
88
92
|
// policy is a user preference (they may want >30 for long pauses, or <30 for
|
|
@@ -532,16 +536,50 @@ function buildUpdateRecommendation(updateInfo, customizedCount) {
|
|
|
532
536
|
return lines;
|
|
533
537
|
}
|
|
534
538
|
|
|
539
|
+
function settingsHooksMatch(srcPath, destPath) {
|
|
540
|
+
try {
|
|
541
|
+
const src = JSON.parse(fs.readFileSync(srcPath, 'utf8'));
|
|
542
|
+
const dest = JSON.parse(fs.readFileSync(destPath, 'utf8'));
|
|
543
|
+
for (const [event, entries] of Object.entries(src.hooks || {})) {
|
|
544
|
+
if (!dest.hooks || !dest.hooks[event]) return false;
|
|
545
|
+
const templateEntry = entries[0];
|
|
546
|
+
if (!templateEntry || !templateEntry.hooks) continue;
|
|
547
|
+
for (const th of templateEntry.hooks) {
|
|
548
|
+
if (!th.command) continue;
|
|
549
|
+
const marker = WIZARD_HOOK_MARKERS.find((m) => th.command.includes(m));
|
|
550
|
+
if (!marker) continue;
|
|
551
|
+
// Verify marker present AND type matches. We intentionally skip matcher/if
|
|
552
|
+
// comparison — those are customizable per-project (the wizard's own settings
|
|
553
|
+
// use different if guards than the consumer template).
|
|
554
|
+
const found = dest.hooks[event].some(
|
|
555
|
+
(de) => de.hooks && de.hooks.some(
|
|
556
|
+
(h) => h.command && h.command.includes(marker) && h.type === (th.type || 'command')
|
|
557
|
+
)
|
|
558
|
+
);
|
|
559
|
+
if (!found) return false;
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
return true;
|
|
563
|
+
} catch (_) {
|
|
564
|
+
return false;
|
|
565
|
+
}
|
|
566
|
+
}
|
|
567
|
+
|
|
535
568
|
function checkFile(srcPath, destPath, relativeDest, shouldBeExecutable) {
|
|
536
569
|
if (!fs.existsSync(destPath)) {
|
|
537
570
|
return { file: relativeDest, status: 'MISSING' };
|
|
538
571
|
}
|
|
539
572
|
const srcHash = crypto.createHash('sha256').update(fs.readFileSync(srcPath)).digest('hex');
|
|
540
573
|
const destHash = crypto.createHash('sha256').update(fs.readFileSync(destPath)).digest('hex');
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
}
|
|
574
|
+
let fileStatus;
|
|
575
|
+
if (srcHash === destHash) {
|
|
576
|
+
fileStatus = 'MATCH';
|
|
577
|
+
} else if (relativeDest === '.claude/settings.json' && settingsHooksMatch(srcPath, destPath)) {
|
|
578
|
+
fileStatus = 'MATCH';
|
|
579
|
+
} else {
|
|
580
|
+
fileStatus = 'CUSTOMIZED';
|
|
581
|
+
}
|
|
582
|
+
const result = { file: relativeDest, status: fileStatus };
|
|
545
583
|
|
|
546
584
|
if (shouldBeExecutable) {
|
|
547
585
|
try {
|
|
@@ -256,7 +256,9 @@ if [ -f "$PROJECT_DIR/.github/workflows/weekly-update.yml" ] && \
|
|
|
256
256
|
fi
|
|
257
257
|
|
|
258
258
|
# Claude Code version check (non-blocking, best-effort)
|
|
259
|
-
|
|
259
|
+
# Gate on CLAUDE_PROJECT_DIR — only Claude Code sets this. Without it, we're
|
|
260
|
+
# running under Codex/OpenCode where a CC update nudge is misleading (#375).
|
|
261
|
+
if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && command -v claude > /dev/null 2>&1 && command -v npm > /dev/null 2>&1; then
|
|
260
262
|
CC_LOCAL=$(claude --version 2>/dev/null | grep -o '[0-9][0-9.]*' | head -1) || true
|
|
261
263
|
if [ -n "$CC_LOCAL" ]; then
|
|
262
264
|
CC_LATEST=$(npm view @anthropic-ai/claude-code version 2>/dev/null) || true
|
|
@@ -1,67 +1,67 @@
|
|
|
1
1
|
#!/bin/bash
|
|
2
2
|
# SessionStart hook — effort/model nudge.
|
|
3
3
|
#
|
|
4
|
-
# Behavior (
|
|
5
|
-
#
|
|
6
|
-
#
|
|
7
|
-
#
|
|
8
|
-
# Opus 4.6 max needs xhigh floor for SDLC compliance (TDD, self-review, deep reasoning).
|
|
9
|
-
# Recommends `/effort max`. Also reminds about recommended model `claude-opus-4-6[1m]`.
|
|
4
|
+
# Behavior (#395 update):
|
|
5
|
+
# CLAUDE_CODE_EFFORT_LEVEL env var takes precedence over effortLevel in settings.
|
|
6
|
+
# CC docs: max is session-only in settings.json — only the env var persists it.
|
|
7
|
+
# Opus 4.6 supports: low, medium, high, max (NO xhigh — falls back to high).
|
|
10
8
|
#
|
|
11
|
-
#
|
|
12
|
-
#
|
|
9
|
+
# effort=max -> silent (only acceptable level)
|
|
10
|
+
# anything else -> LOUD WARNING
|
|
13
11
|
#
|
|
14
12
|
# Non-blocking: always exits 0.
|
|
15
13
|
|
|
16
|
-
RECOMMENDED_MODEL="claude-opus-4-6
|
|
14
|
+
RECOMMENDED_MODEL="claude-opus-4-6"
|
|
17
15
|
|
|
18
|
-
# Token-bloat fix: when both project + plugin register this hook, plugin yields.
|
|
19
16
|
HOOK_DIR="${BASH_SOURCE[0]%/*}"
|
|
20
17
|
[ "$HOOK_DIR" = "${BASH_SOURCE[0]}" ] && HOOK_DIR="."
|
|
21
18
|
# shellcheck disable=SC1091
|
|
22
19
|
source "$HOOK_DIR/_find-sdlc-root.sh"
|
|
23
20
|
dedupe_plugin_or_project "${BASH_SOURCE[0]}" || { cat > /dev/null; exit 0; }
|
|
24
21
|
|
|
25
|
-
# Drain stdin (SessionStart sends JSON but model field isn't in it)
|
|
26
22
|
cat > /dev/null
|
|
27
23
|
|
|
28
24
|
if ! command -v jq > /dev/null 2>&1; then
|
|
29
25
|
exit 0
|
|
30
26
|
fi
|
|
31
27
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
28
|
+
# Env var takes precedence (CC docs: only way to persist max)
|
|
29
|
+
effort="${CLAUDE_CODE_EFFORT_LEVEL:-}"
|
|
30
|
+
settings_max=0
|
|
31
|
+
|
|
32
|
+
if [ -z "$effort" ]; then
|
|
33
|
+
project_dir="${CLAUDE_PROJECT_DIR:-.}"
|
|
34
|
+
for f in "$project_dir/.claude/settings.local.json" "$project_dir/.claude/settings.json" "$HOME/.claude/settings.json"; do
|
|
35
|
+
if [ -f "$f" ]; then
|
|
36
|
+
val=$(jq -r '.effortLevel // empty' "$f" 2>/dev/null)
|
|
37
|
+
if [ -n "$val" ]; then
|
|
38
|
+
effort="$val"
|
|
39
|
+
[ "$val" = "max" ] && settings_max=1
|
|
40
|
+
break
|
|
41
|
+
fi
|
|
40
42
|
fi
|
|
41
|
-
|
|
42
|
-
|
|
43
|
+
done
|
|
44
|
+
fi
|
|
43
45
|
|
|
44
|
-
#
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
;;
|
|
49
|
-
esac
|
|
46
|
+
# Only env-var max is truly silent.
|
|
47
|
+
if [ "$effort" = "max" ] && [ "$settings_max" -eq 0 ]; then
|
|
48
|
+
exit 0
|
|
49
|
+
fi
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
51
|
+
if [ "$settings_max" -eq 1 ] && [ -z "${CLAUDE_CODE_EFFORT_LEVEL:-}" ]; then
|
|
52
|
+
effort_display="max (settings-only — CC ignores this)"
|
|
53
|
+
elif [ -z "$effort" ]; then
|
|
54
54
|
effort_display="unset"
|
|
55
55
|
else
|
|
56
56
|
effort_display="$effort"
|
|
57
57
|
fi
|
|
58
58
|
|
|
59
59
|
echo "=============================================================================="
|
|
60
|
-
echo " WARNING: effort '$effort_display'
|
|
61
|
-
echo " Below
|
|
60
|
+
echo " WARNING: effort '$effort_display' — SDLC requires max."
|
|
61
|
+
echo " Below max = degraded reasoning, shallow TDD, weak self-review."
|
|
62
62
|
echo ""
|
|
63
|
-
echo " Run: /effort max
|
|
64
|
-
echo "
|
|
63
|
+
echo " Run: /effort max"
|
|
64
|
+
echo " Persist: set CLAUDE_CODE_EFFORT_LEVEL=max in settings env block"
|
|
65
65
|
echo ""
|
|
66
66
|
echo " recommended model: $RECOMMENDED_MODEL (run: /model $RECOMMENDED_MODEL)"
|
|
67
67
|
echo "=============================================================================="
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-sdlc-wizard",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.81.0",
|
|
4
4
|
"description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
|
|
5
5
|
"bin": {
|
|
6
6
|
"sdlc-wizard": "cli/bin/sdlc-wizard.js"
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"hooks/",
|
|
12
12
|
".claude-plugin/",
|
|
13
13
|
"CLAUDE_CODE_SDLC_WIZARD.md",
|
|
14
|
+
"AI_SETUP_LANES.md",
|
|
14
15
|
"CHANGELOG.md"
|
|
15
16
|
],
|
|
16
17
|
"keywords": [
|
package/skills/sdlc/SKILL.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: sdlc
|
|
3
3
|
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.
|
|
4
4
|
argument-hint: [task description]
|
|
5
|
-
effort:
|
|
5
|
+
effort: max
|
|
6
6
|
---
|
|
7
7
|
# SDLC Skill - Full Development Workflow
|
|
8
8
|
|
|
@@ -47,7 +47,7 @@ TodoWrite([
|
|
|
47
47
|
{ content: "Visual consistency check (if UI change)", status: "pending" },
|
|
48
48
|
{ content: "Self-review: run /code-review", status: "pending" },
|
|
49
49
|
{ content: "Security review (if warranted)", status: "pending" },
|
|
50
|
-
{ content: "Cross-model review (
|
|
50
|
+
{ content: "Cross-model review (high-stakes)", status: "pending" },
|
|
51
51
|
{ content: "Scope guard: only changes related to task? No legacy/fallback code left?", status: "pending" },
|
|
52
52
|
// CI SHEPHERD
|
|
53
53
|
{ content: "Commit and push to remote", status: "pending" },
|
|
@@ -96,9 +96,9 @@ State your confidence before presenting an approach:
|
|
|
96
96
|
|
|
97
97
|
| Level | Meaning | Action | Effort |
|
|
98
98
|
|-------|---------|--------|--------|
|
|
99
|
-
| HIGH (90%+) | Know exactly what to do | Present, proceed after approval | `
|
|
100
|
-
| MEDIUM (60-89%) | Solid approach, some uncertainty | Present, highlight uncertainties | `
|
|
101
|
-
| LOW (<60%) | Not sure | Research or try Codex; if still LOW, ASK USER | **`/effort
|
|
99
|
+
| HIGH (90%+) | Know exactly what to do | Present, proceed after approval | `max` (default) |
|
|
100
|
+
| MEDIUM (60-89%) | Solid approach, some uncertainty | Present, highlight uncertainties | `max` (default) |
|
|
101
|
+
| LOW (<60%) | Not sure | Research or try Codex; if still LOW, ASK USER | **`/effort max` now** |
|
|
102
102
|
| FAILED 2x | Something's wrong | Codex for fresh perspective; if still stuck, STOP | **`/effort max` now** |
|
|
103
103
|
| CONFUSED | Can't diagnose | Codex; if still confused, STOP and describe | **`/effort max` now** |
|
|
104
104
|
|
|
@@ -114,9 +114,11 @@ Native `/goal <condition>` (**v2.1.143+**). Haiku evaluator re-checks transcript
|
|
|
114
114
|
|
|
115
115
|
## Recommended Model
|
|
116
116
|
|
|
117
|
-
**
|
|
117
|
+
**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.
|
|
118
118
|
|
|
119
|
-
**
|
|
119
|
+
**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.
|
|
120
|
+
|
|
121
|
+
**Advisor (v2.1.170+):** Flagship → `advisorModel: "fable"`. OpusPlan → `advisorModel: "claude-opus-4-6"`. Set during `/setup-wizard` Step 9.5.
|
|
120
122
|
|
|
121
123
|
## Self-Review Loop
|
|
122
124
|
|
|
@@ -128,9 +130,9 @@ PLANNING → DOCS → TDD RED → GREEN → Tests Pass → Self-Review
|
|
|
128
130
|
|
|
129
131
|
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.
|
|
130
132
|
|
|
131
|
-
## Cross-Model Review (
|
|
133
|
+
## Cross-Model Review (REQUIRED for High-Stakes)
|
|
132
134
|
|
|
133
|
-
**When to run:** high-stakes changes (auth, payments, data), releases/publishes, complex refactors. **When to skip:** trivial
|
|
135
|
+
**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.
|
|
134
136
|
|
|
135
137
|
PROTOCOL is universal across domains; only `review_instructions` and `verification_checklist` change.
|
|
136
138
|
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -228,9 +228,9 @@ Present suggestions and let the user confirm.
|
|
|
228
228
|
|
|
229
229
|
### Step 9.5: Context Window + Mixed-Mode Configuration (Opt-In)
|
|
230
230
|
|
|
231
|
-
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
|
|
231
|
+
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.
|
|
232
232
|
|
|
233
|
-
**Why this is opt-in (issue #198):** A top-level `"model"` in `settings.json`
|
|
233
|
+
**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.
|
|
234
234
|
|
|
235
235
|
**Run the complexity heuristic first (roadmap #233):**
|
|
236
236
|
|
|
@@ -246,50 +246,58 @@ The output is JSON: `{ tier: "simple" | "complex", score, signals }`. Use the re
|
|
|
246
246
|
>
|
|
247
247
|
> How do you want to configure the model for this repo?
|
|
248
248
|
>
|
|
249
|
-
> - **[N] No pin (default
|
|
250
|
-
> - **[
|
|
251
|
-
> - **[f] Flagship full** *(
|
|
252
|
-
> - **[l] Latest** *(opt-in
|
|
249
|
+
> - **[N] No pin (default):** Auto-mode. CC picks model per turn. Simplest.
|
|
250
|
+
> - **[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).
|
|
251
|
+
> - **[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).
|
|
252
|
+
> - **[l] Latest** *(opt-in bleeding-edge):* Pins `model: "claude-opus-4-8"`. Effort: always max (#395).
|
|
253
253
|
>
|
|
254
|
-
> `[N/
|
|
254
|
+
> `[N/o/f/l]`
|
|
255
255
|
|
|
256
256
|
**If the user answers `N` (default):** Make no edits to `.claude/settings.json`. Auto-mode stays on. Done.
|
|
257
257
|
|
|
258
|
-
**If the user answers `
|
|
258
|
+
**If the user answers `o` (opusplan):** Edit `.claude/settings.json` and add:
|
|
259
259
|
|
|
260
260
|
```json
|
|
261
261
|
{
|
|
262
|
-
"model": "
|
|
262
|
+
"model": "opusplan",
|
|
263
|
+
"advisorModel": "claude-opus-4-6",
|
|
264
|
+
"env": {
|
|
265
|
+
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
|
|
266
|
+
"CLAUDE_CODE_EFFORT_LEVEL": "max"
|
|
267
|
+
}
|
|
263
268
|
}
|
|
264
269
|
```
|
|
265
270
|
|
|
266
|
-
|
|
271
|
+
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."
|
|
267
272
|
|
|
268
|
-
**If the user answers `f` (flagship):** Edit `.claude/settings.json` and add
|
|
273
|
+
**If the user answers `f` (flagship):** Edit `.claude/settings.json` and add:
|
|
269
274
|
|
|
270
275
|
```json
|
|
271
276
|
{
|
|
272
|
-
"model": "claude-opus-4-6
|
|
277
|
+
"model": "claude-opus-4-6",
|
|
278
|
+
"advisorModel": "fable",
|
|
273
279
|
"env": {
|
|
280
|
+
"CLAUDE_CODE_EFFORT_LEVEL": "max",
|
|
274
281
|
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30"
|
|
275
282
|
}
|
|
276
283
|
}
|
|
277
284
|
```
|
|
278
285
|
|
|
279
|
-
Tell the user: "
|
|
286
|
+
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."
|
|
280
287
|
|
|
281
288
|
**If the user answers `l` (latest):** Edit `.claude/settings.json` and add:
|
|
282
289
|
|
|
283
290
|
```json
|
|
284
291
|
{
|
|
285
|
-
"model": "claude-opus-4-8
|
|
292
|
+
"model": "claude-opus-4-8",
|
|
293
|
+
"advisorModel": "fable",
|
|
286
294
|
"env": {
|
|
287
|
-
"
|
|
295
|
+
"CLAUDE_CODE_EFFORT_LEVEL": "max"
|
|
288
296
|
}
|
|
289
297
|
}
|
|
290
298
|
```
|
|
291
299
|
|
|
292
|
-
Tell the user: "
|
|
300
|
+
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."
|
|
293
301
|
|
|
294
302
|
Mention the escape hatch in all four cases:
|
|
295
303
|
- 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:
|
|
|
298
306
|
|
|
299
307
|
This is project-scoped and shared with the team via git.
|
|
300
308
|
|
|
309
|
+
**After writing project settings (for `[o]`, `[f]`, or `[l]`), ask once:**
|
|
310
|
+
|
|
311
|
+
> Also set `advisorModel` in your global `~/.claude/settings.json`?
|
|
312
|
+
> (Applies advisor to ALL your projects. Project-level always overrides.)
|
|
313
|
+
> `[y/N]`
|
|
314
|
+
|
|
315
|
+
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.
|
|
316
|
+
|
|
317
|
+
**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.
|
|
318
|
+
|
|
301
319
|
### Step 10: Customize Hooks
|
|
302
320
|
|
|
303
321
|
Update `tdd-pretool-check.sh` with the actual source directory (replace generic `/src/` pattern).
|
package/skills/update/SKILL.md
CHANGED
|
@@ -93,9 +93,10 @@ Parse CHANGELOG entries between the user's installed version and latest. Present
|
|
|
93
93
|
|
|
94
94
|
```
|
|
95
95
|
Installed: 1.42.0
|
|
96
|
-
Latest: 1.
|
|
96
|
+
Latest: 1.81.0
|
|
97
97
|
|
|
98
98
|
What changed:
|
|
99
|
+
- [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+.
|
|
99
100
|
- [1.80.0] Flip default: Opus 4.6 max becomes recommended flagship; Opus 4.8 demoted to opt-in `[l] Latest` tier.
|
|
100
101
|
- [1.79.0] Opus 4.6 Stability tier added as flagship alternative (now graduated to default in 1.80.0).
|
|
101
102
|
- [1.78.0] Opus 4.7 → 4.8 model recommendation (#365) + min CC v2.1.154+.
|
|
@@ -176,8 +177,8 @@ Check user's `.claude/settings.json`:
|
|
|
176
177
|
> Remove, keep, or decide later? `[r/k/l]`
|
|
177
178
|
|
|
178
179
|
2. **Only one of the two fields matches** — treat as intentional customization. Do not prompt.
|
|
179
|
-
3. **`model: "sonnet[1m]"`**
|
|
180
|
-
4.
|
|
180
|
+
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)."
|
|
181
|
+
4. **`model: "opusplan"`** or other value (`sonnet`, `opus`) — explicit user choice. Do not touch.
|
|
181
182
|
5. **Neither field set** — already on new default.
|
|
182
183
|
|
|
183
184
|
When removing: drop `model` (and `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` if `env` becomes empty). Never touch other keys.
|
|
@@ -224,35 +225,15 @@ If `cli/init.js` later adds wizard marketplace names, append verbatim.
|
|
|
224
225
|
3. For every dead marketplace `<name>`, look for `enabledPlugins["sdlc-wizard@<name>"]` — also flag for removal.
|
|
225
226
|
4. Repeat for **all** allowlist entries; collect the full set of dead pairs before prompting (multiple are common).
|
|
226
227
|
|
|
227
|
-
**Cleanup
|
|
228
|
+
**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.
|
|
228
229
|
|
|
229
|
-
|
|
230
|
-
>
|
|
231
|
-
> - `extraKnownMarketplaces.sdlc-wizard-local.source.path` → `<resolved-path>` (missing)
|
|
232
|
-
> - `enabledPlugins["sdlc-wizard@sdlc-wizard-local"]` is `true`
|
|
233
|
-
> - (list all dead pairs)
|
|
234
|
-
>
|
|
235
|
-
> Causes `Plugin directory does not exist` on every prompt in every CC session.
|
|
236
|
-
>
|
|
237
|
-
> Drop these entries from `~/.claude/settings.json`? `[y/N]`
|
|
238
|
-
|
|
239
|
-
If yes:
|
|
240
|
-
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).
|
|
241
|
-
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.
|
|
242
|
-
3. Write to a temp file, validate with `jq empty` (round-trip parse), then `mv`. Validation fails → restore from backup.
|
|
243
|
-
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.
|
|
244
|
-
|
|
245
|
-
If no: skip silently. Some users have a recovery plan (re-enable, reinstall).
|
|
246
|
-
|
|
247
|
-
**Idempotency:** rerunning Step 7.7 after a clean must be a no-op. Only marketplaces with allowlist match AND missing path qualify.
|
|
248
|
-
|
|
249
|
-
**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.
|
|
230
|
+
**Guards:** Idempotent (no-op after clean). Scope: only allowlist matches. Runs regardless of version match. `check-only`: detect only, no mutations.
|
|
250
231
|
|
|
251
|
-
|
|
232
|
+
### Step 7.8: advisorModel Migration (v2.1.170+)
|
|
252
233
|
|
|
253
|
-
|
|
234
|
+
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.
|
|
254
235
|
|
|
255
|
-
|
|
236
|
+
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.
|
|
256
237
|
|
|
257
238
|
### Step 8: Apply Selected Changes
|
|
258
239
|
|