brooks-harness
Skill1.6k starsChanged 24 days agoMITView on GitHub
Maintenance orchestrator for the brooks-lint plugin itself. Runs a sequential subagent pipeline — author → eval → QA → trigger-audit → release — to add or edit a skill, refresh the eval suite, keep the four manifests + all README translations + CHANGELOG + AGENTS/GEMINI in sync, audit trigger boundaries, and cut releases. Drives the five agents in .codex/agents/ (skill-author, eval-curator, consistency-qa, trigger-boundary-auditor, release-manager). Triggers when the maintainer asks to work ON brooks-lint itself: "add a new skill", "edit the brooks-debt guide", "update the eval suite", "fix the trigger descriptions", "make this change and validate it", "release brooks-lint", "bump and publish", and follow-ups: "re-run", "re-validate", "update that skill", "redo the audit", "do the X part again". Do NOT trigger for: USING the brooks-lint analysis skills on some target codebase (that's brooks-review / brooks-audit / brooks-debt / brooks-test / brooks-health / brooks-sweep); generic questions about brooks-lint that don't ask to change it; or maintenance of a different plugin.
Trending
More talk lately.about the whole repository
Who's talking about hyhmrright/brooks-lint
- A Hacker News story“Show HN: Brooks-Lint – AI code reviews grounded in 12 classic engineering books”Hacker News · Jun 11, 2026 · 8 points
- hashgraph-online/awesome-codex-plugins“Add brooks-lint — AI code reviews from classic engineering books”GitHub · Apr 1, 2026 · 3 reactions
- sudosubin/agents.nix“claude-code-marketplaces.github.hyhmrright.brooks-lint: init at 1.9.1”GitHub · Oct 28, 2026
- sbalswa/oculix“Add CONTRIBUTING.md”GitHub · Oct 26, 2026
- sudosubin/agents.nix“claude-code-plugins.github.hyhmrright.brooks-lint: 1.8.0 → 1.9.1”GitHub · Oct 24, 2026
The biggest 5 of 31 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 31
Talked about on GitHub and Hacker News (31 times).
On GitHub · 30
- Apr 1, 2026Add brooks-lint — AI code reviews from classic engineering books — hashgraph-online/awesome-codex-plugins3 reactions · 6 comments
- Oct 28, 2026claude-code-marketplaces.github.hyhmrright.brooks-lint: init at 1.9.1 — sudosubin/agents.nix0 reactions
- Oct 26, 2026Add CONTRIBUTING.md — sbalswa/oculix0 reactions
- Oct 24, 2026claude-code-plugins.github.hyhmrright.brooks-lint: 1.8.0 → 1.9.1 — sudosubin/agents.nix0 reactions
- Oct 24, 2026agent-skills.github.hyhmrright.brooks-lint: 1.8.0 → 1.9.1 — sudosubin/agents.nix0 reactions
25 more on GitHub
- Oct 24, 2026[plugin-add] brooks-lint — polang233/dsh-plugin-index0 reactions · 1 comment
- Oct 24, 2026Add brooks-lint code quality skills — awesome-dsh-plugin/awesome-dsh-plugin0 reactions
- Oct 16, 2026claude-code-plugins.github.hyhmrright.brooks-lint: 1.7.0 → 1.8.0 — sudosubin/agents.nix0 reactions
- Oct 16, 2026agent-skills.github.hyhmrright.brooks-lint: 1.7.0 → 1.8.0 — sudosubin/agents.nix0 reactions
- Oct 4, 2026[Candidate] hyhmrright/brooks-lint/.claude/skills/release - release — ProSkillsMD/proskills0 reactions · 1 comment
- Oct 4, 2026[Candidate] hyhmrright/brooks-lint/.claude/skills/new-skill - new-skill — ProSkillsMD/proskills0 reactions · 1 comment
- Oct 4, 2026[Candidate] hyhmrright/brooks-lint/.claude/skills/brooks-harness - brooks-harness — ProSkillsMD/proskills0 reactions · 1 comment
- Oct 4, 2026claude-code-plugins.github.hyhmrright.brooks-lint: init at 1.7.0 — sudosubin/agents.nix0 reactions
- Sep 28, 2026agent-skills.github.hyhmrright.brooks-lint: init at 1.7.0 — sudosubin/agents.nix0 reactions
- Sep 27, 2026[gap] Curated knowledge-grounded rule packs — sblattj/prxref0 reactions
- Sep 27, 2026[gap] Review-score trending with regression gate — sblattj/prxref0 reactions
- Sep 14, 2026Weekly discovery: new DeepSeek Harness ecosystem candidates — fendouai/awesome-deepseek-harness0 reactions · 1 comment
- Aug 17, 2026Weekly discovery: new DeepSeek Harness ecosystem candidates — fendouai/awesome-deepseek-harness0 reactions · 1 comment
- Apr 29, 2026feat: add brooks-lint and logic-lens skills for AI-powered code review — anthropics/skills0 reactions
- Apr 29, 2026Feature Request: Add brooks-lint skill — AI code reviewer grounded in 12 classic engineering books — affaan-m/ECC0 reactions · 1 comment
- Apr 22, 2026[Resource]: brooks-lint — hesreallyhim/awesome-claude-code0 reactions · 1 comment
- Apr 2, 2026[Resource]: brooks-lint — hesreallyhim/awesome-claude-code0 reactions · 1 comment
- Mar 31, 2026Add brooks-lint — book-backed AI code review skill — ComposioHQ/awesome-claude-skills0 reactions
- Mar 31, 2026Add brooks-lint — book-backed AI code review plugin — rohitg00/awesome-claude-code-toolkit0 reactions · 1 comment
- Mar 31, 2026Add brooks-lint — book-backed AI code review skill — travisvn/awesome-claude-skills0 reactions · 1 comment
- Mar 31, 2026Add brooks-lint — book-backed AI code review plugin — composio-community/awesome-claude-plugins0 reactions
- Mar 31, 2026Add brooks-lint extension — Piebald-AI/awesome-gemini-cli0 reactions
- Mar 31, 2026Add brooks-lint extension — Piebald-AI/awesome-gemini-cli-extensions0 reactions
- Mar 30, 2026[Community] brooks-lint: Claude Code plugin for book-backed code reviews (6 classic SE books) — anthropics/claude-code0 reactions · 2 comments
- Mar 27, 2026[Resource]: brooks-lint — hesreallyhim/awesome-claude-code0 reactions · 1 comment
On Hacker News · 1
- Jun 11, 2026Show HN: Brooks-Lint – AI code reviews grounded in 12 classic engineering books8 points · 1 comment
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- new-skillSkill
- releaseSkill
- brooks-harnessSkill
- new-skillSkill
- releaseSkill
- brooks-auditSkill
- brooks-debtSkill
- brooks-healthSkill
- brooks-reviewSkill
- brooks-sweepSkill
- brooks-testSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Use the available Codex collaboration tools with the matching agent role.
- Very specific: line 57
Run notes and the QA report live under _workspace/brooks-harness/.
- Very specific: line 114
Direct-to-main releases: follow AGENTS.md. Commit, push, tag, or publish only when requested.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
brooks-lint — Maintenance Harness (Orchestrator)
This skill orchestrates work on the brooks-lint repo itself. It runs a sequential
subagent pipeline: each stage is a dedicated agent defined in .codex/agents/.
Use the available Codex collaboration tools with the matching agent role; inherit
the parent model and permissions. If custom roles are not loaded, pass the role's
developer_instructions from its TOML file to a standard subagent. Stages run
sequentially. Every editing agent must preserve other contributors' changes and
own only the files assigned by the orchestrator.
Pipeline
[orchestrator]
Phase 0 context check
Phase 1 classify request → select stages
Phase 2 run selected stages in order, with a QA loop-back:
skill-author → eval-curator → consistency-qa ─(FAIL)→ back to author
│ PASS
▼
trigger-boundary-auditor (only if a description changed)
▼
release-manager (only if release requested)
Phase 3 report + collect feedbackPhase 0 — Context check
Determine the run mode before doing anything:
_workspace/brooks-harness/exists + maintainer asks to redo part of a prior run → partial re-run: invoke only the affected stage(s), reusing prior notes._workspace/brooks-harness/exists + a fresh request → new run: move the old folder to_workspace/brooks-harness_prev/, start clean.- No
_workspace/brooks-harness/→ initial run: create it.
Run notes and the QA report live under _workspace/brooks-harness/. The real
artifacts are the repo files themselves — agents edit skills/, evals/, manifests
directly; _workspace/ only holds the run's notes and the PASS/FAIL verdict for audit.
Phase 1 — Classify the request
Pick the minimal set of stages. The QA stage is never skipped — every change is gated.
| Request | author | eval | QA | trigger-audit | release |
| Add a new skill | ✓ (via new-skill scaffold) | ✓ | ✓ | ✓ | — |
| Edit skill / guide content | ✓ | if codes changed | ✓ | if description changed | — |
Edit _shared/ framework | ✓ | if risk defs changed | ✓ | — | — |
| Codex / maintenance configuration | — | — | ✓ | — | — |
| Eval suite only | — | ✓ | ✓ | — | — |
| Fix trigger descriptions | ✓ | — | ✓ | ✓ | — |
| Release | — | — | ✓ | — | ✓ |
| Full: change + release | ✓ | as needed | ✓ | if applicable | ✓ |
Phase 2 — Run the pipeline
Spawn each selected stage as a subagent in order using Codex collaboration tools. Pass each agent (a) the task
contract and (b) the previous stage's summary. Agents write their summaries to
_workspace/brooks-harness/; read them between stages.
- skill-author — creates/edits the content. For a brand-new skill it invokes the
new-skillscaffold. Returns the list of files touched + convention-relevant choices (new risk codes, new Step numbers, changeddescriptiontrigger phrases). - eval-curator — if
skill-authorreported new/changed risk codes or modes, adds the paired happy-path + false-positive scenarios and runsnpm run evals. - consistency-qa (gate — never skipped) — runs
npm run validate+npm test+npm run evals, then the cross-document sync checks (manifests, all version-bearing text files, CHANGELOG, AGENTS/GEMINI book count, eval count). Writes a PASS/FAIL verdict. On FAIL: loop back to the agent named in the verdict (author or eval-curator), fix, then re-run QA. Repeat once; if it still fails, stop and report to the maintainer. - trigger-boundary-auditor — run only if a
descriptionfield changed. It read-only audits the six shipped skills' trigger surfaces for false-triggering and routing collisions. Surface its findings; if it flags a real collision, loop back to skill-author. - release-manager — run only if a release was requested, and only after QA
PASS. Cuts the release via the
releaseskill.
Phase 3 — Report & feedback
Report: stages run, files changed, QA verdict, trigger-audit findings (if any), and the release URL (if any). Then offer the maintainer a feedback opening: "Anything to adjust in the result, the agent roles, or the pipeline order?" Record accepted changes in the AGENTS.md harness change-log table.
Conventions this harness enforces
- Inherit the current Codex model and permissions; do not select a Claude model.
- consistency-qa must be
general-purpose(it runs npm scripts); the trigger-boundary-auditor is read-only. - No command wrappers are created — Codex discovers
.agents/skills/. - Direct-to-main releases follow AGENTS.md. Commit, push, tag, or publish only when requested. Run the explicit validate/test/evals gate; Claude global rules and hooks do not execute in Codex.
Error handling
- A stage that fails once is retried once with its error as input; a second failure stops the pipeline and reports to the maintainer (no silent skip).
- QA FAIL never proceeds to release.
- Conflicting data is reported with provenance, not deleted.
- High-risk git ops (
--no-verify,--force, history rewrites) require explicit maintainer authorization — release-manager stops and asks.
Test scenarios
Normal flow — "add a brooks-security skill": Phase 1 selects author+eval+QA+audit.
skill-author runs new-skill brooks-security, creates SKILL.md (with a sibling-carving
"Do NOT trigger for:" clause) + guide; eval-curator adds an S-code happy-path + a
false-positive scenario; consistency-qa runs the gate → PASS; trigger-boundary-auditor
confirms no collision with brooks-review/audit. Report lists files + PASS.
Error flow — QA FAIL on book-count drift: maintainer adds a thirteenth book but
edits only source-coverage.md. consistency-qa's cross-doc check finds README still
says "twelve" → FAIL, attributed to skill-author. Orchestrator loops back; skill-author
updates README/AGENTS/GEMINI wording; QA re-runs → PASS. No release was requested, so
the pipeline ends at Phase 3.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

