安装时需把 换成具体平台名(如 cursor、codex、copilot),否则脚本无法定位目标目录;npx 方式要求 Node.js 20+,且安装的是技能文件而非原生 IDE 扩展;除 Claude Code、Gemini CLI、Codex CLI 外,其余平台仅验证了文件布局,未做端到端运行验证
brooks-lint
hyhmrrightMIT活跃维护一套可移植的 AI 代码质量审查技能包,让 Codex、Cursor、Copilot 等编码代理按统一标准检查架构、技术债和测试,并给出修复建议。
Portable AI code quality reviews for Codex, Cursor, Copilot and other coding agents: six Agent Skills for architecture, technical debt, tests and remediation.
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>README 未说明,纯技能包,算力由宿主编码代理承担
基于十二本经典工程书的 AI 代码质量审查技能包,给 Codex、Cursor、Copilot 等编码代理用
一套可移植的 AI 代码质量审查技能包,让 Codex、Cursor、Copilot 等编码代理按统一标准检查架构、技术债和测试,并给出修复建议。
核心能力
- 用六维腐化风险诊断生产代码与测试套件
- 每条结论按症状→出处→后果→补救四段输出并附书目引用
- 给出 0–100 健康分,便于横向对比
- 提供 /brooks-review、/brooks-audit、/brooks-debt 等六个斜杠命令
- 以标准 Agent Skills 形式分发,一次安装多平台复用
容易踩的坑
- v1.9.1最新正式版2026-10-24 · 2026-10-24 01:45 UTC
[1.9.1] - 2026-10-24
This release unifies GitHub and npm at 1.9.1. The withdrawn npm 1.9.0 is not reused. Publication follows successful remote CI on the exact release commit.
Added
- Native DeepSeek Harness plugin bundle and skill provider, exposing the six skills and their shared resources through the DSH registry (#44). Thanks to @Sad-happy.
- A portable npm CLI for installing the skills into all 14 existing coding-agent platform targets, with global, project, and custom destinations, platform listing, and no Bash or Git requirement.
- npm distribution metadata, packed-artifact installation regression tests, and a DSH market-index generator that requires an actually published npm version and uses its registry publication timestamp. Documentation covers npm installation, publication, and adding the project-owned DSH market source; default market inclusion and live host compatibility are not claimed.
Fixed
- Release-test fixtures clone without inherited tags, preventing published annotated tags from changing synthetic audit baselines in CI.
- npm publication requires a clean committed tree and a successful latest remote Validate run for the exact commit, including every matrix job. Regression tests and the release procedure enforce remote verification before publication.
- DSH skill discovery now ignores only missing files; unexpected read failures retain the file path and original cause instead of silently hiding skills. Six provider regression tests cover discovery, descriptions, loading, shared resources, and error handling.
Changed
- Synchronized GitHub and npm release information at 1.9.1 across all README translations, manifests, installation guides, and the website. A tracked About/topics/managed-label configuration and metadata verification command now participate in the publication gate.
- All six README translations and the getting-started and DSH guides now distinguish npm filesystem installation from native plugin registration. Installer tests cover all platform destinations, argument validation, path safety, and preservation of unrelated files.
Thanks
A special thank-you to @Sad-happy for contributing the native DeepSeek Harness bundle and skill provider in #44, and for following through with community end-to-end verification on DSH 0.2.1-rc.2 Desktop. Your contribution made brooks-lint a proper installable DSH plugin, and your real-host testing helped us bring it to npm and plugin-market discovery.
Installation and DSH discovery
Install the portable Agent Skills with Node.js 20+ and npm:
npx brooks-lint install codex npx brooks-lint install --listInstall the native DSH plugin by package name:
dsh plugin --profile web add brooks-lintFor search in DSH Discover, enable Custom plugin markets and add the project-owned source:
https://hyhmrright.github.io/brooks-lint/dsh/index.json
Search for
brooks-lint, or discover it with keywords such ascodexandcursor. DSH does not ship a default index source. Community market submissions are pending maintainer review: awesome-dsh-plugin #9022 and Open Plugin Market #65.Published artifacts were verified for all 28 global/project installation paths, six DSH skills, and actual DSH plugin-manager installation by package name. This is not a claim of fresh end-to-end testing in every coding host.
- v1.8.02026-10-16 · 2026-10-16 03:56 UTC
查看更新说明
[1.8.0] - 2026-10-16
Added
-
Configurable model output ceilings through the GitHub Action's
max-tokensinput and the--max-tokensCLI flag, with positive safe-integer validation (#39, #42). Thanks to @scottschreckengaust. -
A
config-refAction input: CI now loads.brooks-lint.yamland conditional custom-risk guidance into a separate system-policy block. Pull requests use the trusted base policy by default;config-ref: headexplicitly opts into the checkout policy (#40). Thanks to @scottschreckengaust. -
Community-contributed documentation and an OIDC workflow example for Claude on Amazon Bedrock and Mantle using the existing custom-endpoint support (#38). Thanks to @scottschreckengaust. These integrations are retained but are outside ongoing maintainer verification.
-
Shared review guidance and the sweep report now identify configuration provenance and honor runner-supplied policy. Added a base-policy suppression regression scenario, bringing the structural eval suite to 58 scenarios (#40). Thanks to @scottschreckengaust.
Fixed
- Truncated reports now emit a workflow warning, carry
truncated: truein JSON, and display a warning in PR comments so incomplete findings and inflated Health Scores are visible. The existing live-eval runner also detects truncation (#42). Thanks to @scottschreckengaust. - CI applies configured strictness and other project policy instead of silently using defaults. An unavailable PR base policy now fails explicitly rather than falling back to unapproved head policy (#40; closes #43).
- Documented Action pins now track the release version automatically across all six READMEs and the workflow example; updated executable GitHub Action dependencies and added regression checks against version drift (#41). Thanks to @scottschreckengaust.
- Release-audit output now handles zero and singular counts correctly, announces audit scope, and has stronger regression coverage. Release-audit test fixtures use an isolated baseline tag so inherited branch history cannot invalidate them.
Changed
- Migrated repository maintenance from Claude Code to Codex: discoverable local skill links, Codex agent roles, a sequential maintenance harness, and explicit offline validation gates. Completed changes must be committed and pushed.
- Maintainer testing policy: the maintainer's Claude account has been banned. From 2026-10-16 onward, ongoing maintainer testing and verification cover only Codex-related capabilities. Previous verification of Claude Code, Gemini CLI, and other platforms is historical. Existing integrations remain available, and community verification and contributions are welcome.
- This policy does not migrate the GitHub Action or live-eval runner to an OpenAI backend: they still use the existing Anthropic client. Anthropic live evals are no longer part of routine maintainer verification; offline validation, unit tests, structural evals, and the parser benchmark remain in use.
- Clarified across all six READMEs and the workflow example that
mode: sweepin CI reports findings without applying fixes (#37). Thanks to @scottschreckengaust. Also clarified token-input descriptions and removed redundant minimum-version annotations now covered by version-reference validation (#41, #42).
-
- v1.7.02026-09-20 · 2026-09-20 12:02 UTC
查看更新说明
Maintainer-facing only — the six skills, their guides, and everything the plugin installs are byte-for-byte identical to 1.6.0. This release hardens how this repo cuts releases, after 1.6.0 shipped with two changes missing from its changelog section and both were found only by auditing after publication.
Added
-
npm run changelog:audit— account for every commit in the release range (scripts/changelog-audit.mjs). It derives the range from the last release tag (v[0-9]*), applies the only three exemptions — the release bump, a merge commit whose branch commits are listed separately, and the weekly star-history refresh — and prints the rest as a checklist to walk. Each line gets an entry or a stated reason it needs none. Between releases it frames the same range as the next release's backlog and exits 0, so it is also how you check the version number against what is actually unreleased before choosing it.The star-history exemption is judged by the files a commit touched, not by its subject: the paths come from
STAR_HISTORY_FILES, exported bygen-star-history.mjsso the chart generator and the exemption share one definition. Matching on[bot]+chore:instead would have exempted adependabot[bot]chore(deps): bump …for free, and a dependency bump is a change this changelog records. -
A release-time coverage gate inside
npm run validate.checkChangelog()only ever proved the new version's section exists.checkChangelogCoverage()now also fails on the one gap a machine can prove: a pull request merged in the range whose#Nthe section never cites — matched as#Nor a/pull/Nlink.It runs only while a release is in progress, derived as "
package.json's version has nov<version>tag yet" — so it is a no-op during normal work and unskippable at the one moment it matters, with no flag to remember.validate.ymlchecks out withfetch-depth: 0because the gate needs tags. -
A
Changelog:git trailer for a commit that lands without a version bump and defers its entry to the next release. The audit surfaces it on the checklist. A trailer rather than a sentence in the body, because prose cannot tell a commit deferring its own entry from one quoting another that did — which is how 1.6.0 lostd4b5c40despite it asking in plain English to be logged. -
npm run validatesays what the gate did, on every run. A stand-down names its reason (Changelog coverage: not audited — v1.6.0 is already tagged.); an audit names its range and its scope (… audited 4 commits in v1.6.0..HEAD — pull-request citations only; walk the rest with npm run changelog:audit.). Plainnpm version <v>tags as it commits and a remotely-deleted tag survives locally — either silently disables the audit for a whole release, and an unannounced off-state reads exactly like a pass.The audited half was missing until this release was cut: the gate printed nothing on the one path that actually audits, and the test covering it had only ever run against this repo while it was tagged, so it exercised the stand-down branch and never the other one. Bumping to 1.7.0 put the repo in enforce mode for the first time and the test failed on the spot.
Fixed
- The [1.6.0] section above now covers the two changes it had missed —
d4b5c40's platform-validation checks, and PR #25 from @2233admin, who went uncredited in a release that credited two other contributors. Both were added after 1.6.0 was published.
Changed
- Cutting a release now requires walking the commit range, not sampling it.
CLAUDE.md's Release Process, thereleaseskill, and therelease-manageragent all gained an explicit audit step between writing the changelog and validating, and all three now state the rule the 1.6.0 misses came from: nothing is exempt beyond the thre
-
- v1.6.02026-09-20 · 2026-09-20 08:42 UTC
查看更新说明
Added
-
OpenCode v2 lists all six modes in its
/menu (#31, #34) — everySKILL.mdfrontmatter now carriesmetadata.opencode/slash: "true", the opt-in OpenCode v2 reads throughmetadataBoolean(frontmatter.metadata, "opencode/slash")(skill-file.ts:45). With it,/brooks-review,/brooks-audit,/brooks-debt,/brooks-test,/brooks-healthand/brooks-sweepappear in the/popup and run the skill directly; without it a skill is reachable only through/skillsor@name.Slash-command wrappers are deliberately not shipped. PR #34 proposed six of them under
commands/opencode/, but on v2 a command that shares a skill's name shadows it: the TUI's/popup skips skills already registered as commands (autocomplete.tsx:526) and submit resolvesisCommandbeforeisSkill(index.tsx:1292) — so the wrapper would hide the very skill it exists to expose. The frontmatter opt-in is OpenCode's own supported path and adds no files to install or keep in sync.On OpenCode 1.x the flag is ignored, and 1.x is still what npm
latestinstalls (opencode-aidist-tags.latestis on the 1.18.x line, with nolatest-2tag). There, use/skills→ pick, or type/brooks-reviewfollowed by a space — a bare/brooks-reviewplus Enter is swallowed by the/popup. All six READMEs now scope the auto-register claim to v2, anddocs/opencode-setup.mdis rewritten for v2 with the 1.x fallback and the shadowing caveat spelled out.Thanks to @rapcal, whose screenshots disproved the maintainer's claim that a bare
/brooks-reviewalready worked on 1.x, and whose pointer to the v2 docs found the flag this release uses instead. -
npm run validatenow fails when a skill ships without the OpenCode opt-in —checkOpencodeSlashFlag()invalidate-repo.mjsreadsskills/*/SKILL.mdfrom disk (so an unregistered skill folder is caught too, and_shared/is skipped by construction since it has noSKILL.md), backed byhasOpencodeSlashFlag()infrontmatter.mjs, which parses themetadata:block and accepts both"true"and YAML's baretrue. No other platform reads the flag, so nothing else would fail — this check is the only thing standing between a seventh skill and a silently missing/brooks-*on OpenCode. Seven unit tests cover it, and the authoring rule is recorded inCLAUDE.md,AGENTS.mdandGEMINI.mdso all three agent-facing docs carry it. -
IBM Bob (
bob) support (#32, #33) —./scripts/install.sh bobinstalls into~/.bob/skills(--projecttargets./.bob/skills); Bob also readsAGENTS.md, so the Iron Law and Health Score rules load with it. New guide atdocs/bob-setup.md, linked and enumerated across all six READMEs anddocs/getting-started.md. Contributed by @asotobu. -
Platform docs and installer mappings are cross-checked —
scripts/platforms.mjsparsesinstall.shso both checks derive their inputs instead of restating them.checkPlatformDocs()requires everydocs/<name>-setup.mdto be linked from all six READMEs anddocs/getting-started.md, and every setup link in those documents to resolve to a guide that exists;checkInstallerPlatforms()requiresPLATFORMSand theglobal_dir()/project_dir()case tables to cover each other, so a platform can no longer be listed without a path mapping (install.sh <platform>would die with "unknown platform") or mapped without appearing in--list. Adding dsh had meant hand-syncing nine places with nothing checking any of them. Verified by mutation rather than by a green run: dropping the dsh link fromREADME.ko.mdandREADME.es.md, and deleting the dsh arm fromproject_dir(), each produce the specific expected failure. -
api-base-urlinput on the GitHub Action — the Anthropic SDK
-
- v1.5.02026-08-14 · 2026-08-14 14:41 UTC
查看更新说明
Adds a tenth platform: DeepSeek Harness (
dsh), DeepSeek AI's open-source agent harness.Added
-
DeepSeek Harness (
dsh) support. dsh loads standard Agent Skills through itspackages/skill/skill-filesystemprovider, so all six brooks-lint modes run with no conversion.curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- dshThe global install writes to
$DSH_HOME/skills(default~/.dsh/skills);--projecttargets./.dsh/skills. dsh also scans~/.agents/skills, so the vendor-neutralinstall.sh agentstarget already covered it.Three loader details were verified against dsh's own documentation and are reflected in the new guide: discovery is one level deep (
<root>/<name>/SKILL.md), which the installer's flat layout already satisfies so../_shared/resolves; skill names must be kebab-case, whichbrooks-*already is; and dsh recognises a whitespace-bounded/nametoken anywhere in a message, so/brooks-reviewand the other five work from its/menu or typed inline. dsh readsAGENTS.mdthe same way the other platforms do —$DSH_HOME/AGENTS.mdplus every file from the project root down to the working directory — so the Iron Law and Health Score rules load unchanged.New guide at
docs/dsh-setup.md, with the platform added to the install table in all six README translations and todocs/getting-started.md.
Verified before tagging:
install.shresolves all three dsh paths correctly (global,$DSH_HOMEoverride,--project) against a temporaryHOME;npm run validate, 107 unit tests, 57 eval scenarios, and the frozen-corpus parser benchmark at 100% fidelity.Full changelog: https://github.com/hyhmrright/brooks-lint/compare/v1.4.3...v1.5.0
-
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
"The bearing of a child takes nine months, no matter how many women are assigned." — Frederick Brooks, The Mythical Man-Month (1975)
50 years later, Brooks was still right — and so were McConnell, Fowler, Martin, Hunt & Thomas, Evans, Ousterhout, Winters, Meszaros, Osherove, Feathers, and the Google Testing team.
Most code quality tools count lines and cyclomatic complexity. brooks-lint goes deeper — it diagnoses your code against six decay risk dimensions synthesized from twelve classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.
For the full source-to-skill mapping, including exceptions and false-positive guards, see
skills/_shared/source-coverage.md.
Quick Start
# Claude Code
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
# Any other Agent Skills platform — Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · Bob …
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>
Then just ask ("review this PR", "audit the architecture"), or run one of the six commands —
/brooks-review, /brooks-audit, /brooks-debt, /brooks-test, /brooks-health, /brooks-sweep
(what each one does).
Every finding comes back as Symptom → Source → Consequence → Remedy with a book citation and a 0–100 Health Score. Full install options (10 more platforms) and CI/CD setup are below.
The Twelve Books
| Book | Author | Contributes to |
|---|---|---|
| The Mythical Man-Month (1975) | Frederick P. Brooks Jr. | R2, R4, R5 |
| Code Complete (1993, 2nd ed. 2004) | Steve McConnell | R1, R4 |
| Refactoring (1999, 2nd ed. 2018) | Martin Fowler | R1, R2, R3, R4, R6 |
| Clean Architecture (2017) | Robert C. Martin | R2, R5 |
| The Pragmatic Programmer (1999, 20th Anniv. 2019) | Andrew Hunt & David Thomas | R2, R3, R4, R5, T2, T3 |
| Domain-Driven Design (2003) | Eric Evans | R1, R3, R6 |
| A Philosophy of Software Design (2018) | John Ousterhout | R1, R4 |
| Software Engineering at Google (2020) | Winters, Manshreck & Wright | R2, R5 |
| The Art of Unit Testing (2009, 3rd ed. 2023) | Roy Osherove | T1, T2, T4, T5 |
| How Google Tests Software (2012) | Whittaker, Arbon & Carollo | T5, T6 |
| Working Effectively with Legacy Code (2004) | Michael Feathers | T4, T5, T6 |
| xUnit Test Patterns (2007) | Gerard Meszaros | T1, T2, T3, T4 |
The Six Decay Risks
brooks-lint evaluates your code across six production-code decay risks and six test-suite decay risks synthesized from twelve classic engineering books:
| Decay Risk | Diagnostic Question | Sources |
|---|---|---|
| 🧠 Cognitive Overload | How much mental effort to understand this? | Code Complete, Refactoring, DDD, Philosophy of SD |
| 🔗 Change Propagation | How many unrelated things break on one change? | Refactoring, Clean Architecture, Pragmatic, SE@Google |
| 📋 Knowledge Duplication | Is the same decision expressed in multiple places? | Pragmatic, Refactoring, DDD |
| 🌀 Accidental Complexity | Is the code more complex than the problem? | Refactoring, Code Complete, Brooks, Philosophy of SD |
| 🏗️ Dependency Disorder | Do dependencies flow in a consistent direction? | Clean Architecture, Brooks, Pragmatic, SE@Google |
| 🗺️ Domain Model Distortion | Does the code faithfully represent the domain? | DDD, Refactoring |
Philosophy of SD = A Philosophy of Software Design (Ousterhout) · SE@Google = Software Engineering at Google (Winters et al.)
What It Looks Like
Given this code:
class UserService:
def update_profile(self, user_id, name, email, avatar_url):
user = self.db.query(f"SELECT * FROM users WHERE id = {user_id}")
user['email'] = email
...
if user['email'] != email: # always False — silent bug
self.smtp.send(...)
points = user['login_count'] * 10 + 500
self.db.execute(f"UPDATE loyalty SET points={points} WHERE user_id={user_id}")
brooks-lint produces:
Health Score: 28/100
This method concentrates four unrelated business responsibilities into a single function, contains a logic bug that silently suppresses email change notifications, and is wide open to SQL injection.
🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons
Symptom: update_profile performs profile field updates, email change notifications, loyalty points recalculation, and cache invalidation all in one method body.
Source: Fowler — Refactoring — Divergent Change; Hunt & Thomas — The Pragmatic Programmer — Orthogonality
Consequence: Any change to the loyalty formula risks breaking email notifications and vice versa. Every edit carries regression risk across four unrelated domains simultaneously.
Remedy: Extract NotificationService, LoyaltyService, and UserCacheInvalidator. UserService.update_profile should orchestrate by calling each — it should hold no implementation logic itself.
🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires
Symptom: user['email'] = email overwrites the old value before if user['email'] != email — the condition is always False. The notification is dead code.
Source: McConnell — Code Complete — Ch. 17: Unusual Control Structures
Consequence: Users are never notified when their email address changes. Silent data integrity failure — the system appears functional while violating a business rule.
Remedy: Capture old_email = user['email'] before any mutation. Compare against old_email, not user['email'].
(+ 6 more findings including SQL injection, dependency disorder, magic numbers)
Architecture Audit with Dependency Graph
In Mode 2 (Architecture Audit), brooks-lint generates a Mermaid dependency graph at the top of the report. Modules are color-coded by severity: red = Critical findings, yellow = Warning, green = clean.
graph TD
subgraph src/api
AuthController
UserController
end
subgraph src/domain
UserService
OrderService
end
subgraph src/infra
Database
EmailClient
end
AuthController --> UserService
UserController --> UserService
UserController --> OrderService
OrderService --> UserService
OrderService --> EmailClient
UserService --> Database
EmailClient -.->|circular| OrderService
classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
classDef warning fill:#ffd43b,stroke:#e67700
classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff
class OrderService,EmailClient critical
class AuthController warning
class UserService,UserController,Database clean
The graph renders natively in GitHub, Notion, and other Markdown environments — no extra tools needed.
See More Examples
The Full Gallery has real brooks-lint output across Python, TypeScript, Go, and Java — including PR reviews, architecture audits with Mermaid dependency graphs, tech debt assessments, and test quality reviews.
New to the decay risks? The Decay Risk Field Guide explains all six — diagnostic question, signature symptoms, source books, and remedy for each.
Benchmark
Tested across 3 real-world scenarios (PR review, architecture audit, tech debt assessment):
| Criterion | brooks-lint | Claude alone |
|---|---|---|
| Structured findings (Symptom → Source → Consequence → Remedy) | ✅ 100% | ❌ 0% |
| Book citations per finding | ✅ 100% | ❌ 0% |
| Severity labels (🔴/🟡/🟢) | ✅ 100% | ❌ 0% |
| Health Score (0–100) | ✅ 100% | ❌ 0% |
| Detects Change Propagation | ✅ 100% | ✅ 100% |
| Overall pass rate | 94% | 16% |
The gap isn't what Claude can find — it's what it consistently finds, with traceable evidence and actionable remedies every time.
Reproducible benchmarks
The table above is illustrative. These numbers are deterministic and you can reproduce them locally:
Parser fidelity — SARIF export and the CI gates depend on parsing the model's Markdown report correctly. Against a frozen corpus of 30 real, model-generated reports spanning all six modes (evals/benchmark-corpus.json), each paired with an independently graded finding inventory (a separate model pass, spot-checked by hand), the shipped parser scores — run npm run benchmark:
| Metric (n = 30, frozen corpus) | Result |
|---|---|
| Exact severity-count match (parser vs. graded truth) | 30 / 30 |
| Risk-code precision / recall | 100% / 100% (56 finding-level codes, 0 FP / 0 FN) |
| Valid SARIF 2.1.0 emitted | 30 / 30 |
Because the parser is deterministic and the corpus is frozen, npm run benchmark gives everyone the same result, and npm test guards it as a regression. The corpus deliberately includes 9 false-positive / tradeoff reports (e.g. a ports-and-adapters design that looks like a dependency cycle) that must stay clean.
Scoring determinism — for a fixed finding set (2 Critical / 3 Warning / 1 Suggestion), the strictness presets produce exactly the scores their common.md table predicts: strict 34, balanced 54, legacy-friendly 74 — and only legacy-friendly leads with the top-three fixes.
Eval contracts — the 64-scenario eval suite (evals/evals.json) checks scenario structure with npm run evals and model report structure/risk codes with npm run evals:live (requires ANTHROPIC_API_KEY). These deterministic checks do not establish semantic correctness. The API runner evaluates supplied fixtures in review, audit, debt, test, and health; it explicitly skips sweep in default runs, excludes it from pass rates, and rejects explicit selection. Full Sweep needs interactive execution. See runner contracts.
Scope & honesty: the parser numbers are deterministic and exactly reproducible. The strictness and eval-suite figures are single-run live measurements against the model and vary slightly run to run. The parser benchmark measures report-parsing fidelity (does the tooling read every finding the report states?), not whether a given finding is "correct." The severity-count match is the fully independent signal; risk-code agreement also reflects the shared canonical name→code legend.
How It Compares
| brooks-lint | ESLint / Pylint | GitHub Copilot Review | Plain Claude | |
|---|---|---|---|---|
| Detects syntax & style issues | — | ✅ | ✅ | ~ |
| Structured diagnosis chain | ✅ | ❌ | ❌ | ❌ |
| Traces findings to classic books | ✅ | ❌ | ❌ | ❌ |
| Consistent severity labels | ✅ | ✅ | ~ | ❌ |
| Architecture-level insights | ✅ | ❌ | ~ | ~ |
| Domain model analysis | ✅ | ❌ | ❌ | ~ |
| Zero config, no plugins to install | ✅ | ❌ | ✅ | ✅ |
| Works with any language | ✅ | ❌ | ✅ | ✅ |
~= occasionally / inconsistently
brooks-lint doesn't replace your linter. It catches what linters can't: architectural drift, knowledge silos, and domain model distortion — the problems that slow teams down for months before anyone notices.
Installation
Claude Code
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
Short-form commands (/brooks-review) are auto-installed on first session start — or run
bash hooks/session-start yourself. To skip the marketplace:
mkdir -p ~/.claude/skills/brooks-lint && cp -r skills/* ~/.claude/skills/brooks-lint/.
Gemini CLI · Codex CLI
/extensions install https://github.com/hyhmrright/brooks-lint # Gemini CLI
Install the brooks-lint skill from hyhmrright/brooks-lint # ask inside a Codex session
Or use the installer below: ./scripts/install.sh gemini / ./scripts/install.sh codex.
Every other platform — OpenCode · Cursor · Windsurf · Antigravity · pi · Copilot · Kiro · Factory Droid · DeepSeek Harness · IBM Bob
brooks-lint ships as standard Agent Skills. Any agent that loads Agent Skills runs all six modes with no conversion — one command installs them:
# pick your platform; --project installs into the current repo instead of your global config
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>
# <platform> = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · dsh · gemini · codex · claude · bob · agents
Install the same Agent Skills with Node.js 20+ and npm, without Git or Bash. The installer covers 13 named coding tools plus the generic agents target. It installs skills rather than native IDE extensions; automated checks verify file layouts and resources, not runtime behavior in every host. The shell installer remains available.
npx brooks-lint install <platform>
npx brooks-lint install <platform> --project
npx brooks-lint install --list
Many thanks to @Sad-happy for building the native DSH bundle and skill provider in PR #44, and for verifying it with the DSH 0.2.1-rc.2 desktop app. That contribution made package-name plugin installation possible. See the DSH setup guide for installation and custom-market search.
The installer copies the skills flat into the right folder, so the shared framework
(../_shared/) always resolves — you can't get the layout wrong. Then just ask ("review this PR",
"audit the architecture") and the matching skill auto-triggers from its description.
| Platform | Installs into | Also reads | Guide |
|---|---|---|---|
| OpenCode | ~/.config/opencode/skills | ~/.claude/skills, AGENTS.md | setup |
| Cursor (2.4+) | ~/.cursor/skills | .agents/skills, AGENTS.md | setup |
| Windsurf (Cascade) | ~/.codeium/windsurf/skills | AGENTS.md | setup |
| Antigravity (Google) | .agent/skills (--project) | AGENTS.md, GEMINI.md | setup |
| pi (earendil-works) | ~/.pi/agent/skills | — | setup |
| GitHub Copilot | .github/skills (--project) | .claude/skills, AGENTS.md | setup |
| Kiro (AWS) | ~/.kiro/skills | AGENTS.md | setup |
| Factory Droid | ~/.factory/skills | AGENTS.md | setup |
DeepSeek Harness (dsh) | ~/.dsh/skills | ~/.agents/skills, AGENTS.md | setup |
IBM Bob (bob) | ~/.bob/skills | AGENTS.md | setup |
OpenCode v2, Kiro, Factory Droid, and DeepSeek Harness also auto-register /brooks-review. New to
skills, or using an agent not listed? See docs/getting-started.md.
Maintainer testing policy (2026-10-16). My Claude account has been banned. Going forward, I will only test and verify Codex-related capabilities. Earlier verification of Claude Code, Gemini CLI, or other platforms is historical and does not imply ongoing testing. Existing integrations remain available, but their current behavior is not verified by the maintainer; community test reports and contributions are welcome.
🧪 Historical verification. Claude Code, Gemini CLI, and Codex CLI were previously verified by the maintainer. The ten platforms above are documented from each tool's official skill spec and verified at the file-layout level (the installer is tested), but not yet run end-to-end by the maintainer on every platform. Tried one — working or broken? Open an issue with the platform, version, and what you saw. Another Agent-Skills agent? It almost certainly works the same way — tell us and we'll add it.
Slash Commands
| Command | What it does |
|---|---|
/brooks-review | Paste a diff or point the AI at changed files. Diagnoses each of the six decay risks in Symptom → Source → Consequence → Remedy format. |
/brooks-audit | Maps module dependencies (with a Mermaid graph), identifies circular dependencies, and checks Conway's Law alignment. |
/brooks-debt | Classifies debt across the six decay risks, scores each finding by Pain × Spread, and produces a repayment roadmap with Critical / Scheduled / Monitored tiers. |
/brooks-test | Audits the suite against six test-space decay risks — Test Obscurity, Test Brittleness, Test Duplication, Mock Abuse, Coverage Illusion, Architecture Mismatch. |
/brooks-health | Abbreviated scans across all four quality dimensions → one weighted composite Health Score. Use it before a release or when onboarding a team. |
/brooks-sweep | Unified scan across R1–R6, T1–T6, and architecture, then applies fixes: safe changes auto-applied, multi-file changes confirmed, architectural decisions flagged as manual. Outputs a Fix Log and score delta. |
Syntax by platform. Claude Code also accepts the namespaced form
/brooks-lint:brooks-review — short forms are auto-installed on first session start by the
session-start hook. Codex CLI uses $brooks-review. Gemini CLI and OpenCode v2 use the table as
written. Cursor, Antigravity, pi, and DeepSeek Harness invoke Agent Skills from each skill's
description, so just ask ("review this PR", "where's our worst tech debt?"); for explicit
invocation use the platform's own syntax (pi registers each skill as /skill:brooks-review; dsh
takes the table as written, from its / menu or typed inline). On every platform the
skills also trigger automatically when you discuss code quality, architecture, or test health.
PR reviews include a lightweight Step 7 Quick Test Check automatically (skipped for docs-only diffs). For a full test audit, run
/brooks-test; for a deep dive on any single dimension, use that dimension's own skill rather than/brooks-health.
Configuration
Place a .brooks-lint.yaml in your project root to customize review behavior:
version: 1
strictness: balanced # strict | balanced (default) | legacy-friendly — softer scoring for legacy code
disable:
- T5 # skip coverage metrics check — we don't enforce coverage
severity:
R1: suggestion # downgrade Cognitive Overload findings for this domain
ignore:
- "**/*.generated.*"
- "**/vendor/**"
# custom_risks: # define project-specific Cx codes — see skills/_shared/custom-risks-guide.md
# suppress: # downgrade specific findings by risk + path (e.g. accepted legacy debt)
Copy .brooks-lint.example.yaml as a starting point.
All settings are optional — omit the file entirely for default behavior.
| Setting | Description |
|---|---|
strictness | Scoring preset: strict, balanced (default), or legacy-friendly (lighter deductions, leads with top fixes) |
disable | Risk codes to skip (R1–R6, T1–T6) |
severity | Override severity tier (critical / warning / suggestion) |
ignore | Glob patterns for files to exclude |
focus | Evaluate only these risk codes (cannot combine with disable) |
custom_risks | Define project-specific risk codes (C1, C2, …) — see custom-risks-guide.md |
suppress | Downgrade specific findings by risk + path (optional expires: date) |
Why These Books, Why Now?
"The complexity of software is an essential property, not an accidental one." — Frederick Brooks
AI can help you write code faster, but it can't tell you whether you're building a cathedral or a tar pit — and the decay risks these authors identified only get sharper as generation gets cheaper. Adding an AI assistant doesn't fix cognitive overload or domain model distortion; generating more code increases change propagation and knowledge duplication; moving faster makes accidental complexity and dependency disorder more dangerous.
Project Structure
Every skill is one SKILL.md (trigger + process skeleton) plus its own guide:
brooks-lint/
├── .claude-plugin/ · .codex-plugin/ # plugin metadata per platform
├── skills/
│ ├── _shared/ # common.md (Iron Law, config, report template, Health Score)
│ │ # source-coverage.md · decay-risks.md (R1–R6)
│ │ # test-decay-risks.md (T1–T6) · remedy-guide.md · custom-risks-guide.md
│ ├── brooks-review/ # Mode 1: PR Review → pr-review-guide.md
│ ├── brooks-audit/ # Mode 2: Architecture Audit → architecture-guide.md, onboarding-guide.md
│ ├── brooks-debt/ # Mode 3: Tech Debt → debt-guide.md
│ ├── brooks-test/ # Mode 4: Test Quality → test-guide.md
│ ├── brooks-health/ # Mode 5: Health Dashboard → health-guide.md
│ └── brooks-sweep/ # Mode 6: Full Sweep → sweep-guide.md
├── hooks/ # SessionStart hook
├── commands/ # short-form command wrappers (auto-installed by the hook)
├── evals/ # 64-scenario eval suite + frozen parser-fidelity corpus
└── assets/ # logo, banner, demo
CI/CD Integration
Automate brooks-lint on every PR using the GitHub Action:
# .github/workflows/brooks-lint.yml
name: Brooks-Lint PR Review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
brooks-lint:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: hyhmrright/brooks-lint/.github/actions/[email protected]
with:
mode: review
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
fail-below: 70
See docs/github-action-example.yml for the full template.
The action posts the review as a PR comment and optionally fails the check if the Health Score drops below a threshold. If .brooks-lint-history.json is committed to your repo, the comment also includes a trend delta (e.g., "85 → 82 (−3) over last 3 runs").
CI supports mode: review only. It reviews the collected diff without file-reading tools or edits. GitHub PR runs compare the event’s base and head SHAs; keep fetch-depth: 0 so both commits and their merge base are available. An empty diff is a skipped run with no score, while missing refs or failed collection are errors. audit, debt, test, health, and sweep remain available through interactive agents with project access. For direct CLI runs, use --base-ref <ref> --head-ref <ref> to select the comparison; the base also selects trusted config when config-ref is base. See runner contracts.
Quality gates and Code Scanning. Beyond fail-below, the action exposes:
with:
mode: review
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
fail-on: critical # fail on any Critical finding (none | warning | critical)
fail-on-regression: true # fail if the Health Score dropped vs the last run
sarif-file: brooks-lint.sarif # also upload findings to GitHub Code Scanning
fail-on-regression reads .brooks-lint-history.json, so commit that file to enforce "no new regressions". Setting sarif-file makes findings appear inline on the PR's Files changed tab and requires security-events: write permission on the job.
Project config in CI. The action applies your .brooks-lint.yaml — strictness, disable, focus, severity, ignore, custom_risks — and reads it from the selected base commit, not from the PR's checkout. A pull request therefore cannot weaken the policy that reviews it: a diff that disables every risk would otherwise score 100 and sail through fail-below before anyone approved the config change. A config a PR adds for the first time takes effect once merged, for the same reason. The report's Config: line names the provenance it used (e.g. applied from base (<ref>)). This needs the base object in the clone, which is why the template checks out with fetch-depth: 0; in a PR, missing base refs stop the action with an error instructing you to use fetch-depth: 0. It never falls back to the PR's policy. For local staged/unstaged reviews without an explicit base, unavailable default base refs allow working-tree config with an explicit provenance note. An explicitly selected missing base is always an error. Set config-ref: head to use the PR's own copy instead — appropriate when .brooks-lint.yaml is CODEOWNERS-protected and config changes should take effect in the PR that makes them:
with:
mode: review
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
config-ref: base # base (default) | head
Custom API endpoint. api-base-url points the action at any Anthropic-compatible /v1/messages endpoint — a self-hosted proxy, an LLM gateway, a regional mirror — instead of api.anthropic.com. Pass that endpoint's key as anthropic-api-key and the model id it expects as model:
with:
mode: review
api-base-url: https://your-gateway.example.com
anthropic-api-key: ${{ secrets.GATEWAY_API_KEY }}
model: gateway-model-id
brooks-lint sends your diff to whatever host you name here, so only point it at one you trust with your source. Running scripts/ci-review.mjs yourself needs no flag at all — the Anthropic SDK reads ANTHROPIC_BASE_URL directly.
Claude on Amazon Bedrock. Bedrock serves the Anthropic Messages API natively, so no new client is needed: point api-base-url (action v1.6.0+) at https://bedrock-runtime.{region}.amazonaws.com/anthropic and pass a short-term Bedrock API key as anthropic-api-key — minted inside the job from an OIDC-assumed role, so no long-lived key sits in a secret. docs/github-action-example.yml carries the full wiring as commented steps: role assumption, token minting, model ids, the IAM permissions needed, and the bedrock-mantle alternative. The trust note above still applies — with Bedrock the diff goes to your own AWS account, in the Region you name.
This path cannot review pull requests from forks. GitHub grants a forked pull_request run neither repository secrets nor id-token: write, so there is no OIDC token to exchange for the role and no stored key to fall back on. Fork coverage needs a different trigger (pull_request_target, with all the care that running against untrusted branches demands) or a different key source.
Output ceiling and invalid reports. max-tokens: 8192 raises the report’s output ceiling (default 4096). Truncated or structurally invalid reports fail the run rather than supplying a passing score. Raise the limit and rerun after truncation. A skipped run has score: null; the Action skips score thresholds and SARIF upload instead of converting that absence to zero.
Cost: ~$0.05–0.15 per PR run depending on diff size and model. Recommend running on pull_request events only.
Roadmap
Current state (v1.4): 12-book foundation, 6 production decay risks (R1–R6) + 6 test decay risks (T1–T6), 6 skills, CI quality gates, SARIF output for GitHub Code Scanning, strictness presets, and a reproducible parser-fidelity benchmark.
- v0.2–v0.4: Plugin infrastructure, six-book framework, decay risk dimensions, benchmark suite
- v0.5–v0.7: Test Quality Review, Mermaid dependency graph,
.brooks-lint.yaml, 10-book expansion - v0.8–v0.9: Independent skill architecture; step validation, auto-diff scope,
/brooks-health, trend tracking, triage mode,--fixremedies, GitHub Action - v1.0–v1.2: Eval automation, custom
Cxrisk codes, Full Sweep skill,npm run bumpversion propagation - v1.3: Codex marketplace metadata, one-command multi-platform installer, localized READMEs + landing site
- v1.4: SARIF output, CI severity + regression gates, strictness presets, 57-scenario eval suite,
npm run benchmark
Contributing
See CONTRIBUTING.md. The most valuable contributions right now are new eval
test cases and improved decay-risk symptom patterns. Run /brooks-review on your own PR — we
review contributions with the tool we're building.
License
MIT License — see LICENSE for details.
Acknowledgments
This project stands on the shoulders of twelve giants — see The Twelve Books above for the full list with editions. The decay risks encoded in this tool are our synthesis of their ideas, applied to modern code quality assessment.