// Development guidance for the Amplify Gen1-to-Gen2 migration tooling — architecture, commands, testing, and snapshot workflows
| name | gen2-migration |
| description | Development guidance for the Amplify Gen1-to-Gen2 migration tooling — architecture, commands, testing, and snapshot workflows |
This skill provides context for working on the amplify gen2-migration CLI feature,
which migrates Amplify Gen1 applications to Gen2.
Before changing code, read the relevant docs files. They are the source of truth for architecture and design decisions:
| Doc | Covers |
|---|---|
docs/packages/amplify-cli/src/commands/gen2-migration.md | Architecture, CLI interface, Plan lifecycle, subcommand design |
docs/packages/amplify-cli/src/commands/gen2-migration/assess.md | Assessment, resource discovery, support levels |
docs/packages/amplify-cli/src/commands/gen2-migration/lock.md | Lock step, drift detection, deletion protection |
docs/packages/amplify-cli/src/commands/gen2-migration/generate.md | Code generation pipeline, directory structure, generators |
docs/packages/amplify-cli/src/commands/gen2-migration/refactor.md | CloudFormation stack refactoring, category refactorers |
packages/amplify-e2e-gen2-migration/README.md | E2E automation system, CLI options, migration workflow steps |
packages/amplify-cli/src/__tests__/commands/gen2-migration/_framework/README.md | Test framework, mock clients, snapshot comparison, customization |
amplify-migration-apps/README.md | App structure, hooks, snapshots, adding/modifying apps |
| https://docs.amplify.aws/gen1/react/tools/cli/ | Amplify Gen1 CLI documentation |
| https://docs.amplify.aws/react/build-a-backend/ | Amplify Gen2 backend documentation |
packages/amplify-cli/src/commands/gen2-migration/ — CLI commands and core logicpackages/amplify-cli/src/__tests__/commands/gen2-migration/ — Snapshot and unit testspackages/amplify-e2e-gen2-migration/ — E2E testing automationEach subdirectory under amplify-migration-apps/ is a test app representing a Gen1 project
with a specific combination of Amplify categories and configurations. See
amplify-migration-apps/README.md for the full structure and conventions.
The E2E logs the working directory for the app (look for App directory: in the output). This directory persists after the run
completes or fails. You can cd into it and run frontend tests directly
(e.g., npm run test:gen1, npm run test:gen2).
The E2E logs the directory where on-the-fly snapshots are captured for the run (look for
the Snapshot directory: line in the output). You can inspect the files in that directory
to see the state of the app at each phase.
The E2E prints Logging to: at the start with the path to a log file. To check progress,
tail -n 50 (or more) that log file.
To avoid filling your context window, delegate E2E output reading to a sub-agent — have it tail the log file and summarize the current phase, pass/fail status, and any errors.
Do not stop polling. This workflow is autonomous — no user is watching. When the E2E is still running, keep polling the log file until it either completes or fails. Do not pause and wait for user input between polls. If the E2E fails, analyze the failure and act on it. If it succeeds, move on to the next step.
E2E runs take a long time — typically 30+ minutes. Expect long polling intervals when monitoring progress.
Use read-only AWS CLI commands whenever you need information about live resources that isn't available locally — stack status, Lambda configurations, Cognito user pool settings, S3 bucket policies, etc. Stick to describe/list/get operations only.
If you changed migration code in packages/amplify-cli/, rebuild the CLI with
yarn build in that package before running the E2E. The E2E invokes the locally built
CLI, so stale builds will mask your fix.
The E2E is idempotent — previous runs won't interfere with the next one.