claudex-setup 1.10.1 → 1.10.3

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [1.10.3] - 2026-04-02
+
+### Added
+- `--snapshot` support for `audit`, `augment`, `suggest-only`, `benchmark`, and `governance`, writing normalized evidence artifacts under `.claude/claudex-setup/snapshots/`
+- shared snapshot history via `index.json` so before/after work can accumulate into a single local evidence spine
+- `governance --out governance.md` for a shareable governance / pilot-readiness artifact
+- packaged Claude-native `audit-repo` skill template under `content/claude-code/audit-repo/`
+- lightweight release checklist in `content/release-checklist.md`
+
+### Changed
+- default audit now surfaces `Top 5 Next Actions` with rationale, traceability, risk, confidence, and a suggested next command
+- `--lite` now gives a shorter beginner-first top-3 quick scan
+- README and docs now reflect snapshot artifacts, governance export, and the Claude-native skill path
+- packaged content and public-facing counts are now aligned with the current CLAUDEX state
+
+## [1.10.2] - 2026-04-02
+
+### Fixed
+- MCP recommendations are now less speculative: `postgres-mcp` requires explicit Postgres signals, `figma-mcp` only appears for design-system repos, and `mcp-security` is no longer auto-added just because multiple packs were suggested
+- `sentry-mcp` now requires real observability signals or stricter operational domains instead of appearing for every frontend/backend repo
+- design-system detection now respects `.storybook/` directories directly, improving frontend pack accuracy
+
+### Added
+- MCP preflight warnings for `setup`, `plan`, and `apply` when selected packs require missing environment variables
+- user-facing docs now reflect the actual 22 detected stacks
+
+## [1.10.1] - 2026-04-02
+
+### Fixed
+- corrected MCP pack package names to verified npm packages
+- aligned settings hierarchy checks with shared settings precedence
+
 ## [1.10.0] - 2026-04-01
 
 ### Added

package/README.md

@@ -1,19 +1,36 @@
 # claudex-setup
 
-> Score your project 0-100 for Claude Code readiness. Discover gaps, export proposal bundles, apply safe starter changes with rollback, and benchmark the impact without touching your live repo.
+> Score your repo's Claude Code setup against 62 checks. See what's missing, apply only what you approve with rollback, and benchmark the impact — without breaking 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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+### What this is
+
+- A **Claude Code workflow audit and improvement tool** — not an MCP installer, not a code generator
+- Scores your repo 0-100 across CLAUDE.md, hooks, commands, agents, skills, MCP, security, and more
+- Proposes changes as diffs you review — applies only what you approve, with rollback for every change
+- Includes governance (permission profiles, hook registry, policy packs) and benchmark (isolated before/after)
+
+### What this is NOT
+
+- Not an MCP setup tool (MCP packs are one of 26 features, not the product)
+- Not a code generator or refactoring tool — it configures how Claude works with your repo, not the code itself
+- Not a replacement for hand-crafted CLAUDE.md — generated output is a strong starting point, not a final answer
+- Not a score you should chase blindly — 90/100 with bad code is still bad code
+
 ## Quick Start
 
 ```bash
+npx claudex-setup --lite      # Quick beginner scan: top 3 fixes + next command
 npx claudex-setup              # Audit your project (10 seconds)
+npx claudex-setup --snapshot   # Save a normalized snapshot under .claude/claudex-setup/
 npx claudex-setup setup        # Create a starter-safe baseline
 npx claudex-setup augment      # Repo-aware plan, no writes
 npx claudex-setup plan         # Export proposal bundles with file previews
 npx claudex-setup governance   # See permission profiles, packs, and pilot guidance
+npx claudex-setup governance --out governance.md  # Export a shareable governance report
 npx claudex-setup benchmark    # Measure before/after in an isolated temp copy
 npx claudex-setup --threshold 60   # Fail CI if score is below 60
 ```
@@ -41,18 +58,35 @@ No install. No config. No dependencies.
      CI pipeline configured
      → Add .github/workflows/ for automated testing
 
-  ⚡ Best next fixes
+  ⚡ Top 5 Next Actions
      1. Add CLAUDE.md verification criteria
+        Why: Claude needs an explicit verification loop before handoff
+        Trace: failed-check:verificationLoop | impact:critical | category:quality
+        Risk: high | Confidence: high
+        Fix: Add test/lint/build commands to CLAUDE.md so Claude can verify its own work
+
      2. Configure safe permissions + deny rules
+        Why: Explicit permissions are the main safety layer for repo writes
+        Trace: failed-check:permissionDeny | impact:high | category:security
+        Risk: medium | Confidence: high
+        Fix: Add permissions.deny rules to block dangerous operations
 
   Weakest areas:
       design: none (0/2)
      devops: none (0/4)
 
   29/62 checks passing
-  Run npx claudex-setup setup to create a starter-safe baseline
+  Next command: npx claudex-setup setup
+```
+
+Want the shortest possible first run?
+
+```bash
+npx claudex-setup --lite
 ```
 
+That prints a compact top-3 quick scan with one clear next command.
+
 ## All Commands
 
 | Command | What it does |
@@ -84,6 +118,8 @@ No install. No config. No dependencies.
 | `--only A,B` | Limit plan/apply to selected proposal ids |
 | `--profile NAME` | Choose a permission profile for write-capable flows |
 | `--mcp-pack A,B` | Merge named MCP packs into generated or patched settings |
+| `--snapshot` | Save a normalized artifact under `.claude/claudex-setup/snapshots/` |
+| `--lite` | Show a short top-3 quick scan with one clear next command |
 | `--dry-run` | Preview apply without writing files |
 | `--verbose` | Show all recommendations (not just critical/high) |
 | `--json` | Machine-readable JSON output (for CI) |
@@ -141,6 +177,7 @@ Use `governance` when the question is "can we pilot this safely?" instead of "wh
 
 ```bash
 npx claudex-setup governance
+npx claudex-setup governance --out governance.md
 ```
 
 It exposes:
@@ -152,6 +189,8 @@ It exposes:
 - 26 MCP packs: Context7, Next.js devtools, GitHub, PostgreSQL, Playwright, Docker, Notion, Linear, Sentry, Slack, Stripe, Figma, Shopify, Hugging Face, Blender, WordPress, Jira/Confluence, GA4, Search Console, n8n, Zendesk, Infisical, Composio, memory, sequential-thinking, mcp-security
 - a pilot rollout kit with scope, approvals, success metrics, and rollback expectations
 
+Use `--out governance.md` if you want a shareable artifact for leads, platform teams, or security review.
+
 ## Domain Packs And MCP Packs
 
 `augment` and `suggest-only` now recommend repo-shaped guidance instead of giving every project the same advice.
@@ -181,6 +220,31 @@ Benchmark mode:
 - applies starter-safe artifacts only in the copy
 - reruns the audit and emits before/after deltas, workflow-evidence coverage, a case-study summary, and an executive recommendation
 
+If you want repeatable evidence artifacts for before/after work, add `--snapshot` to `audit`, `augment`, `suggest-only`, `benchmark`, or `governance`.
+
+```bash
+npx claudex-setup --snapshot
+npx claudex-setup augment --snapshot
+npx claudex-setup benchmark --snapshot
+```
+
+Snapshots are written to `.claude/claudex-setup/snapshots/` with a shared envelope and an `index.json` history file.
+
+## Use Inside Claude Code
+
+If you want the first Claude-native entry point, copy the shipped skill template into your repo.
+
+If `claudex-setup` is installed locally in `node_modules`, use:
+
+```bash
+mkdir -p .claude/skills/audit-repo
+cp ./node_modules/claudex-setup/content/claude-code/audit-repo/SKILL.md .claude/skills/audit-repo/SKILL.md
+```
+
+If you are using `npx` only, copy the same file from the GitHub repo at `content/claude-code/audit-repo/SKILL.md`.
+
+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
 
 The exact applicable count can be lower on a given repo because stack-specific checks are skipped when they do not apply.
@@ -204,16 +268,16 @@ The exact applicable count can be lower on a given repo because stack-specific c
 
 ## Stack Detection
 
-Auto-detects and tailors output for 18 stacks:
+Auto-detects and tailors output for 22 stacks:
 
 | | |
 |--|--|
 | **Frontend** | React, Vue, Angular, Next.js, Svelte |
 | **Backend** | Node.js, Python, Django, FastAPI |
 | **Mobile** | Flutter, Swift, Kotlin |
-| **Systems** | Rust, Go, Java, Ruby |
+| **Systems** | Rust, Go, Java, Ruby, C++, Bazel |
 | **Language** | TypeScript |
-| **Infra** | Docker |
+| **Infra** | Docker, Terraform, Kubernetes |
 
 ## GitHub Action
 
@@ -227,7 +291,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.10.0
+      - uses: DnaFin/claudex-setup@v1.10.3
         with:
           threshold: 50
 ```
@@ -288,7 +352,7 @@ 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
 
-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.
+The catalog includes 1,107 entries (features, techniques, patterns, tools, stats, and known limitations) — not all are actionable checks. 948 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.
 

package/bin/cli.js

@@ -4,8 +4,9 @@ const { audit } = require('../src/audit');
 const { setup } = require('../src/setup');
 const { analyzeProject, printAnalysis, exportMarkdown } = require('../src/analyze');
 const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBundle, printApplyResult } = require('../src/plans');
-const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile } = require('../src/governance');
+const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile, renderGovernanceMarkdown } = require('../src/governance');
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
+const { writeSnapshotArtifact } = require('../src/activity');
 const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -133,6 +134,7 @@ const HELP = `
 
   Usage:
     npx claudex-setup                  Run audit on current directory
+    npx claudex-setup --lite           Run the quick-scan beginner view
     npx claudex-setup discover         Discover the highest-value improvements
     npx claudex-setup audit            Same as above
     npx claudex-setup starter          Alias for setup
@@ -156,6 +158,8 @@ const HELP = `
     --only A,B      Limit plan/apply to selected proposal ids or technique keys
     --profile NAME  Choose permission profile (read-only, suggest-only, safe-write, power-user, internal-research)
     --mcp-pack A,B  Merge named MCP packs into generated settings (e.g. context7-docs,next-devtools)
+    --snapshot      Save a normalized snapshot artifact under .claude/claudex-setup/snapshots/
+    --lite          Show a short top-3 quick scan with one clear next command
     --dry-run       Preview apply without writing files
     --verbose       Show all recommendations (not just critical/high)
     --json          Output as JSON (for CI pipelines)
@@ -166,8 +170,12 @@ const HELP = `
 
   Examples:
     npx claudex-setup
+    npx claudex-setup --lite
+    npx claudex-setup --snapshot
     npx claudex-setup augment
+    npx claudex-setup augment --snapshot
     npx claudex-setup suggest-only --json
+    npx claudex-setup governance --snapshot
     npx claudex-setup plan --out claudex-plan.json
     npx claudex-setup plan --profile safe-write
     npx claudex-setup setup --mcp-pack context7-docs
@@ -210,6 +218,8 @@ async function main() {
     verbose: flags.includes('--verbose'),
     json: flags.includes('--json'),
     auto: flags.includes('--auto'),
+    lite: flags.includes('--lite'),
+    snapshot: flags.includes('--snapshot'),
     dryRun: flags.includes('--dry-run'),
     threshold: parsed.threshold !== null ? Number(parsed.threshold) : null,
     out: parsed.out,
@@ -295,6 +305,9 @@ async function main() {
       return; // keep process alive for http
     } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
       const report = await analyzeProject({ ...options, mode: normalizedCommand });
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, normalizedCommand, report, {
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out && !options.json) {
         const fs = require('fs');
         const md = exportMarkdown(report);
@@ -302,6 +315,11 @@ async function main() {
         console.log(`\n  Report exported to ${options.out}\n`);
       }
       printAnalysis(report, options);
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
     } else if (normalizedCommand === 'plan') {
       const bundle = await buildProposalBundle(options);
       let artifact = null;
@@ -320,10 +338,34 @@ async function main() {
       const result = await applyProposalBundle(options);
       printApplyResult(result, options);
     } else if (normalizedCommand === 'governance') {
+      const fs = require('fs');
+      const path = require('path');
       const summary = getGovernanceSummary();
+      if (options.out) {
+        fs.mkdirSync(path.dirname(options.out), { recursive: true });
+        const content = path.extname(options.out).toLowerCase() === '.md'
+          ? renderGovernanceMarkdown(summary)
+          : JSON.stringify(summary, null, 2);
+        fs.writeFileSync(options.out, content, 'utf8');
+      }
       printGovernanceSummary(summary, options);
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'governance', summary, {
+        sourceCommand: normalizedCommand,
+      }) : null;
+      if (options.out && !options.json) {
+        console.log(`  Governance report written to ${options.out}`);
+        console.log('');
+      }
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
     } else if (normalizedCommand === 'benchmark') {
       const report = await runBenchmark(options);
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'benchmark', report, {
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out) {
         writeBenchmarkReport(report, options.out);
       }
@@ -332,6 +374,11 @@ async function main() {
         console.log(`  Benchmark report written to ${options.out}`);
         console.log('');
       }
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
     } else if (normalizedCommand === 'deep-review') {
       const { deepReview } = require('../src/deep-review');
       await deepReview(options);
@@ -345,6 +392,14 @@ async function main() {
       await setup(options);
     } else {
       const result = await audit(options);
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'audit', result, {
+        sourceCommand: normalizedCommand,
+      }) : null;
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
       if (options.threshold !== null && result.score < options.threshold) {
         if (!options.json) {
           console.error(`  Threshold failed: score ${result.score}/100 is below required ${options.threshold}/100.\n`);

package/content/case-study-template.md

@@ -0,0 +1,91 @@
+# Case Study: [Project Name]
+
+## Overview
+
+| Field | Value |
+|-------|-------|
+| Project | [name] |
+| Repo type | [e.g., backend API, frontend SPA, monorepo, data pipeline] |
+| Team size | [e.g., solo, 3 developers, 15-person team] |
+| Prior Claude setup | [none / basic CLAUDE.md / mature .claude/ config] |
+| Claudex Setup version | [e.g., 1.9.0] |
+| Date | [YYYY-MM-DD] |
+
+## Before State
+
+**Audit score:** [X/100]
+**Organic score:** [X/100]
+
+What existed before running claudex-setup:
+- [ ] CLAUDE.md
+- [ ] .claude/settings.json
+- [ ] Custom commands
+- [ ] Rules
+- [ ] Hooks
+- [ ] Agents
+- [ ] MCP servers
+
+Key observations:
+- [What was good already]
+- [What was missing]
+- [What was risky or misconfigured]
+
+## What We Did
+
+**Mode used:** [discover / starter / augment / plan+apply / suggest-only]
+
+**Steps:**
+1. Ran `npx claudex-setup discover` to understand current state
+2. [Next step]
+3. [Next step]
+
+**Domain pack matched:** [e.g., backend-api]
+**MCP packs recommended:** [e.g., context7-docs, postgres-mcp]
+
+## Changes Applied
+
+| Change | Type | Risk | Applied? |
+|--------|------|------|----------|
+| [e.g., Created CLAUDE.md with architecture] | new file | low | yes |
+| [e.g., Added hooks for auto-lint] | new config | medium | yes |
+| [e.g., Added permission deny rules] | security | low | yes |
+
+**Strengths preserved:**
+- [What we explicitly kept unchanged]
+
+## After State
+
+**Audit score:** [X/100] (was [X/100])
+**Organic score:** [X/100] (was [X/100])
+**Score improvement:** +[X] points
+
+## Measured Impact
+
+| Metric | Before | After | Change |
+|--------|--------|-------|--------|
+| Audit score | X | X | +X |
+| Checks passing | X/58 | X/58 | +X |
+| Time to first productive session | Xm | Xm | -Xm |
+| [Other metric] | | | |
+
+## What Worked Well
+
+- [Specific thing that added clear value]
+- [Another]
+
+## What Could Be Better
+
+- [Specific improvement suggestion for the tool]
+- [Another]
+
+## Verdict
+
+**Would recommend:** [Yes / Yes with caveats / Not yet]
+
+**Best for:** [Who should try this based on our experience]
+
+**One-line summary:** [e.g., "Took our Claude setup from basic to production-ready in 15 minutes with zero breakage."]
+
+---
+
+*Generated with claudex-setup v[version]. Case study template from CLAUDEX.*

package/content/claims-governance.md

@@ -0,0 +1,37 @@
+# Claims Governance
+
+Use this checklist before publishing product-facing claims about Claudex Setup.
+
+## Allowed only with evidence
+
+- score delta claims
+- organic score delta claims
+- time-to-value claims
+- recommendation acceptance rate claims
+- reduction in manual corrections
+- benchmark outcomes on named repo types
+
+## Evidence standard
+
+Every claim should have:
+
+- a benchmark run or pilot report
+- the repo type or cohort it applies to
+- the date the evidence was collected
+- the exact metric definition
+- the comparison method (`before/after`, `control/pilot`, or `observed over time`)
+
+## Avoid
+
+- universal productivity multipliers
+- unsupported token savings claims
+- “works for every repo” language
+- suspiciously precise numbers without a method section
+- implying quality scores are objective truth rather than framework coverage
+
+## Safer phrasing
+
+- "In benchmark mode, this repo improved from 41/100 to 60/100."
+- "Starter-safe artifacts improved readiness on an isolated temp copy."
+- "Suggest-only mode gives mature teams a zero-write review path."
+- "Use governance mode to select permission profiles and inspect shipped hooks."

package/content/claude-code/audit-repo/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: audit-repo
+description: Run claudex-setup on the current repo and summarize the score, top gaps, and next command
+---
+
+Run `npx claudex-setup --json` in the current project directory and summarize the result.
+
+Your output should include:
+
+1. The overall score and organic score
+2. The top 3 next actions from `topNextActions`
+3. The suggested next command from `suggestedNextCommand`
+4. A short explanation of what the repo already does well if there are notable strengths
+
+Behavior rules:
+
+- If the user asks for the shortest version, run `npx claudex-setup --lite`
+- If the user wants deeper no-write analysis, run `npx claudex-setup augment --json`
+- If the score is below 50, explicitly recommend `npx claudex-setup setup`
+- Never apply changes automatically from this skill

package/content/devto-article.json

@@ -0,0 +1,9 @@
+{
+  "article": {
+    "title": "Your Claude Code project scores 10/100. Here's how to fix it in 60 seconds.",
+    "published": false,
+    "tags": ["claude", "ai", "productivity", "devtools"],
+    "series": "Claude Code Optimization",
+    "body_markdown": "After cataloging **1,107 Claude Code entries** and verifying **948 with real evidence**, I found that most projects use barely 10% of what's available.\n\nI built a CLI that scores your project:\n\n```bash\nnpx claudex-setup\n```\n\nMost projects score **10-20 out of 100**. After running setup, they jump to **70+**.\n\n## The Top 10 Things You're Missing\n\n### 1. CLAUDE.md (Critical)\n\nClaude reads this file at the start of every session. Without it, Claude doesn't know your build commands, code style, or project rules.\n\nOur tool generates a smart CLAUDE.md that detects your framework, TypeScript config, and creates a Mermaid architecture diagram automatically.\n\n### 2. Mermaid Architecture Diagrams (73% Token Savings)\n\nA Mermaid diagram in CLAUDE.md gives Claude your project structure in a fraction of the tokens that prose requires.\n\n### 3. Hooks > CLAUDE.md Rules (100% vs 80%)\n\nCLAUDE.md instructions are advisory (~80% compliance). Hooks are deterministic (100%). Auto-lint after every edit. Every time.\n\n### 4. Custom Commands\n\nStop typing the same prompts. Create `/test`, `/deploy`, `/review` in `.claude/commands/`.\n\n### 5. Verification Loops (The #1 Best Practice)\n\n> *This is the single highest-leverage thing you can do.* — Anthropic Best Practices\n\nClaude performs dramatically better when it can verify its own work.\n\n### 6. XML Tags (30% Quality Boost)\n\nUse `<constraints>`, `<validation>` in CLAUDE.md for unambiguous instructions.\n\n### 7. Secrets Protection\n\nClaude Code loads `.env` automatically. Add deny rules to prevent reading sensitive files.\n\n### 8. /security-review\n\nBuilt-in OWASP Top 10 scanning. Most people don't know this command exists.\n\n### 9. Custom Agents\n\nSpecialized subagents: security-reviewer, test-writer in `.claude/agents/`.\n\n### 10. Skills (On-Demand Knowledge)\n\nReusable skills package expertise that Claude can load on demand.\n\n## Try It Now\n\n```bash\nnpx claudex-setup --lite       # Quick scan\nnpx claudex-setup              # Full audit\nnpx claudex-setup --snapshot   # Save evidence artifact\nnpx claudex-setup governance --out governance.md\n```\n\nFree, open source, zero dependencies.\n\n**GitHub:** [github.com/DnaFin/claudex-setup](https://github.com/DnaFin/claudex-setup)\n**npm:** [npmjs.com/package/claudex-setup](https://www.npmjs.com/package/claudex-setup)\n\n---\n\n*Built from a research catalog of 1,107 Claude Code entries, 948 verified with evidence.*"
+  }
+}

package/content/launch-posts.md

@@ -0,0 +1,160 @@
+# Launch Posts — Ready to Publish
+
+## Post 1: Reddit r/ClaudeAI
+
+**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.
+
+Most projects score around 10-20/100. After running setup, they jump to 70+.
+
+```
+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.
+
+GitHub: https://github.com/DnaFin/claudex-setup
+
+Would love feedback!
+
+---
+
+## Post 2: Reddit r/ChatGPTCoding
+
+**Title:** Your Claude Code project is probably running at 10% efficiency. Here's how to check.
+
+**Body:**
+I spent weeks cataloging every Claude Code feature, technique, and best practice — 1,107 total, 948 verified with real evidence.
+
+Turns out most projects are missing basic stuff that makes a huge difference:
+- No CLAUDE.md (Claude doesn't know your project conventions)
+- No hooks (no auto-lint, no auto-test)
+- No custom commands (repeating the same prompts manually)
+- No Mermaid diagrams (wasting 73% more tokens on prose descriptions)
+
+Built a quick checker:
+```
+npx claudex-setup
+```
+
+Scores your project 0-100, tells you exactly what to fix, and can auto-apply everything.
+
+Free, open source, zero dependencies: https://github.com/DnaFin/claudex-setup
+
+---
+
+## Post 3: Dev.to Article
+
+**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.
+
+Here are the top 10 things most developers are missing:
+
+1. **CLAUDE.md** — Claude reads this at the start of every session. Without it, Claude doesn't know your build commands, code style, or project rules.
+
+2. **Mermaid diagrams** — A Mermaid architecture diagram saves 73% tokens compared to describing your project in prose.
+
+3. **Hooks** — Auto-lint after every edit. Auto-test before every commit. Hooks fire 100% of the time, CLAUDE.md rules fire ~80%.
+
+4. **Custom commands** — `/test`, `/deploy`, `/review` — package your repeated workflows.
+
+5. **Verification loops** — Tell Claude how to verify its own work. Include test commands in CLAUDE.md.
+
+6. **Path-specific rules** — Different conventions for frontend vs backend files.
+
+7. **XML tags** — `<constraints>`, `<validation>` in CLAUDE.md = unambiguous instructions.
+
+8. **Custom agents** — Security reviewer, test writer — specialized subagents for focused tasks.
+
+9. **Skills** — Domain-specific workflows that load on demand, not every session.
+
+10. **MCP servers** — Connect Claude to your database, ticket system, Slack.
+
+I packaged this into a CLI that checks your project:
+```
+npx claudex-setup
+```
+
+Full catalog: https://github.com/DnaFin/claudex-setup
+
+---
+
+## Post 4: Twitter/X Thread
+
+**Tweet 1:**
+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:
+
+npx claudex-setup
+
+Thread 🧵👇
+
+**Tweet 2:**
+The #1 thing you're probably missing: CLAUDE.md
+
+It's a file Claude reads at the start of every session. Without it, Claude doesn't know your:
+- Build commands
+- Code style
+- Testing framework
+- Project architecture
+
+Takes 2 minutes to create. Impact: massive.
+
+**Tweet 3:**
+#2: Mermaid diagrams in CLAUDE.md
+
+A few hundred tokens of Mermaid syntax conveys what takes thousands of tokens in prose.
+
+73% token savings = faster responses, lower cost, better context.
+
+**Tweet 4:**
+#3: Hooks > CLAUDE.md rules
+
+CLAUDE.md instructions = ~80% compliance
+Hooks = 100% enforcement
+
+Auto-lint after edits. Block commits without tests. Prevent force-push.
+
+Hooks are deterministic. Instructions are advisory.
+
+**Tweet 5:**
+Want to check your project in 10 seconds?
+
+npx claudex-setup
+
+Scores 0-100. Shows what's missing. Auto-fixes with `setup`.
+
+Free. Open source. Zero dependencies.
+
+https://github.com/DnaFin/claudex-setup
+
+---
+
+## Post 5: Hacker News (Show HN)
+
+**Title:** Show HN: claudex-setup – Audit any project for Claude Code optimization (1,107 entries)
+
+**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.
+
+npx claudex-setup → audit (0-100 score)
+npx claudex-setup setup → auto-fix
+
+Detects your stack (React, Python, TS, Rust, Go, etc) and tailors recommendations.
+
+Zero dependencies, no API keys, runs locally.
+
+https://github.com/DnaFin/claudex-setup