architecture-migration
Use this skill when refactoring legacy PHP code toward a cleaner architecture. Provides guidance on incremental migrations (Strangler Fig), vertical slicing, writing characterization tests, and managing temporary compatibility shims.
How do I install this agent skill?
npx skills add https://github.com/garrettw/php-arch-skills --skill architecture-migrationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides architectural guidance for incrementally migrating legacy PHP codebases to modern design patterns like the Strangler Fig. The analysis confirms the skill contains only informational documentation with no scripts, executable code, or remote dependencies. No security risks were identified beyond the inherent surface of an agent processing source code for refactoring purposes.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Incremental Architecture Migration for PHP Apps
When to Migrate (and When NOT to)
Big-bang rewrites are risky and halt product momentum. Migrate only when actively building a feature or fixing a complex bug in an area. Do not migrate code that has not been touched in years solely for aesthetic reasons.
| Good Migration Trigger | Poor Migration Trigger |
|---|---|
| Actively building a new feature | "Cleaning up" untouched code |
| Fixing a complex bug in legacy code | Standards-compliance refactor of inactive code |
| Exposing a web feature as an API endpoint | Preference for architecture purity |
Migrate with evolutionary, touched-area changes using vertical slices and temporary compatibility shims. This is the Strangler Fig approach: grow new behavior alongside the legacy system, move behavior across behind seams, and remove the legacy only once it carries nothing (see strangler-fig.md). The delivery mechanics — transitional architecture, event interception, legacy mimics, diverting the flow — are catalogued in legacy-displacement-patterns.md. It is the antidote to the big-bang rewrite, which fails because replacements take too long, users can't wait for features, and much of the old behavior isn't actually wanted.
System Overview
This skill guides the process of moving PHP applications toward a cleaner architecture through incremental, touched-area migrations using vertical slices and temporary compatibility shims. Migration works from the edge inward: lock behavior with characterization tests, extract the use case into a handler behind the existing entry point, then push rules down into the domain (workflow 2). The inside-out order (discover the domain, model aggregates and value objects, define ports, implement use cases, add adapters last) is for designing new code, such as a new context or a greenfield slice, not for moving existing behavior.
Numbered Workflows
1. Evaluating a Migration Trigger
If considering refactoring legacy code into a new architecture:
- Check the Motivation. Are you actively building a new feature in this area, fixing a complex bug, or exposing an existing web feature as an API endpoint? If yes, it is a good trigger. Proceed.
- Evaluate Complexity Fit. Is the domain complex enough to warrant full DDD? If the rules are mostly CRUD with few invariants, favor lean ORM entities over full DDD aggregates. Start simple and evolve only when needed.
- Reject Poor Triggers. Are you just doing it to "clean things up" or to fix a standard violation in code that hasn't been touched in years? If yes, halt the migration.
2. Executing a Vertical Slice Migration
If migrating a specific use case (e.g., one API endpoint or queue job):
- Write Characterization Tests. Lock in the current behavior of the existing legacy code (e.g., the massive Controller) with a high-level integration test. Ensure it passes.
- Extract to Handler. Move the core logic out of the legacy location into a new Application Handler. This is the "grow the new fig alongside the host" step — the legacy still serves other use cases until they too are migrated (see strangler-fig.md).
- Adapt the Edge. Update the original Controller to instantiate the new Handler and pass it the required inputs.
- Verify. Run the characterization tests to prove behavior hasn't changed.
- Push Down to Domain. Extract pure business rules from the Handler into Domain objects or policies.
- Verify Again. Run the tests one final time.
- Cleanup. Remove legacy compatibility shims if all callers are migrated.
3. Managing Compatibility Shims
If introducing a temporary class to bridge old and new code (e.g., a legacy facade implementing a new interface):
- Mark Clearly. Name it clearly as temporary (e.g.,
LegacyUserAdapter). - Define Removal Conditions. Add comments specifying what must happen before it can be removed (e.g., "@todo Remove once all Controllers are migrated to Handlers"). These shims are transitional architecture — they exist only so new and legacy coexist, and you delete them when migration completes (see strangler-fig.md and the delivery patterns in legacy-displacement-patterns.md).
4. Rolling Out Production Schema Changes
If application versions overlap during deployment or a table is too large for a blocking migration, use an expand-migrate-contract rollout. Keep old and new code compatible while data is backfilled in bounded, restartable batches, and delay destructive schema changes until rollback is no longer needed. See production-schema-rollout.md.
Boundaries
Always Do
- Always write characterization tests against the legacy code before extracting logic.
- Always migrate one complete vertical slice at a time, rather than horizontal layers (e.g., don't just "move all controllers" at once).
Ask First
- Ask before introducing a compatibility shim if there is an easy way to fully migrate all legacy callers instead.
Never Do
- Never mix massive feature changes with architectural migrations. Move the code first, prove it works, then change the feature.
- Never leave half-migrated workflows. If you start migrating a use case, finish it.
- Never attempt a big-bang rewrite of the whole system. Use the Strangler Fig approach (see strangler-fig.md): grow the new system alongside the legacy and remove the legacy only once it carries nothing.
- Never pursue Feature Parity — replicating the old system's full "as-is" behavior on a new stack. It drives a big-bang cutover and rebuilds behavior that isn't wanted. Migrate by business capability and needed outcome instead (see legacy-displacement-patterns.md).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/garrettw/php-arch-skills/architecture-migration">View architecture-migration on skillZs</a>