agentic-tech-debt

debt-ops

Catches AI-introduced tech debt at write-time

Works with any coding agent. Any stack.

Two decades of tech-debt research, distilled into a plugin and validated across dozens of codebases.

What it does

• Tracks the debt — every "I'll fix this later," shortcut, and punt your agent writes lands in a folder in your repo.
• Records the decisions — a short ADR when your agent makes an architectural call.
• Works quietly in the loop — reads what's already logged, ranks cleanup by hotspot, and surfaces failures before they hit your diff.

---

Install

Just needs a git repo and Python 3.10+.

Claude Code

/plugin marketplace add bcanfield/agentic-tech-debt
/plugin install debt-ops@agentic-tech-debt

codex plugin marketplace add bcanfield/agentic-tech-debt
# then, inside Codex: /plugins → install debt-ops

One-click install via the plugin (hooks + skills bundled):

/add-plugin     # then pick debt-ops, or browse cursor.com/marketplace

Prefer to install by hand? Copy hooks.local.json + the scripts into .cursor/ and the skills into .agents/skills/:

mkdir -p .cursor/hooks .agents/skills
cp cursor/hooks/hooks.local.json .cursor/hooks.json
cp cursor/hooks/*.py .cursor/hooks/
cp -r cursor/skills/debt-ops-* .agents/skills/

See the Cursor adapter README for details.

copilot plugin marketplace add bcanfield/agentic-tech-debt
copilot plugin install debt-ops@agentic-tech-debt

Then run debt-ops-init once — Copilot has no per-session inject, so this writes the disciplines into your charter (.github/copilot-instructions.md or AGENTS.md). See the Copilot adapter README for the manual-install alternative and details.

Via portable Agent Skills:

npx skills add bcanfield/agentic-tech-debt

Then run debt-ops-init once to write the disciplines into your AGENTS.md.

---

Commands

Claude Code /debt-ops:<name> · Codex $<name>:

• add: register a debt entry (auto-fires when your agent defers work). Drop with drop A, drop A,C, or drop all.
• review: audit and rank the registry, then walk paydown.
• init (opt-in): write the disciplines into CLAUDE.md/AGENTS.md so the team shares them.
• metrics: read-only health summary of the registry.

---

Why it exists

AI writes more code and cleans up less of it: across 211M lines, one study saw refactoring more than halve while duplicated code kept climbing. So debt piles up faster than you can review it. The fixes are well understood: keep it visible, pay it down over time, record the decisions. debt-ops wires those into the agent loop as nine cited pillars. Full research synthesis.