agentic-sdlc-wizard 1.15.0 → 1.18.0

package/cli/templates/skills/sdlc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdlc
-description: Full SDLC workflow for implementing features, fixing bugs, refactoring code, and creating new functionality. Use this skill when implementing, fixing, refactoring, adding features, or building new code.
+description: Full SDLC workflow for implementing features, fixing bugs, refactoring code, testing, and creating new functionality. Use this skill when implementing, fixing, refactoring, testing, adding features, or building new code.
 argument-hint: [task description]
 effort: high
 ---
@@ -18,17 +18,16 @@ TodoWrite([
   // PLANNING PHASE (Plan Mode for non-trivial tasks)
   { content: "Find and read relevant documentation", status: "in_progress", activeForm: "Reading docs" },
   { content: "Assess doc health - flag issues (ask before cleaning)", status: "pending", activeForm: "Checking doc health" },
-  { content: "DRY scan: What patterns exist to reuse?", status: "pending", activeForm: "Scanning for reusable patterns" },
+  { content: "DRY scan: What patterns exist to reuse? New pattern = get approval", status: "pending", activeForm: "Scanning for reusable patterns" },
   { content: "Blast radius: What depends on code I'm changing?", status: "pending", activeForm: "Checking dependencies" },
   { content: "Design system check (if UI change)", status: "pending", activeForm: "Checking design system" },
   { content: "Restate task in own words - verify understanding", status: "pending", activeForm: "Verifying understanding" },
   { content: "Scrutinize test design - right things tested? Follow TESTING.md?", status: "pending", activeForm: "Reviewing test approach" },
   { content: "Present approach + STATE CONFIDENCE LEVEL", status: "pending", activeForm: "Presenting approach" },
   { content: "Signal ready - user exits plan mode", status: "pending", activeForm: "Awaiting plan approval" },
-  // TRANSITION PHASE (After plan mode, before compact)
+  // TRANSITION PHASE (After plan mode)
   { content: "Update feature docs with discovered gotchas", status: "pending", activeForm: "Updating feature docs" },
-  { content: "Request /compact before TDD", status: "pending", activeForm: "Requesting compact" },
-  // IMPLEMENTATION PHASE (After compact)
+  // IMPLEMENTATION PHASE
   { content: "TDD RED: Write failing test FIRST", status: "pending", activeForm: "Writing failing test" },
   { content: "TDD GREEN: Implement, verify test passes", status: "pending", activeForm: "Implementing feature" },
   { content: "Run lint/typecheck", status: "pending", activeForm: "Running lint and typecheck" },
@@ -40,15 +39,38 @@ TodoWrite([
   { content: "Self-review: run /code-review", status: "pending", activeForm: "Running code review" },
   { content: "Security review (if warranted)", status: "pending", activeForm: "Checking security implications" },
   { content: "Cross-model review (if configured — see below)", status: "pending", activeForm: "Running cross-model review" },
+  { content: "Scope guard: only changes related to task? No legacy/fallback code left?", status: "pending", activeForm: "Checking scope and legacy code" },
   // CI FEEDBACK LOOP (if CI monitoring enabled in setup - skip if no CI)
   { content: "Commit and push to remote", status: "pending", activeForm: "Pushing to remote" },
   { content: "Watch CI - fix failures, iterate until green (max 2x)", status: "pending", activeForm: "Watching CI" },
   { content: "Read CI review - implement valid suggestions, iterate until clean", status: "pending", activeForm: "Addressing CI review feedback" },
+  { content: "Post-deploy verification (if deploy task — see Deployment Tasks)", status: "pending", activeForm: "Verifying deployment" },
   // FINAL
-  { content: "Present summary: changes, tests, CI status", status: "pending", activeForm: "Presenting final summary" }
+  { content: "Present summary: changes, tests, CI status", status: "pending", activeForm: "Presenting final summary" },
+  { content: "Capture learnings (if any — update TESTING.md, CLAUDE.md, or feature docs)", status: "pending", activeForm: "Capturing session learnings" }
 ])
 ```
 
+## SDLC Quality Checklist (Scoring Rubric)
+
+Your work is scored on these criteria. **Critical** criteria are must-pass.
+
+| Criterion | Points | Critical? | What Counts |
+|-----------|--------|-----------|-------------|
+| task_tracking | 1 | | Use TodoWrite or TaskCreate |
+| confidence | 1 | | State HIGH/MEDIUM/LOW |
+| tdd_red | 2 | **YES** | Write/edit test files BEFORE implementation files |
+| plan_mode_outline | 1 | | Outline steps before coding |
+| plan_mode_tool | 1 | | Use TodoWrite/TaskCreate/EnterPlanMode |
+| tdd_green_ran | 1 | | Run tests, show runner output |
+| tdd_green_pass | 1 | | All tests pass in final run |
+| self_review | 1 | **YES** | Read back files/diffs you modified |
+| clean_code | 1 | | One coherent approach, no dead code |
+
+**Total: 10 points** (11 for UI tasks, +1 for design_system check)
+
+Critical miss on `tdd_red` or `self_review` = process failure regardless of total score.
+
 ## New Pattern & Test Design Scrutiny (PLANNING)
 
 **New design patterns require human approval:**
@@ -68,22 +90,20 @@ TodoWrite([
 
 **Workflow:**
 1. **Plan Mode** (editing blocked): Research -> Write plan file -> Present approach + confidence
-2. **Transition** (after approval): Update feature docs -> Request /compact
-3. **Implementation** (after compact): TDD RED -> GREEN -> PASS
-
-**Before TDD, MUST ask:** "Docs updated. Run `/compact` before implementation?"
+2. **Transition** (after approval): Update feature docs
+3. **Implementation**: TDD RED -> GREEN -> PASS
 
 ## Confidence Check (REQUIRED)
 
 Before presenting approach, STATE your confidence:
 
-| Level | Meaning | Action |
-|-------|---------|--------|
-| HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval |
-| MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties |
-| LOW (<60%) | Not sure | ASK USER before proceeding |
-| FAILED 2x | Something's wrong | STOP. ASK USER immediately |
-| CONFUSED | Can't diagnose why something is failing | STOP. Describe what you tried, ask for help |
+| Level | Meaning | Action | Effort |
+|-------|---------|--------|--------|
+| HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval | `high` (default) |
+| MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties | `high` (default) |
+| LOW (<60%) | Not sure | ASK USER before proceeding | Consider `/effort max` |
+| FAILED 2x | Something's wrong | STOP. ASK USER immediately | Try `/effort max` |
+| CONFUSED | Can't diagnose why something is failing | STOP. Describe what you tried, ask for help | Try `/effort max` |
 
 ## Self-Review Loop (CRITICAL)
 
@@ -116,38 +136,100 @@ PLANNING -> DOCS -> TDD RED -> TDD GREEN -> Tests Pass -> Self-Review
 
 **Prerequisites:** Codex CLI installed (`npm i -g @openai/codex`), OpenAI API key set.
 
-**Steps:**
+### Round 1: Initial Review
+
 1. After self-review passes, write `.reviews/handoff.json`:
    ```jsonc
    {
      "review_id": "feature-xyz-001",
      "status": "PENDING_REVIEW",
+     "round": 1,
      "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
      "review_instructions": "Review for security, edge cases, and correctness",
      "artifact_path": ".reviews/feature-xyz-001/"
    }
    ```
-2. Tell the user to run the independent reviewer:
+2. Run the independent reviewer:
    ```bash
    codex exec \
      -c 'model_reasoning_effort="xhigh"' \
      -s danger-full-access \
      -o .reviews/latest-review.md \
      "You are an independent code reviewer. Read .reviews/handoff.json, \
-      review the listed files, and write your findings to the artifact_path. \
+      review the listed files. Output each finding with: an ID (1, 2, ...), \
+      severity (P0/P1/P2), description, and a 'certify condition' stating \
+      what specific change would resolve it. \
       End with CERTIFIED or NOT CERTIFIED."
    ```
-3. Read `.reviews/latest-review.md` — if CERTIFIED, proceed to CI. If NOT CERTIFIED, fix findings and repeat from step 1.
+3. If CERTIFIED → proceed to CI. If NOT CERTIFIED → go to Round 2.
+
+### Round 2+: Dialogue Loop
+
+When the reviewer finds issues, respond per-finding instead of silently fixing everything:
+
+1. Write `.reviews/response.json`:
+   ```jsonc
+   {
+     "review_id": "feature-xyz-001",
+     "round": 2,
+     "responding_to": ".reviews/latest-review.md",
+     "responses": [
+       { "finding": "1", "action": "FIXED", "summary": "Added missing validation" },
+       { "finding": "2", "action": "DISPUTED", "justification": "This is intentional — see CODE_REVIEW_EXCEPTIONS.md" },
+       { "finding": "3", "action": "ACCEPTED", "summary": "Will add test coverage" }
+     ]
+   }
+   ```
+   - **FIXED**: "I fixed this. Here is what changed." Reviewer verifies.
+   - **DISPUTED**: "This is intentional/incorrect. Here is why." Reviewer accepts or rejects.
+   - **ACCEPTED**: "You are right. Fixing now." (Same as FIXED, batched.)
+
+2. Update `handoff.json` with `"status": "PENDING_RECHECK"`, increment `round`, add `"response_path"` and `"previous_review"` fields.
+
+3. Run targeted recheck (NOT a full re-review):
+   ```bash
+   codex exec \
+     -c 'model_reasoning_effort="xhigh"' \
+     -s danger-full-access \
+     -o .reviews/latest-review.md \
+     "You are doing a TARGETED RECHECK. First read .reviews/handoff.json \
+      to find the previous_review path — read that file for the original \
+      findings and certify conditions. Then read .reviews/response.json \
+      for the author's responses. For each: \
+      FIXED → verify the fix against the original certify condition. \
+      DISPUTED → evaluate the justification (ACCEPT if sound, REJECT if not). \
+      ACCEPTED → verify it was applied. \
+      Do NOT raise new findings unless P0 (critical/security). \
+      New observations go in 'Notes for next review' (non-blocking). \
+      End with CERTIFIED or NOT CERTIFIED."
+   ```
+
+4. If CERTIFIED → done. If NOT CERTIFIED (rejected disputes or failed fixes) → fix rejected items and repeat.
+
+### Convergence
+
+Max 3 recheck rounds (4 total including initial review). If still NOT CERTIFIED after round 4, escalate to the user with a summary of open findings. Don't spin indefinitely.
 
 ```
-Self-review passes → write handoff.json → user runs codex exec
-    ^                                              |
-    |                                    CERTIFIED? → YES → CI feedback loop
-    |                                              |
-    |                                              → NO (findings)
-    |                                              |
-    └──────── Fix findings ←───────────────────────┘
-                  (repeat until CERTIFIED, or ask user)
+Self-review passes → handoff.json (round 1, PENDING_REVIEW)
+                            |
+                   Reviewer: FULL REVIEW (structured findings)
+                            |
+                   CERTIFIED? → YES → CI feedback loop
+                            |
+                            NO (findings with IDs + certify conditions)
+                            |
+                   Claude writes response.json:
+                     FIXED / DISPUTED / ACCEPTED per finding
+                            |
+                   handoff.json (round 2+, PENDING_RECHECK)
+                            |
+                   Reviewer: TARGETED RECHECK (previous findings only)
+                            |
+                   All resolved? → YES → CERTIFIED
+                            |
+                            NO → fix rejected items, repeat
+                            (max 3 rechecks, then escalate to user)
 ```
 
 **Tool-agnostic:** The value is adversarial diversity (different model, different blind spots), not the specific tool. Any competing AI reviewer works.
@@ -161,11 +243,41 @@ During self-review, critique tests HARDER than app code:
 2. **Tests prove correctness?** - Or just verify current behavior?
 3. **Follow our philosophies (TESTING.md)?**
    - Testing Diamond (integration-heavy)?
-   - Minimal mocking (real DB, mock external APIs only)?
+   - Minimal mocking (see table below)?
    - Real fixtures from captured data?
 
 **Tests are the foundation.** Bad tests = false confidence = production bugs.
 
+### Minimal Mocking Philosophy
+
+| What | Mock? | Why |
+|------|-------|-----|
+| Database | NEVER | Use test DB or in-memory |
+| Cache | NEVER | Use isolated test instance |
+| External APIs | YES | Real calls = flaky + expensive |
+| Time/Date | YES | Determinism |
+
+**Mocks MUST come from REAL captured data** — capture real API responses, save to fixtures directory, import in tests. Never guess mock shapes.
+
+### Unit Tests = Pure Logic ONLY
+
+A function qualifies for unit testing ONLY if:
+- No database calls
+- No external API calls
+- No file system access
+- No cache calls
+- Input -> Output transformation only
+
+Everything else needs integration tests.
+
+### TDD Tests Must PROVE
+
+| Phase | What It Proves |
+|-------|----------------|
+| RED | Test FAILS -> Bug exists or feature missing |
+| GREEN | Test PASSES -> Fix works or feature implemented |
+| Forever | Regression protection |
+
 ## Flaky Test Recovery
 
 When a test fails intermittently:
@@ -350,6 +462,16 @@ CI passes -> Read review suggestions
 
 **If ARCHITECTURE.md has no Environments section:** Ask user "How do you deploy to [target]?" before proceeding.
 
+**After deploying — Post-Deploy Verification:**
+1. Read ARCHITECTURE.md → Find the Post-Deploy Verification table
+2. Run health check for the target environment
+3. Check logs for new errors
+4. Run smoke tests if configured
+5. Monitor error rates for 15 min (production only)
+6. If issues found → rollback first, then start new SDLC loop to fix
+
+**If ARCHITECTURE.md has no Post-Deploy section:** Ask user "How do you verify [target] is working after deploy?"
+
 ## DELETE Legacy Code
 
 - Legacy code? DELETE IT
@@ -358,6 +480,13 @@ CI passes -> Read review suggestions
 
 **THE RULE:** Delete old code first. If it breaks, fix it properly.
 
+## After Session (Capture Learnings)
+
+If this session revealed insights, update the right place:
+- **Testing patterns, gotchas** → `TESTING.md`
+- **Feature-specific quirks** → Feature docs (`*_PLAN.md`)
+- **General project context** → `CLAUDE.md` (or `/revise-claude-md`)
+
 ---
 
 **Full reference:** SDLC.md

package/cli/templates/skills/setup/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: setup-wizard
+description: Interactive project setup wizard that scans the codebase, asks all 16 configuration questions, generates SDLC files (CLAUDE.md, SDLC.md, TESTING.md, ARCHITECTURE.md), and verifies the installation. Use this skill when setting up the SDLC wizard for the first time or re-running setup.
+argument-hint: [optional: regenerate | verify-only]
+effort: high
+---
+# Setup Wizard - Interactive Project Configuration
+
+## Task
+$ARGUMENTS
+
+## Purpose
+
+You are an interactive setup wizard. Your job is to scan the project, ask the user ALL configuration questions, and generate the SDLC files. DO NOT skip questions. DO NOT make assumptions. The user's answers drive the output.
+
+## MANDATORY FIRST ACTION: Read the Wizard Doc
+
+**Before doing ANYTHING else**, use the Read tool to read the ENTIRE `CLAUDE_CODE_SDLC_WIZARD.md` file. This file contains all templates, examples, and instructions you need. You CANNOT do this setup correctly without reading it first. Do NOT rely on summaries or references — read the full file now.
+
+After reading, use it as the source of truth for every step below.
+
+## Execution Checklist
+
+Follow these steps IN ORDER. Do not skip or combine steps.
+
+### Step 1: Auto-Scan the Project
+
+Scan the project root for:
+- Package managers: package.json, Cargo.toml, go.mod, pyproject.toml, Gemfile, build.gradle, pom.xml
+- Source directories: src/, app/, lib/, server/, pkg/, cmd/
+- Test directories: tests/, __tests__/, spec/, test files matching *_test.*, test_*.*
+- Test frameworks: from config files (jest.config, vitest.config, pytest.ini, etc.)
+- Lint/format tools: .eslintrc, biome.json, .prettierrc, rustfmt.toml, etc.
+- CI/CD: .github/workflows/, .gitlab-ci.yml, Jenkinsfile
+- Feature docs: *_PLAN.md, *_DOCS.md, *_SPEC.md, docs/
+- Deployment: Dockerfile, vercel.json, fly.toml, netlify.toml, Procfile, k8s/
+- Design system: tailwind.config.*, .storybook/, theme files, CSS custom properties
+- Existing docs: README.md, CLAUDE.md, ARCHITECTURE.md
+
+Present findings to the user in a clear summary with detected values.
+
+### Step 2: Ask ALL 17 Questions
+
+Ask every question. Pre-fill detected values but let the user confirm or override.
+
+**Project Structure:**
+1. Source directory (detected or ask)
+2. Test directory (detected or ask)
+3. Test framework (detected or ask)
+
+**Commands:**
+4. Lint command
+5. Type-check command
+6. Run all tests command
+7. Run single test file command
+8. Production build command
+9. Deployment setup (detected environments, confirm or customize)
+
+**Infrastructure:**
+10. Database(s) used
+11. Caching layer (Redis, etc.)
+12. Test duration (<1 min, 1-5 min, 5+ min)
+
+**Output Preferences:**
+13. Response detail level (small/medium/large)
+
+**Testing Philosophy:**
+14. Testing approach (strict TDD, test-after, mixed, minimal, none yet)
+15. Test types wanted (unit, integration, E2E, API)
+16. Mocking philosophy (minimal, heavy, no mocking)
+
+**Coverage:**
+17. Code coverage preferences (enforce threshold, report only, AI suggestions, skip)
+
+DO NOT proceed to file generation until ALL 17 questions have answers.
+
+### Step 3: Generate CLAUDE.md
+
+Using the user's answers, generate `CLAUDE.md` with:
+- Project overview (from scan results)
+- Commands table (Q4-Q8 answers)
+- Code style section (from detected linters/formatters)
+- Architecture summary (from scan)
+- Special notes (from Q9-Q11)
+
+Reference: See "Step 3" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
+
+### Step 4: Generate SDLC.md
+
+Generate `SDLC.md` with the full SDLC checklist customized to the project:
+- Plan mode guidance
+- TDD workflow with project-specific commands
+- Self-review steps
+- CI feedback loop (if CI detected)
+- Confidence levels
+
+Include metadata comments:
+```
+<!-- SDLC Wizard Version: [version from CLAUDE_CODE_SDLC_WIZARD.md] -->
+<!-- Setup Date: [today's date] -->
+<!-- Completed Steps: 0.4, 1-10 -->
+```
+
+Reference: See "Step 4" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
+
+### Step 5: Generate TESTING.md
+
+Generate `TESTING.md` based on Q13-Q16 answers:
+- Testing Diamond visualization
+- Test types and their purposes
+- Mocking rules (from Q15)
+- Test file organization (from Q2, Q3)
+- Coverage config (from Q16)
+- Framework-specific patterns
+
+Reference: See "Step 5" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
+
+### Step 6: Generate ARCHITECTURE.md
+
+Generate `ARCHITECTURE.md` with:
+- System overview diagram (from scan)
+- Component descriptions
+- Environments table (from Q8.5)
+- Deployment checklist
+- Key technical decisions
+
+Reference: See "Step 6" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
+
+### Step 7: Generate DESIGN_SYSTEM.md (If UI Detected)
+
+Only if design system artifacts were found in Step 1:
+- Extract colors, fonts, spacing from config
+- Document component patterns
+- Reference design sources (Storybook, Figma, etc.)
+
+Skip this step if no UI/design system detected.
+
+### Step 8: Configure Tool Permissions
+
+Based on detected stack, suggest `allowedTools` entries for `.claude/settings.json`:
+- Package manager commands (npm, pnpm, yarn, cargo, go, pip, etc.)
+- Build/test commands
+- CI tools (gh)
+
+Present suggestions and let the user confirm.
+
+### Step 9: Customize Hooks
+
+Update `tdd-pretool-check.sh` with the actual source directory from Q1 (replace generic `/src/` pattern).
+
+### Step 10: Verify Setup
+
+Run verification checks:
+1. All generated files exist and are non-empty
+2. Hooks are executable (`chmod +x`)
+3. `settings.json` is valid JSON
+4. Skill frontmatter is correct (name, effort fields)
+5. `.gitignore` has required entries (.claude/plans/, .claude/settings.local.json)
+
+Report any issues found.
+
+### Step 11: Instruct Restart
+
+Tell the user:
+> Setup complete. Hooks and settings load at session start.
+> **Exit Claude Code and restart it** for the new configuration to take effect.
+> On restart, the SDLC hook will fire and you'll see the checklist in every response.
+
+## Rules
+
+- NEVER skip a question. If the user says "I don't know", record that and move on.
+- NEVER assume answers. If auto-scan can't detect something, ASK.
+- ALWAYS show detected values and let the user confirm or override.
+- ALWAYS generate metadata comments in SDLC.md (version, date, steps).
+- If the user passes `regenerate` as an argument, skip Q&A and regenerate files from existing SDLC.md metadata.
+- If the user passes `verify-only` as an argument, skip to Step 10 (verify) only.

package/cli/templates/skills/update/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: update-wizard
+description: Smart update for SDLC wizard — shows changelog, compares files, lets you selectively adopt changes while preserving customizations.
+argument-hint: [optional: check-only | force-all]
+effort: high
+---
+# Update Wizard - Smart SDLC Update
+
+## Task
+$ARGUMENTS
+
+## Purpose
+
+You are a guided update assistant. Your job is to check what version the user has, show what changed, and walk them through selectively adopting updates while preserving their customizations. DO NOT blindly overwrite files. Show diffs and let the user decide.
+
+## MANDATORY FIRST ACTION: Read the Wizard Doc
+
+**Before doing ANYTHING else**, use the Read tool to read the `CLAUDE_CODE_SDLC_WIZARD.md` file — specifically the "Staying Updated (Idempotent Wizard)" section near the end. This contains the update URLs, version tracking format, and step registry you need. Do NOT proceed without reading it first.
+
+## Execution Checklist
+
+Follow these steps IN ORDER. Do not skip or combine steps.
+
+### Step 1: Read Installed Version
+
+Read `SDLC.md` and extract the version from the metadata comment:
+```
+<!-- SDLC Wizard Version: X.X.X -->
+```
+If no version comment exists, treat as `0.0.0` (first-time setup — suggest running `/setup-wizard` instead).
+
+Also note the completed steps from `<!-- Completed Steps: ... -->`.
+
+### Step 2: Fetch Latest CHANGELOG
+
+Use WebFetch to fetch the CHANGELOG:
+```
+https://raw.githubusercontent.com/BaseInfinity/agentic-ai-sdlc-wizard/main/CHANGELOG.md
+```
+
+Extract the latest version from the first `## [X.X.X]` line.
+
+### Step 3: Compare Versions and Show What Changed
+
+Parse all CHANGELOG entries between the user's installed version and the latest. Present a clear summary:
+
+```
+Installed: 1.15.0
+Latest:    1.18.0
+
+What changed:
+- [1.18.0] Added /update-wizard skill, ...
+- [1.17.0] Consolidated /testing into /sdlc, ...
+- [1.16.0] Cross-model review protocol, ...
+```
+
+**If versions match:** Say "You're up to date! (version X.X.X)" and stop.
+
+**If user passed `check-only`:** Stop here after showing what changed. Do not apply anything.
+
+### Step 4: Run Drift Detection
+
+Run the CLI drift checker to see per-file status:
+```bash
+npx agentic-sdlc-wizard check
+```
+
+This reports each managed file as MATCH, CUSTOMIZED, MISSING, or DRIFT. Present the results.
+
+### Step 5: Fetch Latest Wizard Doc
+
+Use WebFetch to fetch the latest wizard:
+```
+https://raw.githubusercontent.com/BaseInfinity/agentic-ai-sdlc-wizard/main/CLAUDE_CODE_SDLC_WIZARD.md
+```
+
+This is the source of truth for all templates, hooks, skills, and step registry.
+
+### Step 6: Present Per-File Update Plan
+
+For each managed file from the `sdlc-wizard check` output:
+
+| Status | Action |
+|--------|--------|
+| MATCH | Skip — already current |
+| MISSING | Recommend install — show what the file does |
+| CUSTOMIZED | Show what changed in latest vs user's version. Ask: adopt, skip, or merge? |
+| DRIFT | Flag the issue (e.g., missing executable permission). Offer to fix |
+
+Read both the installed file and the latest template content. Present a human-readable summary of differences — not a raw diff, but "what was added/changed/removed and why."
+
+**If user passed `force-all`:** Skip per-file approval and apply all updates.
+
+### Step 7: Handle settings.json Specially
+
+NEVER overwrite settings.json. Instead:
+
+1. Read the user's current settings.json
+2. Compare against the latest template's hook definitions
+3. Describe what hooks changed (added, updated, removed)
+4. Offer to merge: update wizard hooks while preserving all custom hooks, permissions, and other settings
+
+The CLI's `init --force` already has smart merge logic for settings.json. If the manual merge gets complicated, suggest: `npx agentic-sdlc-wizard init --force` (it preserves custom hooks).
+
+### Step 8: Apply Selected Changes
+
+For each file the user approved:
+- Use the Edit tool to update the file content
+- For complete replacements (MISSING files), use Write
+- For settings.json, apply the merge from Step 7
+
+### Step 9: Bump Version Metadata
+
+Update the version in `SDLC.md`:
+```
+<!-- SDLC Wizard Version: X.X.X -->
+```
+Set it to the latest version.
+
+Also update the completed steps if new steps were applied:
+```
+<!-- Completed Steps: step-0.1, step-0.2, ..., step-update-wizard -->
+```
+
+### Step 10: Verify
+
+Run drift detection again:
+```bash
+npx agentic-sdlc-wizard check
+```
+
+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.
+
+## Rules
+
+1. **NEVER modify CLAUDE.md.** It is fully custom to the user's project. The wizard never touches it.
+2. **NEVER auto-apply without showing what will change first** (unless `force-all` was passed).
+3. **Offline fallback:** If WebFetch fails (network unavailable), tell the user: "Cannot reach GitHub. Run `npx agentic-sdlc-wizard init --force` to update from your locally installed CLI version instead."
+4. **First-time users:** If SDLC.md doesn't exist or has no version metadata, suggest `/setup-wizard` instead of `/update-wizard`.
+5. **Respect customizations.** When a file is CUSTOMIZED, the user made intentional changes. Show what's different and let them decide — don't pressure them to adopt the latest.
+6. **Reference the wizard doc** for full protocol details (step registry, URLs, version tracking) rather than hardcoding values in this skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.15.0",
+  "version": "1.18.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "./cli/bin/sdlc-wizard.js"