Maintainability Agent

A deterministic CI gate + bounded remediation prompt generator for repos that use AI coding agents (Claude, Codex, Cursor, Copilot, Windsurf, …) — ships an invokable skill for Codex, Claude Code, and GitHub Copilot Chat so /maintainability-agent is one keystroke away in any of them.

pip install maintainability-agent          # CLI + library
cp -r skills/maintainability-agent ~/.claude/skills/                                  # Claude Code skill
cp skills/maintainability-agent/copilot/maintainability-agent.prompt.md .github/prompts/  # Copilot Chat (VS Code)
# Codex picks up skills/maintainability-agent/ via its own convention.

Jump to Invokable Skill / Slash Command for the full install table.

Why this exists

AI-written code fails in recognizable ways: speculative refactors, duplicated helpers, broad rewrites for narrow bugs, stale comments that sound confident, tests that assert implementation details instead of behavior, architecture drift across modules. SonarQube / CodeClimate / Qlty / ESLint / Ruff / Radon all catch some of this. None of them ship a bounded prompt back to the agent that says "fix only these specific findings, do not refactor outside this scope."

That's the point of this tool:

1. Run a deterministic local audit — file size, function size, approximate cyclomatic complexity, duplication, configurable risk patterns, ISO/IEC 25010-inspired 0–5 score.
2. Emit Markdown, JSON, SARIF, a PR comment, and a baseline for incremental adoption.
3. Generate an AI remediation prompt scoped to the actual findings — bounded, with explicit "don't rewrite the codebase" rules.
4. Hand that prompt to your agent. Get a small, reviewable fix instead of a 600-line speculative cleanup PR.
5. Drop the shipped portable invokable skill into Codex, Claude Code, or GitHub Copilot Chat so /maintainability-agent is one keystroke away in any of them. See Invokable Skill below.

The remediation prompt is the differentiator. Every other tool in this space stops at "here's a list of findings."

Who it's for

• Teams running AI agents in the dev loop who are tired of unbounded agent rewrites and want a CI gate that actively constrains follow-up scope.
• Repos that want a maintainability gate without paying for SonarQube / CodeClimate / Qlty or sending code to a third party.
• Solo devs who want a single-binary deterministic audit they can pin in a Makefile, a pre-commit, or a local CI script.

Design principles

• Deterministic first, AI optional. The audit never calls an LLM by default. The remediation prompt is a generated artifact that you choose to hand to an agent.
• Bounded scope. The remediation prompt explicitly tells the agent to fix the listed findings only — not to embark on architecture cleanup.
• No vendor lock-in. All outputs (Markdown, JSON, SARIF, PR comment) are plain files. Pair this tool with mature analyzers (ESLint, Ruff, Radon, Semgrep, SonarQube, Qlty/Code Climate) — don't replace them.
• Pass-the-cost-of-disclosure. A finding that's "just a warning" never blocks CI alone. Hard gates are configurable + opt-in.

See docs/philosophy.md for the longer version.

Self-Audit

This repo eats its own dogfood — the tool is run against this codebase as part of CI, and the latest report is checked in at docs/self-audit.md:

Metric	Value
Overall score	5.0 / 5 (A+)
File warnings	0
Function warnings	0
Duplicate blocks	0
Risk findings	0
Hard gate failures	0

All five ISO/IEC 25010 categories (modularity, reusability, analyzability, modifiability, testability) score 5.0. Regenerate with maintainability-agent --config maintainability-agent.json --output docs/self-audit.md (see the file's preamble for the path-sanitization step).

Install

Install from PyPI:

python3 -m pip install maintainability-agent
maintainability-agent --root . --config maintainability-agent.json

Or run directly from source without installing:

python3 -m maintainability_audit \
  --root . \
  --config maintainability-agent.json \
  --output maintainability-report.md

Or install editable during development:

python3 -m pip install -e .
maintainability-audit --root . --config maintainability-agent.json
maintainability-agent --root . --config maintainability-agent.json

Quick Start

Copy the example config to your repo root as maintainability-agent.json:

cp maintainability-audit.example.json maintainability-agent.json

Run:

maintainability-agent \
  --config maintainability-agent.json \
  --format markdown \
  --output maintainability-report.md

Fail CI on hard gates:

maintainability-agent \
  --config maintainability-agent.json \
  --fail-on-gate \
  --output maintainability-report.md \
  --prompt-output maintainability-remediation-prompt.md \
  --comment-output maintainability-pr-comment.md

What It Analyzes

The deterministic scanner reads code from your repo (no LLM calls) and produces signals on:

• largest files (warn / fail thresholds configurable per-repo)
• approximate function/class size
• approximate cyclomatic complexity
• duplicate blocks (≥ N consecutive non-trivial lines, configurable)
• configurable risk patterns (regex matchers — TODO/FIXME, eval(, exec(, custom)
• expected files present (README, LICENSE, etc. — opt-in hard gate)
• expected test/lint commands declared in the config (opt-in hard gate)
• worktree-clean state at audit time (opt-in hard gate)
• ISO/IEC 25010-inspired 0–5 score per category + overall letter grade

The analyzer is intentionally conservative and dependency-free. Mature repos should pair this with native tools (ESLint, Ruff, Radon, Semgrep, SonarQube, Qlty / Code Climate) — not replace them. SARIF input from those tools can be folded into this tool's report via --sarif-input.

What It Produces

Each run can emit any combination of:

• maintainability-report.md — the full Markdown report with summary, score, hotspots, duplicates, risk findings, external (SARIF) findings.
• maintainability-remediation-prompt.md — bounded AI prompt scoped to the run's findings.
• maintainability-pr-comment.md — short body suitable for a gh pr comment post.
• maintainability.sarif — SARIF 2.1.0 output for GitHub Code Scanning ingestion.
• maintainability-baseline.json — fingerprints of current findings, for --fail-on-new incremental adoption.
• Per-tool agent instruction files (AGENTS.md, CLAUDE.md, .cursor/rules/maintainability.mdc, .github/copilot-instructions.md, .windsurf/rules/maintainability.md, AI-MAINTAINABILITY.md) via --init-agent-standards.

AI Remediation Prompt

The runner can generate a bounded prompt for a human developer to give to Claude, Codex, or another coding assistant:

maintainability-agent \
  --config maintainability-agent.json \
  --output maintainability-report.md \
  --prompt-output maintainability-remediation-prompt.md

The prompt is designed for AI-written or AI-assisted code reviews. It tells the assistant to:

• fix only the highest-value maintainability issues
• keep the patch small and reviewable
• preserve existing architecture and behavior
• add tests where behavior changes
• report false positives instead of rewriting blindly

This makes the CI artifact actionable without letting the audit turn into an unbounded refactor request.

PR and Baseline Workflows

PR-only audits, baseline grandfathering, AI-agent instruction generation, and reusable agent-standard file generation are covered in PR and Baseline Workflows.

Running Tests

# Sandbox-friendly invocation (works with PYTEST_DISABLE_PLUGIN_AUTOLOAD=1):
PYTHONPATH=src python3 -m pytest

# With coverage gate (matches CI):
PYTHONPATH=src python3 -m pytest \
  --cov=maintainability_audit --cov-fail-under=92

# With ruff lint + pip-audit (matches CI):
python3 -m pip install -e ".[dev]"
ruff check src tests
pip-audit
PYTHONPATH=src python3 -m pytest --cov=maintainability_audit --cov-fail-under=92

Coverage is intentionally NOT in [tool.pytest.ini_options].addopts so the sandbox-friendly invocation (PYTEST_DISABLE_PLUGIN_AUTOLOAD=1) doesn't choke on --cov flags it can't load. Pass coverage flags explicitly when you want the gate.

Scoring Standard

The audit model is based on ISO/IEC 25010 maintainability:

• modularity
• reusability
• analyzability
• modifiability
• testability

See docs/standard.md.

Documentation

• CLI reference
• Config schema
• Philosophy
• Analyzer adapters
• External quality tools
• IDE and agent integration
• PR and baseline workflows
• Roadmap

GitHub Action

This repo includes action.yml, so it can be used as a composite action after publishing:

- uses: marshallguillory86/maintainability-agent@v0.3.0
  with:
    config: maintainability-agent.json
    changed-only: main...HEAD

GitHub Actions

After publishing, copy .github/workflows/maintainability.yml into the target repo or adapt it for your local CI.

IDE and Agent Integration

See docs/ide-agent-integration.md for VS Code tasks and integration notes for Copilot, Cursor, Codex, Claude Code, Windsurf, generic agents, local CI, and GitHub Actions.

Invokable Skill / Slash Command

For agents that support invokable skills, this repo ships a portable skill under skills/maintainability-agent/. The SKILL.md body is the source of truth; per-host adapters live under agents/ and copilot/.

Host	Install destination	Invocation
Codex / OpenAI	wired via skills/maintainability-agent/agents/openai.yaml	per Codex's skills convention
Claude Code	copy skills/maintainability-agent/ → ~/.claude/skills/maintainability-agent/ (user-scope) or <repo>/.claude/skills/maintainability-agent/ (project-scope)	/maintainability-agent (or surfaced automatically when description matches)
GitHub Copilot (VS Code)	copy skills/maintainability-agent/copilot/maintainability-agent.prompt.md → <repo>/.github/prompts/maintainability-agent.prompt.md	/maintainability-agent in Copilot Chat

Quick install (Claude Code, user-scope):

mkdir -p ~/.claude/skills
cp -r skills/maintainability-agent ~/.claude/skills/

Quick install (Copilot, target repo):

mkdir -p .github/prompts
cp skills/maintainability-agent/copilot/maintainability-agent.prompt.md .github/prompts/

For non-invokable, always-on guidance, use --init-agent-standards (see docs/ide-agent-integration.md).

Local CI

For repos that do not use GitHub Actions, use:

examples/local-ci.sh

The local CI script enforces test coverage at >=92% and writes coverage.xml for SonarQube Cloud, Qlty, Codacy, or any other tool that can ingest Python coverage.

Get in Touch

• Bug reports / feature requests / general questions — open a GitHub Issue.
• Discussion / ideas — use the Discussions tab (enable in repo settings if not visible yet).
• Security vulnerabilities — see SECURITY.md and use the private security advisory flow. Do not post vulnerabilities in public issues.

License

MIT