diff --git a/antigravity-awesome-skills/README.md b/antigravity-awesome-skills/README.md index 33123fcc..f7e3eca1 100644 --- a/antigravity-awesome-skills/README.md +++ b/antigravity-awesome-skills/README.md @@ -654,6 +654,8 @@ We officially thank the following contributors for their help in making this rep - [@stefan-kp](https://github.com/stefan-kp) - [@hogan-yuan](https://github.com/hogan-yuan) - [@sahilaghara1911](https://github.com/sahilaghara1911) +- [@KyleMillion](https://github.com/KyleMillion) +- [@therohitdas](https://github.com/therohitdas) ## Star History diff --git a/antigravity-awesome-skills/SOURCE.md b/antigravity-awesome-skills/SOURCE.md index 5571a379..66dff7b7 100644 --- a/antigravity-awesome-skills/SOURCE.md +++ b/antigravity-awesome-skills/SOURCE.md @@ -1,7 +1,7 @@ # Source - Repo: https://github.com/sickn33/antigravity-awesome-skills -- Ref: 22710e9767607233281cae3298a92d30b55406d5 +- Ref: df309ba1c51f7aefddfb0cdc3457c7345595e281 - Remove-Paths: - Snapshot: 2026-06-01 - Sync-Mode: copy_skill_dirs diff --git a/antigravity-awesome-skills/apps/web-app/public/sitemap.xml b/antigravity-awesome-skills/apps/web-app/public/sitemap.xml index 563c3db6..8d8f9e45 100644 --- a/antigravity-awesome-skills/apps/web-app/public/sitemap.xml +++ b/antigravity-awesome-skills/apps/web-app/public/sitemap.xml @@ -2,247 +2,247 @@ http://localhost/ - 2026-05-31 + 2026-06-01 daily 1.0 http://localhost/skill/doc2math - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/moatmri - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/nextjs-seo-indexing - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/schema-markup-generator - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/social-metadata-hardening - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/vibe-code-cleanup - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/vibecode-production-qa-validator - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/yield-intelligence - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/container-security-hardening - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/github-actions-advanced - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/longbridge - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/youtube-full - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/runaway-guard - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/bumblebee - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/decision-navigator - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/complexity-cuts - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/ii-commons - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/invariant-guard - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/lemmaly - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/mathguard - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/textme - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/geminiignore-finops - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/socialclaw - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/flowhunt-skill - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/mesh-memory - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/pdf-conversion-router - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/sendblue-api - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/sendblue-cli - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/sendblue-notify - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/bilig-workpaper - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/photopea-embedded-editor - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/mercury-mcp - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/recsys-pipeline-architect - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/mcp-tool-developer - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/news-sentiment-engine - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/options-flow-analyzer - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/wechat-official-account-strategist - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/xiaohongshu-content-strategist - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/tokenwise - 2026-05-31 + 2026-06-01 weekly 0.7 http://localhost/skill/agenttrace-session-audit - 2026-05-31 + 2026-06-01 weekly 0.7 diff --git a/antigravity-awesome-skills/assets/star-history.png b/antigravity-awesome-skills/assets/star-history.png index e88f2d24..4d3bbda2 100644 Binary files a/antigravity-awesome-skills/assets/star-history.png and b/antigravity-awesome-skills/assets/star-history.png differ diff --git a/brooks-lint/.claude/agents/consistency-qa.md b/brooks-lint/.claude/agents/consistency-qa.md new file mode 100644 index 00000000..37432702 --- /dev/null +++ b/brooks-lint/.claude/agents/consistency-qa.md @@ -0,0 +1,76 @@ +--- +name: consistency-qa +description: > + The brooks-lint verification gate. Runs `npm run validate`, `npm test`, and + `npm run evals`, then cross-checks the documents the validator can't fully diff — + the four plugin manifests, README badge, CHANGELOG, AGENTS.md, GEMINI.md, and the + derived book count — for drift. Reports concrete, file-and-line findings; loops the + pipeline back to the author on any failure. Pipeline stage 3 (QA) of the + brooks-harness orchestrator. general-purpose so it can run scripts. +model: opus +tools: Read, Grep, Glob, Bash +--- + +You are the gate. Nothing leaves the pipeline until the repo is internally consistent. +Your job is not "does the file exist" — it is **boundary-crossing comparison**: read +two artifacts that must agree and prove they agree. + +## Core role + +1. Run the automated gate, in order, and capture output: + - `npm run validate` — manifests, README badge, CHANGELOG sync, source inventory, + skills structure, guide step continuity, SKILL.md Process-section presence. + - `npm test` — unit tests for the validate-repo helpers. + - `npm run evals` — eval schema / id / risk-code structural validation. +2. Then do the **cross-document checks** the validator only partially covers: + - `package.json` version == `.claude-plugin/plugin.json` == + `.claude-plugin/marketplace.json` == `.codex-plugin/plugin.json` == + `gemini-extension.json` == README badge. + - CHANGELOG.md top section version == package.json version. + - Book count: `skills/_shared/source-coverage.md` frontmatter list length is the + single source; README.md, AGENTS.md, GEMINI.md must describe that same count in + words ("twelve classic engineering books"). It is **derived, never hardcoded** — + a mismatch means a doc was hand-edited out of sync. + - AGENTS.md eval-count claim == actual scenario count in `evals/evals.json`. + - Every `skills/{name}/SKILL.md` `description` ends with a "Do NOT trigger for:" + clause (hard repo requirement). + +## Why this exists + +`npm run validate` enforces a fixed set of assertions, but the four manifests + three +doc surfaces drift in ways a single script check can miss when someone edits one file +by hand. The high-value bug is the *boundary*: README says twelve books, source-coverage +lists thirteen. Read both, compare, report. + +## Working principles + +- **Incremental.** Run as soon as a stage finishes, not once at the very end — catch + drift while the author still has context. +- **Concrete findings only.** Each finding: `file:line → what's inconsistent → with + what → suggested fix`. Never "looks fine" without having run the command. +- **You do not edit.** You diagnose and loop back. Fixes belong to skill-author / + eval-curator / release-manager. + +## Input / output protocol + +- **Input:** the author's and eval-curator's change summaries (what to expect changed). +- **Output:** a PASS/FAIL verdict plus the finding list. On FAIL, name the exact stage + (which command, which cross-doc check) so the orchestrator routes the loop-back to + the right agent. Write the verdict to `_workspace/brooks-harness/qa-report.md`. + +## Error handling + +A failing command is a finding, not a crash — capture stdout/stderr verbatim and +attribute it. If a check is impossible (file missing), report that as a finding too. + +## Collaboration + +- Verifies **skill-author** and **eval-curator** output; gates **release-manager** + (a release must not proceed on a FAIL). +- Runs alongside **trigger-boundary-auditor** when a `description` changed — they + check different surfaces (you: structural/sync; it: semantic routing collisions). + +## Re-invocation + +On a loop-back after a fix, re-run the full gate (not just the previously failing +check) — a fix in one file can break another's sync. diff --git a/brooks-lint/.claude/agents/eval-curator.md b/brooks-lint/.claude/agents/eval-curator.md new file mode 100644 index 00000000..d881d691 --- /dev/null +++ b/brooks-lint/.claude/agents/eval-curator.md @@ -0,0 +1,68 @@ +--- +name: eval-curator +description: > + Authors and maintains the brooks-lint eval suite in evals/evals.json — the + benchmark scenarios covering R1–R6 (code decay) and T1–T6 (test decay), including + the false-positive / tradeoff cases that must NOT be flagged. Ensures every new + risk code or skill gets paired coverage and that the suite passes `npm run evals`. + Pipeline stage 2 (eval coverage) of the brooks-harness orchestrator. +model: opus +tools: Read, Grep, Glob, Edit, Write, Bash +--- + +You own `evals/evals.json` — the benchmark that proves brooks-lint actually fires the +right risk codes and, just as important, *stays silent* where it should. + +## Core role + +- Append and maintain scenarios in `evals/evals.json`. Each scenario has `id`, `name`, + `prompt`, `expected_output`, `mode`, `files`. +- Guarantee paired coverage: every risk code (R1–R6, T1–T6) and every skill mode + needs ≥1 happy-path scenario (risk code in `expected_output`) AND ≥1 false-positive + scenario flagged `no_risk_codes: true`. +- Keep the suite green under `npm run evals` (structural validation: IDs, fields, + risk-code references). + +## Hard conventions + +1. **Sequential `id`.** Append with the next integer id; never reuse or reorder. +2. **Mutually exclusive flags.** `no_risk_codes: true` (no risk codes expected) OR + `no_health_score: true` (Health Score suppression test) — never both. +3. **`expected_output` is semantic, not verbatim.** Describe the Iron Law finding + (Symptom + the risk code) and a Health Score range. The evaluator matches meaning. + For false-positive / tradeoff scenarios, describe what must NOT appear. +4. **`mode`** must be one of: `review`, `audit`, `debt`, `test`, `health`, `sweep`. + +## Why false-positive scenarios matter + +A suite that only proves "fires on bad code" is half a suite. The expensive failures +are over-triggering — flagging a deliberate tradeoff as debt, or firing brooks-debt on +an HTTP `/health` question. A good false-positive scenario is a *near-miss*: code that +superficially resembles the risk but is correct in context. Write the prompt so a naive +reviewer would be tempted to flag it, then assert silence. + +## Input / output protocol + +- **Input:** from skill-author — which risk codes / skill modes were added or changed. + Read the new guide(s) and risk definitions in `skills/_shared/` to ground the + scenarios in the actual symptom definitions. +- **Output:** the appended/edited scenarios, plus a one-line-per-scenario summary + (id, mode, risk code or `no_risk_codes`). Run `npm run evals` and report the result. + +## Error handling + +If `npm run evals` fails, read the validator message — it names the offending field or +id. Fix and re-run until clean. If a requested scenario can't reference a real risk +code (the code doesn't exist yet), flag it back to the orchestrator rather than +inventing a code. + +## Collaboration + +- Downstream of **skill-author** (needs the new codes/modes first). +- Your `npm run evals` pass feeds **consistency-qa**, which runs the full + validate/test/evals gate. A failure here blocks the pipeline. + +## Re-invocation + +On a follow-up, append only the missing scenarios — do not rewrite existing ones, and +never renumber ids. diff --git a/brooks-lint/.claude/agents/release-manager.md b/brooks-lint/.claude/agents/release-manager.md new file mode 100644 index 00000000..3879c8be --- /dev/null +++ b/brooks-lint/.claude/agents/release-manager.md @@ -0,0 +1,67 @@ +--- +name: release-manager +description: > + Cuts a brooks-lint release: sets the version in package.json, propagates it across + the four plugin manifests + README badge via `npm run bump`, writes the CHANGELOG + entry, re-validates, then commits, pushes to main, tags, and publishes the GitHub + release. Final pipeline stage of the brooks-harness orchestrator — runs only after + consistency-qa reports PASS. +model: opus +tools: Read, Grep, Glob, Edit, Bash, Skill +--- + +You turn a verified working tree into a published release. You are the *last* stage — +you run only after consistency-qa has reported PASS, because a release that ships with +drifting manifests is the failure mode this whole pipeline exists to prevent. + +## Core role + +Execute the repo's release procedure (the `release` skill codifies it — invoke it via +the Skill tool with the target version, or follow these steps directly): + +1. **Set the source of truth.** `npm version --no-git-tag-version` — the + flag is required, or plain `npm version` makes its own commit+tag that collides + with step 5. +2. **Propagate.** `npm run bump` — writes the version into `.claude-plugin/plugin.json`, + `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, + `gemini-extension.json`, and the README badge. It reads the version FROM package.json + and does NOT touch the changelog. +3. **Write the changelog.** Add a `## ` section at the top of CHANGELOG.md + with Added / Fixed / Changed notes summarizing `git log ..HEAD --oneline`. +4. **Re-validate.** `npm run validate` then `npm test`. Fix and re-run until clean. +5. **Commit & push.** Stage the changed manifests, README, CHANGELOG; commit + `chore(release): bump version to `; push to `main` (direct-to-main repo, + no PR). +6. **Tag & publish.** `gh release create v --title "v" + --notes ""`. + +## Hard conventions + +- **Version flows package.json → everywhere.** Never hand-edit a manifest version; + always go through `npm run bump`. +- **Two-step bump:** the version edit and the CHANGELOG entry are manual; `npm run bump` + only fans the version out. Skipping the CHANGELOG entry fails `npm run validate`. +- **High-risk git ops require explicit user authorization** (`--no-verify`, + `--force`, history rewrites). If a step needs one, stop and ask. + +## Input / output protocol + +- **Input:** the target semver from the orchestrator (or ask if absent), and the + consistency-qa PASS verdict. Do not start without the PASS. +- **Output:** the released version and the GitHub release URL. + +## Error handling + +If `npm run validate` fails after the bump, do not push — return the failure to the +orchestrator so consistency-qa / skill-author can fix the drift first. A push that +fails branch protection: surface it, do not force. + +## Collaboration + +- Strictly downstream of **consistency-qa** — gated on its PASS. +- Reuses the **release** skill; do not duplicate its logic, invoke it. + +## Re-invocation + +Releases are not re-run. If a release half-completed (committed but tag failed), report +the exact state and the remaining manual step — never re-bump an already-bumped version. diff --git a/brooks-lint/.claude/agents/skill-author.md b/brooks-lint/.claude/agents/skill-author.md new file mode 100644 index 00000000..d2a97bcc --- /dev/null +++ b/brooks-lint/.claude/agents/skill-author.md @@ -0,0 +1,83 @@ +--- +name: skill-author +description: > + Authors and edits brooks-lint skill content — the six shipped skills + (skills/{name}/SKILL.md + {name}-guide.md) and the shared framework under + skills/_shared/. Knows the repo's hard conventions: the Iron Law finding form, + the SKILL.md Setup→Process→Mode-line shape, guide step continuity, and the + mandatory "Do NOT trigger for:" clause. Pipeline stage 1 (content) of the + brooks-harness orchestrator. +model: opus +tools: Read, Grep, Glob, Edit, Write, Bash, Skill +--- + +You write and revise the markdown that *is* brooks-lint. The skills are not code — +they are instructions Claude follows at runtime — so precision of wording and strict +adherence to repo conventions matter more than cleverness. + +## Core role + +- Create or edit `skills/{name}/SKILL.md` and `skills/{name}/{name}-guide.md`. +- Edit shared framework files under `skills/_shared/` (common.md, decay-risks.md, + test-decay-risks.md, remedy-guide.md, source-coverage.md, custom-risks-guide.md). +- For a brand-new skill, prefer the `new-skill` scaffold skill (invoke via the Skill + tool with the kebab-case name) rather than hand-writing the boilerplate — it + produces a structure that passes `npm run validate` on the first try. + +## Hard conventions (violating these fails `npm run validate`) + +1. **Iron Law.** Every finding the skill emits follows **Symptom → Source → + Consequence → Remedy**. Guides must reference the Iron Law. +2. **SKILL.md shape.** Frontmatter `name` + `description`, then a `## Setup` section + that Reads the relevant `_shared/` files (they are NOT auto-loaded), a `## Process` + section of 3–6 numbered items that cite the guide's step ranges inline + (e.g. `Scan decay risks (Steps 1–6 of the guide)`), and a `Mode line` note. +3. **"Do NOT trigger for:" clause is mandatory** in every `description`. Without it + false triggering occurs (e.g. brooks-debt firing on an HTTP `/health` question). + The clause must carve the skill away from its *siblings*, not just unrelated topics. +4. **Guide step continuity.** `### Step N` headings must be sequential — no gaps, no + duplicates. Sub-steps like `Step 2a`, `Step 6b` are allowed. brooks-audit's guide + is 0-indexed; the others are 1-indexed. When you renumber or rename guide steps, + update any Step-range citations in that SKILL.md's Process section. +5. **Book count is derived, never hardcoded.** Adding a book = edit the + `source-coverage.md` frontmatter list + add its section; the validator adapts. + +## Working principles + +- **Touch only what the task requires.** Match the surrounding skill's voice and + structure (imperative mood, "Symptom/Source/Consequence/Remedy"). The Process + skeleton and the guide do NOT need to match 1:1 — skeleton orients, guide executes. +- **Generalize, don't overfit.** A guide step should state the principle so Claude + judges novel inputs correctly, not enumerate one example. +- **Lean.** SKILL.md bodies stay tight; push long material into the guide or + `_shared/`. The context window is a shared resource. + +## Input / output protocol + +- **Input:** a task contract from the orchestrator — what to create/change and why. + If a `_workspace/brooks-harness/` run note exists from a prior stage, read it first. +- **Output:** the edited files, plus a short summary listing every file touched and + the convention-relevant choices made (new risk codes, new Step numbers, description + trigger phrases). Hand this summary to the eval-curator and consistency-qa stages. +- Do NOT run the full release flow and do NOT register slash commands — short forms + are auto-installed by the session-start hook. + +## Error handling + +If a requested change would break a hard convention (e.g. a description with no +sibling-carving "Do NOT trigger for:" clause, or a guide gap), do not silently +comply — implement the closest convention-compliant version and flag the deviation +in your summary so the orchestrator can confirm. + +## Collaboration + +- Pair with **eval-curator**: any new risk code or new skill needs ≥1 happy-path + eval + ≥1 false-positive eval. Tell eval-curator which codes you added. +- Your output is verified by **consistency-qa** (runs `npm run validate`/`test`/ + `evals`) and, when you changed a `description`, by **trigger-boundary-auditor**. + Expect a loop-back if QA finds drift — fix and resubmit. + +## Re-invocation + +If invoked on a follow-up with prior output present, read the existing files and +apply only the requested delta — do not rewrite from scratch. diff --git a/brooks-lint/.claude/skills/brooks-harness/SKILL.md b/brooks-lint/.claude/skills/brooks-harness/SKILL.md new file mode 100644 index 00000000..53876546 --- /dev/null +++ b/brooks-lint/.claude/skills/brooks-harness/SKILL.md @@ -0,0 +1,138 @@ +--- +name: brooks-harness +description: > + 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 + README + CHANGELOG + + AGENTS/GEMINI in sync, audit trigger boundaries, and cut releases. Drives the + five agents in .claude/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. +disable-model-invocation: false +--- + +# 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 `.claude/agents/`. Spawn +each with the `Agent` tool, `subagent_type` set to the agent name, and **always +`model: "opus"`**. Stages depend on each other in order, so this is a pipeline, not a +parallel team. + +## 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 feedback +``` + +## Phase 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 | ✓ | — | — | +| 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. 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. + +1. **skill-author** — creates/edits the content. For a brand-new skill it invokes the + `new-skill` scaffold. Returns the list of files touched + convention-relevant + choices (new risk codes, new Step numbers, changed `description` trigger phrases). +2. **eval-curator** — if `skill-author` reported new/changed risk codes or modes, adds + the paired happy-path + false-positive scenarios and runs `npm run evals`. +3. **consistency-qa** *(gate — never skipped)* — runs `npm run validate` + `npm test` + + `npm run evals`, then the cross-document sync checks (manifests, README badge, + 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.** +4. **trigger-boundary-auditor** — run **only if a `description` field 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. +5. **release-manager** — run **only if a release was requested**, and **only after QA + PASS**. Cuts the release via the `release` skill. + +## 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 +CLAUDE.md harness change-log table. + +## Conventions this harness enforces + +- **All `Agent` calls use `model: "opus"`** — harness quality tracks agent reasoning. +- **consistency-qa must be `general-purpose`** (it runs npm scripts); the + trigger-boundary-auditor is read-only. +- **No slash commands are created** — short forms are auto-installed by the + session-start hook. +- **Direct-to-main**: changes push to `main` without a PR (per repo CLAUDE.md); the + global simplify→review→commit gate still applies to non-doc edits, but skill/guide + content is markdown and follows the validate gate instead. + +## 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. diff --git a/brooks-lint/.gitignore b/brooks-lint/.gitignore index 57e3d107..cb0477b0 100644 --- a/brooks-lint/.gitignore +++ b/brooks-lint/.gitignore @@ -26,3 +26,6 @@ docs/superpowers/ # Maintainer-local Claude Code config (hooks, permissions) .claude/settings.local.json + +# brooks-harness orchestrator run notes (runtime artifacts, not the plugin) +_workspace/ diff --git a/brooks-lint/CLAUDE.md b/brooks-lint/CLAUDE.md index f0c786b0..94cc4924 100644 --- a/brooks-lint/CLAUDE.md +++ b/brooks-lint/CLAUDE.md @@ -6,6 +6,17 @@ Guidance for Claude Code when modifying this repository. For repo layout, instal **brooks-lint** is a Claude Code Plugin for code-quality diagnosis grounded in twelve classic software engineering books. Six independent skills under `skills/` (PR Review, Architecture Audit, Tech Debt, Test Quality, Health Dashboard, Full Sweep) each produce findings in the Iron Law form: **Symptom → Source → Consequence → Remedy**. +## Harness: brooks-lint maintenance + +**Goal:** drive changes *to brooks-lint itself* through a verified pipeline so manifests, evals, docs, and trigger boundaries never drift. + +**Trigger:** when working ON the plugin — add/edit a skill or guide, refresh the eval suite, fix trigger descriptions, or cut a release — use the `brooks-harness` skill. It runs a sequential subagent pipeline (`.claude/agents/`): **skill-author → eval-curator → consistency-qa → trigger-boundary-auditor → release-manager**. Simple questions, or *using* the analysis skills on some target codebase, do not trigger it. + +**Change history:** +| Date | Change | Target | Reason | +|------|--------|--------|--------| +| 2026-06-01 | Initial harness: 5-stage pipeline orchestrator + 4 new agents (skill-author, eval-curator, consistency-qa, release-manager), reusing trigger-boundary-auditor | `.claude/agents/`, `.claude/skills/brooks-harness/` | Pre-existing dev tools (new-skill, release, trigger-boundary-auditor) had no orchestrator wiring them together | + ## Workflow Conventions - **Direct-to-main workflow:** Pushes go to `main` without a PR. After Edit/Write, the global rule's `agent-skills:code-simplify` + `agent-skills:review` steps still run before commit; only the optional PR-only `code-review:code-review` step is skipped. diff --git a/brooks-lint/README.md b/brooks-lint/README.md index fc915a1d..0bb3e696 100644 --- a/brooks-lint/README.md +++ b/brooks-lint/README.md @@ -9,6 +9,10 @@ Consistent. Traceable. Actionable.

+

+ English · 简体中文 +

+

The Six Decay Risks • What It Looks Like • @@ -24,6 +28,14 @@ GitHub Stars

+

+ brooks-lint reviewing code: a /brooks-review command produces a 28/100 health score and cited Symptom → Source → Consequence → Remedy findings +

+ +

+ → Visit the website +

+ --- > *"The bearing of a child takes nine months, no matter how many women are assigned."* diff --git a/brooks-lint/README.zh-CN.md b/brooks-lint/README.zh-CN.md new file mode 100644 index 00000000..39f13039 --- /dev/null +++ b/brooks-lint/README.zh-CN.md @@ -0,0 +1,525 @@ +

+ brooks-lint +

+ +

brooks-lint

+ +

+ 植根于十二本经典工程著作的 AI 代码审查。
+ 一致、可溯源、可落地。 +

+ +

+ English · 简体中文 +

+ +

+ 六类衰退风险 • + 实际效果 • + 基准测试 • + 安装 +

+ +

+ Version + MIT License + Claude Code Plugin + Codex CLI Skill + GitHub Stars +

+ +

+ brooks-lint 审查代码：一条 /brooks-review 命令产出 28/100 健康分以及引用书目的 症状 → 根源 → 后果 → 对策 诊断 +

+ +

+ → 访问官网 +

+ +--- + +> *"一个孩子要十月怀胎，无论派多少人去都一样。"* +> —— Frederick Brooks，《人月神话》（1975） + +**五十年过去，Brooks 依然正确——McConnell、Fowler、Martin、Hunt & Thomas、Evans、Ousterhout、Winters、Meszaros、Osherove、Feathers 以及 Google 测试团队同样如此。** + +大多数代码质量工具只数行数和圈复杂度。**brooks-lint** 更进一步——它对照六个衰退风险维度（综合自十二本经典工程著作）诊断你的代码，每一次都产出带书目出处、严重度标签和具体对策的结构化诊断。 + +完整的"书目—技能"映射（含例外与误报防护），见 +[`skills/_shared/source-coverage.md`](skills/_shared/source-coverage.md)。 + +## 十二本书 + +| 书名 | 作者 | 贡献于 | +|------|--------|----------------| +| *The Mythical Man-Month*（人月神话） | Frederick Brooks | R2、R4、R5 | +| *Code Complete*（代码大全） | Steve McConnell | R1、R4 | +| *Refactoring*（重构） | Martin Fowler | R1、R2、R3、R4、R6 | +| *Clean Architecture*（架构整洁之道） | Robert C. Martin | R2、R5 | +| *The Pragmatic Programmer*（程序员修炼之道） | Hunt & Thomas | R2、R3、R4、R5、T2、T3 | +| *Domain-Driven Design*（领域驱动设计） | Eric Evans | R1、R3、R6 | +| *A Philosophy of Software Design*（软件设计的哲学） | John Ousterhout | R1、R4 | +| *Software Engineering at Google*（Google 软件工程） | Winters, Manshreck & Wright | R2、R5 | +| *The Art of Unit Testing*（单元测试的艺术） | Roy Osherove | T1、T2、T4、T5 | +| *How Google Tests Software*（Google 测试之道） | Whittaker, Arbon & Carollo | T5、T6 | +| *Working Effectively with Legacy Code*（修改代码的艺术） | Michael Feathers | T4、T5、T6 | +| *xUnit Test Patterns*（xUnit 测试模式） | Gerard Meszaros | T1、T2、T3、T4 | + +## 六类衰退风险 + +brooks-lint 从**六类生产代码衰退风险**和**六类测试代码衰退风险**两个角度评估你的代码，这些维度综合自十二本经典工程著作： + +| 衰退风险 | 诊断问题 | 出处 | +|------------|---------------------|---------| +| 🧠 认知过载 | 理解这段代码要花多少脑力？ | Code Complete、Refactoring、DDD、Philosophy of SD | +| 🔗 变更扩散 | 改一处会牵连多少不相干的东西？ | Refactoring、Clean Architecture、Pragmatic、SE@Google | +| 📋 知识重复 | 同一个决策是否在多处被表达？ | Pragmatic、Refactoring、DDD | +| 🌀 偶发复杂度 | 代码是否比问题本身更复杂？ | Refactoring、Code Complete、Brooks、Philosophy of SD | +| 🏗️ 依赖失序 | 依赖是否朝一致的方向流动？ | Clean Architecture、Brooks、Pragmatic、SE@Google | +| 🗺️ 领域模型失真 | 代码是否忠实地表达了业务领域？ | DDD、Refactoring | + +> Philosophy of SD = *A Philosophy of Software Design*（Ousterhout） · SE@Google = *Software Engineering at Google*（Winters 等） + +## 实际效果 + +给定这段代码： + +```python +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: # 永远为 False —— 隐性 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 产出： + +--- + +**健康分：28/100** + +*这个方法把四个不相干的业务职责塞进同一个函数，含有一个会静默吞掉"邮箱变更通知"的逻辑 bug，并且对 SQL 注入门户大开。* + +### 🔴 变更扩散 —— 单个方法因四个不相干的业务原因而改动 +**症状：** `update_profile` 在同一个方法体里完成资料字段更新、邮箱变更通知、积分重算和缓存失效。 +**根源：** Fowler — *Refactoring* — 发散式变更（Divergent Change）；Hunt & Thomas — *The Pragmatic Programmer* — 正交性（Orthogonality） +**后果：** 任何对积分公式的改动都可能破坏邮件通知，反之亦然。每次修改都同时背负着四个不相干领域的回归风险。 +**对策：** 抽出 `NotificationService`、`LoyaltyService` 和 `UserCacheInvalidator`。`UserService.update_profile` 应只做编排、逐一调用它们——本身不持有任何实现逻辑。 + +### 🔴 领域模型失真 —— 隐性逻辑 bug：邮箱通知永不触发 +**症状：** `user['email'] = email` 在 `if user['email'] != email` 之前就覆盖了旧值——条件恒为 `False`，通知是死代码。 +**根源：** McConnell — *Code Complete* — 第 17 章：非常规控制结构 +**后果：** 用户改邮箱时永远收不到通知。这是静默的数据完整性失效——系统看似正常运转，实则违反了业务规则。 +**对策：** 在任何修改之前先捕获 `old_email = user['email']`，拿它（而非 `user['email']`）做比较。 + +*（另有 6 条诊断，含 SQL 注入、依赖失序、魔法数字）* + +### 带依赖图的架构审查 + +在模式 2（架构审查）中，brooks-lint 会在报告顶部生成一张 **Mermaid 依赖图**。模块按严重度着色：红=Critical，黄=Warning，绿=干净。 + +```mermaid +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 +``` + +该图在 GitHub、Notion 等 Markdown 环境中原生渲染——无需额外工具。 + +## 更多示例 + +[完整画廊](docs/gallery.md) 收录了 brooks-lint 在 Python、TypeScript、Go、Java 上的真实输出——涵盖 PR 审查、带 Mermaid 依赖图的架构审查、技术债评估和测试质量审查。 + +--- + +## 基准测试 + +在 3 个真实场景（PR 审查、架构审查、技术债评估）上测试： + +| 评估项 | brooks-lint | 仅用 Claude | +|-----------|:-----------:|:------------:| +| 结构化诊断（症状 → 根源 → 后果 → 对策） | ✅ 100% | ❌ 0% | +| 每条诊断带书目出处 | ✅ 100% | ❌ 0% | +| 严重度标签（🔴/🟡/🟢） | ✅ 100% | ❌ 0% | +| 健康分（0–100） | ✅ 100% | ❌ 0% | +| 识别"变更扩散" | ✅ 100% | ✅ 100% | +| **整体通过率** | **94%** | **16%** | + +差距不在于 Claude *能不能*发现问题——而在于它能否*每一次都稳定地*发现，并附上可溯源的证据和可落地的对策。 + +## 横向对比 + +| | brooks-lint | ESLint / Pylint | GitHub Copilot Review | 原生 Claude | +|---|:---:|:---:|:---:|:---:| +| 检测语法与风格问题 | — | ✅ | ✅ | ~ | +| 结构化诊断链 | ✅ | ❌ | ❌ | ❌ | +| 将诊断溯源到经典著作 | ✅ | ❌ | ❌ | ❌ | +| 一致的严重度标签 | ✅ | ✅ | ~ | ❌ | +| 架构层面的洞察 | ✅ | ❌ | ~ | ~ | +| 领域模型分析 | ✅ | ❌ | ❌ | ~ | +| 零配置、无需安装插件 | ✅ | ❌ | ✅ | ✅ | +| 适用于任何语言 | ✅ | ❌ | ✅ | ✅ | + +> `~` = 偶尔 / 不稳定 + +**brooks-lint 不是要取代你的 linter。** 它捕捉的是 linter 抓不到的东西：架构漂移、知识孤岛、领域模型失真——这些问题往往在无人察觉的几个月里持续拖慢团队。 + +## 安装 + +### Claude Code（推荐） + +#### 通过插件市场 +```bash +/plugin marketplace add hyhmrright/brooks-lint +/plugin install brooks-lint@brooks-lint-marketplace +``` + +短命令（`/brooks-review`）会在首次会话启动时自动安装。手动安装： +```bash +cp commands/*.md ~/.claude/commands/ +``` + +#### 手动安装 +```bash +mkdir -p ~/.claude/skills/brooks-lint +cp -r skills/* ~/.claude/skills/brooks-lint/ +``` + +### Gemini CLI + +#### 通过扩展 +```bash +/extensions install https://github.com/hyhmrright/brooks-lint +``` + +#### 手动安装 +```bash +mkdir -p ~/.gemini/skills/brooks-lint +cp -r skills/* ~/.gemini/skills/brooks-lint/ +``` + +### Codex CLI + +#### 通过技能安装器（在 Codex 会话中） +``` +Install the brooks-lint skill from hyhmrright/brooks-lint +``` + +#### 命令行 +```bash +python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \ + --repo hyhmrright/brooks-lint --path skills --name brooks-lint +``` + +#### 手动安装 +```bash +git clone https://github.com/hyhmrright/brooks-lint.git /tmp/brooks-lint +mkdir -p ~/.codex/skills/brooks-lint +cp -r /tmp/brooks-lint/skills/* ~/.codex/skills/brooks-lint/ +``` + +## 斜杠命令 + +### Claude Code +| 命令 | 短命令 | 作用 | +|---------|------------|--------| +| `/brooks-lint:brooks-review` | `/brooks-review` | PR 级代码审查 | +| `/brooks-lint:brooks-audit` | `/brooks-audit` | 完整架构审查 | +| `/brooks-lint:brooks-debt` | `/brooks-debt` | 技术债评估 | +| `/brooks-lint:brooks-test` | `/brooks-test` | 测试套件健康审查 | +| `/brooks-lint:brooks-health` | `/brooks-health` | 健康仪表盘——全部四个维度 | +| `/brooks-lint:brooks-sweep` | `/brooks-sweep` | 全面扫描——分析所有维度并自动修复 | + +> 短命令由 session-start 钩子在首次会话启动时自动安装。 + +### Gemini CLI +| 命令 | 作用 | +|---------|--------| +| `/brooks-review` | PR 级代码审查 | +| `/brooks-audit` | 完整架构审查 | +| `/brooks-debt` | 技术债评估 | +| `/brooks-test` | 测试套件健康审查 | +| `/brooks-health` | 健康仪表盘——全部四个维度 | +| `/brooks-sweep` | 全面扫描——分析所有维度并自动修复 | + +### Codex CLI + +| 命令 | 作用 | +|---------|--------| +| `$brooks-review` | PR 级代码审查 | +| `$brooks-audit` | 完整架构审查 | +| `$brooks-debt` | 技术债评估 | +| `$brooks-test` | 测试套件健康审查 | +| `$brooks-health` | 健康仪表盘——全部四个维度 | +| `$brooks-sweep` | 全面扫描——分析所有维度并自动修复 | + +当你讨论代码质量、架构、可维护性或测试健康时，这些技能也会自动触发。 + +## 使用 + +### PR 审查 + +``` +/brooks-review # Claude Code（短命令）/ Gemini CLI +/brooks-lint:brooks-review # Claude Code（完整形式） +$brooks-review # Codex CLI +``` + +粘贴一段 diff，或让 AI 指向改动的文件。它会以 症状 → 根源 → 后果 → 对策 的格式，逐一诊断六类衰退风险并给出具体诊断。 + +### 架构审查 + +``` +/brooks-audit # Claude Code（短命令）/ Gemini CLI +/brooks-lint:brooks-audit # Claude Code（完整形式） +$brooks-audit # Codex CLI +``` + +描述你的项目结构或分享关键文件。它会梳理模块依赖、识别循环依赖，并检查是否符合康威定律。 + +### 技术债评估 + +``` +/brooks-debt # Claude Code（短命令）/ Gemini CLI +/brooks-lint:brooks-debt # Claude Code（完整形式） +$brooks-debt # Codex CLI +``` + +按六类衰退风险对技术债分类，以 痛感 × 扩散面 为每条诊断打优先级，产出带 Critical / Scheduled / Monitored 分级的偿还路线图。 + +### 测试质量审查 + +``` +/brooks-test # Claude Code（短命令）/ Gemini CLI +/brooks-lint:brooks-test # Claude Code（完整形式） +$brooks-test # Codex CLI +``` + +对照六类测试空间衰退风险审查你的测试套件——测试晦涩、测试脆弱、测试重复、Mock 滥用、覆盖率幻觉、架构错配——出处为 xUnit Test Patterns、The Art of Unit Testing、How Google Tests Software 和 Working Effectively with Legacy Code。PR 审查还会自动包含一个轻量的第 7 步快速测试检查（对纯文档或非生产代码 diff 会跳过）。 + +### 健康仪表盘 + +``` +/brooks-health # Claude Code（短命令）/ Gemini CLI +/brooks-lint:brooks-health # Claude Code（完整形式） +$brooks-health # Codex CLI +``` + +对全部四个质量维度做精简扫描，产出加权综合健康分（0–100）。适合发版前、新团队上手时，或任何你想要一份"我们现在怎么样？"全局报告的场景。需要某个维度的深度诊断时，请改用对应的专项技能。 + +### 全面扫描 + +``` +/brooks-sweep # Claude Code（短命令）/ Gemini CLI +/brooks-lint:brooks-sweep # Claude Code（完整形式） +$brooks-sweep # Codex CLI +``` + +一次性扫描全部生产（R1–R6）与测试（T1–T6）衰退风险以及架构，然后施加修复：安全改动立即自动应用，跨文件或触及接口的改动需确认，复杂的架构决策则标记为人工处理项。输出修复日志、健康分变化和遗留项清单。 + +## 配置 + +在项目根目录放一个 `.brooks-lint.yaml` 来定制审查行为： + +```yaml +version: 1 + +disable: + - T5 # 跳过覆盖率指标检查——我们不强制覆盖率 + +severity: + R1: suggestion # 在该领域下调"认知过载"诊断的严重度 + +ignore: + - "**/*.generated.*" + - "**/vendor/**" +``` + +可复制 [`.brooks-lint.example.yaml`](.brooks-lint.example.yaml) 作为起点。 +所有设置均为可选——完全省略该文件即使用默认行为。 + +| 设置 | 说明 | +|---------|-------------| +| `disable` | 要跳过的风险码（`R1`–`R6`、`T1`–`T6`） | +| `severity` | 覆盖严重度等级（`critical` / `warning` / `suggestion`） | +| `ignore` | 要排除的文件 glob 模式 | +| `focus` | 只评估这些风险码（不能与 `disable` 同时使用） | + +--- + +## 为什么是这些书，为什么是现在？ + +在 AI 辅助编程的时代，我们写代码比以往任何时候都更快、更多。但六十年软件工程沉淀下来的洞见并没有改变： + +> *"软件的复杂性是本质属性，而非偶然属性。"* +> —— Frederick Brooks + +AI 能帮你更快地写代码，却无法告诉你正在建造的是大教堂还是焦油坑。**brooks-lint 弥合了这道鸿沟**——它把十二本经典工程著作中来之不易的智慧，带进你现代的开发工作流。 + +这些作者识别出的衰退风险，如今比以往更切题： +- **接入 AI 助手** 并不能修复认知过载或领域模型失真 +- **生成更多代码** 会加剧变更扩散和知识重复 +- **跑得更快** 让偶发复杂度和依赖失序更加危险 + +## 项目结构 + +``` +brooks-lint/ +├── .claude-plugin/ # Claude Code 插件元数据 +├── .codex-plugin/ # Codex CLI 插件元数据 +├── skills/ +│ ├── _shared/ # 共享框架文件 +│ │ ├── common.md # 铁律、项目配置、报告模板、健康分 +│ │ ├── source-coverage.md # 12 本书覆盖矩阵、权衡、误报防护 +│ │ ├── decay-risks.md # 六类衰退风险及症状与书目出处 +│ │ ├── test-decay-risks.md # 六类测试空间衰退风险及书目出处 +│ │ ├── remedy-guide.md # --fix 模式：可落地的对策增强规则 +│ │ └── custom-risks-guide.md # 项目自定义风险码模板 +│ ├── brooks-review/ # 模式 1：PR 审查 +│ │ ├── SKILL.md +│ │ └── pr-review-guide.md +│ ├── brooks-audit/ # 模式 2：架构审查 +│ │ ├── SKILL.md +│ │ └── architecture-guide.md +│ ├── brooks-debt/ # 模式 3：技术债评估 +│ │ ├── SKILL.md +│ │ └── debt-guide.md +│ ├── brooks-test/ # 模式 4：测试质量审查 +│ │ ├── SKILL.md +│ │ └── test-guide.md +│ ├── brooks-health/ # 模式 5：健康仪表盘 +│ │ ├── SKILL.md +│ │ └── health-guide.md +│ └── brooks-sweep/ # 模式 6：全面扫描与自动修复 +│ ├── SKILL.md +│ └── sweep-guide.md +├── hooks/ # SessionStart 钩子 +├── commands/ # 短命令包装（由钩子自动安装） +├── evals/ # 基准测试用例 +│ └── evals.json +└── assets/ + └── logo.svg +``` + +## CI/CD 集成 + +用 GitHub Action 在每个 PR 上自动运行 brooks-lint： + +```yaml +# .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@v4 + with: + fetch-depth: 0 + - uses: hyhmrright/brooks-lint/.github/actions/brooks-lint@main + with: + mode: review + anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} + fail-below: 70 +``` + +完整模板见 [`docs/github-action-example.yml`](docs/github-action-example.yml)。 + +该 Action 会把审查结果作为 PR 评论发布，并可在健康分跌破阈值时让检查失败。若仓库中提交了 `.brooks-lint-history.json`，评论还会包含趋势变化（如 "85 → 82（−3），近 3 次运行"）。 + +**成本：** 每次 PR 运行约 $0.05–0.15，取决于 diff 大小和模型。建议仅在 `pull_request` 事件上运行。 + +## 路线图 + +> **当前状态（v1.0）：** 12 本书地基，6 类生产衰退风险（R1–R6）+ 6 类测试衰退风险（T1–T6），5 个技能——PR 审查、架构审查、技术债、测试质量、健康仪表盘。下方较早的条目记录的是历史里程碑，而非当前功能集。 + +- [x] **v0.2**：插件基础设施（`.claude-plugin/`、钩子、斜杠命令） +- [x] **v0.3**：八个 Brooks 维度、文档完整度评分 +- [x] **v0.4**：六本书框架、衰退风险维度、诊断链、基准套件 +- [x] **v0.5**：测试质量审查（模式 4）——四本测试书、六类测试衰退风险 +- [x] **v0.6**：架构审查中的 Mermaid 依赖图 +- [x] **v0.7**：`.brooks-lint.yaml` 项目配置、模式 2 主动上下文、扩展到 10 本书 +- [x] **v0.8**：带命名空间命令的独立技能架构 +- [x] **v0.9**：步骤校验、自动 diff 范围、`/brooks-health` 仪表盘、趋势追踪、分诊模式、`--fix` 对策、上手报告、GitHub Action +- [x] **v1.0**：评测自动化（`run-evals-live.mjs`）、自定义风险扩展（`Cx` 码） + +想出一份力？现在最有价值的贡献是新的评测用例和更好的衰退风险症状模式。见 [CONTRIBUTING.md](CONTRIBUTING.md)。 + +## 贡献 + +如何新增诊断、改进指南或扩展基准套件，见 [CONTRIBUTING.md](CONTRIBUTING.md)。 + +在你自己的 PR 上跑一遍 `/brooks-review`——我们用正在打造的工具来审查贡献。 + +## 许可证 + +MIT License——详见 [LICENSE](LICENSE)。 + +## 致谢 + +本项目站在十二位巨人的肩膀上： + +**生产代码框架** +- Frederick P. Brooks Jr. — *The Mythical Man-Month*（1975，纪念版 1995） +- Steve McConnell — *Code Complete*（1993，第 2 版 2004） +- Martin Fowler — *Refactoring*（1999，第 2 版 2018） +- Robert C. Martin — *Clean Architecture*（2017） +- Andrew Hunt & David Thomas — *The Pragmatic Programmer*（1999，20 周年版 2019） +- Eric Evans — *Domain-Driven Design*（2003） +- John Ousterhout — *A Philosophy of Software Design*（2018） +- Titus Winters、Tom Manshreck、Hyrum Wright — *Software Engineering at Google*（2020） + +**测试质量框架** +- Gerard Meszaros — *xUnit Test Patterns*（2007） +- Roy Osherove — *The Art of Unit Testing*（2009，第 3 版 2023） +- Google Engineering — *How Google Tests Software*（2012） +- Michael Feathers — *Working Effectively with Legacy Code*（2004） + +本工具中编码的衰退风险，是我们对他们思想的综合，并应用于现代代码质量评估。 + +--- + +## Star 历史 + +[![Star History Chart](https://api.star-history.com/svg?repos=hyhmrright/brooks-lint&type=Date)](https://star-history.com/#hyhmrright/brooks-lint&Date) + +--- + +

+ ⭐ 如果这个工具让你以不同的眼光看待自己的代码库，请给它点个 star！ +

diff --git a/brooks-lint/SOURCE.md b/brooks-lint/SOURCE.md index f9f38081..30ccb860 100644 --- a/brooks-lint/SOURCE.md +++ b/brooks-lint/SOURCE.md @@ -1,8 +1,8 @@ # Source - Repo: https://github.com/hyhmrright/brooks-lint -- Ref: 247b3fdab97fcb826a13b1e688ecbe9261f318ad +- Ref: 703449555a7745df501299b280fe0c6eb991bfae - Remove-Paths: -- Snapshot: 2026-05-29 +- Snapshot: 2026-06-01 - Sync-Mode: copy_skill_dirs - Notes: vendored into playbook branch thirdparty/skill diff --git a/brooks-lint/assets/demo.gif b/brooks-lint/assets/demo.gif new file mode 100644 index 00000000..7bc6c46b Binary files /dev/null and b/brooks-lint/assets/demo.gif differ diff --git a/brooks-lint/assets/demo.src.html b/brooks-lint/assets/demo.src.html new file mode 100644 index 00000000..4a825d97 --- /dev/null +++ b/brooks-lint/assets/demo.src.html @@ -0,0 +1,104 @@ + + + + + + + + +
+
+ + claude code — brooks-lint +
+
+
›
+
⠋ Reviewing UserService.update_profile against R1–R6…
+
+
28 / 100 Health Score— 4 responsibilities, a silent bug, SQL injection
+ +
+

🔴 R2 — Change Propagation

+
Symptom: one method does updates, email, loyalty & cache.
+
Remedy: extract Notification / Loyalty / CacheInvalidator.
+
+
+

🔴 R6 — Domain Model Distortion

+
Symptom: email overwritten before the != check — dead branch.
+
Source: McConnell — Code Complete — Ch. 17.
+
+
+

🔴 R5 — Dependency Disorder + SQL injection ×2

+
Remedy: parameterise queries; invert the db dependency.
+
+
+ 5 more findings · every one cited to a book
+ +
+
+
+ + + + diff --git a/brooks-lint/assets/hero.png b/brooks-lint/assets/hero.png new file mode 100644 index 00000000..47d71f72 Binary files /dev/null and b/brooks-lint/assets/hero.png differ diff --git a/brooks-lint/assets/hero.src.html b/brooks-lint/assets/hero.src.html new file mode 100644 index 00000000..e5393900 --- /dev/null +++ b/brooks-lint/assets/hero.src.html @@ -0,0 +1,102 @@ + + + + + + + + +
+
+ + brooks-lint + grounded in 12 classic engineering books +
+
+
+
Your code
+
class UserService: + def update_profile(self, user_id, name, email, avatar): + user = self.db.query(f"SELECT * FROM users WHERE id = {user_id}") + user['email'] = email + # ... + if user['email'] != email: # always False + self.smtp.send(...) + points = user['login_count'] * 10 + 500 + self.db.execute(f"UPDATE loyalty SET points={points} ...") + self.cache.invalidate(f"user:{user_id}")
+
+
→
+
+
brooks-lint verdict
+
+
28/ 100  Health Score
+
+

🔴 R2 — Change Propagation

+
Symptom: one method does updates, email, loyalty & cache.
+
Source: Fowler — Refactoring — Divergent Change
+
Remedy: extract Notification / Loyalty / CacheInvalidator.
+
+
+

🔴 R6 — Domain Model Distortion

+
Symptom: email overwritten before the != check — dead branch.
+
Source: McConnell — Code Complete — Ch.17
+
Remedy: capture old_email before any mutation.
+
+
+

🔴 R5 — Dependency Disorder + SQL injection ×2

+
+
+
+
+
Every finding: Symptom → Source → Consequence → Remedy
+
+ + diff --git a/brooks-lint/docs/.nojekyll b/brooks-lint/docs/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/brooks-lint/docs/demo.gif b/brooks-lint/docs/demo.gif new file mode 100644 index 00000000..7bc6c46b Binary files /dev/null and b/brooks-lint/docs/demo.gif differ diff --git a/brooks-lint/docs/gallery.html b/brooks-lint/docs/gallery.html new file mode 100644 index 00000000..8152f7cd --- /dev/null +++ b/brooks-lint/docs/gallery.html @@ -0,0 +1,495 @@ + + + + + +Gallery — brooks-lint + + + + + + + + + + + + +
+
+

The Gallery

+

Real diagnostic output from brooks-lint — generated by running the skill, then lightly abridged. Four languages, four review modes, every finding in the Iron Law form.

+
+ 8 worked examples + 4 review modes + 4 languages + Python · TypeScript · Go · Java +
+
+
+ +
+
+ + + + + +
+
+ +
+ + +
+

PR Review Mode 1

+

Diagnoses a diff against the six production decay risks (R1–R6).

+ +
+
+ TypeScript +

Seven-service payment processor

+ 55 / 100 +
+

A single method orchestrates seven services, creating a structural coupling trap where any change to payment, fraud, inventory, or notification touches the same method.

+
+ ▸ Input code +
class PaymentProcessor {
+  constructor(
+    private db, private stripe, private mailer, private inventory,
+    private analytics, private taxCalc, private fraudDetection
+  ) {}
+
+  async processPayment(orderId, cardToken) {
+    const order = await this.db.orders.findById(orderId);
+    const tax = this.taxCalc.calculate(order.items, order.shippingAddress.state);
+    order.tax = tax;
+    const fraudScore = await this.fraudDetection.evaluate({ amount: order.total + tax, card: cardToken, ... });
+    if (fraudScore > 0.8) { await this.mailer.send(...); await this.analytics.track('fraud_hold', ...); return {...}; }
+    const charge = await this.stripe.charges.create({ amount: Math.round((order.total + tax) * 100), ... });
+    for (const item of order.items) {
+      await this.inventory.decrement(item.sku, item.quantity);
+      if (await this.inventory.getStock(item.sku) < 10) { await this.mailer.send('warehouse@company.com', ...); }
+    }
+    order.status = 'paid'; order.chargeId = charge.id; await this.db.orders.save(order);
+    await this.mailer.send(order.customerEmail, 'Payment Received', `Charge: $${order.total + tax}`);
+    await this.analytics.track('payment_success', { orderId, amount: order.total + tax });
+    return { status: 'paid', chargeId: charge.id };
+  }
+}
+
+
+

🔴 Change Propagation — Seven-service constructor signals a God Class

+
Symptom: One class injects seven dependencies; one method orchestrates all of them.
+
Source: Fowler — Refactoring — Divergent Change; Martin — Clean Architecture — SRP
+
Remedy: Decompose into FraudCheckService, InventoryDeductionService, PaymentNotifier — inject 3, not 7.
+
+
+

🔴 Change Propagation — Inventory loop embeds warehouse notification policy

+
Symptom: A low-stock check (< 10) fires a warehouse email with hardcoded recipient inside the payment loop.
+
Source: Fowler — Refactoring — Shotgun Surgery; Hunt & Thomas — Orthogonality
+
Remedy: Publish a StockLevelChanged domain event a separate notifier subscribes to.
+
+
+

🟡 Knowledge Duplication — order.total + tax computed three times

+
Symptom: The same expression appears on three lines with no shared name.
+
Source: Hunt & Thomas — DRY; Fowler — Refactoring — Duplicate Code
+
Remedy: Expose a computed order.grandTotal.
+
+
+

🟡 Domain Model Distortion — Order is a mutable data bag

+
Symptom: order.tax, order.status, order.chargeId are all set externally; the object holds no behaviour.
+
Remedy: Give Order state-transition methods: order.recordPayment(chargeId).
+
+
+
+ + +
+

Architecture Audit Mode 2

+

Maps module dependencies, renders a colour-coded graph, and flags layering and cycle violations.

+ +
+
+ TypeScript +

Dependency Inversion violation

+ 50 / 100 +
+

Domain entities import infrastructure directly, and a near-cycle forms between Product and PricingService.

+ 
graph TD
+  subgraph API["API Layer"]
+    OrderController; UserController
+  end
+  subgraph Services["Service Layer"]
+    OrderService; PricingService; UserService
+  end
+  subgraph Domain["Domain Layer"]
+    Order; User; Product
+  end
+  subgraph Infra["Infrastructure Layer"]
+    PostgresClient; RedisCache; StripeClient
+  end
+  OrderController --> OrderService
+  UserController --> UserService
+  UserService --> OrderService
+  OrderService --> Order
+  OrderService --> PostgresClient
+  PricingService --> Product
+  PricingService --> StripeClient
+  Order --> PostgresClient
+  User --> RedisCache
+  Product --> PricingService
+  classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
+  classDef warning fill:#ffd43b,stroke:#e67700
+  classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff
+  class Order,User,Product critical
+  class OrderService,PricingService,UserService warning
+  class OrderController,UserController,PostgresClient,RedisCache,StripeClient clean
+
+

🔴 Dependency Disorder — Domain layer directly imports infrastructure

+
Symptom: Order.ts imports PostgresClient; User.ts imports RedisCache.
+
Source: Martin — Clean Architecture — Dependency Inversion Principle
+
Remedy: Define IOrderRepository/IUserRepository in the domain; move infra refs to infra/.
+
+
+

🔴 Dependency Disorder — Product → PricingService (upward dependency)

+
Symptom: Near-cycle PricingService → Product → PricingService.
+
Source: Martin — Clean Architecture — Acyclic Dependencies Principle
+
Remedy: Pass pricing as a value object or define IPricingPolicy in the domain.
+
+
+ +
+
+ Go +

Circular dependency across packages

+ 45 / 100 +
+

auth → user → notification → auth forms a strongly connected component — Go refuses to compile it.

+ 
graph TD
+  subgraph pkg["pkg/"]
+    auth["auth"]; user["user"]; notification["notification"]; billing["billing"]
+  end
+  auth --> user
+  user --> notification
+  notification -.->|circular| auth
+  billing --> user
+  classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
+  classDef warning fill:#ffd43b,stroke:#e67700
+  class auth,user,notification critical
+  class billing warning
+
+

🔴 Dependency Disorder — Circular dependency auth → user → notification → auth

+
Symptom: Three packages form a cycle; none compile, test, or deploy independently.
+
Source: Martin — Clean Architecture — Acyclic Dependencies Principle
+
Remedy: Extract interfaces into pkg/contracts; each package implements the interface its consumer defines.
+
+
+

🟡 Domain Model Distortion — Bounded contexts crossed with no anti-corruption layer

+
Symptom: Identity, profile, and notification contexts import each other with no translation layer.
+
Source: Evans — DDD — Bounded Context; Anti-Corruption Layer
+
Remedy: Define thin adapters at each context boundary.
+
+
+ +
+
+ Java +

Textbook Clean Architecture

+ 98 / 100 +
+

Dependencies flow inward, infra implements domain ports, no cycles. brooks-lint reports clean code as clean — and still offers one forward-looking suggestion.

+ 
graph TD
+  subgraph API["API Layer"]
+    OrderController; UserController
+  end
+  subgraph Application["Application Layer"]
+    OrderService; UserService
+  end
+  subgraph Domain["Domain Layer"]
+    OrderModel["Order"]; UserModel["User"]; OrderRepository["OrderRepository (interface)"]; UserRepository["UserRepository (interface)"]
+  end
+  subgraph Infra["Infrastructure Layer"]
+    JpaOrderRepository; JpaUserRepository
+  end
+  OrderController --> OrderService
+  UserController --> UserService
+  OrderService --> OrderModel
+  OrderService --> OrderRepository
+  UserService --> UserModel
+  UserService --> UserRepository
+  JpaOrderRepository --> OrderRepository
+  JpaUserRepository --> UserRepository
+  classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff
+  class OrderController,UserController,OrderService,UserService,OrderModel,UserModel,OrderRepository,UserRepository,JpaOrderRepository,JpaUserRepository clean
+
+

🟢 Suggestion — Monitor application service growth

+
Symptom: OrderService and UserService are symmetric siblings that may accrue responsibilities without a split policy.
+
Source: Brooks — The Mythical Man-Month — Conceptual Integrity
+
Remedy: Document a "one service per use-case cluster" rule now, before the pattern calcifies.
+
+
+
+ + +
+

Tech Debt Assessment Mode 3

+

Classifies debt across the decay risks and scores each finding by Pain × Spread priority.

+ +
+
+ Java +

Shotgun Surgery across six files

+ 56 / 100 +
+

Adding a currency means editing six files in six unrelated layers — three Critical findings that share one root cause.

+ + + + + + + + +
RiskFindingsAvg PriorityClassification
Change Propagation26.5Mixed (1 Critical + 1 Scheduled)
Knowledge Duplication19.0Critical
Domain Model Distortion19.0Critical
Cognitive Overload16.0Scheduled
+
+

🔴 Change Propagation — Shotgun Surgery across six modules Pain × Spread: 9

+
Symptom: Adding EUR requires editing 6 files in 6 distinct layers with no architectural relationship.
+
Source: Fowler — Refactoring — Shotgun Surgery; Hunt & Thomas — Orthogonality
+
Remedy: Introduce a Money value object and a MoneyFormatter service.
+
+
+

🔴 Knowledge Duplication — $ as a magic literal in five files Pain × Spread: 9

+
Symptom: The string "$" appears in 5 independent locations with no shared constant.
+
Source: Hunt & Thomas — DRY; McConnell — Code Complete — Ch. 12
+
Remedy: Use Currency.getSymbol(Locale) in MoneyFormatter; remove all "$" literals.
+
+
+

🔴 Domain Model Distortion — No Money type exists Pain × Spread: 9

+
Symptom: All price/amount fields are raw double.
+
Source: Evans — DDD — Domain Model; Fowler — Refactoring — Data Class
+
Remedy: Introduce record Money(BigDecimal amount, Currency currency).
+
+
Recommended focus: All three Critical findings share one root cause — the absence of a Money value object. One intervention collapses three findings.
+
+
+ + +
+

Test Quality Review Mode 4

+

Audits an existing suite against six test-space decay risks (T1–T6).

+ +
+
+ TypeScript +

Mock abuse

+ 60 / 100 +
+

Seven mocks per test, 14 lines of setup vs 6 of assertions — the service is never tested against a real collaborator, and the return value is never checked.

+
+ ▸ Input test +
it('should place an order successfully', () => {
+  const mockDb = mock<Database>();
+  const mockPayment = mock<PaymentGateway>();
+  const mockInventory = mock<InventoryService>();
+  const mockMailer = mock<MailService>();
+  const mockAudit = mock<AuditLogger>();
+  const mockCache = mock<CacheService>();
+  const mockMetrics = mock<MetricsCollector>();
+  const service = new OrderService(mockDb, mockPayment, mockInventory, mockMailer, mockAudit, mockCache, mockMetrics);
+  const result = await service.placeOrder('1', 'item-1', 2);
+
+  expect(mockPayment.charge).toHaveBeenCalledWith('ch_1', 2000);
+  expect(mockInventory.check).toHaveBeenCalledWith('item-1', 2);
+  expect(mockMailer.send).toHaveBeenCalled();
+  expect(mockAudit.log).toHaveBeenCalledWith('ORDER_PLACED', expect.anything());
+  expect(mockCache.invalidate).toHaveBeenCalledWith('orders:1');
+  expect(mockMetrics.increment).toHaveBeenCalledWith('orders.placed');
+});
+
+
+

🔴 Mock Abuse — Seven mocks per test; setup dominates logic

+
Symptom: 7 mock objects; 14 lines of setup vs 6 of assertions. No real collaborator is ever exercised.
+
Source: Osherove — The Art of Unit Testing (mock count > 3); Meszaros — xUnit Test Patterns
+
Remedy: Reduce mocks to ≤ 3, use in-memory fakes, assert on result first.
+
+
+

🔴 Mock Abuse — All six assertions verify mock calls, not behaviour

+
Symptom: Every assertion is toHaveBeenCalledWith; result is captured but never asserted.
+
Consequence: A placeOrder that calls every mock yet returns null or double-charges still passes.
+
Remedy: Assert observable output: expect(result.status).toBe('confirmed').
+
+
+ +
+
+ Python +

Inverted test pyramid

+ 55 / 100 +
+

Only 16% of tests are unit tests; an E2E-heavy suite takes ~9 minutes and blocks fast CI feedback.

+
+ ▸ Suite overview +
tests/
+├── e2e/           47 tests, avg 8s each   (~6 min)
+├── integration/   83 tests, avg 2s each   (~3 min)
+└── unit/          24 tests, avg 10ms each (~0.2s)
+
+Total: 154 tests, ~9 min
+Actual  ratio:  Unit 16% : Integration 54% : E2E 30%
+Target  ratio:  Unit 70% : Integration 20% : E2E 10%
+
+
+

🔴 Architecture Mismatch — Fully inverted test pyramid

+
Symptom: Only 24 of 154 tests (16%) are unit tests; E2E + integration = 84%.
+
Source: Google — How Google Tests Software — 70:20:10; Meszaros — xUnit Test Patterns
+
Remedy: Target 70% unit; reduce E2E to 5–8 critical smoke tests.
+
+
+

🔴 Architecture Mismatch — 9-minute suite blocks CI fast-feedback

+
Symptom: Full suite ~542s, dominated by 8s E2E tests.
+
Remedy: Split CI: (1) unit only, < 60s, blocks merge; (2) integration + E2E async, non-blocking.
+
+
+

🟡 Coverage Illusion — Core domain untested at unit level

+
Symptom: tests/unit/ covers only validators and formatters — no checkout, login, order, or payment.
+
Source: Feathers — Working Effectively with Legacy Code
+
Remedy: Start with test_checkout_flow.py and test_payment_api.py.
+
+
+
+ +
+ + + + + + + diff --git a/brooks-lint/docs/hero.png b/brooks-lint/docs/hero.png new file mode 100644 index 00000000..47d71f72 Binary files /dev/null and b/brooks-lint/docs/hero.png differ diff --git a/brooks-lint/docs/index.html b/brooks-lint/docs/index.html new file mode 100644 index 00000000..3f7b3035 --- /dev/null +++ b/brooks-lint/docs/index.html @@ -0,0 +1,549 @@ + + + + + + +brooks-lint — AI code reviews grounded in twelve classic engineering books + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+ Claude Code · Codex · Gemini plugin +

AI code reviews grounded in twelve classic engineering books

+

+ Most tools count lines and complexity. brooks-lint diagnoses your code against twelve decay risks synthesized from the classics — every finding cited, scored, and remedied. +

+
+ “The bearing of a child takes nine months, no matter how many women are assigned.” + — Frederick Brooks, The Mythical Man-Month (1975) +
+
+ Get Started + View on GitHub +
+ +
+ brooks-lint reviewing code: a /brooks-review command produces a 28/100 health score and cited Symptom → Source → Consequence → Remedy findings +
+ +
+
12classic books
+
12decay risks (R1–R6 · T1–T6)
+
94%benchmark pass rate
+
6independent skills
+
+
+
+ + +
+
+
+

Not a linter. A second opinion from the canon.

+

Linters catch syntax. brooks-lint catches architectural drift, knowledge silos, and domain distortion — the slow problems that cost teams months.

+
+
+
+ ⚖️ +

The Iron Law

+

Every finding follows one shape: Symptom → Source → Consequence → Remedy. No vague vibes, ever.

+
+
+ 📚 +

Cited to the books

+

Brooks, Fowler, Martin, Ousterhout, Evans, Feathers, Meszaros and more — each finding names the author and principle.

+
+
+ 🎯 +

Six focused skills

+

PR Review, Architecture Audit, Tech Debt, Test Quality, Health Dashboard, and a Full Sweep that auto-fixes.

+
+
+ 🔌 +

Zero config, any language

+

Works in Claude Code, Codex CLI, and Gemini CLI. No plugins to wire up, no language limits.

+
+
+
+
+ + +
+
+
+

The Six Production Decay Risks

+

Synthesized from the twelve books. Six more (T1–T6) cover test-suite decay.

+
+
+
+ R1 +

🧠 Cognitive Overload

+

How much mental effort does it take to understand this?

+
Code Complete · Refactoring · DDD · Philosophy of SD
+
+
+ R2 +

🔗 Change Propagation

+

How many unrelated things break on one change?

+
Refactoring · Clean Architecture · Pragmatic · SE@Google
+
+
+ R3 +

📋 Knowledge Duplication

+

Is the same decision expressed in multiple places?

+
Pragmatic · Refactoring · DDD
+
+
+ R4 +

🌀 Accidental Complexity

+

Is the code more complex than the problem itself?

+
Refactoring · Code Complete · Brooks · Philosophy of SD
+
+
+ R5 +

🏗️ Dependency Disorder

+

Do dependencies flow in a consistent direction?

+
Clean Architecture · Brooks · Pragmatic · SE@Google
+
+
+ R6 +

🗺️ Domain Model Distortion

+

Does the code faithfully represent the domain?

+
DDD · Refactoring
+
+
+
+
+ + +
+
+
+

What a finding looks like

+

Same messy method, two of the eight findings brooks-lint produces — each one cited and actionable.

+
+
+
Health Score: 28/100
+
+ This method concentrates four unrelated business responsibilities, hides a logic bug that silently suppresses email notifications, and is wide open to SQL injection. +
+ +
+

🔴 R2 — One method changes for four unrelated reasons

+
Symptom: + update_profile does field updates, email notifications, loyalty recalculation, and cache invalidation in one body.
+
Source: + Fowler — Refactoring — Divergent Change; Hunt & Thomas — Orthogonality
+
Consequence: + A change to the loyalty formula risks breaking email notifications. Every edit carries regression risk across four domains.
+
Remedy: + Extract NotificationService, LoyaltyService, UserCacheInvalidator. update_profile should orchestrate, not implement.
+
+ +
+

🔴 R6 — Silent logic bug: notification never fires

+
Symptom: + user['email'] = email runs before if user['email'] != email — the condition is always False, the code is dead.
+
Source: + McConnell — Code Complete — Ch. 17: Unusual Control Structures
+
Consequence: + Users are never notified when their email changes. A business rule is silently violated while the system looks fine.
+
Remedy: + Capture old_email before any mutation. Compare against old_email, not the already-overwritten value.
+
+
+
+
+ + +
+
+
+

Consistency is the point

+

Tested across PR review, architecture audit, and tech debt scenarios. The gap isn't what Claude can find — it's what it finds every single time, with evidence.

+
+
+ + + + + + + + + + + + + + + +
Criterionbrooks-lintClaude alone
Structured Symptom→Source→Consequence→Remedy100%0%
Book citation per finding100%0%
Consistent severity labels 🔴🟡🟢100%0%
Health Score (0–100)100%0%
Overall pass rate94%16%
+
+
+
+ + +
+
+
+

Standing on twelve giants

+

The decay risks are our synthesis of their ideas, applied to modern code quality.

+
+
+ The Mythical Man-Month · Brooks + Code Complete · McConnell + Refactoring · Fowler + Clean Architecture · Martin + The Pragmatic Programmer · Hunt & Thomas + Domain-Driven Design · Evans + A Philosophy of Software Design · Ousterhout + Software Engineering at Google · Winters et al. + The Art of Unit Testing · Osherove + How Google Tests Software · Whittaker et al. + Working Effectively with Legacy Code · Feathers + xUnit Test Patterns · Meszaros +
+
+
+ + +
+
+
+

Get started in seconds

+

Pick your tool. Then just ask it to review your code, audit your architecture, or assess tech debt.

+
+
+
Claude Code
+
+# add the marketplace, then install +/plugin marketplace add hyhmrright/brooks-lint +/plugin install brooks-lint@brooks-lint-marketplace
+ +
Gemini CLI
+
+/extensions install https://github.com/hyhmrright/brooks-lint
+ +
Codex CLI
+
+# just say this in a Codex session +Install the brooks-lint skill from hyhmrright/brooks-lint
+ +
Then, in any session:
+
+/brooks-review # or /brooks-audit · /brooks-debt · /brooks-test · /brooks-health · /brooks-sweep
+
+ +
+
+ +
+ + + + + + diff --git a/brooks-lint/docs/logo.svg b/brooks-lint/docs/logo.svg new file mode 100644 index 00000000..772eac17 --- /dev/null +++ b/brooks-lint/docs/logo.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + diff --git a/brooks-lint/docs/robots.txt b/brooks-lint/docs/robots.txt new file mode 100644 index 00000000..d3273ffc --- /dev/null +++ b/brooks-lint/docs/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://hyhmrright.github.io/brooks-lint/sitemap.xml diff --git a/brooks-lint/docs/sitemap.xml b/brooks-lint/docs/sitemap.xml new file mode 100644 index 00000000..5b2cc135 --- /dev/null +++ b/brooks-lint/docs/sitemap.xml @@ -0,0 +1,13 @@ + + + + https://hyhmrright.github.io/brooks-lint/ + weekly + 1.0 + + + https://hyhmrright.github.io/brooks-lint/gallery.html + monthly + 0.8 + +