⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
brooks-harness
>
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
"The bearing of a child takes nine months, no matter how many women are assigned." — Frederick Brooks, The Mythical Man-Month (1975)
50 years later, Brooks was still right — and so were McConnell, Fowler, Martin, Hunt & Thomas, Evans, Ousterhout, Winters, Meszaros, Osherove, Feathers, and the Google Testing team.
Most code quality tools count lines and cyclomatic complexity. brooks-lint goes deeper — it diagnoses your code against six decay risk dimensions synthesized from twelve classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.
For the full source-to-skill mapping, including exceptions and false-positive guards, see
skills/_shared/source-coverage.md.
Quick Start
# Claude Code
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace
# Any other Agent Skills platform — Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · Bob …
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>
Then just ask ("review this PR", "audit the architecture"), or run one of the six commands —
/brooks-review, /brooks-audit, /brooks-debt, /brooks-test, /brooks-health, /brooks-sweep
(what each one does).
Every finding comes back as Symptom → Source → Consequence → Remedy with a book citation and a 0–100 Health Score. Full install options (10 more platforms) and CI/CD setup are below.
The Twelve Books
| Book | Author | Contributes to |
|---|---|---|
| The Mythical Man-Month (1975) | Frederick P. Brooks Jr. | R2, R4, R5 |
| Code Complete (1993, 2nd ed. 2004) | Steve McConnell | R1, R4 |
| Refactoring (1999, 2nd ed. 2018) | Martin Fowler | R1, R2, R3, R4, R6 |
| Clean Architecture (2017) | Robert C. Martin | R2, R5 |
| The Pragmatic Programmer (1999, 20th Anniv. 2019) | Andrew Hunt & David Thomas | R2, R3, R4, R5, T2, T3 |
| Domain-Driven Design (2003) | Eric Evans | R1, R3, R6 |
| A Philosophy of Software Design (2018) | John Ousterhout | R1, R4 |
| Software Engineering at Google (2020) | Winters, Manshreck & Wright | R2, R5 |
| The Art of Unit Testing (2009, 3rd ed. 2023) | Roy Osherove | T1, T2, T4, T5 |
| How Google Tests Software (2012) | Whittaker, Arbon & Carollo | T5, T6 |
| Working Effectively with Legacy Code (2004) | Michael Feathers | T4, T5, T6 |
| xUnit Test Patterns (2007) | Gerard Meszaros | T1, T2, T3, T4 |
The Six Decay Risks
brooks-lint evaluates your code across six production-code decay risks and six test-suite decay risks synthesized from twelve classic engineering books:
| Decay Risk | Diagnostic Question | Sources |
|---|---|---|
| 🧠 Cognitive Overload | How much mental effort to understand this? | Code Complete, Refactoring, DDD, Philosophy of SD |
| 🔗 Change Propagation | How many unrelated things break on one change? | Refactoring, Clean Architecture, Pragmatic, SE@Google |
| 📋 Knowledge Duplication | Is the same decision expressed in multiple places? | Pragmatic, Refactoring, DDD |
| 🌀 Accidental Complexity | Is the code more complex than the problem? | Refactoring, Code Complete, Brooks, Philosophy of SD |
| 🏗️ Dependency Disorder | Do dependencies flow in a consistent direction? | Clean Architecture, Brooks, Pragmatic, SE@Google |
| 🗺️ Domain Model Distortion | Does the code faithfully represent the domain? | DDD, Refactoring |
Philosophy of SD = A Philosophy of Software Design (Ousterhout) · SE@Google = Software Engineering at Google (Winters et al.)
What It Looks Like
Given this code:
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: # always False — silent 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 produces:
Health Score: 28/100
This method concentrates four unrelated business responsibilities into a single function, contains a logic bug that silently suppresses email change notifications, and is wide open to SQL injection.
🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons
Symptom: update_profile performs profile field updates, email change notifications, loyalty points recalculation, and cache invalidation all in one method body.
Source: Fowler — Refactoring — Divergent Change; Hunt & Thomas — The Pragmatic Programmer — Orthogonality
Consequence: Any change to the loyalty formula risks breaking email notifications and vice versa. Every edit carries regression risk across four unrelated domains simultaneously.
Remedy: Extract NotificationService, LoyaltyService, and UserCacheInvalidator. UserService.update_profile should orchestrate by calling each — it should hold no implementation logic itself.
🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires
Symptom: user['email'] = email overwrites the old value before if user['email'] != email — the condition is always False. The notification is dead code.
Source: McConnell — Code Complete — Ch. 17: Unusual Control Structures
Consequence: Users are never notified when their email address changes. Silent data integrity failure — the system appears functional while violating a business rule.
Remedy: Capture old_email = user['email'] before any mutation. Compare against old_email, not user['email'].
*(+ 6 more findings including SQL injectio
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.claude/skills/brooks-harness/SKILL.md7.2 KBupstream ↗
--- 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 + all README translations + 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, 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.** 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.README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/hyhmrright-brooks-lint-claude-skills-brooks-harness.md