adapt-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

# Adapt Architecture

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.

## When to Use

- Form assessment (see `assess-form`) classified the system as READY
- A system must evolve its architecture to meet new requirements without downtime
- Migrating from monolith to microservices (or the reverse)
- Replacing a core subsystem while dependent systems continue operating
- Evolving a data model while maintaining backward compatibility
- Any architectural change that must be gradual rather than big-bang

## Inputs

- **Required**: Current form assessment (from `assess-form` or equivalent analysis)
- **Required**: Target architecture (what the system should become)
- **Required**: Operational continuity requirements (what must not break during transformation)
- **Optional**: Available transformation budget (time, people, compute)
- **Optional**: Rollback requirements (how far back must we be able to retreat?)
- **Optional**: Parallel running duration (how long to run old and new simultaneously)

## Procedure

### Step 1: Design the Transformation Blueprint

Plan the metamorphosis path from current form to target form.

1. Map the transformation as a sequence of intermediate forms:
   - Current form → Intermediate form 1 → ... → Target form
   - Each intermediate form must be operationally viable (can serve traffic, pass tests)
   - No intermediate form should be harder to maintain than the current form
2. Identify the transformation seams:
   - Where can the current form be "cut" to insert the new architecture?
   - Natural seams: existing interfaces, module boundaries, data partitions
   - Artificial seams: interfaces created specifically to enable the cut (anti-corruption layers)
3. Choose the metamorphosis pattern:
   - **Strangler fig**: new system grows around the old, gradually replacing it
   - **Chrysalis**: old system is wrapped in a new shell; internals replaced while shell preserves external interface
   - **Budding**: new system grows alongside the old; traffic gradually shifts (see `scale-colony` for colony budding)
   - **Metamorphic migration**: phased replacement of components in dependency order (leaves first, roots last)
4. Design the interface preservation layer:
   - External consumers must not experience disruption
   - API versioning, backward-compatible contracts, adapter patterns
   - The preservation layer is temporary scaffolding — plan its removal

```text
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% │         │
│               │ └──────┘ └──────┘     └──────┘ └──────┘         │
└───────────────┴───────────────────────────────────────────────────┘
```

**Got:** A transformation blueprint showing intermediate forms, seams, the chosen metamorphosis pattern, and the interface preservation strategy. Each step is concrete and testable.

**If fail:** 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.

### Step 2: Build the Scaffolding

Construct the temporary infrastructure that supports metamorphosis.

1. Create the anti-corruption layer:
   - A thin translation layer between the old and new systems
   - Routes requests to the appropriate system (old or new) based on migration state
   - Translates data formats between old and new representations
   - This layer is the "cocoon" that protects the transformation
2. Set up parallel running infrastructure:
   - Both old and new systems must be deployable simultaneously
   - Feature flags control which system handles which traffic
   - Comparison mechanisms validate that old and new produce equivalent results
3. Establish rollback checkpoints:
   - At each intermediate form, verify that rollback to the previous form is possible
   - Rollback must be faster than the forward transformation step
   - Data migration must be reversible (or data must be dual-written during transition)
4. Build the validation harness:
   - Automated tests that verify operational continuity at each intermediate form
   - Performance benchmarks that detect regression
   - Data integrity checks that catch migration errors

**Got:** Scaffolding infrastructure (anti-corruption layer, parallel running, rollback, validation) is in place before any transformation begins. The scaffolding itself is tested and verified.

**If fail:** 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.

### Step 3: Execute Progressive Cutover

Migrate functionality from old form to new form incrementally.

1. Order components for migration:
   - Start with the least-coupled, lowest-risk component (build confidence)
   - Progress toward more critical, more coupled components
   - Save the most coupled/critical component for last (by which point the team has experience)
2. For each component:
   a. Implement the new version behind the anti-corruption layer
   b. Run parallel: both old and new process the same inputs
   c. Compare outputs — they should be equivalent (or the differences should be expected and documented)
   d. When confident, switch traffic to the new version (feature flag flip)
   e. Monitor for anomalies (increase monitoring sensitivity post-cutover)
   f. After a stability period, decommission the old version of this component
3. Maintain continuous delivery throughout:
   - Each cutover step is a normal deployment, not a special event
   - The system is always in a known, tested, operational state
   - If a cutover causes issues, roll back to the previous state (which is still operational)

From pjt222/agent-almanac, MIT.

More from pjt222/agent-almanac