hyhmrright/brooks-lint — brooks-lint — AI Code Review Grounded in Classic Engineering Books
Transcript
QuickFacts
Welcome to brooks-lint, a markdown-based diagnostic framework that transforms AI code review from ad-hoc feedback into structured, traceable audits. This repository is grounded in twelve classic software engineering books, and it ships as portable skills that run on over a dozen agent platforms.
PlainEnglish
Think of this like recipe cards for the AI. Instead of programming a traditional linter with regex and abstract syntax trees, you write step-by-step instructions in plain language. The AI reads those instructions at runtime and follows them. The skill is the process, not the code.
QuickFacts
The repository is almost entirely declarative. Skills are defined in markdown with YAML frontmatter. Node scripts handle validation and CI integration. The AI itself — whether Claude, Gemini, or another model — runs on the agent platform and reads the skills. In CI pipelines, the Anthropic API generates reports, which are transformed into SARIF format for GitHub Code Scanning.
Architecture
Here's how it all fits together. Six user-facing skills — review, audit, debt, test, health, and sweep — are triggered by natural language. Each skill reads the shared framework: common dot md defines the Iron Law diagnostic template, decay-risks dot md lists symptom catalogs, and source-coverage dot md maps twelve classic books. Validation scripts enforce consistency across manifests and guides. The installer copies everything flat into platform-specific directories, and each platform discovers the skills automatically.
Architecture
Every finding follows the Iron Law. Think of it like a medical diagnosis form. You can't just say 'this is bad.' You must state the symptom — what you observed in the code. The source — which book and principle it violates. The consequence — what breaks if this is ignored. And the remedy — a concrete action to fix it. This structure prevents vague, inconsistent feedback.
Architecture
Let's trace a typical PR review. A developer pastes a diff and says 'review this.' The AI agent triggers the brooks-review skill by matching the description pattern. The skill reads the shared framework to load the Iron Law template and the decay-risk catalog. It scans the diff for six risks in sequence — Change Propagation, Cognitive Overload, Knowledge Duplication — applying 'what not to flag' guards to prevent false positives. Finally, it outputs a markdown report with findings, a health score, and a one-sentence verdict.
Architecture
The framework defines twelve decay risks split across two dimensions. Six for production code — Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, and Domain Model Distortion. And six for test suites — Test Obscurity, Brittleness, Duplication, Mock Abuse, Coverage Illusion, and Architecture Mismatch. Each risk has a symptom catalog, severity thresholds, and explicit guards to prevent false positives.
Architecture
One of the coolest parts is portability. brooks-lint ships as Agent Skills that install flat across twelve platforms. Every platform expects skills in a different directory — dot claude slash skills, dot codex slash skills, dot config slash opencode slash skills, and so on. The installer copies the skills and shared framework as siblings, so relative imports always resolve. Each platform discovers the skills automatically by reading SKILL dot md frontmatter.
Architecture
The validation pipeline is what keeps this system reliable. validate-repo dot mjs enforces cross-document consistency. The book count is derived from a frontmatter list in source-coverage dot md, and the script checks that all six localized READMEs describe the same count in natural language. Version numbers propagate from package dot json to four platform manifests and six README badges. Guide step continuity is verified — no gaps allowed. Every skill must have a 'Do NOT trigger for' clause to prevent routing collisions. And a frozen benchmark corpus of thirty real model-generated reports measures parser fidelity deterministically.
Architecture
The maintenance layer is itself a multi-agent system. When the maintainer asks to 'add a new skill' or 'release brooks-lint,' the brooks-harness orchestrator spawns five subagents in sequence. The skill-author writes the SKILL dot md and guide. The eval-curator adds test scenarios. The consistency-QA agent runs the full validation gate and writes a PASS or FAIL verdict — if it fails, the work loops back to the author for a fix. The trigger-boundary-auditor checks for routing collisions. And the release-manager cuts the release. The QA gate is never skipped — it's the enforcer that prevents drift.
Community
This is a very active project. The last commit landed today. There have been forty-two commits in the past month and over a hundred in the past ninety days. The repository has three active contributors in recent months, with hyhmrright driving the majority of the work — over four hundred commits total. There are eight branches and fourteen release tags. This is a project that's actively maintained and evolving.
PlainEnglish
brooks-lint takes AI code review from freeform feedback to structured diagnostics. Every finding is grounded in a book, every symptom has a remedy, and the whole system is portable across a dozen agent platforms. It's a framework that respects the classics and makes them actionable in the age of AI. Thanks for watching.
How this was made
Lenzon read hyhmrright/brooks-lint and generated this walkthrough automatically. The narration above is the transcript of what it says.
Explain a pull request from your own repo
Point Lenzon at a repo or a pull request and get a narrated walkthrough like this one.
Try it