agentic-sdlc-wizard 1.15.0 → 1.18.0

package/README.md

@@ -1,6 +1,52 @@
 # Claude Code SDLC Wizard
 
-A **self-evolving SDLC enforcement system for AI coding agents**. Makes Claude plan before coding, test before shipping, and ask when uncertain. Measures itself getting better over time.
+A **self-evolving Software Development Life Cycle (SDLC) enforcement system for AI coding agents**. Makes Claude plan before coding, test before shipping, and ask when uncertain. Measures itself getting better over time.
+
+## Install
+
+**Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)** (Anthropic's CLI for Claude).
+
+Run from your terminal or from inside Claude Code (`!` prefix):
+```bash
+npx agentic-sdlc-wizard init
+```
+Then start (or restart) Claude Code — type `/exit` then `claude` to reload hooks. Setup auto-invokes on first prompt — Claude reads the wizard doc, scans your project, and generates bespoke CLAUDE.md, SDLC.md, TESTING.md, and ARCHITECTURE.md. No manual commands needed.
+
+<details>
+<summary>Alternative install methods</summary>
+
+**From GitHub (no npm needed):**
+```bash
+npx github:BaseInfinity/agentic-ai-sdlc-wizard init
+```
+
+**Manual:** Download `CLAUDE_CODE_SDLC_WIZARD.md` to your project and tell Claude `Run the SDLC wizard setup`.
+</details>
+
+<details>
+<summary>Health check & updates</summary>
+
+```bash
+npx agentic-sdlc-wizard check        # Human-readable
+npx agentic-sdlc-wizard check --json  # Machine-readable (CI-friendly)
+```
+
+Reports MATCH / CUSTOMIZED / MISSING / DRIFT for every installed file. Exits non-zero on MISSING or DRIFT — use in CI to catch setup regressions.
+
+**Check for content updates:** Tell Claude `Check if the SDLC wizard has updates` — it reads [CHANGELOG.md](CHANGELOG.md), shows what's new, and offers to apply changes.
+</details>
+
+## Why Use This
+
+You want Claude Code to follow engineering discipline automatically:
+- **Plan before coding** (not guess-and-check)
+- **Write tests first** (TDD enforced via hooks)
+- **State confidence** (LOW = ask user, don't guess)
+- **Track work visibly** (TaskCreate)
+- **Self-review before presenting**
+- **Prove it's better** (use native features unless you prove custom wins)
+
+The wizard auto-detects your stack (package.json, test framework, deployment targets) and generates bespoke hooks + skills + docs. CI validates the generated assets; cross-stack setup-path E2E is on the [roadmap](ROADMAP.md).
 
 ## What This Actually Is
 
@@ -21,25 +67,13 @@ Layer 3: SCORING ENGINE
 
 Layer 2: ENFORCEMENT
   Hooks fire every interaction (~100 tokens).
-  PreToolUse blocks source edits without tests.
+  PreToolUse reminds Claude to write tests first.
 
 Layer 1: PHILOSOPHY
   The wizard document. KISS. TDD. Confidence levels.
   Copy it, run setup, get a bespoke SDLC.
 ```
 
-## Why Someone Uses This
-
-You want Claude Code to follow engineering discipline automatically:
-- **Plan before coding** (not guess-and-check)
-- **Write tests first** (TDD enforced via hooks)
-- **State confidence** (LOW = ask user, don't guess)
-- **Track work visibly** (TaskCreate)
-- **Self-review before presenting**
-- **Prove it's better** (use native features unless you prove custom wins)
-
-The wizard auto-detects your stack (package.json, test framework, deployment targets) and generates bespoke hooks + skills + docs. CI validates the generated assets; cross-stack setup-path E2E is on the [roadmap](ROADMAP.md).
-
 ## What Makes This Different
 
 | Capability | What It Does |
@@ -48,7 +82,7 @@ The wizard auto-detects your stack (package.json, test framework, deployment tar
 | **Before/after A/B testing** | Compares wizard changes against a baseline with 95% confidence intervals to prove improvements aren't noise |
 | **SDP normalization** | Separates "the model had a bad day" from "our SDLC broke" by cross-referencing external benchmarks |
 | **CUSUM drift detection** | Catches gradual quality decay over time — borrowed from manufacturing quality control |
-| **Pre-tool TDD hooks** | Claude can't write code without writing tests first — enforced at the hook level, not just guidance |
+| **Pre-tool TDD hooks** | Before source edits, a hook reminds Claude to write tests first. CI scoring checks whether it actually followed TDD |
 | **Self-evolving loop** | Weekly/monthly external research + CI friction signals from self-heal — you approve, the system gets better |
 
 ## How It Works
@@ -79,24 +113,6 @@ CI/CD PIPELINE
   - Model-aware: SDP adjusts for external conditions
 ```
 
-## Using It
-
-**One command (recommended):**
-```bash
-npx agentic-sdlc-wizard init
-```
-
-Installs hooks, skills, settings, and the wizard doc. Then start Claude Code and tell it "Run the SDLC wizard setup" — it'll scan your project and generate bespoke CLAUDE.md, SDLC.md, TESTING.md, and ARCHITECTURE.md.
-
-**From GitHub (no npm needed):**
-```bash
-npx github:BaseInfinity/agentic-ai-sdlc-wizard init
-```
-
-**Manual:** Download `CLAUDE_CODE_SDLC_WIZARD.md` to your project and follow setup instructions inside.
-
-**Check for updates:** Ask Claude "Check if the SDLC wizard has updates" — it reads [CHANGELOG.md](CHANGELOG.md), shows what's new, and offers to apply changes (opt-in each).
-
 ## Self-Evolving System
 
 | Cadence | Source | Action |
@@ -148,7 +164,7 @@ Tests aren't just validation - they're the foundation everything else builds on.
 |--------|---------|-------|
 | `claude-md-management` | **Required** - CLAUDE.md maintenance | CLAUDE.md only |
 | `claude-code-setup` | Recommends automations | Recommendations |
-| `code-review` | PR review (optional) | PRs only |
+| `code-review` | Local self-review and PR review (optional) | Local + PRs |
 
 ## Prove It's Better
 
@@ -170,7 +186,7 @@ This isn't the only Claude Code SDLC tool. Here's an honest comparison:
 |--------|------------|----------------------|-------------|
 | **Focus** | SDLC enforcement + measurement | Agent performance optimization | Plugin marketplace |
 | **Hooks** | 3 (SDLC, TDD, instructions) | 12+ (dev blocker, prettier, etc.) | Webhook watcher |
-| **Skills** | 2 (/sdlc, /testing) | 80+ domain-specific | 13 slash commands |
+| **Skills** | 2 (/sdlc, /setup) | 80+ domain-specific | 13 slash commands |
 | **Evaluation** | 95% CI, CUSUM, SDP, Tier 1/2 | Configuration testing | skilltest framework |
 | **Self-healing** | CI auto-fix + re-trigger | No | No |
 | **Auto-updates** | Weekly CC + community scan | No | No |

package/cli/bin/sdlc-wizard.js

@@ -2,13 +2,14 @@
 'use strict';
 
 const { version } = require('../../package.json');
-const { init } = require('../init');
+const { init, check } = require('../init');
 
 const args = process.argv.slice(2);
 
 const flags = {
   force: args.includes('--force'),
   dryRun: args.includes('--dry-run'),
+  json: args.includes('--json'),
 };
 
 const command = args.find((a) => !a.startsWith('--'));
@@ -24,10 +25,12 @@ if (args.includes('--help') || args.includes('-h') || !command) {
 
   Usage:
     sdlc-wizard init [options]    Install SDLC wizard into current directory
+    sdlc-wizard check [options]   Check installation health and updates
 
   Options:
-    --force       Overwrite existing files
-    --dry-run     Preview changes without writing
+    --force       Overwrite existing files (init only)
+    --dry-run     Preview changes without writing (init only)
+    --json        Output as JSON (check only)
     --version     Show version
     --help        Show this help
   `.trim());
@@ -42,6 +45,14 @@ if (command === 'init') {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   }
+} else if (command === 'check') {
+  try {
+    const { hasDrift } = check(process.cwd(), { json: flags.json });
+    process.exit(hasDrift ? 1 : 0);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
 } else {
   console.error(`Unknown command: ${command}`);
   console.error('Run "sdlc-wizard --help" for usage.');

package/cli/init.js

@@ -1,11 +1,14 @@
 'use strict';
 
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
 const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
 const GREEN = '\x1b[32m';
 const YELLOW = '\x1b[33m';
+const MAGENTA = '\x1b[35m';
 const CYAN = '\x1b[36m';
 
 const TEMPLATES_DIR = path.join(__dirname, 'templates');
@@ -17,19 +20,86 @@ const FILES = [
   { src: 'hooks/tdd-pretool-check.sh', dest: '.claude/hooks/tdd-pretool-check.sh', executable: true },
   { src: 'hooks/instructions-loaded-check.sh', dest: '.claude/hooks/instructions-loaded-check.sh', executable: true },
   { src: 'skills/sdlc/SKILL.md', dest: '.claude/skills/sdlc/SKILL.md' },
-  { src: 'skills/testing/SKILL.md', dest: '.claude/skills/testing/SKILL.md' },
+  { src: 'skills/setup/SKILL.md', dest: '.claude/skills/setup/SKILL.md' },
+  { src: 'skills/update/SKILL.md', dest: '.claude/skills/update/SKILL.md' },
 ];
 
+const WIZARD_HOOK_MARKERS = FILES
+  .filter((f) => f.executable && f.dest.startsWith('.claude/hooks/'))
+  .map((f) => path.basename(f.src));
+
 const GITIGNORE_ENTRIES = ['.claude/plans/', '.claude/settings.local.json'];
 
+// Paths from previous versions that should be removed on upgrade
+const OBSOLETE_PATHS = [
+  '.claude/skills/testing',  // consolidated into /sdlc in v1.17.0
+];
+
+function isWizardHookEntry(hookEntry) {
+  if (!hookEntry || !hookEntry.hooks) return false;
+  return hookEntry.hooks.some((h) =>
+    WIZARD_HOOK_MARKERS.some((marker) => h.command && h.command.includes(marker))
+  );
+}
+
+function mergeSettings(existingPath, templatePath, force) {
+  try {
+    const existing = JSON.parse(fs.readFileSync(existingPath, 'utf8'));
+    const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+
+    if (!existing.hooks) existing.hooks = {};
+
+    for (const [event, templateEntries] of Object.entries(template.hooks || {})) {
+      if (!existing.hooks[event]) {
+        existing.hooks[event] = templateEntries;
+        continue;
+      }
+
+      // Each template event has exactly one hook entry
+      const templateEntry = templateEntries[0];
+      const existingIdx = existing.hooks[event].findIndex(isWizardHookEntry);
+
+      if (existingIdx === -1) {
+        existing.hooks[event].push(templateEntry);
+      } else if (force) {
+        existing.hooks[event][existingIdx] = templateEntry;
+      }
+    }
+
+    const merged = JSON.stringify(existing, null, 2) + '\n';
+    const original = fs.readFileSync(existingPath, 'utf8');
+    return merged === original ? null : merged;
+  } catch (_) {
+    return null;
+  }
+}
+
 function planOperations(targetDir, { force }) {
   const ops = [];
 
   for (const file of FILES) {
     const destPath = path.join(targetDir, file.dest);
+    const srcPath = path.join(TEMPLATES_DIR, file.src);
     const exists = fs.existsSync(destPath);
+
+    if (exists && file.dest === '.claude/settings.json') {
+      const merged = mergeSettings(destPath, srcPath, force);
+      if (merged) {
+        ops.push({
+          src: srcPath,
+          dest: destPath,
+          relativeDest: file.dest,
+          action: 'MERGE',
+          mergedContent: merged,
+          executable: false,
+        });
+        continue;
+      }
+      // Invalid JSON — fall through to normal SKIP/OVERWRITE
+    }
+
     ops.push({
-      src: path.join(TEMPLATES_DIR, file.src),
+      src: srcPath,
       dest: destPath,
       relativeDest: file.dest,
       action: exists ? (force ? 'OVERWRITE' : 'SKIP') : 'CREATE',
@@ -59,13 +129,31 @@ function executeOperations(ops) {
   for (const op of ops) {
     if (op.action === 'SKIP') continue;
     ensureDir(op.dest);
-    fs.copyFileSync(op.src, op.dest);
+    if (op.action === 'MERGE') {
+      fs.writeFileSync(op.dest, op.mergedContent);
+    } else {
+      fs.copyFileSync(op.src, op.dest);
+    }
     if (op.executable) {
       fs.chmodSync(op.dest, 0o755);
     }
   }
 }
 
+function removeObsoletePaths(targetDir, { dryRun }) {
+  const removed = [];
+  for (const rel of OBSOLETE_PATHS) {
+    const fullPath = path.join(targetDir, rel);
+    if (fs.existsSync(fullPath)) {
+      if (!dryRun) {
+        fs.rmSync(fullPath, { recursive: true, force: true });
+      }
+      removed.push(rel);
+    }
+  }
+  return removed;
+}
+
 function updateGitignore(targetDir, { dryRun }) {
   const gitignorePath = path.join(targetDir, '.gitignore');
   let content = '';
@@ -73,7 +161,8 @@ function updateGitignore(targetDir, { dryRun }) {
     content = fs.readFileSync(gitignorePath, 'utf8');
   }
 
-  const toAdd = GITIGNORE_ENTRIES.filter((entry) => !content.includes(entry));
+  const lines = content.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+  const toAdd = GITIGNORE_ENTRIES.filter((entry) => !lines.includes(entry));
   if (toAdd.length === 0) return [];
 
   if (!dryRun) {
@@ -86,7 +175,10 @@ function updateGitignore(targetDir, { dryRun }) {
 
 function printOps(ops) {
   for (const op of ops) {
-    const color = op.action === 'CREATE' ? GREEN : op.action === 'SKIP' ? YELLOW : CYAN;
+    const color = op.action === 'CREATE' ? GREEN
+      : op.action === 'SKIP' ? YELLOW
+      : op.action === 'MERGE' ? MAGENTA
+      : CYAN;
     console.log(`  ${color}${op.action}${RESET}  ${op.relativeDest}`);
   }
 }
@@ -97,6 +189,10 @@ function init(targetDir, { force = false, dryRun = false } = {}) {
   if (dryRun) {
     console.log('Dry run — no files will be written:\n');
     printOps(ops);
+    const obsolete = removeObsoletePaths(targetDir, { dryRun: true });
+    for (const p of obsolete) {
+      console.log(`  ${RED}REMOVE${RESET}  ${p} (obsolete)`);
+    }
     const gitignoreAdds = updateGitignore(targetDir, { dryRun: true });
     if (gitignoreAdds.length > 0) {
       console.log(`  ${GREEN}APPEND${RESET}  .gitignore (${gitignoreAdds.join(', ')})`);
@@ -107,7 +203,13 @@ function init(targetDir, { force = false, dryRun = false } = {}) {
   console.log('');
   printOps(ops);
 
-  if (ops.every((o) => o.action === 'SKIP')) {
+  // Always clean up obsolete paths, even when all managed files are SKIP
+  const obsolete = removeObsoletePaths(targetDir, { dryRun: false });
+  for (const p of obsolete) {
+    console.log(`  ${RED}REMOVE${RESET}  ${p} (obsolete)`);
+  }
+
+  if (ops.every((o) => o.action === 'SKIP') && obsolete.length === 0) {
     console.log('\nAll files already exist. Use --force to overwrite.');
     return true;
   }
@@ -122,10 +224,14 @@ function init(targetDir, { force = false, dryRun = false } = {}) {
   console.log(`
 ${GREEN}SDLC Wizard installed successfully!${RESET}
 
+${YELLOW}Important:${RESET} Hooks and settings load at session start.
+  If Claude Code is already running, type ${CYAN}/exit${RESET} then ${CYAN}claude${RESET} to restart.
+  (Or ${CYAN}claude --continue${RESET} to keep your conversation history.)
+
 Next steps:
-  1. Start Claude Code in this directory
-  2. Tell Claude: "Run the SDLC wizard setup"
-  3. Claude will scan your project and create CLAUDE.md, SDLC.md, TESTING.md, ARCHITECTURE.md
+  1. Start Claude Code in this directory (or restart if already running)
+  2. Tell Claude anything — setup auto-invokes when SDLC files are missing
+  3. Claude reads the wizard doc and creates CLAUDE.md, SDLC.md, TESTING.md, ARCHITECTURE.md
 
 The wizard doc is at: CLAUDE_CODE_SDLC_WIZARD.md
   `);
@@ -133,4 +239,90 @@ The wizard doc is at: CLAUDE_CODE_SDLC_WIZARD.md
   return true;
 }
 
-module.exports = { init, planOperations, GITIGNORE_ENTRIES };
+function check(targetDir, { json = false } = {}) {
+  const results = [];
+
+  for (const file of FILES) {
+    const destPath = path.join(targetDir, file.dest);
+    const srcPath = path.join(TEMPLATES_DIR, file.src);
+    results.push(checkFile(srcPath, destPath, file.dest, file.executable || false));
+  }
+
+  const wizardDest = path.join(targetDir, 'CLAUDE_CODE_SDLC_WIZARD.md');
+  results.push(checkFile(WIZARD_DOC, wizardDest, 'CLAUDE_CODE_SDLC_WIZARD.md', false));
+
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  results.push(checkGitignore(gitignorePath));
+
+  let updateInfo = null;
+  try {
+    const { execSync } = require('child_process');
+    const latest = execSync('npm view agentic-sdlc-wizard version 2>/dev/null', {
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
+    const current = require('../package.json').version;
+    if (latest !== current) {
+      updateInfo = { current, latest };
+    }
+  } catch (_) {
+    // Offline or npm unavailable — skip update check
+  }
+
+  const hasDrift = results.some((r) => r.status === 'MISSING' || r.status === 'DRIFT');
+
+  if (json) {
+    console.log(JSON.stringify({ files: results, update: updateInfo }, null, 2));
+  } else {
+    for (const r of results) {
+      const color = r.status === 'MATCH' ? GREEN : r.status === 'MISSING' ? RED : YELLOW;
+      console.log(`  ${color}${r.status}${RESET}  ${r.file}`);
+      if (r.details) console.log(`         ${r.details}`);
+    }
+    if (updateInfo) {
+      console.log(`\n  ${YELLOW}UPDATE${RESET}  v${updateInfo.current} -> v${updateInfo.latest}`);
+      console.log('         Run: npx agentic-sdlc-wizard init --force');
+    }
+  }
+
+  return { results, updateInfo, hasDrift };
+}
+
+function checkFile(srcPath, destPath, relativeDest, shouldBeExecutable) {
+  if (!fs.existsSync(destPath)) {
+    return { file: relativeDest, status: 'MISSING' };
+  }
+  const srcHash = crypto.createHash('sha256').update(fs.readFileSync(srcPath)).digest('hex');
+  const destHash = crypto.createHash('sha256').update(fs.readFileSync(destPath)).digest('hex');
+  const result = {
+    file: relativeDest,
+    status: srcHash === destHash ? 'MATCH' : 'CUSTOMIZED',
+  };
+
+  if (shouldBeExecutable) {
+    try {
+      fs.accessSync(destPath, fs.constants.X_OK);
+    } catch (_) {
+      result.status = 'DRIFT';
+      result.details = 'Missing executable permission (chmod +x)';
+    }
+  }
+
+  return result;
+}
+
+function checkGitignore(gitignorePath) {
+  if (!fs.existsSync(gitignorePath)) {
+    return { file: '.gitignore', status: 'MISSING', details: 'No .gitignore found' };
+  }
+  const lines = fs.readFileSync(gitignorePath, 'utf8').split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+  const missing = GITIGNORE_ENTRIES.filter((e) => !lines.includes(e));
+  if (missing.length > 0) {
+    return { file: '.gitignore', status: 'DRIFT', details: `Missing entries: ${missing.join(', ')}` };
+  }
+  return { file: '.gitignore', status: 'MATCH' };
+}
+
+module.exports = { init, check, planOperations, GITIGNORE_ENTRIES };

package/cli/templates/hooks/instructions-loaded-check.sh

@@ -17,7 +17,7 @@ fi
 
 if [ -n "$MISSING" ]; then
     echo "WARNING: Missing SDLC wizard files: ${MISSING}"
-    echo "Run the wizard setup to generate them."
+    echo "Invoke Skill tool, skill=\"setup-wizard\" to generate them."
 fi
 
 exit 0

package/cli/templates/hooks/sdlc-prompt-check.sh

@@ -1,6 +1,19 @@
 #!/bin/bash
 # Light SDLC hook - baseline reminder every prompt (~100 tokens)
-# Full guidance in skills: .claude/skills/sdlc/ and .claude/skills/testing/
+# Full guidance in skill: .claude/skills/sdlc/
+
+# Check if setup has been completed
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+if [ ! -s "$PROJECT_DIR/SDLC.md" ] || [ ! -s "$PROJECT_DIR/TESTING.md" ]; then
+    cat << 'SETUP'
+SETUP NOT COMPLETE: SDLC.md and/or TESTING.md are missing.
+
+MANDATORY FIRST ACTION: Invoke Skill tool, skill="setup-wizard"
+Do NOT proceed with any other task until setup is complete.
+Tell the user: "I need to run the SDLC setup wizard first to configure your project."
+SETUP
+    exit 0
+fi
 
 cat << 'EOF'
 SDLC BASELINE:
@@ -10,10 +23,8 @@ SDLC BASELINE:
 4. FAILED 2x? STOP and ASK USER
 5. ALL TESTS MUST PASS BEFORE COMMIT - NO EXCEPTIONS
 
-AUTO-INVOKE SKILLS (Claude MUST do this FIRST):
-- implement/fix/refactor/feature/bug/build → Invoke: Skill tool, skill="sdlc"
-- test/TDD/write test (standalone) → Invoke: Skill tool, skill="testing"
-- If BOTH match (e.g., "fix the test") → sdlc takes precedence (includes TDD)
+AUTO-INVOKE SKILL (Claude MUST do this FIRST):
+- implement/fix/refactor/feature/bug/build/test/TDD → Invoke: Skill tool, skill="sdlc"
 - DON'T invoke for: questions, explanations, reading/exploring code, simple queries
 - DON'T wait for user to type /sdlc - AUTO-INVOKE based on task type