# brooks-harness

Adopt this skill: https://proskills.md/skills/other/hyhmrright-brooks-lint-claude-skills-brooks-harness

Page: https://proskills.md/skills/other/hyhmrright-brooks-lint-claude-skills-brooks-harness
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/brooks-harness/SKILL.md
size: 7369
upstream: https://github.com/hyhmrright/brooks-lint/blob/main/.claude/skills/brooks-harness/SKILL.md

````text
---
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.
````

## File: README.md
upstream: https://github.com/hyhmrright/brooks-lint/blob/main/README.md

````text
<p align="center">
  <img src="assets/logo.svg" alt="brooks-lint" width="200">
</p>

<h1 align="center">brooks-lint</h1>

<p align="center">
  <strong>AI code reviews grounded in twelve classic engineering books.<br>
  Consistent. Traceable. Actionable.</strong>
</p>

<p align="center">
  <strong>English</strong> ·
  <a href="README.zh-CN.md">简体中文</a> ·
  <a href="README.zh-TW.md">繁體中文</a> ·
  <a href="README.ja.md">日本語</a> ·
  <a href="README.ko.md">한국어</a> ·
  <a href="README.es.md">Español</a>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#the-six-decay-risks">The Six Decay Risks</a> •
  <a href="#what-it-looks-like">What It Looks Like</a> •
  <a href="#benchmark">Benchmark</a> •
  <a href="#installation">Installation</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-1.9.1-blue.svg" alt="Version">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
  <img src="https://img.shields.io/badge/Claude_Code-Plugin-blueviolet.svg" alt="Claude Code Plugin">
  <img src="https://img.shields.io/badge/Codex_CLI-Skill-orange.svg" alt="Codex CLI Skill">
  <img src="https://img.shields.io/github/stars/hyhmrright/brooks-lint?style=social" alt="GitHub Stars">
</p>

<p align="center">
  <a href="https://trendshift.io/repositories/47738" target="_blank"><img src="https://trendshift.io/api/badge/trendshift/repositories/47738/daily?language=JavaScript" alt="#2 JavaScript Repository of the Day | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>

<p align="center">
  <img src="assets/banner-en.svg" alt="Your code → 12 classics → 12 decay risks → cited findings" width="900">
</p>

<p align="center">
  <a href="https://hyhmrright.github.io/brooks-lint/"><img src="assets/demo.gif" alt="brooks-lint reviewing code: a /brooks-review command produces a 28/100 health score and cited Symptom → Source → Consequence → Remedy findings" width="820"></a>
</p>

<p align="center">
  <strong><a href="https://hyhmrright.github.io/brooks-lint/">→ Visit the website</a></strong>
</p>

---

> *"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`](skills/_shared/source-coverage.md).

## Quick Start

```bash
# 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](#slash-commands)).

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](#installation).

## 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:

```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:   # 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
````
