claude-md-generator

name	claude-md-generator
description	Generate CLAUDE.md from codebase analysis using repoforge — hotspots, ownership, hidden coupling, active decisions. No LLM calls needed. Trigger: When user says "generate CLAUDE.md", "analyze codebase for onboarding", or wants automated project context documentation.
license	MIT
metadata	{"author":"gentleman-programming","version":"1.0","tags":["onboarding","context","repoforge","analysis"],"category":"tooling"}
allowed-tools	Read, Bash, Glob, Grep, Write

Claude MD Generator

Generate a comprehensive CLAUDE.md file from pure static analysis of a codebase. Uses repoforge CLI commands (no API key, no LLM calls) to extract actionable project intelligence.

---

Core Principle

A good CLAUDE.md gives an AI agent instant context about a project: what matters, who owns what, where the dragons live, and what decisions are in flight. This skill automates that by running repoforge analysis commands and synthesizing the output into a structured document.

No LLM required — all analysis is done by repoforge's static analysis engine (graph, ownership, co-change, complexity, dead-code).

---

What You Receive

The orchestrator or user provides:

• project_path — path to the repository to analyze
• output_path — where to write the CLAUDE.md (default: {project_path}/CLAUDE.md)
• sections — optional list of sections to include (default: all)

---

Execution Steps

Step 1: Pre-Flight Check

Verify repoforge is available:

repoforge --version

If not found, tell the user to install it: pip install repoforge-ai or check the project at /home/javier/programacion/repoforge.

Step 2: Run Analysis Commands

Run these repoforge commands against the target repo. Each produces a section of the final CLAUDE.md. All commands are API-key-free.

ANALYSIS PIPELINE:
├── repoforge export -w {path} --no-contents --max-tokens 5000
│   └── Project structure overview
├── repoforge ownership -w {path} --bus-factor --json
│   └── Per-file and per-directory ownership + bus factor risks
├── repoforge co-change -w {path} --json
│   └── Hidden coupling: files that change together without import links
├── repoforge prompts -w {path} -o /tmp/rf-prompts
│   └── Complexity hotspots from the performance prompt
├── repoforge dead-code -w {path} --json
│   └── Unused exports and unreachable code
└── repoforge graph -w {path} --json (optional, if index exists)
    └── God nodes — over-connected coupling hotspots

Run commands in parallel where possible. Use --json output for structured parsing. Use --quiet to suppress progress bars.

Step 3: Parse and Extract

From each command output, extract the key insights:

From ownership --bus-factor --json:

• Top 5 files with highest ownership concentration (>80% single author)
• Directories with bus factor = 1
• Format as a "Bus Factor Risks" table

From co-change --json:

• Pairs with has_import_link: false (truly hidden coupling)
• Top 10 pairs by co-change count
• Format as "Hidden Coupling" section

From prompts output (performance prompt):

• High-complexity functions (cyclomatic complexity > 10)
• Large files (>500 lines)
• Format as "Hotspots" section

From dead-code --json:

• Unused exports count
• Top unreachable functions
• Format as "Technical Debt" note

From export --no-contents:

• Project structure tree
• Language/framework detection
• Entry points

Step 4: Detect Active Decisions

Scan the codebase for decision markers:

# Search for TODO, FIXME, HACK, DECISION, ADR references
rg -c "TODO|FIXME|HACK|DECISION|ADR" {path} --type-add 'src:*.{ts,js,py,go,rs,java}' --type src

Also check for:

• docs/adr/ or docs/decisions/ directories
• ARCHITECTURE.md or DECISIONS.md files
• Recent large PRs (via gh pr list --state merged --limit 10)

Step 5: Assemble CLAUDE.md

Write the final document with this structure:

# {Project Name}

> Auto-generated by claude-md-generator. Last updated: {DATE}

## Project Overview
- **Language**: {detected}
- **Framework**: {detected}
- **Package Manager**: {detected}
- **Test Framework**: {detected}

## Architecture
{structure tree from export, max 60 lines}

## Hotspots
High-complexity areas that need careful attention:

| File | Function | Complexity | Lines |
|------|----------|-----------|-------|
| ... | ... | ... | ... |

## Ownership & Bus Factor
Files and modules with concentrated knowledge:

| Path | Top Contributor | Ownership | Bus Factor | Risk |
|------|----------------|-----------|------------|------|
| ... | ... | ... | ... | ... |

## Hidden Coupling
Files that change together without import relationships:

| File A | File B | Co-changes | Confidence |
|--------|--------|-----------|------------|
| ... | ... | ... | ... |

## Active Decisions
- {TODO/FIXME counts by directory}
- {Links to ADR files if found}
- {Recent architectural PRs}

## Technical Debt
- Dead code: {count} unused exports
- {Notable unreachable functions}

## Conventions
{Detected from existing config files: linter, formatter, test patterns}

Step 6: Validate Output

• Ensure CLAUDE.md is under 4000 tokens (~3000 words)
• Verify all file paths referenced actually exist
• Remove sections that produced no data (don't show empty tables)

---

Configuration

The skill accepts an optional config section in openspec/config.yaml:

claude-md-generator:
  sections:            # Which sections to include (default: all)
    - overview
    - hotspots
    - ownership
    - coupling
    - decisions
    - debt
    - conventions
  max_tokens: 4000     # Target token budget for output
  ownership:
    threshold: 0.8     # Ownership concentration threshold
    since: "1 year ago" # Git history window
  co_change:
    threshold: 0.5     # Co-change confidence threshold
    min_commits: 3     # Minimum co-occurrences

---

Critical Rules

1. NEVER call an LLM — all analysis is pure repoforge static analysis
2. NEVER include file contents in the CLAUDE.md — only metadata and insights
3. ALWAYS verify repoforge is installed before running commands
4. ALWAYS use --json output for parsing, --quiet for clean execution
5. ALWAYS respect the token budget — prune aggressively if output exceeds limit
6. If a repoforge command fails, skip that section with a comment, do NOT abort
7. Hidden coupling section is the highest-value insight — prioritize it
8. File paths in output MUST be relative to project root