# QUALITY.md

QUALITY.md is a file you put at the root of a repository that writes down what quality means for that specific project: which characteristics matter (security, maintainability, test and spec quality, and so on), what the requirements are under each one, and the context — mission, stakeholder needs, risks — that explains why those and not others. The premise is that agents and humans are both bad at "make this better" without a written rubric, and that the rubric belongs in the repo rather than in someone's head.

It ships as three things. The format itself is a spec, published as vendor- and tool-agnostic. The `qualitymd` CLI and a `/quality` agent skill are the reference implementation: they read the file, evaluate the codebase against it, and write out an evaluation report plus a prioritized list of improvement recommendations, in a `.quality/` directory:

```
.quality/
└── evaluations/
    └── 0001-full-eval/
        ├── report.md
        └── recommendations.md
```

Numbered evaluations mean a project accumulates a history of assessments rather than one overwritten snapshot, and the recommendations file is explicitly shaped for handoff — to a human reviewer, or to an agent as the next batch of work. The pitch calls the resulting cycle a "quality loop": declare, evaluate, act, re-evaluate.

## Where it sits

The idea belongs to a family. [[llms-txt]] proposed a root markdown file describing a site for LLMs; CLAUDE.md and AGENTS.md do the same for repository conventions; QUALITY.md is the same move applied to evaluation criteria. The distinguishing bet is that quality is project-specific and has to be declared, which is why the format carries context and stakeholder needs rather than a fixed checklist — a linter config would be the version of this that doesn't need a spec.

It also overlaps with the spec-driven-development tools without duplicating them. [[acceptance-criteria-ids]] as used by [[acai]] number individual requirements so agent-written code can point back at the spec item it satisfies; that is per-feature and per-commit. QUALITY.md operates a level up, on properties of the whole codebase that no single acceptance criterion covers. The two are compatible, and the honest question is whether a project that maintains one has the appetite to maintain the other.

The philosophy section on the site — maintaining something is caring for it, and caring for a thing that serves someone is caring for that person — is a nicer framing than most quality tooling bothers with. It also sidesteps the harder question raised in [[notes-on-software-quality]], where quality is defined as the absence of problems and the argument is that quality does not survive organizational scale. A declared rubric doesn't fix that; it makes the gap between stated and actual standards legible, which is a different and smaller claim.

## Limitations

Six weeks old at time of writing, one vendor, 29 stars. The format's value is entirely in adoption — an open spec that only its own CLI reads is a config file with extra steps — and there is no visible third-party implementation yet. Evaluation is done by an LLM reading a rubric, so the output inherits every property of LLM judgement: plausible, inconsistent between runs, and unverifiable without reading the code yourself. Writing a good QUALITY.md is the hard part and the tooling can't do it for you; a generic one will produce generic recommendations.

On the [[toolbox/watchlist]] — worth re-checking for adoption by projects unrelated to the authors, a second implementation of the spec, and whether the evaluation reports hold up as anything more than a well-organized code review.

Repo: [github.com/qualitymd/quality.md](https://github.com/qualitymd/quality.md) — ~29 stars, MIT, TypeScript. Site: [getquality.md](https://getquality.md/).