commit 1312c2171e4b2de8a3a14ef3c97ea02b3c0987ad Author: Zhongwei Li Date: Sun Nov 30 08:41:58 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..28e7ffa --- /dev/null +++ b/.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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..722ff2f --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# claude-code-claude-md + +CLAUDE.md manager for creating and optimizing memory files across the hierarchical cascade system diff --git a/commands/audit.md b/commands/audit.md new file mode 100644 index 0000000..fd5525b --- /dev/null +++ b/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 diff --git a/commands/import-docs.md b/commands/import-docs.md new file mode 100644 index 0000000..a6af569 --- /dev/null +++ b/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 diff --git a/commands/init.md b/commands/init.md new file mode 100644 index 0000000..82a84e8 --- /dev/null +++ b/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 ``) +- 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 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 = ""; + const CUSTOM_END = ""; + + 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 `` + - 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 = ""; +const CUSTOM_END = ""; +const AUTO_MARKER = ""; + +// 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 │ +│ │ +│ ## My Custom Section ← preserve │ +│ │ +│ ## Key Files ← update │ +└─────────────────────────────────────┘ +``` + +### 4. Custom Section Markers + +To protect custom content from auto-updates, wrap in markers: + +```markdown + +## Special Rules + +- Never modify src/legacy/ - deprecated +- Always run migrations after model changes +- Check with Nathan before major refactors + + +``` + +--- + +## 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 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..6605a7c --- /dev/null +++ b/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": [] + } +} \ No newline at end of file