Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "claude-code-claude-md",
+  "description": "CLAUDE.md manager for creating and optimizing memory files across the hierarchical cascade system",
+  "version": "1.0.0",
+  "author": {
+    "name": "Nathan Vale"
+  },
+  "commands": [
+    "./commands"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# claude-code-claude-md
+
+CLAUDE.md manager for creating and optimizing memory files across the hierarchical cascade system

commands/audit.md

@@ -0,0 +1,168 @@
+---
+description: Audit CLAUDE.md files against Anthropic best practices (user, project, or module level)
+model: claude-haiku-4-5-20251001
+allowed-tools: Read, Glob, LS
+argument-hint: [level] - level: user|project|module (optional, auto-detects if omitted)
+---
+
+# Audit CLAUDE.md Files
+
+Analyze CLAUDE.md files against Anthropic's official best practices with level-specific requirements.
+
+## Background
+
+For Anthropic's official guidelines and best practices, see:
+@../templates/best-practices.md
+
+## Instructions
+
+### 1. Determine Level
+
+Parse arguments or auto-detect:
+
+| Location | Level | Detection |
+|----------|-------|-----------|
+| `~/.claude/CLAUDE.md` | **user** | Home directory |
+| `./CLAUDE.md` (repo root) | **project** | Has .git sibling |
+| `src/*/CLAUDE.md` | **module** | Inside src/lib/packages dir |
+
+### 2. Apply Level-Specific Requirements
+
+For detailed quality checks and requirements by level, see:
+@../templates/quality-checks.md
+
+For formatting best practices, see:
+@../templates/formatting-guide.md
+
+### 3. Quick Reference Summary
+
+**Token Budgets:**
+- User: 50-100 lines (max 150)
+- Project: 100-200 lines (max 300)
+- Module: 30-50 lines (max 100)
+
+**Key Requirements:**
+- **User**: Personal prefs, global tools, @imports to context files
+- **Project**: Directory structure (required!), commands, coding standards
+- **Module**: One-line purpose, key files, module-specific conventions
+
+**Common Anti-Patterns:**
+- Verbose paragraphs (>3 sentences) → Convert to bullets
+- Vague instructions → Be specific with examples
+- Critical rules without emphasis → Add **NEVER**, **YOU MUST**
+- Sections >50 lines inline → Extract to @import
+- Duplicate info across levels → Keep in one place
+
+---
+
+## 4. Generate Report
+
+```markdown
+## CLAUDE.md Audit Report
+
+**Level:** [user | project | module]
+**File:** [path]
+**Lines:** X (Budget: Y-Z, Max: W)
+
+### Level-Specific Compliance
+
+#### Required Content
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| [requirement 1] | ✅/❌ | [details] |
+| [requirement 2] | ✅/❌ | [details] |
+
+#### Content That Should Move
+| Content | Current Location | Should Be In |
+|---------|------------------|--------------|
+| [item] | [this file] | [correct level] |
+
+### Token Efficiency Score
+
+**Overall: X/10**
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| Structure | X/10 | Headings, bullets, tables |
+| Conciseness | X/10 | No verbose explanations |
+| Imports | X/10 | Modular, on-demand loading |
+| Emphasis | X/10 | Critical rules marked |
+| Specificity | X/10 | Actionable directives |
+| Level-appropriate | X/10 | Right content for this level |
+
+### Issues Found
+
+#### 🔴 High Priority
+- **[Issue]**: [problem]
+  - Line(s): X-Y
+  - Fix: [action]
+  - Before: `[current]`
+  - After: `[improved]`
+
+#### 🟡 Medium Priority
+...
+
+#### 🟢 Suggestions
+...
+
+### What's Working Well
+- [strength]
+- [strength]
+```
+
+---
+
+## Level-Specific Report Additions
+
+### For PROJECT Level — File Tree Check
+
+```markdown
+### Directory Structure Audit
+
+**Status:** ✅ Present and annotated | 🟡 Present but no annotations | 🔴 Missing
+
+Current:
+[paste current tree or note if missing]
+
+Suggestions:
+- [specific improvements]
+```
+
+### For USER Level — Cross-File Check
+
+```markdown
+### Duplication Check
+
+| Content | Also In | Action |
+|---------|---------|--------|
+| [item] | [project file] | Remove from [location] |
+```
+
+### For MODULE Level — Scope Check
+
+```markdown
+### Scope Audit
+
+**Focused:** ✅ Yes | ❌ No (contains project-wide content)
+
+Content that belongs in parent:
+- [item that should be in root CLAUDE.md]
+```
+
+---
+
+## Output Guidelines
+
+1. **Identify level first** — User, project, or module determines requirements
+2. **Check level-specific requirements** — Each level has must-have content
+3. **Flag misplaced content** — Personal prefs in project file, etc.
+4. **Be specific** — Line numbers, exact text, before/after examples
+5. **Prioritize by impact** — Missing file tree (project) is high priority
+6. **Calculate savings** — "Moving X to user-level saves ~Y lines per project"
+
+## Example Issues by Level
+
+For detailed examples of common issues and fixes, see:
+@../templates/quality-checks.md
+
+Now audit the CLAUDE.md file: $ARGUMENTS

commands/import-docs.md

@@ -0,0 +1,286 @@
+---
+description: Extract documentation into structured context, then invoke /create to generate CLAUDE.md
+model: claude-sonnet-4-5-20250929
+allowed-tools: Read, Glob, LS
+argument-hint: [source-file] - e.g., README.md, CONTRIBUTING.md
+---
+
+# Import Documentation into CLAUDE.md
+
+Extract relevant information from existing docs, then invoke `/create` with that context.
+
+## Why Composable?
+
+This command **extracts and structures** data, then delegates to `/create` which:
+- Has the official templates for each level (user/project/module)
+- Knows the token budgets and best practices
+- Handles file writing and next steps
+
+**Flow:**
+```
+/import-docs README.md
+  → Extract: commands, conventions, structure
+  → Output: structured context block
+  → User runs: /create project (with context pre-filled)
+```
+
+## Instructions
+
+### 1. Locate Source Documentation
+
+If argument provided:
+- Read the specified file
+
+If no argument:
+- Search for: README.md, CONTRIBUTING.md, docs/*.md, DEVELOPMENT.md, package.json
+- List found files and ask which to convert
+
+### 2. Extract Relevant Information
+
+**High Value (extract):**
+| Category | What to Look For |
+|----------|------------------|
+| Commands | Scripts in package.json, "Getting Started", "Development" sections |
+| Tech Stack | Dependencies, frameworks, language versions |
+| Structure | Directory explanations, architecture sections |
+| Conventions | Code style, linting, formatting rules |
+| Testing | Test commands, coverage requirements, test structure |
+| Git Workflow | Branch naming, commit format, PR process |
+| Environment | Required env vars, setup steps |
+
+**Low Value (skip):**
+- Marketing content, badges, logos
+- License text (reference only)
+- Detailed API docs (use @import)
+- Screenshots, images
+- Changelog, release notes
+- Contributor lists
+
+### 3. Transform to Structured Context
+
+Output the extracted data in this format:
+
+```markdown
+## Extracted Context for /create
+
+### Project Info
+- **Name**: [from package.json or README title]
+- **Description**: [one-line from README]
+- **Tech Stack**: [detected languages, frameworks]
+
+### Directory Structure
+```
+[extracted or generated tree]
+```
+
+### Commands
+```bash
+[extracted commands with comments]
+```
+
+### Key Files
+- `[file]` — [purpose]
+
+### Code Conventions
+- [extracted conventions]
+
+### Git Workflow
+- Branch: [format]
+- Commit: [format]
+
+### Testing
+- Command: `[test command]`
+- [other testing info]
+
+### Environment
+- [required env vars]
+
+### Source References
+- @./README.md — Full project documentation
+- @./CONTRIBUTING.md — Contribution guidelines
+- @./docs/architecture.md — Detailed architecture
+```
+
+### 4. Conversion Rules
+
+| Source Pattern | Extracted Format |
+|----------------|------------------|
+| "You should..." / "We recommend..." | Direct: "Use X" |
+| Paragraphs of explanation | Bullet points |
+| Multiple examples | Single canonical example |
+| `npm run X` in prose | Extracted to Commands section |
+| Directory explanations | File tree with annotations |
+| Long detailed sections | @import reference |
+
+### 5. Present Results and Next Steps
+
+Output format:
+
+```markdown
+## Documentation Extracted
+
+[Show the structured context block from step 3]
+
+---
+
+## Extraction Summary
+
+| Category | Status | Lines |
+|----------|--------|-------|
+| Commands | ✅ Extracted | X |
+| Structure | ✅ Extracted | X |
+| Conventions | ⚠️ Not found | - |
+| Testing | ✅ Extracted | X |
+
+**Total extracted:** ~X lines
+**Recommended imports:** [list any sections that were too long]
+
+---
+
+## Next Step
+
+Run `/create project` and paste the extracted context above when prompted,
+or copy this ready-to-use command:
+
+\`\`\`
+/create project
+\`\`\`
+
+The create command will:
+1. Use the project-level template
+2. Incorporate your extracted context
+3. Generate a properly structured CLAUDE.md
+4. Apply token budget guidelines (100-200 lines)
+
+---
+
+## Manual Adjustments Needed
+
+After running /create, you may want to add:
+- [ ] [specific thing not found in docs]
+- [ ] [another gap identified]
+```
+
+### 6. Alternative: Direct Generation
+
+If user says "just generate it" or wants immediate output:
+
+```markdown
+I've extracted the context above. You have two options:
+
+**Option A: Use /create (recommended)**
+Run `/create project` — uses official templates, consistent structure
+
+**Option B: Direct output**
+I can generate CLAUDE.md directly, but it won't use the standardized templates.
+Want me to proceed with direct generation?
+```
+
+## Quick Extraction Templates
+
+### From package.json
+
+```javascript
+// Extract these fields:
+{
+  "name": "→ Project name",
+  "description": "→ One-liner",
+  "scripts": {
+    "dev": "→ Commands section",
+    "build": "→ Commands section",
+    "test": "→ Testing section",
+    "lint": "→ Commands section"
+  },
+  "dependencies": "→ Tech stack",
+  "devDependencies": "→ Tech stack (tooling)"
+}
+```
+
+### From README.md
+
+```markdown
+# Title → Project name
+First paragraph → Description
+
+## Installation / Getting Started → Commands
+## Development → Commands + Conventions
+## Testing → Testing section
+## Project Structure → Directory structure
+## Contributing → Git workflow (or @import)
+## Architecture → @import reference
+```
+
+### From CONTRIBUTING.md
+
+```markdown
+## Code Style → Conventions
+## Commit Messages → Git workflow
+## Pull Requests → Git workflow
+## Testing Requirements → Testing
+```
+
+## Example Output
+
+**Input:** README.md with 500 lines
+
+**Output:**
+```markdown
+## Extracted Context for /create
+
+### Project Info
+- **Name**: my-awesome-api
+- **Description**: REST API for user management with TypeScript and Express
+- **Tech Stack**: TypeScript, Express, PostgreSQL, Jest
+
+### Directory Structure
+```
+my-awesome-api/
+├── src/
+│   ├── controllers/    # Route handlers
+│   ├── models/         # Database models
+│   ├── middleware/     # Express middleware
+│   └── index.ts        # Entry point
+├── tests/              # Jest tests
+└── docs/               # API documentation
+```
+
+### Commands
+```bash
+npm install            # Install dependencies
+npm run dev            # Start dev server (port 3000)
+npm run build          # Production build
+npm test               # Run Jest tests
+npm run lint           # ESLint check
+```
+
+### Key Files
+- `src/index.ts` — Application entry point
+- `src/config.ts` — Environment configuration
+- `.env.example` — Required environment variables
+
+### Code Conventions
+- TypeScript strict mode
+- ESLint + Prettier
+- Functional style preferred
+
+### Git Workflow
+- Branch: `feature/[ticket]-[description]`
+- Commit: `type(scope): subject`
+
+### Testing
+- Command: `npm test`
+- Coverage minimum: 80%
+- Tests mirror src/ structure
+
+### Source References
+- @./README.md — Full documentation
+- @./docs/api.md — API reference
+
+---
+
+## Next Step
+
+Run `/create project` to generate CLAUDE.md with this context.
+```
+
+Now extract documentation from: $ARGUMENTS

commands/init.md

@@ -0,0 +1,819 @@
+---
+description: Smart CLAUDE.md initialization with CI mode for automated updates
+model: claude-sonnet-4-5-20250929
+allowed-tools: Read, Write, Glob, LS, Bash(ls:*), Bash(cat:*), Bash(head:*), Bash(git:*), AskUserQuestion, mcp__kit__*, mcp__git-intelligence__*, mcp__bun-runner__*
+argument-hint: [--ci] [--update] [path]
+---
+
+# Smart CLAUDE.md Initialization
+
+Gather comprehensive project context using MCP tools, with CI mode for automated updates.
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `--ci` | Non-interactive mode, use detected values only |
+| `--update` | Update existing CLAUDE.md, preserve custom sections |
+| `--diff` | Show what would change without writing (dry run) |
+| `[path]` | Project path (defaults to current directory) |
+
+**Auto-detection:** If `CI=true` or `GITHUB_ACTIONS=true` environment variable is set, automatically enables `--ci` mode.
+
+## Examples
+
+```bash
+# Interactive init (default)
+/init
+
+# CI mode - no questions, detection only
+/init --ci
+
+# Update existing CLAUDE.md with latest detection
+/init --update
+
+# CI + Update (for cron jobs)
+/init --ci --update
+
+# Dry run - see what would change
+/init --ci --update --diff
+```
+
+## Modes
+
+### Interactive Mode (default)
+- Full MCP discovery
+- Asks questions for gaps
+- Confirms before writing
+
+### CI Mode (`--ci`)
+- No interactive questions
+- Uses detected values + sensible defaults
+- Writes directly (or shows diff with `--diff`)
+- Exit codes for scripting:
+  - `0` — Success, file written/updated
+  - `1` — Error during detection
+  - `2` — No changes detected (with `--update`)
+
+### Update Mode (`--update`)
+- Reads existing CLAUDE.md
+- Preserves custom sections (marked with `<!-- custom -->`)
+- Updates auto-detected sections only
+- Shows diff of changes
+
+---
+
+## Why This Init is Different
+
+Standard `/init` just reads README.md. This command:
+
+1. **Interrogates the codebase** — Uses Kit for structure, Git for history
+2. **Asks targeted questions** — Only what can't be auto-detected (skipped in CI)
+3. **Detects patterns** — Commit style, test patterns, code conventions
+4. **Supports CI/cron** — Keep CLAUDE.md fresh automatically
+5. **Preserves customizations** — Update mode keeps your manual additions
+
+## Phase 0: Mode Detection
+
+```typescript
+// Detect CI environment automatically
+const isCI =
+  args.includes("--ci") ||
+  process.env.CI === "true" ||
+  process.env.GITHUB_ACTIONS === "true" ||
+  process.env.GITLAB_CI === "true" ||
+  process.env.CIRCLECI === "true";
+
+const isUpdate = args.includes("--update");
+const isDryRun = args.includes("--diff");
+
+// Behavior adjustments
+if (isCI) {
+  // Skip all AskUserQuestion calls
+  // Use detected values or sensible defaults
+  // Minimal output, structured for logs
+}
+
+if (isUpdate) {
+  // Read existing CLAUDE.md first
+  // Parse into sections
+  // Only regenerate auto-detected sections
+  // Preserve <!-- custom --> blocks
+}
+```
+
+**CI Output Format:**
+```
+[init] Detecting project context...
+[init] Found: TypeScript, Next.js, Biome, Vitest
+[init] Commits: conventional (feat/fix/chore)
+[init] Generating CLAUDE.md...
+[init] ✓ Updated ./CLAUDE.md (3 sections changed)
+```
+
+---
+
+## Phase 1: Automated Discovery
+
+Run these MCP tools to gather context (parallelize where possible):
+
+### 1.1 Directory Structure
+
+```
+Tool: kit_file_tree
+Purpose: Get annotated directory structure fast (~50ms)
+Extract: Top-level folders, depth-2 structure
+```
+
+**Fallback if Kit unavailable:** `ls -la` + `find . -type d -maxdepth 2`
+
+### 1.2 Project Configuration
+
+**Read these files (if they exist):**
+
+| File | Extract |
+|------|---------|
+| `package.json` | name, description, scripts, dependencies, devDependencies |
+| `tsconfig.*.json` | strict mode, target, paths |
+| `biome.json` / `.eslintrc` | linting rules |
+| `pyproject.toml` | Python project config |
+| `Cargo.toml` | Rust project config |
+| `go.mod` | Go module info |
+| `.nvmrc` / `.node-version` | Node version |
+| `.env.example` | Required environment variables |
+
+### 1.3 Git Intelligence
+
+```
+Tool: git_get_recent_commits (limit: 20)
+Extract:
+- Commit message format (conventional? descriptive?)
+- Active contributors
+- Recent areas of change
+
+Tool: git_get_branch_info
+Extract:
+- Branch naming pattern
+- Default branch name
+```
+
+**Detect commit style:**
+```
+Pattern: "feat(scope): subject" → Conventional commits
+Pattern: "JIRA-123: description" → Ticket-prefixed
+Pattern: "Add feature X" → Descriptive
+```
+
+### 1.4 Code Patterns (Kit)
+
+```
+Tool: kit_symbols (path: "src/")
+Extract:
+- Main exports
+- Entry points
+- Key abstractions
+
+Tool: kit_grep (pattern: "describe\\(|test\\(|it\\(")
+Extract:
+- Test framework (Jest, Vitest, Mocha, Bun test)
+- Test file patterns
+```
+
+### 1.5 Documentation Scan
+
+```
+Tool: kit_grep (pattern: "^#|^##" in *.md files)
+Extract:
+- README sections
+- CONTRIBUTING guidelines
+- Existing architecture docs
+```
+
+---
+
+## Phase 2: Analysis
+
+After discovery, analyze what was found:
+
+```markdown
+## Discovery Summary
+
+### Detected Stack
+- **Language**: [TypeScript/JavaScript/Python/Rust/Go]
+- **Framework**: [Next.js/Express/FastAPI/etc. or "None detected"]
+- **Package Manager**: [npm/yarn/pnpm/bun/uv/cargo]
+- **Test Framework**: [Jest/Vitest/pytest/etc.]
+- **Linter/Formatter**: [Biome/ESLint+Prettier/ruff/etc.]
+
+### Detected Patterns
+- **Commit Style**: [Conventional/Ticket-prefixed/Descriptive]
+- **Branch Pattern**: [feature/*, feat/*, JIRA-*]
+- **Test Pattern**: [*.test.ts, *.spec.ts, tests/*, __tests__/*]
+
+### Gaps (need to ask)
+- [ ] [Thing that couldn't be detected]
+- [ ] [Another gap]
+```
+
+---
+
+## Phase 3: Interactive Questions
+
+Only ask what couldn't be auto-detected. Use `AskUserQuestion` tool.
+
+### Question Bank
+
+**Q1: Project Type** (if not clear from structure)
+```
+What type of project is this?
+- Web Application (frontend)
+- API / Backend Service
+- Full-stack Application
+- CLI Tool
+- Library / Package
+- Monorepo
+- Other: [describe]
+```
+
+**Q2: Team or Solo** (affects conventions section)
+```
+Is this a team project or personal?
+- Team project (include team conventions)
+- Personal project (lighter conventions)
+```
+
+**Q3: Code Style** (if no linter config found)
+```
+What code style do you follow?
+- Strict TypeScript (strict: true, no any)
+- Standard with some flexibility
+- Follow existing patterns in codebase
+- Other: [describe]
+```
+
+**Q4: Testing Approach** (if no test files found)
+```
+What's your testing approach?
+- TDD (tests first)
+- Test after implementation
+- Integration tests only
+- Minimal/no tests
+```
+
+**Q5: Git Workflow** (if couldn't detect from commits)
+```
+What's your Git workflow?
+- Feature branches → PR → main
+- Trunk-based (commit to main)
+- Gitflow (develop, release branches)
+- Other: [describe]
+```
+
+**Q6: Anything special Claude should know?**
+```
+Any project-specific rules or gotchas?
+(e.g., "Don't modify legacy/ folder", "Always run migrations after model changes")
+```
+
+### Skip Logic
+
+- If `tsconfig.json` has `strict: true` → Skip Q3
+- If test files found → Skip Q4
+- If conventional commits detected → Skip Q5 (infer workflow)
+- If solo project → Simplify Q2-Q5
+
+---
+
+## Phase 4: Generate Context Block
+
+Combine discovered + answered info into structured context:
+
+```markdown
+## Project Context for /create
+
+### Project Info
+- **Name**: [from package.json or directory name]
+- **Description**: [from package.json or ask]
+- **Type**: [detected or answered]
+- **Tech Stack**: TypeScript, Next.js, Prisma, PostgreSQL
+
+### Directory Structure
+```
+[project-name]/
+├── src/
+│   ├── app/           # Next.js app router
+│   ├── components/    # React components
+│   ├── lib/           # Shared utilities
+│   └── server/        # Server-side code
+├── prisma/            # Database schema
+├── tests/             # Test files
+└── docs/              # Documentation
+```
+
+### Commands
+```bash
+bun install            # Install dependencies
+bun dev                # Start dev server (port 3000)
+bun build              # Production build
+bun test               # Run tests
+bun lint               # Biome lint + format check
+```
+
+### Key Files
+- `src/app/layout.tsx` — Root layout
+- `src/lib/db.ts` — Database client
+- `prisma/schema.prisma` — Database schema
+- `.env.example` — Required environment variables
+
+### Code Conventions
+- TypeScript strict mode (tsconfig.json)
+- Biome for linting and formatting
+- Functional components with hooks
+- Server actions for mutations
+
+### Git Workflow
+- **Branch**: `feat/[description]` or `fix/[description]`
+- **Commits**: Conventional format `type(scope): subject`
+- **PR Process**: Feature branch → Review → Squash merge
+
+### Testing
+- Framework: Vitest
+- Pattern: `*.test.ts` alongside source files
+- Run: `bun test`
+
+### Special Rules
+[From Q6 answers]
+
+### Source References
+- @./README.md
+- @./CONTRIBUTING.md
+- @./docs/architecture.md
+```
+
+---
+
+## Phase 5: Generate CLAUDE.md
+
+Using the context gathered, generate CLAUDE.md directly.
+
+### Template Reference
+
+Use the project template structure from:
+@../templates/project-template.md
+
+Follow best practices from:
+@../templates/best-practices.md
+
+Apply formatting guidelines from:
+@../templates/formatting-guide.md
+
+### Generation Logic
+
+1. **Check if file exists**:
+   ```typescript
+   if (exists("./CLAUDE.md") && !args.includes("--update")) {
+     // Stop and suggest /audit instead
+   }
+   ```
+
+2. **Populate template** with discovered context:
+   - Replace `[project-name]` with actual name
+   - Insert actual directory structure from Phase 1
+   - Fill in real commands from package.json
+   - Add detected tech stack
+   - Include detected conventions
+
+3. **Customize based on answers**:
+   - Team vs solo affects conventions section
+   - Testing approach affects testing section
+   - Special rules from Q6 go in Notes section
+
+4. **Write file** (or show diff if `--diff` flag)
+
+### Output Format
+
+**Interactive Mode:**
+```markdown
+## ✅ CLAUDE.md Generated
+
+I've created ./CLAUDE.md with:
+
+**Auto-detected:**
+- Directory structure (X directories)
+- Y commands from package.json
+- Tech stack: [list]
+- Commit style: [conventional/other]
+
+**From your answers:**
+- [Answer 1]
+- [Answer 2]
+
+**Next steps:**
+1. Review the file and customize as needed
+2. Add any project-specific gotchas to the Notes section
+3. Run `/audit` to check optimization
+4. Commit to version control
+```
+
+**CI Mode:**
+```
+[init] ✓ Created ./CLAUDE.md (145 lines)
+[init] Sections: Directory Structure, Commands, Tech Stack, Git Workflow
+[init] Exit code: 0
+```
+
+### Update Mode (--update)
+
+When updating existing CLAUDE.md:
+
+1. **Read existing file**
+2. **Parse sections**:
+   ```typescript
+   const CUSTOM_START = "<!-- custom -->";
+   const CUSTOM_END = "<!-- /custom -->";
+
+   const AUTO_SECTIONS = [
+     "Directory Structure",
+     "Commands",
+     "Tech Stack",
+     "Key Files"
+   ];
+
+   const PRESERVED_SECTIONS = [
+     "CRITICAL RULES",
+     "Special Rules",
+     "Notes"
+   ];
+   ```
+
+3. **Detect changes**:
+   - Compare new auto-generated sections with existing
+   - Preserve custom sections marked with `<!-- custom -->`
+   - Show diff of what changed
+
+4. **Merge and write**:
+   - Update auto-generated sections
+   - Keep preserved sections untouched
+   - Maintain custom content
+
+### Diff Mode (--diff)
+
+Show what would change without writing:
+
+```diff
+--- a/CLAUDE.md
++++ b/CLAUDE.md
+@@ -15,6 +15,7 @@ project/
+ ├── src/
+ │   ├── components/
++│   ├── hooks/          # New directory
+ │   └── utils/
+
+@@ -25,6 +26,7 @@ Commands
+ bun dev               # Start dev server
+ bun build             # Production build
++bun typecheck         # Type checking
+```
+
+---
+
+## Tool Availability Check
+
+At start, check which tools are available:
+
+```typescript
+// Check for enhanced capabilities
+const hasKit = toolExists("kit_file_tree");
+const hasGit = toolExists("git_get_recent_commits");
+const hasBunRunner = toolExists("bun_lintCheck");
+
+// Adjust discovery strategy
+if (!hasKit) {
+  // Fallback to LS + Glob for structure
+}
+if (!hasGit) {
+  // Skip commit style detection, ask instead
+}
+```
+
+---
+
+## Example Session
+
+```
+User: /init
+
+Claude: 🔍 Analyzing project...
+
+[Runs kit_file_tree, reads package.json, git_get_recent_commits]
+
+## Discovery Complete
+
+**Detected:**
+- TypeScript + Next.js 14 (App Router)
+- Biome for linting
+- Vitest for testing
+- Conventional commits (feat/fix/chore)
+
+**Need to confirm:**
+
+Q1: Is this a team project or personal?
+> Team project
+
+Q2: Any special rules Claude should know?
+> Don't modify anything in src/legacy/ - it's being deprecated
+
+## Context Generated
+
+[Shows structured context block]
+
+Run `/create project` to generate CLAUDE.md, or say "generate" for direct output.
+
+User: generate
+
+Claude: [Creates CLAUDE.md with all gathered context]
+
+✅ Created ./CLAUDE.md (145 lines)
+
+Key sections:
+- Directory structure with annotations
+- 6 commands from package.json
+- TypeScript strict + Biome conventions
+- Conventional commit workflow
+- Special rule: Don't modify src/legacy/
+```
+
+---
+
+## Fallback Behavior
+
+If MCP tools unavailable:
+
+| Tool Missing | Fallback |
+|--------------|----------|
+| `kit_file_tree` | `ls -la` + `find . -type d -maxdepth 2` |
+| `kit_symbols` | Skip, rely on file structure |
+| `kit_grep` | `grep -r` via Bash |
+| `git_get_recent_commits` | `git log --oneline -20` via Bash |
+| `git_get_branch_info` | `git branch -a` via Bash |
+
+The command should work (with reduced intelligence) even without MCP tools.
+
+---
+
+## Update Mode Logic
+
+When `--update` is passed:
+
+### 1. Parse Existing CLAUDE.md
+
+```typescript
+// Section markers for preservation
+const CUSTOM_START = "<!-- custom -->";
+const CUSTOM_END = "<!-- /custom -->";
+const AUTO_MARKER = "<!-- auto-generated -->";
+
+// Sections that get auto-updated
+const AUTO_SECTIONS = [
+  "Directory Structure",
+  "Commands",
+  "Tech Stack",
+  "Key Files"
+];
+
+// Sections preserved (never auto-updated)
+const PRESERVED_SECTIONS = [
+  "CRITICAL RULES",
+  "NEVER",
+  "Special Rules",
+  "Notes"
+];
+```
+
+### 2. Detect Changes
+
+```markdown
+## Update Diff
+
+**Changed sections:**
+- Directory Structure: +2 files, -1 file
+- Commands: +1 new script (bun run typecheck)
+
+**Unchanged sections:**
+- Tech Stack
+- Key Files
+- Code Conventions
+
+**Preserved (custom) sections:**
+- CRITICAL RULES (5 lines)
+- Notes (3 lines)
+```
+
+### 3. Merge Strategy
+
+```
+┌─────────────────────────────────────┐
+│ Existing CLAUDE.md                  │
+├─────────────────────────────────────┤
+│ # Project Name          ← update    │
+│ ## Directory Structure  ← update    │
+│ ## Commands             ← update    │
+│ ## CRITICAL RULES       ← preserve  │
+│ <!-- custom -->                     │
+│ ## My Custom Section    ← preserve  │
+│ <!-- /custom -->                    │
+│ ## Key Files            ← update    │
+└─────────────────────────────────────┘
+```
+
+### 4. Custom Section Markers
+
+To protect custom content from auto-updates, wrap in markers:
+
+```markdown
+<!-- custom -->
+## Special Rules
+
+- Never modify src/legacy/ - deprecated
+- Always run migrations after model changes
+- Check with Nathan before major refactors
+
+<!-- /custom -->
+```
+
+---
+
+## Cron Job Setup
+
+### GitHub Actions (Recommended)
+
+```yaml
+# .github/workflows/update-claude-md.yml
+name: Update CLAUDE.md
+
+on:
+  schedule:
+    # Run nightly at 2am UTC
+    - cron: '0 2 * * *'
+  workflow_dispatch: # Manual trigger
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Claude Code
+        run: |
+          npm install -g @anthropic-ai/claude-code
+
+      - name: Update CLAUDE.md
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          claude --print "/init --ci --update"
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet CLAUDE.md; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit changes
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add CLAUDE.md
+          git commit -m "chore: auto-update CLAUDE.md [skip ci]"
+          git push
+```
+
+### Local Cron (macOS/Linux)
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add nightly update at 2am
+0 2 * * * cd /path/to/project && claude --print "/init --ci --update" >> /tmp/claude-md-update.log 2>&1
+```
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Quick check if CLAUDE.md might be stale
+if git diff --cached --name-only | grep -qE 'package\.json|tsconfig\.json|src/'; then
+  echo "Checking if CLAUDE.md needs update..."
+  claude --print "/init --ci --update --diff"
+fi
+```
+
+---
+
+## CI Defaults
+
+When in CI mode without interactive questions, use these sensible defaults:
+
+| Gap | CI Default |
+|-----|------------|
+| Project type not clear | Infer from structure (src/app → Web, src/cli → CLI) |
+| Team vs solo | Assume team (include conventions) |
+| Code style | Use detected linter config, or "Follow existing patterns" |
+| Testing approach | Infer from test files, or "Test after implementation" |
+| Git workflow | Infer from commits, or "Feature branches → PR → main" |
+| Special rules | Leave section empty with TODO marker |
+
+---
+
+## CI Output Examples
+
+### Successful Update
+
+```
+$ claude --print "/init --ci --update"
+
+[init] CI mode detected (GITHUB_ACTIONS=true)
+[init] Reading existing CLAUDE.md...
+[init] Detecting project context...
+[init]   ├─ kit_file_tree: 23 directories
+[init]   ├─ package.json: 8 scripts
+[init]   ├─ git_get_recent_commits: conventional commits
+[init]   └─ tsconfig.json: strict mode
+[init] Comparing with existing...
+[init] Changes detected:
+[init]   ├─ Directory Structure: +2 entries
+[init]   └─ Commands: +1 script (typecheck)
+[init] Writing CLAUDE.md...
+[init] ✓ Updated ./CLAUDE.md
+[init] Exit code: 0
+```
+
+### No Changes
+
+```
+$ claude --print "/init --ci --update"
+
+[init] CI mode detected
+[init] Detecting project context...
+[init] No changes detected
+[init] Exit code: 2
+```
+
+### Dry Run
+
+```
+$ claude --print "/init --ci --update --diff"
+
+[init] CI mode detected (dry run)
+[init] Detecting project context...
+[init] Changes that would be made:
+
+--- a/CLAUDE.md
++++ b/CLAUDE.md
+@@ -15,6 +15,7 @@ project/
+ ├── src/
+ │   ├── components/
++│   ├── hooks/          # New directory
+ │   └── utils/
+
+@@ -25,6 +26,7 @@ bun dev               # Start dev server
+ bun build             # Production build
+ bun test              # Run tests
++bun typecheck         # Type checking
+
+[init] Would update 2 sections
+[init] Exit code: 0 (dry run, no changes written)
+```
+
+---
+
+## Scheduling Recommendations
+
+| Frequency | Use Case |
+|-----------|----------|
+| Nightly | Active development, frequent changes |
+| Weekly | Stable projects, occasional updates |
+| On PR merge | Keep in sync with main branch |
+| Manual | When you remember / before major work |
+
+**Tip:** Use `--diff` in PR checks to catch when CLAUDE.md is stale:
+
+```yaml
+- name: Check CLAUDE.md freshness
+  run: |
+    claude --print "/init --ci --update --diff" > /tmp/diff.txt
+    if grep -q "Changes that would be made" /tmp/diff.txt; then
+      echo "::warning::CLAUDE.md may be stale. Run '/init --update' to refresh."
+    fi
+```
+
+---
+
+Now initialize CLAUDE.md for: $ARGUMENTS

plugin.lock.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:nathanvale/side-quest-marketplace:plugins/claude-code-claude-md",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "917d48308a58340583a949792e23b74517074fb3",
+    "treeHash": "6aca974cb574e5de5b4626635f5167c5a5447ed390bbd6c1ff8f38bb2998f310",
+    "generatedAt": "2025-11-28T10:27:15.675756Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "claude-code-claude-md",
+    "description": "CLAUDE.md manager for creating and optimizing memory files across the hierarchical cascade system",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "7b650cf3dfcb4a1eec0311e889adf20cc93517577b8d6efadfc00edf9431ef76"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "e77a9ffa2967668db4b6acb98f28b1c06f32cec1812fb4849411a47afb2d2522"
+      },
+      {
+        "path": "commands/import-docs.md",
+        "sha256": "22b98cabb69ec7e379b94824c6e9bc3a857a950a9d9128fbfdfddfa54904995a"
+      },
+      {
+        "path": "commands/init.md",
+        "sha256": "e24c7047f97500b7693a10495074a30270d8d45010b8c3d8edcdf5c04140ebf6"
+      },
+      {
+        "path": "commands/audit.md",
+        "sha256": "cfdda77f77f83828844c121e008c207cf9c10b9ab34a2fed41f9b3f076aca0d1"
+      }
+    ],
+    "dirSha256": "6aca974cb574e5de5b4626635f5167c5a5447ed390bbd6c1ff8f38bb2998f310"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}