claudenv 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGoldian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# claudenv
+
+One command to set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) documentation for any project.
+
+## Installation
+
+Run directly without installing — pick your package manager:
+
+```bash
+npx claudenv          # npm
+pnpm dlx claudenv     # pnpm
+bunx claudenv         # bun
+yarn dlx claudenv     # yarn
+```
+
+Or install globally:
+
+```bash
+npm i -g claudenv
+```
+
+## Quick start
+
+```bash
+cd your-project
+npx claudenv
+```
+
+Scans your project, detects the tech stack, asks a few questions, and generates everything Claude Code needs to understand your codebase.
+
+Skip the questions with `-y`:
+
+```bash
+npx claudenv -y
+```
+
+## Usage in Claude Code
+
+### Option A: Global install + shell command
+
+```bash
+npm i -g claudenv
+# Then inside Claude Code, just run:
+claudenv
+```
+
+### Option B: Slash command (auto-installed)
+
+After running `claudenv` in your project, the `.claude/commands/init-docs.md` file is created. This gives you the `/init-docs` slash command inside Claude Code, which does the same thing — analyzes the project and generates documentation.
+
+## What gets generated
+
+```
+your-project/
+├── CLAUDE.md                          # Project overview, commands, architecture
+├── _state.md                          # Track decisions and context across sessions
+├── .claude/
+│   ├── rules/
+│   │   ├── code-style.md              # Coding conventions (scoped by file paths)
+│   │   ├── testing.md                 # Testing patterns and commands
+│   │   └── workflow.md                # Claude Code best practices
+│   ├── settings.json                  # Validation hooks
+│   ├── commands/
+│   │   ├── init-docs.md               # /init-docs — regenerate docs interactively
+│   │   ├── update-docs.md             # /update-docs — refresh from current state
+│   │   └── validate-docs.md           # /validate-docs — check docs are correct
+│   ├── skills/
+│   │   └── doc-generator/             # Auto-invoked when docs need updating
+│   │       ├── SKILL.md
+│   │       ├── scripts/validate.sh
+│   │       └── templates/detection-patterns.md
+│   └── agents/
+│       └── doc-analyzer.md            # Read-only analysis subagent
+```
+
+### Key files
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Compact project overview (< 60 lines) with `@import` references to rule files |
+| `_state.md` | Tracks current focus, key decisions, known issues — persists context between sessions |
+| `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, `/clear`, subagents, git discipline |
+| `.claude/rules/code-style.md` | Language and framework-specific coding conventions |
+| `.claude/rules/testing.md` | Test framework patterns and commands |
+
+## After setup
+
+Inside Claude Code, you get three slash commands:
+
+| Command | What it does |
+|---------|-------------|
+| `/init-docs` | Re-run interactive documentation setup |
+| `/update-docs` | Scan for changes and propose doc updates |
+| `/validate-docs` | Check that documentation is complete and correct |
+
+The `doc-generator` skill auto-triggers when Claude detects your docs are outdated.
+
+## What it detects
+
+**10+ languages** and **25+ frameworks** out of the box:
+
+- **Languages**: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Java, Kotlin, C#
+- **Frameworks**: Next.js, Vite, Nuxt, SvelteKit, Astro, Angular, Django, FastAPI, Flask, Rails, Laravel, Spring Boot, and more
+- **Package managers**: npm, yarn, pnpm, bun, poetry, pipenv, uv, cargo, go modules
+- **Test frameworks**: Vitest, Jest, Playwright, Cypress, pytest, RSpec, go test, cargo test
+- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, CircleCI
+- **Linters/formatters**: ESLint, Biome, Prettier, Ruff, RuboCop, golangci-lint, Clippy
+
+## CLI reference
+
+```
+Usage: claudenv [dir] [options]
+
+Options:
+  -y, --yes        Skip prompts, use auto-detected defaults
+  --overwrite      Overwrite existing files
+  -V, --version    Show version
+  -h, --help       Show help
+
+Commands:
+  init [dir]       Interactive setup (default when no command given)
+  generate         Non-interactive generation (templates only)
+  validate         Check documentation completeness
+```
+
+## Install from source
+
+```bash
+git clone https://github.com/AGoldian/claudenv.git
+cd claudenv
+npm install
+npm link
+
+# Then in any project:
+claudenv
+```
+
+## Programmatic API
+
+```javascript
+import { detectTechStack, generateDocs, writeDocs, installScaffold } from 'claudenv';
+
+const detected = await detectTechStack('/path/to/project');
+const { files } = await generateDocs('/path/to/project', {
+  ...detected,
+  projectDescription: 'My awesome project',
+  generateRules: true,
+  generateHooks: true,
+});
+await writeDocs('/path/to/project', files);
+await installScaffold('/path/to/project');
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { resolve, join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { detectTechStack } from '../src/detector.js';
+import { generateDocs, writeDocs, installScaffold } from '../src/generator.js';
+import { validateClaudeMd, validateStructure, crossReferenceCheck } from '../src/validator.js';
+import { runExistingProjectFlow, runColdStartFlow, buildDefaultConfig } from '../src/prompts.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgJson = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('claudenv')
+  .description('One command to set up Claude Code documentation for any project')
+  .version(pkgJson.version);
+
+// --- Default action: running without subcommand triggers init ---
+program
+  .argument('[dir]', 'Project directory', '.')
+  .option('-y, --yes', 'Skip prompts, use auto-detected defaults')
+  .option('--overwrite', 'Overwrite existing files')
+  .action(runInit);
+
+// --- init (explicit subcommand, same logic) ---
+program
+  .command('init')
+  .description('Interactive setup — detect stack, ask questions, generate docs')
+  .argument('[dir]', 'Project directory', '.')
+  .option('-y, --yes', 'Skip prompts, use auto-detected defaults')
+  .option('--overwrite', 'Overwrite existing files')
+  .action(runInit);
+
+// --- generate (templates only, no scaffold, no prompts) ---
+program
+  .command('generate')
+  .description('Non-interactive generation (templates only, no Claude Code commands)')
+  .option('-d, --dir <path>', 'Project directory', '.')
+  .option('--overwrite', 'Overwrite existing files', false)
+  .option('--no-rules', 'Skip generating rules files')
+  .option('--no-hooks', 'Skip generating hooks/settings.json')
+  .action(async (opts) => {
+    const projectDir = resolve(opts.dir);
+    const detected = await detectTechStack(projectDir);
+
+    if (!detected.language) {
+      console.error('No project files detected. Use `init` for interactive setup.');
+      process.exit(1);
+    }
+
+    console.log(`Detected: ${detected.language}${detected.framework ? ` + ${detected.framework}` : ''}`);
+
+    const config = {
+      ...detected,
+      projectDescription: `${detected.framework || detected.language} project`,
+      generateRules: opts.rules !== false,
+      generateHooks: opts.hooks !== false,
+    };
+
+    const { files } = await generateDocs(projectDir, config);
+    const { written, skipped } = await writeDocs(projectDir, files, {
+      overwrite: opts.overwrite,
+    });
+
+    printFileResults(written, skipped);
+  });
+
+// --- validate ---
+program
+  .command('validate')
+  .description('Run validation checks on documentation')
+  .option('-d, --dir <path>', 'Project directory', '.')
+  .action(async (opts) => {
+    const projectDir = resolve(opts.dir);
+    let hasErrors = false;
+
+    console.log('Validating documentation...\n');
+
+    const claudeResult = await validateClaudeMd(join(projectDir, 'CLAUDE.md'));
+    printValidation('CLAUDE.md', claudeResult);
+    if (!claudeResult.valid) hasErrors = true;
+
+    const structResult = await validateStructure(projectDir);
+    printValidation('Structure', structResult);
+    if (!structResult.valid) hasErrors = true;
+
+    const xrefResult = await crossReferenceCheck(projectDir);
+    printValidation('Cross-references', xrefResult);
+    if (!xrefResult.valid) hasErrors = true;
+
+    if (hasErrors) {
+      console.log('\nValidation failed.');
+      process.exit(2);
+    } else {
+      console.log('\nAll checks passed.');
+    }
+  });
+
+// =============================================
+// Main init logic
+// =============================================
+async function runInit(dirArg, opts) {
+  // Commander passes (dir, opts) for arguments, or (opts) for options-only
+  if (typeof dirArg === 'object') {
+    opts = dirArg;
+    dirArg = '.';
+  }
+  const projectDir = resolve(dirArg || '.');
+  const yes = opts.yes || false;
+  const overwrite = opts.overwrite || false;
+
+  console.log(`\n  claudenv v${pkgJson.version}\n`);
+  console.log(`  Scanning ${projectDir}...\n`);
+
+  // 1. Detect tech stack
+  const detected = await detectTechStack(projectDir);
+  const hasProject = detected.language !== null;
+
+  if (hasProject) {
+    const parts = [detected.language];
+    if (detected.framework) parts.push(detected.framework);
+    const extras = [
+      detected.packageManager,
+      detected.testFramework,
+      detected.linter,
+      detected.formatter,
+    ].filter(Boolean);
+    console.log(`  Detected: ${parts.join(' + ')}${extras.length ? ` (${extras.join(', ')})` : ''}\n`);
+  }
+
+  // 2. Build config
+  let config;
+  if (yes) {
+    config = hasProject
+      ? await buildDefaultConfig(detected, projectDir)
+      : {
+          language: null,
+          generateRules: true,
+          generateHooks: true,
+          projectDescription: 'New project',
+        };
+  } else {
+    config = hasProject
+      ? await runExistingProjectFlow(detected)
+      : await runColdStartFlow();
+  }
+
+  // 3. Generate template-based files (CLAUDE.md, rules, settings.json)
+  const { files } = await generateDocs(projectDir, config);
+  const docResult = await writeDocs(projectDir, files, { overwrite });
+
+  // 4. Install scaffold (Claude Code commands, skills, agents)
+  const scaffoldResult = await installScaffold(projectDir, { overwrite });
+
+  // 5. Print results
+  const allWritten = [...docResult.written, ...scaffoldResult.written];
+  const allSkipped = [...docResult.skipped, ...scaffoldResult.skipped];
+
+  if (allWritten.length > 0) {
+    console.log(`\n  Created ${allWritten.length} file(s):\n`);
+    for (const f of allWritten) console.log(`    + ${f}`);
+  }
+
+  if (allSkipped.length > 0) {
+    console.log(`\n  Skipped ${allSkipped.length} existing file(s) (use --overwrite to replace):\n`);
+    for (const f of allSkipped) console.log(`    ~ ${f}`);
+  }
+
+  // 6. Next steps
+  console.log(`
+  Next steps:
+    1. Review and edit CLAUDE.md
+    2. In Claude Code, try: /init-docs  /update-docs  /validate-docs
+    3. git add .claude/ CLAUDE.md && git commit -m "Add Claude Code docs"
+`);
+}
+
+function printFileResults(written, skipped) {
+  if (written.length > 0) {
+    console.log(`Written ${written.length} file(s):`);
+    for (const f of written) console.log(`  + ${f}`);
+  }
+  if (skipped.length > 0) {
+    console.log(`Skipped ${skipped.length} existing file(s) (use --overwrite):`);
+    for (const f of skipped) console.log(`  ~ ${f}`);
+  }
+}
+
+function printValidation(label, result) {
+  const status = result.valid ? 'PASS' : 'FAIL';
+  console.log(`[${status}] ${label}`);
+  for (const err of result.errors) {
+    console.log(`  ERROR: ${err}`);
+  }
+  for (const warn of result.warnings) {
+    console.log(`  WARN:  ${warn}`);
+  }
+}
+
+program.parse();

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "claudenv",
+  "version": "1.0.1",
+  "description": "One command to set up Claude Code documentation for any project — detects tech stack, generates CLAUDE.md, rules, hooks, commands, and skills",
+  "type": "module",
+  "bin": {
+    "claudenv": "./bin/cli.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "scaffold",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "vitest run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^13.0.0",
+    "ejs": "^3.1.10",
+    "glob": "^11.0.0",
+    "smol-toml": "^1.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "documentation",
+    "generator",
+    "scaffold",
+    "CLAUDE.md",
+    "ai",
+    "developer-tools",
+    "cli"
+  ],
+  "author": "AGoldian",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AGoldian/claudenv.git"
+  },
+  "homepage": "https://github.com/AGoldian/claudenv#readme",
+  "bugs": {
+    "url": "https://github.com/AGoldian/claudenv/issues"
+  },
+  "license": "MIT"
+}

package/scaffold/.claude/agents/doc-analyzer.md

@@ -0,0 +1,70 @@
+---
+name: doc-analyzer
+description: Analyzes project structure for documentation. Use proactively when scanning codebases or evaluating documentation completeness.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+memory: project
+---
+
+You are a documentation analysis specialist. Your job is to scan project files and determine the tech stack, build commands, testing patterns, and coding conventions.
+
+## Analysis Process
+
+When analyzing a project:
+
+1. **Manifest files first** — Read package.json, pyproject.toml, go.mod, Cargo.toml, Gemfile, or composer.json to identify the language, dependencies, and scripts.
+
+2. **Framework detection** — Look for framework config files (next.config.js, vite.config.ts, manage.py, etc.) to identify the application framework.
+
+3. **Tooling inventory** — Scan for:
+   - Linter configs (.eslintrc*, biome.json, ruff.toml, .golangci.yml)
+   - Formatter configs (.prettierrc*, .editorconfig)
+   - Test configs (vitest.config.*, jest.config.*, pytest.ini, conftest.py)
+   - CI/CD files (.github/workflows/, .gitlab-ci.yml)
+   - Infrastructure (Dockerfile, docker-compose.yml, terraform/, *.tf)
+
+4. **Read existing documentation** — Check for README.md, CONTRIBUTING.md, CLAUDE.md, and any docs/ directory.
+
+5. **Directory structure** — Use Glob to map the top-level directory layout and identify key source directories.
+
+## Output Format
+
+Output your findings as structured JSON:
+
+```json
+{
+  "language": "typescript",
+  "runtime": "node",
+  "framework": "next.js",
+  "packageManager": "pnpm",
+  "testFramework": "vitest",
+  "linter": "eslint",
+  "formatter": "prettier",
+  "ci": "github-actions",
+  "containerized": true,
+  "monorepo": null,
+  "scripts": {
+    "dev": "pnpm next dev",
+    "build": "pnpm next build",
+    "test": "pnpm vitest run",
+    "lint": "pnpm next lint"
+  },
+  "directories": [
+    { "path": "src/app/", "description": "App Router pages and layouts" },
+    { "path": "src/components/", "description": "React components" },
+    { "path": "src/lib/", "description": "Shared utilities" }
+  ],
+  "existingDocs": ["README.md"],
+  "recommendations": [
+    "CLAUDE.md is missing — generate one",
+    "No .claude/rules/ directory — consider adding code style rules"
+  ]
+}
+```
+
+## Rules
+
+- **NEVER modify files.** You are read-only.
+- Only read and report findings.
+- If you cannot determine something with confidence, say so rather than guessing.
+- Prioritize accuracy over completeness.

package/scaffold/.claude/commands/init-docs.md

@@ -0,0 +1,69 @@
+---
+description: Analyze project and generate Claude Code documentation interactively
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(node:*)
+argument-hint: [--force]
+disable-model-invocation: true
+---
+
+# Project Documentation Generator
+
+You are generating Claude Code documentation for this project. Follow the phases below carefully.
+
+## Phase 1: Project Analysis
+
+Scan the project to detect the tech stack. Read the following detected files:
+
+**Package managers and manifests:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "pom.xml" -o -name "build.gradle*" -o -name "*.csproj" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+**Framework configs:**
+!`find . -maxdepth 2 \( -name "tsconfig.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "nuxt.config.*" -o -name "svelte.config.*" -o -name "astro.config.*" -o -name "angular.json" -o -name "manage.py" -o -name "docker-compose.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+**CI/CD:**
+!`find . -maxdepth 3 \( -path "*/.github/workflows/*" -o -name ".gitlab-ci.yml" -o -name "Jenkinsfile" -o -name ".circleci/config.yml" \) 2>/dev/null | head -10`
+
+**Existing documentation:**
+!`find . -maxdepth 2 \( -name "README.md" -o -name "CLAUDE.md" -o -name "CONTRIBUTING.md" \) -not -path "*/node_modules/*" 2>/dev/null | head -10`
+
+Read the manifest files you found above to understand dependencies, scripts, and project structure.
+
+## Phase 2: Clarifying Questions
+
+Based on your analysis, ask the user these questions **ONE AT A TIME**, waiting for each answer before proceeding to the next:
+
+1. **Project description**: "What is the primary purpose of this project?" (e.g., SaaS web app, REST API, CLI tool, shared library)
+2. **Deployment**: "What deployment target does this project use?" (e.g., Vercel, AWS, Docker, bare metal, not yet decided)
+3. **Conventions**: "Are there any team conventions not captured in config files?" (naming patterns, branching strategy, PR process, coding standards)
+4. **Focus areas**: "What areas of the codebase should Claude pay special attention to?" (critical business logic, complex algorithms, areas prone to bugs)
+
+## Phase 3: Generate Documentation
+
+After gathering all answers, generate these files:
+
+### CLAUDE.md
+Create a compact `CLAUDE.md` (under 60 lines) in the project root containing:
+- **Project overview**: One-sentence description including detected stack
+- **Commands**: All detected dev/build/test/lint commands with descriptions
+- **Architecture**: Key directories and their purposes (read the actual directory structure)
+- **Conventions**: @import references to `.claude/rules/code-style.md` and `.claude/rules/testing.md`
+- **Workflow**: @import reference to `.claude/rules/workflow.md`
+- **Memory**: Reference to `_state.md` for session persistence
+- **Rules**: Project-specific rules, including: "NEVER create documentation files (.md) unless the user explicitly requests it"
+
+### _state.md
+Create `_state.md` in the project root for tracking project state across sessions:
+- **Current Focus**: What is being worked on
+- **Key Decisions**: Architecture and design decisions (pre-fill from detected stack)
+- **Known Issues**: Bugs, tech debt, gotchas
+- **Session Notes**: Context to preserve between sessions
+
+### .claude/rules/code-style.md
+Create coding convention rules based on detected linter, formatter, framework, and user-specified conventions. Include YAML frontmatter with path globs to scope the rules.
+
+### .claude/rules/testing.md
+Create testing rules based on detected test framework. Include test commands, file patterns, and best practices. Include YAML frontmatter with path globs.
+
+### .claude/rules/workflow.md
+Create Claude Code workflow best practices including: plan mode usage, /compact and /clear, subagents, memory via _state.md, commit discipline, and the rule to NEVER create .md files unless explicitly asked.
+
+**Present each file to the user for confirmation before writing it.** If the argument `$ARGUMENTS` includes `--force`, write all files without confirmation.

package/scaffold/.claude/commands/update-docs.md

@@ -0,0 +1,49 @@
+---
+description: Refresh project documentation from current state
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(diff:*)
+disable-model-invocation: true
+---
+
+# Update Project Documentation
+
+You are updating the existing Claude Code documentation for this project.
+
+## Step 1: Read Current Documentation
+
+Read the existing documentation files:
+- @CLAUDE.md
+- Read any files referenced by @imports in CLAUDE.md
+
+## Step 2: Scan Current State
+
+Detect the current tech stack:
+
+**Package managers:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+**Framework configs:**
+!`find . -maxdepth 2 \( -name "tsconfig.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "manage.py" -o -name "docker-compose.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+Read the manifest files to check for new dependencies, scripts, or configuration changes since the documentation was last generated.
+
+## Step 3: Identify Changes
+
+Compare the current state against the existing documentation:
+- **New dependencies or tools** not mentioned in CLAUDE.md
+- **Changed scripts** (renamed, added, or removed)
+- **New directories** not covered in Architecture section
+- **Stale references** to files or directories that no longer exist
+- **Missing conventions** based on new config files (e.g., new linter added)
+
+## Step 4: Propose Updates
+
+Present a **diff-style summary** of proposed changes to each documentation file. For each change:
+- Show what currently exists
+- Show what should be updated
+- Explain why the change is needed
+
+Wait for user approval before writing any changes.
+
+## Step 5: Apply Updates
+
+After user approval, update the documentation files. Preserve any user-written content that was manually added — only update sections that correspond to detected/generated content.

package/scaffold/.claude/commands/validate-docs.md

@@ -0,0 +1,40 @@
+---
+description: Validate project documentation for completeness and correctness
+allowed-tools: Read, Glob, Grep, Bash(bash:*)
+disable-model-invocation: true
+---
+
+# Validate Project Documentation
+
+Run validation checks on the project's Claude Code documentation.
+
+## Step 1: Run Bash Validation
+
+Execute the validation script:
+!`bash .claude/skills/doc-generator/scripts/validate.sh 2>&1 || true`
+
+## Step 2: Deep Validation
+
+Perform additional checks that require reading file contents:
+
+1. **Read CLAUDE.md** and verify:
+   - All `@import` references resolve to existing files
+   - Commands in the ## Commands section match actual scripts in package.json / pyproject.toml / Makefile
+   - Directories in ## Architecture section actually exist
+
+2. **Read .claude/rules/*.md** files and verify:
+   - YAML frontmatter `paths` globs match files that exist in the project
+   - Referenced tools (linters, formatters, test frameworks) are actually installed
+
+3. **Read .claude/settings.json** and verify:
+   - Valid JSON structure
+   - Referenced hook scripts exist at the specified paths
+
+## Step 3: Report
+
+Present a clear summary:
+- List all **errors** (things that must be fixed)
+- List all **warnings** (things that should be reviewed)
+- Provide a **pass/fail** verdict
+
+If there are errors, suggest specific fixes for each one.