claudex-setup 1.15.1 → 1.16.0

package/README.md

@@ -51,6 +51,8 @@ Tested on 4 real projects — not demos:
 
 Most common gaps found: missing secrets protection, no deny rules, no mermaid diagram, no hooks in settings.
 
+> Scores measured with claudex-setup@1.10.3 on 2026-04-03. Full case studies: [VTCLE](https://github.com/DnaFin/claudex/blob/main/research/case-study-vtcle-2026-04-03.md) | [Social](https://github.com/DnaFin/claudex/blob/main/research/case-study-social-2026-04-03.md) | [Polymiro](https://github.com/DnaFin/claudex/blob/main/research/case-study-polymiro-2026-04-03.md)
+
 ## What You Get
 
 ```
@@ -259,7 +261,7 @@ If you are using `npx` only, copy the same file from the GitHub repo at `content
 
 The skill runs `npx claudex-setup --json`, summarizes the score, shows the top next actions, and points to the right next command without applying changes.
 
-## 62 Checks Across 14 Categories
+## 84 Checks Across 14 Categories
 
 The exact applicable count can be lower on a given repo because stack-specific checks are skipped when they do not apply.
 
@@ -268,30 +270,30 @@ The exact applicable count can be lower on a given repo because stack-specific c
 | Memory | 8 | CLAUDE.md, architecture, conventions |
 | Quality | 7 | verification loops, self-correction |
 | Git Safety | 5 | hooks, force-push protection |
-| Workflow | 6 | commands, skills, rules, agents |
-| Security | 5 | permissions, secrets, deny rules |
+| Workflow | 8 | commands, skills, rules, agents |
+| Security | 6 | permissions, secrets, deny rules |
 | Automation | 5 | PreToolUse, PostToolUse, SessionStart |
 | Design | 4 | Mermaid, XML tags, structured prompts |
-| DevOps | 4 | Docker, CI, Terraform, K8s |
-| Hygiene | 6 | .gitignore, cleanup, structure |
+| DevOps | 6 | Docker, CI, Terraform, K8s, pipelines |
+| Hygiene | 7 | .gitignore, cleanup, structure |
 | Performance | 3 | context management, compaction |
 | MCP | 3 | servers, Context7, integrations |
-| Prompting | 3 | constraints, validation, patterns |
-| Features | 2 | /security-review, Channels |
-| **Quality Deep** | **9** | **freshness, contradictions, deprecated patterns, maxTurns, $ARGUMENTS** |
+| Prompting | 5 | constraints, validation, patterns, style |
+| Features | 3 | /security-review, Channels, modern features |
+| **Quality Deep** | **14** | **freshness, contradictions, deprecated patterns, maxTurns, $ARGUMENTS, hook specificity** |
 
 ## Stack Detection
 
-Auto-detects and tailors output for 22 stacks:
+Auto-detects and tailors output for 30 stacks:
 
 | | |
 |--|--|
-| **Frontend** | React, Vue, Angular, Next.js, Svelte |
-| **Backend** | Node.js, Python, Django, FastAPI |
-| **Mobile** | Flutter, Swift, Kotlin |
-| **Systems** | Rust, Go, Java, Ruby, C++, Bazel |
+| **Frontend** | React, Vue, Angular, Next.js, Svelte, Astro |
+| **Backend** | Node.js, Python, Django, FastAPI, Express, NestJS, Spring Boot |
+| **Mobile** | React Native, Expo, Flutter, Swift, Kotlin |
+| **Systems** | Rust, Go, Java, Ruby, C++, Bazel, Deno, Bun |
 | **Language** | TypeScript |
-| **Infra** | Docker, Terraform, Kubernetes |
+| **Infra** | Docker, Terraform, Kubernetes, Wrangler |
 
 ## GitHub Action
 
@@ -305,7 +307,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.14.0
+      - uses: DnaFin/claudex-setup@v1.15.1
         with:
           threshold: 50
 ```

package/bin/cli.js

@@ -19,7 +19,7 @@ const COMMAND_ALIASES = {
   suggest: 'suggest-only',
   gov: 'governance',
 };
-const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -63,6 +63,7 @@ function parseArgs(rawArgs) {
   let mcpPacks = [];
   let requireChecks = [];
   let commandSet = false;
+  let extraArgs = [];
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
@@ -126,12 +127,14 @@ function parseArgs(rawArgs) {
     if (!commandSet) {
       command = arg;
       commandSet = true;
+    } else {
+      extraArgs.push(arg);
     }
   }
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, extraArgs };
 }
 
 const HELP = `
@@ -155,6 +158,9 @@ const HELP = `
     npx claudex-setup compare          Compare latest vs previous snapshot
     npx claudex-setup trend --out r.md Export trend report as markdown
 
+  Multi-repo:
+    npx claudex-setup scan dir1 dir2   Compare multiple repos side-by-side
+
   Advanced:
     npx claudex-setup governance       Permission profiles, hooks, policy packs
     npx claudex-setup benchmark        Before/after in isolated temp copy
@@ -249,7 +255,7 @@ async function main() {
     process.exit(1);
   }
 
-  if (options.require && normalizedCommand !== 'audit' && !['audit', 'discover'].includes(command)) {
+  if (options.require && options.require.length > 0 && normalizedCommand !== 'audit' && !['audit', 'discover'].includes(command)) {
     console.error(`\n  Warning: --require is only supported with the audit command. Ignoring for '${normalizedCommand}'.\n`);
   }
 
@@ -279,7 +285,74 @@ async function main() {
   }
 
   try {
-    if (normalizedCommand === 'history') {
+    if (normalizedCommand === 'scan') {
+      const scanDirs = parsed.extraArgs;
+      if (scanDirs.length === 0) {
+        console.error('\n  Error: scan requires at least one directory argument.');
+        console.error('  Usage: npx claudex-setup scan dir1 dir2 dir3\n');
+        process.exit(1);
+      }
+      const fs = require('fs');
+      const pathMod = require('path');
+      const rows = [];
+      for (const rawDir of scanDirs) {
+        const dir = pathMod.resolve(rawDir);
+        if (!fs.existsSync(dir)) {
+          rows.push({ name: pathMod.basename(rawDir), dir: rawDir, score: null, passed: '-', failed: '-', suggested: '-', error: 'directory not found' });
+          continue;
+        }
+        try {
+          const result = await audit({ dir, silent: true });
+          rows.push({
+            name: pathMod.basename(dir),
+            dir: rawDir,
+            score: result.score,
+            passed: result.passed,
+            failed: result.failed,
+            suggested: result.suggestedNextCommand || '-',
+            error: null,
+          });
+        } catch (err) {
+          rows.push({ name: pathMod.basename(dir), dir: rawDir, score: null, passed: '-', failed: '-', suggested: '-', error: err.message });
+        }
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify(rows, null, 2));
+      } else {
+        // Find weakest
+        const validRows = rows.filter(r => r.score !== null);
+        const minScore = validRows.length > 0 ? Math.min(...validRows.map(r => r.score)) : null;
+        const weakest = validRows.length > 1 && validRows.filter(r => r.score > minScore).length > 0
+          ? validRows.find(r => r.score === minScore)
+          : null;
+
+        console.log('');
+        console.log('\x1b[1m  claudex-setup multi-repo scan\x1b[0m');
+        console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
+        console.log('');
+
+        // Table header
+        const nameW = Math.max(8, ...rows.map(r => r.name.length)) + 2;
+        const header = `  ${'Project'.padEnd(nameW)} ${'Score'.padStart(5)}  ${'Pass'.padStart(4)}  ${'Fail'.padStart(4)}  Suggested Command`;
+        console.log('\x1b[1m' + header + '\x1b[0m');
+        console.log('  ' + '─'.repeat(header.trim().length));
+
+        for (const row of rows) {
+          if (row.error) {
+            console.log(`  ${row.name.padEnd(nameW)} \x1b[31m${('ERR').padStart(5)}\x1b[0m  ${String(row.passed).padStart(4)}  ${String(row.failed).padStart(4)}  ${row.error}`);
+            continue;
+          }
+          const isWeak = weakest && row.name === weakest.name && row.dir === weakest.dir;
+          const scoreColor = row.score >= 70 ? '\x1b[32m' : row.score >= 40 ? '\x1b[33m' : '\x1b[31m';
+          const prefix = isWeak ? '\x1b[31m⚠ ' : '  ';
+          const suffix = isWeak ? ' ← weakest\x1b[0m' : '';
+          console.log(`${prefix}${row.name.padEnd(nameW)} ${scoreColor}${String(row.score).padStart(5)}\x1b[0m  ${String(row.passed).padStart(4)}  ${String(row.failed).padStart(4)}  ${row.suggested}${suffix}`);
+        }
+        console.log('');
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'history') {
       const { formatHistory } = require('../src/activity');
       console.log('');
       console.log(formatHistory(options.dir));

package/content/launch-posts.md

@@ -5,16 +5,14 @@
 **Title:** I built a tool that audits your project for Claude Code optimization — scores you 0-100
 
 **Body:**
-After cataloging 1,107 Claude Code entries and verifying 948 of them with evidence, I built a CLI that checks if your project is actually set up to get the most out of Claude Code.
+After cataloging 1,107 Claude Code entries and verifying 948 of them with evidence, I built a CLI that checks if your project is actually set up to get the most out of Claude Code. It runs 84 checks across CLAUDE.md, hooks, commands, agents, diagrams, and more.
 
-Most projects score around 10-20/100. After running setup, they jump to 70+.
+I tested it on 4 real repos. A FastAPI marketing engine went from 46 to 64. A React Native social app went from 40 to 48. A Polymiro project jumped from 35 to 48. The CLAUDEX catalog repo itself: 62 to 90.
 
 ```
 npx claudex-setup
 ```
 
-It checks for: CLAUDE.md, hooks, custom commands, skills, agents, Mermaid diagrams, XML tags, path rules, MCP config, permissions, and more.
-
 Then `npx claudex-setup setup` auto-creates everything that's missing, tailored to your stack (React, Python, TypeScript, etc).
 
 Zero dependencies. No API keys. Runs entirely local.
@@ -38,7 +36,8 @@ Turns out most projects are missing basic stuff that makes a huge difference:
 - No custom commands (repeating the same prompts manually)
 - No Mermaid diagrams (wasting 73% more tokens on prose descriptions)
 
-Built a quick checker:
+I tested 4 real repos with 84 checks. Before optimization: scores ranged from 35 to 62. After: 48 to 90. A VTCLE FastAPI project jumped from 46→64 just from adding missing hooks and commands.
+
 ```
 npx claudex-setup
 ```
@@ -54,7 +53,7 @@ Free, open source, zero dependencies: https://github.com/DnaFin/claudex-setup
 **Title:** 1,107 Claude Code Entries: What I Learned Building the Most Comprehensive Catalog
 
 **Body (excerpt):**
-I set out to catalog every single Claude Code capability, technique, and best practice. After repeated research cycles, I have 1,107 entries — 948 verified with real evidence.
+I set out to catalog every single Claude Code capability, technique, and best practice. After repeated research cycles, I have 1,107 entries — 948 verified with real evidence. I packaged this into an 84-check CLI audit and tested it on 4 real projects — scores before optimization ranged from 35 to 62, and after: 48 to 90.
 
 Here are the top 10 things most developers are missing:
 
@@ -94,7 +93,7 @@ I cataloged 1,107 Claude Code entries and verified 948 of them with evidence.
 
 Most projects use less than 5% of what Claude Code can do.
 
-Here's a free tool that checks your project and tells you exactly what's missing:
+Tested on 4 real repos — a React Native app scored 40, a FastAPI engine scored 46. After auto-setup: 48 and 64. Here's the free 84-check audit:
 
 npx claudex-setup
 
@@ -148,9 +147,9 @@ https://github.com/DnaFin/claudex-setup
 **Body:**
 I built a CLI tool that scores your project against Claude Code best practices.
 
-After researching 1,107 entries (948 verified with evidence), most projects score 10-20 out of 100 because they're missing basic optimizations like CLAUDE.md files, hooks, custom commands, and architecture diagrams.
+After researching 1,107 entries (948 verified with evidence), I tested 4 real repos with 84 checks. Scores before optimization: 35–62. After auto-setup: 48–90. The biggest jump was a research catalog repo going from 62 to 90.
 
-npx claudex-setup → audit (0-100 score)
+npx claudex-setup → audit (84 checks, 0-100 score)
 npx claudex-setup setup → auto-fix
 
 Detects your stack (React, Python, TS, Rust, Go, etc) and tailors recommendations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Score your repo's Claude Code setup against 84 checks. See gaps, apply fixes selectively with rollback, govern hooks and permissions, and benchmark impact — without breaking existing config.",
   "main": "src/index.js",
   "bin": {
@@ -16,7 +16,10 @@
   "scripts": {
     "start": "node bin/cli.js",
     "build": "npm pack --dry-run",
-    "test": "node test/run.js"
+    "test": "node test/run.js",
+    "test:jest": "jest",
+    "test:coverage": "jest --coverage",
+    "test:all": "node test/run.js && node test/check-matrix.js && node test/golden-matrix.js && node test/security-tests.js && jest"
   },
   "keywords": [
     "claude",
@@ -42,5 +45,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
   }
 }

package/src/activity.js

@@ -140,6 +140,14 @@ function updateSnapshotIndex(snapshotDir, record) {
   fs.writeFileSync(indexPath, JSON.stringify(entries, null, 2), 'utf8');
 }
 
+/**
+ * Write a normalized snapshot artifact to .claude/claudex-setup/snapshots/ and update the index.
+ * @param {string} dir - Project root directory.
+ * @param {string} snapshotKind - Snapshot type ('audit', 'benchmark', 'governance', 'augment', 'suggest-only').
+ * @param {Object} payload - Full result payload to persist.
+ * @param {Object} [meta={}] - Optional metadata fields merged into the envelope.
+ * @returns {Object} Artifact record with id, filePath, relativePath, indexPath, and summary.
+ */
 function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
   const id = timestampId();
   const { snapshotDir } = ensureArtifactDirs(dir);
@@ -189,6 +197,12 @@ function readSnapshotIndex(dir) {
   }
 }
 
+/**
+ * Get the audit score history from saved snapshots, most recent first.
+ * @param {string} dir - Project root directory.
+ * @param {number} [limit=20] - Maximum number of entries to return.
+ * @returns {Object[]} Array of snapshot index entries for audit snapshots.
+ */
 function getHistory(dir, limit = 20) {
   const entries = readSnapshotIndex(dir);
   return entries
@@ -197,6 +211,11 @@ function getHistory(dir, limit = 20) {
     .slice(0, limit);
 }
 
+/**
+ * Compare the two most recent audit snapshots and return the delta.
+ * @param {string} dir - Project root directory.
+ * @returns {Object|null} Comparison with current/previous scores, delta, regressions, improvements, and trend. Null if fewer than 2 snapshots.
+ */
 function compareLatest(dir) {
   const audits = getHistory(dir, 2);
   if (audits.length < 2) return null;

package/src/analyze.js

@@ -308,6 +308,13 @@ function buildRolloutOrder(report) {
   return steps;
 }
 
+/**
+ * Analyze a project's Claude Code setup and produce a structured recommendation report.
+ * @param {Object} options - Analysis options.
+ * @param {string} options.dir - Project directory to analyze.
+ * @param {string} [options.mode='augment'] - Analysis mode ('augment' or 'suggest-only').
+ * @returns {Promise<Object>} Structured report with project summary, gaps, strengths, and recommendations.
+ */
 async function analyzeProject(options) {
   const mode = options.mode || 'augment';
   const ctx = new ProjectContext(options.dir);
@@ -472,6 +479,11 @@ function printAnalysis(report, options = {}) {
   }
 }
 
+/**
+ * Export an analysis report as a formatted markdown string.
+ * @param {Object} report - The report object returned by analyzeProject().
+ * @returns {string} Markdown-formatted report content.
+ */
 function exportMarkdown(report) {
   const lines = [];
   lines.push(`# Claudex Setup Analysis Report`);

package/src/audit.js

@@ -179,6 +179,16 @@ function printLiteAudit(result, dir) {
   console.log('');
 }
 
+/**
+ * Run a full audit of a project's Claude Code setup against the CLAUDEX technique database.
+ * @param {Object} options - Audit options.
+ * @param {string} options.dir - Project directory to audit.
+ * @param {boolean} [options.silent] - Skip all console output, return result only.
+ * @param {boolean} [options.json] - Output result as JSON.
+ * @param {boolean} [options.lite] - Show short top-3 quick scan.
+ * @param {boolean} [options.verbose] - Show all recommendations including medium-impact.
+ * @returns {Promise<Object>} Audit result with score, passed/failed counts, quickWins, and topNextActions.
+ */
 async function audit(options) {
   const silent = options.silent || false;
   const ctx = new ProjectContext(options.dir);

package/src/benchmark.js

@@ -114,6 +114,21 @@ function buildExecutiveSummary(before, after, workflowEvidence) {
   };
 }
 
+function buildPracticalValue(before, after, applyResult) {
+  const written = applyResult.writtenFiles || [];
+  return {
+    denyRulesAdded: written.includes('.claude/settings.json') ? 'yes' : 'no',
+    hooksCreated: written.filter(f => f.includes('hooks/')).length,
+    commandsCreated: written.filter(f => f.includes('commands/')).length,
+    agentsCreated: written.filter(f => f.includes('agents/')).length,
+    skillsCreated: written.filter(f => f.includes('skills/')).length,
+    rulesCreated: written.filter(f => f.includes('rules/')).length,
+    claudeMdCreated: written.includes('CLAUDE.md') ? 'yes' : 'no',
+    totalFilesCreated: written.length,
+    totalFilesPreserved: (applyResult.preservedFiles || []).length,
+  };
+}
+
 function buildCaseStudy(before, after, applyResult) {
   return {
     initialState: `Baseline score ${before.score}/100, organic ${before.organicScore}/100.`,
@@ -125,6 +140,7 @@ function buildCaseStudy(before, after, applyResult) {
       organicDelta: after.organicScore - before.organicScore,
       passedDelta: after.passed - before.passed,
     },
+    practicalValue: buildPracticalValue(before, after, applyResult),
   };
 }
 
@@ -172,6 +188,14 @@ function renderBenchmarkMarkdown(report) {
   ].join('\n');
 }
 
+/**
+ * Run a before/after benchmark on an isolated copy of the project.
+ * @param {Object} options - Benchmark options.
+ * @param {string} options.dir - Project directory to benchmark.
+ * @param {string} [options.profile] - Permission profile to use during setup.
+ * @param {string[]} [options.mcpPacks] - MCP pack keys to include in setup.
+ * @returns {Promise<Object>} Benchmark report with before/after scores, delta, and workflow evidence.
+ */
 async function runBenchmark(options) {
   const before = await audit({ dir: options.dir, silent: true });
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'claudex-benchmark-'));

package/src/context.js

@@ -5,6 +5,10 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Scans and caches project files to provide fast lookups for technique checks.
+ * Reads the project directory on construction and exposes helpers for file content, JSON, and stack detection.
+ */
 class ProjectContext {
   constructor(dir) {
     this.dir = dir;
@@ -67,10 +71,19 @@ class ProjectContext {
     }
   }
 
+  /**
+   * Return the contents of the project's CLAUDE.md (root or .claude/ location).
+   * @returns {string|null} File content or null if not found.
+   */
   claudeMdContent() {
     return this.fileContent('CLAUDE.md') || this.fileContent('.claude/CLAUDE.md');
   }
 
+  /**
+   * Read and cache the content of a file relative to the project root.
+   * @param {string} filePath - Relative path from the project root.
+   * @returns {string|null} File content or null if not readable.
+   */
   fileContent(filePath) {
     if (this._cache[filePath] !== undefined) return this._cache[filePath];
     const fullPath = path.join(this.dir, filePath);

package/src/governance.js

@@ -332,6 +332,10 @@ function buildSettingsForProfile({ profileKey = 'safe-write', hookFiles = [], ex
   return base;
 }
 
+/**
+ * Return the full governance surface: permission profiles, hooks, policy packs, and pilot kit.
+ * @returns {Object} Summary containing permissionProfiles, hookRegistry, policyPacks, domainPacks, mcpPacks, and pilotRolloutKit.
+ */
 function getGovernanceSummary() {
   return {
     permissionProfiles: PERMISSION_PROFILES,
@@ -396,6 +400,11 @@ function printGovernanceSummary(summary, options = {}) {
   console.log('');
 }
 
+/**
+ * Render a governance summary as a formatted markdown string.
+ * @param {Object} summary - The summary object returned by getGovernanceSummary().
+ * @returns {string} Markdown-formatted governance report.
+ */
 function renderGovernanceMarkdown(summary) {
   const lines = [
     '# Claudex Setup Governance Report',

package/src/interactive.js

@@ -98,7 +98,14 @@ async function interactive(options) {
   }
 
   console.log('');
-  console.log(c(`  Applying ${toFix.length} fixes...`, 'bold'));
+  console.log(c('  ── Summary ──', 'magenta'));
+  console.log(`  Selected ${c(String(toFix.length), 'bold')} improvements to apply:`);
+  for (const key of toFix) {
+    const item = results.find(r => r.key === key);
+    console.log(c(`    • ${item ? item.name : key}`, 'dim'));
+  }
+  console.log('');
+  console.log(c(`  Applying...`, 'bold'));
   console.log('');
 
   // Run setup in auto mode

package/src/techniques.js

@@ -1295,6 +1295,24 @@ const TECHNIQUES = {
     fix: 'CLAUDE.md references deprecated patterns (old model names or API formats). Update to current Claude 4.x conventions.',
     template: null
   },
+
+  claudeMdQuality: {
+    id: 102502,
+    name: 'CLAUDE.md has substantive content',
+    check: (ctx) => {
+      const md = ctx.claudeMdContent();
+      if (!md) return null;
+      const lines = md.split('\n').filter(l => l.trim());
+      const sections = (md.match(/^##\s/gm) || []).length;
+      const hasCommand = /\b(npm|yarn|pnpm|pytest|go |make |ruff |cargo |dotnet )\b/i.test(md);
+      return lines.length >= 15 && sections >= 2 && hasCommand;
+    },
+    impact: 'medium',
+    rating: 4,
+    category: 'quality-deep',
+    fix: 'CLAUDE.md exists but lacks substance. Add at least 2 sections (## headings) and include your test/build/lint commands.',
+    template: null
+  },
 };
 
 // Stack detection