readme-generation

# README Generator Analyze a codebase and produce a complete, professional README.md. Parse the user's input to determine: - **Target**: a local path, a remote GitHub repo (e.g., `fortra/impacket`), or current directory (default) - **Style**: `security-tool`, `library`, `cli`, `webapp`, `minimal`, or auto-detect (default) - **Update mode**: if the user says "update" or the project already has a README, preserve custom sections Common patterns: - `$readme-generation` → generate for current directory, auto-detect style - `$readme-generation ~/projects/mytool` → generate for local path - `$readme-generation fortra/impacket` → clone and generate for remote repo - `$readme-generation --style security-tool` → force a specific style - `$readme-generation --update` → update existing README, keeping custom sections ## Steps ### 1. Acquire the codebase - If a remote repo is given: `gh repo clone owner/repo /tmp/readme-target` and work from there - If a local path is given: use that directory - Otherwise: use current working directory ### 2. Deep scan the project Read and analyze these files (skip any that don't exist): **Project metadata:** - `pyproject.toml`, `setup.py`, `setup.cfg` — Python project info, dependencies, entry points - `Cargo.toml` — Rust project info - `go.mod` — Go module info - `package.json` — Node.js project info - `Makefile`, `Justfile` — Build commands - `Dockerfile`, `docker-compose.yml` — Container setup - `.github/workflows/` — CI/CD configuration **Source code (sample, don't read everything):** - Entry points: `main.py`, `cli.py`, `main.go`, `main.rs`, `src/main.*`, `cmd/` - Top-level source files for imports and structure - CLI argument definitions (argparse, typer, cobra, clap) - Config file examples **Existing docs:** - Current `README.md` (if updating) - `CONTRIBUTING.md`, `CHANGELOG.md`, `LICENSE` - `docs/` directory contents **Git context:** - `git log --oneline -30` — recent activity and feature descriptions - `git tag --sort=-v:refname | head -5` — version history - `git remote -v` — origin URL ### 3. Determine project type and style Auto-detect from user input or infer: | Signal | Type | |---|---| | nmap/scanning/enum imports, --target flags | `security-tool` | | Library with no CLI, published to PyPI/crates | `library` | | CLI with subcommands, --help output | `cli` | | Web framework (Flask, FastAPI, Express, Next.js) | `webapp` | | Few files, single purpose | `minimal` | ### 4. Generate README using the appropriate template #### Security Tool Template ```markdown # [Name] [One-line description of what it does and why you'd use it] ## Features - [Key capability 1] - [Key capability 2] - [Key capability 3] ## Installation [Package manager install or build from source — include both if applicable] ## Quick Start ```bash [Single command showing the most common usage] ``` ## Usage ``` [Full --help output or manual command reference] ``` ### Examples ```bash # [Description of scenario 1] [command] # [Description of scenario 2] [command] # [Description of scenario 3] [command] ``` ## Output Formats [If the tool supports multiple output formats, show examples of each] ## Requirements - [Runtime dependencies] - [System requirements] - [Required access/permissions] ## Building from Source ```bash [Build steps] ``` ## License [License type and link] ``` #### Library Template ```markdown # [Name] [One-line description] ## Installation ```bash [pip install / cargo add / go get command] ``` ## Quick Start ```python (or appropriate language) [Minimal working example — 5-10 lines] ``` ## API Reference ### [Module/Class Name] #### `function_name(params) -> return_type` [Description and example] ## Configuration [Config options if applicable] ## Contributing [How to contribute, run tests, submit PRs] ## License [License] ``` #### CLI Template ```markdown # [Name] [One-line description] ## Installation ```bash [Install command] ``` ## Usage ``` [Command syntax overview] ``` ### Commands #### `command-name` [Description, flags, example] ## Configuration [Config file location and format if applicable] ## Examples [2-3 real-world usage scenarios] ## License [License] ``` #### Webapp Template ```markdown # [Name] [One-line description] ## Tech Stack - [Frontend framework] - [Backend framework] - [Database] - [Deployment] ## Getting Started ### Prerequisites [Required software and versions] ### Setup ```bash [Clone, install deps, configure, run — step by step] ``` ### Environment Variables | Variable | Description | Default | |---|---|---| | `VAR_NAME` | What it does | `default` | ## Development ```bash [Dev server, test, lint commands] ``` ## Deployment [How to deploy] ## License [License] ``` #### Minimal Template ```markdown # [Name] [One-line description] ## Usage ```bash [Primary usage command] ``` ## Install ```bash [Install steps] ``` ## License [License] ``` ### 5. Writing guidelines - **First line matters most** — the description after `# Name` should explain what the tool does AND why someone would use it, in one sentence - **Show, don't tell** — real command examples over descriptions of what's possible - **Copy-pasteable** — every code block should work if pasted into a terminal - **No filler** — skip badges, excessive formatting, or sections with no content - **Accurate dependencies** — only list what's actually required, pulled from the project files - **Version-aware** — if the project has tags, reference the latest version in install commands ### 6. Update mode When updating an existing README (user said "update" or `--update`): 1. Read the existing README fully 2. Identify **custom sections** — any section not in the standard template (acknowledgments, special notes, contributor lists, etc.) 3. Regenerate the standard sections with current project data 4. **Preserve custom sections in their original position** — do not delete or rewrite them 5. If a standard section has user-added content beyond what the template provides (e.g., extra examples), keep the user additions and only update the generated parts 6. Show a diff summary of what changed before writing ### 7. Output - Write the README to the project directory - If working on a remote repo in `/tmp/`, also copy the output to the current directory as `README-[project-name].md` - Report the file path and a brief summary of what was generated