Continuous Refactoring
Paying down technical debt. Now. Automatically.
🌐 continuous-refactoring.de
A portable agent-skill suite for coding agents — Claude Code,
Cursor, OpenCode — that keeps a software project under continuous refactoring. Each call is one run: it leads from the
project's open refactoring tickets to one opened merge request, and stops there. You get more work
done by calling again.
flowchart LR
Reconcile --> Track[Choose a Track]
Track --> Scan
Scan --> File[File tickets]
File --> Select[Select a ticket]
Select --> Design
Design --> Implement
Implement --> MR[Merge request]
Every link of that chain is a decision point: the suite shows what it found, the options, and
the one it recommends. By default you decide each time. Say in the call that it should do the run
itself, and it takes its own recommendation at every point instead.
The suite keeps no state of its own. Your open tickets are the worklist; merge requests,
declined work and the standing Housekeeping ticket are found by searching your tracker and your
forge on every run. What you change there by hand is simply what the next run finds.
The core is language-neutral, with tools delivered in Packs. A generic Pack applies to every project; the first language Pack is a general PHP project (code style, Rector, PHPStan, PHPMD and more, with the diagram of what comes after what), grounded in over 20 years of PHP experience and kept up to date with current best practice; a Twig Pack adds the templates of a PHP project that uses Twig. Tools you already run — Psalm instead of PHPStan, Laravel Pint instead of PHP CS Fixer — are recognised and not replaced, and a tool the suite does not know joins through a Pack of your own. The tooling overview lists every Role, Tool and Pack.
How it works
A run spends itself on one of four Tracks. The suite sorts your open tickets into them and
recommends the first one, in this fixed order, that has something to work on:
| Track | What it does | Recommended when |
|---|
| Safety Net | Sets up the deterministic checks (test runner, coding standards, static analysis, CI, and a backward-compatibility check where your project promises SemVer) that catch a regression before an agent's own judgement has to | one of its tickets can be worked, or the Track was never scanned |
| Guardrails | Adds further quality and security tooling once the Safety Net is in place (coverage floor, mess detection, stricter static analysis, …) — a few tools, such as security scanners, only when you ask for them — and takes in a large rule set — a code style, PHPMD — rule by rule, in merge requests a person can review | the same, once Safety Net is fulfilled |
| Housekeeping | Recurring maintenance — dependency currency, tooling-deprecation cleanup, a secret scan over the Git history — plus the small refactoring ideas left as comments on its ticket | its open ticket is due, or it is not set up yet |
| Investigation | Structural refactoring: works the tickets that ask for one, or explores the code for hot spots and deepening opportunities and proposes tickets | nothing above has work |
Each of the two tooling Tracks is scanned once. From then on its tickets are the record: a tool without an open ticket
counts as done, and a recurring Housekeeping task re-checks whether a tool went missing. Before a
ticket is worked the suite checks again whether the work is still needed — a tool you set up by hand
closes its ticket instead of being set up twice.
While a run is going, the suite tells you what it is doing: a sentence before and after every step,
and one line for every change to your tracker, your forge or your repository. Details:
Run playbook, Track playbook,
Architecture.
Skills
| Skill | Purpose |
|---|
continuous-refactoring | One run, from the open tickets to an opened merge request |
continuous-housekeeping | One Housekeeping run and nothing else — no Track choice, so it can be put on a schedule |
You or an agent may start either one — an agent from a scheduled job, say, or one that hands each run
to a subagent and reviews its merge request before calling the next — a Driver
(playbook).
Everything else — choosing a Track, 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.
Installing in a target project
Two symlinks, side by side in the target's skills folder:
mkdir -p <target>/.agents/skills
ln -s /path/to/continuous-refactoring/skills/continuous-refactoring <target>/.agents/skills/
ln -s /path/to/continuous-refactoring/skills/continuous-housekeeping <target>/.agents/skills/
Or copy the two folders. To make the suite available everywhere, link both into your agent's global
skills folder (e.g. ~/.config/opencode/skills/) the same way. The two belong together:
continuous-housekeeping reads files of continuous-refactoring.
Works with other skills, needs none. The suite is compatible with engineering skills such as mattpocock/skills (see aihero.dev): where a project has skills for planning or implementing, a run offers to use them. Without any, the first /continuous-refactoring writes the issue-tracker file itself, and plans and implements its own way.
Any issue tracker works that docs/agents/issue-tracker.md describes. GitHub, GitLab and local Markdown files come with a ready-made template. For another one — Redmine, Jira — onboarding asks how the suite's few operations work there (how tickets are searched, how a finished one is recognised) and writes the answers into that file. Tickets and merge requests may live in different systems: the tracker is whatever that file describes, merge requests live where the Git remote points.
Quick start
- Call
/continuous-refactoring. On a project the suite has not seen, it first asks where your tickets live and how the operations work there, and writes that as one section into docs/agents/issue-tracker.md — commit that file. The run ends there; commit, then call it again.
- Answer the decision points. Each comes with a recommendation, so "yes" moves on. Say "carry on yourself from here" at any point and the rest of the run takes its own recommendations.
- Or let it run by itself:
/continuous-refactoring do it yourself. One call then takes a ticket from selection to an opened merge request.
- Steer it in the call, in your own words: a Track ("work on Guardrails"), a restriction ("only the Rector tools"), a ticket ("ticket 42").
- Review and merge what the suite opens. Nothing limits how many merge requests are open at once; how much runs in parallel is your decision.
- Housekeeping:
/continuous-housekeeping sets its mechanism up on the first call and works the due ticket afterwards. The suite schedules nothing itself — point your own scheduler (/schedule, /loop, cron) at either command.
Upgrading
Pull the suite's checkout; the symlinks follow it. What a version changes, and the steps a breaking
change needs in your project, are in the CHANGELOG — coming from 0.6.0 or earlier,
read the 0.7.0 entry first.
Where things live
Everything is in your project, your tracker and your forge — nothing in the conversation, nothing in files of the suite.
- Work to do: open tickets on your tracker
- Work in review: open merge requests on your forge, found from their tickets
- Declined work: a closed ticket or a file with the reason, in the place your tracker section names under Rejected
- Recurring maintenance: the Housekeeping template, a file in your repository, and the one open Housekeeping ticket made from it
- How the tracker is reached: the
## Refactoring operations section of docs/agents/issue-tracker.md, including the optional bullets — a Candidate mark, Ready after plan, Rejected
- Tools of your own: a Pack in your repository, named under Tooling Pack in that section
- Focus areas and refactoring goal: two lines you add to
AGENTS.md (or CLAUDE.md), any time
- Domain language and decisions: your own glossary and ADR directory, where your project keeps them
Documentation
| Doc | For |
|---|
| Run playbook | Steering a run as a human — the call, the decision points, how a run ends |
| Track playbook | How the four Tracks are chosen, scanned and worked |
| Own-tool playbook | Adding a tool the suite does not know, as a Pack of your own |
| Housekeeping playbook | The maintenance Track — template, standing ticket, rhythm |
| Reviewer-loop playbook | Observing a run from a separate reviewer agent |
| Tooling | Every Role, Tool and Pack the suite knows, with a diagram per Pack |
| Architecture | The two skills, their references, the tooling tree |
| FAQ | Why the suite is designed the way it is |
| Known limitations | Limits without a suite-side fix, plus troubleshooting |
| Operations reference |
Contributing
Bug reports, feature requests, and pull requests are welcome — see CONTRIBUTING.md.
License
MIT — see LICENSE.
Built by Artur Weigandt — PHP refactoring, freelance.
