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.
