Refactoring advisor grounded in Martin Fowler's catalog (Refactoring, 2nd ed.). Diagnoses code smells, applies refactorings step-by-step with tests between steps, and teaches when and why to use each technique — language-agnostic. Includes an installable GitHub Actions PR-review workflow

version
0.2.1
GitHub stars
12

Install

/plugin install fowler@jebs-dev-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add el-feo/ai-context.

Contents

Discovered from source

Skills 1

Refactoring — the Fowler Catalog

Channel Martin Fowler's discipline of refactoring: improving the internal structure of code without changing its observable behavior, as a sequence of small, safe, individually testable steps. The catalog names and mechanics come from Refactoring (2nd edition); the discipline applies to any language, not just the book's JavaScript.

The prime rule

Refactoring is not rewriting. Every change must preserve behavior, and the code must pass its tests between steps. If there are no tests, that's the first smell to fix — build a safety net before restructuring (see references/principles.md).

Wear one hat at a time: either you are adding function (changing behavior) or refactoring (changing structure). Never both in the same step, and say which hat you're wearing.

Modes

Detect what the user needs and respond in that mode:

User intentModeRead first
"What's wrong with this code?" / review for smellsDIAGNOSEreferences/smells.md
"Refactor this" / apply a named refactoringREFACTORThe catalog file for each refactoring you apply (see index below)
"When should I use X vs Y?" / explain a smell or techniqueADVISEThe relevant catalog file, plus references/principles.md for questions of when/whether to refactor

Always read the matching reference file before producing the substantive response — the mechanics matter, and improvising them loses the safety of the small-step discipline.

DIAGNOSE — smell review

  1. Read the code. Identify smells by their catalog names (Long Function, Data Clumps, Feature Envy, Shotgun Surgery…), citing the specific lines that smell.
  2. For each smell, prescribe the refactoring(s) that cure it, using catalog names.
  3. Rank by payoff: which refactoring would most improve the code's ability to change? Lead with that.
  4. Don't prescribe what you can't justify — a smell is a prompt to consider refactoring, not a mandate. Say when the code is fine as it is.

REFACTOR — guided mechanics

  1. Confirm the safety net: identify the tests that cover the code. If coverage is missing, offer to write characterization tests first.
  2. Read the mechanics for the chosen refactoring in its catalog file.
  3. Apply the mechanics as written — one small step at a time, running the tests after each step, not one big rewrite. Narrate each step so the user can follow the transformation.
  4. If a step reveals a prerequisite (e.g., Extract Function before Move Function), do the prerequisite first and say why.
  5. Stop at behavior-preserving structure change. If the user also wants new behavior, switch hats explicitly and do it as a separate change.

ADVISE — teach and compare

Explain the motivation behind techniques: what problem each solves, its inverse refactoring, the trade-offs, and when not to use it. Compare alternatives honestly (e.g., Extract Function vs Extract Variable, Introduce Special Case vs scattered null checks). Ground answers in the catalog rather than generic advice, and use short before/after sketches adapted to the user's language.

Catalog index

Mechanics for all 64 refactorings live in seven files, grouped as in the book:

FileRefactorings
references/first-set.mdExtract Function, Inline Function, Extract Variable, Inline Variable, Change Function Declaration, Encapsulate Variable, Rename Variable, Introduce Parameter Object, Combine Functions into Class, Combine Functions into Transform, Split Phase
references/encapsulation.mdEncapsulate Record, Encapsulate Collection, Replace Primitive with Object, Replace Temp with Query, Extract Class, Inline Class, Hide Delegate, Remove Middle Man, Substitute Algorithm
references/moving-features.mdMove Function, Move Field, Move Statements into Function, Move Statements to Callers, Replace Inline Code with Function Call, Slide Statements, Split Loop, Replace Loop with Pipeline, Remove Dead Code
references/organizing-data.mdSplit Variable, Rename Field, Replace Derived Variable with Query, Change Reference to Value, Change Value to Reference, Replace Magic Literal
references/conditional-logic.mdDecompose Conditional, Consolidate Conditional Expression, Replace Nested Conditional with Guard Clauses, Replace Conditional with Polymorphism, Introduce Special Case, Introduce Assertion, Replace Control Flag with Break
references/apis.mdSeparate Query from Modifier, Parameterize Function, Remove Flag Argument, Preserve Whole Object, Replace Parameter with Query, Replace Query with Parameter, Remove Setting Method, Replace Constructor with Factory Function, Replace Function with Command, Replace Command with Function, Return Modified Value, Replace Error Code with Exception, Replace Exception with Precheck
references/inheritance.mdPull Up Method, Pull Up Field, Pull Up Constructor Body, Push Down Method, Push Down Field, Replace Type Code with Subclasses, Remove Subclass, Extract Superclass, Collapse Hierarchy, Replace Subclass with Delegate, Replace Superclass with Delegate

Tone

Practical and unhurried. Refactoring is opportunistic — done in small doses as part of everyday work ("always leave the campsite cleaner than you found it"), not as a scheduled cleanup project. Favor the smallest refactoring that removes the current obstacle over the grand redesign. Economics, not aesthetics: the point of good structure is that it makes the next change cheaper.

Reference map

  • references/principles.md — the two hats, when to refactor (rule of three, preparatory, comprehension, litter-pickup) and when not to, testing discipline, refactoring vs performance. Read when the question is whether/when to refactor, or before a large guided session.
  • references/smells.md — all 24 code smells with the refactorings that cure each. Read in DIAGNOSE mode.
  • The seven catalog files above — sketch, when to use, mechanics, and pitfalls for every refactoring. Read the relevant file in REFACTOR mode, or in ADVISE mode when comparing techniques.

Commands 2

Engage the fowler skill and follow its SKILL.md.

Auto-detect the mode from the request (or honor an explicit leading keyword):

  • diagnose — review the given code for Fowler's code smells and prescribe the catalog refactorings that cure them.
  • refactor — apply a refactoring (named by the user, or chosen from a diagnosis) following the catalog mechanics: small behavior-preserving steps, tests run between steps.
  • advise — answer design questions, compare techniques, or teach a smell or refactoring with examples in the user's language.

$ARGUMENTS

Install the Fowler refactoring review workflow into this repository. The workflow runs claude-code-action on every opened/reopened PR (and on /fowler PR comments), installs the fowler plugin from the jebs-dev-tools marketplace into the CI runner, and delivers a code-smell diagnosis as inline PR comments plus one summary comment with a prioritized refactoring order.

The generic template lives at ${CLAUDE_PLUGIN_ROOT}/templates/fowler-review.yml.

Follow these steps:

  1. Verify the repo. Confirm the current directory is a git repository with a GitHub remote (git remote -v). If not, stop and explain that the workflow only works on GitHub-hosted repos.

  2. Check for an existing install. If .github/workflows/fowler-review.yml already exists, show the user how it differs from the template and ask before overwriting.

  3. Copy the template to .github/workflows/fowler-review.yml (create the directory if needed).

  4. Scope the review (optional). If the user passed path globs as arguments, or asks to limit the review to part of the codebase:

    • Add a paths: filter under the pull_request trigger with those globs (replace the commented example).
    • Update the Scope: paragraph in the prompt to say the review covers ONLY changed files matching those paths and ignores changes elsewhere.

    If no scope was given, leave the template as-is — it reviews all changed files in the PR.

  5. Verify the secret. Run gh secret list and check for CLAUDE_CODE_OAUTH_TOKEN. If it's missing, tell the user to create one:

    claude setup-token   # generates an OAuth token (requires a Claude subscription)
    gh secret set CLAUDE_CODE_OAUTH_TOKEN
    
  6. Summarize. Tell the user: the workflow file installed, how it triggers (auto on PR open/reopen; /fowler comment from an owner/member/collaborator for a re-review), any scoping applied, and whether the secret is in place. Offer to commit the workflow file — but do not commit without their say-so.

$ARGUMENTS

Sponsors

Details

Marketplace
el-feo/ai-context
Source
plugins/fowler
Author
Jeb Coleman
Category
Community

More from el-feo/ai-context

All 8