RepoReady

One-command launch readiness scorecard for open-source repositories.

RepoReady scans a repo before you publish it and tells you whether it has the basics people trust: README quality, install path, license, tests, CI, examples, contribution docs, issue templates, PR template, package metadata, and obvious publishing risks.

Demo screenshot/GIF placeholder: run repoready . --format markdown --output repoready-report.md, then capture the terminal score and generated Markdown report.

Features

• Local-first CLI with zero runtime dependencies
• Text, Markdown, and JSON output
• CI-friendly thresholds with non-zero exit codes
• README section and installability checks
• License, manifest, tests, CI, examples, changelog, contributing guide, issue template, and PR template checks
• Basic secret-pattern and large-file warnings before public release
• Designed for AI-agent-generated repos that need a final human-quality launch pass

Why This Exists

AI coding agents make it easy to create a repository in minutes. Publishing something people trust is still harder.

Many promising repos lose stars because the first visitor cannot answer simple questions:

• What does this do?
• Can I install it in one command?
• Is there a working example?
• Are there tests?
• Is it safe to clone?
• Can I contribute?

RepoReady turns those launch basics into a fast scorecard you can run locally or in CI.

Installation

From a local checkout:

python -m pip install -e .

After the first PyPI release:

pip install repoready

Quick Start

repoready .

Generate a Markdown report:

repoready . --format markdown --output repoready-report.md

Use RepoReady as a CI gate:

repoready . --min-score 80 --fail-on-findings

Usage Examples

Scan another project:

repoready ~/code/my-open-source-project

Emit machine-readable JSON:

repoready . --format json

Fail when the repo is below launch quality:

repoready . --min-score 85

CLI Reference

usage: repoready [-h] [--format {text,markdown,json}] [--output OUTPUT]
                 [--min-score MIN_SCORE] [--fail-on-findings]
                 [path]

Arguments:

• path: Repository path to scan. Defaults to the current directory.
• --format: Output format: text, markdown, or json.
• --output, -o: Write the report to a file.
• --min-score: Exit with status 2 when the percentage score is below this threshold.
• --fail-on-findings: Exit with status 2 when any failing checks are present.

Configuration

RepoReady v0.1.0 intentionally has no configuration file. The default checks represent a practical launch baseline for most open-source projects.

Planned configuration support:

[tool.repoready]
min_score = 85
ignore_checks = ["large_files"]

Real-World Use Cases

• Run before publishing a new GitHub repository.
• Add as a CI gate for AI-agent-generated starter projects.
• Generate a Markdown readiness report for maintainers.
• Audit old repos before relaunching them on Hacker News, Reddit, or Product Hunt.
• Teach junior developers what credible open-source packaging looks like.

API Reference

from repoready import scan_repository

report = scan_repository(".")
print(report.percentage, report.grade)
for finding in report.findings:
    print(finding.title, finding.severity, finding.message)

Roadmap

• Language-specific check packs for Python, Node, Go, and Rust
• GitHub Actions annotation output
• repoready fix --plan for safe, reviewable remediation suggestions
• README quality examples and benchmark mode
• SARIF output for security/scanning platforms
• Optional LLM-assisted README critique without making API access mandatory

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, open a focused issue, and include before/after output for scoring changes.

License

MIT. See LICENSE.

Star History

Star history chart placeholder:

Add star-history.com chart after the repository is public.

FAQ

Is RepoReady a security scanner?

No. It only catches obvious secret-looking strings and launch-readiness issues. Use dedicated security tools before serious production releases.

Does it call an LLM?

No. RepoReady v0.1.0 is deterministic and local-only.

Is this only for Python repositories?

No. The first version checks general open-source launch hygiene. Language-specific packs are on the roadmap.

Why not just use a checklist?

Checklists are easy to ignore. RepoReady produces a score, CI exit code, and shareable report.