⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.9.1

brooks-harness

hyhmrright@hyhmrright⭐ 1.6k stars· last commit 6d ago· 0 open issues

>

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 1.6k on GitHubGitHub ↗

Very popular

🟢ProSkills Score
—
📍

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

BookAuthorContributes to
The Mythical Man-Month (1975)Frederick P. Brooks Jr.R2, R4, R5
Code Complete (1993, 2nd ed. 2004)Steve McConnellR1, R4
Refactoring (1999, 2nd ed. 2018)Martin FowlerR1, R2, R3, R4, R6
Clean Architecture (2017)Robert C. MartinR2, R5
The Pragmatic Programmer (1999, 20th Anniv. 2019)Andrew Hunt & David ThomasR2, R3, R4, R5, T2, T3
Domain-Driven Design (2003)Eric EvansR1, R3, R6
A Philosophy of Software Design (2018)John OusterhoutR1, R4
Software Engineering at Google (2020)Winters, Manshreck & WrightR2, R5
The Art of Unit Testing (2009, 3rd ed. 2023)Roy OsheroveT1, T2, T4, T5
How Google Tests Software (2012)Whittaker, Arbon & CarolloT5, T6
Working Effectively with Legacy Code (2004)Michael FeathersT4, T5, T6
xUnit Test Patterns (2007)Gerard MeszarosT1, 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 RiskDiagnostic QuestionSources
🧠 Cognitive OverloadHow much mental effort to understand this?Code Complete, Refactoring, DDD, Philosophy of SD
🔗 Change PropagationHow many unrelated things break on one change?Refactoring, Clean Architecture, Pragmatic, SE@Google
📋 Knowledge DuplicationIs the same decision expressed in multiple places?Pragmatic, Refactoring, DDD
🌀 Accidental ComplexityIs the code more complex than the problem?Refactoring, Code Complete, Brooks, Philosophy of SD
🏗️ Dependency DisorderDo dependencies flow in a consistent direction?Clean Architecture, Brooks, Pragmatic, SE@Google
🗺️ Domain Model DistortionDoes 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

// REPO STATS

1.6k stars
0 open issues
Last commit: 6d ago