Rubric documentation
Assessment standards
The complete scoring rubric used by the assessment agent — what each standard measures, why it matters, and what evidence is required to earn points.
| Pillar | Points | Primary signal |
|---|---|---|
| Documentation | 25 | README, CHANGELOG, roadmap, API docs |
| Community health | 25 | CONTRIBUTING.md, issue responsiveness, CoC, onboarding |
| Code health | 25 | CI/CD, versioning, dependencies, branch protection |
| Security | 15 | License, disclosure process, supply chain |
| Sustainability | 10 | Maintainer health, activity signals, bus factor |
Pillar 1 — Documentation
25 pts1.1 · README quality10 points
The README is often the only thing a visitor reads before deciding whether to use or contribute to a project.
What is evaluated
- README exists at the root 2 pts
- Clear description of what the project does 2 pts
- Explains the problem it solves 2 pts
- Installation/quick-start instructions 2 pts
- Screenshots, demo, or usage samples 1 pt
- Status badges 1 pt
1.2 · CHANGELOG and release notes5 points
Silent breaking changes are one of the most damaging things a maintainer can inflict on users.
- CHANGELOG.md file exists 2 pts
- Breaking changes called out explicitly 1 pt
- GitHub releases have meaningful notes 1 pt
- Major bumps include migration guides 1 pt
1.3 · Roadmap and vision5 points
- ROADMAP.md or GitHub Project board exists 2 pts
- Scope explicitly defined 2 pts
- Near-term milestones labeled 1 pt
1.4 · API documentation5 points
- /docs folder or docs site exists 2 pts
- Public functions/endpoints documented 2 pts
- Config options documented 1 pt
Pillar 2 — Community Health
25 pts2.1 · Contributor onboarding10 points
The number one reason contributors give up is not knowing how to start.
- CONTRIBUTING.md with dev setup 3 pts
- "good first issue" labels used 2 pts
- Pull request templates present 2 pts
- Issue templates for bugs/features 2 pts
- Cross-platform dev setup 1 pt
2.2 · Issue and PR responsiveness8 points
- Stale issue ratio suggests responsiveness 3 pts
- Open PRs addressed within reasonable time 3 pts
- Maintainers acknowledge contributions 2 pts
2.3 · Code of Conduct4 points
- CODE_OF_CONDUCT.md exists 2 pts
- Project ownership is clear 1 pt
- Community communication channel exists 1 pt
2.4 · Inclusive experience3 points
- Cross-platform dev setup 1 pt
- Respectful tone toward newcomers 1 pt
- Async participation possible 1 pt
Pillar 3 — Code Health
25 pts3.1 · CI/CD and testing10 points
- CI system configured 3 pts
- Tests exist and pass on main 3 pts
- Linting enforced automatically 2 pts
- PRs require passing CI 2 pts
3.2 · Versioning8 points
- Semantic versioning followed 3 pts
- Releases tagged and published 2 pts
- No silent breaking changes 2 pts
- Pre-releases clearly marked 1 pt
3.3 · Dependency management4 points
- Dependabot or Renovate enabled 2 pts
- No critical outdated dependencies 1 pt
- Lockfile committed and current 1 pt
3.4 · Branch hygiene3 points
- Default branch protected 1 pt
- PRs require reviewer 1 pt
- Clean commit history 1 pt
Pillar 4 — Security
15 pts4.1 · License clarity5 points
A repo without a license is all rights reserved by default — a hard blocker for enterprise adoption.
- LICENSE file exists 2 pts
- OSI-approved license 1 pt
- License in README/registry 1 pt
- Third-party licenses acknowledged 1 pt
4.2 · Vulnerability disclosure5 points
- SECURITY.md with private path 2 pts
- GitHub Private Advisories enabled 2 pts
- No hardcoded secrets 1 pt
4.3 · Supply chain integrity5 points
- Secret scanning enabled 2 pts
- Healthy contributor distribution 2 pts
- Actions use pinned SHAs 1 pt
Pillar 5 — Sustainability
10 pts5.1 · Maintainer health5 points
- Multiple active maintainers 2 pts
- Project status communicated 1 pt
- Expectations stated 1 pt
- Funding info present 1 pt
5.2 · Activity signals5 points
- Commits within last 6 months 2 pts
- Release within last 12 months 1 pt
- Organic star growth 1 pt
- Community engagement beyond maintainer 1 pt
Score interpretation
| Score | Verdict | Meaning |
|---|---|---|
| 85–100 | Excellent | Well-maintained, contributor-friendly, production-ready |
| 65–84 | Good | Solid foundation. Address flagged gaps |
| 45–64 | Needs work | Several critical gaps. Fix docs and community first |
| 0–44 | High risk | Not ready for external contributors or production |