Complexity Quality Gate Enforcer

Set hard numeric thresholds for cyclomatic and cognitive complexity that your AI agent must stay under — enforced by linters and CI, not code review promises.

The Problem

Your AI coding agent produces 200 lines of beautiful, well-commented Python in a single function with 7 levels of nested conditionals, 3 types of exception handling, and a switch statement inside a loop inside a try/catch. It passes all tests. It gets approved in code review because it's too complex for anyone to review thoroughly in under 30 minutes. Three months later, you're the one who has to add a feature to this function and you spend a full day just understanding the control flow. This is "agent slop" — code that works but is structurally unmaintainable.

What You Get

• Complexity metrics configuration — sets hard thresholds for cyclomatic complexity (default ≤10), cognitive complexity (default ≤15), and coupling between objects (default ≤20), with per-function blocking
• Multi-language linter setup — configures radon (Python), eslint-plugin-complexity (JS/TS), gocyclo (Go), and rust-clippy (Rust) with the exact threshold values and output formatting
• Pre-commit hook — universal bash script that auto-detects the project language, runs the appropriate complexity linter, and blocks commits that introduce functions exceeding the configured threshold
• CI/CD pipeline gate — GitHub Actions workflow that blocks PRs with complexity violations, outputting function name, file path, and exact complexity score for each violation
• Agent self-check behavior — instructions for CLAUDE.md/AGENTS.md that teach the agent to run the complexity linter BEFORE committing, not after, with refactoring rules when a violation is found
• Progressive tightening schedule — a 4-week onboarding plan that starts with no blocking (baseline), then blocks new functions >15, then all functions >10, then reduces to 7 — preventing team resistance while building compliance

Why This Beats Prompting It Yourself

Telling an agent "write clean code" is unenforceable and the agent ignores it under context pressure. Telling it "your cyclomatic complexity must stay under 10 or the CI will reject your PR" is deterministic and verifiable. This skill creates the enforcement infrastructure (linter config, pre-commit hook, CI gate) so the agent operates under structural constraints rather than behavioral suggestions. The agent doesn't need to "try" to write simple code — it must, or the commit is blocked.

Example Session

You: Set up complexity gates for this Python project.

Agent: Configured radon with threshold 10 for cyclomatic complexity, created .radon.json quality gate, installed pre-commit hook, and added GitHub Actions workflow. Baseline scan: 89 functions exceed threshold 10 (26% of 342 total). Worst: router.py::handle_request (complexity 31). Progressive tightening schedule: Week 1 baseline (no blocking), Week 2 block new >15, Week 4 block all >10. Agent CLAUDE.md updated with mandatory self-check rule: "Before ANY commit, run radon cc . -a --min C. If violations found, refactor before committing."

Use Cases

• Enforcing code complexity limits across a team that uses multiple AI coding agents
• Blocking PRs that introduce god-functions or deeply nested control flow
• Creating a baseline complexity report for a codebase before starting a refactoring sprint
• Teaching AI agents to self-check complexity before committing, building a culture of simple code
• Progressive quality improvement with a 4-week tightening schedule that doesn't disrupt existing velocity

Known Limitations

Some functions are legitimately complex (parsers, protocol handlers, state machines) and should be exempted with documented justification. The skill supports annotated exceptions (# complexity:ignore — parser state machine) but they must be explicitly approved per-function to prevent abuse.

Tags: code-quality complexity ci-cd linting agent-productivity refactoring

Version: 1.0.0