claudex-setup 1.10.2 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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.11.0] - 2026-04-03
+
+### Added
+- `history` command — show score timeline from saved snapshots
+- `compare` command — diff latest vs previous snapshot with delta, regressions, improvements
+- `trend --out report.md` — export trend report as shareable markdown
+- `--require A,B` CI flag — exit code 1 if named checks fail (policy guardrails)
+- Agentic DX positioning in README
+- Real results table (4 case studies) in README
+- Claude-native integration guide (skill, hook, agent examples)
+- Trust-first help text reordering
+
+### Fixed
+- Hook checks (hooksInSettings, preToolUse, postToolUse, sessionStart) now OR across settings.json and settings.local.json
+
 ## [1.10.2] - 2026-04-02
 
 ### Fixed
@@ -11,6 +41,12 @@
 - 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,25 +1,56 @@
 # 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
+
+- The **Agentic DX layer for Claude Code** — audit, improve, govern, and benchmark how Claude works with your repo
+- 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
 ```
 
 No install. No config. No dependencies.
 
+## Real Results
+
+Tested on 4 real projects — not demos:
+
+| Project | Type | Before | After | Delta |
+|---------|------|--------|-------|-------|
+| CLAUDEX | Research engine, Python | 62 | 90 | **+28** |
+| VTCLE | Marketing automation, FastAPI | 46 | 64 | **+18** |
+| Social | Mobile app, React Native | 40 | 48 | **+8** |
+| Polymiro | Prediction system, Python/Docker | 35 | 48 | **+13** |
+
+Most common gaps found: missing secrets protection, no deny rules, no mermaid diagram, no hooks in settings.
+
 ## What You Get
 
 ```
@@ -41,18 +72,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 +132,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 +191,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 +203,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 +234,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.
@@ -227,7 +305,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.10.2
+      - uses: DnaFin/claudex-setup@v1.11.0
         with:
           threshold: 50
 ```
@@ -288,7 +366,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);
@@ -18,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', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -60,12 +61,13 @@ function parseArgs(rawArgs) {
   let only = [];
   let profile = 'safe-write';
   let mcpPacks = [];
+  let requireChecks = [];
   let commandSet = false;
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack') {
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -76,10 +78,16 @@ function parseArgs(rawArgs) {
       if (arg === '--only') only = value.split(',').map(item => item.trim()).filter(Boolean);
       if (arg === '--profile') profile = value.trim();
       if (arg === '--mcp-pack') mcpPacks = value.split(',').map(item => item.trim()).filter(Boolean);
+      if (arg === '--require') requireChecks = value.split(',').map(item => item.trim()).filter(Boolean);
       i++;
       continue;
     }
 
+    if (arg.startsWith('--require=')) {
+      requireChecks = arg.split('=').slice(1).join('=').split(',').map(item => item.trim()).filter(Boolean);
+      continue;
+    }
+
     if (arg.startsWith('--threshold=')) {
       threshold = arg.split('=')[1];
       continue;
@@ -123,39 +131,48 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks };
 }
 
 const HELP = `
   claudex-setup v${version}
-  Audit and optimize any project for Claude Code.
-  Backed by CLAUDEX research and evidence.
-
-  Usage:
-    npx claudex-setup                  Run audit on current directory
-    npx claudex-setup discover         Discover the highest-value improvements
-    npx claudex-setup audit            Same as above
-    npx claudex-setup starter          Alias for setup
-    npx claudex-setup setup            Apply recommended configuration
-    npx claudex-setup setup --auto     Apply all without prompts
-    npx claudex-setup augment          Repo-aware augment plan (no writes)
-    npx claudex-setup suggest-only     Structured suggestion report (no writes)
-    npx claudex-setup plan             Exportable proposal bundles with file previews
-    npx claudex-setup apply            Apply ready proposal bundles with rollback manifest
-    npx claudex-setup governance       Profiles, hooks, and pilot rollout guidance
-    npx claudex-setup benchmark        Measure before/after impact in an isolated temp copy
-    npx claudex-setup deep-review      AI-powered config review (uses Claude Code or API key)
+  Score your repo's Claude Code setup. Fix gaps safely. Benchmark the impact.
+
+  Start here (read-only, nothing changes):
+    npx claudex-setup                  Audit your project (10 seconds)
+    npx claudex-setup --lite           Quick scan: top 3 gaps + next command
+    npx claudex-setup augment          Repo-aware analysis, no writes
+    npx claudex-setup suggest-only     Structured report, no writes
+
+  Plan and apply (when you're ready to change things):
+    npx claudex-setup plan             Export proposal bundles with previews
+    npx claudex-setup apply            Apply proposals selectively with rollback
+    npx claudex-setup setup            Generate starter-safe baseline
+    npx claudex-setup setup --auto     Apply all generated files without prompts
+
+  Track progress over time:
+    npx claudex-setup history          Show score history from saved snapshots
+    npx claudex-setup compare          Compare latest vs previous snapshot
+    npx claudex-setup trend --out r.md Export trend report as markdown
+
+  Advanced:
+    npx claudex-setup governance       Permission profiles, hooks, policy packs
+    npx claudex-setup benchmark        Before/after in isolated temp copy
+    npx claudex-setup deep-review      AI-powered config review (opt-in, uses API)
     npx claudex-setup interactive      Step-by-step guided wizard
-    npx claudex-setup watch            Monitor changes and re-audit live
+    npx claudex-setup watch            Live monitoring on config changes
     npx claudex-setup badge            Generate shields.io badge markdown
 
   Options:
     --threshold N   Exit with code 1 if score is below N (useful for CI)
+    --require A,B   Exit with code 1 if named checks fail (e.g. --require secretsProtection,permissionDeny)
     --out FILE      Write JSON or markdown output to a file
     --plan FILE     Load a previously exported plan file
     --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 +183,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 +231,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,
@@ -217,6 +240,7 @@ async function main() {
     only: parsed.only,
     profile: parsed.profile,
     mcpPacks: parsed.mcpPacks,
+    require: parsed.requireChecks,
     dir: process.cwd()
   };
 
@@ -251,7 +275,48 @@ async function main() {
   }
 
   try {
-    if (normalizedCommand === 'badge') {
+    if (normalizedCommand === 'history') {
+      const { formatHistory } = require('../src/activity');
+      console.log('');
+      console.log(formatHistory(options.dir));
+      console.log('');
+      process.exit(0);
+    } else if (normalizedCommand === 'compare') {
+      const { compareLatest } = require('../src/activity');
+      const result = compareLatest(options.dir);
+      if (!result) {
+        console.log('\n  Need at least 2 snapshots to compare. Run `npx claudex-setup --snapshot` twice.\n');
+        process.exit(0);
+      }
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const sign = result.delta.score >= 0 ? '+' : '';
+        console.log('');
+        console.log(`  Previous: ${result.previous.score}/100 (${result.previous.date?.split('T')[0]})`);
+        console.log(`  Current:  ${result.current.score}/100 (${result.current.date?.split('T')[0]})`);
+        console.log(`  Delta:    ${sign}${result.delta.score} points`);
+        console.log(`  Trend:    ${result.trend}`);
+        if (result.improvements.length > 0) console.log(`  Fixed:    ${result.improvements.join(', ')}`);
+        if (result.regressions.length > 0) console.log(`  New gaps: ${result.regressions.join(', ')}`);
+        console.log('');
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'trend') {
+      const { exportTrendReport } = require('../src/activity');
+      const report = exportTrendReport(options.dir);
+      if (!report) {
+        console.log('\n  No snapshots found. Run `npx claudex-setup --snapshot` to start tracking.\n');
+        process.exit(0);
+      }
+      if (options.out) {
+        require('fs').writeFileSync(options.out, report, 'utf8');
+        console.log(`\n  Trend report exported to ${options.out}\n`);
+      } else {
+        console.log(report);
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'badge') {
       const { getBadgeMarkdown } = require('../src/badge');
       const result = await audit({ ...options, silent: true });
       console.log(getBadgeMarkdown(result.score));
@@ -295,6 +360,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 +370,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 +393,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 +429,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,12 +447,33 @@ 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`);
         }
         process.exit(1);
       }
+      if (options.require && options.require.length > 0) {
+        const failedRequired = options.require.filter(key => {
+          const check = result.results.find(r => r.key === key);
+          return !check || check.passed !== true;
+        });
+        if (failedRequired.length > 0) {
+          if (!options.json) {
+            console.error(`\n  Required checks failed: ${failedRequired.join(', ')}`);
+            console.error('  These must pass for CI to succeed.\n');
+          }
+          process.exit(1);
+        }
+      }
     }
   } catch (err) {
     console.error(`\n  Error: ${err.message}`);

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