agentic-sdlc-wizard 1.46.1 → 1.48.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/CHANGELOG.md +40 -0
- package/CLAUDE_CODE_SDLC_WIZARD.md +2 -2
- package/README.md +1 -1
- package/package.json +1 -1
- package/skills/sdlc/SKILL.md +173 -646
- package/skills/update/SKILL.md +119 -210
package/skills/update/SKILL.md
CHANGED
|
@@ -11,350 +11,259 @@ $ARGUMENTS
|
|
|
11
11
|
|
|
12
12
|
## Purpose
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Guided update assistant. Check what version the user has, show what changed, walk them through selectively adopting updates while preserving their customizations. **DO NOT blindly overwrite files.** Show diffs and let the user decide.
|
|
15
15
|
|
|
16
16
|
## MANDATORY FIRST ACTION: Read the Wizard Doc
|
|
17
17
|
|
|
18
|
-
**Before doing ANYTHING else**, use
|
|
18
|
+
**Before doing ANYTHING else**, use Read on `CLAUDE_CODE_SDLC_WIZARD.md` — specifically the "Staying Updated (Idempotent Wizard)" section near the end. This contains update URLs, version tracking format, and step registry. Do NOT proceed without reading it first.
|
|
19
19
|
|
|
20
20
|
## Execution Checklist
|
|
21
21
|
|
|
22
|
-
Follow
|
|
22
|
+
Follow steps IN ORDER. Do not skip or combine.
|
|
23
23
|
|
|
24
24
|
### Step 1: Read Installed Version
|
|
25
25
|
|
|
26
|
-
Read `SDLC.md` and extract
|
|
26
|
+
Read `SDLC.md` and extract from the metadata comment:
|
|
27
27
|
```
|
|
28
28
|
<!-- SDLC Wizard Version: X.X.X -->
|
|
29
|
+
<!-- Completed Steps: ... -->
|
|
29
30
|
```
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
Also note the completed steps from `<!-- Completed Steps: ... -->`.
|
|
31
|
+
No version comment → treat as `0.0.0` (suggest `/setup-wizard` instead).
|
|
33
32
|
|
|
34
33
|
### Step 1.5: Check CLI Version (ROADMAP #232)
|
|
35
34
|
|
|
36
|
-
The wizard files in the user's project
|
|
37
|
-
|
|
38
|
-
**Detection — try both paths, in order:**
|
|
35
|
+
The wizard files in the user's project are one half of the install. The other half is the **npm CLI** (`agentic-sdlc-wizard`) — the binary powering `npx agentic-sdlc-wizard init`/`check`/`complexity`. If the user ran `init` months ago, their npx cache (or global install) can be stuck on an old version even after `/update-wizard` patches the project files in-session. This step closes that gap.
|
|
39
36
|
|
|
40
|
-
|
|
37
|
+
**Detection — try both paths:**
|
|
41
38
|
|
|
42
|
-
|
|
39
|
+
1. **Global install** (rare): `npm ls -g agentic-sdlc-wizard --json --depth=0 2>/dev/null | jq -r '.dependencies["agentic-sdlc-wizard"].version // empty'`
|
|
43
40
|
|
|
44
|
-
|
|
45
|
-
find ~/.npm/_npx -maxdepth 4 -name 'package.json' -path '*agentic-sdlc-wizard*' 2>/dev/null \
|
|
46
|
-
| xargs -I{} jq -r '.version' {} 2>/dev/null \
|
|
47
|
-
| node -e "
|
|
48
|
-
let max = '';
|
|
49
|
-
require('readline').createInterface({input: process.stdin}).on('line', v => {
|
|
50
|
-
if (!v) return;
|
|
51
|
-
if (!max || cmp(v, max) > 0) max = v;
|
|
52
|
-
}).on('close', () => process.stdout.write(max));
|
|
53
|
-
function cmp(a, b) {
|
|
54
|
-
const [ab, ap] = a.split('-'), [bb, bp] = b.split('-');
|
|
55
|
-
const an = ab.split('.').map(Number), bn = bb.split('.').map(Number);
|
|
56
|
-
for (let i = 0; i < 3; i++) if (an[i] !== bn[i]) return an[i] - bn[i];
|
|
57
|
-
if (ap && !bp) return -1; if (!ap && bp) return 1;
|
|
58
|
-
if (ap && bp) return ap < bp ? -1 : ap > bp ? 1 : 0;
|
|
59
|
-
return 0;
|
|
60
|
-
}
|
|
61
|
-
"
|
|
62
|
-
```
|
|
41
|
+
2. **npx cache** (common): find every `package.json` under `~/.npm/_npx` matching `*agentic-sdlc-wizard*`, extract `.version`, pick the largest **by semver** (do NOT use `sort -u | tail -1` — lexicographic treats `1.9.0 > 1.10.0`). Use a Node `cmp()` helper: split on `-` for prerelease tag, compare numeric `major.minor.patch`, then prerelease ordering (`1.40.0-beta.1 < 1.40.0`). Read each version on its own line via stdin, track max, print at close. Empty input → empty output.
|
|
63
42
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
If both paths return empty, the user may be running from a custom install or has never used `npx`. Treat as **undetectable** — note it in your update report but do not block the rest of the flow. Skip the CLI bump prompt, continue to Step 2.
|
|
43
|
+
If both paths return empty, the user may be running from a custom install or never used `npx`. Treat as **undetectable** — note in the report but do not block. Skip the CLI bump prompt; continue to Step 2.
|
|
67
44
|
|
|
68
45
|
**Registry comparison:**
|
|
69
|
-
|
|
70
46
|
```bash
|
|
71
47
|
curl -fsS "https://registry.npmjs.org/agentic-sdlc-wizard/latest" | jq -r '.version'
|
|
72
48
|
```
|
|
49
|
+
Cache the result (also used in Step 3).
|
|
73
50
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
**Compare with semver-aware logic** — `sort -V` does NOT correctly order prereleases (it places `1.40.0-beta.1` *after* `1.40.0`, but semver requires the opposite). Use the same Node `cmp()` helper from the npx-cache step:
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
node -e "
|
|
80
|
-
const a = process.argv[1], b = process.argv[2];
|
|
81
|
-
function cmp(a, b) { /* same body as above */ }
|
|
82
|
-
process.exit(cmp(a, b) < 0 ? 0 : cmp(a, b) > 0 ? 1 : 2);
|
|
83
|
-
" "$INSTALLED" "$LATEST"
|
|
84
|
-
# Exit 0 = installed < latest (behind); 1 = installed > latest; 2 = equal
|
|
85
|
-
```
|
|
51
|
+
**Compare with semver-aware logic** — `sort -V` does NOT correctly order prereleases. Reuse the Node `cmp()` helper to produce exit `0` (installed < latest), `1` (installed > latest), `2` (equal).
|
|
86
52
|
|
|
87
|
-
**Surface
|
|
53
|
+
**Surface the result:**
|
|
54
|
+
- `installed == latest` → silent, continue.
|
|
55
|
+
- `installed < latest` → show the gap with the upgrade options below.
|
|
56
|
+
- `installed > latest` (rare — pre-release/local dev) → silent, continue.
|
|
88
57
|
|
|
89
|
-
|
|
90
|
-
- `installed < latest` → surface the gap with the upgrade options below.
|
|
91
|
-
- `installed > latest` (rare — pre-release or local dev install) → silent, continue.
|
|
58
|
+
**Upgrade options when behind:**
|
|
92
59
|
|
|
93
|
-
**
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
>
|
|
109
|
-
> **C. Skip the CLI bump entirely.** Keep the stale CLI; this session's file updates apply but `npx agentic-sdlc-wizard check` will keep using the old drift logic.
|
|
110
|
-
>
|
|
111
|
-
> Pick A, B, or C: `[A/B/C]`
|
|
60
|
+
> Your `agentic-sdlc-wizard` CLI is at **{installed}**, npm has **{latest}**. The in-session `/update-wizard` will refresh project files via Step 6, but your `npx` cache will keep the old CLI on disk for `npx agentic-sdlc-wizard check`/`init`/`complexity`.
|
|
61
|
+
>
|
|
62
|
+
> **A. Refresh just the CLI cache (recommended).** No project changes; Step 6 handles the rest with diffs:
|
|
63
|
+
> ```bash
|
|
64
|
+
> npx -y agentic-sdlc-wizard@latest --version
|
|
65
|
+
> ```
|
|
66
|
+
>
|
|
67
|
+
> **B. One-shot CLI + project re-init.** Refreshes CLI AND overwrites *non-settings* managed files (skills, hooks, templates) with latest. `settings.json` is smart-merged (custom hooks + permissions preserved); other managed files are NOT smart-merged — local edits are lost unless committed. Use only if no local skill/hook customizations:
|
|
68
|
+
> ```bash
|
|
69
|
+
> npx -y agentic-sdlc-wizard@latest init --force
|
|
70
|
+
> ```
|
|
71
|
+
>
|
|
72
|
+
> **C. Skip the CLI bump.** Keep stale CLI; this session's file updates apply but `npx ... check` keeps using old drift logic.
|
|
73
|
+
>
|
|
74
|
+
> Pick A, B, or C: `[A/B/C]` (default A)
|
|
112
75
|
|
|
113
|
-
|
|
76
|
+
If A: prompt the user to run the one-liner, then re-invoke `/update-wizard`. If B: same with the warning. If C: log the choice and continue.
|
|
114
77
|
|
|
115
|
-
**`check-only` precedence:** if the user passed `check-only`, Step 1.5 runs in report-only mode — print the gap if found, but do NOT prompt and do NOT run `init --force`. The check-only contract is "tell me what's drifted, don't change anything," and that supersedes the CLI bump path.
|
|
78
|
+
**`check-only` precedence:** if the user passed `check-only`, Step 1.5 runs in report-only mode — print the gap if found, but do NOT prompt and do NOT run `init --force`. The check-only contract is "tell me what's drifted, don't change anything," and that supersedes the CLI bump path. **Graceful fallback** when CLI undetectable: skip the bump prompt, surface the unknown-state in the report, continue to Step 2.
|
|
116
79
|
|
|
117
|
-
**Why
|
|
80
|
+
**Why Step 1.5, not later:** subsequent steps shell out to `npx agentic-sdlc-wizard check` (Step 4). If the CLI is stale, Step 4 reports based on the OLD definition of managed files and may miss new templates entirely.
|
|
118
81
|
|
|
119
82
|
### Step 2: Fetch Latest CHANGELOG
|
|
120
83
|
|
|
121
|
-
|
|
84
|
+
WebFetch:
|
|
122
85
|
```
|
|
123
86
|
https://raw.githubusercontent.com/BaseInfinity/claude-sdlc-wizard/main/CHANGELOG.md
|
|
124
87
|
```
|
|
125
|
-
|
|
126
|
-
Extract the latest version from the first `## [X.X.X]` line.
|
|
88
|
+
Extract latest version from the first `## [X.X.X]` line.
|
|
127
89
|
|
|
128
90
|
### Step 3: Compare Versions and Show What Changed
|
|
129
91
|
|
|
130
|
-
Parse
|
|
92
|
+
Parse CHANGELOG entries between the user's installed version and latest. Present a clear summary:
|
|
131
93
|
|
|
132
94
|
```
|
|
133
|
-
Installed: 1.
|
|
134
|
-
Latest: 1.
|
|
95
|
+
Installed: 1.42.0
|
|
96
|
+
Latest: 1.48.0
|
|
135
97
|
|
|
136
98
|
What changed:
|
|
137
|
-
- [1.
|
|
138
|
-
- [1.
|
|
139
|
-
- [1.
|
|
140
|
-
- [1.
|
|
141
|
-
- [1.
|
|
142
|
-
- [1.
|
|
143
|
-
|
|
144
|
-
- [1.42.1] CI hygiene fix — skip Claude PR review on wizard self-PRs. 7 self-PRs (v1.39.0–v1.42.0) had shipped with red `review` job (API canary firing on dead credit balance). Treated as "expected" but red normalizes red. Workflow `if:` now skips review on `BaseInfinity/claude-sdlc-wizard` repo only; consumer projects unaffected. 7 quality tests, mutation-verified (== inversion fails).
|
|
145
|
-
- [1.42.0] AGENTS.md interop detection — ROADMAP #205 phase (a). Setup wizard auto-scan now lists AGENTS.md (cross-tool agent-instructions standard, CC issue #6235); new Step 4.5 surfaces a 3-way decision (dual-maintain / merge / skip) when AGENTS.md is detected. Phase (b) write-fresh and phase (d) drift-test deferred. 7 quality tests.
|
|
146
|
-
- [1.41.1] MCP-tool hooks audit — ROADMAP #218. Audited all 5 wizard hooks against CC 2.1.118's `type: "mcp_tool"` migration option; conclusion: all stay bash (portability to Codex/OpenCode siblings + exit-code gating semantics rule out MCP). Per-hook rationale documented under "Known CC Gotchas → MCP-tool hooks audit". 7 quality tests.
|
|
147
|
-
- [1.41.0] Post-mortem 2026-04-23 lessons folded into wizard — ROADMAP #221. New "Known CC Gotchas" section documents extended-thinking + caching + idle-session failure mode. Recommended Effort section cites the post-mortem as third-party evidence ("don't rely on CC default — set effort yourself"). Brevity-cap audit clean, regression guard added. 7 quality tests.
|
|
148
|
-
- [1.40.1] cleanupPeriodDays: 30 pinned in template — ROADMAP #225. CC 2.1.117 expanded `cleanupPeriodDays` to also cover `~/.claude/tasks/`. Aggressive defaults could prune in-progress TodoWrite checklists for paused long-running features. Wizard now ships a 30-day floor + documented gotcha. 7 quality tests.
|
|
149
|
-
- [1.40.0] CLI version detection in /update-wizard — ROADMAP #232. New Step 1.5 detects locally installed `agentic-sdlc-wizard` CLI version (npm ls + npx cache inspection, both with semver-aware ordering), compares to `registry.npmjs.org/agentic-sdlc-wizard/latest`, and surfaces a 3-way upgrade choice BEFORE drift detection: A) refresh CLI cache only (default, safest), B) `init --force` re-init with explicit non-settings overwrite warning, C) skip. Closes the gap where in-session file updates landed but the user's stale npx cache kept running an old CLI. Mirrors `claude update` UX. 8 quality tests, mutation-verified.
|
|
150
|
-
- [1.39.1] Step 7.7 hoist — dead-plugin cleanup now runs even when wizard versions match. Previously `/update-wizard` exited at "you're up to date" before reaching Step 7.7, so users on the latest wizard with a stale `~/.claude/settings.json` plugin registration were never offered cleanup. New `tests/test-update-skill-step-7-7.sh` (8 quality tests) guards the ordering.
|
|
151
|
-
- [1.39.0] Community feature-discovery scanner — ROADMAP #207. `tests/e2e/scan-community.sh` extracts unknown `/slash-command` mentions from transcript text (Reddit / HN / Discord exports), dedupes against `tests/e2e/known-slash-commands.txt` allowlist, emits JSON digest of candidates with count + sample. Replaces the deleted CI scan-community job (per #231 Phase 3) with a maintainer-runnable offline scan. 14 quality tests.
|
|
152
|
-
- [1.38.0] Mixed-mode tier (Sonnet 4.6 coder + Opus 4.7 reviewer) for simple repos — ROADMAP #233. New `cli/lib/repo-complexity.js` heuristic + `npx agentic-sdlc-wizard complexity .` CLI command. Setup Step 9.5 expanded from binary y/N to 3-way (no-pin / mixed / flagship). Cross-model review always stays at flagship regardless of coder pin. Reconciles with #198: mixed-mode is opt-in per-project; no-pin remains the default. Plus ROADMAP #224 prompt-hook-fires-once instrumentation (opt-in `SDLC_HOOK_FIRE_LOG`).
|
|
153
|
-
- [1.37.1] Token-bloat fix: dedupe 2× SDLC BASELINE print when both project + plugin register the same hook (~300 tokens doubled per prompt). 5 hooks gain `dedupe_plugin_or_project()` helper. Codex 2-round 100/100.
|
|
154
|
-
- [1.37.0] `monthly-research.yml` workflow deleted (ROADMAP #231 Phase 1) — 0 merged artifacts in 30d while burning $11-23/month; research happens inline now. `model-effort-check.sh` loud WARNING below xhigh (#217) — max preferred, xhigh floor; duplicate effort nudge in `instructions-loaded-check.sh` removed; single source of truth. Both changes Codex-certified.
|
|
155
|
-
- [1.36.1] Repo renamed `agentic-ai-sdlc-wizard` → `claude-sdlc-wizard` (matches sibling pattern; npm package unchanged); `npm pkg fix` metadata cleanup; slug migration across docs/tests/configs
|
|
156
|
-
- [1.36.0] CC 2.1.118 `/usage` canonical + aliases, Tier 2 dead-gate fix (#215), score-history max_score correctness (#211), setup-bun regression guard (#210), post-mortem learnings (#220-222), GPT-5.5 adoption plan (#223), MCP-tool hooks + #198 re-verify in backlog (#218/#219)
|
|
157
|
-
- [1.35.0] PreCompact seam gate + self-heal (#208/#209), effort auto-bump on LOW/FAILED/CONFUSED (#195), wizard staleness nudge (#196), Codex CI-log audit pattern, ...
|
|
158
|
-
- [1.34.0] API feature detection shepherd for Claude releases, Memory Audit Protocol with 7 verified lessons (+2 caught-and-retracted), /less-permission-prompts surfaced, ...
|
|
159
|
-
- [1.33.0] opus[1m] as SDLC default, dual-channel install drift guardrails, model/effort session-start nudge, ...
|
|
160
|
-
- [1.32.0] Opus 4.7 + xhigh support, model/effort upgrade detection, benchmark ceiling audit, ...
|
|
161
|
-
- [1.31.0] Hook false-positive fix for non-SDLC dirs, ephemeral marketplace path warning, ...
|
|
162
|
-
- [1.30.0] Firmware fixture, model A/B comparison workflow, CC degradation detection, ...
|
|
163
|
-
- [1.29.0] Node 24 compliance, autocompact in settings.json, effectiveness scoreboard, ...
|
|
164
|
-
- [1.28.0] Autocompact benchmarking methodology, canary fact mechanism, benchmark harness, ...
|
|
165
|
-
- [1.27.0] Domain-adaptive testing diamond, 3 domain fixtures, 25 quality tests, ...
|
|
166
|
-
- [1.26.0] Codex SDLC Adapter plan, claw-code/OmO/OmX research, CC feature discovery verified, ...
|
|
167
|
-
- [1.25.0] Plugin format, 6 distribution channels (curl, Homebrew, gh, GitHub Releases), ...
|
|
168
|
-
- [1.24.0] Hook if conditionals, autocompact tuning + 1M/200K guidance, tdd_red fix, ...
|
|
99
|
+
- [1.48.0] SKILL.md trim — token bloat audit phase 2 follow-up
|
|
100
|
+
- [1.47.0] Codex review progress wrapper (#259)
|
|
101
|
+
- [1.46.1] npx check surfaces dangling+enabled plugin state (#266)
|
|
102
|
+
- [1.46.0] PreCompact dry-run env vars (#240)
|
|
103
|
+
- [1.45.0] PreCompact path (c) — SHA-ancestry self-heal (#257)
|
|
104
|
+
- [1.44.1] Autocompact compound-misconfig detection (#207)
|
|
105
|
+
... (full entries from fetched CHANGELOG)
|
|
169
106
|
```
|
|
170
107
|
|
|
171
|
-
|
|
108
|
+
Read the actual entries from the fetched CHANGELOG; don't paraphrase. The user wants to see exactly what shipped.
|
|
109
|
+
|
|
110
|
+
**If versions match:** Step 7.7 (global plugin-registration cleanup) is independent of wizard file versions — it must run even when the user is up-to-date. The `check-only` flag still gates whether cleanup is *applied*:
|
|
172
111
|
|
|
173
112
|
- **Without `check-only`**: Run Step 7.7 in normal mode (detect, prompt, apply) before stopping. Then say "You're up to date! (version X.X.X)" and stop. Do not run Steps 4–10; only Step 7.7 fires on match.
|
|
174
|
-
- **With `check-only`**: Run Step 7.7 in detection-only mode — report any dead plugin registrations
|
|
113
|
+
- **With `check-only`**: Run Step 7.7 in detection-only mode — report any dead plugin registrations, but do NOT prompt and do NOT mutate `~/.claude/settings.json`. Then say "You're up to date! (version X.X.X)" and stop.
|
|
175
114
|
|
|
176
|
-
**If user passed `check-only` and versions don't match:** Stop after showing what changed. Do not apply anything
|
|
115
|
+
**If user passed `check-only` and versions don't match:** Stop after showing what changed. Do not apply anything.
|
|
177
116
|
|
|
178
117
|
### Step 4: Run Drift Detection
|
|
179
118
|
|
|
180
|
-
Run the CLI drift checker to see per-file status:
|
|
181
119
|
```bash
|
|
182
120
|
npx agentic-sdlc-wizard check
|
|
183
121
|
```
|
|
184
|
-
|
|
185
|
-
This reports each managed file as MATCH, CUSTOMIZED, MISSING, or DRIFT. Present the results.
|
|
122
|
+
Reports each managed file as MATCH, CUSTOMIZED, MISSING, or DRIFT.
|
|
186
123
|
|
|
187
124
|
### Step 5: Fetch Latest Wizard Doc
|
|
188
125
|
|
|
189
|
-
|
|
126
|
+
WebFetch:
|
|
190
127
|
```
|
|
191
128
|
https://raw.githubusercontent.com/BaseInfinity/claude-sdlc-wizard/main/CLAUDE_CODE_SDLC_WIZARD.md
|
|
192
129
|
```
|
|
130
|
+
Source of truth for all templates, hooks, skills, step registry.
|
|
193
131
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
### Step 6: Present Per-File Update Plan
|
|
197
|
-
|
|
198
|
-
For each managed file from the `sdlc-wizard check` output:
|
|
132
|
+
### Step 6: Per-File Update Plan
|
|
199
133
|
|
|
200
134
|
| Status | Action |
|
|
201
135
|
|--------|--------|
|
|
202
136
|
| MATCH | Skip — already current |
|
|
203
|
-
| MISSING | Recommend install —
|
|
137
|
+
| MISSING | Recommend install — explain what the file does |
|
|
204
138
|
| CUSTOMIZED | Show what changed in latest vs user's version. Ask: adopt, skip, or merge? |
|
|
205
139
|
| DRIFT | Flag the issue (e.g., missing executable permission). Offer to fix |
|
|
206
140
|
|
|
207
|
-
Read both the installed file and the latest template
|
|
208
|
-
|
|
209
|
-
**If user passed `force-all`:** Skip per-file approval and apply all updates.
|
|
141
|
+
Read both the installed file and the latest template. Present a human-readable summary of differences — what was added/changed/removed and why, NOT a raw diff.
|
|
210
142
|
|
|
211
|
-
|
|
143
|
+
**If user passed `force-all`:** skip per-file approval, apply all updates.
|
|
212
144
|
|
|
213
|
-
|
|
145
|
+
### Step 7: settings.json (Smart Merge Only)
|
|
214
146
|
|
|
215
|
-
|
|
216
|
-
2. Compare against the latest template's hook definitions
|
|
217
|
-
3. Describe what hooks changed (added, updated, removed)
|
|
218
|
-
4. Offer to merge: update wizard hooks while preserving all custom hooks, permissions, and other settings
|
|
147
|
+
NEVER overwrite. Read user's current settings.json, compare to latest template's hook definitions, describe what changed (added/updated/removed), offer to merge: update wizard hooks while preserving all custom hooks, permissions, and other settings.
|
|
219
148
|
|
|
220
|
-
|
|
149
|
+
CLI's `init --force` already has smart-merge logic. If manual merge gets complicated, suggest: `npx agentic-sdlc-wizard init --force` (preserves custom hooks).
|
|
221
150
|
|
|
222
151
|
### Step 7.5: Model Pin Migration (Issue #198)
|
|
223
152
|
|
|
224
|
-
Wizard
|
|
153
|
+
Wizard 1.31.0–1.33.x unconditionally wrote `"model": "opus[1m]"` and `"env": { "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30" }` to `.claude/settings.json`. Issue #198 flipped that to opt-in because a top-level `model` disables Claude Code's auto-mode.
|
|
225
154
|
|
|
226
|
-
|
|
155
|
+
Check user's `.claude/settings.json`:
|
|
227
156
|
|
|
228
|
-
1.
|
|
229
|
-
|
|
230
|
-
>
|
|
231
|
-
>
|
|
232
|
-
>
|
|
233
|
-
> - **Remove the pin** (recommended for most users) — keeps auto-mode enabled, lets Claude Code pick the model per turn.
|
|
234
|
-
> - **Keep the pin** — you want guaranteed Opus 4.7 + 1M context, and you're OK giving up model auto-selection.
|
|
235
|
-
>
|
|
157
|
+
1. **`model: "opus[1m]"` AND `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "30"`** — likely the old wizard-installed pair, not an intentional choice. Ask:
|
|
158
|
+
> Your `.claude/settings.json` pins `model: "opus[1m]"` with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30`. This pair was the wizard default in 1.31.0–1.33.x, but it disables Claude Code's auto-mode (issue #198).
|
|
159
|
+
> - **Remove the pin** (recommended) — keeps auto-mode enabled
|
|
160
|
+
> - **Keep the pin** — guaranteed Opus 4.7 + 1M, OK with no auto-selection
|
|
236
161
|
> Remove, keep, or decide later? `[r/k/l]`
|
|
237
162
|
|
|
238
|
-
2. **
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
4. **If `model` is some other value** (e.g. `"sonnet"`, `"opus"`) — treat as user's explicit choice. Do not touch.
|
|
163
|
+
2. **Only one of the two fields matches** — treat as intentional customization. Do not prompt.
|
|
164
|
+
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."
|
|
165
|
+
4. **Other `model` value** (`sonnet`, `opus`) — explicit user choice. Do not touch.
|
|
166
|
+
5. **Neither field set** — already on new default.
|
|
243
167
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
When removing: edit the file in place, drop the `model` key (and the `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` key if nothing else is in `env`, otherwise leave `env` alone). Never touch other keys the user added.
|
|
168
|
+
When removing: drop `model` (and `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` if `env` becomes empty). Never touch other keys.
|
|
247
169
|
|
|
248
170
|
### Step 7.6: `allowedTools` → `permissions.allow` Migration (Issue #197)
|
|
249
171
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
If the user's `.claude/settings.json` has a top-level `allowedTools` array, offer to migrate:
|
|
172
|
+
Pre-#197 wizard guided users to write a top-level `allowedTools` array. Claude Code silently disables auto-mode when that key is present, even with `defaultMode: "auto"`.
|
|
253
173
|
|
|
254
|
-
|
|
174
|
+
If user's `.claude/settings.json` has top-level `allowedTools`, offer migrate:
|
|
255
175
|
|
|
256
|
-
|
|
257
|
-
>
|
|
258
|
-
> - **Migrate** (recommended): move all entries into `permissions.allow`, remove the
|
|
259
|
-
> - **Keep** —
|
|
260
|
-
> - **Later** — don't touch
|
|
261
|
-
>
|
|
176
|
+
1. **Only `allowedTools`** (no `permissions.allow`) — ask:
|
|
177
|
+
> Your `.claude/settings.json` has top-level `allowedTools` (silently disables auto-mode, issue #197). Successor: `permissions.allow`.
|
|
178
|
+
> - **Migrate** (recommended): move all entries into `permissions.allow`, remove the legacy key
|
|
179
|
+
> - **Keep** — specific reason for legacy key
|
|
180
|
+
> - **Later** — don't touch now
|
|
262
181
|
> `[m/k/l]`
|
|
263
182
|
|
|
264
|
-
2. **
|
|
183
|
+
2. **Both `allowedTools` AND `permissions.allow` present** — flag: lists may have diverged. Show both arrays. On migrate, **append every entry from `allowedTools` to the end of `permissions.allow`** byte-for-byte (preserve order within each list), then drop `allowedTools`. **Do NOT dedup.** Same string in both lists stays in both — CC treats duplicates as no-op, but dedup would silently remove user data the user might have intended. If user explicitly asks to dedup, that's a separate follow-up edit.
|
|
265
184
|
|
|
266
|
-
3. **
|
|
185
|
+
3. **Only `permissions.allow`** — already on new shape.
|
|
186
|
+
4. **Neither** — no action.
|
|
267
187
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
When migrating: preserve every entry byte-for-byte; only the container key changes. Do not reorder, dedup, or expand wildcards. Other top-level keys (hooks, env, model, custom user fields) are never touched.
|
|
188
|
+
Preserve every entry byte-for-byte; only the container key changes. Do not reorder, dedup, or expand wildcards. Other top-level keys never touched.
|
|
271
189
|
|
|
272
190
|
### Step 7.7: Dead Plugin Registration Cleanup (Global Settings)
|
|
273
191
|
|
|
274
|
-
Wizard installs sometimes leave dead plugin registrations in
|
|
192
|
+
Wizard installs sometimes leave dead plugin registrations in **global** `~/.claude/settings.json` after the underlying plugin directory is renamed/disabled/removed. Symptom: every CC session emits `UserPromptSubmit hook error: Failed to run: Plugin directory does not exist: <path> ... run /plugin to reinstall`. Harmless but bleeds into every prompt across every project until cleaned up.
|
|
275
193
|
|
|
276
|
-
This step is **global-settings-only** (`~/.claude/settings.json`, not
|
|
194
|
+
This step is **global-settings-only** (`~/.claude/settings.json`, not project's). Update normally avoids global; this is the one exception, only when the marketplace name matches an exact wizard-owned identifier.
|
|
277
195
|
|
|
278
|
-
**Wizard-owned marketplace allowlist** (exact match
|
|
196
|
+
**Wizard-owned marketplace allowlist** (exact match — wildcards risk eating third-party `sdlc-wizard-tools` if such a thing ships):
|
|
279
197
|
|
|
280
198
|
- `sdlc-wizard-local`
|
|
281
199
|
- `sdlc-wizard-wrap`
|
|
282
200
|
|
|
283
|
-
If `cli/init.js` later
|
|
201
|
+
If `cli/init.js` later adds wizard marketplace names, append verbatim.
|
|
284
202
|
|
|
285
203
|
**Detection:**
|
|
286
204
|
|
|
287
|
-
1. Read `~/.claude/settings.json
|
|
288
|
-
2. For each `extraKnownMarketplaces[key]` where `key` is in the allowlist
|
|
289
|
-
- Verify `entry.source.source === "directory"` AND `typeof entry.source.path === "string"`.
|
|
290
|
-
- Resolve
|
|
205
|
+
1. Read `~/.claude/settings.json`, parse as JSON.
|
|
206
|
+
2. For each `extraKnownMarketplaces[key]` where `key` is in the allowlist:
|
|
207
|
+
- Verify `entry.source.source === "directory"` AND `typeof entry.source.path === "string"`. Either guard fails → skip (not the wizard's shape).
|
|
208
|
+
- Resolve `source.path` (expand `~`). If the resolved path **does not exist**, mark **dead**.
|
|
291
209
|
3. For every dead marketplace `<name>`, look for `enabledPlugins["sdlc-wizard@<name>"]` — also flag for removal.
|
|
292
|
-
4. Repeat for **all** allowlist entries; collect the full set of dead
|
|
210
|
+
4. Repeat for **all** allowlist entries; collect the full set of dead pairs before prompting (multiple are common).
|
|
293
211
|
|
|
294
|
-
**Cleanup (always ask
|
|
212
|
+
**Cleanup (always ask, all-or-nothing per response):**
|
|
295
213
|
|
|
296
214
|
> Your `~/.claude/settings.json` references wizard plugin marketplaces that don't exist on disk:
|
|
297
215
|
>
|
|
298
216
|
> - `extraKnownMarketplaces.sdlc-wizard-local.source.path` → `<resolved-path>` (missing)
|
|
299
217
|
> - `enabledPlugins["sdlc-wizard@sdlc-wizard-local"]` is `true`
|
|
300
|
-
> - (list all dead pairs
|
|
218
|
+
> - (list all dead pairs)
|
|
301
219
|
>
|
|
302
|
-
>
|
|
220
|
+
> Causes `Plugin directory does not exist` on every prompt in every CC session.
|
|
303
221
|
>
|
|
304
|
-
> Drop
|
|
222
|
+
> Drop these entries from `~/.claude/settings.json`? `[y/N]`
|
|
305
223
|
|
|
306
|
-
If
|
|
307
|
-
1. **
|
|
308
|
-
2. **
|
|
309
|
-
3. Write to a temp file, validate with `jq empty` (round-trip parse),
|
|
310
|
-
4. **Formatting note**: `jq` rewrites the whole file
|
|
224
|
+
If yes:
|
|
225
|
+
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).
|
|
226
|
+
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.
|
|
227
|
+
3. Write to a temp file, validate with `jq empty` (round-trip parse), then `mv`. Validation fails → restore from backup.
|
|
228
|
+
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.
|
|
311
229
|
|
|
312
|
-
If
|
|
230
|
+
If no: skip silently. Some users have a recovery plan (re-enable, reinstall).
|
|
313
231
|
|
|
314
|
-
**Idempotency:**
|
|
232
|
+
**Idempotency:** rerunning Step 7.7 after a clean must be a no-op. Only marketplaces with allowlist match AND missing path qualify.
|
|
315
233
|
|
|
316
|
-
**Scope guard:** only
|
|
234
|
+
**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.
|
|
317
235
|
|
|
318
|
-
**Why
|
|
236
|
+
**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.
|
|
319
237
|
|
|
320
|
-
**Runs regardless of version match:** Step 7.7 is global-settings hygiene, not file-update logic.
|
|
238
|
+
**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.
|
|
321
239
|
|
|
322
|
-
**`check-only` precedence:**
|
|
240
|
+
**`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.
|
|
323
241
|
|
|
324
242
|
### Step 8: Apply Selected Changes
|
|
325
243
|
|
|
326
|
-
For each file the
|
|
327
|
-
- Use the Edit tool to update the file content
|
|
328
|
-
- For complete replacements (MISSING files), use Write
|
|
329
|
-
- For settings.json, apply the merge from Step 7
|
|
244
|
+
For each approved file: Edit (existing) or Write (MISSING). For settings.json, apply the merge from Step 7.
|
|
330
245
|
|
|
331
246
|
### Step 9: Bump Version Metadata
|
|
332
247
|
|
|
333
|
-
Update
|
|
248
|
+
Update `SDLC.md`:
|
|
334
249
|
```
|
|
335
250
|
<!-- SDLC Wizard Version: X.X.X -->
|
|
336
|
-
```
|
|
337
|
-
Set it to the latest version.
|
|
338
|
-
|
|
339
|
-
Also update the completed steps if new steps were applied:
|
|
340
|
-
```
|
|
341
251
|
<!-- Completed Steps: step-0.1, step-0.2, ..., step-update-wizard -->
|
|
342
252
|
```
|
|
253
|
+
Set to latest version. Update completed steps if new ones applied.
|
|
343
254
|
|
|
344
255
|
### Step 10: Verify
|
|
345
256
|
|
|
346
|
-
Run drift detection again:
|
|
347
257
|
```bash
|
|
348
258
|
npx agentic-sdlc-wizard check
|
|
349
259
|
```
|
|
350
|
-
|
|
351
|
-
Report final status. All updated files should show MATCH. Files the user chose to skip will still show CUSTOMIZED — that's fine, it's their choice.
|
|
260
|
+
All updated files should show MATCH. User-skipped files still show CUSTOMIZED — that's fine.
|
|
352
261
|
|
|
353
262
|
## Rules
|
|
354
263
|
|
|
355
|
-
1. **NEVER modify CLAUDE.md.**
|
|
356
|
-
2. **NEVER auto-apply without showing what will change first** (unless `force-all`
|
|
357
|
-
3. **Offline fallback:**
|
|
358
|
-
4. **First-time users:**
|
|
359
|
-
5. **Respect customizations.**
|
|
360
|
-
6. **Reference the wizard doc** for full protocol details (step registry, URLs, version tracking) rather than hardcoding
|
|
264
|
+
1. **NEVER modify CLAUDE.md.** Fully custom to user's project. Wizard never touches it.
|
|
265
|
+
2. **NEVER auto-apply without showing what will change first** (unless `force-all`).
|
|
266
|
+
3. **Offline fallback:** WebFetch fails → tell user "Cannot reach GitHub. Run `npx agentic-sdlc-wizard init --force` to update from your locally installed CLI."
|
|
267
|
+
4. **First-time users:** SDLC.md missing or no version metadata → suggest `/setup-wizard`.
|
|
268
|
+
5. **Respect customizations.** CUSTOMIZED files are intentional — show what's different, let them decide. Don't pressure.
|
|
269
|
+
6. **Reference the wizard doc** for full protocol details (step registry, URLs, version tracking) rather than hardcoding.
|