claudex-setup 0.3.2 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # claudex-setup
 
-> Score your project 0-100 for Claude Code. Smart CLAUDE.md, 54 checks, wizard, watch mode, CI action. Powered by 1,107 verified techniques.
+> Score your project 0-100 for Claude Code readiness. Smart CLAUDE.md generator, 63 audit checks, interactive wizard, watch mode, CI action. Never overwrites existing config.
 
 [![npm version](https://img.shields.io/npm/v/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
 [![npm downloads](https://img.shields.io/npm/dm/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
@@ -44,7 +44,7 @@ No install. No config. No dependencies.
      design: none (0/2)
      devops: none (0/4)
 
-  29/54 checks passing
+  29/63 checks passing
   Run npx claudex-setup setup to fix
 ```
 
@@ -52,12 +52,13 @@ No install. No config. No dependencies.
 
 | Command | What it does |
 |---------|-------------|
-| `npx claudex-setup` | **Audit** - Score 0-100 against 54 checks |
+| `npx claudex-setup` | **Audit** - Score 0-100 against 63 checks |
 | `npx claudex-setup setup` | **Setup** - Smart CLAUDE.md + hooks + commands + agents |
 | `npx claudex-setup setup --auto` | **Auto-setup** - No prompts, apply all |
 | `npx claudex-setup interactive` | **Wizard** - Step-by-step guided tour |
 | `npx claudex-setup watch` | **Watch** - Live monitoring with score delta |
 | `npx claudex-setup badge` | **Badge** - Generate shields.io badge for README |
+| `npx claudex-setup deep-review` | **Deep Review** - AI-powered config analysis (needs API key) |
 | `npx claudex-setup insights` | **Insights** - View community aggregate stats |
 
 ### Options
@@ -79,7 +80,7 @@ Not a generic template. The `setup` command actually analyzes your project:
 - **XML constraint blocks** - adds `<constraints>` and `<verification>` with context-aware rules
 - **Verification criteria** - auto-generates checklist from your actual commands
 
-## 54 Checks Across 13 Categories
+## 63 Checks Across 14 Categories
 
 | Category | Checks | Key items |
 |----------|-------:|-----------|
@@ -96,6 +97,7 @@ Not a generic template. The `setup` command actually analyzes your project:
 | MCP | 3 | servers, Context7, integrations |
 | Prompting | 3 | constraints, validation, patterns |
 | Features | 2 | /security-review, Channels |
+| **Quality Deep** | **9** | **freshness, contradictions, deprecated patterns, maxTurns, $ARGUMENTS** |
 
 ## Stack Detection
 
@@ -136,6 +138,36 @@ npx claudex-setup badge
 # Output: [![Claude Code Ready](https://img.shields.io/badge/...)](...)
 ```
 
+## For Veteran Claude Code Users
+
+Already have a solid CLAUDE.md and hooks? Two things for you:
+
+### Deep Review (AI-powered)
+
+```bash
+npx claudex-setup deep-review
+```
+
+Claude reads your actual config and gives specific feedback: what's strong, what has issues, what's missing for your stack. Not pattern matching — real analysis. Your config goes to Anthropic API only, we never see it.
+
+### Quality-Deep Checks
+
+The v0.4.0 quality-deep checks catch what basic audits miss:
+
+| Check | What it catches |
+|-------|----------------|
+| **Freshness** | CLAUDE.md that doesn't mention modern features (hooks, skills, MCP) |
+| **Conciseness** | CLAUDE.md over 200 lines (wastes tokens every session) |
+| **Contradictions** | Conflicting rules ("always X" + "never X") |
+| **Hook specificity** | Hooks without matchers that fire on every tool call |
+| **Permission hygiene** | bypassPermissions still enabled in production |
+| **Command flexibility** | Commands without $ARGUMENTS (static, not reusable) |
+| **Agent limits** | Agents without maxTurns (can run forever) |
+| **Security workflow** | No /security-review in your process |
+| **Deprecated patterns** | Old model names, prefill, deprecated API formats |
+
+These checks evaluate **quality**, not just existence. A well-configured project with stale patterns will surface real improvements.
+
 ## Privacy
 
 - **Zero dependencies** - nothing to audit
@@ -151,7 +183,9 @@ Every check traces to a verified technique from a systematic audit of:
 - Anthropic blog posts and benchmark papers
 - 194 hands-on experiments with real evidence
 
-1,107 techniques cataloged. 954 tested. Continuously updated.
+The catalog includes 1,107 entries (features, techniques, patterns, tools, stats, and known limitations) — not all are actionable checks. 954 were verified with real evidence. Continuously updated.
+
+**Note:** A hand-crafted CLAUDE.md that reflects your real conventions will always be better than a generated one. This tool is most useful for projects starting from zero, or as a checklist for what you might be missing.
 
 ## Requirements
 

package/bin/cli.js

@@ -18,6 +18,7 @@ const HELP = `
     npx claudex-setup audit            Same as above
     npx claudex-setup setup            Apply recommended configuration
     npx claudex-setup setup --auto     Apply all without prompts
+    npx claudex-setup deep-review       AI-powered config analysis (needs API key)
     npx claudex-setup interactive      Step-by-step guided wizard
     npx claudex-setup watch            Monitor changes and re-audit live
     npx claudex-setup badge            Generate shields.io badge markdown
@@ -91,6 +92,9 @@ async function main() {
         console.log('  Could not reach insights server. Run locally: npx claudex-setup');
       });
       return; // keep process alive for http
+    } else if (command === 'deep-review' || command === 'review') {
+      const { deepReview } = require('../src/deep-review');
+      await deepReview(options);
     } else if (command === 'interactive' || command === 'wizard') {
       const { interactive } = require('../src/interactive');
       await interactive(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "0.3.2",
+  "version": "0.5.1",
   "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {

package/src/deep-review.js

@@ -0,0 +1,310 @@
+/**
+ * Deep Review - AI-powered analysis of Claude Code configuration quality.
+ * Uses Claude API to read and critique your actual config, not just pattern match.
+ *
+ * Requires: ANTHROPIC_API_KEY environment variable
+ * Usage: npx claudex-setup deep-review
+ */
+
+const https = require('https');
+const { ProjectContext } = require('./context');
+const { STACKS } = require('./techniques');
+
+const COLORS = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m',
+  blue: '\x1b[36m', magenta: '\x1b[35m',
+};
+const c = (text, color) => `${COLORS[color] || ''}${text}${COLORS.reset}`;
+
+function collectProjectConfig(ctx, stacks) {
+  const config = {};
+
+  // CLAUDE.md
+  config.claudeMd = ctx.fileContent('CLAUDE.md') || ctx.fileContent('.claude/CLAUDE.md');
+
+  // Settings
+  config.settings = ctx.fileContent('.claude/settings.local.json') || ctx.fileContent('.claude/settings.json');
+
+  // Commands
+  config.commands = {};
+  if (ctx.hasDir('.claude/commands')) {
+    for (const f of ctx.dirFiles('.claude/commands')) {
+      config.commands[f] = ctx.fileContent(`.claude/commands/${f}`);
+    }
+  }
+
+  // Agents
+  config.agents = {};
+  if (ctx.hasDir('.claude/agents')) {
+    for (const f of ctx.dirFiles('.claude/agents')) {
+      config.agents[f] = ctx.fileContent(`.claude/agents/${f}`);
+    }
+  }
+
+  // Rules
+  config.rules = {};
+  if (ctx.hasDir('.claude/rules')) {
+    for (const f of ctx.dirFiles('.claude/rules')) {
+      config.rules[f] = ctx.fileContent(`.claude/rules/${f}`);
+    }
+  }
+
+  // Hooks (from settings)
+  if (ctx.hasDir('.claude/hooks')) {
+    config.hookFiles = {};
+    for (const f of ctx.dirFiles('.claude/hooks')) {
+      config.hookFiles[f] = ctx.fileContent(`.claude/hooks/${f}`);
+    }
+  }
+
+  // Package.json (scripts only)
+  const pkg = ctx.jsonFile('package.json');
+  if (pkg) {
+    config.packageScripts = pkg.scripts || {};
+    config.packageName = pkg.name;
+  }
+
+  config.stacks = stacks.map(s => s.label);
+
+  return config;
+}
+
+function buildPrompt(config) {
+  const parts = [];
+
+  parts.push(`You are an expert Claude Code configuration reviewer. Analyze this project's Claude Code setup and provide specific, actionable feedback.
+
+The project uses: ${config.stacks.join(', ') || 'unknown stack'}
+${config.packageName ? `Project name: ${config.packageName}` : ''}`);
+
+  if (config.claudeMd) {
+    parts.push(`\n<claude_md>\n${config.claudeMd.slice(0, 4000)}\n</claude_md>`);
+  } else {
+    parts.push('\nNo CLAUDE.md found.');
+  }
+
+  if (config.settings) {
+    parts.push(`\n<settings>\n${config.settings.slice(0, 2000)}\n</settings>`);
+  }
+
+  if (Object.keys(config.commands).length > 0) {
+    parts.push('\n<commands>');
+    for (const [name, content] of Object.entries(config.commands)) {
+      parts.push(`--- ${name} ---\n${(content || '').slice(0, 500)}`);
+    }
+    parts.push('</commands>');
+  }
+
+  if (Object.keys(config.agents).length > 0) {
+    parts.push('\n<agents>');
+    for (const [name, content] of Object.entries(config.agents)) {
+      parts.push(`--- ${name} ---\n${(content || '').slice(0, 500)}`);
+    }
+    parts.push('</agents>');
+  }
+
+  if (Object.keys(config.rules || {}).length > 0) {
+    parts.push('\n<rules>');
+    for (const [name, content] of Object.entries(config.rules)) {
+      parts.push(`--- ${name} ---\n${(content || '').slice(0, 300)}`);
+    }
+    parts.push('</rules>');
+  }
+
+  if (config.hookFiles && Object.keys(config.hookFiles).length > 0) {
+    parts.push('\n<hooks>');
+    for (const [name, content] of Object.entries(config.hookFiles)) {
+      parts.push(`--- ${name} ---\n${(content || '').slice(0, 300)}`);
+    }
+    parts.push('</hooks>');
+  }
+
+  parts.push(`
+<task>
+Provide a deep review with these exact sections:
+
+## Score: X/10
+
+## Strengths (what's done well)
+- List 2-4 specific things this config does right, with WHY they're effective
+
+## Issues (what needs fixing)
+- List 3-5 specific issues, each with:
+  - What's wrong (be specific, quote from the config)
+  - Why it matters
+  - Exact fix (show the corrected version or command)
+
+## Missing (what's not there but should be)
+- List 2-3 things this project should add based on its stack
+- Be specific to THIS project's stack and size, not generic advice
+
+## Quick Wins (fastest improvements)
+- Top 3 changes that take under 2 minutes each
+
+Be direct, specific, and honest. Don't pad with generic advice. Reference actual content from the config. If the setup is already excellent, say so and focus on micro-optimizations.
+</task>`);
+
+  return parts.join('\n');
+}
+
+function callClaude(apiKey, prompt) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({
+      model: 'claude-sonnet-4-6',
+      max_tokens: 2000,
+      messages: [{ role: 'user', content: prompt }],
+    });
+
+    const req = https.request({
+      hostname: 'api.anthropic.com',
+      path: '/v1/messages',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.error) {
+            reject(new Error(parsed.error.message));
+          } else {
+            resolve(parsed.content[0].text);
+          }
+        } catch (e) {
+          reject(new Error(`API response parse error: ${data.slice(0, 200)}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+function hasClaudeCode() {
+  try {
+    require('child_process').execSync('claude --version', { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+async function callClaudeCode(prompt) {
+  const { execSync } = require('child_process');
+  // Use claude -p (headless/print mode) - uses the user's existing Claude Code auth
+  const escaped = prompt.replace(/'/g, "'\\''");
+  const result = execSync(`claude -p '${escaped}' --output-format text`, {
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+    timeout: 120000,
+  });
+  return result;
+}
+
+async function deepReview(options) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  const hasClaude = hasClaudeCode();
+
+  if (!apiKey && !hasClaude) {
+    console.log('');
+    console.log(c('  Deep Review needs Claude Code or an API key.', 'bold'));
+    console.log('');
+    console.log('  Option A (recommended): Install Claude Code, then run this command.');
+    console.log(c('    npm install -g @anthropic-ai/claude-code', 'green'));
+    console.log('');
+    console.log('  Option B: Set an API key:');
+    console.log(c('    export ANTHROPIC_API_KEY=sk-ant-...', 'green'));
+    console.log('');
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(c('  claudex-setup deep review', 'bold'));
+  console.log(c('  ═══════════════════════════════════════', 'dim'));
+
+  const ctx = new ProjectContext(options.dir);
+  const stacks = ctx.detectStacks(STACKS);
+
+  console.log(c(`  Scanning: ${options.dir}`, 'dim'));
+  if (stacks.length > 0) {
+    console.log(c(`  Stack: ${stacks.map(s => s.label).join(', ')}`, 'blue'));
+  }
+
+  // Collect config
+  const config = collectProjectConfig(ctx, stacks);
+  const fileCount = [
+    config.claudeMd ? 1 : 0,
+    config.settings ? 1 : 0,
+    Object.keys(config.commands).length,
+    Object.keys(config.agents).length,
+    Object.keys(config.rules || {}).length,
+    Object.keys(config.hookFiles || {}).length,
+  ].reduce((a, b) => a + b, 0);
+
+  console.log(c(`  Found ${fileCount} config files to analyze`, 'dim'));
+  console.log('');
+  console.log(c('  Sending to Claude for deep analysis...', 'magenta'));
+  console.log('');
+
+  try {
+    const prompt = buildPrompt(config);
+    let review;
+    let method;
+
+    if (hasClaude) {
+      method = 'Claude Code (your existing subscription)';
+      console.log(c('  Using: Claude Code (no API key needed)', 'green'));
+      console.log('');
+      review = await callClaudeCode(prompt);
+    } else {
+      method = 'Anthropic API (your key)';
+      console.log(c('  Using: Anthropic API', 'dim'));
+      console.log('');
+      review = await callClaude(apiKey, prompt);
+    }
+
+    // Format output
+    const lines = review.split('\n');
+    for (const line of lines) {
+      if (line.startsWith('## Score')) {
+        console.log(c(`  ${line}`, 'bold'));
+      } else if (line.startsWith('## Strengths')) {
+        console.log(c(`  ${line}`, 'green'));
+      } else if (line.startsWith('## Issues')) {
+        console.log(c(`  ${line}`, 'yellow'));
+      } else if (line.startsWith('## Missing')) {
+        console.log(c(`  ${line}`, 'red'));
+      } else if (line.startsWith('## Quick')) {
+        console.log(c(`  ${line}`, 'magenta'));
+      } else if (line.startsWith('- ')) {
+        console.log(`  ${line}`);
+      } else if (line.startsWith('```')) {
+        console.log(c(`  ${line}`, 'dim'));
+      } else if (line.trim()) {
+        console.log(`  ${line}`);
+      } else {
+        console.log('');
+      }
+    }
+
+    console.log('');
+    console.log(c('  ─────────────────────────────────────', 'dim'));
+    console.log(c(`  Reviewed via ${method}`, 'dim'));
+    console.log(c('  Your config stays between you and Anthropic. We never see it.', 'dim'));
+    console.log('');
+  } catch (err) {
+    console.log(c(`  Error: ${err.message}`, 'red'));
+    console.log('');
+    console.log('  Check your ANTHROPIC_API_KEY is valid.');
+    process.exit(1);
+  }
+}
+
+module.exports = { deepReview };

package/src/setup.js

@@ -569,6 +569,7 @@ async function setup(options) {
   console.log('');
 
   let created = 0;
+  let skipped = 0;
 
   for (const [key, technique] of Object.entries(TECHNIQUES)) {
     if (technique.passed || technique.check(ctx)) continue;
@@ -589,6 +590,9 @@ async function setup(options) {
         fs.writeFileSync(fullPath, result, 'utf8');
         console.log(`  \x1b[32m✅\x1b[0m Created ${filePath}`);
         created++;
+      } else {
+        console.log(`  \x1b[2m⏭️  Skipped ${filePath} (already exists — your version is kept)\x1b[0m`);
+        skipped++;
       }
     } else if (typeof result === 'object') {
       // Multiple files template (hooks, commands, etc)
@@ -616,16 +620,23 @@ async function setup(options) {
           fs.writeFileSync(filePath, content, 'utf8');
           console.log(`  \x1b[32m✅\x1b[0m Created ${path.relative(options.dir, filePath)}`);
           created++;
+        } else {
+          skipped++;
         }
       }
     }
   }
 
-  if (created === 0) {
-    console.log('  \x1b[32m✅\x1b[0m Project already well configured!');
-  } else {
-    console.log('');
+  console.log('');
+  if (created === 0 && skipped > 0) {
+    console.log('  \x1b[32m✅\x1b[0m Your project is already well configured!');
+    console.log(`  \x1b[2m  ${skipped} files already exist and were preserved.\x1b[0m`);
+    console.log('  \x1b[2m  We never overwrite your existing config — your setup is kept.\x1b[0m');
+  } else if (created > 0) {
     console.log(`  \x1b[1m${created} files created.\x1b[0m`);
+    if (skipped > 0) {
+      console.log(`  \x1b[2m${skipped} existing files preserved (not overwritten).\x1b[0m`);
+    }
   }
 
   console.log('');

package/src/techniques.js

@@ -702,15 +702,18 @@ const TECHNIQUES = {
     name: 'XML tags for structured prompts',
     check: (ctx) => {
       const md = ctx.fileContent('CLAUDE.md') || '';
-      return md.includes('<') && md.includes('>') && (
-        md.includes('<constraints') || md.includes('<rules') ||
-        md.includes('<validation') || md.includes('<instructions')
-      );
+      // Give credit for XML tags OR well-structured markdown with clear sections
+      const hasXml = md.includes('<constraints') || md.includes('<rules') ||
+        md.includes('<validation') || md.includes('<instructions');
+      const hasStructuredMd = (md.includes('## Rules') || md.includes('## Constraints') ||
+        md.includes('## Do not') || md.includes('## Never') || md.includes('## Important')) &&
+        md.split('\n').length > 20;
+      return hasXml || hasStructuredMd;
     },
-    impact: 'high',
-    rating: 5,
+    impact: 'medium',
+    rating: 4,
     category: 'prompting',
-    fix: 'Use XML tags (<constraints>, <validation>) in CLAUDE.md for unambiguous instructions.',
+    fix: 'Add clear rules sections to CLAUDE.md. XML tags (<constraints>) are optional but improve clarity.',
     template: null
   },
 
@@ -770,6 +773,169 @@ const TECHNIQUES = {
     fix: 'Claude Code Channels (v2.1.80+) lets you control sessions from Telegram/Discord/iMessage.',
     template: null
   },
+
+  // ============================================================
+  // === QUALITY CHECKS FOR VETERANS (category: 'quality-deep')
+  // These check HOW GOOD your config is, not just IF it exists.
+  // ============================================================
+
+  claudeMdFreshness: {
+    id: 2001,
+    name: 'CLAUDE.md mentions current Claude features',
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      if (md.length < 50) return false; // too short to evaluate
+      // Check for awareness of features from 2025+
+      const modernFeatures = ['hook', 'skill', 'agent', 'subagent', 'mcp', 'compact', '/clear', 'extended thinking', 'tool_use', 'worktree'];
+      const found = modernFeatures.filter(f => md.toLowerCase().includes(f));
+      return found.length >= 2; // knows at least 2 modern features
+    },
+    impact: 'medium',
+    rating: 4,
+    category: 'quality-deep',
+    fix: 'Your CLAUDE.md may be outdated. Modern Claude Code supports hooks, skills, agents, MCP, worktrees, and extended thinking. Mention the ones you use.',
+    template: null
+  },
+
+  claudeMdNotOverlong: {
+    id: 2002,
+    name: 'CLAUDE.md is concise (under 200 lines)',
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      return md.split('\n').length <= 200;
+    },
+    impact: 'medium',
+    rating: 4,
+    category: 'quality-deep',
+    fix: 'CLAUDE.md over 200 lines wastes tokens every session. Move detailed docs to .claude/rules/ or skills. Keep CLAUDE.md lean.',
+    template: null
+  },
+
+  claudeMdNoContradictions: {
+    id: 2003,
+    name: 'CLAUDE.md has no obvious contradictions',
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      // Check for common contradictions
+      const hasNever = /never.*always|always.*never/i.test(md);
+      const hasBothStyles = /use tabs/i.test(md) && /use spaces/i.test(md);
+      return !hasNever && !hasBothStyles;
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'quality-deep',
+    fix: 'CLAUDE.md may contain contradictory instructions. Review for conflicting rules (e.g., "always X" and "never X" about the same topic).',
+    template: null
+  },
+
+  hooksAreSpecific: {
+    id: 2004,
+    name: 'Hooks use specific matchers (not catch-all)',
+    check: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
+      if (!settings || !settings.hooks) return true; // no hooks = skip
+      const hookStr = JSON.stringify(settings.hooks);
+      // Check that hooks have matchers, not just catch-all
+      return hookStr.includes('matcher');
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'quality-deep',
+    fix: 'Hooks without matchers run on every tool call. Use matchers like "Write|Edit" or "Bash" to target specific tools.',
+    template: null
+  },
+
+  permissionsNotBypassed: {
+    id: 2005,
+    name: 'Default mode is not bypassPermissions',
+    check: (ctx) => {
+      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
+      if (!settings || !settings.permissions) return true;
+      return settings.permissions.defaultMode !== 'bypassPermissions';
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'quality-deep',
+    fix: 'bypassPermissions skips all safety checks. Use "default" or "auto" mode with targeted allow rules instead.',
+    template: null
+  },
+
+  commandsUseArguments: {
+    id: 2006,
+    name: 'Commands use $ARGUMENTS for flexibility',
+    check: (ctx) => {
+      if (!ctx.hasDir('.claude/commands')) return true;
+      const files = ctx.dirFiles('.claude/commands');
+      if (files.length === 0) return true;
+      // Check if at least one command uses $ARGUMENTS
+      for (const f of files) {
+        const content = ctx.fileContent(`.claude/commands/${f}`) || '';
+        if (content.includes('$ARGUMENTS') || content.includes('$arguments')) return true;
+      }
+      return false;
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'quality-deep',
+    fix: 'Commands without $ARGUMENTS are static. Use $ARGUMENTS to make them flexible: "Fix the issue: $ARGUMENTS"',
+    template: null
+  },
+
+  agentsHaveMaxTurns: {
+    id: 2007,
+    name: 'Agents have maxTurns limit',
+    check: (ctx) => {
+      if (!ctx.hasDir('.claude/agents')) return true;
+      const files = ctx.dirFiles('.claude/agents');
+      if (files.length === 0) return true;
+      for (const f of files) {
+        const content = ctx.fileContent(`.claude/agents/${f}`) || '';
+        if (!content.includes('maxTurns')) return false;
+      }
+      return true;
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'quality-deep',
+    fix: 'Agents without maxTurns can run indefinitely. Add "maxTurns: 50" to agent frontmatter.',
+    template: null
+  },
+
+  securityReviewInWorkflow: {
+    id: 2008,
+    name: '/security-review in workflow',
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      const hasCommand = ctx.hasDir('.claude/commands') &&
+        (ctx.dirFiles('.claude/commands') || []).some(f => f.includes('security') || f.includes('review'));
+      return md.toLowerCase().includes('security') || hasCommand;
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'quality-deep',
+    fix: 'Claude Code has built-in /security-review (OWASP Top 10). Add it to your workflow or create a /security command.',
+    template: null
+  },
+
+  noDeprecatedPatterns: {
+    id: 2009,
+    name: 'No deprecated patterns detected',
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      // Check for patterns deprecated in Claude 4.x
+      const deprecated = [
+        'prefill', // deprecated in 4.6
+        'claude-3-opus', 'claude-3-sonnet', 'claude-3-haiku', // old model names
+        'human_prompt', 'assistant_prompt', // old API format
+      ];
+      return !deprecated.some(d => md.toLowerCase().includes(d));
+    },
+    impact: 'medium',
+    rating: 3,
+    category: 'quality-deep',
+    fix: 'CLAUDE.md references deprecated patterns (old model names or API formats). Update to current Claude 4.x conventions.',
+    template: null
+  },
 };
 
 // Stack detection