---
name: project-migration
description: Plan, execute, verify, cut over, and safely retire migrations of existing applications between hosting, cloud, database, authentication, storage, DNS, or managed-service providers. Use when moving or replacing application runtime, persistent data, files, authentication, domains, secrets, callbacks, scheduled work, or external integrations while preserving user-visible behavior, rollback, and source safety.
---

# Project Migration

Preserve required state and user-visible behavior. Do not reduce a migration to
copying infrastructure.

Treat these as invariants:

- The repository is not necessarily the complete architecture.
- A successful deployment is not proof that the application migrated.
- Configuration presence is not proof that a credential or integration works.
- Source retirement normally follows replacement verification. An informed
  user may explicitly accept irreversible loss, but that is not verification.

## Operating Contract

- Discover before mutating.
- Keep source and destination identifiers explicit.
- Preserve unrelated repository and platform state.
- Separate direct evidence, inference, unknowns, and user-accepted limitations.
- Match verification depth to data loss, security, traffic, and rollback risk.
- Keep the source usable until the replacement is demonstrated or the user
  explicitly accepts the loss of rollback.
- Do not encode a provider's previously fixed bug as a permanent workaround.

## Provider Handoff

Keep orchestration provider-agnostic and delegate implementation to the current
provider-specific skill, official CLI, API, or documentation.

For every active provider:

1. Load its current skill or instructions.
2. Discover current capabilities instead of assuming historical limitations.
3. Use provider-native read-only inventory before proposing mutations.
4. Follow its authorization and production-safety rules.
5. Convert provider output into migration evidence without overstating it.

When Anyhost is a source or destination, read `../anyhost/SKILL.md` before
operating it. For an Anyhost destination, use its current `doctor` workflow for
the selected environment. Treat `unknown` literally. Anyhost target diagnostics
do not prove source retirement, authentication, OAuth callbacks, payment
webhooks, or end-to-end user journeys.

Read `references/verification-patterns.md` only for capabilities actually
discovered in the project.

## 1. Discover The Real System

Inspect both the repository and connected control planes:

- repository remote, branch, uncommitted changes, build and runtime config;
- hosting projects, environments, deployments, domains, DNS and TLS;
- environment-variable names, owners and generated values;
- databases, object storage, caches, queues and background work;
- authentication providers, sessions, callbacks and protected routes;
- payments, email, analytics, webhooks and external consumers;
- current production behavior, traffic path and rollback options.

Do not infer absence only because an SDK or config file is missing. OAuth
secrets, DNS records, provider settings and webhook destinations may exist only
in an external control plane.

Create one dependency ledger and add only capabilities that exist:

| Capability | Source | Destination | Action | Required state | Risk | Verification | Rollback | Retirement gate | Status |
|---|---|---|---|---|---|---|---|---|---|

Classify each action as:

- `move`: preserve the capability at the destination;
- `replace`: implement the capability differently;
- `retain`: intentionally keep the source provider dependency;
- `retire`: remove it after replacement verification;
- `unknown`: investigate or explicitly accept the risk.

Keep registrar, authoritative DNS, CDN or proxy, TLS, and application hosting
as separate capabilities. Keep authentication separate from application user
tables.

## 2. Define Success And Risk

For every ledger row, define:

- state that must survive;
- critical user or operator behavior;
- destination implementation;
- independent evidence required;
- rollback action and maximum acceptable data loss;
- condition for retiring the source capability.

Distinguish evidence levels:

1. present;
2. syntactically plausible;
3. accepted by the provider;
4. verified through the real application or protocol flow.

Use level 4 for high-risk capabilities whenever a safe test is possible.

Treat reproducible static assets as lower risk; configuration and replaceable
integrations as medium risk; and user data, authentication, payments, customer
files, production traffic and destructive operations as high risk.

Record an explicitly accepted limitation instead of silently calling it
verified.

## 3. Plan Reversible Work

Prefer this sequence unless actual dependencies require another order:

1. Prepare the destination without production traffic.
2. Deploy an exact pushed repository commit.
3. Create destination resources and configuration.
4. Copy persistent state.
5. Validate privately or in a non-production environment.
6. Repeat incremental synchronization while the source remains writable.
7. Update callbacks and external integrations.
8. Record the cutover and rollback plan.
9. Switch production traffic.
10. Re-run critical verification and observe.
11. Retire only demonstrated replacements.
12. Remove temporary migration access and tooling.

For a writable source, choose and document one consistency strategy: write
freeze, maintenance window, change-data capture, dual write, or final delta
sync. Row or object counts alone do not define a safe cutover point.

Perform read-only discovery without repeatedly asking for confirmation. Obtain
authorization required by the active provider or policy immediately before
production mutation, traffic cutover, credential rotation, or destructive
work.

## 4. Protect Repository And Secrets

Before deployment:

- confirm the repository, remote, intended branch and full remote commit;
- verify required build files exist in that exact commit;
- verify the destination actually selected that commit;
- preserve unrelated user changes;
- never assume an existing deployment follows a moved branch;
- do not commit `.env`, credentials, provider state or local agent files.

Inventory secret names, purpose, owner and destination without printing values.
Use provider secret commands or secure prompts. Treat masked or injected values
as presence evidence only. Validate credentials at the protocol step where the
application actually uses them. Remove temporary credentials after use.

## 5. Execute With Checkpoints

Use provider-specific tools for implementation and keep actions scoped to the
recorded project, environment and resource identifiers.

- Make transfers repeatable or idempotent where practical.
- Record the production version and state checkpoint being migrated.
- Checkpoint long-running data or object transfers.
- Reduce concurrency and retry safely when external services are unstable.
- Reconcile destination-generated configuration before adding manual values.
- Do not use a successful command as its own verification evidence.

Stop and report a blocker when a required provider setting or credential cannot
be discovered safely. Do not invent it from repository contents.

## 6. Verify Independently

Use the matching sections of `references/verification-patterns.md`.

For every capability:

- verify required state independently from the transfer mechanism;
- test through the destination runtime identity where applicable;
- exercise the real user or operator path;
- correlate current logs to the relevant deployment, time and instance;
- confirm rollback remains possible;
- update the ledger with evidence or an honest unresolved status.

A homepage or health endpoint does not prove authentication, uploads,
payments, callbacks, protected routes or background work. An administrator
connection does not prove the application runtime can read and write. An OAuth
authorization page does not prove callback or token exchange success.

Do not proceed to cutover with an unresolved high-risk capability unless the
user explicitly accepts the limitation and its rollback impact.

## 7. Cut Over And Observe

Before cutover, record:

- exact destination deployment and state checkpoint;
- current and target traffic, DNS and callback state;
- rollback commands or control-plane actions;
- verification evidence and accepted limitations.

After cutover:

- verify through an external path, not only inside the destination network;
- verify canonical domains, TLS and intentional redirects;
- repeat critical user journeys and callback tests;
- inspect logs for the current deployment and time window;
- distinguish current failures from historical logs or expected termination;
- observe for a period appropriate to traffic and risk.

Roll back when a defined rollback threshold is crossed. Do not improvise the
threshold after impact begins.

## 8. Retire The Source

Retire one capability at a time and normally only after its retirement gate is
met. If the user explicitly asks to retire an unverified source capability:

1. State the missing evidence and concrete irreversible impact.
2. Distinguish risk acceptance from successful migration.
3. Confirm the exact provider, project and resource at the destructive step.
4. Proceed only when the active provider and policy permit the operation.

Before an irreversible action:

- identify the exact provider, project and resource;
- list the destructive effect;
- confirm retained dependencies and rollback requirements;
- obtain explicit authorization required by the provider or policy.

Do not delete an entire source project because one capability moved. After
retirement, confirm unrelated projects remain untouched, verify the destination
again, and remove temporary credentials, routes and elevated permissions.

## 9. Report Completion Honestly

Report:

- capabilities moved, replaced, retained and retired;
- evidence for every discovered required capability;
- skipped checks, blockers and accepted limitations;
- current production deployment, domain and state checkpoint;
- remaining rollback, cleanup or security actions.

Do not declare completion because a deployment succeeded, `/health` returned
2xx, counts matched, variables existed, or DNS records were created.

Declare completion only when every discovered required capability is verified,
intentionally retained, or explicitly accepted as a limitation. If an
unverified source is destroyed through informed risk acceptance, report the
migration as operationally incomplete and rollback as unavailable; never
relabel the missing evidence as pass.