claudex-setup 0.3.0 → 0.3.2

package/README.md

@@ -1,220 +1,163 @@
 # claudex-setup
 
-> Audit and optimize any project for Claude Code. Powered by 1,107 verified techniques.
+> Score your project 0-100 for Claude Code. Smart CLAUDE.md, 54 checks, wizard, watch mode, CI action. Powered by 1,107 verified techniques.
 
 [![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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-One command to make your project Claude Code-ready. Detects your stack, scores your setup against 50+ checks, and auto-generates everything Claude Code needs to work at full capacity.
-
 ## Quick Start
 
 ```bash
-# Audit your project
-npx claudex-setup
-
-# Apply recommended configuration
-npx claudex-setup setup
+npx claudex-setup              # Audit your project (10 seconds)
+npx claudex-setup setup        # Auto-fix everything
 ```
 
-That's it. No config files, no dependencies to install.
-
-## Example Output
-
-```
-  claudex-setup v0.2.0
-  ═══════════════════════════════════════════════════
-
-  Detected stack: React, TypeScript, Docker
-
-  ██████████████░░░░░░░░░░░░ 54/100
-
-  ┌─────────────────────────────────────────────────┐
-  │  CATEGORY          SCORE   CHECKS               │
-  │  Memory              8/15  CLAUDE.md, rules      │
-  │  Quality             6/15  verification, linting │
-  │  Git Safety          5/10  hooks, permissions    │
-  │  Workflow            4/10  commands, skills      │
-  │  Security            3/10  permissions, secrets  │
-  │  Automation          5/10  hooks, agents         │
-  │  Design              4/10  Mermaid, XML tags     │
-  │  DevOps              3/5   Docker, CI            │
-  │  Hygiene             4/5   .gitignore, cleanup   │
-  │  Performance         4/5   context, compaction   │
-  │  MCP                 3/5   servers, tools        │
-  │  Prompting           5/5   constraints, chains   │
-  └─────────────────────────────────────────────────┘
-
-  ✅ Passing (12)
-     CLAUDE.md exists with project instructions
-     Pre-commit hook configured
-     Custom slash commands defined
-     .gitignore tracks .claude/ correctly
-     Docker stack detected and configured
-     ...
-
-  ⚠️  Warnings (6)
-     No Mermaid architecture diagram in CLAUDE.md
-     → Add a ```mermaid graph to visualize project structure
-     Missing XML constraint tags
-     → Wrap critical rules in <constraints> tags for 30% better adherence
-     ...
-
-  🔴 Critical (3)
-     No verification criteria in CLAUDE.md
-     → Add test/lint commands so Claude can verify its own work
-       Example:
-       ## Verification
-       - Run `npm test` before committing
-       - Run `npm run lint` to check style
-
-     No security permissions configured
-     → Create .claude/settings.json with allowed commands
-
-     No self-correction workflow
-     → Add review commands for generate → review → refine cycles
-
-  ───────────────────────────────────────────────────
-  Run `npx claudex-setup setup` to fix 9 issues automatically
-```
+No install. No config. No dependencies.
 
-## What It Checks
-
-### 📋 Memory (8 checks)
-- CLAUDE.md exists with project instructions
-- CLAUDE.md includes stack-specific guidance
-- Architecture section with Mermaid diagram
-- Verification criteria (test/lint commands)
-- Coding conventions documented
-- Error handling patterns defined
-- Session memory configured
-- State tracking files present
-
-### ✅ Quality (7 checks)
-- Self-correction chains (generate → review → refine)
-- Constraint-based validation blocks
-- Verification loops for claims
-- Quality gates before commits
-- Duplicate detection rules
-- Metadata sync requirements
-- Iron Law enforcement (evidence for all claims)
-
-### 🔒 Git Safety (5 checks)
-- Pre-commit hooks configured
-- Destructive command warnings
-- Force-push protection
-- Branch naming conventions
-- Commit message standards
-
-### 🔄 Workflow (6 checks)
-- Custom slash commands defined
-- Skills for domain workflows
-- Rules for path-specific conventions
-- Agents for specialized tasks
-- Command templates present
-- Workflow documentation
-
-### 🛡️ Security (5 checks)
-- Permissions configured in settings.json
-- Secrets excluded from commits
-- Allowed/denied command lists
-- MCP server permissions
-- Environment variable handling
-
-### ⚙️ Automation (5 checks)
-- Edit hooks for linting
-- Save hooks for formatting
-- Notification hooks
-- Log rotation configured
-- Auto-sync with knowledge base
-
-### 🎨 Design (4 checks)
-- Mermaid diagrams for architecture
-- XML tags for structured prompts
-- Documents at top of prompts
-- Meta-prompting patterns
-
-### 🚀 DevOps (3 checks)
-- CI/CD pipeline detection
-- Docker configuration
-- Deployment instructions in CLAUDE.md
-
-### 🧹 Hygiene (3 checks)
-- .gitignore tracks .claude/ correctly
-- No stale configuration files
-- Clean project structure
-
-### ⚡ Performance (3 checks)
-- Context management strategy
-- Compaction triggers documented
-- Tool search over full loads
-
-### 🔌 MCP (3 checks)
-- MCP servers configured
-- MCP tools documented
-- Server permissions set
-
-### 💬 Prompting (3 checks)
-- Constraint tags used
-- Self-validation blocks
-- Research methodology defined
-
-## Auto-Generated Setup
-
-Running `npx claudex-setup setup` creates everything your project needs:
+## What You Get
 
 ```
-  ✅ Created CLAUDE.md              — project instructions with Mermaid diagram
-  ✅ Created .claude/settings.json  — permissions and security
-  ✅ Created .claude/hooks/         — pre-commit, on-edit linting
-  ✅ Created .claude/commands/      — /test, /review, /deploy
-  ✅ Created .claude/skills/        — domain-specific workflows
-  ✅ Created .claude/rules/         — path-specific conventions
-  ✅ Created .claude/agents/        — specialized subagents
-
-  7 configs created. Your project is now Claude Code-ready.
+  claudex-setup audit
+  ═══════════════════════════════════════
+  Detected: React, TypeScript, Docker
+
+  ████████████████░░░░ 78/100
+
+  ✅ Passing
+     CLAUDE.md project instructions
+     Mermaid architecture diagram
+     Hooks (PreToolUse + PostToolUse)
+     Custom slash commands (5 commands)
+     XML constraint blocks
+     Secrets protection configured
+
+  🟡 High Impact
+     CI pipeline configured
+     → Add .github/workflows/ for automated testing
+
+  ⚡ Quick wins
+     1. Add LICENSE file
+     2. Add CHANGELOG.md
+
+  Weakest areas:
+     design: none (0/2)
+     devops: none (0/4)
+
+  29/54 checks passing
+  Run npx claudex-setup setup to fix
 ```
 
-All generated files are tailored to your detected stack. A React + TypeScript project gets different hooks, commands, and CLAUDE.md content than a Python + FastAPI project.
+## All Commands
+
+| Command | What it does |
+|---------|-------------|
+| `npx claudex-setup` | **Audit** - Score 0-100 against 54 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 insights` | **Insights** - View community aggregate stats |
+
+### Options
+
+| Flag | Effect |
+|------|--------|
+| `--verbose` | Show all recommendations (not just critical/high) |
+| `--json` | Machine-readable JSON output (for CI) |
+| `--no-insights` | Disable anonymous usage insights |
+
+## Smart CLAUDE.md Generation
+
+Not a generic template. The `setup` command actually analyzes your project:
+
+- **Reads package.json** - includes your actual test, build, lint, dev commands
+- **Detects framework** - Next.js Server Components, Django models, FastAPI Pydantic, React hooks
+- **TypeScript-aware** - detects strict mode, adds TS-specific rules
+- **Auto Mermaid diagram** - scans directories and generates architecture visualization (73% token savings)
+- **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
+
+| Category | Checks | Key items |
+|----------|-------:|-----------|
+| 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 |
+| Automation | 5 | PreToolUse, PostToolUse, SessionStart |
+| Design | 4 | Mermaid, XML tags, structured prompts |
+| DevOps | 4 | Docker, CI, Terraform, K8s |
+| Hygiene | 6 | .gitignore, cleanup, structure |
+| Performance | 3 | context management, compaction |
+| MCP | 3 | servers, Context7, integrations |
+| Prompting | 3 | constraints, validation, patterns |
+| Features | 2 | /security-review, Channels |
 
 ## Stack Detection
 
-Automatically detects and tailors configuration for:
-
-| Category | Frameworks |
-|----------|-----------|
-| Frontend | React, Vue, Angular, Next.js, Svelte |
-| Backend | Node.js, Python, Django, FastAPI, Ruby |
-| Mobile | Flutter, Swift, Kotlin |
-| Systems | Rust, Go, Java |
-| Language | TypeScript, JavaScript |
-| Infra | Docker, Kubernetes |
+Auto-detects and tailors output for 18 stacks:
+
+| | |
+|--|--|
+| **Frontend** | React, Vue, Angular, Next.js, Svelte |
+| **Backend** | Node.js, Python, Django, FastAPI |
+| **Mobile** | Flutter, Swift, Kotlin |
+| **Systems** | Rust, Go, Java, Ruby |
+| **Language** | TypeScript |
+| **Infra** | Docker |
+
+## GitHub Action
+
+Add to `.github/workflows/claudex.yml`:
+
+```yaml
+name: CLAUDEX Audit
+on: [pull_request]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DnaFin/claudex-setup@main
+        with:
+          threshold: 50
+```
 
-Detection is based on package.json, requirements.txt, Cargo.toml, go.mod, pubspec.yaml, Gemfile, build.gradle, Package.swift, and other standard manifest files.
+## Badge
 
-## Options
+Add a readiness badge to your README:
 
 ```bash
-npx claudex-setup                    # Audit (default)
-npx claudex-setup audit              # Audit explicitly
-npx claudex-setup audit --verbose    # Show all checks with details
-npx claudex-setup audit --json       # Machine-readable JSON output
-npx claudex-setup setup              # Auto-generate missing configs
-npx claudex-setup setup --auto       # Non-interactive, accept all defaults
-npx claudex-setup --help             # Show help
+npx claudex-setup badge
+# Output: [![Claude Code Ready](https://img.shields.io/badge/...)](...)
 ```
 
+## Privacy
+
+- **Zero dependencies** - nothing to audit
+- **Runs 100% locally** - no cloud processing
+- **Anonymous insights** - opt-in, no PII, no file contents (disable with `--no-insights`)
+- **MIT Licensed** - use anywhere
+
 ## Backed by Research
 
-Every check and template is derived from the [CLAUDEX](https://github.com/DnaFin/claudex-setup) research catalog — a systematic audit of 1,107 verified Claude Code techniques across 13 research categories. This includes findings from all 73 official Claude Code documentation pages, community reports, and hands-on experiments.
+Every check traces to a verified technique from a systematic audit of:
+- All 73 official Claude Code documentation pages
+- 100+ community MCP servers verified via GitHub API
+- Anthropic blog posts and benchmark papers
+- 194 hands-on experiments with real evidence
 
-The knowledge base is continuously updated. Run `npx claudex-setup` periodically to pick up new checks and improved templates.
+1,107 techniques cataloged. 954 tested. Continuously updated.
 
 ## Requirements
 
 - Node.js 18+
-- Works on macOS, Linux, and Windows
-- No global install needed (npx handles it)
+- macOS, Linux, Windows
+- No global install (npx handles it)
 
 ## License
 

package/bin/cli.js

@@ -23,10 +23,11 @@ const HELP = `
     npx claudex-setup badge            Generate shields.io badge markdown
 
   Options:
-    --verbose    Show all recommendations (not just critical/high)
-    --json       Output as JSON (for CI pipelines)
-    --help       Show this help
-    --version    Show version
+    --verbose       Show all recommendations (not just critical/high)
+    --json          Output as JSON (for CI pipelines)
+    --no-insights   Disable anonymous usage insights
+    --help          Show this help
+    --version       Show version
 `;
 
 async function main() {
@@ -55,6 +56,41 @@ async function main() {
       console.log('');
       console.log('Add this to your README.md');
       process.exit(0);
+    } else if (command === 'insights' || command === 'learn') {
+      const https = require('https');
+      const url = 'https://claudex-insights.claudex.workers.dev/v1/stats';
+      https.get(url, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try {
+            const stats = JSON.parse(data);
+            console.log('');
+            console.log('\x1b[1m  CLAUDEX Community Insights\x1b[0m');
+            console.log('\x1b[2m  ═══════════════════════════════════════\x1b[0m');
+            console.log(`  Total audits run: \x1b[1m${stats.totalRuns}\x1b[0m`);
+            console.log(`  Average score: \x1b[1m${stats.averageScore}/100\x1b[0m`);
+            console.log('');
+            if (stats.topFailedChecks && stats.topFailedChecks.length > 0) {
+              console.log('\x1b[33m  Most common gaps:\x1b[0m');
+              for (const f of stats.topFailedChecks.slice(0, 5)) {
+                console.log(`     ${f.pct}% miss: \x1b[1m${f.check}\x1b[0m`);
+              }
+              console.log('');
+            }
+            if (stats.topStacks && stats.topStacks.length > 0) {
+              console.log('\x1b[36m  Popular stacks:\x1b[0m');
+              console.log(`     ${stats.topStacks.map(s => s.stack).join(', ')}`);
+            }
+            console.log('');
+          } catch (e) {
+            console.log('  No community data available yet. Be the first to run: npx claudex-setup');
+          }
+        });
+      }).on('error', () => {
+        console.log('  Could not reach insights server. Run locally: npx claudex-setup');
+      });
+      return; // keep process alive for http
     } 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.0",
+  "version": "0.3.2",
   "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {

package/src/audit.js

@@ -5,6 +5,7 @@
 const { TECHNIQUES, STACKS } = require('./techniques');
 const { ProjectContext } = require('./context');
 const { getBadgeMarkdown } = require('./badge');
+const { sendInsights, getLocalInsights } = require('./insights');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -161,11 +162,27 @@ async function audit(options) {
   console.log('');
   console.log(`  Add to README: ${getBadgeMarkdown(score)}`);
   console.log('');
+
+  // Weakest categories insight
+  const insights = getLocalInsights({ score, results });
+  if (insights.weakest.length > 0) {
+    console.log(colorize('  Weakest areas:', 'dim'));
+    for (const w of insights.weakest) {
+      const bar = w.score === 0 ? colorize('none', 'red') : `${w.score}%`;
+      console.log(colorize(`     ${w.name}: ${bar} (${w.passed}/${w.total})`, 'dim'));
+    }
+    console.log('');
+  }
+
   console.log(colorize('  Powered by CLAUDEX - 1,107 verified Claude Code techniques', 'dim'));
   console.log(colorize('  https://github.com/DnaFin/claudex-setup', 'dim'));
   console.log('');
 
-  return { score, passed: passed.length, failed: failed.length, stacks, results };
+  // Send anonymous insights (opt-in, privacy-first, fire-and-forget)
+  const result = { score, passed: passed.length, failed: failed.length, stacks, results };
+  sendInsights(result);
+
+  return result;
 }
 
 module.exports = { audit };

package/src/insights.js

@@ -0,0 +1,122 @@
+/**
+ * Anonymous insights collection - opt-in, privacy-first.
+ *
+ * What we collect (anonymously, no PII):
+ * - Score distribution (10/100, 45/100, etc.)
+ * - Stack detection (React+TS, Python+Docker, etc.)
+ * - Which checks fail most
+ * - Which checks pass most
+ * - OS + Node version
+ *
+ * What we NEVER collect:
+ * - File contents, paths, or project names
+ * - IP addresses or user identity
+ * - API keys, tokens, or credentials
+ * - Any data if user opts out
+ *
+ * Users can opt out with: npx claudex-setup --no-insights
+ * Or set env: CLAUDEX_NO_INSIGHTS=1
+ */
+
+const https = require('https');
+const os = require('os');
+
+const INSIGHTS_ENDPOINT = 'https://claudex-insights.claudex.workers.dev/v1/report';
+const TIMEOUT_MS = 3000;
+
+function shouldCollect() {
+  // Respect opt-out
+  if (process.env.CLAUDEX_NO_INSIGHTS === '1') return false;
+  if (process.argv.includes('--no-insights')) return false;
+
+  // Don't collect in CI
+  if (process.env.CI || process.env.GITHUB_ACTIONS) return false;
+
+  return true;
+}
+
+function buildPayload(auditResult) {
+  // Only anonymous aggregate data - no PII, no file contents, no paths
+  const failedChecks = auditResult.results
+    .filter(r => !r.passed)
+    .map(r => r.key);
+
+  const passedChecks = auditResult.results
+    .filter(r => r.passed)
+    .map(r => r.key);
+
+  return {
+    v: 1,
+    score: auditResult.score,
+    passed: auditResult.passed,
+    failed: auditResult.failed,
+    stacks: (auditResult.stacks || []).map(s => s.label),
+    failedChecks,
+    passedChecks,
+    platform: os.platform(),
+    nodeVersion: process.version,
+    toolVersion: require('../package.json').version,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function sendInsights(auditResult) {
+  if (!shouldCollect()) return;
+
+  try {
+    const payload = JSON.stringify(buildPayload(auditResult));
+    const url = new URL(INSIGHTS_ENDPOINT);
+
+    const req = https.request({
+      hostname: url.hostname,
+      path: url.pathname,
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+      timeout: TIMEOUT_MS,
+    });
+
+    // Fire and forget - never block the CLI
+    req.on('error', () => {}); // silently ignore
+    req.on('timeout', () => req.destroy());
+    req.write(payload);
+    req.end();
+  } catch (e) {
+    // Never let insights crash the CLI
+  }
+}
+
+/**
+ * Generate insights summary from local audit history.
+ * This runs locally - no network needed.
+ */
+function getLocalInsights(auditResult) {
+  const { results } = auditResult;
+  const failed = results.filter(r => !r.passed);
+
+  // Top 3 most impactful fixes
+  const impactOrder = { critical: 3, high: 2, medium: 1 };
+  const topFixes = [...failed]
+    .sort((a, b) => (impactOrder[b.impact] || 0) - (impactOrder[a.impact] || 0))
+    .slice(0, 3)
+    .map(r => ({ name: r.name, impact: r.impact, fix: r.fix }));
+
+  // Score breakdown by category
+  const categories = {};
+  for (const r of results) {
+    const cat = r.category || 'other';
+    if (!categories[cat]) categories[cat] = { passed: 0, total: 0 };
+    categories[cat].total++;
+    if (r.passed) categories[cat].passed++;
+  }
+
+  // Weakest categories
+  const weakest = Object.entries(categories)
+    .map(([name, data]) => ({ name, score: Math.round((data.passed / data.total) * 100), ...data }))
+    .filter(c => c.score < 100)
+    .sort((a, b) => a.score - b.score)
+    .slice(0, 3);
+
+  return { topFixes, categories, weakest, totalScore: auditResult.score };
+}
+
+module.exports = { sendInsights, getLocalInsights, shouldCollect };