agentic-sdlc-wizard 1.47.0 → 1.49.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 +36 -0
- package/CLAUDE_CODE_SDLC_WIZARD.md +2 -2
- package/package.json +1 -1
- package/skills/sdlc/SKILL.md +170 -661
- package/skills/update/SKILL.md +120 -211
package/skills/update/SKILL.md
CHANGED
|
@@ -11,351 +11,260 @@ $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.49.0
|
|
135
97
|
|
|
136
98
|
What changed:
|
|
137
|
-
- [1.
|
|
138
|
-
- [1.
|
|
139
|
-
- [1.
|
|
140
|
-
- [1.
|
|
141
|
-
- [1.
|
|
142
|
-
- [1.
|
|
143
|
-
- [1.
|
|
144
|
-
|
|
145
|
-
- [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).
|
|
146
|
-
- [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.
|
|
147
|
-
- [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.
|
|
148
|
-
- [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.
|
|
149
|
-
- [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.
|
|
150
|
-
- [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.
|
|
151
|
-
- [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.
|
|
152
|
-
- [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.
|
|
153
|
-
- [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`).
|
|
154
|
-
- [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.
|
|
155
|
-
- [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.
|
|
156
|
-
- [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
|
|
157
|
-
- [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)
|
|
158
|
-
- [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, ...
|
|
159
|
-
- [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, ...
|
|
160
|
-
- [1.33.0] opus[1m] as SDLC default, dual-channel install drift guardrails, model/effort session-start nudge, ...
|
|
161
|
-
- [1.32.0] Opus 4.7 + xhigh support, model/effort upgrade detection, benchmark ceiling audit, ...
|
|
162
|
-
- [1.31.0] Hook false-positive fix for non-SDLC dirs, ephemeral marketplace path warning, ...
|
|
163
|
-
- [1.30.0] Firmware fixture, model A/B comparison workflow, CC degradation detection, ...
|
|
164
|
-
- [1.29.0] Node 24 compliance, autocompact in settings.json, effectiveness scoreboard, ...
|
|
165
|
-
- [1.28.0] Autocompact benchmarking methodology, canary fact mechanism, benchmark harness, ...
|
|
166
|
-
- [1.27.0] Domain-adaptive testing diamond, 3 domain fixtures, 25 quality tests, ...
|
|
167
|
-
- [1.26.0] Codex SDLC Adapter plan, claw-code/OmO/OmX research, CC feature discovery verified, ...
|
|
168
|
-
- [1.25.0] Plugin format, 6 distribution channels (curl, Homebrew, gh, GitHub Releases), ...
|
|
169
|
-
- [1.24.0] Hook if conditionals, autocompact tuning + 1M/200K guidance, tdd_red fix, ...
|
|
99
|
+
- [1.49.0] local-shepherd.sh --compare-baseline flag (#230)
|
|
100
|
+
- [1.48.0] SKILL.md trim — token bloat audit phase 2 follow-up
|
|
101
|
+
- [1.47.0] Codex review progress wrapper (#259)
|
|
102
|
+
- [1.46.1] npx check surfaces dangling+enabled plugin state (#266)
|
|
103
|
+
- [1.46.0] PreCompact dry-run env vars (#240)
|
|
104
|
+
- [1.45.0] PreCompact path (c) — SHA-ancestry self-heal (#257)
|
|
105
|
+
- [1.44.1] Autocompact compound-misconfig detection (#207)
|
|
106
|
+
... (full entries from fetched CHANGELOG)
|
|
170
107
|
```
|
|
171
108
|
|
|
172
|
-
|
|
109
|
+
Read the actual entries from the fetched CHANGELOG; don't paraphrase. The user wants to see exactly what shipped.
|
|
110
|
+
|
|
111
|
+
**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*:
|
|
173
112
|
|
|
174
113
|
- **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.
|
|
175
|
-
- **With `check-only`**: Run Step 7.7 in detection-only mode — report any dead plugin registrations
|
|
114
|
+
- **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.
|
|
176
115
|
|
|
177
|
-
**If user passed `check-only` and versions don't match:** Stop after showing what changed. Do not apply anything
|
|
116
|
+
**If user passed `check-only` and versions don't match:** Stop after showing what changed. Do not apply anything.
|
|
178
117
|
|
|
179
118
|
### Step 4: Run Drift Detection
|
|
180
119
|
|
|
181
|
-
Run the CLI drift checker to see per-file status:
|
|
182
120
|
```bash
|
|
183
121
|
npx agentic-sdlc-wizard check
|
|
184
122
|
```
|
|
185
|
-
|
|
186
|
-
This reports each managed file as MATCH, CUSTOMIZED, MISSING, or DRIFT. Present the results.
|
|
123
|
+
Reports each managed file as MATCH, CUSTOMIZED, MISSING, or DRIFT.
|
|
187
124
|
|
|
188
125
|
### Step 5: Fetch Latest Wizard Doc
|
|
189
126
|
|
|
190
|
-
|
|
127
|
+
WebFetch:
|
|
191
128
|
```
|
|
192
129
|
https://raw.githubusercontent.com/BaseInfinity/claude-sdlc-wizard/main/CLAUDE_CODE_SDLC_WIZARD.md
|
|
193
130
|
```
|
|
131
|
+
Source of truth for all templates, hooks, skills, step registry.
|
|
194
132
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
### Step 6: Present Per-File Update Plan
|
|
198
|
-
|
|
199
|
-
For each managed file from the `sdlc-wizard check` output:
|
|
133
|
+
### Step 6: Per-File Update Plan
|
|
200
134
|
|
|
201
135
|
| Status | Action |
|
|
202
136
|
|--------|--------|
|
|
203
137
|
| MATCH | Skip — already current |
|
|
204
|
-
| MISSING | Recommend install —
|
|
138
|
+
| MISSING | Recommend install — explain what the file does |
|
|
205
139
|
| CUSTOMIZED | Show what changed in latest vs user's version. Ask: adopt, skip, or merge? |
|
|
206
140
|
| DRIFT | Flag the issue (e.g., missing executable permission). Offer to fix |
|
|
207
141
|
|
|
208
|
-
Read both the installed file and the latest template
|
|
209
|
-
|
|
210
|
-
**If user passed `force-all`:** Skip per-file approval and apply all updates.
|
|
142
|
+
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.
|
|
211
143
|
|
|
212
|
-
|
|
144
|
+
**If user passed `force-all`:** skip per-file approval, apply all updates.
|
|
213
145
|
|
|
214
|
-
|
|
146
|
+
### Step 7: settings.json (Smart Merge Only)
|
|
215
147
|
|
|
216
|
-
|
|
217
|
-
2. Compare against the latest template's hook definitions
|
|
218
|
-
3. Describe what hooks changed (added, updated, removed)
|
|
219
|
-
4. Offer to merge: update wizard hooks while preserving all custom hooks, permissions, and other settings
|
|
148
|
+
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.
|
|
220
149
|
|
|
221
|
-
|
|
150
|
+
CLI's `init --force` already has smart-merge logic. If manual merge gets complicated, suggest: `npx agentic-sdlc-wizard init --force` (preserves custom hooks).
|
|
222
151
|
|
|
223
152
|
### Step 7.5: Model Pin Migration (Issue #198)
|
|
224
153
|
|
|
225
|
-
Wizard
|
|
154
|
+
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.
|
|
226
155
|
|
|
227
|
-
|
|
156
|
+
Check user's `.claude/settings.json`:
|
|
228
157
|
|
|
229
|
-
1.
|
|
230
|
-
|
|
231
|
-
>
|
|
232
|
-
>
|
|
233
|
-
>
|
|
234
|
-
> - **Remove the pin** (recommended for most users) — keeps auto-mode enabled, lets Claude Code pick the model per turn.
|
|
235
|
-
> - **Keep the pin** — you want guaranteed Opus 4.7 + 1M context, and you're OK giving up model auto-selection.
|
|
236
|
-
>
|
|
158
|
+
1. **`model: "opus[1m]"` AND `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "30"`** — likely the old wizard-installed pair, not an intentional choice. Ask:
|
|
159
|
+
> 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).
|
|
160
|
+
> - **Remove the pin** (recommended) — keeps auto-mode enabled
|
|
161
|
+
> - **Keep the pin** — guaranteed Opus 4.7 + 1M, OK with no auto-selection
|
|
237
162
|
> Remove, keep, or decide later? `[r/k/l]`
|
|
238
163
|
|
|
239
|
-
2. **
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
4. **If `model` is some other value** (e.g. `"sonnet"`, `"opus"`) — treat as user's explicit choice. Do not touch.
|
|
164
|
+
2. **Only one of the two fields matches** — treat as intentional customization. Do not prompt.
|
|
165
|
+
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."
|
|
166
|
+
4. **Other `model` value** (`sonnet`, `opus`) — explicit user choice. Do not touch.
|
|
167
|
+
5. **Neither field set** — already on new default.
|
|
244
168
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
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.
|
|
169
|
+
When removing: drop `model` (and `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` if `env` becomes empty). Never touch other keys.
|
|
248
170
|
|
|
249
171
|
### Step 7.6: `allowedTools` → `permissions.allow` Migration (Issue #197)
|
|
250
172
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
If the user's `.claude/settings.json` has a top-level `allowedTools` array, offer to migrate:
|
|
173
|
+
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"`.
|
|
254
174
|
|
|
255
|
-
|
|
175
|
+
If user's `.claude/settings.json` has top-level `allowedTools`, offer migrate:
|
|
256
176
|
|
|
257
|
-
|
|
258
|
-
>
|
|
259
|
-
> - **Migrate** (recommended): move all entries into `permissions.allow`, remove the
|
|
260
|
-
> - **Keep** —
|
|
261
|
-
> - **Later** — don't touch
|
|
262
|
-
>
|
|
177
|
+
1. **Only `allowedTools`** (no `permissions.allow`) — ask:
|
|
178
|
+
> Your `.claude/settings.json` has top-level `allowedTools` (silently disables auto-mode, issue #197). Successor: `permissions.allow`.
|
|
179
|
+
> - **Migrate** (recommended): move all entries into `permissions.allow`, remove the legacy key
|
|
180
|
+
> - **Keep** — specific reason for legacy key
|
|
181
|
+
> - **Later** — don't touch now
|
|
263
182
|
> `[m/k/l]`
|
|
264
183
|
|
|
265
|
-
2. **
|
|
184
|
+
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.
|
|
266
185
|
|
|
267
|
-
3. **
|
|
186
|
+
3. **Only `permissions.allow`** — already on new shape.
|
|
187
|
+
4. **Neither** — no action.
|
|
268
188
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
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.
|
|
189
|
+
Preserve every entry byte-for-byte; only the container key changes. Do not reorder, dedup, or expand wildcards. Other top-level keys never touched.
|
|
272
190
|
|
|
273
191
|
### Step 7.7: Dead Plugin Registration Cleanup (Global Settings)
|
|
274
192
|
|
|
275
|
-
Wizard installs sometimes leave dead plugin registrations in
|
|
193
|
+
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.
|
|
276
194
|
|
|
277
|
-
This step is **global-settings-only** (`~/.claude/settings.json`, not
|
|
195
|
+
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.
|
|
278
196
|
|
|
279
|
-
**Wizard-owned marketplace allowlist** (exact match
|
|
197
|
+
**Wizard-owned marketplace allowlist** (exact match — wildcards risk eating third-party `sdlc-wizard-tools` if such a thing ships):
|
|
280
198
|
|
|
281
199
|
- `sdlc-wizard-local`
|
|
282
200
|
- `sdlc-wizard-wrap`
|
|
283
201
|
|
|
284
|
-
If `cli/init.js` later
|
|
202
|
+
If `cli/init.js` later adds wizard marketplace names, append verbatim.
|
|
285
203
|
|
|
286
204
|
**Detection:**
|
|
287
205
|
|
|
288
|
-
1. Read `~/.claude/settings.json
|
|
289
|
-
2. For each `extraKnownMarketplaces[key]` where `key` is in the allowlist
|
|
290
|
-
- Verify `entry.source.source === "directory"` AND `typeof entry.source.path === "string"`.
|
|
291
|
-
- Resolve
|
|
206
|
+
1. Read `~/.claude/settings.json`, parse as JSON.
|
|
207
|
+
2. For each `extraKnownMarketplaces[key]` where `key` is in the allowlist:
|
|
208
|
+
- Verify `entry.source.source === "directory"` AND `typeof entry.source.path === "string"`. Either guard fails → skip (not the wizard's shape).
|
|
209
|
+
- Resolve `source.path` (expand `~`). If the resolved path **does not exist**, mark **dead**.
|
|
292
210
|
3. For every dead marketplace `<name>`, look for `enabledPlugins["sdlc-wizard@<name>"]` — also flag for removal.
|
|
293
|
-
4. Repeat for **all** allowlist entries; collect the full set of dead
|
|
211
|
+
4. Repeat for **all** allowlist entries; collect the full set of dead pairs before prompting (multiple are common).
|
|
294
212
|
|
|
295
|
-
**Cleanup (always ask
|
|
213
|
+
**Cleanup (always ask, all-or-nothing per response):**
|
|
296
214
|
|
|
297
215
|
> Your `~/.claude/settings.json` references wizard plugin marketplaces that don't exist on disk:
|
|
298
216
|
>
|
|
299
217
|
> - `extraKnownMarketplaces.sdlc-wizard-local.source.path` → `<resolved-path>` (missing)
|
|
300
218
|
> - `enabledPlugins["sdlc-wizard@sdlc-wizard-local"]` is `true`
|
|
301
|
-
> - (list all dead pairs
|
|
219
|
+
> - (list all dead pairs)
|
|
302
220
|
>
|
|
303
|
-
>
|
|
221
|
+
> Causes `Plugin directory does not exist` on every prompt in every CC session.
|
|
304
222
|
>
|
|
305
|
-
> Drop
|
|
223
|
+
> Drop these entries from `~/.claude/settings.json`? `[y/N]`
|
|
306
224
|
|
|
307
|
-
If
|
|
308
|
-
1. **
|
|
309
|
-
2. **
|
|
310
|
-
3. Write to a temp file, validate with `jq empty` (round-trip parse),
|
|
311
|
-
4. **Formatting note**: `jq` rewrites the whole file
|
|
225
|
+
If yes:
|
|
226
|
+
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).
|
|
227
|
+
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.
|
|
228
|
+
3. Write to a temp file, validate with `jq empty` (round-trip parse), then `mv`. Validation fails → restore from backup.
|
|
229
|
+
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.
|
|
312
230
|
|
|
313
|
-
If
|
|
231
|
+
If no: skip silently. Some users have a recovery plan (re-enable, reinstall).
|
|
314
232
|
|
|
315
|
-
**Idempotency:**
|
|
233
|
+
**Idempotency:** rerunning Step 7.7 after a clean must be a no-op. Only marketplaces with allowlist match AND missing path qualify.
|
|
316
234
|
|
|
317
|
-
**Scope guard:** only
|
|
235
|
+
**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.
|
|
318
236
|
|
|
319
|
-
**Why
|
|
237
|
+
**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.
|
|
320
238
|
|
|
321
|
-
**Runs regardless of version match:** Step 7.7 is global-settings hygiene, not file-update logic.
|
|
239
|
+
**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.
|
|
322
240
|
|
|
323
|
-
**`check-only` precedence:**
|
|
241
|
+
**`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.
|
|
324
242
|
|
|
325
243
|
### Step 8: Apply Selected Changes
|
|
326
244
|
|
|
327
|
-
For each file the
|
|
328
|
-
- Use the Edit tool to update the file content
|
|
329
|
-
- For complete replacements (MISSING files), use Write
|
|
330
|
-
- For settings.json, apply the merge from Step 7
|
|
245
|
+
For each approved file: Edit (existing) or Write (MISSING). For settings.json, apply the merge from Step 7.
|
|
331
246
|
|
|
332
247
|
### Step 9: Bump Version Metadata
|
|
333
248
|
|
|
334
|
-
Update
|
|
249
|
+
Update `SDLC.md`:
|
|
335
250
|
```
|
|
336
251
|
<!-- SDLC Wizard Version: X.X.X -->
|
|
337
|
-
```
|
|
338
|
-
Set it to the latest version.
|
|
339
|
-
|
|
340
|
-
Also update the completed steps if new steps were applied:
|
|
341
|
-
```
|
|
342
252
|
<!-- Completed Steps: step-0.1, step-0.2, ..., step-update-wizard -->
|
|
343
253
|
```
|
|
254
|
+
Set to latest version. Update completed steps if new ones applied.
|
|
344
255
|
|
|
345
256
|
### Step 10: Verify
|
|
346
257
|
|
|
347
|
-
Run drift detection again:
|
|
348
258
|
```bash
|
|
349
259
|
npx agentic-sdlc-wizard check
|
|
350
260
|
```
|
|
351
|
-
|
|
352
|
-
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.
|
|
261
|
+
All updated files should show MATCH. User-skipped files still show CUSTOMIZED — that's fine.
|
|
353
262
|
|
|
354
263
|
## Rules
|
|
355
264
|
|
|
356
|
-
1. **NEVER modify CLAUDE.md.**
|
|
357
|
-
2. **NEVER auto-apply without showing what will change first** (unless `force-all`
|
|
358
|
-
3. **Offline fallback:**
|
|
359
|
-
4. **First-time users:**
|
|
360
|
-
5. **Respect customizations.**
|
|
361
|
-
6. **Reference the wizard doc** for full protocol details (step registry, URLs, version tracking) rather than hardcoding
|
|
265
|
+
1. **NEVER modify CLAUDE.md.** Fully custom to user's project. Wizard never touches it.
|
|
266
|
+
2. **NEVER auto-apply without showing what will change first** (unless `force-all`).
|
|
267
|
+
3. **Offline fallback:** WebFetch fails → tell user "Cannot reach GitHub. Run `npx agentic-sdlc-wizard init --force` to update from your locally installed CLI."
|
|
268
|
+
4. **First-time users:** SDLC.md missing or no version metadata → suggest `/setup-wizard`.
|
|
269
|
+
5. **Respect customizations.** CUSTOMIZED files are intentional — show what's different, let them decide. Don't pressure.
|
|
270
|
+
6. **Reference the wizard doc** for full protocol details (step registry, URLs, version tracking) rather than hardcoding.
|