brooks-lint: AI Code Reviews With Citations From Twelve Engineering Books

The problem brooks-lint targets: reviews that cannot be repeated

Two engineers reviewing the same pull request rarely produce the same list of complaints. One flags a long method, the other shrugs and says it is fine. brooks-lint tries to make that output repeatable by anchoring every finding to a named pattern from a specific book, so a comment about a method doing four unrelated things arrives as Divergent Change with a Refactoring citation rather than as a matter of taste. The target user is a team that already runs an AI coding agent and wants its review pass to produce structured, citable output. The README frames the contrast plainly: most code quality tools count lines and cyclomatic complexity, while brooks-lint diagnoses against six decay risk dimensions synthesized from twelve books. That is a claim about the shape of the output, not about accuracy. The diagnosis is only as good as the model reading the code, and the README itself points to skills/_shared/source-coverage.md for the exceptions and false-positive guards, which is an admission that the mapping from book to finding needs qualification.

Six decay risks and the twelve books behind them

The taxonomy is the part of the project with the most structure. Six production decay risks are named, each with a diagnostic question and a source list: Cognitive Overload (how much mental effort to understand this), Change Propagation (how many unrelated things break on one change), Knowledge Duplication (is the same decision expressed in multiple places), Accidental Complexity (is the code more complex than the problem), Dependency Disorder (do dependencies flow in a consistent direction), and Domain Model Distortion (does the code faithfully represent the domain). The README also says a parallel set of six test-suite decay risks exists, though the table shown covers the production side. The twelve books are listed with the risks they contribute to, and the mapping is many-to-many: Refactoring feeds R1, R2, R3, R4 and R6, while Domain-Driven Design feeds R1, R3 and R6. That overlap is the honest part of the design. A single finding can legitimately cite Fowler and Evans at once, and the README does exactly that in its sample output, pairing Fowler's Divergent Change with Hunt and Thomas on Orthogonality for one Change Propagation finding. The risk labels are not a partition of code smells; they are lenses that can point at the same line.

How a finding is assembled: Symptom, Source, Consequence, Remedy

The output contract is fixed. Every finding comes back as Symptom, Source, Consequence, Remedy, with a book citation and a contribution to a 0 to 100 Health Score. The README's worked example takes a Python UserService.update_profile method and reports a Health Score of 28/100, then lists findings. The first is a Change Propagation finding: the method performs profile updates, email change notifications, loyalty points recalculation and cache invalidation in one body. The Source line names Fowler for Divergent Change and Hunt and Thomas for Orthogonality. The Consequence explains that any change to the loyalty formula risks breaking email notifications. The Remedy is concrete: extract NotificationService, LoyaltyService and UserCacheInvalidator, and let update_profile orchestrate without holding implementation logic. A second finding is Domain Model Distortion, and it is a bug rather than a style note: the code assigns user['email'] = email before testing if user['email'] != email, so the condition is always False and the notification is dead code. The remedy is to capture old_email before mutating. That pairing is the strongest argument for the tool. It reports a real defect and a design problem in the same pass, and it tells you which book each judgement comes from.

Installing brooks-lint and running a first review

There are two install paths. On Claude Code, the README uses the plugin marketplace commands. The first registers the repository as a marketplace, the second installs the plugin from it.

/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

For any other Agent Skills platform, the README gives a curl one-liner that takes the platform name as an argument. The list named in the README is Cursor, Codex, Gemini, Copilot, Windsurf, OpenCode and Kiro, and it says nine more platforms are covered in the installation section further down.

curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>

After installing, the README says you can either ask in plain language, for example "review this PR" or "audit the architecture", or invoke one of six slash commands: /brooks-review, /brooks-audit, /brooks-debt, /brooks-test, /brooks-health and /brooks-sweep. A sensible first run is /brooks-health on a module you already understand, because a health score you can sanity-check against your own opinion tells you more than a score on unfamiliar code. The repository also ships .brooks-lint.example.yaml at the top level, which is the configuration file to copy before you change any defaults; the README excerpt does not document its keys, so read the file itself. The package.json is not a runtime dependency: it declares no dependencies, only a devDependency on @anthropic-ai/sdk at 0.52.0, and its scripts are maintenance tasks (validate, test, evals, benchmark, history, bump). Treat the project as an agent skill bundle plus tooling, not as an npm library you import.

Six commands, and what full-sweep auto-fix actually implies

The six commands split the work by scope rather than by language. /brooks-review is the pull-request-sized pass. /brooks-audit and /brooks-health look at architecture and overall condition. /brooks-debt and /brooks-test target accumulated design debt and the test suite. /brooks-sweep is the one to think hardest about: the project description calls it full-sweep auto-fix. An agent that both diagnoses and edits across a whole repository is doing something categorically different from one that prints comments. The README's own example remedies are refactorings with real blast radius, such as extracting three services out of a single method. Nothing in the README excerpt describes a rollback path, a dry-run mode, or a diff preview for the sweep command. That absence is the single most important thing to resolve before running it on a branch you care about. The safe pattern is the obvious one: run the review and audit commands first, read the findings, and only then decide whether to let a sweep touch files, on a branch you can discard.

Where brooks-lint is the wrong tool

It is not a linter in the compiler sense. There is no rule engine to configure deterministically, no exit code you can rely on to fail a build, and no offline analysis. Every finding is produced by a model reading your code, which means the same input can produce different findings on two runs, and a finding can be wrong. The README's example finding is a genuine bug, but a tool that can spot a dead notification branch can also invent one, and the source-coverage document exists precisely because the book-to-pattern mapping has exceptions. If your requirement is a reproducible gate in CI, this is the wrong layer. The right shape is to run it alongside a conventional linter, not instead of one. There is a second boundary: the tool is built for Agent Skills platforms. If your workflow has no such agent, the install path does not apply to you at all. And the taxonomy is opinionated by construction. Twelve books chosen by the maintainer define what counts as decay, so a team that disagrees with Ousterhout on deep modules will find the Cognitive Overload findings argue past them.

Alternatives: SonarQube-style analyzers and plain linters

The closest comparison is a rule-based static analyzer such as SonarQube or a language linter like ESLint. The difference is the mechanism, not the goal. A rule engine parses code into a syntax tree and matches patterns, so its output is deterministic and its rule set is enumerable; you can read the rule that fired and know exactly why. brooks-lint has no rules to enumerate. It has a taxonomy of six risks and a corpus of twelve books, and a model applies them to whatever it reads. That buys it findings a rule engine cannot express, because Divergent Change is a judgement about responsibilities rather than a syntax pattern, and the README's dead-code example depends on reading the order of two statements in context. It costs determinism, auditability and speed. The honest split: use a rule engine for the checks you want enforced on every commit, and use brooks-lint for the design conversation you would otherwise have in a review thread. They do not compete for the same slot.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-14, the same day as the v1.5.0 release. The two releases before it are v1.4.3 on 2026-08-04 and v1.4.2 on 2026-07-24, whose release note reads "Fix duplicate skills on Codex CLI". That cadence matters for upgrade cost in a specific way: because the deliverable is prompt and skill content rather than compiled code, a version bump can change how findings are phrased without changing any API you depend on. The v1.4.2 note is a good illustration, since a platform integration bug was fixed in a patch release. The practical implication is that pinning matters less than reading the changelog before a sweep, because a changed skill can change what an auto-fix does. The licence is MIT, which is permissive and places few obligations on reuse; the repository ships a LICENSE file at the top level. That is a description of the licence identifier, not legal advice, and if you redistribute the bundled book-derived content you should read the licence text and the source-coverage document yourself.

Editorial conclusion

Adopt brooks-lint if your team already uses an Agent Skills platform such as Claude Code, Cursor, Codex or Gemini, and you want review findings that name the pattern and the book behind it rather than a raw complexity number. Skip it if you need deterministic, offline static analysis wired into a build gate, or if you cannot accept an LLM in the review path. Before trusting it on real code, run /brooks-health on one module you know well and check whether the cited patterns match what you would have said yourself; the README also points to skills/_shared/source-coverage.md for the exceptions and false-positive guards, which is where you should look next.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes