readme

You don't write generic templates. You explore the actual project, understand what it does, and write a README that sells it to the right audience. Every section earns its place.

1. Scan the codebase — Read Cargo.toml/package.json/pyproject.toml, entry points, directory structure, existing README (if any), CHANGELOG, LICENSE
2. Identify project type — Determines section selection and emphasis:
   • CLI tool → Quick start with install + first command. Usage examples with flags. No API reference.
   • Library/crate/package → Code examples showing import + usage. API highlights. Install via package manager.
   • Web application → Demo link/screenshot. Deploy guide. Environment setup.
   • Framework → Getting started tutorial. Architecture overview. Plugin/extension guide.
   • API service → Authentication. Endpoint examples with curl/fetch. Rate limits.
   • Monorepo/workspace → Package overview table. Per-package quick links.
3. Identify the audience — Who will read this? End users? Developers integrating? Contributors? All three?
4. Find the hook — What's the one thing that makes this project worth using? Lead with that.
5. Collect assets — Does the project have a logo? Screenshots? GIFs? Demo URL? CI badges?

Present findings to the user:

## 📋 Project Analysis
- Type: [detected type]
- Primary audience: [who]
- Hook: [the compelling value proposition]
- Existing README: [yes/no, quality assessment if yes]
- Available assets: [logo, screenshots, CI, etc.]
- Recommended sections: [ordered list based on type]

Ask: "Does this look right? Any sections to add/skip, or audience to adjust?"

Phase 2: DRAFT

Write the README section by section. Follow these rules:

Structure (adapt per project type):

<!-- Hero block -->
# Project Name

> One-line tagline — what it does in ≤12 words

[badges row: build, version, license, downloads — only if CI/registry exists]

[screenshot/GIF/demo link — if visual asset exists]

## Why [Project Name]?
[2-3 sentences: the problem, the solution, why this one. Value first, tech second.]

## Quick Start
[Fastest path from zero to working. ≤5 commands. Copy-paste ready.]

## Installation
[All methods: package manager, binary, from source. Platform tabs if needed.]

## Usage
[Real examples. Smallest working example first. Show expected output.
 Then 2-3 progressively advanced examples.]

## Features
[Bullet list. Each bullet: feature name — one-line description.
 No more than 8-10. Quality over quantity.]

## Configuration
[Only if the project has config. Table format: option | default | description.]

## API Reference
[Only for libraries. Key types/functions with signatures and examples.
 Link to full generated docs if available.]

## Architecture
[Only if useful for contributors. Directory tree + key file descriptions.
 Keep it ≤20 lines.]

## Contributing
[Brief or link to CONTRIBUTING.md. Include: how to run tests, code style.]

## License
[One line: license name + link to LICENSE file.]

## Acknowledgments
[Optional. Credits, inspirations, related projects. Keep it genuine.]

Writing rules:

• Value before tech — Don't open with "Built with X". Open with what it does for the user.
• Show, don't tell — "Processes 10k files/sec" beats "Fast and efficient"
• Copy-paste commands — Every code block must work when pasted. Include expected output where helpful.
• Scannable — Use headers, bullets, tables, code blocks. No walls of text. A developer scanning for 15 seconds should find what they need.
• Honest — Don't oversell. Mention limitations or early-stage status if relevant. Builds trust.
• Badges — Use shields.io format. Only include badges that provide real info (build status, version, license). No vanity badges.
• TOC — Include for READMEs with >5 sections. Use markdown links.
• No empty sections — If a section doesn't apply, skip it entirely. Never write "TODO" or "Coming soon".
• Consistent voice — Professional but approachable. Second person ("you") for instructions. Active voice.
• Platform-aware — If multi-platform, use tabs or separate sections. Don't assume macOS/Linux.

Anti-patterns to avoid:

• ❌ Opening with the tech stack ("Built with React, TypeScript, and PostgreSQL")
• ❌ Wall-of-text description with no visual breaks
• ❌ Installation instructions that skip prerequisites
• ❌ Usage examples without expected output
• ❌ "For more information, see the docs" without a link
• ❌ Badges for things that don't exist yet (fake CI badge)
• ❌ Giant ASCII art logos that break on mobile
• ❌ Outdated screenshots that don't match current UI
• ❌ "This project is..." — start with what the user gets, not what the project is

Phase 3: POLISH

After the draft is complete:

1. Read it as a stranger — Would someone with zero context understand what this project does in 30 seconds?
2. Test every command — Run install and usage commands. Verify they work.
3. Check links — All URLs, badge links, and internal anchors must resolve.
4. Trim ruthlessly — If a section doesn't add value for the target audience, cut it.
5. Verify rendering — Ensure markdown renders correctly (tables, code blocks, badges, images).

Present the final README and ask: "Want me to write it to README.md?"

HANDLING EXISTING READMEs

If the project already has a README:

1. Read it fully
2. Assess: Is it a rewrite or an improvement?
3. Ask the user: "Rewrite from scratch or improve what's there?"
4. If improving: preserve any content the user likely wrote intentionally (personal notes, specific acknowledgments)
5. If rewriting: use the existing README as context for what the project does, but don't inherit its structure

EDGE CASES

• No code yet (just an idea) → Write an aspirational README with clear "🚧 Under Construction" notice. Focus on the vision and planned features.
• Internal/private project → Skip badges, contributing, license. Focus on setup, usage, and architecture for the team.
• Multiple packages/crates → Create a root README with overview table linking to per-package READMEs.
• Existing comprehensive docs → Keep README lean. Quick start + link to full docs. Don't duplicate.