Name: readme-maker
Author: asabocinski

Prompt file imported from asabocinski/bravo-edd (.codex/prompts/readme-maker.md). Copyright stays with the author.

README Maker Command

Generates a professional README.md by combining codebase exploration with documentation best practices.

Usage

/readme-maker                        # Full analysis → README.md
/readme-maker --output docs/         # Output to specific directory
/readme-maker --style minimal        # Minimal README (Quick Start focus)
/readme-maker --style comprehensive  # Full documentation (default)
/readme-maker --dry-run              # Preview without saving

What It Does

Explores codebase using codebase-explorer patterns
Analyzes project structure, tech stack, and patterns
Generates README.md following code-documenter standards
Validates all examples and links before saving

Execution Flow

┌─────────────────────────────────────────────────────────────┐
│  README-MAKER WORKFLOW                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Phase 1: EXPLORE (codebase-explorer patterns)              │
│  ├─ Scan root structure (ls, package files, configs)        │
│  ├─ Map source code (Glob patterns by language)             │
│  ├─ Identify tech stack and frameworks                      │
│  ├─ Count files, tests, documentation                       │
│  └─ Calculate health score                                  │
│                                                             │
│  Phase 2: EXTRACT (project metadata)                        │
│  ├─ Read package.json / pyproject.toml / Cargo.toml         │
│  ├─ Parse existing README (if present)                      │
│  ├─ Detect entry points (main, index, handler)              │
│  ├─ Find installation/setup commands                        │
│  └─ Identify environment variables                          │
│                                                             │
│  Phase 3: GENERATE (code-documenter patterns)               │
│  ├─ Create compelling project description                   │
│  ├─ Build Quick Start with tested commands                  │
│  ├─ Document features with examples                         │
│  ├─ Add architecture overview (if complex)                  │
│  └─ Include contributing guidelines                         │
│                                                             │
│  Phase 4: VALIDATE (quality checks)                         │
│  ├─ Test all installation commands                          │
│  ├─ Verify code examples work                               │
│  ├─ Check all links resolve                                 │
│  └─ Ensure no placeholder text remains                      │
│                                                             │
│  Phase 5: OUTPUT                                            │
│  ├─ Write README.md to project root                         │
│  └─ Report summary of what was generated                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Analysis Steps

Step 1: Scan Project Structure

# Root structure
ls -la (root)
Read README.md (if exists - preserve manual content)

# Package files (detect language/framework)
Glob("**/package.json")      # Node.js
Glob("**/pyproject.toml")    # Python
Glob("**/Cargo.toml")        # Rust
Glob("**/go.mod")            # Go
Glob("**/pom.xml")           # Java/Maven
Glob("**/build.gradle")      # Java/Gradle

# Source code
Glob("src/**/*")             # Main source
Glob("lib/**/*")             # Library code
Glob("tests/**/*")           # Test files
Glob("docs/**/*")            # Documentation

Step 2: Extract Project Metadata

# From package files
- Project name
- Version
- Description
- Author/maintainers
- License
- Dependencies (key ones)
- Scripts/commands

# From codebase
- Primary language
- Framework(s)
- Entry points
- Environment variables (from .env.example, config)
- API endpoints (if applicable)

Step 3: Generate README Sections

Use this template structure:

# {Project Name}

> {Compelling one-line description from package or inferred}

{Badges: build status, version, license}

## Overview

{2-3 paragraphs explaining:}
- What the project does
- Why it exists (problem it solves)
- Who it's for

## Features

{Bullet list with brief descriptions}
- Feature 1: Description
- Feature 2: Description

## Quick Start

{60-second setup - MUST be tested commands}

### Prerequisites

- {requirement 1}
- {requirement 2}

### Installation

```bash
{installation commands}

Basic Usage

{usage example}

Documentation

{Table linking to detailed docs if they exist}

Topic	Link
API Reference	docs/api.md
Configuration	docs/config.md

Architecture

{Only include if project is complex enough}

{Simple ASCII diagram}

Configuration

{Environment variables and config options}

Variable	Description	Default
`VAR_NAME`	What it does	`default`

Development

Setup

{dev setup commands}

Running Tests

{test commands}

Contributing

{Link to CONTRIBUTING.md or brief guidelines}

License

{License name} - see LICENSE


---

## Output Styles

### Minimal (`--style minimal`)

Sections included:
- Project name + description
- Quick Start (installation + basic usage)
- License

Best for: Small utilities, scripts, simple libraries

### Comprehensive (`--style comprehensive`) - Default

Sections included:
- All sections in template
- Architecture diagram
- Full configuration reference
- Development guide
- API documentation links

Best for: Production projects, open source, team codebases

---

## Quality Checklist

Before saving README.md, verify:

```text
CONTENT
[ ] Project description is clear and compelling
[ ] Quick Start works (commands tested)
[ ] Features accurately reflect codebase
[ ] No placeholder text like "TODO" or "{}"

FORMAT
[ ] Badges are valid (if included)
[ ] Code blocks have language hints
[ ] Tables properly formatted
[ ] Links point to existing files

ACCURACY
[ ] Version matches package file
[ ] Dependencies are current
[ ] Installation actually works
[ ] Examples produce expected output

Example Output

README GENERATION
━━━━━━━━━━━━━━━━━

Exploring codebase...
✓ Detected: Python project (pyproject.toml)
✓ Found: 17 source files, 4 test files
✓ Framework: Click CLI, Pydantic
✓ Entry point: src/task_runner/cli.py

Extracting metadata...
✓ Name: task-runner
✓ Version: 0.1.0
✓ License: MIT
✓ Dependencies: click, pydantic, faker

Generating README...
✓ Overview: from pyproject.toml description
✓ Quick Start: from scripts + entry point
✓ Features: from module analysis
✓ Configuration: from .env.example

Validating...
✓ Installation commands work
✓ Basic usage example runs
✓ All links valid

━━━━━━━━━━━━━━━━━
Saved: README.md (comprehensive style)

Preview:
# task-runner

> Flexible task execution framework with plugin support

## Quick Start

pip install -e .
task-runner run --workers 4 --output results/

Flags

Flag	Description
`--output {dir}`	Output directory (default: project root)
`--style {type}`	`minimal` or `comprehensive` (default)
`--dry-run`	Preview without saving
`--preserve-manual`	Keep manually-written sections (default: true)
`--force`	Overwrite without preserving manual content

Best Practices

When to Use

New projects without README
Projects with outdated README
After major refactoring
Before open-sourcing internal code

What to Review After

Overview - Add business context the tool can't infer
Features - Prioritize and add details
Architecture - Add domain-specific explanations
Contributing - Add team-specific guidelines

Integration with Other Commands

# Full documentation workflow
/readme-maker                    # Generate README
/sync-context                    # Update CLAUDE.md
/memory "Generated docs"         # Save what was done

Agent Integration

This command leverages:

Agent	Purpose
codebase-explorer	Comprehensive codebase analysis
code-documenter	Documentation generation patterns

The command combines:

Explorer's systematic analysis workflow
Documenter's quality checklist and templates
Both agents' validation requirements

Remember

"A README is often the first impression of your project"

Goal: Generate README that answers:

What is this?
Why should I care?
How do I use it?

Quality bar: Every command must work. Every link must resolve. No placeholders allowed.

Install readme-maker and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# README Maker Command Generates a professional README.md by combining codebase exploration with documentation best practices. ## Usage ```bash /readme-maker # Full analysis → README.md /readme-maker --output docs/ # Output to specific directory /readme-maker --style minimal # Minimal README (Quick Start focus) /readme-maker --style comprehensive # Full documentation (default) /readme-maker --dry-run # Preview without saving ``` --- ## What It Does 1. **Explores** codebase using codebase-explorer patterns 2. **Analyzes** project structure, tech stack, and patterns 3. **Generates** README.md following code-documenter standards 4. **Validates** all examples and links before saving --- ## Execution Flow ```text ┌─────────────────────────────────────────────────────────────┐ │ README-MAKER WORKFLOW │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Phase 1: EXPLORE (codebase-explorer patterns) │ │ ├─ Scan root structure (ls, package files, configs) │ │ ├─ Map source code (Glob patterns by language) │ │ ├─ Identify tech stack and frameworks │ │ ├─ Count files, tests, documentation │ │ └─ Calculate health score │ │ │ │ Phase 2: EXTRACT (project metadata) │ │ ├─ Read package.json / pyproject.toml / Cargo.toml │ │ ├─ Parse existing README (if present) │ │ ├─ Detect entry points (main, index, handler) │ │ ├─ Find installation/setup commands │ │ └─ Identify environment variables │ │ │ │ Phase 3: GENERATE (code-documenter patterns) │ │ ├─ Create compelling project description │ │ ├─ Build Quick Start with tested commands │ │ ├─ Document features with examples │ │ ├─ Add architecture overview (if complex) │ │ └─ Include contributing guidelines │ │ │ │ Phase 4: VALIDATE (quality checks) │ │ ├─ Test all installation commands │ │ ├─ Verify code examples work │ │ ├─ Check all links resolve │ │ └─ Ensure no placeholder text remains │ │ │ │ Phase 5: OUTPUT │ │ ├─ Write README.md to project root │ │ └─ Report summary of what was generated │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Analysis Steps ### Step 1: Scan Project Structure ```text # Root structure ls -la (root) Read README.md (if exists - preserve manual content) # Package files (detect language/framework) Glob("**/package.json") # Node.js Glob("**/pyproject.toml") # Python Glob("**/Cargo.toml") # Rust Glob("**/go.mod") # Go Glob("**/pom.xml") # Java/Maven Glob("**/build.gradle") # Java/Gradle # Source code Glob("src/**/*") # Main source Glob("lib/**/*") # Library code Glob("tests/**/*") # Test files Glob("docs/**/*") # Documentation ``` ### Step 2: Extract Project Metadata ```text # From package files - Project name - Version - Description - Author/maintainers - License - Dependencies (key ones) - Scripts/commands # From codebase - Primary language - Framework(s) - Entry points - Environment variables (from .env.example, config) - API endpoints (if applicable) ``` ### Step 3: Generate README Sections Use this template structure: ```markdown # {Project Name} > {Compelling one-line description from package or inferred} {Badges: build status, version, license} ## Overview {2-3 paragraphs explaining:} - What the project does - Why it exists (problem it solves) - Who it's for ## Features {Bullet list with brief descriptions} - Feature 1: Description - Feature 2: Description ## Quick Start {60-second setup - MUST be tested commands} ### Prerequisites - {requirement 1} - {requirement 2} ### Installation ```bash {installation commands} ``` ### Basic Usage ```bash {usage example} ``` ## Documentation {Table linking to detailed docs if they exist} | Topic | Link | | ----- | ---- | | API Reference | [docs/api.md](docs/api.md) | | Configuration | [docs/config.md](docs/config.md) | ## Architecture {Only include if project is complex enough} ```text {Simple ASCII diagram} ``` ## Configuration {Environment variables and config options} | Variable | Description | Default | | -------- | ----------- | ------- | | `VAR_NAME` | What it does | `default` | ## Development ### Setup ```bash {dev setup commands} ``` ### Running Tests ```bash {test commands} ``` ## Contributing {Link to CONTRIBUTING.md or brief guidelines} ## License {License name} - see [LICENSE](LICENSE) ``` --- ## Output Styles ### Minimal (`--style minimal`) Sections included: - Project name + description - Quick Start (installation + basic usage) - License Best for: Small utilities, scripts, simple libraries ### Comprehensive (`--style comprehensive`) - Default Sections included: - All sections in template - Architecture diagram - Full configuration reference - Development guide - API documentation links Best for: Production projects, open source, team codebases --- ## Quality Checklist Before saving README.md, verify: ```text CONTENT [ ] Project description is clear and compelling [ ] Quick Start works (commands tested) [ ] Features accurately reflect codebase [ ] No placeholder text like "TODO" or "{}" FORMAT [ ] Badges are valid (if included) [ ] Code blocks have language hints [ ] Tables properly formatted [ ] Links point to existing files ACCURACY [ ] Version matches package file [ ] Dependencies are current [ ] Installation actually works [ ] Examples produce expected output ``` --- ## Example Output ```text README GENERATION ━━━━━━━━━━━━━━━━━ Exploring codebase... ✓ Detected: Python project (pyproject.toml) ✓ Found: 17 source files, 4 test files ✓ Framework: Click CLI, Pydantic ✓ Entry point: src/task_runner/cli.py Extracting metadata... ✓ Name: task-runner ✓ Version: 0.1.0 ✓ License: MIT ✓ Dependencies: click, pydantic, faker Generating README... ✓ Overview: from pyproject.toml description ✓ Quick Start: from scripts + entry point ✓ Features: from module analysis ✓ Configuration: from .env.example Validating... ✓ Installation commands work ✓ Basic usage example runs ✓ All links valid ━━━━━━━━━━━━━━━━━ Saved: README.md (comprehensive style) Preview: # task-runner > Flexible task execution framework with plugin support ## Quick Start pip install -e . task-runner run --workers 4 --output results/ ``` --- ## Flags | Flag | Description | | ---- | ----------- | | `--output {dir}` | Output directory (default: project root) | | `--style {type}` | `minimal` or `comprehensive` (default) | | `--dry-run` | Preview without saving | | `--preserve-manual` | Keep manually-written sections (default: true) | | `--force` | Overwrite without preserving manual content | --- ## Best Practices ### When to Use - New projects without README - Projects with outdated README - After major refactoring - Before open-sourcing internal code ### What to Review After 1. **Overview** - Add business context the tool can't infer 2. **Features** - Prioritize and add details 3. **Architecture** - Add domain-specific explanations 4. **Contributing** - Add team-specific guidelines ### Integration with Other Commands ```bash # Full documentation workflow /readme-maker # Generate README /sync-context # Update CLAUDE.md /memory "Generated docs" # Save what was done ``` --- ## Agent Integration This command leverages: | Agent | Purpose | | ----- | ------- | | **codebase-explorer** | Comprehensive codebase analysis | | **code-documenter** | Documentation generation patterns | The command combines: - Explorer's systematic analysis workflow - Documenter's quality checklist and templates - Both agents' validation requirements --- ## Remember > **"A README is often the first impression of your project"** **Goal:** Generate README that answers: 1. What is this? 2. Why should I care? 3. How do I use it? **Quality bar:** Every command must work. Every link must resolve. No placeholders allowed.

{ "prompt": "# README Maker Command\n\nGenerates a professional README.md by combining codebase exploration with documentation best practices.\n\n## Usage\n\n```bash\n/readme-maker # Full analysis → README.md\n/readme-maker --output docs/ # Output to specific directory\n/readme-maker --style minimal # Minimal README (Quick Start focus)\n/readme-maker --style comprehensive # Full documentation (default)\n/readme-maker --dry-run # Preview without saving\n```\n\n---\n\n## What It Does\n\n1. **Explores** codebase using codebase-explorer patterns\n2. **Analyzes** project structure, tech stack, and patterns\n3. **Generates** README.md following code-documenter standards\n4. **Validates** all examples and links before saving\n\n---\n\n## Execution Flow\n\n```text\n┌─────────────────────────────────────────────────────────────┐\n│ README-MAKER WORKFLOW │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ Phase 1: EXPLORE (codebase-explorer patterns) │\n│ ├─ Scan root structure (ls, package files, configs) │\n│ ├─ Map source code (Glob patterns by language) │\n│ ├─ Identify tech stack and frameworks │\n│ ├─ Count files, tests, documentation │\n│ └─ Calculate health score │\n│ │\n│ Phase 2: EXTRACT (project metadata) │\n│ ├─ Read package.json / pyproject.toml / Cargo.toml │\n│ ├─ Parse existing README (if present) │\n│ ├─ Detect entry points (main, index, handler) │\n│ ├─ Find installation/setup commands │\n│ └─ Identify environment variables │\n│ │\n│ Phase 3: GENERATE (code-documenter patterns) │\n│ ├─ Create compelling project description │\n│ ├─ Build Quick Start with tested commands │\n│ ├─ Document features with examples │\n│ ├─ Add architecture overview (if complex) │\n│ └─ Include contributing guidelines │\n│ │\n│ Phase 4: VALIDATE (quality checks) │\n│ ├─ Test all installation commands │\n│ ├─ Verify code examples work │\n│ ├─ Check all links resolve │\n│ └─ Ensure no placeholder text remains │\n│ │\n│ Phase 5: OUTPUT │\n│ ├─ Write README.md to project root │\n│ └─ Report summary of what was generated │\n│ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Analysis Steps\n\n### Step 1: Scan Project Structure\n\n```text\n# Root structure\nls -la (root)\nRead README.md (if exists - preserve manual content)\n\n# Package files (detect language/framework)\nGlob(\"**/package.json\") # Node.js\nGlob(\"**/pyproject.toml\") # Python\nGlob(\"**/Cargo.toml\") # Rust\nGlob(\"**/go.mod\") # Go\nGlob(\"**/pom.xml\") # Java/Maven\nGlob(\"**/build.gradle\") # Java/Gradle\n\n# Source code\nGlob(\"src/**/*\") # Main source\nGlob(\"lib/**/*\") # Library code\nGlob(\"tests/**/*\") # Test files\nGlob(\"docs/**/*\") # Documentation\n```\n\n### Step 2: Extract Project Metadata\n\n```text\n# From package files\n- Project name\n- Version\n- Description\n- Author/maintainers\n- License\n- Dependencies (key ones)\n- Scripts/commands\n\n# From codebase\n- Primary language\n- Framework(s)\n- Entry points\n- Environment variables (from .env.example, config)\n- API endpoints (if applicable)\n```\n\n### Step 3: Generate README Sections\n\nUse this template structure:\n\n```markdown\n# {Project Name}\n\n> {Compelling one-line description from package or inferred}\n\n{Badges: build status, version, license}\n\n## Overview\n\n{2-3 paragraphs explaining:}\n- What the project does\n- Why it exists (problem it solves)\n- Who it's for\n\n## Features\n\n{Bullet list with brief descriptions}\n- Feature 1: Description\n- Feature 2: Description\n\n## Quick Start\n\n{60-second setup - MUST be tested commands}\n\n### Prerequisites\n\n- {requirement 1}\n- {requirement 2}\n\n### Installation\n\n```bash\n{installation commands}\n```\n\n### Basic Usage\n\n```bash\n{usage example}\n```\n\n## Documentation\n\n{Table linking to detailed docs if they exist}\n\n| Topic | Link |\n| ----- | ---- |\n| API Reference | [docs/api.md](docs/api.md) |\n| Configuration | [docs/config.md](docs/config.md) |\n\n## Architecture\n\n{Only include if project is complex enough}\n\n```text\n{Simple ASCII diagram}\n```\n\n## Configuration\n\n{Environment variables and config options}\n\n| Variable | Description | Default |\n| -------- | ----------- | ------- |\n| `VAR_NAME` | What it does | `default` |\n\n## Development\n\n### Setup\n\n```bash\n{dev setup commands}\n```\n\n### Running Tests\n\n```bash\n{test commands}\n```\n\n## Contributing\n\n{Link to CONTRIBUTING.md or brief guidelines}\n\n## License\n\n{License name} - see [LICENSE](LICENSE)\n```\n\n---\n\n## Output Styles\n\n### Minimal (`--style minimal`)\n\nSections included:\n- Project name + description\n- Quick Start (installation + basic usage)\n- License\n\nBest for: Small utilities, scripts, simple libraries\n\n### Comprehensive (`--style comprehensive`) - Default\n\nSections included:\n- All sections in template\n- Architecture diagram\n- Full configuration reference\n- Development guide\n- API documentation links\n\nBest for: Production projects, open source, team codebases\n\n---\n\n## Quality Checklist\n\nBefore saving README.md, verify:\n\n```text\nCONTENT\n[ ] Project description is clear and compelling\n[ ] Quick Start works (commands tested)\n[ ] Features accurately reflect codebase\n[ ] No placeholder text like \"TODO\" or \"{}\"\n\nFORMAT\n[ ] Badges are valid (if included)\n[ ] Code blocks have language hints\n[ ] Tables properly formatted\n[ ] Links point to existing files\n\nACCURACY\n[ ] Version matches package file\n[ ] Dependencies are current\n[ ] Installation actually works\n[ ] Examples produce expected output\n```\n\n---\n\n## Example Output\n\n```text\nREADME GENERATION\n━━━━━━━━━━━━━━━━━\n\nExploring codebase...\n✓ Detected: Python project (pyproject.toml)\n✓ Found: 17 source files, 4 test files\n✓ Framework: Click CLI, Pydantic\n✓ Entry point: src/task_runner/cli.py\n\nExtracting metadata...\n✓ Name: task-runner\n✓ Version: 0.1.0\n✓ License: MIT\n✓ Dependencies: click, pydantic, faker\n\nGenerating README...\n✓ Overview: from pyproject.toml description\n✓ Quick Start: from scripts + entry point\n✓ Features: from module analysis\n✓ Configuration: from .env.example\n\nValidating...\n✓ Installation commands work\n✓ Basic usage example runs\n✓ All links valid\n\n━━━━━━━━━━━━━━━━━\nSaved: README.md (comprehensive style)\n\nPreview:\n# task-runner\n\n> Flexible task execution framework with plugin support\n\n## Quick Start\n\npip install -e .\ntask-runner run --workers 4 --output results/\n```\n\n---\n\n## Flags\n\n| Flag | Description |\n| ---- | ----------- |\n| `--output {dir}` | Output directory (default: project root) |\n| `--style {type}` | `minimal` or `comprehensive` (default) |\n| `--dry-run` | Preview without saving |\n| `--preserve-manual` | Keep manually-written sections (default: true) |\n| `--force` | Overwrite without preserving manual content |\n\n---\n\n## Best Practices\n\n### When to Use\n\n- New projects without README\n- Projects with outdated README\n- After major refactoring\n- Before open-sourcing internal code\n\n### What to Review After\n\n1. **Overview** - Add business context the tool can't infer\n2. **Features** - Prioritize and add details\n3. **Architecture** - Add domain-specific explanations\n4. **Contributing** - Add team-specific guidelines\n\n### Integration with Other Commands\n\n```bash\n# Full documentation workflow\n/readme-maker # Generate README\n/sync-context # Update CLAUDE.md\n/memory \"Generated docs\" # Save what was done\n```\n\n---\n\n## Agent Integration\n\nThis command leverages:\n\n| Agent | Purpose |\n| ----- | ------- |\n| **codebase-explorer** | Comprehensive codebase analysis |\n| **code-documenter** | Documentation generation patterns |\n\nThe command combines:\n- Explorer's systematic analysis workflow\n- Documenter's quality checklist and templates\n- Both agents' validation requirements\n\n---\n\n## Remember\n\n> **\"A README is often the first impression of your project\"**\n\n**Goal:** Generate README that answers:\n1. What is this?\n2. Why should I care?\n3. How do I use it?\n\n**Quality bar:** Every command must work. Every link must resolve. No placeholders allowed.", "variables": [], "notes": "Generate comprehensive, production-ready README.md by analyzing codebase with explorer + documenter agents", "metadata": { "source": { "provider": "github-codex-prompts", "repository": "https://github.com/asabocinski/bravo-edd", "path": ".codex/prompts/readme-maker.md", "ref": "ae4c539580470e782ac67d2dc4a4eabe9fc68336", "url": "https://github.com/asabocinski/bravo-edd/blob/ae4c539580470e782ac67d2dc4a4eabe9fc68336/.codex/prompts/readme-maker.md", "key": "asabocinski/bravo-edd/.codex/prompts/readme-maker.md" } } }

readme-maker

About