setup

name	setup
description	Set up a migration project — connect to source, initialize, extract objects, convert, and assess. Covers steps 1-5 of the migration lifecycle.
license	Proprietary. See License-Skills for complete terms

Migration Setup

On Entry

Tell the user:

Phase 1: Setup — I'll walk you through connecting to your source database, initializing the project, registering your objects, converting them to Snowflake SQL, and generating an assessment report. Once you've seen the assessment I'll ask whether you want to go on to migrating objects.

Flow

Setup is driven by the setup state machine — the resolver picks the next step automatically. The flow:

1. Call progress_setup(). The response carries the following keys when relevant — fields that would otherwise be the no-op default (completed: false, blocked: false, etc.) are omitted to keep responses small:

   • next_task — id of the task the resolver landed on
   • next_skill — sub-skill path to load (omitted when the task is handled inline via next_prompt)
   • next_skill_md — when present, the full body of the skill at next_skill. Execute it directly without calling Read. Only emitted for skills small enough to inline; for larger ones (or any skill not in the inline set), next_skill is the path and you Read it normally.
   • next_prompt — present when the task is an inline question (see step 3 below)
   • then_ask — further questions to ask in the same turn, in order (see step 3)
   • planned_steps — remaining task ids in order
   • completed: true — only when the machine reached its terminal state; absence means "not done, keep looping"
   • blocked: true (+ blocked_on), errored: true (+ error_reason), committed: [...], project_initialized: false — emitted only when actionable

2. If completed is true, jump to On Completion below.

3. If next_prompt is non-null, the engine wants you to ask the user a question directly — no sub-skill load required. Surface the prompt exactly as the engine returned it via ask_user_question (multiSelect = false):

   • next_prompt.question is the question text.
   • next_prompt.options is the list of {label, value, description?} entries to render. Use label as the user-facing choice; never show value to the user.
   • If then_ask is present, ask every question in one ask_user_question call — next_prompt first, then each entry of then_ask in the order given, one question per entry, multiSelect = false on each. Don't ask them one call at a time. They are queued precisely because the machine reaches all of them whatever the user answers, so nothing you learn from one can make a later one wrong. The queue is capped so a whole run always fits in a single call; never split it.
   • Send every answer you collected in one call: progress_setup(answers={"<write_to>": "<chosen value>", ...}) — keys are each prompt's write_to, values the chosen option's value verbatim (a string, even for a number or a boolean). That records the answers and returns the next step, so for questions it replaces both the separate configure(...) call and the follow-up progress_setup(). Go to step 2 with its response.
   • A prompt whose chosen option carries then is the other case — that answer leads somewhere specific, so you can start on it in the same turn (such a prompt never has then_ask):
     • then.completed → setup is done; jump to On Completion.
     • then.skill → that is the step the answer leads to. Send the answer with progress_setup(answers={...}); its response carries next_skill_md for that very step, so execute it from there rather than Reading the file. then gives you the route early — what to tell the user, and what's coming — while the body arrives once, for the branch actually taken.
     • a then with only task → that step is already satisfied; send the answer and act on whatever the response names. If that response names the same you just acted on, the step did not complete — do run its skill again. Re-running it re-asks questions the user just answered; instead do what that skill says to do when it can't finish (e.g. ).

4. Otherwise (no prompt): if next_skill_md is set, execute its instructions directly in this same turn — no Read needed. Otherwise load the skill at next_skill immediately (Read it, then execute in the same turn). The sub-skill is responsible for asking the user any question it needs. Do not surface "Next step pending: X — let me know" prose and wait — that's a wasted round-trip; the user already said "continue" upstream. When the sub-skill returns, go back to step 1.

Note: progress_setup() also handles git commits automatically — when a task with commitOnComplete completes, the tool commits and pushes project files. You do not need to run git commands manually.

Tasks the machine routes through, in order:

Task id	How the agent handles it
validateEmptyDir	sub-skill: setup/validate-empty-dir.md
confirmProjectDir	sub-skill: setup/confirm-project-dir.md
recommendSafeTools	inline prompt — arrives with the next two queued in then_ask
chooseSourceDialect	inline prompt (queued)
chooseEntryMode	inline prompt (queued; nothing queues after it — it routes by dialect)
midwayEntry	sub-skill: setup/midway-entry.md
chooseCodeSource	inline prompt (next_prompt) — extract vs. local files; each answer carries its then
configureSourceConnection	sub-skill: setup/configure-source-connection.md (extract path only)
registerCode	sub-skill: register-code-units/SKILL.md
convertCode	sub-skill: convert/SKILL.md
runAssessment	sub-skill: assessment/SKILL.md
continueToMigration	inline prompt (next_prompt) — the post-assessment gate; each answer carries its then
configureGit	sub-skill: setup/git.md
configureSnowflakeTarget	sub-skill: setup/configure-snowflake-target.md
setupDataInfrastructure	sub-skill: data-infrastructure/SKILL.md
dataStrategy	sub-skill: setup/data-strategy/SKILL.md
configureTesting	sub-skill:

Conversion and assessment come first on purpose: neither needs a Snowflake target, so a user reaches their assessment report without picking a connection or database. Everything else — git included — is gated behind the continueToMigration prompt, so a user who only wanted an assessment is never asked to set up a repository. Answer "Not now" and the machine finishes at assessment; nothing is persisted for that answer, so the gate is offered again on the next run.

One consequence: the milestone commits (registerCode, convertCode, runAssessment) need git, which now comes after the gate. They land together on the first progress_setup() after configureGit rather than one at a time, and an assessment-only run makes none of them — it has no repository.

The assessment skill's closing menu asks the same thing the gate asks, so on "Move on to migration" it submits progress_setup(answers={"continue_to_migration": "true"}) instead of a bare call. A bare call there would put the question a second time.

The testing choice also decides the last step: synthetic walks into generateTestbed (synthetic tests need generated data), while source-data ends setup right after configureTesting.

If progress_setup() returns an unexpected next_task not listed above, surface the raw response to the user and stop — do not invent a skill path.

Skipping an optional step

To skip an optional setup step for this run, call progress_setup(mode="setup", skip="runAssessment"). The response resolves the next step exactly as a normal call would (for the last step, completed: true) — act on it directly. Nothing is persisted, so the step is offered again later; for a permanent opt-out use configure(tasks={"runAssessment": {"enabled": false}}).

Trust progress_setup() / related MCP return values for what is done vs pending — do not invent completion from chat history.

Sub-Skills Reference

Stage	Sub-skill	Location
1	sql-server-connection	../connection/sql-server-connection/SKILL.md
1	redshift-connection	../connection/redshift-connection/SKILL.md
1	oracle-connection	../connection/oracle-connection/SKILL.md
1	teradata-connection	../connection/teradata-connection/SKILL.md
1	postgresql-connection	../connection/postgresql-connection/SKILL.md
—	midway-entry (existing project with pre-converted code; SQL Server/Redshift only)	./midway-entry.md
3	register-code-units	../register-code-units/SKILL.md
4	convert	../convert/SKILL.md
4	code-conversion-only	../code-conversion-only/SKILL.md
5	snowconvert-assessment	../assessment/SKILL.md
—	configure-snowflake-target (post-assessment: connection + database)	./configure-snowflake-target.md
—	configure-testing (post-assessment: source-data vs synthetic)	./configure-testing.md
—	data-infrastructure-setup	../data-infrastructure/SKILL.md
—	data-strategy	./data-strategy/SKILL.md
—	data-migration-setup	../migrate-objects/actions/data-migration/SKILL.md
—	data-validation-setup	./data-validation/SKILL.md
—	data-infrastructure-teardown	../data-infrastructure/teardown/SKILL.md

Rules

1. Follow sub-skill instructions — Complete each sub-skill fully before returning
2. Confirm transitions — Ask user before moving to next stage

On Completion

When the setup machine reaches setupComplete, the closing message depends on how the user answered the continueToMigration gate.

If they chose "Not now" (no Snowflake target configured) — close out here without nudging them toward migration:

Assessment complete — connected to <source_type>, objects registered, code converted, and your assessment report is ready. Every step was committed to git.

Whenever you want to go on to deploying objects to Snowflake, just say so — I'll pick up right here and set up the Snowflake target then.

Then ask what else you can help with, and stop. Do not load ../migrate-objects/SKILL.md.

If they opted in and the Snowflake target and testing path are set:

Setup complete — Your migration project is configured: connected to <source_type>, objects registered, code converted, assessment generated, and your Snowflake target (<snowflake_database>) and testing path are set. Ready to start migrating objects.

Every step along the way was committed to git. This is a good time to share the project with your team — the next phase (object migration) is designed to be multi-user, with multiple engineers working through waves in parallel.

Then return to the parent migration skill.