zhongwei/gh-nathanvale-side-quest-marketplace-plugins-claude-code-claude-md
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:41:58 +08:00
commit 1312c2171e
6 changed files with 1340 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

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

168
commands/audit.md Normal file
View File

@@ -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

286
commands/import-docs.md Normal file
View File

@@ -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

819
commands/init.md Normal file
View File

@@ -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

53
plugin.lock.json Normal file
View File

@@ -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": []
}
}