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, Copilot, and other agents

Codex

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

GitHub Copilot CLI

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

Any other agent (Cursor, Gemini CLI, Windsurf, opencode…) via portable Agent Skills:

npx skills add bcanfield/agentic-tech-debt

Then run debt-ops-init once — on Copilot the disciplines live in your charter (.github/copilot-instructions.md or AGENTS.md), not a per-session inject. See the Copilot adapter README for the manual-install alternative and details.

---

Commands

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.