<SKILL_BASE>

• $SCRIPTS

  =

  <SKILL_BASE>/scripts

• $HELPERS

  =

  <SKILL_BASE>/references/helpers

  (the former helper skills, now references)

$ARGUMENTS

$REPO

git clone

$REPO

1. Git-root check (compare resolved paths — on macOS

   /tmp

   resolves to

   /private/tmp

   , so a raw string comparison false-positives):
   bash

   [ "$(git -C <REPO> rev-parse --show-toplevel 2>/dev/null)" = "$(cd <REPO> && pwd -P)" ] && echo GIT_ROOT_OK || echo GIT_ROOT_MISMATCH

   • GIT_ROOT_OK

     → proceed.

   • GIT_ROOT_MISMATCH

     and the command errored (not a git repo at all) → tell the user the path must be a git repository (the deliverable is a git branch); re-ask.

   • GIT_ROOT_MISMATCH

     but inside a repo (user pointed at a subdirectory) → AskUserQuestion: "Use the repo root instead" (recommended) / "Continue with this subdirectory" / "Abort".
2. Dirty-tree check:
   bash

   git -C <REPO> status --porcelain

   If uncommitted changes exist, show them and AskUserQuestion: "Continue anyway" or "Let me clean up first".

$REPO

migration-to-aws:gcp-to-aws

"I'm now invoking the gcp-to-aws Assess skill to discover your AI workloads and design the Bedrock migration. It will ask you some questions — please answer them. (Don't be confused by the skill's

gcp-to-aws

name — it also covers pure AI/LLM migrations with no GCP or infrastructure component, which is how it's being used here.)"

gcp-to-aws

$REPO

• Source code is at

  $REPO

  — when the skill asks for GCP sources or scans for files, point it there
• This is an AI/LLM workload migration — the AI path is the goal
• Unless Terraform/IaC files are actually present in

  $REPO

  , skip IaC discovery
• Unless the user offers billing data, skip billing discovery. If the source provider is OpenAI, the skill may instead offer its OpenAI Admin API usage discovery (

  discover-openai-api.md

  — read-only, consent-gated, needs an Admin key with Usage set to Read); accepting it gives Estimate real spend and token volumes without manual CSV exports

$MIGRATION_DIR

.migration/<MMDD-HHMM>/

ls -td "$REPO/.migration"/*/ 2>/dev/null | head -1

$MIGRATION_DIR

• aws-design-ai.json

  (model mapping + architecture)

• ai-workload-profile.json

  (detected workloads)

• preferences.json

  (user preferences from Clarify)

aws-design-ai.json

$MIGRATION_DIR/aws-design-ai.json

• ai_architecture.bedrock_models[]

  → array of

  {source_model, aws_model_id, use_case}

• Collect all

  aws_model_id

  values into

  $TARGET_MODELS

  (array). Keep the

  use_case

  of each: the preflight script probes each model by the right API automatically (Converse for chat, InvokeModel for embeddings), but the evaluator's quality scoring only applies to chat models — embedding targets get format/dimension validation only.

$MIGRATION_DIR/ai-workload-profile.json

• summary.ai_source

  → source provider

$MIGRATION_DIR/preferences.json

• design_constraints.target_region

  →

  $REGION

  (default

  us-east-1

  if absent)

aws-design-ai.json

ai_architecture.bedrock_models[]

aws sts get-caller-identity 2>&1

aws configure

aws sso login

! aws sso login

• Yes, use this identity → proceed
• Use a different AWS profile → ask which profile, record it as

  $AWS_PROFILE_CHOICE

  , re-run B2 as

  aws sts get-caller-identity --profile $AWS_PROFILE_CHOICE

  , and re-confirm. Do NOT rely on exporting

  AWS_PROFILE

  — env vars do not persist across Bash tool calls or into workflow subagents (see B3). Instead pass the choice explicitly everywhere:

  --profile

  on every aws CLI call, and prepend

  AWS_PROFILE=$AWS_PROFILE_CHOICE

  inline on the B4 preflight command and inside the workflow args (

  awsProfile

  field) so subagents can do the same.

$REGION

mkdir -p "$REPO/.saws-migrate" && printf '*\n' > "$REPO/.saws-migrate/.gitignore"

$KEY_ENV_VAR

NAME=

• openai

  →

  OPENAI_API_KEY

• anthropic

  →

  ANTHROPIC_API_KEY

• google

  /

  gemini

  →

  GEMINI_API_KEY

printenv

${!VAR}

[ -n "$(printenv "$KEY_ENV_VAR")" ] && echo ENV_KEY_PRESENT || echo ENV_KEY_ABSENT

ENV_KEY_PRESENT

• Use the

  $KEY_ENV_VAR

  already in my environment → materialize env var to file in one command — the value never appears in the transcript:
  bash

  printf '%s=%s\n' "$KEY_ENV_VAR" "$(printenv "$KEY_ENV_VAR")" > "$REPO/.saws-migrate/.source-provider-env" && chmod 600 "$REPO/.saws-migrate/.source-provider-env"

  Then run the format check below and set

  sourceBaselineAvailable = true

  ,

  sourceKeyRef = "$REPO/.saws-migrate/.source-provider-env"

  .
• I'll write it to a file myself → give the user this command to run in THEIR OWN terminal (not through the agent; in Claude Code an

  !

  prefix runs it in-session) —

  read -rs

  collects the key without echoing it:
  bash

  read -rs k && printf '%s=%s\n' "<KEY_ENV_VAR>" "$k" > "<REPO>/.saws-migrate/.source-provider-env" && chmod 600 "<REPO>/.saws-migrate/.source-provider-env" && unset k

  Substitute the literal env-var name and repo path when presenting it (those are not secrets). Then run the format check below and set the same flags as above.
• Skip →

  sourceBaselineAvailable = false

  ,

  sourceKeyRef = ""

  .

NAME=

grep -qE '^(OPENAI|ANTHROPIC|GEMINI)_API_KEY=.+' "$REPO/.saws-migrate/.source-provider-env" && echo KEY_FORMAT_OK || echo KEY_FORMAT_BAD

KEY_FORMAT_BAD

.saws-migrate/

export

ENV_KEY_PRESENT

uv run --project $SCRIPTS python $SCRIPTS/preflight_bedrock.py --region $REGION --models <comma-separated $TARGET_MODELS> --dataset-size 200

--dataset-size 200

AWS_PROFILE=$AWS_PROFILE_CHOICE

reason

detail

failing_models

models[]

• ok == false

  +

  reason: credentials

  → show the detail (configure/refresh credentials), stop; user re-runs after fixing.

• ok == false

  +

  reason: model_access

  → model access not enabled in the Bedrock console (NOT an IAM problem): point the user at the console Model access page for the failing models, stop; re-run B4 after they enable it.

• ok == false

  +

  reason: authz

  → IAM denies

  bedrock:InvokeModel

  : tell user the IAM action to grant; stop.

• ok == false

  +

  reason: model_unavailable

  → Read the

  resolve-bedrock-model-id

  reference at

  $HELPERS/resolve-bedrock-model-id/resolve-bedrock-model-id.md

  and follow its procedure with each ID from

  failing_models

  + region. AskUserQuestion with the candidates: "Use

  <candidate>

  (cross-region inference profile)" / "Paste a different model ID" / "Abort". On a choice, replace the ID in

  $TARGET_MODELS

  and re-run B4.

• ok == false

  + any other

  reason

  → show

  detail

  and stop.

• ok == true

  → proceed. Surface any

  quota_warning

  , and any model whose

  reason

  is

  embedding_unprobed

  (embedding family the preflight can't probe — remind the user to confirm model access in the console).

uv run --project $SCRIPTS python $SCRIPTS/validate_result.py --schema <analysis|ingestion|eval|rewrite|delta-decisions> <file>

• Exit 0 +

  RESULT=valid CONTROL=ok

  → phase completed; proceed.
• Exit 0 +

  CONTROL=blocked REASON=<r>

  → blocked flow (below).
• Exit 0 +

  CONTROL=partial COMPLETED=<n> TOTAL=<m>

  → partial flow (eval only).
• Exit 1 (

  RESULT=invalid

  + error lines) or exit 2 (file missing) → stateless fixer retry: dispatch a FRESH agent of the same type whose prompt is the original context block + the file path + the validator's verbatim error output + the instruction "fix ONLY the output file at

  <path>

  so it validates; do not redo the phase's work unless a required field is genuinely missing from it". Cap 2 retries per phase; then stop and show the errors.

1. mkdir -p $PHASE_DIR

   . Build

   $PHASE_DIR/current-context.json

   with exactly these fields (hashes via

   shasum -a 256

   ; key hash is a fingerprint — never store the key value):

{
  "repo_root": "<cd $REPO && pwd -P>",
  "migration_dir": "<$MIGRATION_DIR>",
  "region": "<$REGION>",
  "aws_profile": "<$AWS_PROFILE_CHOICE or \"\">",
  "aws_account": "<Account from B2>",
  "repo_head_sha": "<git -C $REPO rev-parse HEAD>",
  "repo_branch": "<git -C $REPO rev-parse --abbrev-ref HEAD>",
  "repo_dirty_sha256": "<sha256 of: git status --porcelain + git diff + git diff --cached, EACH with pathspecs -- . ':(exclude).saws-migrate' ':(exclude).migration' ':(exclude)MIGRATION_REPORT_*.md'; \"\" when all three are empty>",
  "target_models": [{"source_model": "...", "aws_model_id": "...", "use_case": "..."}],
  "resolved_model_overrides": {},
  "source_provider": "<from B1>",
  "source_baseline_available": <true|false from B3>,
  "source_key_sha256": "<sha256 of .source-provider-env contents, \"\" when absent>",
  "log_files": [{"path": "...", "sha256": "..."}],
  "max_golden_cases": 200,
  "assess_design_sha256": "<sha256 of $MIGRATION_DIR/aws-design-ai.json>",
  "report_date_suffix": "<date +%Y-%m-%d>",
  "schema_version": 1,
  "plugin_version": "<version from <plugin>/.claude-plugin/plugin.json>"
}

1. Stage 0 (post-C5 normalization). If

   $PHASE_DIR/rewrite.json

   exists and validates as a payload (

   CONTROL=ok

   ), do NOT use live

   repo_*

   values. Run three integrity checks: (1)

   rewrite.baseline_parent_sha

   equals the SAVED

   repo_head_sha

   ; (2)

   git rev-parse <rewrite.branch_name>

   equals

   rewrite.branch_tip_sha

   ; (3)

   git status --porcelain

   (with the artifact exclusions) is empty. All pass → copy the saved

   repo_*

   values into current-context verbatim, continue to step 3. Check 2 fails (tip moved) → STOP and AskUserQuestion: "Keep your commits (regenerate report only, with a mixed-authorship note)" / "Reset the branch to the rewriter's tip and regenerate from C6" / "Abort". Check 3 fails (dirty tree) → STOP and ask: commit/stash (then re-check) or discard the edits. Check 1 fails → treat as a full

   repo_*

   mismatch in step 3.
2. If

   $PHASE_DIR/run-context.json

   exists, compare:

uv run --project $SCRIPTS python $SCRIPTS/validate_result.py --check-run-context $PHASE_DIR/run-context.json --current $PHASE_DIR/current-context.json

• RUN_CONTEXT=match

  → resume: walk C1→C2→C3→(C4: delta-decisions.json)→C5→(C6: report file) in order; a phase counts completed iff its file validates with

  CONTROL=ok

  (C6: iff

  MIGRATION_REPORT_<saved suffix>.md

  exists while rewrite.json is payload-valid). STOP the walk at the first missing/invalid/control-state file — blocked/partial files route to their flows below, NEVER count as completed. Offer the user "skip completed phases X..Y, resume at Z". Files after an unexplained gap: archive them with the gap.

• RUN_CONTEXT=mismatch

  → scoped invalidation. Map each MISMATCH line through this table, archive the named units to

  $REPO/.saws-migrate/phase-results-archive/<saved suffix>-$(date +%H%M%S)/

  (a SIBLING of phase-results/ — never nest it inside), then immediately overwrite run-context.json with current-context.json (carrying forward the saved

  report_date_suffix

  unless REPORT itself is being invalidated), then re-run the invalidated phases in order. Tell the user which fields differed and what re-runs.

.saws-migrate/golden-dataset/

.saws-migrate/eval-results/

MIGRATION_REPORT_<saved suffix>.md

git checkout <saved repo_branch>

saws-migrate-baseline

1. No saved run-context → fresh run: write current-context.json as run-context.json, dispatch C1.

migration-to-aws:llm2bedrock-code-analyzer

$PHASE_DIR/analysis.json

migration-to-aws:llm2bedrock-log-ingestor

$PHASE_DIR/ingestion.json

migration-to-aws:llm2bedrock-prompt-evaluator

$PHASE_DIR/eval.json

CONTROL=blocked

• model_access

  → user enables the model in the Bedrock console (nothing fingerprinted changes; re-dispatch the blocked phase only)

• model_unresolvable

  → user picks/pastes an ID → record it in

  resolved_model_overrides

  , fold it into the Target line

• source_key_auth

  → user supplies a new key (re-run B3) or sets baseline unavailable

• assess_output_missing

  → re-run Phase A, then restart Phase C at C0

CONTROL=partial

• Continue remaining cases → re-dispatch the evaluator with the extra context line:

  Resume: raw_results.jsonl already contains completed cases — evaluate only prompts whose ids are not present in it, then re-score and overwrite eval.json

• Proceed with partial pass rate → re-dispatch the evaluator with:

  Finalize partial: do NOT call Bedrock again — score the cases already in raw_results.jsonl and emit the FULL eval payload over only those cases, with total_cases = the number scored and a notes prefix line 'partial_coverage: <completed>/<total> cases (throttled)'

  . Then C4 runs normally.
• Abort → stop; the files stay on disk for a later C0 resume.

$PHASE_DIR/eval.json

source_baseline_quality != 'poor'

no_golden_cases: true

• Proceed anyway → gate (b)
• Change target model → record in

  resolved_model_overrides

  , re-run C0 (the table invalidates ANALYSIS/EVAL and execution resumes at C1). Cap: 2 retries.
• Abort → stop, no code touched.

migration_path

$MIGRATION_DIR/aws-design-ai.json

ai_architecture.code_migration.migration_path

"mantle"

rewrite_strategy = "mantle"

"converse"

"gpt-oss"

rewrite_strategy = "converse"

analysis.behavior_deltas[]

user_visible == true

behavior-delta-detection

$HELPERS/behavior-delta-detection/behavior-delta-detection.md

source_provider

references/

{delta_type, location, resolution_chosen, source}

[]

$PHASE_DIR/delta-decisions.json

--schema delta-decisions

migration-to-aws:llm2bedrock-code-rewriter

$PHASE_DIR/rewrite.json

migration-to-aws:llm2bedrock-report-generator

MIGRATION_REPORT_<saved suffix>.md

Confirmed behavior-delta decisions file

Report date suffix

rewrite_strategy == "mantle"

• Rewrite strategy: mantle

  (omit this line entirely for Converse — its absence is the signal for the default Converse path)

• Mantle model map: <source-model> -> <bedrock-model-id>

  — sourced from the plan's

  ai_architecture.bedrock_models[]

  entries (each

  source_model

  →

  aws_model_id

  pair).

uv run --project $SCRIPTS python $SCRIPTS/render_report.py --phase-results $PHASE_DIR --repo $REPO --date-suffix <saved suffix>

rewrite.branch_name

bedrock-migration

bedrock-migration-2

rewrite.branch_name

bedrock-migration

To discard:

git checkout <your original branch>

,

git branch -D <rewrite.branch_name>

,

git tag -d saws-migrate-baseline

, and

rm -rf .saws-migrate .migration

removes all migration artifacts (including the API key file).

1. Read

   exactly ONE agent definition (

   <plugin>/agents/<name>.md

   ) — never load more than one phase's definition into context at once.
2. Follow it start-to-finish; write and validate the same phase-result file.
3. STOP. Report the phase outcome (validator CONTROL line + one-line summary) and ask the user to confirm before loading the next phase's definition. This sidebar is mandatory: it is the context-pressure release valve, and the phase-result file means nothing is lost if the user continues in a fresh session instead.

• An agent dispatch dies (tool error, terminal failure) → the phase file is missing → validator exit 2 → the stateless fixer-retry path (which, finding no file to fix, re-runs the phase). Do not auto-retry more than the 2-retry cap.
• User aborts at any gate → confirm no SOURCE CODE was modified (C5 never started if aborted before then). Note that

  .migration/

  and

  .saws-migrate/

  artifacts do exist; show the undo commands from C7 if the user wants them gone.
• Assess skill fails → show the error and stop. User can re-run

  /migration-to-aws:llm-to-bedrock

  .