legacy-modernization-playbook — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited legacy-modernization-playbook (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
You have inherited a production system with these properties:
This skill is the senior architect's checklist for the first 1–4 weeks. It does not tell you HOW to do each thing (other skills in this kit cover the how). It tells you WHAT to do, in WHAT ORDER, and crucially WHAT NOT TO DO.
The one rule that overrides every other rule:
Don't try to modernize the code. Build the safety net around it. Modernization comes later, after the lights stay on reliably.
The strongest temptation is to "just refactor this part" or "rewrite this in a framework." Resist. The best return on engineering effort, by an order of magnitude, is in the layer above the code: deployment, monitoring, backups, audit trail.
This is the order. Do them in sequence. Do not skip ahead.
Before you do anything else, audit:
shared-hosting-recon (separate skill in this kit). Output: a structured Markdown document covering disabled PHP functions, available APIs, /tmp quirks, security holes.Output: a single document (e.g., audit-2026-05.md) committed to wherever you keep working notes. Refer to it often.
Don't skip this. Every architectural decision you make later will reference findings from this audit.
You don't have a reliable source of truth yet. Establish one.
<project>-production, mark it private, push it..git, .svn, anything 100 MB+.* -text) so that subsequent diffs reflect content, not line-ending churn.Output: a private GitHub (or GitLab/whatever) repository, byte-for-byte mirroring production code at a known timestamp.
Why this is Phase 1: every subsequent step depends on having a known-good baseline. You cannot deploy if you don't know what's currently deployed. You cannot rollback if you don't know what to roll back to.
Before any deploy automation. Before any code changes. Backups first.
mysqldump cron, gzipped, uploaded to off-server storage (B2, S3, Dropbox — whatever you control). 30-day retention minimum.Why backups go before deploys: a deploy can break things. If the deploy breaks things and you don't have backups, you've now broken production with no recovery. Backups are the prerequisite, not the dessert.
Your audit (Phase 0) surfaced security holes. Fix them now, before automation goes live, because automation will then preserve their absence.
Common findings, ordered by typical severity:
phpinfo.php, info.php). Delete.mysqldumper.php, adminer.php outside its proper directory). Move outside web root.*.sql, dump.sql.gz in the web root). Move outside web root.*.bak, *~, *_old.php). Audit; delete or move..htaccess or remove.This phase is grunt work. Do it carefully. Document each thing you removed. If you accidentally remove something the previous developer was actively using, you'll need to put it back.
NOW you can build deployment automation. With backups in place (Phase 2) and the security floor raised (Phase 3), this is safe.
Use the solo-engineer-pipeline skill. Specifically for shared-hosting environments without shell access. Outputs: _deploy.php, smoke tests, GitHub Actions for lint + deploy + monitoring.
Important order within Phase 4:
The pipeline can deploy. Now ensure you know if prod is broken.
You now know within 15 minutes if production is broken. Before this phase, your Mean Time to Detect was however long until a user complained.
Now make every change traceable.
You can now answer "what was different about the registration page on October 14?" — to the byte.
Write the runbooks. Two specifically:
Use the bilingual-exec-report skill if a status report for non-technical leadership is needed.
These are the temptations. Avoid each one for at least 6 months.
Especially: don't refactor anything you don't deeply understand. Especially-especially: don't refactor with no test coverage. The code that looks "ugly" or "wrong" probably encodes 17 years of bug fixes, edge-case handling, and reverse-engineered customer requirements that nobody documented. Touch it now and you'll discover this the painful way.
Migrating an existing legacy app to a framework is one of the most cited engineering disasters in our industry. The pattern: begins with optimism, takes 3x longer than estimated, never quite finishes, leaves a half-migrated codebase that's worse than the original. Don't.
If you really want a framework: build the new system in parallel, route specific URLs at it, migrate one feature at a time over 12–18 months. The legacy system continues to serve everything else.
PHP 5.6 → PHP 8 in place is a 2-month project minimum. There are silent behaviour changes (string-to-number comparisons, default error reporting, deprecated functions). Without test coverage you cannot verify the upgrade didn't break anything. Defer this until after Phase 7 + you have monitoring + you're ready to spend the time.
Stabilize the system first. Adding features on top of a system with no safety net means each feature ships at risk. Adding features after Phases 0–7 means each feature ships through tests and rollback safety. Same feature, different risk profile.
Legacy code is often untestable without significant refactoring (see "Don't refactor"). Don't attempt comprehensive test coverage of the existing code. Instead:
php -l syntax checks via CI — basically free, catches dumb errors.Phases 0–7 takes 1–4 weeks of solo work, depending on the system size and the host's quirks. Don't compress it into a weekend. The goal is reliability; rushing introduces the same kinds of unsafe changes you're building the safety net to prevent.
The instinct is to under-communicate technical work. Resist. Here's the framing that works:
Use the bilingual-exec-report skill for a formal status report.
You now have:
What you DON'T have (and what's fine):
You have built the foundation. The legacy system is now safe to operate. Modernization is the next 12–24 months, done in carefully scoped projects, each one bounded and reversible because of the foundation you just built.
The senior engineer's instinct, when handed a legacy system, is something like: "OK, I'll just refactor this module first, then upgrade PHP, then add tests, then..." This produces 6 months of half-finished work and a system that's now both legacy AND unstable.
The right instinct, learned the hard way: do nothing to the code. Build the safety net first. Then, once the system is observable, deployable, and recoverable, consider modernization — slowly, in scoped projects, with the safety net catching mistakes.
This is the playbook every senior architect writes for themselves after their first painful encounter with legacy modernization. Most engineers have to learn it the slow way. This skill compresses it into a checklist.
| Phase | Description | Time |
|---|---|---|
| 0 | Recon | 2–4 hours |
| 1 | Source of truth | 2–4 hours |
| 2 | Off-server backups | 2–4 hours |
| 3 | Security cleanup | 2–6 hours |
| 4 | Deploy pipeline | 4–8 hours |
| 5 | Continuous monitoring | 1–2 hours |
| 6 | Audit trail | 2–4 hours |
| 7 | Documentation | 4–8 hours |
| Total | Phases 0–7 | ~20–40 hours of focused work |
For a solo engineer working evenings/weekends: ~3–6 weeks elapsed time. Worth it. The system is yours to operate sustainably from here.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.