Paying down technical debt. Now. Automatically.
Keep your code under continuous refactoring.
/continuous-refactoring
Improve your code step by step — with guardrails of tests and checks, so you can trust your agent more and more.
A portable agent-skill suite — works with Claude Code, OpenCode, Cursor and more.
Why continuous?
Because debt compounds silently
Every shortcut in the code makes the next change a little riskier — unnoticed, until a refactor comes due that nobody can safely touch anymore. A one-off cleanup project only fixes that short-term: without a lasting routine, the old state returns once the project ends. What actually holds is a process that runs alongside normal development, instead of being treated as the exception.
Because automation makes it cheap
The tools for this — static analysis, automated code rewriting, test coverage — are mature. The real bottleneck isn't the tool, it's running it continuously instead of occasionally. And that's only safe once a deterministic safety net sits in front of every structural change: tests, coding standards, static analysis. Automation — script or agent — shouldn't be trusted blindly; only the net makes every change mechanically verifiable. How that net gets built before structure is touched at all is what the method below shows.
The method
One call is one run: five steps to an opened merge request. Called again and again in autonomous mode, it becomes a loop — every run finds in your tracker what the previous one left behind.
Tap to jump straight there — otherwise the loop keeps turning on its own.
Orient
Reads your tracker: what became of the last merge requests, where work is waiting — and chooses the Track.
Find
Checks what the Track still lacks, and files tickets for it.
Design
Takes the next workable ticket and writes a plan onto it.
Implement
Builds the plan test-first on a branch of its own, until every check is green.
Merge request
Opens the merge request for review — the next run takes its bearings from it.
Example
$ /continuous-refactoring do it yourself
Understood: an autonomous run over all Tracks.
Reconcile… MR !46 (PHPUnit) merged → closed ticket #81
Track choice: Safety Net has 1 workable ticket → took the recommendation
Select: #82 "Introduce PHP CS Fixer" — not in place yet
Posted the plan on #82
Implementing test-first on branch 82-php-cs-fixer… checks green
Opened merge request !47
Status: !47 for #82 is open, CI green.
Next: review and merge — or call again.
- Every step is a decision point: findings, options, a recommendation. You decide — or say "do it yourself" and the suite takes its recommendation.
- Test-driven, step by step — speed doesn't matter.
- Flexible rhythm: from occasional, manually triggered runs to a loop around the clock — your scheduler calls the run autonomously again and again, and a counterpart (human or agent) reviews the merge requests, for example to put leftover token/API budget to good use before it expires at month's end.
The skills
/continuous-refactoring
One run
One call, one run: from an open ticket to an opened merge request. Reconciles, chooses the Track, scans, files tickets, plans and implements — and asks at every decision point, unless you say "do it yourself". On a new project, a short onboarding first sets up how your tracker is reached.
/continuous-housekeeping
For the schedule
The Housekeeping Track alone, no Track choice — which makes it the command to put on a schedule. Sets up the template and the first ticket on its first call, then works whichever Housekeeping ticket is due.
Everything else — scanning, selecting, planning, implementing, onboarding — is reference material these two load when a run reaches it. Where your project has its own skills for planning and implementing, the suite recommends those and uses its own procedures only as a fallback.
One run, one Track
Every run works one ticket from one of four Tracks. The recommendation is the first in a fixed order that has work — or you name it in the call.
Sets up the deterministic checks — test runner, coding standards, static analysis, CI — before an agent touches structure. An autonomous run moves on only once it's in place.
Sets up further quality and security tooling once the Safety Net is in place — coverage floor, mess detection, stricter static analysis, and more.
Recurring maintenance as one standing ticket with a due date — dependency currency, a dependency audit, deprecation cleanup, a secret scan, plus small refactoring ideas left on it as comments.
Structural refactoring — works the tickets that ask for it, or explores the code for hot spots and deepening opportunities and proposes the strongest finds as tickets.
More on runs, Tracks, tooling, architecture and FAQ: documentation.
Installation
First clone this repo's current release, then wire the two skills into a target project via symlink:
git clone --branch 0.10.0 https://github.com/Art4/continuous-refactoring.git
mkdir -p <target>/.agents/skills
ln -s /path/to/continuous-refactoring/skills/* <target>/.agents/skills/
The core is language-neutral, with tools delivered in Packs: one for every project, one for PHP projects (code style, Rector, PHPStan and more — with the diagram of what comes after what), and one for Twig. A tool the suite does not know is added as a Pack of your own.
The PHP Pack is grounded in over 20 years of PHP experience by Artur Weigandt and is continuously updated to current best practice. When a maintainer declines a tool, that is recorded with the reason and not proposed again. Housekeeping's recurring re-check keeps suggesting further steps toward maintainability, testability, and security — including a test-coverage floor that only ever tightens and, on request, OWASP Top 10 coverage via Semgrep or mutation testing with Infection.
Moving to a newer release: in the clone, git fetch --tags && git checkout <tag> — the symlinks then point at the new state automatically. Releases: GitHub.
Moving over from 0.6.0? Remove the symlinks of the removed skills, delete the suite's old state files in its scratch folder, and call /continuous-refactoring once — the onboarding adds what is missing. Details in the FAQ.
FAQ
Does a human stay in the loop?
By default at every step: a run lays out findings, options and a recommendation at every decision point and writes nothing to your tracker, forge or repository that you didn't approve. Say "do it yourself" and it takes its own recommendations — but it never merges on its own: every run ends at a merge request that a human, or another agent acting as reviewer, reviews and merges. Where a ticket needs a decision that is hard to reverse, or would change behaviour, the suite leaves an open question on the ticket and waits for your answer there. And a change to your AGENTS.md always waits for you.
Why so much tooling instead of just starting the refactor?
Because an LLM can't be trusted to make sweeping changes to existing code safely on its own. The tooling tree builds up deterministic checks first — static analysis, coding standards, a working test runner — before an agent is allowed to touch the code, so a wrong or overconfident change gets caught mechanically instead of relying on the agent to notice its own mistake. Almost all of it can be declined — at the cost of code quality and backward compatibility: fewer gates means a coarser safety net for catching a bad change before it merges. And the order isn't forced on you: name the Track you want in the call.
Which tools does the suite suggest?
A selection of the tools the suite proposes when a project doesn't have them set up yet — it works with whatever tooling is already in place, too. Tools marked on request are never offered unasked: name one in the call ("set up Semgrep").
- PHP CS Fixer — Automated code formatting, so later automated changes (e.g. from Rector) land already properly styled.
- PHPUnit — The project's test runner, paired with a self-tightening coverage floor: test coverage can only rise, never drop.
- PHPStan — Static type analysis across 11 progressively stricter levels (0–10) — the suite's default path for new projects.
- Psalm — An alternative to PHPStan: recognized and continued where a project already uses it, but not proposed fresh.
- Psalm Taint Analysis — Follows data from untrusted input to dangerous operations (SQL injection, XSS, and similar) — on request, for projects on PHPStan, too.
- PHPMD — Measures cyclomatic complexity and other code-quality metrics — feeds signals into deciding what to refactor next.
- Rector — Automated PHP code rewriting: language-version upgrades, dead-code removal, increasing type coverage, code-quality improvements. Builds on PHPStan or Psalm.
- Roave Backward Compatibility Check — Compares the code with the last release and fails on a break — for projects that promise SemVer, before any restructuring starts.
- Infection — Mutation testing, on request: plants small faults in the code and checks that the tests catch them.
- Secret Detection — A CI gate against accidentally committed credentials/tokens/secrets, on request — tool-agnostic; Housekeeping scans the Git history for secrets either way.
- Semgrep — Static analysis using ready-made rules for the OWASP Top 10 security risks (e.g. injection, misconfiguration), on request.
- Twig-CS-Fixer — Code style for Twig templates, once a PHP project uses Twig.
- TwigStan — Static analysis for Twig templates, building on PHPStan.
Every tool with its Role and the order it comes in: tooling overview.