@nerviq/cli 1.0.0 → 1.2.0

package/src/workspace.js

@@ -0,0 +1,233 @@
+const fs = require('fs');
+const path = require('path');
+
+function normalizePath(value) {
+  return value.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function unique(items) {
+  return [...new Set(items.filter(Boolean).map(normalizePath))];
+}
+
+function hasWorkspaceConfig(dir) {
+  return [
+    'turbo.json',
+    'lerna.json',
+    'pnpm-workspace.yaml',
+  ].some((file) => fs.existsSync(path.join(dir, file))) ||
+    Boolean(readJsonSafe(path.join(dir, 'package.json'))?.workspaces);
+}
+
+function packageWorkspacePatterns(dir) {
+  const pkg = readJsonSafe(path.join(dir, 'package.json')) || {};
+  const workspaces = pkg.workspaces;
+
+  if (Array.isArray(workspaces)) {
+    return workspaces;
+  }
+
+  if (workspaces && Array.isArray(workspaces.packages)) {
+    return workspaces.packages;
+  }
+
+  return [];
+}
+
+function lernaWorkspacePatterns(dir) {
+  const lerna = readJsonSafe(path.join(dir, 'lerna.json')) || {};
+  return Array.isArray(lerna.packages) ? lerna.packages : [];
+}
+
+function pnpmWorkspacePatterns(dir) {
+  const content = readTextSafe(path.join(dir, 'pnpm-workspace.yaml'));
+  if (!content) return [];
+
+  const matches = [];
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*-\s*["']?([^"']+)["']?\s*$/);
+    if (match) {
+      matches.push(match[1]);
+    }
+  }
+  return matches;
+}
+
+function turboWorkspacePatterns(dir) {
+  if (!fs.existsSync(path.join(dir, 'turbo.json'))) {
+    return [];
+  }
+
+  const commonPatterns = [];
+  for (const candidate of ['apps', 'packages', 'services']) {
+    if (fs.existsSync(path.join(dir, candidate)) && fs.statSync(path.join(dir, candidate)).isDirectory()) {
+      commonPatterns.push(`${candidate}/*`);
+    }
+  }
+
+  return commonPatterns;
+}
+
+function listDirectories(rootDir) {
+  const found = [];
+  const queue = [''];
+
+  while (queue.length > 0) {
+    const relative = queue.shift();
+    const full = path.join(rootDir, relative);
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(full, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.next' || entry.name === 'dist') continue;
+      const child = normalizePath(path.join(relative, entry.name));
+      found.push(child);
+      queue.push(child);
+    }
+  }
+
+  return found;
+}
+
+function globToRegExp(pattern) {
+  const normalized = normalizePath(pattern)
+    .replace(/\*\*/g, '__DOUBLE_STAR__')
+    .replace(/\*/g, '__SINGLE_STAR__')
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/__DOUBLE_STAR__/g, '.*')
+    .replace(/__SINGLE_STAR__/g, '[^/]+');
+  return new RegExp(`^${normalized}$`);
+}
+
+function expandWorkspacePatterns(dir, patterns) {
+  const normalizedPatterns = unique(Array.isArray(patterns) ? patterns : []);
+  if (normalizedPatterns.length === 0) {
+    return [];
+  }
+
+  const allDirs = listDirectories(dir);
+  const matches = [];
+
+  for (const pattern of normalizedPatterns) {
+    const fullPath = path.join(dir, pattern);
+    if (!pattern.includes('*') && fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory()) {
+      matches.push(normalizePath(pattern));
+      continue;
+    }
+
+    const matcher = globToRegExp(pattern);
+    for (const candidate of allDirs) {
+      if (matcher.test(candidate)) {
+        matches.push(candidate);
+      }
+    }
+  }
+
+  return unique(matches);
+}
+
+function detectWorkspaceGlobs(dir) {
+  return unique([
+    ...packageWorkspacePatterns(dir),
+    ...lernaWorkspacePatterns(dir),
+    ...pnpmWorkspacePatterns(dir),
+    ...turboWorkspacePatterns(dir),
+  ]);
+}
+
+function detectWorkspaces(dir) {
+  return expandWorkspacePatterns(dir, detectWorkspaceGlobs(dir));
+}
+
+function parseWorkspaceSelection(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return unique(value);
+  return unique(String(value).split(',').map((item) => item.trim()).filter(Boolean));
+}
+
+async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
+  const { audit } = require('./audit');
+  const rootDir = path.resolve(dir);
+  const selectedPatterns = parseWorkspaceSelection(workspaceGlobs);
+  const sourcePatterns = selectedPatterns.length > 0 ? selectedPatterns : detectWorkspaceGlobs(rootDir);
+  const workspacePaths = selectedPatterns.length > 0
+    ? expandWorkspacePatterns(rootDir, selectedPatterns)
+    : detectWorkspaces(rootDir);
+  const results = [];
+
+  for (const workspacePath of workspacePaths) {
+    const absPath = path.join(rootDir, workspacePath);
+    try {
+      const result = await audit({ dir: absPath, platform, silent: true });
+      results.push({
+        name: path.basename(workspacePath),
+        workspace: workspacePath,
+        dir: absPath,
+        platform,
+        score: result.score,
+        passed: result.passed,
+        total: result.checkCount,
+        topAction: result.topNextActions?.[0]?.name || null,
+        result,
+      });
+    } catch (error) {
+      results.push({
+        name: path.basename(workspacePath),
+        workspace: workspacePath,
+        dir: absPath,
+        platform,
+        score: null,
+        passed: 0,
+        total: 0,
+        topAction: null,
+        error: error.message,
+      });
+    }
+  }
+
+  const validScores = results.filter((item) => typeof item.score === 'number').map((item) => item.score);
+  const averageScore = validScores.length > 0
+    ? Math.round(validScores.reduce((sum, value) => sum + value, 0) / validScores.length)
+    : 0;
+
+  return {
+    rootDir,
+    platform,
+    patterns: sourcePatterns,
+    workspaces: results,
+    detectedWorkspaces: workspacePaths,
+    workspaceCount: workspacePaths.length,
+    averageScore,
+    maxScore: validScores.length > 0 ? Math.max(...validScores) : 0,
+    minScore: validScores.length > 0 ? Math.min(...validScores) : 0,
+  };
+}
+
+module.exports = {
+  hasWorkspaceConfig,
+  detectWorkspaceGlobs,
+  detectWorkspaces,
+  parseWorkspaceSelection,
+  auditWorkspaces,
+};

package/CHANGELOG.md

@@ -1,198 +0,0 @@
-# Changelog
-
-## 1.0.0 — 2026-04-05
-### 🎉 First Stable Release
-- 8 platforms: Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Aider, OpenCode
-- 673 checks with sourceUrl and confidence on every check
-- Harmony: cross-platform drift detection and alignment
-- Synergy: multi-agent amplification and task routing
-- Plugin system: custom checks via nerviq.config.js
-- SDK: @nerviq/sdk with TypeScript types
-- REST API: nerviq serve --port 3000
-- MCP Server: nerviq as MCP tool provider
-- VS Code Extension
-- GitHub Action with SARIF support
-- Performance: 226ms total audit across 8 platforms
-- CLI commands: audit, setup, plan, apply, governance, benchmark, harmony-audit, synergy-report, deep-review, interactive, watch, history, compare, trend, feedback, catalog, certify, doctor, convert, migrate, serve
-- 213 tests across 21 test suites
-- AGPL-3.0 license
-
-## [1.16.2] - 2026-04-03
-
-### Changed
-- bumped the local release line to `1.16.2` so the next publish does not overwrite the already-live `1.16.1` npm release
-- synchronized README, docs, launch copy, and proof-facing state to distinguish clearly between public npm latest (`1.16.1`) and local release prep (`1.16.2`)
-
-### Fixed
-- release-truth drift across package metadata, docs, and public-facing proof references
-
-## [1.16.1] - 2026-04-03
-
-### Added
-- `feedback` command validation on the public npm package line
-- stronger secret detection coverage for Anthropic-style keys
-- deep-review sanitization and secret redaction hardening
-- watch-mode resilience improvements across recursive and non-recursive platforms
-
-### Changed
-- increased verified check count from `84` to `85`
-- proof-backed product copy and case-study traceability improvements
-
-## [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.14.0] - 2026-04-03
-
-### Added
-- Check-level test matrix: 327 verified scenarios across all 84 checks
-- Golden matrix: 12 repo profile tests with expected results
-
-### Fixed
-- `hooks` check now detects hooks in settings.json (not only .claude/hooks/ dir)
-- `context7Mcp` check now reads .mcp.json
-- `skillUsesPaths` now traverses skill subdirectories (skills/name/SKILL.md)
-- `lintCommand` now matches npm/yarn/pnpm/bun lint commands
-
-## [1.13.0] - 2026-04-03
-
-### Added
-- 10 new checks (74→84): project description, directory structure, multiple hook types, stop-failure hook, skill paths, MCP env config, gitignore local settings, .env.example, package scripts, type checking
-- 15 new tests (58→73): history/compare/trend, new checks structure, CLI commands, deny depth, negative instructions, --require flag
-- All references updated to 74→84 checks
-
-## [1.12.0] - 2026-04-03
-
-### Added
-- 12 new checks (62→74): test coverage, agent tool restrictions, auto-memory, sandbox, deny rule depth, git attribution, effort level, snapshot history, worktree, negative instructions, output style, CI variants
-- 8 new stacks (22→30): Deno, Bun, Elixir, Astro, Remix, NestJS, Laravel, .NET
-- Deeper domain detection: llamaindex, crewai, autogen, ollama for AI/ML; paypal, square, adyen, medusa for ecommerce; chromatic, style-dictionary for design; capacitor, ionic for mobile
-
-### Fixed
-- `githubActionsOrCI` check used non-existent `ctx.hasFile()` — now uses `ctx.fileContent()`
-- `.NET` stack detection no longer uses glob patterns
-
-## [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
-- 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
-- 11 new MCP packs (15→26): sequential-thinking, jira-confluence, ga4-analytics, search-console, n8n-workflows, zendesk, infisical-secrets, shopify, huggingface, blender, wordpress
-- 7 new domain packs (10→17→16 final): ecommerce, ai-ml, devops-cicd, design-system, docs-content, security-focused
-- Smart recommendation for all new packs based on detected stack and domain
-- Detection logic: Storybook, Docusaurus, Stripe, LangChain, GitHub Actions, auth deps
-
-## [1.9.0] - 2026-03-31
-
-### Added
-- 3 new domain packs: `monorepo`, `mobile`, `regulated-lite` (7→10 total)
-- 3 new MCP packs: `github-mcp`, `postgres-mcp`, `memory-mcp` (2→5 total)
-- smart MCP pack recommendation based on detected domain packs
-- `suggest-only --out report.md` exports full analysis as shareable markdown
-- `why` explanations for all strengths preserved (20+ specific reasons)
-- `why` explanations for all gap findings (12+ specific reasons)
-- 5 new hooks in governance registry: duplicate-id-check, injection-defense, trust-drift-check, session-init, protect-catalog
-- case study template in `content/case-study-template.md`
-- hook risk level display in governance output (color-coded low/medium/high)
-
-### Fixed
-- **Settings hierarchy bug**: `noBypassPermissions` and `secretsProtection` checks now correctly read `.claude/settings.json` before `.claude/settings.local.json`, so personal maintainer overrides no longer fail the shared audit
-- domain pack detection now handles monorepo (nx.json, turbo.json, lerna.json, workspaces), mobile (React Native, Flutter, iOS/Android dirs), and regulated repos (SECURITY.md, compliance dirs)
-
-### Changed
-- strengths preserved section now shows 8 items (was 6) with specific value explanations
-- claudex-sync.json updated with domain pack, MCP pack, and anti-pattern counts
-
-## [1.8.0] - 2026-03-31
-
-### Added
-- domain pack recommendations for backend, frontend, data, infra, OSS, and enterprise-governed repos
-- MCP pack recommendations and merge support for `context7-docs` and `next-devtools`
-- workflow-evidence coverage in benchmark reports
-- runtime settings overlays so `apply --plan` still respects current `--profile` and `--mcp-pack` flags
-
-### Changed
-- benchmark now respects the selected profile and MCP pack options during isolated-copy runs
-- governance and suggest-only outputs now expose domain packs and MCP packs directly
-- README and docs clarify the local-vs-opt-in-network boundary for core flows vs `deep-review`
-- audit output now frames `setup` as starter-safe generation instead of an automatic full fix
-
-## [1.7.0] - 2026-03-31
-
-### Added
-- `augment` / `suggest-only` repo-aware analysis with strengths, gaps, top actions, risk notes, and rollout order
-- `plan` command for exportable proposal bundles with file previews and diff-style output
-- `apply` command for selective starter-safe apply flows with rollback manifests and activity artifacts
-- `governance` command with permission profiles, hook registry, policy packs, and pilot rollout guidance
-- `benchmark` command that measures before/after impact in an isolated temp copy and exports evidence reports
-- claims governance and pilot rollout docs in `content/`
-
-### Changed
-- `setup` now exposes reusable planning primitives and returns written/preserved file summaries
-- CLI now supports `--out`, `--plan`, `--only`, and `--dry-run`
-- README and docs now reflect the actual product surface instead of only audit/setup flows
-- benchmark and proposal workflows now preserve existing files by default and treat mature repos as review-first
-
-## [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/content/case-study-template.md

@@ -1,91 +0,0 @@
-# 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/84 | X/84 | +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

@@ -1,37 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
----
-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/claude-native-integration.md

@@ -1,60 +0,0 @@
-# Using claudex-setup from inside Claude Code
-
-## Skill: Audit Repo
-
-Add this to `.claude/skills/audit-repo.md` in any project:
-
-```markdown
----
-name: audit-repo
-description: Run claudex-setup audit on the current project and show score + top gaps
----
-
-Run `npx claudex-setup --json` on the current project directory.
-Parse the JSON output and present:
-1. Score X/100
-2. Top 3 critical/high gaps with fix descriptions
-3. Suggest next command based on score
-
-$ARGUMENTS — optional: --lite for quick scan
-```
-
-## Hook: Auto-audit on SessionStart
-
-Add to `.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "type": "command",
-        "command": "node -e \"try{const r=require('child_process').execSync('npx claudex-setup --json 2>/dev/null',{timeout:15000}).toString();const d=JSON.parse(r);if(d.score<50)console.log(JSON.stringify({systemMessage:'⚠️ Claude Code setup score: '+d.score+'/100. Consider running: npx claudex-setup --lite'}))}catch(e){console.log('{}')}\"",
-        "timeout": 20,
-        "statusMessage": "Checking Claude Code setup..."
-      }
-    ]
-  }
-}
-```
-
-## Agent: Setup Advisor
-
-Add to `.claude/agents/setup-advisor.md`:
-
-```markdown
----
-name: setup-advisor
-description: Analyzes Claude Code setup and recommends improvements
-tools: [Bash, Read, Glob, Grep]
-model: haiku
-maxTurns: 10
----
-
-You are a Claude Code setup advisor.
-
-1. Run `npx claudex-setup augment --json` on the current project
-2. Analyze gaps and strengths
-3. Recommend top 5 improvements with rationale
-4. If user approves, guide them through applying changes
-```

package/content/devto-article.json

@@ -1,9 +0,0 @@
-{
-  "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.*"
-  }
-}