Add the prose gate
-
Install it:
Terminal window pnpm add -D @oakgreencc/deadwood -
Add
deadwood.jsonat the repository root.{}uses the defaults; to allow more Markdown, list it:{"markdown": { "allow": ["**/README.md", "AGENTS.md", "CLAUDE.md", "docs/**"] }}Setting
allowreplaces the default list, so keep the defaults you want. -
Run it:
Terminal window npx deadwoodExit 0 is clean, 1 lists offenders, 2 is a usage or config error.
Adopt it with existing offenders
Section titled “Adopt it with existing offenders”deadwood --init # freeze today's offenders in deadwood.baseline.jsonCommit the baseline and own it in CODEOWNERS, so growing it takes a person. When offenders are fixed, run deadwood --update: it only shrinks the baseline.
Exempt some files from the comment check
Section titled “Exempt some files from the comment check”{ "overrides": [{ "files": ["scripts/**"], "comments": false }]}Or give them their own ceiling: "comments": { "maxDensity": 0.3 }.
Run it in Nx
Section titled “Run it in Nx”deadwood checks the whole repository, so run it from a root project that depends on every project. In the root package.json:
"nx": { "name": "workspace", "implicitDependencies": ["*"], "targets": { "deadwood": { "command": "deadwood", "cache": true } }}Then add deadwood to the verify command, e.g. nx run-many -t lint test deadwood.
Every key: deadwood reference. Why: Quality ratchets.