Plugin
Your agent ships better code when it has a named vocabulary for what's wrong and what to do — and only the matching skill loads per query.
Two ways to install: the Claude Code plugin (auto-invoking skills) or an AGENTS.md drop-in for other agents. Pick the higher one your environment supports.
If you have Claude Code: install the plugin
Only the skill matching what you're working on enters context — the other 139 in the catalog cost nothing per query. Coverage spans 66 refactorings, 24 smells, 27 Kerievsky composites, and 23 GoF patterns. An audit orchestrator picks which one applies.
/plugin marketplace add wallacedrew/ritl /plugin install refactor@ritl
How to invoke the plugin
Three entry points, picked by what you know about the code in front of you.
(just describe it)Type what you see in plain English — "this feels off", "is this clean?", "what's wrong here?", "take a look at this", "audit this", "tidy this up". The audit orchestrator's router catches phrases like these and walks the full cycle. No slash command needed; the plugin teaches you the vocabulary through the agent's announcements.
/refactor:auditForce the audit orchestrator with the block of code attached. Same cycle as above, but invoked explicitly instead of relying on description match — useful when the conversation isn't about refactoring and you want to switch modes.
/refactor:<skill-slug>Invoke the per-skill command directly. Tab-completion after /refactor: lists all 140 skills. Examples: /refactor:extract-function, /refactor:strategy, /refactor:replace-conditional-with-polymorphism.
How to use the plugin
The loop you actually run in once it's installed.
- Describe the problem in plain English. "This function is doing too much", "this conditional is unreadable", "this is duplicated across three files". The plugin's router matches your description against each skill — you don't have to memorise the catalog.
- Watch for the agent naming the smell and the refactoring. Before any edit, the agent announces what it sees and what it's applying — "this is a Long Function smell; I'll apply Extract Function." Treat the announcement as the contract: if it doesn't name a catalog entry, it isn't using one.
- Click through when you don't recognise the named skill. Every named skill has a detail page at refactoringintheloop.com with the Before/After and the agent-side forces. Two clicks to verify the agent picked the right move.
- Watch for the destination pattern when refactorings stack. When the agent says "this chain of Extract Method + Replace Conditional with Polymorphism is heading toward Strategy", that's where the catalog earns its weight versus a vocabulary-less agent. Let it name the destination before the next move.
- Watch the decline vocabulary when the agent doesn't refactor. When the agent decides not to apply a refactoring, it should name which kind of decline — catalog miss (checkable), taste call (arguable), cost-benefit (arguable cost or value), constraint-blocked (non-negotiable), or insufficient context (asking before deciding). Silent non-action is the smell — name which.
What a skill looks like: Extract Function
This is the SKILL.md the plugin auto-loads when its description matches the agent's task. Same content as the Extract Function detail page.
Apply Extract Function when you see Long Function, Duplicated Code, Comments. Each function is a verifiable unit small enough that the agent reasons about its full behavior in a single reasoning step.
A function whose token cost exceeds the agent's reliable chunk-reasoning budget; verifying behavior preservation requires re-reading the entire span on every edit. The context-window load of the unstructured body crowds out other reasoning, and the reasoning step count rises as the agent re-derives the function's internal structure on each read.
Each function is a verifiable unit small enough that the agent reasons about its full behavior in a single reasoning step. The agent's context window holds the relevant helper and its signature; verifying behavior touches one named unit, and the reasoning-step cost of any edit drops because the agent doesn't re-derive structure on each read.
Before the refactoring
function invoiceTotal(invoice) {let total = 0;for (const line of invoice.lines) {total += line.qty * line.unitPrice;if (line.qty >= 100) total -= line.qty * line.unitPrice * 0.05;}total += total * invoice.taxRate;return Math.round(total * 100) / 100;}
After the refactoring
function invoiceTotal(invoice) {const subtotal = subtotalAfterBulkDiscount(invoice);const withTax = subtotal * (1 + invoice.taxRate);return roundToCents(withTax);}
Every edit pays full re-read cost; chained changes compound context usage and increase the chance of missing a cross-statement invariant. The agent's verification-surface cost multiplies with body length — verifying any single change requires scanning every other statement to confirm it didn't shift, and the agent's retrieval cost on chained edits compounds.
Each extracted helper inflates the agent's context-window load by one definition the next reasoning step must load; over-extracting saturates the agent's effective context-window capacity. The agent's completeness-check cost rises during the extraction itself — every reference to the body must be confirmed to route through the new helper rather than continuing to inline what's left.
Each extracted helper fits inside one read; the agent verifies behavior against one signature instead of loading the entire original procedure into context to detect what changed. The agent's token cost per edit drops because the relevant unit is the helper, not the parent — and helper boundaries surface cross-statement invariants through type-checker visibility rather than runtime drift.
Forces the agent to chase a dozen function definitions to follow what was once a 20-line procedure — context cost inflates and cross-function invariants disappear. The agent's retrieval cost across the call graph rises faster than the per-helper context-window load drops; tiny helpers cost more to assemble than to inline.
If you don't have Claude Code: paste this AGENTS.md drop-in instead
For Codex, Aider, Cursor, and other agents that read AGENTS.md or CLAUDE.md. A ~30-line directive snippet — sense the smell, name the refactoring, write the safety net, ship one named move per commit. References the catalog at refactoringintheloop.com for the lookup data. Skip this whole section if you installed the Claude Code plugin — the two artifacts do the same job.
When not to install
The plugin is the wrong choice when you're chasing a live bug. The discipline's safety-net step writes characterization tests before any structural change, and that test-writing latency compounds when you're iterating fast on the fault. Disable it with /plugin disable refactor@ritl until the trace is clean, then re-enable for the cleanup pass.