agentleFS
unlockers-aiunlockers-ai/unlockers-skills-library/skills/quality-gate/SKILL.md

quality-gate

Skill4 starsChanged 3 months agoMITView on GitHub

An objective, threshold-based backstop for when review nudges fail to land — blocks on over-long files and functions, too many parameters, high complexity, magic numbers, oversized classes. Wire it as a final CI stage, a Claude Code Stop hook, or both.

45 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use deploy.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • VercelSkill

    deploy

    Deploy applications to Vercel. Use when the user says "deploy", "deploy to Vercel", "push to production", "deploy my app", or "go live".

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 36 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add a config for any other language using the same limits, and teach hooks/check-quality.sh to run its linter.

    line 50
  2. Distinctive:

    Run the script as the last stage of the pipeline, after tests, lint and any automated review.

    line 61
  3. Very specific:

    Start it non-blocking (allow_failure: true, or the equivalent) on an existing codebase.

    line 71
  4. Distinctive:

    If the script finds violations it exits 2, which blocks the agent and feeds the violation list back so it must fix them before finishing.

    line 91
  5. Distinctive:

    Ensure the linters are installed in your environment.

    line 102

“Common” is measured: kept by at least 6 in 10 of the 36 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Quality Gate

A small set of objective, language-agnostic thresholds, enforced mechanically.

Why this exists

Everything else in this library nudges. The reviewers report findings and hope someone acts on them; refactor improves what it is pointed at. Nudges work most of the time, which is the problem — the failures are invisible. A class grows by twenty lines a month. Each individual diff is reasonable and each review is right to pass it. Nobody is ever wrong, and after a year the class is unmaintainable.

This gate is the backstop for that case. It does not read the diff, it reads the code as it now stands, so it catches accumulated drift rather than the increment that caused it. When it fires, the finding is usually old: the file crossed the threshold months ago and every review since has looked only at the change in front of it.

That makes it deliberately blunt. It has no judgment and no view of intent — that is the point. Thresholds are arguable in any single case and useful precisely because they do not argue back. Run it last, after the reviewers, as the thing that catches what their nudges did not.

A firing gate is a signal about the review loop as much as about the code. If the same file trips it every release, the reviewers have been raising it and it has not been getting fixed; that is worth a conversation, not just a refactor.

Three wirings are provided — use whichever fit.

The Thresholds (language-agnostic)

MetricLimit
File length≤ 150 lines
Function/method length≤ 30 lines
Parameters per function≤ 4
Cyclomatic / cognitive complexity≤ 10
Magic numbersflagged
Duplicate string literals≤ 3
Class instance attributes / data-abstraction coupling≤ 6

These same limits are expressed per-language in config/:

  • Python → config/python.flake8 (flake8 + plugins: flake8-functions, flake8-cognitive-complexity, wemake-python-styleguide, flake8-simplify)
  • Java → config/java-checkstyle.xml (Checkstyle)

Add a config for any other language using the same limits, and teach hooks/check-quality.sh to run its linter.

How It Works

hooks/check-quality.sh runs the available linters plus a couple of universal AST/line checks, and prints violations (exit 1) or nothing (exit 0). It needs no Claude Code context and no git history, so the same script serves all three wirings:

Option A — Final CI stage (the backstop)

Run the script as the last stage of the pipeline, after tests, lint and any automated review. It exits non-zero on violations, so any CI system fails the build on it:

quality-gate:
  stage: .post           # last — after tests, lint, and automated review
  script:
    - ./.ci/check-quality.sh

Start it non-blocking (allow_failure: true, or the equivalent) on an existing codebase. Turning it on hard against accumulated drift produces a wall of violations that nobody can act on, and the gate gets disabled within a week. Let it report for a few weeks, fix what it finds, then make it blocking — and keep it blocking, because a gate that can be waved through is not a backstop.

Tune the thresholds once, at adoption, to sit just above what your codebase already achieves. Raising them later to make a build pass is how the gate stops meaning anything.

Option B — Agent review hook (soft, judgment-based)

A Stop hook of type agent runs the script, then a reviewer agent reads each reported violation, decides whether it genuinely needs refactoring, and returns block (with a specific, actionable reason) or allow. Good as an early warning while you are working, where a hard wall would be disruptive. It catches violations before they reach CI, but it can be reasoned with — so it complements Option A rather than replacing it. See settings.json.

Option C — Hard gate hook (strict, deterministic)

A Stop hook that runs hooks/stop-quality-gate.sh directly. If the script finds violations it exits 2, which blocks the agent and feeds the violation list back so it must fix them before finishing. No judgment — any violation blocks.

Install

  1. Copy hooks/ into your project's .claude/hooks/ and make the scripts executable (chmod +x).
  2. Copy the relevant config/ file(s) to where your linter expects them (e.g. .flake8, checkstyle.xml).
  3. For CI (Option A), call check-quality.sh from your pipeline's final stage. For the hooks (Options B and C), merge settings.json into .claude/settings.json — pick one.
  4. Ensure the linters are installed in your environment.

The reference scripts default to checking a python/ and/or java/ subtree; adjust the SRC globs in check-quality.sh to match your project's layout.

Thresholds and the reviewers

The gate and review-complexity look at the same kind of problem from opposite ends, and both are needed:

review-complexityquality-gate
Inputthe diffthe codebase as it stands
Basisjudgment, with a smell cataloguefixed numeric thresholds
Catchescomplexity being introducedcomplexity that has accumulated
Answer to "but this case is fine"accepts itdoes not care
Runsduring reviewlast, after everything else

A threshold cannot see that a 200-line file is a lookup table nobody reads. A reviewer cannot see that this is the fourteenth reasonable increment. Neither alone is enough.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.