AI Debt Scanner Framework 🚀

This is a universal reasoning framework designed for AI agents (like Gemini, Claude, or GPT-based CLIs) to audit and clean technical debt generated by "vibe coding" in multi-language projects. Unlike traditional static analysis tools, this framework provides the agent with a structured reasoning protocol to detect patterns in code using its own intelligence and standard toolsets.

Key Advancements

• 🌍 OS & Runtime Agnostic: Works natively on Windows, macOS, and Linux without requiring Python, Node.js, or any external binaries.
• 🛡️ Lightweight Guardrails: Applies a compact quality check during code changes and escalates only when the change is broad, architectural, or explicitly audit-driven.
• 🧪 Context-Aware Scanning: Automatically reduces noise in test files (ignores Magic Numbers in **/tests/** or *.spec.*) and relaxes rules for configuration and orchestration files.
• 🌫️ Dynamic Context Discovery: Automatically scans for project laws in GEMINI.md, CLAUDE.md, or .ai-debt-rules.md to adapt its audit to your specific team standards.
• ⚡ Incremental Audits: Supports --diff mode to scan only modified files, making it ideal for pre-commit hooks.
• ⚖️ Severity-Based Scoring: Classifies debt as CRITICAL (e.g., security risks, AI artifacts), WARNING (structural bloat, cognitive overload), or INFO (magic numbers, redundant comments).
• 🧠 Universal Support: Audits any language or runtime by focusing on semantic and architectural patterns (KISS, DRY, YAGNI, SOLID, failure semantics, boundary integrity, contract safety) instead of a fixed stack list.
• 🗺️ Scoped Artifact Fingerprinting: Detects execution surfaces and trust boundaries at the right depth, from a local change to a repo-wide audit, without over-scanning by default.
• 🎚️ Depth-Based Workflow: Uses Quick, Standard, and Deep modes so small edits stay fast while larger audits still get full architectural scrutiny.

How it Works

The framework implements a depth-aware reasoning protocol:

1. Quick: Review the affected area and immediate boundaries only.
2. Standard: Expand to adjacent contracts, modules, and subsystem edges.
3. Deep: Run a full architectural audit across the repository.

Supporting agents are used selectively:

1. Scanner Agent: Identifies hotspots using platform-independent tools (grep_search, glob) and calculates a debt profile for the chosen scope.
2. Architect Agent: Used when cross-file boundaries or architecture are central to the problem.
3. Cleaner Agent: Used when there is a concrete fix plan and behavior can be validated safely.

🤖 Multi-Agent Awareness

This repository is designed to be Agent-Aware. It includes specialized configuration files to ensure that any AI assistant (Gemini, Claude, Copilot, Cursor, etc.) understands its role as a Technical Debt Auditor and proactively suggests the installation of the git hook.

Agent	Config File	Behavior
Gemini CLI	GEMINI.md	Proactive setup & reasoning protocol
Claude Code	.claude/CLAUDE.md	Senior Architect mindset & hook setup
GitHub Copilot	.github/copilot-instructions.md	Contextual guardrails & auto-setup
Cursor	.cursorrules	Rule-based auditing & hook installation
Universal	AGENTS.md	Fallback instructions for any AI agent

---

Automation: Git Hooks ⚓

Stop "vibe coding" before it reaches your repository. You can integrate the scanner as a pre-commit hook to audit only your staged changes.

Automatic Installation

Just ask your agent:

"Install the AI debt git hook"

The agent will automatically copy the template to .git/hooks/pre-commit and set the correct permissions.

Pro-Developer Workflow:

• Incremental: Only scans files you've touched (git diff --cached).
• Helpful, Not Annoying: If critical debt is found, the agent offers to Auto-Fix it using the Cleaner Agent before allowing the commit.
• Thresholds: Block only on CRITICAL issues. Warn on WARNINGS. Ignore INFO.

See templates/hooks/pre-commit-ai-debt.sh for an implementation template.

Project Structure

.
├── skills/
│   └── ai-debt-scanner/
│       └── SKILL.md         # Skill definition and core reasoning protocol
├── templates/
│   └── hooks/               # Git hook automation templates
└── references/
    ├── agents/              # Specialized agent instructions (Scanner, Architect, Cleaner)
    ├── rules.md             # Scoring logic, severities, and contextual overrides
    ├── chunking_protocol.md  # Handling large file analysis (>300 lines)
    └── refactoring_patterns.md # Patterns for transforming "vibe coding" debt

Usage

You can invoke the scanner by asking the agent to:

• "Scan this project for AI debt."
• "Run an incremental audit (--diff) to check my recent changes."
• "Show me the top 5 most critical offenders (--top-k 5)."
• "Review this refactor for technical debt before we merge it."
• "Use guardrails on this architectural change."

Output is depth-aware:

• Quick: short human summary
• Standard: structured findings summary
• Deep / --diff / --top-k: TOON (Token-Oriented Object Notation) JSON report

Universal Audit Examples

• Failure handling: swallowed errors, ignored status channels, blanket exception handling, unsafe revert paths.
• Boundary integrity: transport/domain/persistence/infra mixed in one unit or hidden dependency leaks.
• Contract safety: unchecked inputs, type escapes, schema drift, generated clients diverging from source contracts.
• Operational risk: unsafe deployment scripts, brittle automation, missing rollback/failure strategy.

Depth Selection

• Quick: one-file review, narrow fix, local refactor
• Standard: multi-file feature, subsystem review, unclear ownership
• Deep: full audit, architecture review, repo-wide drift analysis

Installation

Install it into your agent's skill environment:

gemini skill add .

(Or point to the repository URL)