
fowler
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-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add el-feo/ai-context.
Contents
Discovered from sourceSkills 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 intent | Mode | Read first |
|---|---|---|
| "What's wrong with this code?" / review for smells | DIAGNOSE | references/smells.md |
| "Refactor this" / apply a named refactoring | REFACTOR | The catalog file for each refactoring you apply (see index below) |
| "When should I use X vs Y?" / explain a smell or technique | ADVISE | The 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
- Read the code. Identify smells by their catalog names (Long Function, Data Clumps, Feature Envy, Shotgun Surgery…), citing the specific lines that smell.
- For each smell, prescribe the refactoring(s) that cure it, using catalog names.
- Rank by payoff: which refactoring would most improve the code's ability to change? Lead with that.
- 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
- Confirm the safety net: identify the tests that cover the code. If coverage is missing, offer to write characterization tests first.
- Read the mechanics for the chosen refactoring in its catalog file.
- 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.
- If a step reveals a prerequisite (e.g., Extract Function before Move Function), do the prerequisite first and say why.
- 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:
| File | Refactorings |
|---|---|
| references/first-set.md | Extract 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.md | Encapsulate 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.md | Move 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.md | Split Variable, Rename Field, Replace Derived Variable with Query, Change Reference to Value, Change Value to Reference, Replace Magic Literal |
| references/conditional-logic.md | Decompose 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.md | Separate 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.md | Pull 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:
-
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. -
Check for an existing install. If
.github/workflows/fowler-review.ymlalready exists, show the user how it differs from the template and ask before overwriting. -
Copy the template to
.github/workflows/fowler-review.yml(create the directory if needed). -
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 thepull_requesttrigger 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.
- Add a
-
Verify the secret. Run
gh secret listand check forCLAUDE_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 -
Summarize. Tell the user: the workflow file installed, how it triggers (auto on PR open/reopen;
/fowlercomment 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