Gen Claude

---
name: gen-claude
description: Generate or enhance CLAUDE.md with project-specific guidance following best practices
argument-hint: "[--force] [--template=minimal|standard|comprehensive] [--no-docs] [--dry-run]"
user-invocable: true
disable-model-invocation: true
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(git:*), Bash(find:*), Bash(wc:*), Bash(awk:*), Task, AskUserQuestion
---

# Generate CLAUDE.md

Automatically generate or enhance a project-specific CLAUDE.md file following 2025-2026 best practices. This skill performs deep codebase analysis to create comprehensive project documentation that stays within the 2500 token limit.

## Why This Skill Exists

**Problem**: Projects often lack CLAUDE.md files or have poorly structured ones, forcing Claude to operate without project-specific context.

**Solution**: Automated generation that:
- Analyzes codebase comprehensively
- Auto-detects linter/formatter configs (avoids duplication)
- Creates docs/ folder for progressive disclosure
- Merges/enhances existing CLAUDE.md (preserves customizations)
- Optimizes for 2500 token limit

## Content Generation Rules

**CRITICAL**: When generating any content (CLAUDE.md, docs/, commit messages, descriptions, or any other output):
- **NEVER** add Claude Code attribution or co-authorship
- **NEVER** include phrases like "Generated by Claude", "Created with Claude Code", or similar
- **NEVER** add "Co-Authored-By: Claude" in commit messages or documentation
- All generated content should appear as if written by a human developer
- Focus on technical accuracy and project-specific details, not tool attribution

## Process (5 Phases)

### Phase 1: Parallel Discovery (4 Sonnet Agents)

Launch 4 independent agents concurrently to analyze different aspects of the project:

**Agent #1: Project Structure Analyzer**
```
Task(subagent_type: "Explore", model: "sonnet", prompt: "
Analyze project structure and return JSON:
{
  languages: [list of detected languages from file extensions],
  frameworks: [frameworks/libraries detected from imports/configs],
  buildTool: string (npm/go/cargo/maven/gradle/make/task/etc),
  buildCommands: {build: '', test: '', lint: '', run: ''},
  structure: {
    source: path,
    tests: path,
    docs: path,
    config: path
  }
}

Detection strategy:
- Languages: Glob for *.go, *.js, *.py, *.rs, *.java, *.rb, *.php
- Build tools: Look for package.json, go.mod, Cargo.toml, requirements.txt, pom.xml, build.gradle, Makefile, Taskfile.yml
- Extract commands from: npm scripts, Makefile targets, Taskfile tasks, go.mod for go commands
- Map directory structure: src/, test/, docs/, internal/, cmd/, pkg/
")
```

**Agent #2: Linter Config Detective**
```
Task(subagent_type: "Explore", model: "sonnet", prompt: "
Find all linter/formatter configuration files and return JSON:
[
  {path: string, tool: string, ruleCount: estimate}
]

Search for:
- ESLint: .eslintrc*, eslint.config.*
- Prettier: .prettierrc*, prettier.config.*
- golangci-lint: .golangci.yml, .golangci.yaml
- Rubocop: .rubocop.yml
- Pylint: pylintrc, .pylintrc, pyproject.toml
- EditorConfig: .editorconfig
- Black: pyproject.toml
- Flake8: .flake8, setup.cfg
- rustfmt: rustfmt.toml
- checkstyle: checkstyle.xml

Use Glob: **/.{eslintrc,prettierrc,golangci,rubocop,pylintrc,flake8,editorconfig}*
Also search: **/rustfmt.toml, **/checkstyle.xml, **/pyproject.toml

For each config: extract path, tool name, estimate rule count from file size
")
```

**Agent #3: Architectural Pattern Recognizer**
```
Task(subagent_type: "Explore", model: "sonnet", prompt: "
Analyze code organization and identify 3-5 key architectural patterns.

Focus areas:
1. Code organization: monorepo vs modular vs flat structure
2. Testing patterns: test file locations, naming conventions (test/, _test.go, .test.js, .spec.js)
3. Error handling: error wrapping patterns, custom error types
4. API patterns: REST endpoints, GraphQL schemas, gRPC services
5. Database patterns: ORM usage (sqlx, gorm, sequelize), migration strategy
6. Dependency injection: constructor injection, interface patterns

Return structured list:
[
  {pattern: 'Repository pattern', description: '...', examples: ['file:line']},
  {pattern: 'Error wrapping', description: '...', examples: ['file:line']},
  ...
]

Provide concrete file:line references for each pattern.
")
```

**Agent #4: Repository Context Gatherer**
```
Task(subagent_type: "general-purpose", model: "sonnet", prompt: "
Extract repository metadata and return JSON:
{
  remote: string (GitHub/GitLab/Bitbucket/self-hosted URL),
  readme: {
    exists: bool,
    projectName: string,
    description: string (first 2-3 sentences),
    sections: [list of ## headers]
  },
  contributing: bool (CONTRIBUTING.md exists),
  license: string (LICENSE file content first line),
  cicd: [list of CI/CD files found]
}

Steps:
1. Run: git remote -v (to get remote URL)
2. Read README.md if exists
3. Check for CONTRIBUTING.md, CODE_OF_CONDUCT.md
4. Detect CI/CD: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, .circleci/config.yml
5. Read LICENSE file
")
```

**Why parallel?** Independent analyses complete in ~30s total vs ~120s sequential.

Wait for all 4 agents to complete before proceeding to Phase 2.

### Phase 2: Existing CLAUDE.md Analysis

1. **Check if CLAUDE.md exists** at `./CLAUDE.md`
   ```bash
   # Using Read tool, not Bash
   Read file_path: "./CLAUDE.md"
   ```

2. **If exists:**
   - Read entire content
   - Calculate tokens:
     ```bash
     wc -c CLAUDE.md | awk '{print int($1/4)}'
     ```
   - Parse sections: Use Grep to find `^## ` headers
   - Identify custom sections (user-added content beyond standard template)
   - Store for merge in Phase 3
   - Set `existingClaudeMd = <content>`, `isNew = false`

3. **If not exists:**
   - Set `isNew = true`
   - Set `existingClaudeMd = null`

### Phase 3: Content Generation

Parse skill arguments (from argument string):
- `--template=minimal|standard|comprehensive` (default: standard)
- Other flags parsed in Phase 5

**Validate required asset:**
- Use Read tool to load `${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/behavioral-guidelines-section.md`
- If it fails: Exit with error "Skill asset not found at ${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/behavioral-guidelines-section.md. Plugin may be corrupted. Reinstall the software-engineering plugin."
- This asset is validated here (Phase 3), not in Phase 4 — Phase 4 is skipped wholesale when `--no-docs` is set, but this section is emitted regardless of that flag
- Keep the loaded content for the verbatim splice below and for the Phase 5 integrity check

**Template Selection:**
- **minimal**: 90-110 lines (overview + commands + linter refs)
- **standard**: 110-140 lines (includes architecture) [DEFAULT]
- **comprehensive**: 140-160 lines (includes patterns + examples)

Each range includes the ~61-line `## Behavioral Guidelines` block, present in all three templates.

**Content Structure:**

````markdown
# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

[If --no-docs NOT set:]
## Operating Guidelines

**Read `docs/operating-guidelines.md` at the start of every session.** It
defines how to plan, verify, and iterate in this repository: plan mode,
subagent strategy, verification gates, self-improvement loop, and the
communication contract. Treat it as load-bearing context.

[Always, every template, regardless of --no-docs:]
[Insert the `## Behavioral Guidelines` section verbatim from ${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/behavioral-guidelines-section.md — the asset carries its own H2 heading. Do NOT paraphrase, reorder, renumber, or compress.]

## Repository Overview
[2-3 sentences from Agent #4 README analysis + detected tech stack from Agent #1]

Example:
"This is a [detected framework] application built with [languages]. [README description]. The project follows [key pattern from Agent #3]."

## Architecture
[3-6 bullets from Agent #3 pattern analyzer]
- [Key pattern 1: e.g., "Monorepo structure with /packages"]
- [Key pattern 2: e.g., "Repository pattern for database access"]
- [Key pattern 3: ...]

[If template != minimal:]
- Link: See docs/architecture.md for detailed design decisions

## Development Commands
[Essential commands from Agent #1 build tool analysis]
```bash
# Build
[detected command]

# Test
[detected command]

# Lint
[detected command]

# Run
[detected command]
```

## Code Quality Standards
**Linters configured** (do not duplicate rules):
[From Agent #2: for each config]
- [Tool]: See [config path] for complete rule set

[If template == comprehensive:]
**Key conventions:**
- [Convention 1 from Agent #3]
- [Convention 2 from Agent #3]

## File Locations
- **Source**: [detected from Agent #1]
- **Tests**: [detected from Agent #1]
- **Docs**: docs/
[If build tool specific:]
- **Config**: [detected from Agent #1]

[If template != minimal:]
## Documentation
- docs/architecture.md: System design and component overview
- docs/workflows.md: Development processes and git workflow
- docs/patterns.md: Code patterns and best practices

[If existingClaudeMd and custom sections found:]
[Insert preserved custom sections here]
````

**Merge Algorithm (if `!isNew`):**
1. Parse existing CLAUDE.md sections (split by `^## `)
2. Identify standard sections: "Operating Guidelines", "Behavioral Guidelines", "Repository Overview", "Architecture", "Development Commands", "Code Quality Standards", "File Locations", "Documentation"
3. Identify custom sections: everything else
4. Update standard sections with fresh analysis from agents
5. Preserve all custom sections verbatim at end of file
6. Keep user-added bullet points within standard sections
7. Calculate token count: if > 2000, apply compression (see Phase 5) — the protected Behavioral Guidelines block is excluded from compression; compress project-specific content only

**Operating Guidelines section — merge rules:**
- If `--no-docs` is set: do NOT insert the section. If it already exists in the current file, leave it untouched (user may have curated it).
- If the section exists: replace its body with the canonical wording from the content template above.
- If the section is missing: insert it as the first section, immediately after the file title and before `## Behavioral Guidelines`.

**Behavioral Guidelines section — merge rules:**
- **Always inserted.** Not gated on `--no-docs`, not gated on `--template`.
- Anchor: immediately after `## Operating Guidelines`; if that section is absent (because `--no-docs` suppressed it), immediately after the file title. Always before `## Repository Overview`.
- If the section exists: replace its body **wholesale** from the asset. Step 6 above ("keep user-added bullet points within standard sections") explicitly does NOT apply here — there is no bullet-level merge for this section.
- **Migration rule**: if the file contains standalone H2s `## 1. Think Before Coding`, `## 2. Simplicity First`, `## 3. Surgical Changes`, or `## 4. Goal-Driven Execution` (hand-rolled or from an older layout), delete them and emit the single wrapped section instead. Do NOT classify them as custom sections.
- Never relocated to end of file; never moved to `docs/`; never compressed or reworded.

**New File (`isNew == true`):**
Generate from template using agent results.

### Phase 4: docs/ Structure Creation

**Parse flag:** Check if `--no-docs` in arguments. If yes, skip this phase.

**Validate asset templates:**
- Use Read tool to verify these assets exist in `${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/`:
  - `architecture-template.md`
  - `workflows-template.md`
  - `patterns-template.md`
  - `operating-guidelines.md`
- If any fails: Exit with error "Skill assets directory not found or incomplete at ${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/. Plugin may be corrupted. Reinstall the software-engineering plugin."

**Create docs/ folder structure** (only if missing):

```bash
# Check if docs/ exists
# If not, create: docs/architecture.md, docs/workflows.md, docs/patterns.md, docs/operating-guidelines.md
```

**docs/architecture.md** (30-50 lines):
- Read template from `${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/architecture-template.md`
- Populate placeholders with Phase 1 agent results

**docs/workflows.md** (30-50 lines):
- Read template from `${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/workflows-template.md`
- Populate placeholders with Phase 1 agent results

**docs/patterns.md** (30-50 lines):
- Read template from `${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/patterns-template.md`
- Populate placeholders with Phase 1 agent results

**docs/operating-guidelines.md** (static, ~110 lines):
- Read file from `${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/operating-guidelines.md`
- Write verbatim to `./docs/operating-guidelines.md` — this is a static asset, not a template; do NOT substitute placeholders or alter content
- Defines workflow orchestration, verification, self-improvement loop, and the communication contract that `CLAUDE.md` references

**Creation Rules:**
- Only create `docs/` if it doesn't exist
- Only create individual files (`architecture.md`, `workflows.md`, `patterns.md`, `operating-guidelines.md`) if they don't exist
- If files exist, do NOT overwrite (unless `--force` flag present)
- Populate the three templates with insights from Phase 1 agents; copy `operating-guidelines.md` verbatim

### Phase 5: Validation & User Approval

**Parse additional flags:**
- `--force`: Regenerate from scratch (backup existing to `CLAUDE.md.backup`)
- `--dry-run`: Show preview without writing files

**If `--force` flag:**
```bash
# Backup existing CLAUDE.md
cp CLAUDE.md CLAUDE.md.backup
# Then regenerate from scratch (ignore merge algorithm)
```

**Validation Checks:**

1. **Token count:**
   ```bash
   wc -c CLAUDE.md | awk '{print int($1/4)}'
   ```
   - Must be < 2500 tokens
   - Target: < 2000 tokens (leaves buffer)
   - If > 2000: Show warning
   - If > 2500: Apply compression (see below)
   - **Fixed overhead** (already accounted for in the 2000-token target):
     - `## Operating Guidelines`: ~40 tokens
     - `## Behavioral Guidelines`: ~545 tokens, verbatim, non-negotiable
     - Total: ~585 tokens
   - **Project-specific content budget**: ~1415 tokens (target) / ~1915 tokens (hard max)

2. **Linter references:**
   - For each linter config mentioned in CLAUDE.md
   - Verify file exists using Read tool
   - If missing: Remove reference or add "TODO: configure"

3. **Markdown validity:**
   - Check header hierarchy (no skipped levels: ## → ### not ## → ####)
   - Verify code blocks closed (count ``` pairs — the Behavioral Guidelines block contributes exactly one pair, its plan-skeleton fence)
   - Check list formatting consistency
   - `## Behavioral Guidelines` hierarchy intact: H2 wrapper with exactly four `### N. <Name>` children, numbered 1-4
   - **Verbatim integrity**: the emitted `## Behavioral Guidelines` block matches `${CLAUDE_PLUGIN_ROOT}/assets/gen-claude/behavioral-guidelines-section.md` byte-for-byte. If it does not, re-splice from the asset — do not hand-repair

4. **Link integrity:**
   - For each docs/ reference in CLAUDE.md
   - Verify file exists or will be created
   - Check internal section links valid
   - Specifically verify that `docs/operating-guidelines.md` exists (or will be created in Phase 4) whenever CLAUDE.md contains the `## Operating Guidelines` section — the section must never reference a missing file
   - The `## Behavioral Guidelines` block must be self-contained — no docs/ or external links — so it remains valid under `--no-docs`

**Token Overflow Handling:**

**Protected regions — never compress, abbreviate, reorder, renumber, or relocate:**
- `## Behavioral Guidelines` — a byte-identical copy of the plugin asset. Compressing it defeats its purpose and breaks the verbatim-integrity check.
- `## Operating Guidelines` — already only ~40 tokens.

All three compression passes below operate on project-specific content only.

If token count > 2500 after generation:
1. **First pass compression:**
   - Remove examples from CLAUDE.md (keep in docs/patterns.md)
   - Abbreviate bullet points (excluding protected regions)
   - Use tables for structured data
   - Compress whitespace

2. **Second pass compression:**
   - Move "Architecture" section content to docs/architecture.md
   - Leave only: "See docs/architecture.md for system design"
   - Move patterns to docs/patterns.md
   - Never move a protected region to docs/

3. **Last resort:**
   - Split into `CLAUDE.md` + `CLAUDE-EXTENDED.md`
   - Keep essential info in CLAUDE.md (< 2500 tokens)
   - Move detailed info to CLAUDE-EXTENDED.md
   - `## Behavioral Guidelines` stays in `CLAUDE.md` — it never migrates to `CLAUDE-EXTENDED.md`
   - Add reference: "See CLAUDE-EXTENDED.md for additional context"

**User Presentation:**

```
📊 CLAUDE.md Generation Complete

Analysis Results:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Detected: [languages from Agent #1]
✅ Build tool: [tool from Agent #1] ([X] commands found)
✅ Linters: [tools from Agent #2] ([X] configs found)
✅ Patterns: [count from Agent #3] architectural patterns identified

Generated CLAUDE.md:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Length: [X] tokens ([status: ✅ under 2000 / ⚠️ 2000-2500 / ❌ over 2500])
  - Fixed overhead: ~585 tokens (Operating Guidelines ~40 + Behavioral Guidelines ~545)
  - Project content: [X] tokens
- Behavioral Guidelines: ✅ included (~545 tokens, verbatim from plugin asset)
- Sections: [X] ([X] standard + [X] custom preserved)
- Commands: [X] development commands

[If docs/ created:]
Created documentation:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ docs/architecture.md ([X] lines)
✅ docs/workflows.md ([X] lines)
✅ docs/patterns.md ([X] lines)
✅ docs/operating-guidelines.md ([X] lines, static)

[If existing CLAUDE.md was merged:]
ℹ️  Preserved [X] custom sections from existing CLAUDE.md

[If --force was used:]
💾 Backup saved: CLAUDE.md.backup
```

**Dry Run Mode:**
If `--dry-run` flag present:
- Generate all content
- Show preview (first 50 lines + summary)
- Do NOT write any files
- Exit without changes

**User Approval:**
If token count > 2000 or custom sections were modified:
```
Use AskUserQuestion:
Question: "Generated CLAUDE.md is [X] tokens. [Status message]. Proceed with writing files?"
Options:
1. "Yes, write files"
2. "Show full preview first"
3. "Apply compression and regenerate"
4. "Cancel"
```

**Write Files:**
If approved (or auto-approved if < 2000 tokens and no modifications):
1. Write `./CLAUDE.md`
2. Create `docs/` folder if needed
3. Write `docs/architecture.md`, `docs/workflows.md`, `docs/patterns.md`, `docs/operating-guidelines.md` (if not existing)
4. Report success with file paths

## Arguments

Arguments are parsed from the `argument` string parameter:

- `--force`: Backup existing CLAUDE.md to `CLAUDE.md.backup` and regenerate from scratch
- `--template=minimal`: Generate 90-110 line CLAUDE.md (overview + commands + linter refs only)
- `--template=standard`: Generate 110-140 line CLAUDE.md (includes architecture) [DEFAULT]
- `--template=comprehensive`: Generate 140-160 line CLAUDE.md (includes patterns + examples)

Each range includes the ~61-line `## Behavioral Guidelines` block, which is present in all three templates.
- `--no-docs`: Skip docs/ folder creation (only generate CLAUDE.md)
- `--dry-run`: Show preview without writing any files

**Parsing example:**
```
argument = "--force --template=comprehensive --dry-run"
Split by space, check for each flag presence
```

## Error Handling

### Agent Failures

**Timeout (>90s per agent):**
- Use partial results from successful agents
- Log which agents failed
- Continue with available data

**All agents fail:**
- Fall back to minimal template
- Use README.md analysis only (without agents)
- Generate basic CLAUDE.md with project name + "Add project details manually"

### Missing Critical Files

**No README.md:**
- Generate minimal README.md alongside CLAUDE.md
- Use git remote for project name fallback
- Content: "# [ProjectName]\n\nProject description goes here."

**No build tool detected:**
- Include generic command template
- Provide common examples based on detected language:
  - Go: `go build`, `go test`, `go vet`
  - JavaScript: `npm install`, `npm test`, `npm run build`
  - Python: `pip install -r requirements.txt`, `pytest`
  - Rust: `cargo build`, `cargo test`, `cargo clippy`

**No git remote:**
- Set project name from current directory name
- Skip CI/CD detection
- Note in CLAUDE.md: "Repository: local (no remote configured)"

### Token Overflow

**Still over 2500 after compression:**
- Create `CLAUDE-EXTENDED.md` with overflow content
- Add reference in `CLAUDE.md`: "See CLAUDE-EXTENDED.md for additional context"
- Prioritize keeping: Behavioral Guidelines (verbatim), Operating Guidelines, Overview, Commands, Linter references in main file

**Phase 1 agents timeout:**
- Extend timeout to 120s
- If still fails: use minimal analysis (Glob/Grep from the main skill, not agents)

## Best Practices

**Token Management:**
- Target 1500-2000 tokens for CLAUDE.md (leaves growth room)
- Use progressive disclosure: keep CLAUDE.md concise, details in docs/
- Reference don't duplicate: link to linter configs instead of listing rules

**Content Quality:**
- Extract real examples from code (file:line references)
- Prioritize actionable information (commands, file locations)
- Avoid generic advice ("follow best practices") - be specific

**Attribution Policy:**
- Never include Claude Code attribution in any generated content
- Never add co-authorship lines in commit messages or documentation
- All content should appear as human-written, focusing on technical value
- No "Generated by", "Created with", or similar tool attribution phrases

**Merging Strategy:**
- Always preserve user customizations
- Update stale information (new build commands, new patterns)
- Append custom sections at end to avoid fragmentation

**Agent Coordination:**
- Phase 1 agents are independent (parallel execution)
- Phase 2-5 are sequential (each depends on previous)
- Each agent has specific JSON output format for easy parsing

## Integration with Other Skills

**Works with:**
- `/check-claude-md-tokens`: Run after generation to validate token count
- `/commit`: Commit generated files with conventional commit format
- `/audit-codebase`: Use generated CLAUDE.md as quality reference

**Workflow:**
```bash
# Generate CLAUDE.md
/gen-claude

# Validate token count
/check-claude-md-tokens

# Commit if valid
/commit
```

## Output Files

**Primary:**
- `./CLAUDE.md`: Project-specific guidance (90-160 lines, < 2500 tokens)

**Plugin assets consumed (read-only, never written to docs/):**
- `assets/gen-claude/behavioral-guidelines-section.md`: spliced verbatim into `./CLAUDE.md` as the `## Behavioral Guidelines` section (~61 lines, ~545 tokens)

**Supporting (if not existing):**
- `docs/architecture.md`: System design (30-50 lines)
- `docs/workflows.md`: Development processes (30-50 lines)
- `docs/patterns.md`: Code patterns (30-50 lines)
- `docs/operating-guidelines.md`: Workflow, verification, and self-improvement rules (~110 lines, static verbatim copy from plugin assets)

**Backup (if --force used):**
- `CLAUDE.md.backup`: Original CLAUDE.md before regeneration

## Examples

```bash
# Generate with defaults (standard template)
/gen-claude

# Force regenerate from scratch
/gen-claude --force

# Generate minimal CLAUDE.md only (no docs/)
/gen-claude --template=minimal --no-docs

# Preview without writing
/gen-claude --dry-run

# Comprehensive with docs/
/gen-claude --template=comprehensive

# Regenerate and skip docs folder
/gen-claude --force --no-docs
```

## Success Criteria

✅ CLAUDE.md generated or enhanced (90-160 lines)
✅ Token count < 2500 (ideally < 2000)
✅ Contains project overview (2-3 sentences)
✅ Lists development commands (4-8 commands)
✅ References linter configs (no rule duplication)
✅ Documents architectural patterns (3-6 patterns)
✅ Links to docs/ for extended info
✅ Preserves user customizations (if merging)
✅ docs/ created with 4 files — architecture, workflows, patterns, operating-guidelines (unless --no-docs)
✅ CLAUDE.md includes `## Operating Guidelines` section pointing at docs/operating-guidelines.md (unless --no-docs)
✅ CLAUDE.md includes `## Behavioral Guidelines` with 4 numbered subsections, byte-identical to the plugin asset (always — including --no-docs and --template=minimal)
✅ All validation checks pass
✅ Total runtime < 60 seconds (with parallel agents)