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.

v1.9.1发布于 2026-10-24 01:45 UTC1,571star +4 / 7 天75fork同步于 2026-11-10 23:48 UTC

怎么上手

由 README 提炼,执行前请确认
/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 说明

README 未说明,纯技能包,算力由宿主编码代理承担

下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

由 README 自动翻译提炼

基于十二本经典工程书的 AI 代码质量审查技能包,给 Codex、Cursor、Copilot 等编码代理用

一套可移植的 AI 代码质量审查技能包,让 Codex、Cursor、Copilot 等编码代理按统一标准检查架构、技术债和测试,并给出修复建议。

核心能力

  • 用六维腐化风险诊断生产代码与测试套件
  • 每条结论按症状→出处→后果→补救四段输出并附书目引用
  • 给出 0–100 健康分,便于横向对比
  • 提供 /brooks-review、/brooks-audit、/brooks-debt 等六个斜杠命令
  • 以标准 Agent Skills 形式分发,一次安装多平台复用

容易踩的坑

安装时需把 换成具体平台名(如 cursor、codex、copilot),否则脚本无法定位目标目录;npx 方式要求 Node.js 20+,且安装的是技能文件而非原生 IDE 扩展;除 Claude Code、Gemini CLI、Codex CLI 外,其余平台仅验证了文件布局,未做端到端运行验证

内容由模型根据 README 生成,可能不完整或不准确,以官方文档为准。看原文 README

最近发版

5 个版本v1.9.1
  1. 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 --list
    

    Install the native DSH plugin by package name:

    dsh plugin --profile web add brooks-lint
    

    For 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 as codex and cursor. 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.

  2. 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-tokens input and the --max-tokens CLI flag, with positive safe-integer validation (#39, #42). Thanks to @scottschreckengaust.

    • A config-ref Action input: CI now loads .brooks-lint.yaml and conditional custom-risk guidance into a separate system-policy block. Pull requests use the trusted base policy by default; config-ref: head explicitly 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: true in 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: sweep in 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).
  3. 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 by gen-star-history.mjs so the chart generator and the exemption share one definition. Matching on [bot] + chore: instead would have exempted a dependabot[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 #N the section never cites — matched as #N or a /pull/N link.

      It runs only while a release is in progress, derived as "package.json's version has no v<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.yml checks out with fetch-depth: 0 because 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 lost d4b5c40 despite it asking in plain English to be logged.

    • npm run validate says 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.). Plain npm 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, the release skill, and the release-manager agent 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
  4. v1.6.02026-09-20 · 2026-09-20 08:42 UTC
    查看更新说明

    Added

    • OpenCode v2 lists all six modes in its / menu (#31, #34) — every SKILL.md frontmatter now carries metadata.opencode/slash: "true", the opt-in OpenCode v2 reads through metadataBoolean(frontmatter.metadata, "opencode/slash") (skill-file.ts:45). With it, /brooks-review, /brooks-audit, /brooks-debt, /brooks-test, /brooks-health and /brooks-sweep appear in the / popup and run the skill directly; without it a skill is reachable only through /skills or @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 resolves isCommand before isSkill (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 latest installs (opencode-ai dist-tags.latest is on the 1.18.x line, with no latest-2 tag). There, use /skills → pick, or type /brooks-review followed by a space — a bare /brooks-review plus Enter is swallowed by the / popup. All six READMEs now scope the auto-register claim to v2, and docs/opencode-setup.md is 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-review already worked on 1.x, and whose pointer to the v2 docs found the flag this release uses instead.

    • npm run validate now fails when a skill ships without the OpenCode opt-in — checkOpencodeSlashFlag() in validate-repo.mjs reads skills/*/SKILL.md from disk (so an unregistered skill folder is caught too, and _shared/ is skipped by construction since it has no SKILL.md), backed by hasOpencodeSlashFlag() in frontmatter.mjs, which parses the metadata: block and accepts both "true" and YAML's bare true. 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 in CLAUDE.md, AGENTS.md and GEMINI.md so all three agent-facing docs carry it.

    • IBM Bob (bob) support (#32, #33) — ./scripts/install.sh bob installs into ~/.bob/skills (--project targets ./.bob/skills); Bob also reads AGENTS.md, so the Iron Law and Health Score rules load with it. New guide at docs/bob-setup.md, linked and enumerated across all six READMEs and docs/getting-started.md. Contributed by @asotobu.

    • Platform docs and installer mappings are cross-checked — scripts/platforms.mjs parses install.sh so both checks derive their inputs instead of restating them. checkPlatformDocs() requires every docs/<name>-setup.md to be linked from all six READMEs and docs/getting-started.md, and every setup link in those documents to resolve to a guide that exists; checkInstallerPlatforms() requires PLATFORMS and the global_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 from README.ko.md and README.es.md, and deleting the dsh arm from project_dir(), each produce the specific expected failure.

    • api-base-url input on the GitHub Action — the Anthropic SDK

  5. 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 its packages/skill/skill-filesystem provider, 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 -- dsh
      

      The global install writes to $DSH_HOME/skills (default ~/.dsh/skills); --project targets ./.dsh/skills. dsh also scans ~/.agents/skills, so the vendor-neutral install.sh agents target 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, which brooks-* already is; and dsh recognises a whitespace-bounded /name token anywhere in a message, so /brooks-review and the other five work from its / menu or typed inline. dsh reads AGENTS.md the same way the other platforms do — $DSH_HOME/AGENTS.md plus 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 to docs/getting-started.md.

    Verified before tagging: install.sh resolves all three dsh paths correctly (global, $DSH_HOME override, --project) against a temporary HOME; 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

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

    "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

    BookAuthorContributes to
    The Mythical Man-Month (1975)Frederick P. Brooks Jr.R2, R4, R5
    Code Complete (1993, 2nd ed. 2004)Steve McConnellR1, R4
    Refactoring (1999, 2nd ed. 2018)Martin FowlerR1, R2, R3, R4, R6
    Clean Architecture (2017)Robert C. MartinR2, R5
    The Pragmatic Programmer (1999, 20th Anniv. 2019)Andrew Hunt & David ThomasR2, R3, R4, R5, T2, T3
    Domain-Driven Design (2003)Eric EvansR1, R3, R6
    A Philosophy of Software Design (2018)John OusterhoutR1, R4
    Software Engineering at Google (2020)Winters, Manshreck & WrightR2, R5
    The Art of Unit Testing (2009, 3rd ed. 2023)Roy OsheroveT1, T2, T4, T5
    How Google Tests Software (2012)Whittaker, Arbon & CarolloT5, T6
    Working Effectively with Legacy Code (2004)Michael FeathersT4, T5, T6
    xUnit Test Patterns (2007)Gerard MeszarosT1, 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 RiskDiagnostic QuestionSources
    🧠 Cognitive OverloadHow much mental effort to understand this?Code Complete, Refactoring, DDD, Philosophy of SD
    🔗 Change PropagationHow many unrelated things break on one change?Refactoring, Clean Architecture, Pragmatic, SE@Google
    📋 Knowledge DuplicationIs the same decision expressed in multiple places?Pragmatic, Refactoring, DDD
    🌀 Accidental ComplexityIs the code more complex than the problem?Refactoring, Code Complete, Brooks, Philosophy of SD
    🏗️ Dependency DisorderDo dependencies flow in a consistent direction?Clean Architecture, Brooks, Pragmatic, SE@Google
    🗺️ Domain Model DistortionDoes 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):

    Criterionbrooks-lintClaude 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 rate94%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 / recall100% / 100% (56 finding-level codes, 0 FP / 0 FN)
    Valid SARIF 2.1.0 emitted30 / 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-lintESLint / PylintGitHub Copilot ReviewPlain 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.

    PlatformInstalls intoAlso readsGuide
    OpenCode~/.config/opencode/skills~/.claude/skills, AGENTS.mdsetup
    Cursor (2.4+)~/.cursor/skills.agents/skills, AGENTS.mdsetup
    Windsurf (Cascade)~/.codeium/windsurf/skillsAGENTS.mdsetup
    Antigravity (Google).agent/skills (--project)AGENTS.md, GEMINI.mdsetup
    pi (earendil-works)~/.pi/agent/skills—setup
    GitHub Copilot.github/skills (--project).claude/skills, AGENTS.mdsetup
    Kiro (AWS)~/.kiro/skillsAGENTS.mdsetup
    Factory Droid~/.factory/skillsAGENTS.mdsetup
    DeepSeek Harness (dsh)~/.dsh/skills~/.agents/skills, AGENTS.mdsetup
    IBM Bob (bob)~/.bob/skillsAGENTS.mdsetup

    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

    CommandWhat it does
    /brooks-reviewPaste a diff or point the AI at changed files. Diagnoses each of the six decay risks in Symptom → Source → Consequence → Remedy format.
    /brooks-auditMaps module dependencies (with a Mermaid graph), identifies circular dependencies, and checks Conway's Law alignment.
    /brooks-debtClassifies debt across the six decay risks, scores each finding by Pain × Spread, and produces a repayment roadmap with Critical / Scheduled / Monitored tiers.
    /brooks-testAudits the suite against six test-space decay risks — Test Obscurity, Test Brittleness, Test Duplication, Mock Abuse, Coverage Illusion, Architecture Mismatch.
    /brooks-healthAbbreviated scans across all four quality dimensions → one weighted composite Health Score. Use it before a release or when onboarding a team.
    /brooks-sweepUnified 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.

    SettingDescription
    strictnessScoring preset: strict, balanced (default), or legacy-friendly (lighter deductions, leads with top fixes)
    disableRisk codes to skip (R1–R6, T1–T6)
    severityOverride severity tier (critical / warning / suggestion)
    ignoreGlob patterns for files to exclude
    focusEvaluate only these risk codes (cannot combine with disable)
    custom_risksDefine project-specific risk codes (C1, C2, …) — see custom-risks-guide.md
    suppressDowngrade 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, --fix remedies, GitHub Action
    • v1.0–v1.2: Eval automation, custom Cx risk codes, Full Sweep skill, npm run bump version 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.


    Star History

    Star History