agentic-sdlc-wizard 1.15.0

package/README.md

@@ -0,0 +1,199 @@
+# 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.
+
+## What This Actually Is
+
+Five layers working together:
+
+```
+Layer 5: SELF-IMPROVEMENT
+  Weekly/monthly workflows detect changes, test them
+  statistically, create PRs. Baselines evolve organically.
+
+Layer 4: STATISTICAL VALIDATION
+  E2E scoring with 95% CI (5 trials, t-distribution).
+  SDP normalizes for model quality. CUSUM catches drift.
+
+Layer 3: SCORING ENGINE
+  7 criteria, 10/11 points. Claude evaluates Claude.
+  Before/after wizard A/B comparison in CI.
+
+Layer 2: ENFORCEMENT
+  Hooks fire every interaction (~100 tokens).
+  PreToolUse blocks source edits without tests.
+
+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 |
+|---|---|
+| **E2E scoring in CI** | Every PR gets an automated SDLC compliance score (0-10) — measures whether Claude actually planned, tested, and reviewed |
+| **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 |
+| **Self-evolving loop** | Weekly/monthly external research + CI friction signals from self-heal — you approve, the system gets better |
+
+## How It Works
+
+**Think Iron Man:** Jarvis is nothing without Tony Stark. Tony Stark is still Tony Stark. But together? They make Iron Man. This SDLC is your suit - you build it over time, improve it for your needs, and it makes you both better.
+
+**The dream:** Mold an ever-evolving SDLC to your needs. Replace my components with native Claude Code features as they ship — and one day, delete this repo entirely because Claude Code has them all built in. That's the goal.
+
+```
+WIZARD FILE (CLAUDE_CODE_SDLC_WIZARD.md)
+  - Setup guide, used once
+  - Lives on GitHub, fetched when needed
+        |
+        | generates
+        v
+GENERATED FILES (in your repo)
+  - .claude/hooks/*.sh
+  - .claude/skills/*/SKILL.md
+  - .claude/settings.json
+  - CLAUDE.md, SDLC.md, TESTING.md, ARCHITECTURE.md
+        |
+        | validated by
+        v
+CI/CD PIPELINE
+  - E2E: simulate SDLC task -> score 0-10
+  - Before/after: main vs PR wizard
+  - Statistical: 5x trials, 95% CI
+  - 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 |
+|---------|--------|--------|
+| Weekly | Claude Code releases | PR with analysis + E2E test |
+| Weekly | Community (Reddit, HN) | Issue digest |
+| Monthly | Deep research, papers | Trend report |
+
+Every update: regression tested -> AI reviewed -> human approved.
+
+## E2E Scoring
+
+Like evaluating scientific method adherence - we measure **process compliance**:
+
+| Criterion | Points | Type |
+|-----------|--------|------|
+| TodoWrite/TaskCreate | 1 | Deterministic |
+| Confidence stated | 1 | Deterministic |
+| Plan mode | 2 | AI-judge |
+| TDD RED | 2 | Deterministic |
+| TDD GREEN | 2 | AI-judge |
+| Self-review | 1 | AI-judge |
+| Clean code | 1 | AI-judge |
+
+40% deterministic + 60% AI-judged. 5 trials handle variance.
+
+## Model-Adjusted Scoring (SDP)
+
+| Metric | Meaning |
+|--------|---------|
+| **Raw** | Actual score (Layer 2: SDLC compliance) |
+| **SDP** | Adjusted for model conditions |
+| **Robustness** | How well SDLC holds up vs model changes |
+
+- **Robustness < 1.0** = SDLC is resilient (good!)
+- **Robustness > 1.0** = SDLC is sensitive (investigate)
+
+## Tests Are The Building Blocks
+
+Tests aren't just validation - they're the foundation everything else builds on.
+
+- **Tests >= App Code** - Critique tests as hard (or harder) than implementation
+- **Tests prove correctness** - Without them, you're just hoping
+- **Tests enable fearless change** - Refactor confidently
+
+## Official Plugin Integration
+
+| Plugin | Purpose | Scope |
+|--------|---------|-------|
+| `claude-md-management` | **Required** - CLAUDE.md maintenance | CLAUDE.md only |
+| `claude-code-setup` | Recommends automations | Recommendations |
+| `code-review` | PR review (optional) | PRs only |
+
+## Prove It's Better
+
+Don't reinvent the wheel. Use native/built-in features UNLESS you prove your custom version is better. If you can't prove it, delete yours.
+
+1. Test the native solution — measure quality, speed, reliability
+2. Test your custom solution — same scenario, same metrics
+3. Compare side-by-side
+4. Native >= custom? **Use native. Delete yours.**
+5. Custom > native? **Keep yours. Document WHY.** Re-evaluate when native improves.
+
+This applies to everything: native commands vs custom skills, framework utilities vs hand-rolled code, library functions vs custom implementations.
+
+## How This Compares
+
+This isn't the only Claude Code SDLC tool. Here's an honest comparison:
+
+| Aspect | SDLC Wizard | everything-claude-code | claude-sdlc |
+|--------|------------|----------------------|-------------|
+| **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 |
+| **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 |
+| **Install** | `npx agentic-sdlc-wizard init` | npm install | npm install |
+| **Philosophy** | Lightweight, prove-it-or-delete | Scale and optimization | Documentation-first |
+
+**Our unique strengths:** Statistical rigor (CUSUM + 95% CI), SDP scoring (model quality vs SDLC compliance), self-healing CI, Prove-It A/B pipeline, comprehensive automated test suite, dogfooding enforcement.
+
+**Where others are stronger:** everything-claude-code has broader language/framework coverage. claude-sdlc has webhook-driven automation. Both have npm distribution.
+
+**The spirit:** Open source — we learn from each other. See [COMPETITIVE_AUDIT.md](COMPETITIVE_AUDIT.md) for details.
+
+## Documentation
+
+| Document | What It Covers |
+|----------|---------------|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System design, 5-layer diagram, data flows, file structure |
+| [CI_CD.md](CI_CD.md) | All 5 workflows, E2E scoring, tier system, SDP, integrity checks |
+| [SDLC.md](SDLC.md) | Version tracking, enforcement rules, SDLC configuration |
+| [TESTING.md](TESTING.md) | Testing philosophy, test diamond, TDD approach |
+| [CHANGELOG.md](CHANGELOG.md) | Version history, what changed and when |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute, evaluation methodology |
+
+## Contributing
+
+PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for evaluation methodology and testing.

package/cli/bin/sdlc-wizard.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+
+const { version } = require('../../package.json');
+const { init } = require('../init');
+
+const args = process.argv.slice(2);
+
+const flags = {
+  force: args.includes('--force'),
+  dryRun: args.includes('--dry-run'),
+};
+
+const command = args.find((a) => !a.startsWith('--'));
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(version);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h') || !command) {
+  console.log(`
+  agentic-sdlc-wizard v${version}
+
+  Usage:
+    sdlc-wizard init [options]    Install SDLC wizard into current directory
+
+  Options:
+    --force       Overwrite existing files
+    --dry-run     Preview changes without writing
+    --version     Show version
+    --help        Show this help
+  `.trim());
+  process.exit(0);
+}
+
+if (command === 'init') {
+  try {
+    init(process.cwd(), flags);
+    process.exit(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.');
+  process.exit(1);
+}

package/cli/init.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+
+const TEMPLATES_DIR = path.join(__dirname, 'templates');
+const WIZARD_DOC = path.join(__dirname, '..', 'CLAUDE_CODE_SDLC_WIZARD.md');
+
+const FILES = [
+  { src: 'settings.json', dest: '.claude/settings.json' },
+  { src: 'hooks/sdlc-prompt-check.sh', dest: '.claude/hooks/sdlc-prompt-check.sh', executable: true },
+  { 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' },
+];
+
+const GITIGNORE_ENTRIES = ['.claude/plans/', '.claude/settings.local.json'];
+
+function planOperations(targetDir, { force }) {
+  const ops = [];
+
+  for (const file of FILES) {
+    const destPath = path.join(targetDir, file.dest);
+    const exists = fs.existsSync(destPath);
+    ops.push({
+      src: path.join(TEMPLATES_DIR, file.src),
+      dest: destPath,
+      relativeDest: file.dest,
+      action: exists ? (force ? 'OVERWRITE' : 'SKIP') : 'CREATE',
+      executable: file.executable || false,
+    });
+  }
+
+  // Wizard doc
+  const wizardDest = path.join(targetDir, 'CLAUDE_CODE_SDLC_WIZARD.md');
+  const wizardExists = fs.existsSync(wizardDest);
+  ops.push({
+    src: WIZARD_DOC,
+    dest: wizardDest,
+    relativeDest: 'CLAUDE_CODE_SDLC_WIZARD.md',
+    action: wizardExists ? (force ? 'OVERWRITE' : 'SKIP') : 'CREATE',
+    executable: false,
+  });
+
+  return ops;
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function executeOperations(ops) {
+  for (const op of ops) {
+    if (op.action === 'SKIP') continue;
+    ensureDir(op.dest);
+    fs.copyFileSync(op.src, op.dest);
+    if (op.executable) {
+      fs.chmodSync(op.dest, 0o755);
+    }
+  }
+}
+
+function updateGitignore(targetDir, { dryRun }) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf8');
+  }
+
+  const toAdd = GITIGNORE_ENTRIES.filter((entry) => !content.includes(entry));
+  if (toAdd.length === 0) return [];
+
+  if (!dryRun) {
+    const suffix = (content && !content.endsWith('\n') ? '\n' : '') + toAdd.join('\n') + '\n';
+    fs.appendFileSync(gitignorePath, suffix);
+  }
+
+  return toAdd;
+}
+
+function printOps(ops) {
+  for (const op of ops) {
+    const color = op.action === 'CREATE' ? GREEN : op.action === 'SKIP' ? YELLOW : CYAN;
+    console.log(`  ${color}${op.action}${RESET}  ${op.relativeDest}`);
+  }
+}
+
+function init(targetDir, { force = false, dryRun = false } = {}) {
+  const ops = planOperations(targetDir, { force });
+
+  if (dryRun) {
+    console.log('Dry run — no files will be written:\n');
+    printOps(ops);
+    const gitignoreAdds = updateGitignore(targetDir, { dryRun: true });
+    if (gitignoreAdds.length > 0) {
+      console.log(`  ${GREEN}APPEND${RESET}  .gitignore (${gitignoreAdds.join(', ')})`);
+    }
+    return true;
+  }
+
+  console.log('');
+  printOps(ops);
+
+  if (ops.every((o) => o.action === 'SKIP')) {
+    console.log('\nAll files already exist. Use --force to overwrite.');
+    return true;
+  }
+
+  executeOperations(ops);
+
+  const gitignoreAdds = updateGitignore(targetDir, { dryRun: false });
+  if (gitignoreAdds.length > 0) {
+    console.log(`  ${GREEN}APPEND${RESET}  .gitignore (${gitignoreAdds.join(', ')})`);
+  }
+
+  console.log(`
+${GREEN}SDLC Wizard installed successfully!${RESET}
+
+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
+
+The wizard doc is at: CLAUDE_CODE_SDLC_WIZARD.md
+  `);
+
+  return true;
+}
+
+module.exports = { init, planOperations, GITIGNORE_ENTRIES };

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

@@ -0,0 +1,23 @@
+#!/bin/bash
+# InstructionsLoaded hook - validates SDLC files exist at session start
+# Fires when Claude loads instructions (session start/resume)
+# Available since Claude Code v2.1.69
+# Note: no set -e — this hook must always exit 0 to not block session start
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+MISSING=""
+
+if [ ! -f "$PROJECT_DIR/SDLC.md" ]; then
+    MISSING="${MISSING:+${MISSING}, }SDLC.md"
+fi
+
+if [ ! -f "$PROJECT_DIR/TESTING.md" ]; then
+    MISSING="${MISSING:+${MISSING}, }TESTING.md"
+fi
+
+if [ -n "$MISSING" ]; then
+    echo "WARNING: Missing SDLC wizard files: ${MISSING}"
+    echo "Run the wizard setup to generate them."
+fi
+
+exit 0

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

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Light SDLC hook - baseline reminder every prompt (~100 tokens)
+# Full guidance in skills: .claude/skills/sdlc/ and .claude/skills/testing/
+
+cat << 'EOF'
+SDLC BASELINE:
+1. TodoWrite FIRST (plan tasks before coding)
+2. STATE CONFIDENCE: HIGH/MEDIUM/LOW
+3. LOW confidence? ASK USER before proceeding
+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)
+- 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
+
+Workflow phases:
+1. Plan Mode (research) → Present approach + confidence
+2. Transition (update docs) → Request /compact
+3. Implementation (TDD after compact)
+4. SELF-REVIEW (/code-review) → BEFORE presenting to user
+
+Quick refs: SDLC.md | TESTING.md | *_PLAN.md for feature
+EOF

package/cli/templates/hooks/tdd-pretool-check.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# PreToolUse hook - TDD enforcement before editing source files
+# Fires before Write/Edit/MultiEdit tools
+
+# Read the tool input (JSON with file_path, content, etc.)
+TOOL_INPUT=$(cat)
+
+# Extract the file path being edited (requires jq)
+FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.tool_input.file_path // empty')
+
+# CUSTOMIZE: Change this pattern to match YOUR source directory
+# Examples: "/src/", "/app/", "/lib/", "/packages/", "/server/"
+if [[ "$FILE_PATH" == *"/src/"* ]]; then
+  # Output additionalContext that Claude will read
+  cat << 'EOF'
+{"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": "TDD CHECK: Are you writing IMPLEMENTATION before a FAILING TEST? If yes, STOP. Write the test first (TDD RED), then implement (TDD GREEN)."}}
+EOF
+fi
+
+# No output = allow the tool to proceed

package/cli/templates/settings.json

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sdlc-prompt-check.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tdd-pretool-check.sh"
+          }
+        ]
+      }
+    ],
+    "InstructionsLoaded": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/instructions-loaded-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}