• Re-platform by default: Select AWS services that match GCP workload types (e.g., Cloud Run → Fargate, Cloud SQL → RDS).
• Extract before ask: When Terraform, billing, or app code already answers a Clarify question, resolve it with

  chosen_by: "extracted"

  and present it on the Assumption Sheet for confirmation — never re-ask it as a full question unless the user converts it ("ask me about X") or corrects it.
• Dev sizing unless specified: Default to development-tier capacity (e.g., db.t4g.micro, single AZ). Upgrade only on user direction.
• No human one-time migration costs: Do not present human labor, professional services, or people-time work as dollar estimates or "one-time migration cost" budget categories. Vendor charges grounded in data (for example GCP data transfer egress in the infra estimate when billing exists) are allowed.
• Multi-signal approach: Design phase adapts based on available inputs — live gcloud discovery and/or Terraform IaC for infrastructure, billing data for service mapping, and app code for AI workload detection. When live and IaC both run, live is authoritative for current state and disagreements surface as drift, never silently resolved.
• BigQuery /

  google_bigquery_*

  : The skill does not recommend a specific AWS analytics or warehouse service. During Clarify, if discovery shows BigQuery (IaC

  google_bigquery_*

  and/or billing rows for BigQuery), you must surface the specialist advisory before Design (see

  references/phases/clarify/clarify.md

  ). Design output uses

  Deferred — specialist engagement

  ; keep directing the user to their AWS account team and/or a data analytics migration partner through Design, Estimate, and docs (see

  references/phases/design/design-infra.md

  BigQuery specialist gate).

• "Load" = Read the file using the Read tool and follow its instructions. Do not summarize or skip sections.

• $MIGRATION_DIR

  = The run-specific directory under

  .migration/

  (e.g.,

  .migration/0226-1430/

  ). Set during Phase 1 (Discover).

• Budget: Each phase should load no more than ~800 lines of instructions (excluding user artifacts like JSON profiles and MCP tool results).
• Conditional loading: Reference files with trigger conditions (e.g.,

  agentic_profile.is_agentic == true

  ) MUST NOT be loaded unless the condition is met. Do not speculatively load files.
• No duplication: Model mapping tables, pricing data, and shared warnings exist in one canonical file. Other files reference them; they do not copy them inline.
• Progressive depth: Phase orchestrators (

  design.md

  ,

  generate.md

  ) contain short routing logic that points to detailed sub-files. Load the sub-file only when its path is selected.

design-refs/ai-gemini-to-bedrock.md

ai-workload-profile.json

summary.ai_source

"gemini"

"both"

design-refs/ai-openai-to-bedrock.md

ai-workload-profile.json

summary.ai_source

"openai"

"both"

design-refs/ai-anthropic-to-bedrock.md

ai-workload-profile.json

summary.ai_source

"anthropic"

design-refs/ai.md

ai-workload-profile.json

summary.ai_source

"other"

design-refs/elastic-beanstalk.md

google_app_engine_application

compute_model == "managed_platform"

compute

"eks"

compute.md

compute_model

compute: "eks"

design-refs/design-ref-harness.md

agentic_profile.is_agentic == true

ai_constraints.agentic.migration_approach == "harness"

design-refs/design-ref-agentic-to-agentcore.md

agentic_profile.is_agentic == true

ai_constraints.agentic.migration_approach == "strands"

shared/retarget-gotchas.md

agentic_profile.is_agentic == true

ai_constraints.agentic.migration_approach == "retarget"

shared/graviton.md

graviton_profile

gcp-resource-inventory.json

ai-workload-profile.json

"⚠️ This is a large hybrid stack (infrastructure + AI workloads). To ensure complete and accurate recommendations, consider running the migration in two separate passes:

Pass 1 — Infrastructure: Run with only your Terraform files to get infra mapping, Terraform generation, and cost estimates.

Pass 2 — AI workloads: Run with only your application code to get Bedrock model recommendations, provider adapters, and AI migration artifacts.

Continue with the combined run? (Y/N)"

• Live gcloud CLI (recommended for infrastructure): an authenticated

  gcloud

  CLI — read-only, consent-gated live discovery of the project (see

  references/phases/discover/discover-live.md

  )
• Terraform IaC:

  .tf

  files (with optional

  .tfvars

  ,

  .tfstate

  )
• Application code: Source files with GCP SDK or AI framework imports
• Billing data: GCP billing/cost/usage export files (CSV or JSON)
• OpenAI usage API (supplement, for AI workloads on OpenAI): an OpenAI Admin API key with Usage set to Read (API scope

  api.usage.read

  ) — read-only, consent-gated capture of real cost and token usage (see

  references/phases/discover/discover-openai-api.md

  ); replaces manual billing CSV exports for OpenAI spend. Not a standalone source: usage data supplies spend and volumes but not integration or capability detail, so AI migration design still requires application code (or another source above)

discover.md

discover

phases.discover != "completed"

references/phases/discover/discover.md

clarify

phases.discover == "completed"

phases.clarify != "completed"

references/phases/clarify/clarify.md

design

phases.clarify == "completed"

phases.design != "completed"

references/phases/design/design.md

estimate

phases.design == "completed"

phases.estimate != "completed"

references/phases/estimate/estimate.md

workshop

current_phase == "estimate"

phases.estimate == "completed"

phases.workshop

"pending"

"in_progress"

workshop

"pending"

estimate.md

"in_progress"

references/phases/workshop/workshop.md

generate

phases.estimate == "completed"

phases.workshop == "completed"

phases.generate != "completed"

run_mode == "decide_and_execute"

references/phases/generate/generate.md

current_phase == "complete"

run_mode == "decide"

phases.generate == "pending"

run_mode: "decide_and_execute"

current_phase: "generate"

generate.md

current_phase == "generate"

run_mode

phases.generate != "completed"

current_phase: generate

run_mode

generate.md

run_mode: "decide_and_execute"

run_mode: "decide"

current_phase: "complete"

generate

complete

phases.generate == "completed"

phases.feedback == "pending"

phases.feedback

"completed"

complete

phases.generate == "completed"

phases.feedback == "completed"

1. Read

   $MIGRATION_DIR/.phase-status.json

2. Workshop resume (mandatory): If

   current_phase == "estimate"

   AND

   phases.estimate == "completed"

   AND

   phases.workshop

   is

   "pending"

   or

   "in_progress"

   , follow the

   workshop

   row above — never re-run Estimate on a plain "continue my migration" / resume. Explicit "what if" / "reprice" / "workshop mode" phrases also load

   workshop.md

   when Estimate artifacts exist.
3. Legacy Generate resume (mandatory): If

   current_phase == "generate"

   AND

   run_mode

   is absent AND

   phases.generate != "completed"

   , follow the

   legacy-generate

   row — present the resume offer; do not auto-load

   generate.md

   and do not leave the state machine with no matching row.
4. If

   current_phase

   exists (and steps 2–3 did not apply), use it (must match one of: discover, clarify, design, estimate, generate, complete)
5. Otherwise use ordered phase evaluation:

   discover

   →

   clarify

   →

   design

   →

   estimate

   →

   generate

6. Pick the first phase in that order where

   phases.<phase> != "completed"

   ; if none, state is

   complete

   . When evaluating

   generate

   , require

   phases.workshop == "completed"

   (seed

   "pending"

   on Discover so a missing key is not treated as resolved) and Generate opt-in consent (

   run_mode == "decide_and_execute"

   or an explicit request — see the hard rule above); without consent, treat the state as decide-complete and present the resume offer instead of loading

   generate.md

   .

references/phases/generate/generate.md

estimate.md

run_mode: "decide_and_execute"

.phase-status.json

generate.md

run_mode: "decide"

run_mode

references/phases/design/design.md

references/phases/estimate/estimate.md

references/phases/generate/generate.md

$MIGRATION_DIR/.phase-status.json

phases.clarify

"completed"

preferences.json

references/phases/clarify/clarify.md

references/shared/handoff-gates.md

1. Single

   $MIGRATION_DIR

   : Use one run directory for the entire migration. Do not mix artifacts across

   .migration/*/

   sessions.
2. Re-read from disk: Before each phase (and before each handoff gate), Read required artifacts from

   $MIGRATION_DIR/

   . Do not rely on chat memory.
3. Advance only on

   HANDOFF_OK

   : A phase is complete only when its orchestrator emits

   HANDOFF_OK | phase=<name> | artifacts=...

   . Do not load the next phase without it.
4. On

   GATE_FAIL

   : Output the failure line(s) to the user in plain language. Do NOT modify artifacts to pass the gate. Do NOT continue to the next phase. Tell the user which phase to re-run.
5. Re-entry: Re-running an earlier phase after downstream phases completed requires explicit user confirmation; downstream phases must be reset to

   "pending"

   . See

   handoff-gates.md

   re-entry table.

references/shared/validate-artifacts.md

migration-report.html

references/shared/validate-migration-report.md

$MIGRATION_DIR/.phase-status.json

1. Multiple sessions: If multiple directories exist under

   .migration/

   , list them with their phase status and ask: [A] Resume latest, [B] Start fresh, [C] Cancel.
2. Invalid JSON: If

   .phase-status.json

   fails to parse, do NOT delete it and do NOT restart from Discover — the phase artifacts on disk are the durable record of progress. Reconstruct instead:
   1. Enumerate

      $MIGRATION_DIR

      and infer completed phases from artifacts: any of

      gcp-resource-inventory.json

      /

      billing-profile.json

      /

      ai-workload-profile.json

      → discover completed;

      preferences.json

      → clarify completed;

      aws-design.json

      /

      aws-design-ai.json

      /

      aws-design-billing.json

      → design completed;

      estimation-*.json

      → estimate completed (partial-write check: if

      preferences.json

      has an

      ai_constraints

      section — or

      ai-workload-profile.json

      /

      aws-design-ai.json

      is present — but

      estimation-ai.json

      is missing while another

      estimation-*.json

      exists, treat estimate as incomplete, not completed; propose resume at estimate);

      generation-*.json

      or

      MIGRATION_GUIDE.md

      → generate completed.
   2. Present the inferred status to the user: "Your state file was corrupted, but I can see [phases] completed from the artifacts on disk. Resume at [next phase]? (Y/N)". Confirmation is the safety net for residual ambiguity (e.g. other partial writes the heuristic misses) — on N, the user picks the phase to resume.
   3. On Y: rewrite

      .phase-status.json

      with the inferred phases marked

      "completed"

      , the next phase

      "pending"

      ,

      current_phase

      set to it, and a fresh

      last_updated

      . Continue normally. On N: ask which phase to resume from and write that instead. This is reconstruction of ground truth from artifacts, not artifact-patching to pass a gate — the handoff-gate prohibition does not apply to

      .phase-status.json

      recovery.
3. Unrecognized phase: If

   phases

   object contains a phase not in {discover, clarify, design, estimate, workshop, generate, feedback}, STOP. Output: "Unrecognized phase: [value]. Valid phases: discover, clarify, design, estimate, workshop, generate, feedback."
4. Unrecognized status: If any

   phases.*

   value is not in {pending, in_progress, completed}, STOP. Output: "Unrecognized status: [value]. Valid values: pending, in_progress, completed."
5. Invalid

   current_phase

   (if present): If

   current_phase

   is not in {discover, clarify, design, estimate, generate, complete}, STOP. Output: "Unrecognized current_phase: [value]. Valid values: discover, clarify, design, estimate, generate, complete." (

   workshop

   and

   feedback

   are sidebars — never

   current_phase

   .)
6. Out-of-order completion: For ordered phases [discover, clarify, design, estimate, generate], if any later phase is

   "completed"

   while an earlier phase is not

   "completed"

   , STOP. Output: "Inconsistent phase ordering detected. Reconcile

   .phase-status.json

   before resuming."
7. Multiple active phases: Across core phases {discover, clarify, design, estimate, generate}, at most one phase may be

   "in_progress"

   . If >1, STOP. Output: "Multiple phases are in_progress. Keep only one active phase before resuming." (Sidebar

   workshop

   /

   feedback

   may be

   in_progress

   while estimate is

   completed

   .)

.phase-status.json

1. Read the current file before every update.
2. Change only the phase keys being advanced and

   last_updated

   .
3. Keep prior completed phases unchanged.
4. Set

   current_phase

   to the next deterministic phase — or

   complete

   after Generate, or after Estimate when the user chose Decision-gate A (

   run_mode: "decide"

   ; Generate stays pending).
5. Write the full file in the same turn as your final phase work message.

$MIGRATION_DIR/.phase-status.json

{
  "migration_id": "MMDD-HHMM",
  "last_updated": "2026-02-26T15:35:22Z",
  "current_phase": "design",
  "phases": {
    "discover": "completed",
    "clarify": "completed",
    "design": "pending",
    "estimate": "pending",
    "workshop": "pending",
    "generate": "pending",
    "feedback": "pending"
  }
}

MMDD-HHMM

last_updated

• Provides

  get_pricing

  ,

  get_pricing_service_codes

  ,

  get_pricing_service_attributes

  tools
• Only needed during Estimate phase. Discover and Design do not require it.
• Primary pricing source:

  references/shared/pricing-cache.md

  (cached 2026 rates, ±5-10% for infrastructure, ±15-25% for AI models). MCP is secondary — used only for services not found in the cache.

• IaC output: Terraform configurations, migration scripts, AI migration code, and documentation
• Region:

  us-east-1

  (unless user specifies, or GCP region → AWS region mapping suggests otherwise)
• Sizing: Development tier (e.g.,

  db.t4g.micro

  for databases, 0.5 CPU for Fargate)
• CPU architecture: Graviton (ARM64) for all eligible compute when the workload is arm64-compatible; x86 only for incompatible workloads (Windows/.NET Framework, GPU/CUDA, RDS SQL Server). See

  references/shared/graviton.md

  .
• Migration mode: Adapts based on available inputs (infrastructure, AI, or billing-only)
• Cost currency: USD
• Timeline assumption: 2-16 weeks depending on migration complexity — small (2-6 weeks), medium (6-12 weeks), large (12-18 weeks). See

  references/shared/migration-complexity.md

  for tier definitions.

1. Load phase status: Read

   .phase-status.json

   from

   .migration/*/

   .
   • If missing: Initialize for Phase 1 (Discover)
   • If exists: Determine current phase using deterministic rules in State Machine
2. Determine phase to execute:
   • If

     current_phase

     exists: execute that phase.
   • Otherwise execute the first non-completed phase in ordered list: discover → clarify → design → estimate → generate.
   • If all ordered phases are completed: migration is complete (with feedback finalization rule).
3. Read phase reference: Load the full reference file for the target phase.
4. Execute ALL steps in order: Follow every numbered step in the reference file. Do not skip, optimize, or deviate.
5. Validate outputs: Confirm all required output files exist with correct schema before proceeding. Phase orchestrators run Completion Handoff Gate checks per

   shared/handoff-gates.md

   .
6. Handoff gate: Emit

   HANDOFF_OK

   or

   GATE_FAIL

   per

   shared/handoff-gates.md

   . On

   GATE_FAIL

   , stop — do not update phase status or load the next phase.
7. Update phase status: Only after

   HANDOFF_OK

   . Use the Phase Status Update Protocol (read-merge-write) in the same turn as the phase's final output message.
8. Feedback sidebar: After a phase completes, check if feedback is due (see rules below). This runs before advancing to the next phase.
   • After Discover (if

     phases.feedback

     is

     "pending"

     ): Output to user: "Would you like to share quick feedback (5 optional questions + anonymized usage data) to help improve this tool? Your data never includes resource names, file paths, or account IDs. [A] Send feedback now [B] Wait until after the Estimate phase"
     • If user picks A → Load

       references/phases/feedback/feedback.md

       , execute it, then continue to Clarify.
     • If user picks B → Continue to Clarify (feedback stays

       "pending"

       ).
   • After Estimate: First present the post-Estimate Decision gate per

     estimate.md

     (done for now / what-if workshop / generate). The gate owns the post-Estimate sequence — do not interleave the feedback offer with it, and do not stack it with other prompts in one message. Outer Estimate keeps

     current_phase: estimate

     until the gate resolves (workshop exits return to the gate). Then, after the gate resolves to A or C, if

     phases.feedback

     is

     "pending"

     :
     • After gate C (continuing to Generate), use the standard form: "Would you like to share quick feedback now? (5 optional questions + anonymized usage data) [A] Yes, share feedback [B] No thanks"
     • After gate A (user said they're done), fold a one-line short form into the closing message instead of a separate prompt: "…everything is saved and I'll pick up from here. Quick feedback before you go? [Yes] [No]" — the user just said they're done; don't make feedback feel like another phase.
     • Yes/A → Load

       references/phases/feedback/feedback.md

       , execute it, then continue per the gate choice (Generate for C; done for A).
     • No/B → Use the Phase Status Update Protocol to set

       phases.feedback

       to

       "completed"

       . Continue per the gate choice. This placement means the feedback decision-check questions land immediately after the user actually made their migrate/stay decision.
   • Warm start / explicit what-if: If the user says "what if", "reprice", "workshop mode", or "compare scenarios" and infra Estimate artifacts exist, load

     references/phases/workshop/workshop.md

     (respect Generate re-entry).
   • After Generate: No feedback offer. If

     phases.feedback

     is still

     "pending"

     , use the Phase Status Update Protocol to set it to

     "completed"

     (user had two chances and chose to defer/skip).
9. Display summary: Show user what was accomplished, highlight next phase, or confirm migration completion.

current_phase

current_phase

• Terraform infrastructure discovery
• Live infrastructure discovery via authenticated gcloud CLI (read-only, consent-gated, with IaC drift detection)
• App code scanning (AI workload detection)
• Billing data import from GCP
• User requirement clarification (assumption-sheet wizard by default: confirm detected/assumed values, answer only essential questions; full adaptive question flow available on request)
• Multi-path Design (infrastructure, AI workloads, billing-only fallback)
• AWS cost estimation (from pricing API or fallback)
• Migration artifact generation (Terraform, scripts, AI adapters, documentation)
• Optional feedback collection with anonymized telemetry