Lint Enforcement Skill

Philosophy

Adopt a strict-by-default "straightjacket" approach to linting. Every rule starts enabled at its strictest setting. Teams adapt by selectively relaxing rules with documented rationale — never by starting permissive and hoping to tighten later.

The reasoning is simple: it is far easier to disable a rule that does not apply to your codebase than to retroactively enforce a rule across thousands of existing violations. Strict defaults create a culture of intentional exceptions rather than accidental omissions.

Supported Languages

Language	Linter	Config File	Key Focus Areas
TypeScript	ESLint	.eslintrc.json	Type safety, no-any, explicit returns, strict bools
Python	ruff	ruff.toml	PEP 8, import sorting, security, complexity
Swift	SwiftLint	.swiftlint.yml	Force unwrap prevention, naming, complexity
Bash	shellcheck	.shellcheckrc	Quoting, globbing, POSIX compliance

Stack Detection

Use detect_stack.sh (located at ${CLAUDE_PLUGIN_ROOT}/lib/detect_stack.sh) to automatically identify which languages are present in a project. The script scans for:

• TypeScript: tsconfig.json or .ts files (maxdepth 3, excludes node_modules)
• JavaScript: package.json + .js files without tsconfig.json
• Python: pyproject.toml, setup.py, requirements.txt, or .py files
• Swift: Package.swift, .xcodeproj, or .swift files
• Bash: .sh files (excludes node_modules, .git)

Output is one language per line, enabling pipeline composition.

Audit Methodology

When auditing a project, check three layers per detected language:

1. Config exists — Is there a linter configuration file in the project root?
2. Lint script exists — Does package.json (or Makefile, pyproject.toml) define a lint script/target?
3. CI step exists — Does .github/workflows/, .circleci/, or similar contain a lint step?

Each layer is scored independently, producing a per-language audit report.

Severity Classification

Severity	Color	Meaning	Example
GREEN	Green	All three layers present and correctly configured	ESLint config + npm lint + CI step
YELLOW	Yellow	Config exists but missing lint script or CI integration	ruff.toml present, no Makefile target
RED	Red	No linter configuration found for a detected language	Python project with zero ruff config

Config Philosophy: Strict Defaults

Reference configs in references/ follow these principles:

1. Enable every available rule — Start with the superset of recommended + strict + stylistic rules.
2. Set thresholds conservatively — Line length 100, function body 40 lines, cyclomatic complexity 10.
3. Pair linter with formatter — ESLint + Prettier, ruff format, SwiftLint autocorrect.
4. Document every relaxation — If a rule is disabled, the config includes a comment explaining why.
5. Version-pin configs — Reference configs target specific linter versions to avoid surprise breaks.

Test Generation Methodology

For each lint rule in a config, generate two test fixtures:

1. Violation fixture — Code that deliberately breaks the rule. The linter MUST report an error.
2. Clean fixture — Code that satisfies the rule. The linter MUST report zero errors.

A test runner script executes the linter against both fixtures and asserts expected outcomes. This validates that:

• Rules are not accidentally disabled
• Rule severity is correct (error vs. warning)
• Custom thresholds are enforced

PostToolUse Hook

The post_write_lint.sh hook (at ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/post_write_lint.sh) runs automatically on every Write or Edit tool use:

1. Extracts file_path from TOOL_INPUT JSON
2. Detects language from file extension
3. Walks up directory tree to find project root
4. Checks for linter config in project root
5. Runs linter against the written file
6. Exit 0 — File passes lint or no config/linter available (graceful degradation)
7. Exit 2 — Lint violations found; block with violations on stderr

Graceful degradation ensures the hook never breaks workflows:

• No config found: warns and approves
• Linter not installed: warns and approves
• Non-code file: silently approves