Happy-path walkthrough for migrating two tables, silver.DimCustomer and silver.FactInternetSales.

You will alternate between two interfaces throughout this walkthrough:

• Claude Code session -- where you type / commands (like /scope-tables, /profile-tables). These are AI-driven commands that analyze your code and make decisions interactively.
• Terminal shell -- where you run ad-migration CLI commands (like ad-migration setup-source). These are deterministic tools that connect to databases and write files.

Each step below is tagged with which interface to use.

• All tools installed and verified, see Installation and Prerequisites
• A git repo for the migration project
• Access to the source database

/init-ad-migration

This installs the ad-migration CLI via Homebrew on macOS, reports the supported Linux/WSL install path when needed, checks prerequisites, writes the project starter files, and scaffolds the repo-local git-workflow guidance.

Generated files include:

• CLAUDE.md
• README.md
• repo-map.json
• .envrc
• .githooks/pre-commit
• .claude/rules/git-workflow.md

See Project Init.

ad-migration setup-source --schemas silver,gold

This validates credentials, extracts DDL, and builds catalog files. It creates manifest.json, writes extracted DDL into ddl/, and builds per-object catalog files in catalog/.

See DDL Extraction.

For a large warehouse where business ownership is unclear, first decide the warehouse domains before choosing the tables for this walkthrough. Ask Claude Code to decide data domains from the whole-warehouse DDL and persist the result, then use the resulting domain catalog to pick the source tables to scope.

See Deciding Data Domains for Migration.

/scope-tables silver.DimCustomer silver.FactInternetSales

Before ad-migration setup-target can proceed, every extracted table needs one of these outcomes:

• scoped to a writer via /scope-tables or /analyzing-table
• excluded from the migration via ad-migration exclude-table <fqn>
• confirmed as a source via ad-migration add-source-table <fqn>

Tables with scoping.status == "no_writer_found" are not automatically included in staging source metadata; they stay pending until you explicitly confirm them as sources with ad-migration add-source-table.

After you confirm source tables, use /listing-objects list sources to see the current confirmed-source inventory from catalog state.

See Scoping.

ad-migration setup-target

This scaffolds dbt/, persists runtime.target, and generates models/staging/_staging__sources.yml, _staging__models.yml, and pure pass-through stg_bronze__<entity>.sql wrappers.

Staging source metadata includes only tables explicitly marked is_source: true. setup-target assumes you have already finished the scope/exclude/source decision for the extracted tables you want to keep. Writerless tables that have not been confirmed yet remain pending and should be marked first with ad-migration add-source-table before you rely on setup-target.

If you identify more source tables later, mark them with ad-migration add-source-table <fqn> and run ad-migration setup-target again. The command is idempotent: it will refresh staging source metadata and wrappers and create any newly required target-side source tables without redoing existing ones.

Setup target also validates the generated source-facing dbt layer with seed, compile, and build checks. See Target Setup.

/profile-tables silver.DimCustomer silver.FactInternetSales

This writes the migration profile for each object: classification, keys, watermark, and other downstream signals used by test generation and model generation.

See Profiling.

ad-migration setup-sandbox

This creates the active sandbox endpoint used for ground-truth capture and SQL equivalence checks and persists it as runtime.sandbox.

See Sandbox Setup.

/generate-tests silver.DimCustomer silver.FactInternetSales

This generates scenarios, runs the independent review loop, executes approved scenarios in the sandbox, and writes reviewed JSON test specs with captured expectations.

See Test Generation.

/refactor-query silver.DimCustomer silver.FactInternetSales

This restructures the source SQL into import/logical/final CTE form and proves equivalence against the extracted ground truth. For table migrations, the proof-backed refactor is persisted on the selected writer procedure catalog entry.

See SQL Refactoring.

/generate-model silver.DimCustomer silver.FactInternetSales

This generates dbt SQL and schema YAML, compiles the generated model, materializes direct parents with an empty run when unit tests need them, runs scoped dbt unit tests, applies the independent model review loop, and commits successful items.

See Model Generation.

/status

Use this to see what is complete, what is blocked, which source tables still need confirmation, and what command to run next.

See Status Dashboard.

ad-migration teardown-sandbox

Run this after all test generation and refactor work that depends on the sandbox is complete.

/cleanup-worktrees

After PRs are merged, use this to remove stale worktrees and merged branches.