From agent-almanac
Executes gradual architecture transformations using strangler fig migration, chrysalis phases, and interface preservation. For monolith-to-microservices, subsystem replacements, or any change requiring operational continuity.
npx claudepluginhub pjt222/agent-almanacThis skill uses the workspace's default tool permissions.
---
Orchestrates full migration workflows from current state analysis through planning, incremental implementation, and verification for technologies, platforms, and architecture patterns with rollback planning.
Orchestrates complete migration workflows for frameworks (e.g., Vue 2→3, Express→Fastify), databases (MySQL→PostgreSQL), and architectures (REST→GraphQL, monolith→microservices) with analysis, incremental execution, and rollback.
Manages architecture evolution by analyzing change impacts, generating ADRs, planning migrations, and coordinating execution for component additions, deprecations, and breaking changes.
Share bugs, ideas, or general feedback.
Execute structural metamorphosis — transforming a system's architecture from its current form to a target form while maintaining operational continuity. Uses strangler fig migration, chrysalis phases, and interface preservation to ensure the system never stops functioning during transformation.
assess-form) classified the system as READYassess-form or equivalent analysis)Plan the metamorphosis path from current form to target form.
scale-colony for colony budding)Metamorphosis Patterns:
┌───────────────┬───────────────────────────────────────────────────┐
│ Strangler Fig │ New code intercepts routes one by one; │
│ │ old code handles everything else until replaced │
│ │ ┌──────────┐ │
│ │ │ Old ████ │ → │ Old ██ New ██ │ → │ New ████ │ │
│ │ └──────────┘ │
├───────────────┼───────────────────────────────────────────────────┤
│ Chrysalis │ Wrap old system in new interface; replace │
│ │ internals while external shell stays stable │
│ │ ┌──────────┐ ┌──[new]───┐ ┌──[new]───┐ │
│ │ │ old core │ → │ old core │ → │ new core │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │
├───────────────┼───────────────────────────────────────────────────┤
│ Budding │ New system runs in parallel; traffic shifts │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │ │ Old │ │ New │ → │ Old │ │ New │ │
│ │ │ 100% │ │ 0% │ │ 0% │ │ 100% │ │
│ │ └──────┘ └──────┘ └──────┘ └──────┘ │
└───────────────┴───────────────────────────────────────────────────┘
Expected: A transformation blueprint showing intermediate forms, seams, the chosen metamorphosis pattern, and the interface preservation strategy. Each step is concrete and testable.
On failure: If no clean seam can be found, the system may need preliminary dissolution (see dissolve-form) to create seams before transformation. If the intermediate forms aren't operationally viable, the transformation steps are too large — decompose into smaller increments.
Construct the temporary infrastructure that supports metamorphosis.
Expected: Scaffolding infrastructure (anti-corruption layer, parallel running, rollback, validation) is in place before any transformation begins. The scaffolding itself is tested and verified.
On failure: If scaffolding is too expensive, simplify: the minimum viable scaffolding is a feature flag and a rollback procedure. Anti-corruption layers and parallel running add safety but are not always necessary for smaller transformations.
Migrate functionality from old form to new form incrementally.
Expected: Functionality migrates component by component with validation at each step. The system is always operational. Each cutover builds confidence for the next.
On failure: If parallel running reveals discrepancies, the new implementation has a bug — fix it before cutting over. If a cutover causes performance degradation, the new component may need optimization or the anti-corruption layer is adding too much overhead. If the team loses confidence mid-migration, pause and stabilize — a half-migrated system in a known state is far better than a rushed full migration.
Navigate the most vulnerable period — when the system is between forms.
Expected: The chrysalis phase is managed as a deliberate, time-bounded period with increased discipline and monitoring. The team understands that temporary complexity is the cost of safe transformation.
On failure: If the chrysalis phase drags on too long, the hybrid state becomes the new normal — which is worse than either old or new. Set a time limit. If the limit is reached, either accelerate the remaining migration or accept the hybrid state as the "new form" and stabilize it.
Finish the transformation and remove scaffolding.
Expected: The transformation is complete. The system operates in its new form. Scaffolding is removed. Documentation is updated. The team has captured learnings for future transformations.
On failure: If the new form is unstable after cutover, maintain the rollback path and continue stabilization. If stabilization takes more than the planned period, there may be a design issue in the new architecture — consider whether targeted fixes or a partial rollback of the most problematic component is appropriate.
assess-form — prerequisite assessment that determines if the system is ready for transformationdissolve-form — for systems too rigid to transform directly; dissolution creates the seams needed hererepair-damage — recovery skill for when transformation introduces damageshift-camouflage — surface adaptation that may suffice without deep architectural changecoordinate-swarm — swarm coordination informs the sequencing of transformation across distributed systemsscale-colony — growth pressure is a common trigger for architectural adaptationimplement-gitops-workflow — GitOps provides the deployment infrastructure for progressive cutoverreview-software-architecture — complementary review skill for evaluating the target architecture