{{ summaryTitle }}
{{ summaryPrimary }}
{{ summaryLine }}
{{ badge.label }}
Use the closest project type; it changes section names and audit expectations.
Use the exact name readers will search for or install.
Write one clear paragraph readers can understand before setup.
Optional but recommended for copy-ready install and contribution links.
List the capabilities that tell readers whether the project fits their need.
One prerequisite per line; leave blank only when there are no special requirements.
Include clone, install, migration, or setup steps needed before first run.
Make this the fastest successful path after installation.
Use an SPDX-style label when the repository is open source.
Keep it short, for example Blue Oak Model License 1.0.0.
Active omits the status note; other states add a clear status callout.
Open-source projects should point to contribution and code-of-conduct files when available.
Link to full guides, API docs, or team docs if they exist.
Leave blank if tests are not ready to document.
One short note per line; generated as bullets.
Generated as a Markdown table when at least one variable is present.
Add one concise line per endpoint, option, artifact, or operating note.
Optional, but the audit will flag missing help routes for public projects.
Use a relative path such as CONTRIBUTING.md or docs/CONTRIBUTING.md.
Leave blank when the project is not accepting contributions.
Optional for small projects, recommended for published software.
Leave blank unless users need formal citation guidance.
Leave off for short READMEs; turn on for longer generated drafts.
{{ include_toc ? 'On' : 'Off' }}
Optional badges stay near the top and never replace setup instructions.
{{ include_badges ? 'On' : 'Off' }} 
{{ markdownOutput }}
Area Status Signal Next copy Copy
{{ row.area }} {{ row.status }} {{ row.signal }} {{ row.nextCopy }}
Repository item Status Why it matters Next action Copy
{{ row.item }} {{ row.status }} {{ row.reason }} {{ row.nextAction }}
Tags: Devtools, Productivity
Feature Flag Cleanup Checker Review feature flag inventories in your browser for stale rollouts, code references, owner gaps, dependencies, and archive-ready cleanup work.
Dependency License Flags Checker Check dependency license evidence against allowed, review, and denied policies with SPDX expression triage, scope filters, and action queues.
.gitignore Pattern Coverage Checker Check whether .gitignore rules cover generated and sensitive repository paths, with gate metrics for negations, tracked files, gaps, and review actions.
SemVer Bump Required Checker Check release notes and commit subjects for the required SemVer bump, compare a planned version, and review breaking, feature, fix, and neutral signals.
Customize
Advanced
:

A repository can have solid code and still lose readers when its front page does not answer the first practical questions. The README is where a new visitor looks for the project name, purpose, setup path, first successful run, support route, and reuse terms. It also becomes the document that future maintainers reopen when they have forgotten why a service exists or how a small utility is supposed to be started.

Good README writing is not the same as listing every feature. The opening has to help someone decide whether the project fits their need, while the setup and usage sections have to remove guesswork. Governance details matter too: a license tells readers what they may do, contribution rules set expectations, and a security contact keeps sensitive reports out of public issue threads.

Reader README question Risk when it is missing
New user What does this project do, and what is the smallest useful example? They leave before trying the project or run the wrong command first.
Contributor How should changes, tests, and community rules work? Pull requests arrive without the checks or behavior expectations maintainers need.
Operator What requirements, configuration, and support route keep the project usable? Runtime assumptions, environment variables, and ownership are rediscovered during an incident.
Reviewer Can the license, status, security policy, and citation be trusted? Legal, security, or research-credit decisions are made from incomplete wording.

Project type changes the emphasis. A command-line utility needs options and copyable invocations. A web service needs endpoints or operations notes. A data project needs reproducibility and citation details. An internal service may need less public contribution wording and more ownership, status, and support guidance. The common mistake is treating a README as a brochure when readers usually need a reliable first action.

Project facts flowing into a README file, then into first-run and trust-signal checks

Generated Markdown can create a strong starting point, but it cannot prove the repository behind the words. Commands still need to run in a clean checkout, policy links still need to exist, and license text still needs to match the project's real reuse terms.

How to Use This Tool:

Build the README around a first successful run, then use the audit and checklist to catch missing repository work before copying the Markdown.

  1. Choose README profile first. The profile selects the project-specific section name, such as API Reference, Options, Data and Reproducibility, or Operations, so pick the closest reader workflow rather than the broadest label.
  2. Enter Project name and Short description. Keep the description long enough to explain what the project does, who it helps, and why the first example matters; a very short paragraph lowers the Opening description audit row.
  3. Add Repository URL, Key features, Requirements, Install or setup commands, and Usage example. The README Draft should show a title, practical sections, fenced command blocks, and a first-run example as those fields fill in.
  4. Set License and use Custom license label only when none of the built-in choices match the repository. The generated wording should be checked against the real LICENSE file before publication.
  5. Open Advanced for status wording, contribution posture, documentation links, test commands, configuration notes, environment variables, support contact, community file paths, security policy, citation DOI, table of contents, and quality badges.
  6. Read README notes, Section Audit, and Repository Checklist. If the summary says README draft needs review, fix the rows marked Missing or Check before treating the draft as publishable.
  7. Use the final Markdown only after running the setup, usage, and test commands and opening important links such as LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

Interpreting Results:

The main result is a copy-ready Markdown draft. Read the draft for tone and flow, then use the review surfaces as a checklist for missing facts. A high readiness percentage means the entered values satisfy the built-in content checks; it does not prove that commands run, badges resolve, or policy files exist.

  • README draft ready means no current warning is shown, but the generated text still needs a clean checkout test.
  • README draft needs review means at least one audit area is short, missing, inconsistent, or incomplete for the selected contribution posture.
  • Section Audit explains the content area, status, evidence, and Next copy cue for each audit row.
  • Repository Checklist names companion files and follow-up repository tasks that the README may reference but cannot create.
  • JSON is useful as a saved review record when another workflow needs the settings, readiness, warnings, audit rows, checklist rows, and generated Markdown.

Technical Details:

README generation is a structured Markdown transformation. Project facts become the heading, opening paragraph, optional badges, project-status note, and a sequence of sections. Multiline fields become bullets, command fields become fenced shell blocks, environment variable entries become a table, and profile notes move into the section that matches the selected project type.

The readiness score is a content-coverage estimate. It checks whether expected fields exist and whether a few values meet simple quality cues, such as a description of at least 60 characters, at least three feature bullets, setup and usage examples, a help route, and contribution files when public collaboration is enabled. It does not inspect repository contents, validate legal text, fetch documentation, or execute commands.

Transformation Core:

Entered content Generated Markdown Review meaning
Project name and short description Main heading and opening paragraph. The opening should explain purpose, reader, and practical value before setup begins.
README profile Profile-specific section title for APIs, options, operations, or reproducibility notes. The section should match how readers will actually use or operate the project.
Features, requirements, setup, usage, and tests Bullets and fenced command blocks in practical sections. Missing setup or usage content is treated as a major readiness gap.
Configuration notes and environment variables Configuration bullets and a name-description table. Each variable should explain purpose, default, or required value before publishing.
Contribution posture and community paths Contribution guidance for public, internal, or closed collaboration models. Public collaboration expects contribution and code-of-conduct links when available.
License, security, docs, citation, table of contents, and badges Optional sections or top-of-file Markdown when the needed values are present. Referenced files, DOI values, and badge targets still need manual verification.

Rule Core:

Audit area Possible points Full-credit signal
Project name 10 A non-empty project name is entered.
Opening description 16 The first paragraph reaches at least 60 characters.
Feature bullets 10 At least three feature lines are present.
Requirements 7 Prerequisites are listed, or the optional gap is accepted as lower priority.
Installation and usage 32 Setup commands and a usage example are both present.
Profile notes 7 The profile-specific section has notes or receives partial optional credit.
Repository URL, license, and help route 21 A readable repository URL, specific license wording, and support route are present.
Community, security, and docs cues 15 Contribution files, security policy, and longer documentation are linked when they apply.

Formula Core:

The readiness percentage is the rounded share of earned audit points:

Readiness = round ( earned audit points possible audit points × 100 )

For example, 104 earned points out of 118 possible points displays as 88% ready. Partial credit is possible for optional or incomplete rows, so the percentage should be read as a drafting signal rather than a pass/fail verdict.

Accuracy and Privacy Notes:

The generated README is based only on the values entered in the form. The tool does not inspect the actual repository, run commands, check hosted files, verify legal terms, or confirm that a support channel or security policy is valid.

  • Run install, usage, and test commands in a clean checkout before publishing the README.
  • Open referenced files such as LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, and CITATION.cff when they appear in the draft or checklist.
  • Review custom or proprietary license wording with the responsible owner when reuse terms matter.
  • Entered values can appear in the browser address bar for sharing. Do not enter secrets, private tokens, or confidential internal URLs if browser history or shared links could expose them.

Advanced Tips:

  • Use README profile to match reader intent, not repository ownership. A private API can still need the Web app/API profile if endpoints are the main thing readers must understand.
  • Enter environment variables as NAME=description or NAME: description. Lines without a description are still included, but they need manual cleanup before publishing.
  • Turn on Table of contents only when the generated README has enough sections to benefit from it; short READMEs usually read better without one.
  • Use Quality badges with a valid GitHub repository URL. Without a compatible URL, the warning block asks you to add one or leave badges off.
  • Keep Support contact concrete. A generic phrase is less useful than an issue URL, email alias, owning team, or documentation route that readers can actually use.

Worked Examples:

Public Web Service

A small service named signal-exporter with three feature lines, Node.js requirements, setup commands, a health-check usage example, support issue URL, MIT license, contribution path, code-of-conduct path, and security policy should produce setup, configuration, usage, API, testing, support, contribution, security, and license sections. Section Audit should mark the core first-run and trust areas as Ready.

Research Data Project

Choosing the data or research profile, adding reproducibility notes, and entering a citation DOI creates Data and Reproducibility and Citation sections. The checklist can recommend CITATION.cff, which reminds the maintainer to add formal citation metadata outside the README.

Badge Warning

Turning on Quality badges without a readable GitHub repository URL produces a README note. Add a compatible repository URL if the badge should point to CI, or turn badges off when the project does not use that hosting pattern.

FAQ:

Does this check the real repository?

No. It creates the README Draft, Section Audit, Repository Checklist, and JSON from entered values only. Verify commands, links, badges, and support files separately.

Why is the readiness score below 100%?

One or more audit rows are marked Check, Missing, or partially credited as optional. Open Section Audit and use the Next copy cue to decide what needs more detail.

Can the license wording be used as legal advice?

No. The selected license only creates README wording. It should match the repository's full license text, and custom or proprietary terms should be reviewed by the responsible owner.

Why did badge Markdown not appear?

Badge Markdown appears when Quality badges is on and Repository URL can be read as a GitHub repository. Add a compatible URL or leave badges off.

What should be checked first before publishing?

Check the title, opening paragraph, setup commands, usage example, support route, license wording, and any README notes. Those areas decide whether a new reader can trust the draft.

Glossary:

README profile
The project type setting that chooses the profile-specific README section and review emphasis.
Contribution posture
The setting that decides whether the README invites public contributions, routes internal changes, or avoids contribution wording.
Section Audit
A review table that scores README content areas as Ready, Check, Missing, or Optional.
Repository Checklist
A follow-up list of repository files and support resources that may need to exist beside the README.
SPDX-style label
A concise license identifier style used to name common software licenses consistently.
Citation DOI
A digital object identifier used when research software, data, or releases need formal citation guidance.
Quality badges
Small Markdown badges that can point to project signals such as CI or license status when the supporting links are valid.

References: