hyhmrright/brooks-lint

Overview

brooks‑lint is a tool that lets you run AI‑powered code‑review “skills” on a variety of agent platforms (Claude, Gemini, Codex, Cursor, etc.). It does not lint syntax or style; instead it evaluates production code and test suites against six decay‑risk dimensions that the author distilled from twelve classic software‑engineering books (e.g., The Mythical Man‑Month, Clean Architecture, Refactoring). For each risk it produces a structured finding:

Symptom → Source → Consequence → Remedy

Each finding is cited to the original book, labelled with a severity (🔴 critical, 🟡 warning, 🟢 suggestion) and contributes to an overall Health Score (0‑100). The tool can also emit architecture diagrams (Mermaid), debt‑ranking tables, and a “sweep” mode that automatically applies safe fixes.

The package is distributed as Agent‑Skills that can be installed on many AI‑assistant platforms via a tiny installer script. Once installed you invoke one of six slash commands (/brooks-review, /brooks-audit, …) or ask the assistant to “review this PR”.

---

Key Features

Feature	What it does	Why it matters
Six decay‑risk dimensions	Cognitive overload, change propagation, knowledge duplication, accidental complexity, dependency disorder, domain‑model distortion (plus six test‑suite risks)	Gives a principled, book‑backed view of code health beyond line‑count metrics
Structured findings	Each issue is reported as Symptom → Source → Consequence → Remedy with a citation to a classic book	Makes the feedback traceable and actionable for developers and reviewers
Health score (0‑100)	Aggregates severity counts using configurable strictness presets (strict, balanced, legacy‑friendly)	Provides a quick, comparable health indicator for PRs, releases, or whole repos
Architecture audit	Generates a Mermaid dependency graph, highlights cycles and Conway’s‑Law mismatches	Helps spot high‑level design drift that linters miss
Tech‑debt roadmap	Ranks findings by Pain × Spread and groups them into Critical / Scheduled / Monitored tiers	Gives teams a concrete plan for incremental improvement
Test‑suite audit	Checks for test obscurity, brittleness, duplication, mock abuse, coverage illusion, architecture mismatch	Extends the same risk model to the test code base
Auto‑fix / sweep mode	Applies safe, single‑file fixes automatically; larger changes are logged for manual review	Reduces manual effort for low‑risk issues
Multi‑platform Agent‑Skills	Installable on Claude, Gemini, Codex, Cursor, OpenCode, Windsurf, IBM Bob, etc. via a single script	Lets teams use the same review logic regardless of the AI assistant they prefer
Zero‑config default	Works out‑of‑the‑box; optional .brooks‑lint.yaml for custom strictness, disabled risks, ignore patterns	Low barrier to adoption

---

How It Works (High‑Level Flow)

1. Installation – Run the provided install.sh script with the target platform name (e.g., bash scripts/install.sh codex). The script copies the skill files into the platform’s skill directory.
2. Invocation – In the chat/IDE, issue a slash command (/brooks-review) or simply ask the assistant to review a PR.
3. Model call – The skill sends the relevant code (diff, whole files, or dependency graph) to the underlying LLM (Claude, Gemini, etc.) along with a prompt that encodes the six risk questions and the citation style.
4. Parsing – The LLM returns a Markdown report. brooks‑lint’s parser extracts each finding, maps it to a canonical risk code, and computes severity counts.
5. Scoring & Output – The tool aggregates counts into a Health Score, optionally renders a Mermaid graph, and returns the structured report to the user.
6. Optional sweep – In /brooks‑sweep mode the tool attempts to apply the “Remedy” steps that are safe to automate, then reports a “Fix Log” and updated score.

---

Typical Use Cases

Scenario	Command	What you get
Pull‑request review	/brooks-review	A list of decay‑risk findings for the changed files, each with book citation and remediation advice, plus a health score for the PR.
Architecture sanity check	/brooks-audit	Mermaid dependency graph, circular‑dependency warnings, and risk findings that relate to module coupling and dependency direction.
Technical‑debt triage	/brooks-debt	Ranked debt items, pain‑×‑spread scores, and a roadmap (Critical / Scheduled / Monitored).
Test‑suite health	/brooks-test	Findings specific to test code (obscurity, brittleness, mock abuse, etc.) with suggestions for refactoring tests.
Quick health snapshot	/brooks-health	Composite health score across all dimensions – useful before a release or for onboarding.
Automated clean‑up	/brooks-sweep	Auto‑applies safe fixes, produces a fix log, and shows the delta in health score.

---

Installation Quick‑Start

# Example for the Codex CLI platform
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh \
  | bash -s -- codex

The script copies the skill files into the appropriate ~/.codex/skills (or equivalent) folder and registers the six slash commands. For Claude Code, Gemini CLI, or any of the other listed agents, replace codex with the platform name.

If you prefer a manual install for Claude Code:

mkdir -p ~/.claude/skills/brooks-lint
cp -r skills/* ~/.claude/skills/brooks-lint/

After installation, simply ask the assistant to “review this PR” or run one of the slash commands.

---

Configuration (Optional)

Create a .brooks-lint.yaml at the repository root to tweak behavior:

version: 1
strictness: balanced   # strict | balanced (default) | legacy-friendly
disable:
  - T5                 # skip coverage‑metric check
severity:
  R1: suggestion       # downgrade Cognitive Overload findings
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

• strictness changes how the health score is calculated.
• disable can turn off specific risk categories.
• severity lets you re‑label a risk for a particular project.
• ignore uses glob patterns to exclude generated or vendored files.

---

Limitations & Open Issues

Limitation	Details
Dependency on LLM quality	The accuracy of findings hinges on the underlying model (Claude, Gemini, etc.). The repo provides deterministic parsing benchmarks, but the semantic correctness of a finding is still model‑dependent.
Platform verification	The maintainer notes that Claude Code testing is no longer performed; only Codex‑related capabilities are actively verified. Community testing is encouraged for other platforms.
Language‑agnostic but not language‑aware	brooks‑lint works with any language because it treats code as text, but it cannot leverage language‑specific AST information, so some patterns may be missed compared to a language‑aware static analyzer.
Benchmark numbers are illustrative	The README states the benchmark table is “illustrative” and that live eval numbers can vary.
No replacement for traditional linters	It is meant to complement, not replace, tools like ESLint, Pylint, or static analysis suites.

---

Who Might Benefit?

• Engineering managers looking for a high‑level health metric across many repositories.
• Dev‑ops / CI pipelines that want an AI‑driven quality gate before merging.
• Individual developers who want actionable, book‑backed review comments without reading the original texts.
• Teams using multiple AI assistants – the same skill works on Claude, Gemini, Codex, Cursor, etc., providing consistent feedback.

---

Bottom Line

brooks‑lint bridges classic software‑engineering wisdom with modern LLM‑based code review. It delivers structured, citation‑rich findings across six well‑defined decay risks, produces a composite health score, and can even auto‑apply safe fixes. While it does not replace traditional linters, it adds a valuable layer of architectural and design‑level insight that many AI‑assisted reviewers miss.

---

All information above is taken directly from the repository’s README; no external assumptions have been added.