repo-standard/README.md

repo-standard

Per-repo gate for the open/ presentation standard: README first screen, install block, files required by the repo's class, and dead repo references.

A repository can be substantially good and still read as abandoned. The gap is almost never the code — it is the first screen, an install path that stops halfway, and references to a name that was retired two renames ago. This plugin checks that surface in one repository and reports what it finds.

Solo-maintained, fork-and-own. This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See the marketplace governance for the full model.

AI-generated: all code produced by Claude Code through dialog-driven development.

Install

Use the https:// form. The forge UI's clone button hands out an ssh:// URL, and marketplace add answers it with Invalid git URL — a message that never mentions the protocol.

claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
claude plugin install repo-standard@ktg-plugin-marketplace

Or enable it directly in ~/.claude/settings.json — a working second path, not a replacement for the two commands above:

{ "enabledPlugins": { "repo-standard@ktg-plugin-marketplace": true } }

Requirements

Node 18 or newer. No dependencies. The one network call — the org listing, used to read a repo's published description — reads anonymously, so it needs no token; --offline skips it.

What it does

Run it inside a repository:

node scripts/repo-standard-check.mjs --dir "$PWD"

It checks five things, and the repository's class decides what each one means:

Check	What fails it
First screen	no H1 on line 1, or the line under it is not the published description. An H1 that merely differs from the repo name is a WARN — that is a naming choice, not a defect
Install block	the form for this class is missing, incomplete, or shown over ssh://
Required files	a file this class needs is absent
References	an open/<name> in URL position resolves to nothing
Description	empty, or past the length bound

Findings are ERROR, WARN, SKIP or OK; the process exits 1 on any ERROR. A SKIP means the check could not run — an unreachable forge, a repo that is not in the register. It is not a pass, and the output says which.

The class decides what is required

The class is read off the catalog and the remotes; it is structural, not a judgement. It lives in register/repos.json.

Class	Install form	Requires
plugin	marketplace add and a CLI install command	README, LICENSE, CHANGELOG, plugin manifest
catalog	marketplace add only — it is the marketplace	+ GOVERNANCE, CONVENTIONS
shared-asset	how to vendor it; never a plugin install line	README, LICENSE
standalone	pip/uv	README, LICENSE
org-profile	none	README

A flat standard across every class would demand a CONTRIBUTING from a CSS library that accepts no contributions, and a roadmap from a five-line profile. That is how a gate teaches people to switch it off.

Three outcomes on references, not two

"Matches no repository" and "matches something that is deliberately not a repository" are different findings. The second class is real and it is common: a retired name kept alive on purpose in prose, a reserved namespace occupying a repo-shaped path, a published package name that was never a repo. If those share an outcome with genuine dead links, the genuine ones hide inside a pile of correct text.

Only names in URL position are treated as references, which excludes prose, paths and directory names in one move. The .git suffix is normalised first — without that, a raw scan turns three dead names into about twenty.

Non-goals

• Anything requiring a view across every repository at once. This gate sees one repo. A README can look correct from the inside and only turn out wrong when a dozen are compared. Org-wide divergence is measured where the org is enumerated, not here.
• Fixing while measuring. It records findings; you fix them afterwards. Patching under measurement is how inconsistency accumulates unnoticed.
• Deciding whether to rename a repo, or whether a roadmap is real. Those are operator calls. The gate brings evidence to them.
• Blocking commits. There is no hook. A gate that fails a correct repository is the mechanism that gets gates switched off, so this one earns that role before it takes it.

Tests

npm test

34 tests over the pure classifiers. The reference fixtures are the measured false positives that produced the three-outcome rule, each with its expected verdict.

Changelog

See CHANGELOG.md.