Skip to content
Back to search

brooks-lint-marketplace

MarketplaceWorks with Claude CodeGitHub

Marketplace for brooks-lint plugin

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hyhmrright-brooks-lint/badge.svg)](/listings/hyhmrright-brooks-lint)

HTML

<a href="/listings/hyhmrright-brooks-lint"><img src="/api/listings/hyhmrright-brooks-lint/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Source checkout: Git + Bash
git clone https://github.com/hyhmrright/brooks-lint.git
cd brooks-lint
bash scripts/install.sh codex
$brooks-review Review the current diff and identify supported maintainability risks.
$brooks-health Assess this repository; distinguish missing evidence from clean dimensions.

This installs the current source into the global Codex skills directory. Start a new session if skills are not discovered. To install into another project, run the installer by its absolute path from that project with `codex --project`. Keep `_shared` beside the six skill folders. See the [Codex guide](docs/codex-setup.md) for layout and capability checks.

Install the latest published package with Node.js 20+: `npx brooks-lint@latest install codex`. See [getting started](docs/getting-started.md) for other installation targets.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "brooks-lint-marketplace",
  3. "description": "Marketplace for brooks-lint plugin",
  4. "owner": {
  5. "name": "hyhmrright",
  6. "email": "hyhmrright@gmail.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "brooks-lint",
  11. "description": "AI code reviews grounded in twelve classic engineering books — decay risk diagnostics with book citations, severity labels, and six analysis modes (PR review, architecture audit, tech debt, test quality, health dashboard, full-sweep auto-fix)",
  12. "version": "2.0.0",
  13. "source": "./",
  14. "author": {
  15. "name": "hyhmrright",
  16. "email": "hyhmrright@gmail.com"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 196 lines
  1. <p align="center"><img src="assets/logo.svg" alt="brooks-lint" width="150"></p>
  2. # brooks-lint
  3. **English** · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Español](README.es.md)
  4. ![Source version](https://img.shields.io/badge/version-2.0.0-blue.svg)
  5. ![MIT](https://img.shields.io/badge/license-MIT-green.svg)
  6. Six focused workflows for code review, architecture, technical debt, test quality, a health dashboard, and scoped repairs — grounded in twelve classic engineering books.
  7. Published versions: [npm](https://www.npmjs.com/package/brooks-lint) · [GitHub Releases](https://github.com/hyhmrright/brooks-lint/releases)
  8. [Migration from 1.9.1 to 2.0.0](docs/migration-v2.md)
  9. brooks-lint is a collection of Agent Skills, shared guidance and small deterministic reporting tools. Your coding agent performs the diagnosis; the project supplies a repeatable workflow, risk vocabulary and reporting contract. It is not a static analyzer and it does not guarantee that a model finds every defect.
  10. ## Quick start: Codex
  11. ```bash
  12. # Source checkout: Git + Bash
  13. git clone https://github.com/hyhmrright/brooks-lint.git
  14. cd brooks-lint
  15. bash scripts/install.sh codex
  16. ```
  17. ```text
  18. $brooks-review Review the current diff and identify supported maintainability risks.
  19. $brooks-health Assess this repository; distinguish missing evidence from clean dimensions.
  20. ```
  21. This installs the current source into the global Codex skills directory. Start a new session if skills are not discovered. To install into another project, run the installer by its absolute path from that project with `codex --project`. Keep `_shared` beside the six skill folders. See the [Codex guide](docs/codex-setup.md) for layout and capability checks.
  22. Install the latest published package with Node.js 20+: `npx brooks-lint@latest install codex`. See [getting started](docs/getting-started.md) for other installation targets.
  23. ## Choose the smallest workflow that fits
  24. | Skill | Use it for | Changes files? |
  25. |---|---|---|
  26. | `$brooks-review` | A diff or specified code: governing contract, supported risks and a discriminating witness. | No |
  27. | `$brooks-audit` | Module dependencies, ownership and boundary integrity; onboarding also has a dedicated guide. | No |
  28. | `$brooks-debt` | Maintainability debt, priorities and a repayment plan. | No |
  29. | `$brooks-test` | An existing test suite: what failures its assertions do and do not detect. | No |
  30. | `$brooks-health` | An abbreviated four-dimension assessment and evidence-scoped dashboard. | No |
  31. | `$brooks-sweep` | Diagnose and apply authorized, verifiable repairs within a bounded scope. | Yes |
  32. Use `$brooks-review` in Codex; other hosts have their own invocation syntax. Natural-language discovery depends on the host and model. Health is a summary, not four exhaustive audits. Sweep requires editing and verification capabilities and respects existing authorization; it does not demand another approval merely because a change spans files.
  33. ## What a report means
  34. A retained finding follows **Symptom → Source → Consequence → Remedy**: observable evidence, the relevant engineering principle, its consequence, and a scoped response. Book references explain the framework; they do not prove a diagnosis or a chapter-level claim. Protected behavior and unresolved obligations should be reported without invented deductions. Predictions must be distinguished from checks actually executed.
  35. The score is a configured summary of retained findings, **not a probability of correctness**. Health uses one ledger for Code Quality, Architecture, Tech Debt and Test Quality. When execution is available and permitted, bundled Node tools calculate and finalize the report. A required dimension with missing decisive evidence is **unassessed**, so no numeric composite is emitted. Only PR quality with no diff is **skipped**, with its weight redistributed. An assessed dimension with no supported findings is different from an unknown dimension.
  36. The delivery helper checks that supplied output bytes equal the finalized report and match its receipt. It does not verify diagnostic truth, later UI rendering or transport. Without permitted tool execution, the guide requires explicit verification limits; it must not invent a tool receipt. [Ledger and tool contract](skills/brooks-health/score-ledger.md).
  37. Sweep defaults to **three total repair rounds**, including the initial and Critical-only rounds. User time/tool budgets also apply. It reports a supported stop reason and unresolved work. A clean local scope can coexist with unknown broader dashboard dimensions. [Sweep guide](skills/brooks-sweep/sweep-guide.md).
  38. ## Risk vocabulary
  39. | Production code | Tests |
  40. |---|---|
  41. | R1 — Cognitive Overload | T1 — Test Obscurity |
  42. | R2 — Change Propagation | T2 — Test Brittleness |
  43. | R3 — Knowledge Duplication | T3 — Test Duplication |
  44. | R4 — Accidental Complexity | T4 — Mock Abuse |
  45. | R5 — Dependency Disorder | T5 — Coverage Illusion |
  46. | R6 — Domain Model Distortion | T6 — Architecture Mismatch |
  47. ## The Twelve Books
  48. | Book | Author |
  49. |---|---|
  50. | *The Mythical Man-Month* | Frederick P. Brooks Jr. |
  51. | *Code Complete* | Steve McConnell |
  52. | *Refactoring* | Martin Fowler |
  53. | *Clean Architecture* | Robert C. Martin |
  54. | *The Pragmatic Programmer* | Andrew Hunt & David Thomas |
  55. | *Domain-Driven Design* | Eric Evans |
  56. | *A Philosophy of Software Design* | John Ousterhout |
  57. | *Software Engineering at Google* | Titus Winters, Tom Manshreck & Hyrum Wright |
  58. | *The Art of Unit Testing* | Roy Osherove |
  59. | *How Google Tests Software* | James Whittaker, Jason Arbon & Jeff Carollo |
  60. | *Working Effectively with Legacy Code* | Michael Feathers |
  61. | *xUnit Test Patterns* | Gerard Meszaros |
  62. The detailed [source coverage matrix](skills/_shared/source-coverage.md) records concepts, tradeoffs and false-positive guards. These risks are this project’s synthesis, not an official taxonomy authored jointly by the books’ writers.
  63. <a id="benchmark"></a>
  64. ## Benchmark: choose a workflow, inspect its results
  65. Try a skill on a task you already need to do: a review with a concrete witness, a dependency diagnosis, a debt plan, a test gap, a scoped dashboard or a verified repair. The table shows **all six skills**, including ties and regressions. Workflow usefulness and measured improvement are separate claims.
  66. | Experiment | Skill / evidence | Baseline → skill | Observed change |
  67. |---|---|---:|---|
  68. | E1 | [review](docs/benchmark-evidence.md#review) | 6/6 → 6/6 | No additional passes |
  69. | E1 | [audit](docs/benchmark-evidence.md#audit) | 6/6 → 6/6 | No additional passes |
  70. | E1 | [test](docs/benchmark-evidence.md#test-the-difference-and-the-correction) | 5/6 → 6/6 | **+1 passing answer**; BV5-23 |
  71. | E2 | [debt](docs/benchmark-evidence.md#debt--older-case-only-baseline) | 11/15 → 12/15 | **+1 complete-supported answer**; older baseline |
  72. | E3 | [health](docs/benchmark-evidence.md#health--adverse-result-remains-visible) | 15/18 → 10/18 | **−5 passing answers**; excessive abstention |
  73. | E3 | [sweep](docs/benchmark-evidence.md#sweep--advantage-limited-to-one-family) | 15/18 → 18/18 | **+3 passing answers**; repeats in one family |
  74. **Read within each experiment, not across rows.** E1: generic checklist versus focused guidance, six cases per skill, one response per arm. E2: older case-only baseline versus guidance, five debt cases × three repeats; counts complete-supported answers, not E1’s primary passes. E3: generic checklist versus full guidance, 18 responses per skill and arm in the 72-answer health/sweep campaign. Sweep’s gain is confined to one priority-routing family. Health’s later fixes have offline coverage but **no completed post-fix efficacy result**. Do not combine these counts into an overall accuracy or a six-skill ranking.
  75. **E1** — CLI-selected `gpt-6.1-terra / low`; 18 cases × two groups = **36 answers**, one answer per case and group. The E1 rows count primary behavioral passes after offline adjudication: all five axes (diagnosis, contract scope, discriminating witness, remedy and verification honesty) must pass, with no missed expected issue or established false claim.
  76. **A concrete difference — BV5-23:** the contract requires an integer for a numeric string. The skill answer identified a 309-digit input that becomes `Infinity` and a protection gap in the two supplied tests. The checklist answer failed the required mutant-comparison axis; it was not penalized retrospectively for missing this newly supported observation.
  77. **A correction — BV5-24:** we initially rejected the checklist answer, then accepted its behaviorally equivalent assertion-failure witness. The original judgments and revisions remain available. One paired advantage in reused development cases is not general superiority.
  78. ### Put it to work on your own code
  79. These are starting prompts and intended deliverables, not additional benchmark wins. Supply a concrete scope and review the evidence before acting.
  80. | Skill | A useful first task |
  81. |---|---|
  82. | `$brooks-review` | Review this diff against its contract; show a minimal input that distinguishes a defect from protected behavior. |
  83. | `$brooks-audit` | Trace this dependency across module boundaries; identify the owner of the violated rule. |
  84. | `$brooks-debt` | Rank these maintenance problems by change impact; propose the smallest repayment step. |
  85. | `$brooks-test` | Show a faulty implementation these tests would accept, and the assertion that distinguishes it. |
  86. | `$brooks-health` | Assess this scope with one finding ledger; separate supported findings, clean dimensions and unknowns. |
  87. | `$brooks-sweep` | Diagnose and repair this authorized scope within three total rounds; run available checks and report what remains. |
  88. These studies use related development-authored cases and non-independent grading. Repeated answers are not independent projects. Static supplied instructions do not test native skill discovery, all models or the whole current 2.0.0 source tree.
  89. | Evidence | What it checks |
  90. |---|---|
  91. | Product regressions | Installation, scoring arithmetic, exact delivery and bounded-stop fixtures |
  92. | 30-report parser benchmark | Severity/risk extraction and SARIF, not whether diagnoses are true |
  93. | Model comparisons | Specified tasks, models, instruction revisions and rubrics |
  94. [Frozen plan](https://github.com/hyhmrright/brooks-lint/blob/17bd333/docs/research/focused-skill-recovery/results/2026-11-16-live/plan.json) · [Raw answers and records](https://github.com/hyhmrright/brooks-lint/tree/17bd333/docs/research/focused-skill-recovery/results/2026-11-16-live) · [Quoted judgments and corrections](https://github.com/hyhmrright/brooks-lint/blob/17bd333/docs/research/focused-skill-recovery/results/2026-11-16-live/adjudication/README.md) · [All six skills: evidence and limits](docs/benchmark-evidence.md)
  95. <a id="installation"></a>
  96. ## Installation and compatibility
  97. Maintainer verification currently covers **Codex**. Other integrations remain available, but earlier host verification is historical; installer layout tests are not end-to-end compatibility tests. Community reports should include host version and reproduction steps. The installers support 13 named targets plus the generic `agents` destination.
  98. `<platform> = opencode · cursor · windsurf · antigravity · pi · kiro · copilot · droid · dsh · gemini · codex · claude · bob · agents`
  99. [Codex](docs/codex-setup.md) · [OpenCode](docs/opencode-setup.md) · [Cursor](docs/cursor-setup.md) · [Windsurf](docs/windsurf-setup.md) · [Antigravity](docs/antigravity-setup.md) · [pi](docs/pi-setup.md) · [GitHub Copilot](docs/copilot-setup.md) · [Kiro](docs/kiro-setup.md) · [Factory Droid](docs/factory-droid-setup.md) · [DeepSeek Harness](docs/dsh-setup.md) · [IBM Bob](docs/bob-setup.md)
  100. The existing Claude Code marketplace commands are retained; this path is not currently maintainer-tested:
  101. ```text
  102. /plugin marketplace add hyhmrright/brooks-lint
  103. /plugin install brooks-lint@brooks-lint-marketplace
  104. ```
  105. ## Configuration
  106. ```yaml
  107. version: 1
  108. strictness: balanced
  109. ignore:
  110. - "**/vendor/**"
  111. sweep:
  112. max_iterations: 3
  113. # Optional: deliberately omit a risk from this review.
  114. # disable:
  115. # - T5
  116. ```
  117. Copy [`.brooks-lint.example.yaml`](.brooks-lint.example.yaml). The shared contract defines `strictness`, `severity`, `ignore`, `focus`/`disable`, custom `Cx` risks and scoped suppression. Disabling T5 intentionally omits its diagnosis; T5 is not merely a code-coverage percentage check. [Configuration and report contract](skills/_shared/common.md).
  118. ## CI integration is a separate path
  119. The shipped GitHub Action uses an **Anthropic-compatible API**, not Codex login. It supports **review of the collected diff only**, without interactive repository tools or repairs. This historical provider path is not part of current maintainer live verification. Use a published tag in this example.
  120. ```yaml
  121. - uses: hyhmrright/brooks-lint/.github/actions/brooks-lint@v2.0.0
  122. with:
  123. mode: review
  124. anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
  125. ```
  126. See [runner contracts](docs/runner-contracts.md) and the [full workflow template](docs/github-action-example.yml) for base-config trust, fork restrictions, invalid reports and permissions. No fixed per-run price is promised; usage depends on the selected provider, model and input.
  127. ## Development and contributions
  128. Offline validation:
  129. ```bash
  130. npm run validate
  131. npm test
  132. npm run evals
  133. npm run benchmark
  134. npm run evals:codex:validate
  135. ```
  136. Live Codex evaluation is opt-in and uses a separately chosen model and budget. Do not run the historical Anthropic evaluation as part of ordinary offline checks. Read [CONTRIBUTING.md](CONTRIBUTING.md), [the changelog](CHANGELOG.md) and [historical examples](docs/gallery.md). Thanks to contributors, including [@Sad-happy](https://github.com/Sad-happy) for the native DSH integration in [#44](https://github.com/hyhmrright/brooks-lint/pull/44).
  137. MIT — [LICENSE](LICENSE).
  138. [![Star History](assets/star-history.svg)](https://github.com/hyhmrright/brooks-lint/stargazers)
scripts/install.sh · Bundled script · 144 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. #
  3. # brooks-lint universal skill installer.
  4. #
  5. # brooks-lint ships as standard Agent Skills (SKILL.md). Most modern coding
  6. # agents discover skills from a per-platform folder with a single-level glob
  7. # (skills/<name>/SKILL.md) and read shared files via the relative path
  8. # ../_shared/. This script copies the six skills + _shared/ FLAT into the right
  9. # folder for your platform, so the relative reads always resolve — you can't get
  10. # the layout wrong.
  11. #
  12. # Usage:
  13. # ./scripts/install.sh <platform> [--project]
  14. # curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 14 on GitHub
  15. #
  16. # Platforms: opencode cursor windsurf antigravity pi kiro copilot droid dsh gemini codex claude agents bob
  17. # agents = the vendor-neutral ~/.agents/skills folder (read by Cursor, Copilot, pi, Gemini,
  18. # Codex, and DeepSeek Harness)
  19. #
  20. # Flags:
  21. # --project install into the current repo (./.<platform>/skills) instead of the global folder
  22. # --dir PATH install into an explicit folder (overrides platform mapping)
  23. # --list print supported platforms and exit
  24. #
  25. set -euo pipefail
  26. REPO_URL="https://github.com/hyhmrright/brooks-lint.git"
  27. PLATFORMS="opencode cursor windsurf antigravity pi kiro copilot droid dsh gemini codex claude agents bob"
  28. err() { printf '\033[31merror:\033[0m %s\n' "$*" >&2; }
  29. info() { printf '\033[36m›\033[0m %s\n' "$*"; }
  30. ok() { printf '\033[32m✓\033[0m %s\n' "$*"; }
  31. # --- resolve the skills/ source (adjacent to this script, or clone) ----------
  32. resolve_src() {
  33. local script_dir
  34. script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd || true)"
  35. if [ -n "$script_dir" ] && [ -d "$script_dir/../skills" ]; then
  36. local root
  37. root="$( cd "$script_dir/.." && pwd )"
  38. printf '%s' "$root/skills"
  39. return
  40. fi
  41. # Running via curl | bash — clone a shallow copy.
  42. local tmp
  43. tmp="$(mktemp -d)"
  44. info "Cloning brooks-lint into $tmp …" >&2
  45. git clone --depth 1 "$REPO_URL" "$tmp/brooks-lint" >/dev/null 2>&1
  46. printf '%s' "$tmp/brooks-lint/skills"
  47. }
  48. # --- map a platform to its skills folder -------------------------------------
  49. global_dir() {
  50. case "$1" in
  51. opencode) printf '%s' "$HOME/.config/opencode/skills" ;;
  52. cursor) printf '%s' "$HOME/.cursor/skills" ;;
  53. windsurf) printf '%s' "$HOME/.codeium/windsurf/skills" ;;
  54. antigravity) printf '%s' "$HOME/.gemini/skills" ;;
  55. pi) printf '%s' "$HOME/.pi/agent/skills" ;;
  56. kiro) printf '%s' "$HOME/.kiro/skills" ;;
  57. copilot) printf '%s' "$HOME/.copilot/skills" ;;
  58. droid) printf '%s' "$HOME/.factory/skills" ;;
  59. # DeepSeek Harness resolves its config root from $DSH_HOME, falling back to ~/.dsh.
  60. dsh) printf '%s' "${DSH_HOME:-$HOME/.dsh}/skills" ;;
  61. gemini) printf '%s' "$HOME/.gemini/skills" ;;
  62. codex) printf '%s' "$HOME/.codex/skills" ;;
  63. claude) printf '%s' "$HOME/.claude/skills" ;;
  64. agents) printf '%s' "$HOME/.agents/skills" ;;
  65. bob) printf '%s' "$HOME/.bob/skills" ;;
  66. *) return 1 ;;
  67. esac
  68. }
  69. project_dir() {
  70. case "$1" in
  71. opencode) printf '%s' "$PWD/.opencode/skills" ;;
  72. cursor) printf '%s' "$PWD/.cursor/skills" ;;
  73. windsurf) printf '%s' "$PWD/.windsurf/skills" ;;
  74. antigravity) printf '%s' "$PWD/.agent/skills" ;;
  75. pi) printf '%s' "$PWD/.pi/skills" ;;
  76. kiro) printf '%s' "$PWD/.kiro/skills" ;;
  77. copilot) printf '%s' "$PWD/.github/skills" ;;
  78. droid) printf '%s' "$PWD/.factory/skills" ;;
  79. dsh) printf '%s' "$PWD/.dsh/skills" ;;
  80. gemini) printf '%s' "$PWD/.gemini/skills" ;;
  81. codex) printf '%s' "$PWD/.codex/skills" ;;
  82. claude) printf '%s' "$PWD/.claude/skills" ;;
  83. agents) printf '%s' "$PWD/.agents/skills" ;;
  84. bob) printf '%s' "$PWD/.bob/skills" ;;
  85. *) return 1 ;;
  86. esac
  87. }
  88. # --- arg parsing -------------------------------------------------------------
  89. PLATFORM=""
  90. SCOPE="global"
  91. EXPLICIT_DIR=""
  92. while [ $# -gt 0 ]; do
  93. case "$1" in
  94. --project|--here) SCOPE="project" ;;
  95. --dir) shift; EXPLICIT_DIR="${1:-}" ;;
  96. --list) printf 'Supported platforms: %s\n' "$PLATFORMS"; exit 0 ;;
  97. # Print the header comment block, stopping at the first non-comment line. A
  98. # hardcoded line range drifted out of sync and leaked `set -euo pipefail`
  99. # and the variable assignments into the help text.
  100. -h|--help) awk 'NR>1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]:-$0}"; exit 0 ;;
  101. -*) err "unknown flag: $1"; exit 2 ;;
  102. *) PLATFORM="$1" ;;
  103. esac
  104. shift
  105. done
  106. if [ -z "$PLATFORM" ] && [ -z "$EXPLICIT_DIR" ]; then
  107. err "no platform given."
  108. printf 'Supported platforms: %s\n' "$PLATFORMS" >&2
  109. printf 'Example: ./scripts/install.sh opencode\n' >&2
  110. exit 2
  111. fi
  112. # --- resolve destination -----------------------------------------------------
  113. if [ -n "$EXPLICIT_DIR" ]; then
  114. DEST="$EXPLICIT_DIR"
  115. elif [ "$SCOPE" = "project" ]; then
  116. DEST="$(project_dir "$PLATFORM")" || { err "unknown platform: $PLATFORM"; exit 2; }
  117. else
  118. DEST="$(global_dir "$PLATFORM")" || { err "unknown platform: $PLATFORM"; exit 2; }
  119. fi
  120. SRC="$(resolve_src)"
  121. [ -d "$SRC" ] || { err "could not locate skills/ source at: $SRC"; exit 1; }
  122. # --- copy flat ---------------------------------------------------------------
  123. info "Installing brooks-lint skills"
  124. info " from: $SRC"
  125. info " to: $DEST"
  126. mkdir -p "$DEST"
  127. cp -R "$SRC"/* "$DEST"/
  128. count="$(find "$DEST" -maxdepth 2 -name SKILL.md | wc -l | tr -d ' ')"
  129. ok "Installed $count skills (+ _shared/) into $DEST"
  130. info "Flat layout verified: brooks-* and _shared/ are siblings, so ../_shared/ resolves."
  131. echo
  132. info "Next: open your agent and ask \"review this PR\" / \"audit the architecture\","
  133. info "or invoke a skill directly (e.g. /brooks-review). See docs/<platform>-setup.md."

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.