Architecture Evolve

/architecture-evolve — Architecture Migration

Plan and document an architecture migration. Produces an ADR explaining the decision, a target-state ARCHITECTURE.md, a phased migration plan, fitness functions to enforce the transition, and a rollback strategy.

When to use

• Cross-technology migration: REST → gRPC, monolith → microservices, on-prem → cloud, framework upgrade
• Major redesign initiative driven by tech debt or scale
• Strategic platform shift: change of database engine, message bus, identity provider, observability vendor

Not for

• New feature design → /architecture-design
• Documenting existing state without migration intent → /architecture-analyze
• Implementation execution (use this skill's output as input to /plan)
• Routine library/version upgrades → /migrate

Step 1 — Receive Input and Establish Baseline

Extract: From → To (current technology / pattern → target), Why (driver: tech debt, scale, cost, compliance, strategic), Scope (system-wide, single service, single module), Constraints (timeline, compatibility, downtime budget), Stakeholders.

Confirm a baseline exists (or run /architecture-analyze first). Migration without a documented current state is high-risk — the second-order effects are invisible. If no baseline → refuse and surface: "Run /architecture-analyze first to establish baseline."

Step 2 — Define Target State NFRs

Agent(solution-architect). NFRs for the target state, with delta vs current:

Migration only makes sense if the delta justifies the cost. Present target NFRs to the user — if the user accepts a current → target step that NFRs alone do not justify, document the strategic rationale explicitly.

Step 3 — Migration ADR

Agent(solution-architect). Architecture Decision Record:

• Status: Proposed
• Context: Why the migration is needed (technical + business drivers)
• Decision: From → To, including the migration pattern (strangler fig / expand-contract / branch by abstraction / parallel run)
• Consequences: positive (target NFRs achieved, debt resolved), negative (transitional complexity, double-running costs, team learning curve), neutral (process/tooling changes)
• Alternatives Considered: keep-as-is, smaller-scope migration, different target tech, deferred timing

Step 4 — Target-State Architecture

Agent(system-architect). Produce:

• C4 diagrams (Context + Container) of the target state
• Component inventory of the target with responsibilities + tech stack
• Data flow diagrams for critical target-state paths
• Integration points + new contracts (API, events, schemas)
• Update ARCHITECTURE.md to reflect target state (in a sibling ARCHITECTURE-TARGET.md until migration completes — keeps the live doc accurate)

Step 5 — Phased Migration Plan

Pick a migration pattern fit for the situation:

Phase structure (typical):

For schema migrations, use expand-contract semantics — never break-then-fix.

Step 6 — Fitness Functions

Automated architectural checks that enforce the transition:

Fitness functions catch regression early — without them, the migration drifts off-target invisibly.

Step 7 — Rollback Strategy

For each phase, document:

• Detection signal: alert that fires (latency, error rate, divergence, manual call)
• Decision threshold: when to roll back vs investigate vs press on
• Rollback action: exact runbook step (config flag, traffic route change, schema revert, code revert)
• Time-to-rollback target: should be measured in minutes for traffic, hours for schema, days for code

A migration without explicit rollback per phase is a one-way door. Reject the plan if rollback is missing for any phase that touches production.

Step 8 — Quality Gates

• Migration pattern matches the change (no parallel-run for trivial refactors; no strangler-fig for schema changes)
• Each phase has explicit exit criteria + rollback procedure
• Target NFRs are concrete and delta-justified vs current
• Fitness functions cover the structural invariants that the migration relies on
• Dual-running cost is estimated (cloud cost, ops load, team capacity)
• Decommission phase is included (otherwise the old system lingers as debt)
• Security review covers BOTH systems during dual-run and the new system post-cutover
• Data migration (if any) has explicit backfill + verification plan

Step 9 — Engineering Estimates

Per-phase estimates to feed /plan:

Step 10 — Present and Persist

Present: migration ADR, target-state diagrams, phased plan + rollback per phase, fitness functions, total cost estimate, total timeline. Wait for user approval. The user may request changes — common ones: longer canary, additional shadow phase, smaller initial scope.

After approval, save:

1. ADR → docs/adr/ADR-NNN-migrate-[from]-to-[to].md
2. Target architecture → docs/architecture/ARCHITECTURE-TARGET.md (becomes live ARCHITECTURE.md at end of migration)
3. Migration plan → docs/architecture/migrations/[migration-name]/PLAN.md
4. Rollback playbook → docs/architecture/migrations/[migration-name]/ROLLBACK.md
5. Fitness functions → as actual code (CI checks) and as doc docs/architecture/migrations/[migration-name]/FITNESS.md

Step 11 — Handoff

Run /plan for each phase. Phases run as separate /develop cycles to keep blast radius small.

Integration

• Input from: /architecture-analyze (current state baseline), strategic initiative
• Followed by: /plan (per-phase decomposition), /develop (per-phase execution)
• Roles: Agent(solution-architect) (ADR), Agent(system-architect) (target state), plus Agent(cloud-architect) / Agent(devops-architect) for infra/pipeline-touching migrations
• Output style: ${CLAUDE_PLUGIN_ROOT}/output-styles/design-pack.md
• Templates: ${CLAUDE_PLUGIN_ROOT}/skills/architecture/assets/ — adr-template.md, c4-mermaid-template.md, nfr-template.md, tech-debt-register-template.md
• Related skills: /migrate (library/schema-level migrations with RALF rollback gate; smaller scope than architecture-level evolution)
• Knowledge: @owasp-coverage (security during dual-run), @observability-methods (fitness functions for telemetry parity), @supply-chain-security (target-state SBOM/SLSA)