claudex-setup 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.2.0] - 2026-03-31
+
+### Added
+- 50+ audit checks (up from 16)
+- 8 new categories: Design, DevOps, Hygiene, Performance, MCP, Prompting, Git Safety, Automation
+- 6 new stack detections: Svelte, Flutter, Ruby, Java, Kotlin, Swift
+- Improved CLAUDE.md template with Mermaid diagrams and XML constraints
+- Auto-sync with CLAUDEX research catalog (1,107 items)
+- Copy-paste config snippets in fix suggestions
+
+### Changed
+- Knowledge base upgraded from 972 to 1,107 verified techniques
+- Better scoring weights per category
+
+## [0.1.0] - 2026-03-30
+
+### Added
+- Initial release
+- 16 audit checks
+- Automatic setup with CLAUDE.md, hooks, commands, skills, rules, agents
+- Stack detection for 12 frameworks
+- JSON output mode

package/README.md

@@ -1,8 +1,11 @@
 # claudex-setup
 
-> Audit and optimize any project for Claude Code. Powered by 972 verified techniques.
+> Audit and optimize any project for Claude Code. Powered by 1,107 verified techniques.
 
-One command to make your project Claude Code-ready.
+[![npm version](https://img.shields.io/npm/v/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
 
@@ -14,78 +17,204 @@ npx claudex-setup
 npx claudex-setup setup
 ```
 
-## What it does
+That's it. No config files, no dependencies to install.
 
-**Audit** scans your project and scores it against 12 critical Claude Code best practices:
+## Example Output
 
 ```
-  claudex-setup audit
-  ═══════════════════════════════════════
-  Detected: React, TypeScript
-
-  ██████████████░░░░░░ 71/100
+  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
+     ...
 
-  ✅ Passing
-     CLAUDE.md project instructions
-     Hooks for automation
-     Custom slash commands
+  ⚠️  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
-     Verification criteria in CLAUDE.md
-     → Add test/lint commands so Claude can verify its own work.
+  🔴 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
 
-  Run npx claudex-setup setup to fix automatically
+     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
 ```
 
-**Setup** creates the missing configuration automatically:
+## 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:
 
 ```
-  ✅ Created CLAUDE.md
-  ✅ Created .claude/hooks/on-edit-lint.sh
-  ✅ Created .claude/commands/test.md
-  ✅ Created .claude/commands/review.md
-  ✅ Created .claude/skills/fix-issue/SKILL.md
-  ✅ Created .claude/agents/security-reviewer.md
-
-  7 files created.
+  ✅ 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.
 ```
 
-## What it checks
-
-| Check | Impact | What |
-|-------|--------|------|
-| CLAUDE.md | Critical | Project instructions for Claude |
-| Verification | Critical | Test/lint commands for self-checking |
-| Hooks | High | Automation on file edits |
-| Commands | High | Custom slash commands |
-| Mermaid diagram | High | Architecture visualization (73% token savings) |
-| XML tags | High | Structured prompts |
-| Skills | Medium | Domain-specific workflows |
-| Rules | Medium | Path-specific coding conventions |
-| Agents | Medium | Specialized subagents |
-| MCP servers | Medium | External tool integration |
-| Permissions | Medium | Security configuration |
-| .gitignore | High | Track .claude/ in version control |
+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.
+
+## 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 |
+
+Detection is based on package.json, requirements.txt, Cargo.toml, go.mod, pubspec.yaml, Gemfile, build.gradle, Package.swift, and other standard manifest files.
 
 ## Options
 
 ```bash
-npx claudex-setup                # Audit (default)
-npx claudex-setup audit          # Audit explicitly
-npx claudex-setup audit --verbose  # Show all recommendations
-npx claudex-setup audit --json   # JSON output
-npx claudex-setup setup          # Apply fixes
-npx claudex-setup --help         # Help
+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
 ```
 
-## Stack Detection
+## Backed by Research
+
+Every check and template is derived from the [CLAUDEX](https://github.com/DnaFin/claudex) 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.
 
-Automatically detects: React, Vue, Angular, Next.js, Python, Django, FastAPI, Node.js, TypeScript, Rust, Go, Docker — and tailors recommendations.
+The knowledge base is continuously updated. Run `npx claudex-setup` periodically to pick up new checks and improved templates.
 
-## Why
+## Requirements
 
-Claude Code is powerful but most projects are barely optimized for it. A proper CLAUDE.md, hooks, and skills can **3-5x your productivity**. This tool applies the knowledge from [CLAUDEX](https://github.com/DnaFin/claudex) — a research catalog of 972 verified Claude Code techniques.
+- Node.js 18+
+- Works on macOS, Linux, and Windows
+- No global install needed (npx handles it)
 
 ## License
 

package/bin/cli.js

@@ -11,13 +11,14 @@ const flags = args.filter(a => a.startsWith('--'));
 const HELP = `
   claudex-setup v${version}
   Audit and optimize any project for Claude Code.
-  Powered by 972 verified techniques.
+  Powered by 1,107 verified techniques.
 
   Usage:
     npx claudex-setup              Run audit on current directory
     npx claudex-setup audit        Same as above
     npx claudex-setup setup        Apply recommended configuration
     npx claudex-setup setup --auto Apply all recommendations without prompts
+    npx claudex-setup badge        Generate shields.io badge markdown
 
   Options:
     --verbose    Show detailed analysis
@@ -45,7 +46,14 @@ async function main() {
   };
 
   try {
-    if (command === 'setup') {
+    if (command === 'badge') {
+      const { getBadgeMarkdown } = require('../src/badge');
+      const result = await audit({ ...options, silent: true });
+      console.log(getBadgeMarkdown(result.score));
+      console.log('');
+      console.log('Add this to your README.md');
+      process.exit(0);
+    } else if (command === 'setup') {
       await setup(options);
     } else {
       await audit(options);

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "claudex-setup",
-  "version": "0.1.0",
-  "description": "Audit and optimize any project for Claude Code. Powered by 972 verified techniques.",
+  "version": "0.2.1",
+  "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {
     "claudex-setup": "bin/cli.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "start": "node bin/cli.js",
     "test": "node test/run.js"
@@ -25,7 +31,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DnaFin/claudex-setup"
+    "url": "git+https://github.com/DnaFin/claudex.git"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/audit.js

@@ -4,6 +4,7 @@
 
 const { TECHNIQUES, STACKS } = require('./techniques');
 const { ProjectContext } = require('./context');
+const { getBadgeMarkdown } = require('./badge');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -27,7 +28,24 @@ function progressBar(score, max = 100, width = 20) {
   return colorize('█'.repeat(filled), color) + colorize('░'.repeat(empty), 'dim');
 }
 
+const EFFORT_ORDER = { critical: 0, high: 1, medium: 2 };
+
+function getQuickWins(failed) {
+  // Quick wins = medium impact items first (easiest), then high, sorted by name length (shorter = simpler)
+  return [...failed]
+    .sort((a, b) => {
+      const effortA = EFFORT_ORDER[a.impact] ?? 3;
+      const effortB = EFFORT_ORDER[b.impact] ?? 3;
+      // Prefer medium (easiest to fix), then high, then critical
+      if (effortA !== effortB) return effortB - effortA;
+      // Tie-break by fix length (shorter fix description = likely simpler)
+      return (a.fix || '').length - (b.fix || '').length;
+    })
+    .slice(0, 3);
+}
+
 async function audit(options) {
+  const silent = options.silent || false;
   const ctx = new ProjectContext(options.dir);
   const stacks = ctx.detectStacks(STACKS);
   const results = [];
@@ -54,9 +72,14 @@ async function audit(options) {
   const earnedScore = passed.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
   const score = Math.round((earnedScore / maxScore) * 100);
 
+  // Silent mode: skip all output, just return result
+  if (silent) {
+    return { score, passed: passed.length, failed: failed.length, stacks, results };
+  }
+
   if (options.json) {
     console.log(JSON.stringify({ score, stacks, passed: passed.length, failed: failed.length, results }, null, 2));
-    return;
+    return { score, passed: passed.length, failed: failed.length, stacks, results };
   }
 
   // Display results
@@ -115,6 +138,18 @@ async function audit(options) {
     console.log('');
   }
 
+  // Quick wins
+  if (failed.length > 0) {
+    const quickWins = getQuickWins(failed);
+    console.log(colorize('  ⚡ Quick wins (easiest fixes first)', 'magenta'));
+    for (let i = 0; i < quickWins.length; i++) {
+      const r = quickWins[i];
+      console.log(`     ${i + 1}. ${colorize(r.name, 'bold')}`);
+      console.log(colorize(`        → ${r.fix}`, 'dim'));
+    }
+    console.log('');
+  }
+
   // Summary
   console.log(colorize('  ─────────────────────────────────────', 'dim'));
   console.log(`  ${colorize(`${passed.length}/${results.length}`, 'bold')} checks passing`);
@@ -124,11 +159,13 @@ async function audit(options) {
   }
 
   console.log('');
-  console.log(colorize('  Powered by CLAUDEX - 972 verified Claude Code techniques', 'dim'));
-  console.log(colorize('  https://github.com/naorp/claudex-setup', 'dim'));
+  console.log(`  Add to README: ${getBadgeMarkdown(score)}`);
+  console.log('');
+  console.log(colorize('  Powered by CLAUDEX - 1,107 verified Claude Code techniques', 'dim'));
+  console.log(colorize('  https://github.com/DnaFin/claudex', 'dim'));
   console.log('');
 
-  return { score, passed: passed.length, failed: failed.length, stacks };
+  return { score, passed: passed.length, failed: failed.length, stacks, results };
 }
 
 module.exports = { audit };

package/src/badge.js

@@ -0,0 +1,13 @@
+function getBadgeUrl(score) {
+  const color = score >= 80 ? 'brightgreen' : score >= 60 ? 'yellow' : score >= 40 ? 'orange' : 'red';
+  const label = encodeURIComponent('Claude Code Ready');
+  const message = encodeURIComponent(`${score}/100`);
+  return `https://img.shields.io/badge/${label}-${message}-${color}`;
+}
+
+function getBadgeMarkdown(score) {
+  const url = getBadgeUrl(score);
+  return `[![Claude Code Ready](${url})](https://github.com/DnaFin/claudex)`;
+}
+
+module.exports = { getBadgeUrl, getBadgeMarkdown };

package/src/claudex-sync.json

@@ -0,0 +1,7 @@
+{
+  "synced_from": "claudex",
+  "synced_at": "2026-03-30T23:05:29Z",
+  "total_items": 1107,
+  "tested": 948,
+  "last_id": 1157
+}