agentleFS
fworks-techfworks-tech/agenthood/skills/warden/SKILL.md

warden

Skill2 starsChanged todayMITView on GitHub

Detects code smell, complexity violations, architectural boundary breaches, dead code, and dependency decay in project code. Runs on every PR diff and on demand for full codebase scans. The chaos does not arrive all at once — The Warden is here for the accumulation. Use on PR diffs and codebase quality scans.

7 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use mobilebuildmcp-cli, mobilebuildmcp-docs-command-review and 9 more.

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.
  • SentrySkill

    mobilebuildmcp-cli

    Official skill for the MobileBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).

    Also in 3 projects that use this

  • SentrySkill

    mobilebuildmcp-docs-command-review

    Use when reviewing MobileBuildMCP changelog CLI command references for invalid current guidance while allowing historical migration examples.

    Also in 3 projects that use this

  • +9 more from getsentry

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 9 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before merging to main — confirm the branch does not worsen the codebase's health score

    line 21
  2. Distinctive:

    After a large refactor — verify the refactor did not introduce new coupling

    line 22
  3. Distinctive:

    When the codebase feels slow or brittle — before attributing it to something else

    line 24
  4. Very specific:

    Run git diff origin/main...HEAD --name-only to get changed files

    line 32
  5. Distinctive:

    Check for the following categories in scanned files:

    line 56
  6. Distinctive:

    When flagging: name the function, line count, and file:line location

    line 61
  7. Distinctive:

    When flagging: name the function and the deepest block

    line 70
  8. Distinctive:

    When flagging: list all locations of the duplicate

    line 80
  9. Distinctive:

    Add 1 for the function itself

    line 101
  10. Very specific:

    If the project has a custom architecture, read docs/architecture/ or equivalent before scanning.

    line 126
  11. Very specific:

    When running a full scan (/warden dead-code):

    line 130
  12. Distinctive:

    Do not flag test files for unused exports — test utilities are legitimately not imported elsewhere.

    line 138

“Common” is measured: kept by at least 6 in 10 of the 7 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

The Warden

Overview

The Warden watches for the conditions that produce bugs before the bugs appear. Code smell is not a style preference — it is a leading indicator of where the next defect will live. A function with eight parameters will be called wrong. A file with 800 lines will have a bug nobody finds because nobody reads it all. A circular dependency will produce an import error nobody can explain. The Warden sees these things while they are still cheap to fix.

When to Use

  • On every PR — scan the diff for new smells introduced by the change
  • Before merging to main — confirm the branch does not worsen the codebase's health score
  • After a large refactor — verify the refactor did not introduce new coupling
  • On demand — full codebase scan to establish or revisit a health baseline
  • When the codebase feels slow or brittle — before attributing it to something else

Process

PR Diff Scan

On every PR, scan only the changed files to keep the check fast:

  1. Run git diff origin/main...HEAD --name-only to get changed files
  2. For each changed file, check against all smell categories below
  3. Produce a report showing new smells introduced (not pre-existing ones)
  4. Block the PR if any BLOCKING threshold is exceeded on changed lines
  5. Warn (not block) for WARNING threshold violations

Report format:

Warden Scan — PR #42 (feat/user-preferences)
Date: YYYY-MM-DD
Files scanned: 4

✅ No blocking violations
⚠️  Warnings (2):
    src/components/PreferencesForm.tsx:87
      Function `handleSubmit` is 52 lines (warning threshold: 40)
    src/api/preferences.ts:23
      Nesting depth 4 in `validatePayload` (warning threshold: 3)

Smell-free files: src/hooks/usePreferences.ts, src/types/preferences.ts

Code Smell Detection

Check for the following categories in scanned files:

Long functions

  • Count lines per function/method (excluding blank lines and comments)
  • Warning: >40 lines. Blocking: >80 lines
  • When flagging: name the function, line count, and file:line location

Large files

  • Count total lines per file
  • Warning: >300 lines. Blocking: >500 lines

Deep nesting

  • Count maximum nesting depth (if/for/while/try blocks)
  • Warning: >3. Blocking: >5
  • When flagging: name the function and the deepest block

Too many parameters

  • Count parameters per function signature
  • Warning: >4. Blocking: >7
  • Exception: config/options objects (single object parameter) are not flagged

Duplicated logic

  • Identify blocks of >10 lines that are near-identical across two or more locations
  • Warning: >10 lines. Blocking: >20 lines
  • When flagging: list all locations of the duplicate

Inconsistent naming

  • Within a single file: flag mixed conventions (camelCase + snake_case for the same type of identifier)
  • Flag variables named with single letters outside of loop counters (i, j, k)
  • Flag boolean variables not prefixed with is, has, should, or can

Feature envy

  • Flag functions that call methods on another module more than they use their own module's data
  • Indicates the function likely belongs in the other module

Dead code

  • Exported symbols (functions, types, constants) with no import found in the project
  • Variables declared but never read
  • Conditions that are always true or always false
  • console.log, print, debugger statements in non-test files

Complexity Enforcement

For each function in the diff, compute cyclomatic complexity:

  • Count: if, else if, for, while, case, catch, &&, ||, ternary ?
  • Add 1 for the function itself
  • Warning: >10. Blocking: >20

When blocking, provide:

  1. Function name and location
  2. Complexity score
  3. The top 3 branches contributing most to complexity
  4. Suggested decomposition: "Extract validateInput (handles 4 branches) and processResult (handles 3 branches)"

Architectural Boundary Violations

Detect imports that cross layer boundaries. Default layer order (innermost to outermost):

domain / core       → no imports from outer layers
application         → may import from domain only
infrastructure      → may import from application and domain
presentation / ui   → may import from application only; never from infrastructure directly

Detection steps:

  1. Identify the project's layer structure from directory names and existing imports
  2. For each import in the diff, check if it crosses a boundary inward
  3. Flag: ui/PreferencesForm.tsx imports from db/queries.ts — UI must not import from infrastructure

If the project has a custom architecture, read docs/architecture/ or equivalent before scanning.

Dead Code Audit

When running a full scan (/warden dead-code):

  1. Build an import graph: which files import which exports
  2. Find exports with zero importers — flag as UNUSED EXPORT
  3. Find variables assigned but never read within their scope — flag as DEAD VARIABLE
  4. Find commented-out code blocks (>3 lines) — flag as COMMENTED BLOCK with file:line
  5. Find TODO and FIXME comments — list with age if determinable from git log

Do not flag test files for unused exports — test utilities are legitimately not imported elsewhere.

Dependency Hygiene

Scan package.json, requirements.txt, Pipfile, go.mod, Cargo.toml, or equivalent:

Wildcard versions — flag any *, latest, or overly broad range (^0.x, >=1.0.0) Unused dependencies — cross-reference declared deps against actual imports in source Duplicate functionality — flag pairs like lodash + underscore, moment + dayjs Deprecated packages — flag packages marked deprecated on their registry page Dev deps in production — flag packages in dependencies that are only used in tests or scripts

Red Flags

  • A function whose purpose cannot be stated in one sentence — complexity has won
  • A file that is the only place that knows about two unrelated things
  • Any // TODO: fix this properly comment older than one sprint
  • A dependency version pinned to latest in a production manifest
  • Dead code defended with "we might need it later"
  • A test file with no assertions (it passes but proves nothing)
  • Circular imports between any two modules

Rationalizations

What you thinkWhat The Warden knows
"The function is long but it's readable"Readability and length are not the same thing. A 90-line function cannot be held in working memory. It will be misread by the next person and mischanged by the one after that.
"We'll refactor it after the deadline"The deadline passes. The next one begins. The function stays. Six months from now nobody remembers why it was left and everyone is afraid to touch it.
"The duplication is fine, they just look similar"They look similar because they do the same thing. When the logic changes, it will be changed in one place and not the other. That is where the bug will live.
"Dead code doesn't hurt anything"It hurts comprehension. Every reader must determine whether it is dead or dormant. That cost is paid on every read, forever.
"The architectural violation is just this once"The second violation is easier to justify than the first. The third is routine. By the tenth, the architecture no longer exists.

Verification

The Warden's scan is complete when:

  • All changed files in the diff have been scanned
  • No BLOCKING violations remain unresolved
  • All WARNING violations are acknowledged — either fixed or explicitly accepted with justification
  • No new architectural boundary violations introduced
  • No dead code added (new unused exports, new commented-out blocks)
  • Dependency manifest has no new wildcard versions
  • Full scan baseline (if run) is recorded for comparison at next scan

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.