Gcp To Aws

GCP-to-AWS Migration Skill

Philosophy

• Re-platform by default: Select AWS services that match GCP workload types (e.g., Cloud Run → Fargate, Cloud SQL → RDS).
• 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 — Terraform IaC for infrastructure, billing data for service mapping, and app code for AI workload detection.
• *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).

---

Definitions

• "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).

---

Context Loading Rules

Each phase loads reference files on demand. To keep per-turn context manageable and prevent instruction-following degradation:

• 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.

Conditional reference files (load ONLY when condition is true):

When adding new reference files, verify the phase's total loaded instructions remain under budget. If a new file would exceed ~800 lines when combined with other loaded refs, split it or make it conditional.

---

Prerequisites

User must provide at least one GCP source:

• 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)

If none of the above are found, stop and ask user to provide at least one source type.

---

State Machine

This is the execution controller. After completing each phase, consult this table to determine the next action.

How to determine current state (deterministic):

1. Read $MIGRATION_DIR/.phase-status.json 2. If current_phase exists, use it (must match one of: discover, clarify, design, estimate, generate, complete) 3. Otherwise use ordered phase evaluation: discover → clarify → design → estimate → generate 4. Pick the first phase in that order where phases.<phase> != "completed"; if none, state is complete

Phase gate checks: If prior phase incomplete, do not advance (e.g., cannot enter estimate without completed design).

Clarify is mandatory: Do not load references/phases/design/design.md, references/phases/estimate/estimate.md, or references/phases/generate/generate.md unless $MIGRATION_DIR/.phase-status.json exists and phases.clarify is exactly "completed". A preferences.json file alone is not sufficient proof that Clarify ran. If the user asks to skip Clarify or jump straight to Design, cost estimate, or artifact generation, refuse briefly, then load references/phases/clarify/clarify.md and run Phase 2. There is no exception for "quick" or "obvious" migrations.

Feedback checkpoints: Feedback is not a sequential phase — it is offered at two interleaved checkpoints (after Discover and after Estimate). See the Feedback Checkpoints section below for details.

---

State Validation

When reading $MIGRATION_DIR/.phase-status.json, validate before proceeding:

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, STOP. Output: "State file corrupted (invalid JSON). Delete the file and restart the current phase." 3. Unrecognized phase: If phases object contains a phase not in {discover, clarify, design, estimate, generate, feedback}, STOP. Output: "Unrecognized phase: [value]. Valid phases: discover, clarify, design, estimate, 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." 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."

---

State Management

Migration state lives in $MIGRATION_DIR (.migration/[MMDD-HHMM]/), created by Phase 1 and persisted across invocations.

.phase-status.json schema:

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

Status values: "pending" → "in_progress" → "completed". Never goes backward. For core phases (discover, clarify, design, estimate, generate), at most one phase may be "in_progress" at any time. current_phase is optional but recommended; when present it is authoritative.

The .migration/ directory is automatically protected by a .gitignore file created in Phase 1.

Phase Status Update Protocol

Use read-merge-write updates for .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). 5. Write the full file in the same turn as your final phase work message.

Example — after completing the Clarify phase, write $MIGRATION_DIR/.phase-status.json with:

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

Replace MMDD-HHMM with the actual migration ID, generate the last_updated ISO 8601 UTC timestamp yourself, and set each phase to its correct status at that point.

---

Phase Summary Table

---

MCP Servers

awspricing (for cost estimation):

• 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.

---

Files in This Skill

gcp-to-aws/
├── SKILL.md                                    ← You are here (orchestrator + state machine)
│
├── references/
│   ├── phases/
│   │   ├── discover/
│   │   │   ├── discover.md                     # Phase 1: Discover orchestrator
│   │   │   ├── discover-iac.md                 # Terraform/IaC discovery
│   │   │   ├── discover-app-code.md            # App code discovery
│   │   │   └── discover-billing.md             # Billing data discovery
│   │   ├── clarify/
│   │   │   ├── clarify.md                     # Phase 2: Clarify orchestrator
│   │   │   ├── clarify-global.md              # Category A: Global/Strategic (Q1-Q7)
│   │   │   ├── clarify-compute.md             # Categories B+C: Config Gaps + Compute (Q8-Q11)
│   │   │   ├── clarify-database.md            # Category D: Database (Q12-Q13)
│   │   │   ├── clarify-ai.md                  # Category F: AI/Bedrock (Q14-Q22)
│   │   │   └── clarify-ai-only.md             # Standalone AI-only migration flow
│   │   ├── design/
│   │   │   ├── design.md                       # Phase 3: Design orchestrator
│   │   │   ├── design-infra.md                 # Infrastructure design (IaC-based)
│   │   │   ├── design-ai.md                    # AI workload design (Bedrock)
│   │   │   └── design-billing.md               # Billing-only design (fallback)
│   │   ├── estimate/
│   │   │   ├── estimate.md                     # Phase 4: Estimate orchestrator
│   │   │   ├── estimate-infra.md               # Infrastructure cost analysis
│   │   │   ├── estimate-ai.md                  # AI workload cost analysis
│   │   │   └── estimate-billing.md             # Billing-only cost analysis
│   │   ├── generate/
│   │   │   ├── generate.md                     # Phase 5: Generate orchestrator
│   │   │   ├── generate-infra.md               # Infrastructure migration plan
│   │   │   ├── generate-ai.md                  # AI migration plan
│   │   │   ├── generate-billing.md             # Billing-only migration plan
│   │   │   ├── generate-artifacts-infra.md     # Terraform configurations
│   │   │   ├── generate-artifacts-scripts.md  # Migration scripts
│   │   │   ├── generate-artifacts-ai.md        # Provider adapter + test harness
│   │   │   ├── generate-artifacts-billing.md   # Skeleton Terraform
│   │   │   └── generate-artifacts-docs.md      # MIGRATION_GUIDE.md + README.md
│   │   └── feedback/
│   │       ├── feedback.md                     # Phase 6: Feedback orchestrator
│   │       └── feedback-trace.md               # Anonymized trace builder
│   │
│   ├── design-refs/
│   │   ├── index.md                            # Lookup table: GCP type → design-ref file
│   │   ├── fast-path.md                        # Deterministic 1:1 mappings (Pass 1)
│   │   ├── compute.md                          # Compute mappings (Cloud Run, GCE, GKE, etc.)
│   │   ├── database.md                         # Database mappings (Cloud SQL, Spanner, etc.)
│   │   ├── storage.md                          # Storage mappings (GCS, Filestore, etc.)
│   │   ├── networking.md                       # Networking mappings (VPC, LB, DNS, etc.)
│   │   ├── messaging.md                        # Messaging mappings (Pub/Sub, etc.)
│   │   └── ai.md                               # AI mappings (Vertex AI → Bedrock)
│   │
│   ├── clustering/terraform/
│   │   ├── classification-rules.md             # Primary/secondary classification
│   │   ├── clustering-algorithm.md             # Cluster formation rules
│   │   ├── depth-calculation.md                # Topological depth calculation
│   │   └── typed-edges-strategy.md             # Edge type assignment
│   │
│   └── shared/
│       ├── schema-phase-status.md              # .phase-status.json schema (canonical reference)
│       ├── schema-discover-iac.md              # gcp-resource-inventory + clusters schemas (loaded by discover-iac.md)
│       ├── schema-discover-ai.md               # ai-workload-profile schema (loaded by discover-app-code.md and discover-iac.md Step 7d)
│       ├── schema-discover-billing.md          # billing-profile schema (loaded by discover-billing.md)
│       ├── schema-estimate-infra.md            # estimation-infra.json schema (loaded by estimate-infra.md at write time)
│       ├── migration-complexity.md             # Complexity tier definitions (small/medium/large) for timeline scaling
│       ├── pricing-cache.md                    # Cached AWS + source provider pricing (±5-25%, primary source)
│       └── bedrock-quotas.md                   # Bedrock TPM/RPM quota awareness, burndown rates, capacity planning

Defaults

• 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)
• 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.

Workflow Execution

When invoked, the agent MUST follow this exact sequence:

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.

6. Update phase status: Use the Phase Status Update Protocol (read-merge-write) in the same turn as the phase's final output message.

7. Feedback checkpoint: 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 (if phases.feedback is "pending"): Output to user:

"Would you like to share quick feedback now? (5 optional questions + anonymized usage data) [A] Yes, share feedback [B] No thanks, continue to Generate"

• If user picks A → Load references/phases/feedback/feedback.md, execute it, then continue to Generate.
• If user picks B → Use the Phase Status Update Protocol to set phases.feedback to "completed". Continue to Generate.

• 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).

8. Display summary: Show user what was accomplished, highlight next phase, or confirm migration completion.

Critical constraint: Agent must strictly adhere to the reference file's workflow. If unable to complete a step, stop and report the exact step that failed.

User can invoke the skill again to resume from current_phase (or deterministic ordered evaluation when current_phase is absent).

Scope Notes

v1.0 includes:

• Terraform infrastructure discovery
• App code scanning (AI workload detection)
• Billing data import from GCP
• User requirement clarification (adaptive questions by category)
• 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

Terraform Clustering: Classification Rules

Hardcoded lists for classifying GCP resources as PRIMARY or SECONDARY.

Each PRIMARY resource is assigned a tier indicating its infrastructure layer.

Priority 0: Excluded Resources (Skip Entirely)

These resource types are excluded from classification, clustering, and migration. Do not classify them as PRIMARY or SECONDARY. Do not create clusters for them. Do not include them in gcp-resource-inventory.json.

Authentication Providers

Third-party and GCP-adjacent authentication resources. Users should keep their existing auth provider — do not recommend migrating to AWS Cognito or any AWS auth service.

• google_identity_platform_* — GCP Identity Platform (all variants: config, tenant, default_supported_idp_config, inbound_saml_config, oauth_idp_config)
• google_firebase_auth_* — Firebase Authentication (all variants)

If encountered: log as "Auth provider detected — excluded from migration scope. Keep your existing auth solution." and skip.

Priority 1: PRIMARY Resources (Workload-Bearing)

These resource types are always PRIMARY:

Compute (tier: "compute")

• google_cloud_run_service — Serverless container workload
• google_cloud_run_v2_service — Serverless container workload (v2 API)
• google_container_cluster — Kubernetes cluster
• google_container_node_pool — Kubernetes node pool
• google_compute_instance — Virtual machine
• google_cloudfunctions_function — Serverless function (Gen 1)
• google_cloudfunctions2_function — Serverless function (Gen 2)
• google_app_engine_application — App Engine application

Database (tier: "database")

• google_sql_database_instance — Relational database
• google_spanner_instance — Globally-distributed relational database
• google_firestore_database — Document database
• google_bigtable_instance — Wide-column NoSQL database
• google_redis_instance — In-memory cache

Storage (tier: "storage")

• google_storage_bucket — Object storage
• google_filestore_instance — Managed NFS file storage
• google_bigquery_dataset — Data warehouse

Messaging (tier: "messaging")

• google_pubsub_topic — Message queue
• google_cloud_tasks_queue — Task queue

Networking (tier: "networking")

• google_compute_network — Virtual network (VPC — primary because it defines topology)
• google_compute_security_policy — Web application firewall (Cloud Armor)
• google_dns_managed_zone — DNS zone

Monitoring (tier: "monitoring")

• google_monitoring_alert_policy — Alert policy

Other

• module.* — Terraform module that wraps primary resources (tier inferred from wrapped resource)

Action: Mark as PRIMARY with assigned tier. Classification done. No secondary_role.

Priority 2: SECONDARY Resources by Role

Match resource type against secondary classification table. Each match assigns a secondary_role:

Identity (identity)

• google_service_account — Workload identity
• data.google_service_account — Data source reference to existing service account

Access Control (access_control)

• google_*_iam_member — IAM binding (all variants: project, cloud_run_service, storage_bucket, etc.)
• google_*_iam_policy — IAM policy (all variants)

Network Path (network_path)

• google_vpc_access_connector — VPC connector for serverless
• google_compute_subnetwork — Subnet
• google_compute_firewall — Firewall rule
• google_compute_router — Cloud router
• google_compute_router_nat — NAT rule
• google_compute_global_address — Global IP address (for VPC peering, load balancing)
• google_service_networking_connection — VPC peering

Configuration (configuration)

• google_sql_database — SQL schema
• google_sql_user — SQL user
• google_spanner_database — Spanner database schema
• google_secret_manager_secret — Secret vault
• google_secret_manager_secret_version — Secret value
• google_dns_record_set — DNS record
• google_monitoring_notification_channel — Alert notification target

Encryption (encryption)

• google_kms_crypto_key — KMS encryption key
• google_kms_key_ring — KMS key ring

Orchestration (orchestration)

• null_resource — Terraform orchestration marker
• time_sleep — Orchestration delay
• google_project_service — API service enablement (prerequisite, not a deployable unit)

Action: Mark as SECONDARY with assigned role.

Priority 3: LLM Inference Fallback

If resource type not in Priority 1 or 2, apply these deterministic fallback heuristics BEFORE free-form LLM reasoning:

If still uncertain after heuristics, use LLM reasoning. Mark with:

• classification_source: "llm_inference"
• confidence: 0.5-0.75

Default: If all heuristics and LLM fail: SECONDARY / configuration with confidence 0.5. It is safer to under-classify (secondary) than over-classify (primary), because secondaries are grouped into existing clusters while primaries create new clusters.

Serves[] Population

For SECONDARY resources, populate serves[] array (list of PRIMARY resources it supports):

1. Extract all outgoing references from this SECONDARY's config 2. Include direct references: field = resource_type.name.id patterns 3. Include transitive chains: if referenced resource is also SECONDARY, trace to PRIMARY

Example: google_compute_firewall → references google_compute_network (SECONDARY) → serves google_compute_instance.web (PRIMARY)

Serves array: Points back to PRIMARY workloads affected by this firewall rule. Trace through SECONDARY resources until a PRIMARY is reached.

Terraform Clustering: Deterministic Algorithm

Groups resources into named clusters using priority-ordered rules.

Input

All resources with fields:

• address, type, classification (PRIMARY/SECONDARY)
• secondary_role (if SECONDARY)
• typed_edges[], depth, serves[]

Algorithm: Apply Rules in Priority Order

Rule 1: Networking Cluster

IF google_compute_network resource exists:

• Group: google_compute_network + ALL network_path secondaries (subnetworks, firewalls, routers)
• Cluster ID: networking_vpc_{gcp_region}_001 (e.g., networking_vpc_us-central1_001)
• Reasoning: Network is shared infrastructure; groups all config together

Output: 1 cluster (or 0 if no networks found)

Mark these resources as clustered; remove from unassigned pool.

Rule 2: Same-Type Grouping (GROUP ALL INTO ONE CLUSTER PER TYPE)

CRITICAL: Create ONE cluster per resource type, NOT one cluster per resource.

Process:

1. Identify all resource types with 2+ PRIMARY resources

• Example: 4× google_pubsub_topic, 3× google_storage_bucket, 2× google_sql_database_instance

2. For EACH resource type with 2+ primaries: Create ONE cluster containing ALL of them

• Do NOT create separate clusters for each resource
• Create ONE cluster with ALL matching resources

3. Cluster ID format: {service_category}_{service_type}_{gcp_region}_{sequence:001}

• messaging_pubsubtopic_us-central1_001 (contains ALL 4 pubsub topics)
• storage_bucket_us-central1_001 (contains ALL 3 storage buckets)
• database_sql_us-central1_001 (contains ALL 2 SQL instances)

4. Primary resources in cluster: List ALL matching resources

• Example cluster messaging_pubsubtopic_us-central1_001:
• primary_resources:
• google_pubsub_topic.order_events
• google_pubsub_topic.inventory_events
• google_pubsub_topic.user_events
• google_pubsub_topic.dead_letter

5. Secondary resources: Collect ALL secondaries that serve ANY of the grouped primaries

• All subscriptions for all grouped topics
• All IAM bindings for all grouped resources
• All supporting resources

Correct Examples (ONE cluster per type):

• 4× google_pubsub_topic → 1 cluster: messaging_pubsubtopic_us-central1_001
• 3× google_storage_bucket → 1 cluster: storage_bucket_us-central1_001
• 2× google_sql_database_instance → 1 cluster: database_sql_us-central1_001
• 3× google_container_cluster → 1 cluster: compute_gke_us-central1_001 (NOT k8s_001, k8s_002, k8s_003)

INCORRECT Examples (DO NOT DO THIS):

• ❌ 4× google_pubsub_topic → 4 clusters (compute_pubsubtopic_001, compute_pubsubtopic_002, etc.)
• ❌ 3× google_storage_bucket → 3 clusters (compute_storagebucket_001, compute_storagebucket_002, etc.)
• ❌ 3× google_container_cluster → 3 clusters (k8s_001, k8s_002, k8s_003)

Output: ONE cluster per resource type (not per resource)

Reasoning: Identical workloads of the same GCP service type migrate together, share operational characteristics, and are managed as a unit.

Mark all resources of this type as clustered; remove from unassigned pool.

Rule 3: Seed Clusters

FOR EACH remaining PRIMARY resource (unassigned):

• Create cluster seeded by this PRIMARY
• Add all SECONDARY resources in its serves[] array
• Cluster ID: {service_type}_{gcp_region}_{sequence} (e.g., cloudrun_us-central1_001)
• Reasoning: Primary + its supports = deployment unit

Output: N clusters (one per remaining PRIMARY)

Mark all included resources as clustered.

Rule 4: Merge on Dependencies

IF two clusters have bidirectional data_dependency edges between their PRIMARY resources (A→B AND B→A):

• THEN merge clusters

Action: Combine into one cluster; update ID to reflect both (e.g., web-api_us-central1_001)

Reasoning: Bidirectional data dependencies indicate a tightly coupled deployment unit that must migrate together.

Do NOT merge when edges are unidirectional (A→B only). Unidirectional dependencies are captured in dependencies[] instead.

Rule 5: Skip API Services

IF resource is google_project_service:

• Classify as orchestration secondary
• Do NOT create its own cluster
• Attach to cluster of service it enables (e.g., google_project_service.cloud_run attaches to Cloud Run cluster)

Reasoning: API enablement is prerequisite, not a deployable unit.

Rule 6: Deterministic Naming

Apply consistent cluster naming:

• Format: {service_category}_{service_type}_{gcp_region}_{sequence}
• service_category: One of: compute, database, storage, networking, messaging, monitoring, analytics, security
• service_type: GCP service shortname (e.g., cloudrun, sql, bucket, vpc)
• gcp_region: Source region (e.g., us-central1)
• sequence: Zero-padded counter (e.g., 001, 002)

Examples:

• compute_cloudrun_us-central1_001
• database_sql_us-west1_001
• storage_bucket_multi-region_001
• networking_vpc_us-central1_001 (rule 1 network cluster)

Reasoning: Names reflect deployment intent; deterministic for reproducibility.

Post-Clustering: Populate Cluster Metadata

After all clusters are formed, populate these fields for each cluster:

network

Identify which VPC/network the cluster's resources belong to. Trace network_path edges from resources in this cluster to find the google_compute_network they reference. Store the network cluster ID (e.g., networking_vpc_us-central1_001). Set to null if resources have no network association.

must_migrate_together

Default: true for all clusters. Set to false only if the cluster contains resources that can be independently migrated without breaking dependencies (rare — most clusters are atomic).

dependencies

Derive from Primary→Primary edges that cross cluster boundaries. If cluster A contains a resource with a data_dependency edge to a resource in cluster B, then cluster A depends on cluster B. Store as array of cluster IDs.

creation_order

Build a global ordering of clusters by depth level:

"creation_order": [
  { "depth": 0, "clusters": ["networking_vpc_us-central1_001"] },
  { "depth": 1, "clusters": ["security_iam_us-central1_001"] },
  { "depth": 2, "clusters": ["database_sql_us-central1_001", "storage_gcs_us-central1_001"] },
  { "depth": 3, "clusters": ["compute_cloudrun_us-central1_001"] }
]

Cluster depth = minimum depth across all primary resources in the cluster. Clusters at the same depth can be migrated in parallel.

Output Cluster Schema

Each cluster includes:

{
  "cluster_id": "compute_cloudrun_us-central1_001",
  "gcp_region": "us-central1",
  "primary_resources": ["google_cloud_run_service.app"],
  "secondary_resources": ["google_service_account.app_runner"],
  "network": "networking_vpc_us-central1_001",
  "creation_order_depth": 2,
  "must_migrate_together": true,
  "dependencies": ["database_sql_us-central1_001"],
  "edges": [
    {
      "from": "google_cloud_run_service.app",
      "to": "google_sql_database_instance.db",
      "relationship_type": "data_dependency",
      "evidence": {
        "field_path": "template.spec.containers[0].env[].value",
        "reference": "DATABASE_URL"
      }
    }
  ]
}

Determinism Guarantee

Given the same classified resource inputs, the clustering algorithm produces the same cluster structure every run:

1. Rules applied in fixed order 2. Sequence counters increment deterministically 3. Naming reflects source state, not random IDs 4. All clustering heuristics are deterministic (no LLM-based decisions within the clustering algorithm itself)

Note: Resource classification (see classification-rules.md) may use LLM inference as a fallback for resource types not in the hardcoded tables. If LLM-classified resources enter the pipeline, overall reproducibility depends on the LLM producing consistent classifications.

Terraform Clustering: Depth Calculation

Assigns topological depth to every resource via Kahn's algorithm (longest path variant).

Depth Semantics

• Depth 0: Resources with no incoming dependencies (can start immediately)
• Depth N: Resources where all dependencies are at depth ≤ N-1, and at least one is at depth N-1

Higher depth = later in deployment sequence.

Algorithm: Kahn's Algorithm (Longest Path Variant)

Input

All resources with:

• address, type
• dependencies[] array (addresses of resources this one depends on)

Step 1: Build Dependency Graph

For each resource:

• Outgoing edges: follow its dependencies[] array
• Incoming edges: count how many resources depend on this one
• Store: in_degree[resource] = count_of_incoming_edges

Step 2: Initialize Queue

Create queue of all resources with in_degree = 0.

These are depth 0 (no dependencies).

Assign: depth[resource] = 0 for all queued resources.

Step 3: Process Queue (Longest Path)

While queue not empty:

1. Dequeue resource R 2. For each resource D that depends on R (traverse reverse edges):

• Update: depth[D] = max(depth[D], depth[R] + 1)
• Decrement: in_degree[D] -= 1
• If in_degree[D] becomes 0: Enqueue D

Note: "Resources that depend on R" means all resources X where X's dependencies[] contains R. This correctly assigns higher depths to dependent resources (which must deploy later).

Step 4: Cycle Detection

If queue empties but unassigned resources remain:

• Cycle detected: Some resources have circular dependencies
• Bounded retry (max 3 attempts total):

1. Identify the cycle (trace unassigned resources' dependencies) 2. Find lowest-confidence edge in cycle (prefer unknown_dependency or LLM-inferred edges over deterministic edges) 3. Only break inferred edges (confidence < 1.0). If all edges in the cycle are deterministic (hardcoded classification), do NOT break — proceed to STOP. 4. Remove the selected edge and restart the algorithm 5. Log warning: "Circular dependency detected and broken (attempt N/3): {resources and edges removed}"

• If cycle persists after 3 attempts: STOP. Output: "Unresolvable circular dependency between: [resource addresses]. All edges are deterministic. Manual review required — restructure Terraform dependencies or add depends_on overrides."

Step 5: Assign Final Depths

All resources have assigned depth field.

Verify: Every resource has depth ∈ [0, max_depth].

Pseudocode

function calculateDepth(resources) {
  // Build graph
  in_degree = {}
  depends_on = {}
  dependents_of = {}  // Reverse adjacency: resource → resources that depend on it
  for each resource R:
    in_degree[R] = count incoming edges
    depends_on[R] = R.dependencies[]
    dependents_of[R] = []

  // Populate dependents_of (reverse edges)
  for each resource R:
    for each D in R.dependencies[]:
      dependents_of[D].append(R)

  // Initialize depth 0
  depth = {}
  queue = [R for R in resources if in_degree[R] == 0]
  for each R in queue:
    depth[R] = 0

  // Process queue (longest path variant)
  while queue not empty:
    R = queue.dequeue()
    for each D in dependents_of[R]:  // Iterate resources that depend on R
      depth[D] = max(depth[D], depth[R] + 1)
      in_degree[D] -= 1
      if in_degree[D] == 0:
        queue.enqueue(D)

  // Cycle check (bounded: max 3 attempts)
  if any resource not assigned depth:
    if attempt >= 3:
      STOP("Unresolvable circular dependency. Manual review required.")
    edge = find_lowest_confidence_edge_in_cycle()
    if edge.confidence == 1.0:
      STOP("Cycle contains only deterministic edges. Manual review required.")
    remove(edge)
    return calculateDepth(resources, attempt + 1)  // Retry

  return depth
}

Example

Resources and dependencies:

A: depends on [] → depth 0
B: depends on [A] → depth 1
C: depends on [A] → depth 1
D: depends on [B, C] → depth 2

Queue trace:

1. Initial queue: [A] (in_degree 0) 2. Dequeue A, depth[A]=0; enqueue B, C (both now in_degree 0) 3. Dequeue B, depth[B]=1; update depth[D]=max(0,1+1)=2; in_degree[D]=1 4. Dequeue C, depth[C]=1; update depth[D]=max(2,1+1)=2; enqueue D (in_degree 0) 5. Dequeue D, depth[D]=2 6. Queue empty; all depths assigned

Final: A:0, B:1, C:1, D:2 ✓

Deployment Order Guarantee

Resources sorted by ascending depth can deploy in order:

Deploy depth 0: A
Deploy depth 1: B, C (parallel OK)
Deploy depth 2: D

No dependency violations; parallelism at same depth.

Terraform Clustering: Typed Edge Strategy

Infers edge types from HCL context to classify relationships between resources.

Edges are categorized into two groups:

• Secondary→Primary relationships — infrastructure support (identity, network, encryption)
• Primary→Primary relationships — service communication (data, cache, messaging, storage)

Pass 1: Extract References from HCL

Parse HCL configuration text for all resource_type.name.attribute patterns:

• Regex: (google_\w+)\.(\w+)\.(\w+) or google_\w+\.[\w\.]+
• Capture fully qualified references: google_sql_database_instance.prod.id
• Include references in: attribute values, depends_on arrays, variable interpolations

Store each reference with:

• reference: target resource address
• field_path: HCL attribute path where reference appears
• raw_context: surrounding HCL text (10 lines for LLM context)

Pass 2: Classify Edge Type by Field Context

For each reference, determine edge type. Use the secondary_role of the source resource to guide classification.

Secondary→Primary Relationships

These use the secondary's secondary_role as the relationship type:

• identity_binding — service account attached to compute resource
• network_path — VPC connector, subnet, firewall serving a resource
• access_control — IAM binding granting access to resource
• configuration — database user, secret version, DNS record configuring resource
• encryption — KMS key protecting a resource
• orchestration — null_resource, time_sleep sequencing

Primary→Primary Relationships

Infer from field paths and environment variable names:

Data Dependencies

Field name matches: DATABASE*, DB_*, SQL*, CONNECTION_*

Environment variable name matches: DATABASE*, DB_HOST, SQL_*

• Type: data_dependency
• Example: google_cloud_run_service.app.env.DATABASE_URL → google_sql_database_instance.prod.id

Cache Dependencies

Field name matches: REDIS*, CACHE*, MEMCACHE*

• Type: cache_dependency
• Example: google_cloudfunctions_function.worker.env.REDIS_HOST → google_redis_instance.cache.host

Publish Dependencies

Field name matches: PUBSUB*, TOPIC*, QUEUE*, STREAM*

• Type: publishes_to
• Example: google_cloud_run_service.publisher.env.PUBSUB_TOPIC → google_pubsub_topic.events.id

Storage Dependencies

Field name matches: BUCKET*, STORAGE*, S3*

Direction determined by context:

• Write context (upload, save, persist) → writes_to
• Read context (download, fetch, load) → reads_from
• Bidirectional → Both edge types

• Example: google_cloud_run_service.worker.env.STORAGE_BUCKET → google_storage_bucket.data.name

DNS Resolution

A DNS record pointing to a compute resource.

• Type: dns_resolution
• Example: google_dns_record_set.api → google_compute_instance.web (A record pointing to compute IP)

Network Membership

Resources sharing the same VPC/subnet.

• Type: network_membership
• Example: Multiple primary resources referencing the same google_compute_network.main

Infrastructure Relationships

These apply to both Secondary→Primary and resource-to-resource references:

Network Path

Field name: vpc_connector, network, subnetwork

• Type: network_path
• Example: google_cloudfunctions_function.app.vpc_connector → google_vpc_access_connector.main.id

Encryption

Field name: kms_key_name, encryption_key, key_ring

• Type: encryption
• Example: google_sql_database_instance.db.backup_encryption_key_name → google_kms_crypto_key.sql.id

Orchestration

Explicit depends_on array

• Type: orchestration
• Example: depends_on = [google_project_service.run]

Default Fallback

If no patterns match, use LLM to infer edge type from:

• Resource types (compute → storage likely data_dependency)
• Field names and values
• Raw HCL context

If LLM uncertain: unknown_dependency with confidence field.

Evidence Structure

Every edge must include a structured evidence object:

{
  "from": "google_cloud_run_service.api",
  "to": "google_sql_database_instance.db",
  "relationship_type": "data_dependency",
  "evidence": {
    "field_path": "template.spec.containers[0].env[].value",
    "reference": "DATABASE_URL"
  }
}

Evidence fields:

• field_path — HCL attribute path where the reference appears
• reference — the specific value, variable name, or env var that creates the relationship

All edges stored in resource's typed_edges[] array and in the cluster's edges[] array.

Gemini to Bedrock — Model Selection Guide

Applies to: Vertex AI Generative AI (Gemini models) → Amazon Bedrock

This file is loaded by design-ai.md when ai-workload-profile.json has summary.ai_source = "gemini" or "both". It provides model mapping tables with pricing and honest competitive analysis for Gemini → Bedrock migration decisions.

Verify all pricing via AWS Pricing MCP or references/shared/pricing-cache.md.

Model lifecycle: Before recommending any Bedrock model, check references/shared/ai-model-lifecycle.md. Do not recommend Legacy models as primary selections for new migrations. Legacy models are annotated below where they appear.

---

Competitive Reality (March 2026)

Gemini 3.1 Pro Preview (Feb 19, 2026) has shifted the landscape. Be honest with users:

• Gemini 3.1 Pro leads 13/16 Google-reported benchmarks and 6/10 on the Artificial Analysis Intelligence Index
• ARC-AGI-2: 77.1% (2.5x jump over Gemini 3 Pro), SWE-Bench: 80.6% (tied with Opus 4.6 at 80.8%)
• Costs $2/$12 per 1M tokens — less than half of Opus 4.6 / 4.7 ($5/$25), cheaper than Sonnet 4.6 ($3/$15)
• ~119 tokens/sec — faster than any Bedrock model at this quality tier

Where Bedrock still wins:

• Claude Sonnet 4.6 / Opus 4.x lead on real-world agentic tasks (GDPval evaluation) — the gap between benchmarks and production agent reliability is real
• Claude prompt caching (90% savings on repeated content) has no Gemini equivalent at Preview tier
• Claude function calling remains best-in-class for complex multi-turn tool use
• AWS ecosystem integration (Bedrock Agents, Knowledge Bases, Guardrails) has no Gemini equivalent

Migration case by tier:

• Gemini Pro → Bedrock: driven by AWS consolidation, agentic reliability, or ecosystem — NOT cost or general benchmarks
• Gemini Flash/Lite → Nova Lite/Micro: still 64-88% cheaper, strong cost case
• Gemini 2.5 Pro → Bedrock: moderate case (older model, higher price than 3.1 Pro)

---

Bedrock Model Portfolio

---

Gemini → Bedrock Model Mapping

Gemini Pro Tier

Gemini Flash/Lite Tier

Legacy/Specialized

_Percentages are blended savings using a 2:1 input-to-output token ratio. Actual savings depend on your input/output ratio._

---

Decision Paths by Priority

Quality-First

Gemini 3.1 Pro Preview matches or beats Opus 4.6 on most reasoning benchmarks at less than half the cost. Be transparent:

• If user needs general reasoning/coding quality → Gemini 3.1 Pro is competitive or better. Migration case is weak unless driven by AWS consolidation.
• If user needs agentic reliability (real-world multi-step tasks) → Claude Sonnet 4.6 still leads on GDPval. This is the honest differentiator.
• If user needs maximum reasoning on hardest problems → Claude Opus 4.7 ($5/$25 headline on-demand, same tier as Opus 4.6) — use the latest Claude on Bedrock model card for benchmark deltas vs Gemini; Opus 4.6 remains a same-price alternative where batch or regional availability matters.

Speed-First

Gemini Flash → Nova Micro (<200ms, text-only, cheapest), Haiku 4.5 (<400ms, vision), or Llama 4 Scout (<300ms, cheapest capable)

Cost-First

• Gemini Flash/Lite → Nova Lite (54-88% cheaper), Nova Micro (53-64% cheaper)
• Gemini Pro → Llama 4 Maverick ($0.24/$0.97, 63% cheaper than Gemini 3 Pro) or Llama 4 Scout ($0.17/$0.66, 75% cheaper)

Balanced

• Gemini 3.1 Pro → Nova 2 Pro (-14% cost, AWS-native) or Claude Sonnet 4.6 (+31% cost, stronger agentic reliability)
• Gemini 2.5 Pro → Nova 2 Pro (+10% cost, AWS-native) or Nova Pro (-62% cost)
• Gemini 3 Pro → Llama 4 Maverick (-63%), Nova Pro (+20%)

---

Volume-Based Recommendations

Low (<1M tokens/day): Use best model for quality. Cost difference minimal at this volume.

Medium (1-10M tokens/day): Present cost comparison at volume. At 5M input + 2.5M output/day:

High (10-100M tokens/day): Cost optimization critical. Recommend multi-model tiered approach. Llama 4 Maverick/Scout or Nova for output-heavy workloads.

Very high (>100M tokens/day): Mandatory multi-model tiered strategy:

• Simple tasks (60% of traffic) → Nova Micro or Llama 4 Scout
• Moderate tasks (30% of traffic) → Llama 4 Maverick or Nova Pro
• Complex tasks (10% of traffic) → Claude Sonnet 4.6

---

Cost Comparison Table (150M input + 75M output per month)

_Difference column shows blended savings at a 2:1 input/output token ratio. Positive = Bedrock costs more (Gemini cheaper), negative = Bedrock cheaper._

---

Prompt Caching (Claude Only)

Cache frequently-used system prompts for 90% cost reduction on cached portions. Example: 10K token system prompt repeated 1000x → $30 without caching, $3 with caching.

Not available on other Bedrock models. This is a significant Claude advantage for applications with heavy system prompt repetition.

---

Feature Migration Notes

OpenAI to Bedrock — Model Selection Guide

Applies to: OpenAI SDK usage detected in GCP-hosted applications → Amazon Bedrock

This file is loaded by design-ai.md when ai-workload-profile.json has summary.ai_source = "openai" or "both". It provides model mapping tables with pricing and honest competitive analysis for OpenAI → Bedrock migration decisions.

Many GCP-hosted applications use OpenAI's API rather than Vertex AI. This guide covers that migration path.

Verify all pricing via AWS Pricing MCP or references/shared/pricing-cache.md. Uses OpenAI Standard tier pricing.

Model lifecycle: Before recommending any Bedrock model, check references/shared/ai-model-lifecycle.md. Do not recommend Legacy models as primary selections for new migrations. Legacy models are annotated below where they appear.

---

Key Insight: The Landscape Has Changed (April 2026)

It is no longer "Bedrock is always cheaper." It depends on the model.

• Bedrock cheaper: GPT-5.5 flagship (17% cheaper output via Opus 4.6), Nova Lite vs Mini models (85-94%), Nova Micro vs Nano (65-87%), Nova 2 Pro vs Pro models (90-95%), DeepSeek-R1 vs o3 (32%)
• OpenAI cheaper: GPT-5.4 (5%), GPT-5.2 (50%), GPT-5.1/5 (40%), GPT-4.1 (43%), GPT-4o (29%), o4-mini/o3-mini/o1-mini (69%)

GPT-5.5 note (April 23, 2026): GPT-5.5 doubled pricing to $5/$30 per MTok vs GPT-5.4's $2.50/$15. Claude Opus 4.6 at $5/$25 now matches on input and is 17% cheaper on output. This reverses the GPT-5.4 dynamic where OpenAI was cheaper — at the GPT-5.5 tier, Bedrock wins on cost. GPT-5.5 uses 40% fewer output tokens on coding tasks (per OpenAI), partially offsetting the price hike for Codex-style workloads.

---

Model Mapping Tables

GPT-5.5 Series (Latest — April 23, 2026)

GPT-5.5 is the first fully retrained base model since GPT-4.5. Natively omnimodal (text + image + audio + video), 88.7% SWE-Bench Verified, 256K context in ChatGPT / 1M in API. Two variants: standard and Pro. No Mini/Nano variants at launch (expected Q3 2026). Percentages below are blended savings using a 2:1 input-to-output token ratio.

Token efficiency caveat: OpenAI reports GPT-5.5 uses ~40% fewer output tokens on Codex-style tasks vs GPT-5.4. Effective cost increase over GPT-5.4 is ~50% (not 100%) for coding workloads. For non-coding workloads, the full 2× price applies.

GPT-5.4 Series

Percentages below are blended savings using a 2:1 input-to-output token ratio. GPT-5.4 uses breakpoint pricing at 272K input tokens; rates below assume <272K context.

Flagship (GPT-5/5.2 Series)

Percentages below are blended savings using a 2:1 input-to-output token ratio.

Pro Models (Extended Reasoning)

Lifecycle note: Nova Premier v1 is Legacy (EOL Sep 14, 2026). Nova 2 Pro (Preview) is the Active successor for reasoning-heavy workloads. Pricing differs — see pricing-cache.md.

GPT-4.1 Series

GPT-4o Series

Reasoning Models (o-series)

Lifecycle note: Nova Premier v1 is Legacy (EOL Sep 14, 2026). Table below uses Nova 2 Pro (Preview) as the Active replacement.

Legacy Models

OpenAI Models on Bedrock (gpt-oss)

OpenAI's open-source models are available directly on Bedrock, enabling migration without switching model families:

This path avoids model-family risk: the application stays on OpenAI-architecture models while consolidating on AWS infrastructure.

_Percentages are blended savings using a 2:1 input-to-output token ratio. Actual savings depend on your input/output ratio._

---

Migration Decision Framework

Migrate to Bedrock if:

• Using GPT-5.5 flagship → Bedrock 17% cheaper on output via Opus 4.6 ($5/$25 vs $5/$30); Sonnet 4.6 is 53% cheaper
• Using Pro/expensive models (GPT-5.5 Pro, GPT-5.4 Pro, o1-pro) → 87-98% savings via Nova 2 Pro
• Using Mini/Nano models at high volume → 87-94% savings via Nova Lite/Micro
• Using legacy GPT-4/3.5 → 42-82% savings
• Need AWS infrastructure integration
• Need prompt caching (Claude only, 90% savings on cached content)
• Using o3 for reasoning → DeepSeek-R1 on Bedrock is 32% cheaper
• Want to stay on OpenAI models → gpt-oss on Bedrock (same models, AWS infrastructure)

Consider staying on OpenAI if:

• Using GPT-5.5 for omnimodal (audio/video) → Claude is text+image only; GPT-5.5 has native audio/video
• Using GPT-5.4 flagship → only 5% cheaper than Sonnet 4.6; marginal either way
• Using mid-tier flagships (GPT-5, GPT-4.1, o3, o4-mini) → OpenAI 29-69% cheaper
• Low volume (<$500/mo) where absolute savings are small
• Heavily integrated with OpenAI ecosystem (Assistants API, gpt-image, Whisper, Realtime)
• Need Realtime API (no Bedrock equivalent)

Analyze carefully: Calculate actual token usage x model-specific pricing. Small % differences matter at scale.

---

Feature Migration

---

Common Migration Paths

OpenAI SDK → Mantle (minimal code changes)

If the application uses the OpenAI Python/JS SDK directly (from openai import OpenAI / new OpenAI()), Bedrock's Mantle OpenAI-compatible endpoints allow migration with minimal code changes — primarily environment variables plus a model string swap:

1. Set OPENAI_BASE_URL=https://bedrock-mantle.{region}.api.aws/v1 2. Set OPENAI_API_KEY=<bedrock-api-key> — use a Bedrock API key, not your existing OpenAI API key 3. Change model string (e.g., gpt-5.4 → anthropic.claude-sonnet-4-6 or openai.gpt-oss-120b)

Hard gates before recommending Mantle:

• Model compatibility: Verify the selected Bedrock model supports the Responses API — check API compatibility. Not all models do. Do not recommend Mantle Responses API unless the target model is confirmed compatible.
• Region availability: Mantle is available in 13 regions (us-east-1, us-east-2, us-west-2, ap-northeast-1, ap-south-1, ap-southeast-2, ap-southeast-3, eu-central-1, eu-west-1, eu-west-2, eu-south-1, eu-north-1, sa-east-1). If the target region is outside this list, do not recommend Mantle — use the boto3 Converse API path instead.

Supports Chat Completions API, Responses API, streaming, and stateful conversations.

Responses API capabilities (when stateful conversations matter):

• Stateful conversation management — Bedrock rebuilds context automatically; no need to pass full conversation history on each request
• Async / long-running inference — background processing for workloads that exceed typical request timeouts (useful for complex agentic tasks)
• Streaming + non-streaming — both modes supported via the same endpoint

Assistants API → Migration Decision Tree

Assistants API and Responses API are different surfaces. Do not treat all Assistants API usage as an env-var-only migration. Apply this decision tree:

1. App already uses OpenAI Responses API (responses.create) → Mantle is the cleanest path. Env var swap + model string change. Minimal code changes.

2. App uses Assistants API only for stateful multi-turn conversation (no hosted tools, no file search, no code interpreter, no persistent Assistant objects, no complex run lifecycle) → Mantle Responses API is viable. Requires migrating from threads/runs calls to responses.create — this is a small API migration (days), not a full redesign. Not a zero-code-change swap.

3. App uses Assistants API with simple hosted tools (function calling only, no file search or code interpreter) → Mantle Responses API with tool use is viable. Moderate code migration (1-2 weeks) to adapt tool definitions and run lifecycle.

4. App uses Assistants API with file search, vector stores, code interpreter, persistent Assistant objects, or complex run lifecycle management → Do not recommend Mantle. Evaluate: Bedrock Agents (sessions, action groups, knowledge bases) for full agentic replacement (2-4 week migration), or app-managed orchestration if the team prefers to own state.

When to prefer Converse API over Mantle: If you need Bedrock-specific features (Guardrails, Knowledge Bases, prompt caching, Bedrock Agents integration) or your target region doesn't have Mantle. Mantle is the fastest path; Converse API is the most feature-complete path.

GPT-5.4 → Claude Sonnet 4.6

Near price parity (~5% difference). Migration case is driven by AWS consolidation, agentic reliability, or prompt caching — not cost. Both have ~200K+ context. Low risk.

GPT-5.4 Mini/Nano → Nova Lite/Micro

87-94% savings. Strong cost case at any volume. Nova Lite (300K context) covers most GPT-5.4 Mini use cases.

GPT-4/4 Turbo → Claude Sonnet 4.6

70-90% savings, similar or better quality, longer context (200K vs 128K). Low risk.

GPT-3.5 Turbo → Llama 4 Maverick

Similar cost, dramatically better quality, 1M context (vs 16K).

GPT-4 → Multi-Model (high spend)

Tier by complexity: simple → Nova Micro/Llama 4 Scout (60%), moderate → Llama 4 Maverick/Nova Pro (30%), complex → Claude Sonnet (10%). 85-95% savings.

Pro models → Nova 2 Pro

83-98% savings. Strong migration case at any volume. (Nova Premier v1 is Legacy — use Nova 2 Pro instead.)

---

Volume-Based Recommendations

Low (<1M tokens/day): Use best model for quality. Cost difference minimal.

Medium (1-10M tokens/day): Present cost comparison at volume. At 5M input + 2.5M output/day, evaluate per-model economics carefully.

High (10-100M tokens/day): Multi-model tiered approach recommended. Route by task complexity.

Very high (>100M tokens/day): Mandatory tiering:

• Simple tasks (60%) → Nova Micro or Llama 4 Scout
• Moderate tasks (30%) → Llama 4 Maverick or Nova Pro
• Complex tasks (10%) → Claude Sonnet 4.6

---

OpenAI Pricing Tiers

OpenAI offers 4 tiers: Batch (50% off, 24hr), Flex (30-50% off, higher latency), Standard (baseline), Priority (2x, lowest latency). This guide uses Standard tier for comparison.

AI/ML Services Design Rubric

Applies to: Vertex AI (traditional ML), Cloud Vision API, Cloud ML Engine (deprecated — now part of Vertex AI)

LLM Routing

If the detected AI workload is LLM-based (generative models), load the source-specific design reference instead of this file:

• If ai-workload-profile.json → summary.ai_source = "gemini": load ai-gemini-to-bedrock.md
• If ai-workload-profile.json → summary.ai_source = "openai": load ai-openai-to-bedrock.md
• If ai-workload-profile.json → summary.ai_source = "both": load both files
• If ai-workload-profile.json → summary.ai_source = "other" or absent, OR if the workload is traditional ML (custom models, Vision API, Speech API): use the SageMaker/Rekognition/Textract rubric below.

---

Signals (Decision Criteria)

Vertex AI (Endpoints / Models)

• Custom model inference → SageMaker Endpoints
• Pre-built model APIs → AWS APIs (Rekognition, Textract, Translate, etc.)
• Batch prediction → SageMaker Batch Transform

Cloud Vision API

• Image classification, OCR → AWS Rekognition (images) or Textract (OCR)
• Document understanding → AWS Textract (more powerful for docs)

Cloud ML Engine (deprecated — legacy Terraform configs only)

• Model training → SageMaker (managed training jobs)
• AutoML → SageMaker Autopilot / Canvas

6-Criteria Rubric

Apply in order:

1. Eliminators: Does GCP config require AWS-unsupported features? If yes: use alternative 2. Operational Model: Managed (SageMaker) vs Custom (EC2 + training)?

• Prefer managed

3. User Preference: From preferences.json: design_constraints.cost_sensitivity + ai_constraints (if present)

• If cost-sensitive → check SageMaker Spot + Autopilot

4. Feature Parity: Does GCP config need model type unavailable in AWS?

• Example: TensorFlow 2.x → SageMaker (supported)

5. Cluster Context: Are other compute resources running ML? Prefer SageMaker affinity 6. Simplicity: SageMaker endpoints (managed) > custom EC2 instances

Examples

Example 1: Vertex AI Endpoint (PyTorch model)

• GCP: google_ai_platform_model (model_name="image-classifier", framework=PYTORCH)
• Signals: Custom model inference, PyTorch
• Criterion 1 (Eliminators): PASS (PyTorch supported)
• Criterion 2 (Operational Model): SageMaker Endpoint (managed)
• → AWS: SageMaker Endpoint (PyTorch container)
• Confidence: inferred

Example 2: Cloud Vision API

• GCP: google_vision_api_call (feature=TEXT_DETECTION, image_source=GCS)
• Signals: Pre-built API
• → AWS: Textract (if document OCR) or Rekognition (if image classification)
• Confidence: inferred

Example 3: AutoML (image classification)

• GCP: google_automl_image_classification_dataset
• Signals: Training pipeline, classification
• Criterion 1 (Eliminators): PASS
• Criterion 2 (Operational Model): SageMaker Autopilot (managed)
• → AWS: SageMaker Autopilot + Canvas (for low-code)
• Confidence: inferred

Output Schema

{
  "gcp_type": "google_ai_platform_model",
  "gcp_address": "image-classifier-v2",
  "gcp_config": {
    "framework": "PYTORCH",
    "version": "1.9"
  },
  "aws_service": "SageMaker",
  "aws_config": {
    "endpoint_name": "image-classifier-v2",
    "instance_type": "ml.m5.large",
    "container_image": "pytorch:1.9"
  },
  "confidence": "inferred",
  "rationale": "Vertex AI custom model → SageMaker Endpoint (PyTorch supported)"
}

Compute Services Design Rubric

Applies to: Cloud Run (v1/v2), Cloud Functions (Gen 1/Gen 2), Compute Engine, GKE, App Engine

Table lookup first: Check fast-path.md Direct Mappings for this Terraform type.

• google_cloud_run_service, google_cloud_run_v2_service, google_cloudfunctions_function, and google_cloudfunctions2_function are currently in Direct Mappings and usually resolve with confidence: "deterministic" when row conditions are met.
• google_compute_instance, google_container_cluster, and google_app_engine_application are not direct-mapped in fast-path.md; use the rubric below (typically confidence: "inferred").
• If a resource is not eligible for Direct Mappings (or row conditions are not met), use the rubric below.

Eliminators (Hard Blockers)

Signals (Decision Criteria)

Cloud Run / App Engine

• Always-on or cold-start sensitive → Fargate (not Lambda)
• Stateless microservice + <15 min execution → Lambda
• HTTP-only + container-native → Fargate preferred (better dev/prod parity)

Cloud Functions

• Event-driven + <15 min + Python/Node/Go → Lambda
• Always-on or long → run as Container on Fargate or ECS

Compute Engine (VMs)

• Always-on workload → EC2 (reserved or on-demand based on cost sensitivity)
• Batch/periodic jobs → EC2 with Auto Scaling (scale to 0 in dev)
• Windows-only workload → EC2 (Lambda/Fargate support limited)

GKE

• Kubernetes orchestration explicitly required (kubernetes = "eks-managed" or "eks-or-ecs" in preferences.json) → EKS
• Default / no explicit K8s preference (kubernetes = "ecs-fargate" or absent):
• If gcp-resource-inventory.json contains google_container_cluster → EKS (IaC signal shows K8s workload)
• Otherwise → Fargate (no K8s signal; lower-ops default)

6-Criteria Rubric

Apply in order; first match wins:

1. Eliminators: Does GCP config violate AWS constraints? If yes: switch to alternative 2. Operational Model: Managed (Lambda, Fargate) vs Self-Hosted (EC2, EKS)?

• Prefer managed unless: Always-on + high baseline cost → EC2

3. User Preference: From preferences.json: design_constraints.kubernetes, design_constraints.cost_sensitivity?

• If kubernetes = "eks-managed" → EKS (preserves K8s investment)
• If kubernetes = "eks-or-ecs" → EKS with managed node groups (user is competent with K8s)
• If kubernetes = "ecs-fargate" → Fargate (simpler managed containers)
• If kubernetes is absent → Fargate (treat same as "ecs-fargate" — do not default to EKS)
• If cost_sensitivity present and high → prefer Fargate (lower operational cost)

4. Feature Parity: Does GCP config require AWS-unsupported features?

• Example: GCP auto-scaling to zero + cold-start-sensitive → Fargate (not Lambda)

5. Cluster Context: Are other resources in this cluster using EKS/EC2/Fargate?

• Prefer same platform (affinity)

6. Simplicity: Fewer resources = higher score

• Fargate (1 service) > EC2 (N services for ASG + monitoring)

Examples

Example 1: Cloud Run (stateless API)

• GCP: google_cloud_run_service (memory=512MB, timeout=60s, min_instances=1)
• Signals: HTTP, stateless, always-on
• Criterion 1 (Eliminators): PASS (60s < 15min doesn't apply; stateless OK)
• Criterion 2 (Operational Model): FARGATE preferred
• → AWS: Fargate (0.5 CPU, 1 GB memory)
• Confidence: inferred (rubric-based — Cloud Run is not in fast-path)

Example 2a: Cloud Functions (event processor, short-running)

• GCP: google_cloudfunctions_function (runtime=python39, timeout=540s)
• Signals: Event-driven, 540s = 9 minutes (< 15min limit)
• Criterion 1 (Eliminators): PASS on timeout (540s < 900s)
• Criterion 2 (Operational Model): Lambda preferred for event-driven + short-running
• → AWS: Lambda with EventBridge trigger
• Confidence: inferred

Example 2b: Cloud Functions (long-running batch processor)

• GCP: google_cloudfunctions_function (runtime=python39, timeout=1200s)
• Signals: Event-driven but 1200s = 20 minutes (> 15min limit)
• Criterion 1 (Eliminators): FAIL on timeout (1200s > 900s) → cannot use Lambda
• Criterion 2 (Operational Model): Fargate (managed + can handle longer execution)
• → AWS: Fargate (0.5 CPU, 1 GB memory) with EventBridge trigger
• Confidence: inferred

Example 3: Compute Engine (background job)

• GCP: google_compute_instance (machine_type=e2-medium, region=us-central1, startup_script=...)
• Signals: Periodic batch job (inferred from startup script), always-on
• Criterion 1 (Eliminators): PASS
• Criterion 2 (Operational Model): EC2 (explicit compute control)
• Criterion 3 (User Preference): If design_constraints.gcp_monthly_spend indicates cost sensitivity, prefer auto-scaling → EC2 + ASG (scale to 0)
• → AWS: EC2 t3.medium + Auto Scaling Group (min=0 in dev)
• Confidence: inferred

Output Schema

{
  "gcp_type": "google_cloud_run_service",
  "gcp_address": "example-service",
  "gcp_config": {
    "memory_mb": 512,
    "timeout_seconds": 60
  },
  "aws_service": "Fargate",
  "aws_config": {
    "cpu": "0.5",
    "memory_mb": 1024,
    "region": "us-east-1"
  },
  "confidence": "inferred",
  "rationale": "Rubric: Cloud Run (stateless, <15min) → Fargate (always-on, managed)",
  "rubric_applied": [
    "Eliminators: PASS",
    "Operational Model: Managed preferred",
    "User Preference: N/A",
    "Feature Parity: Full",
    "Cluster Context: Fargate affinity",
    "Simplicity: Fargate (1 service)"
  ]
}

Database Services Design Rubric

Applies to: Cloud SQL, Firestore, BigQuery, Memorystore (Redis), Cloud Spanner

Quick lookup (no rubric): Check fast-path.md first (Cloud SQL PostgreSQL → RDS Aurora, Cloud SQL MySQL → RDS Aurora, etc.)

Eliminators (Hard Blockers)

Signals (Decision Criteria)

Cloud SQL

• PostgreSQL, MySQL, SQL Server → Direct RDS mapping (fast-path)
• High availability required → RDS Multi-AZ or Aurora (preferred)
• Dev/test sizing → RDS Aurora Serverless v2 (min 0.5 ACU, ~$43–58/mo depending on I/O mode)
• Production, always-on → RDS Aurora Provisioned (or Serverless v2 if fluctuating)

Firestore

• Flexible schema + NoSQL → DynamoDB
• Strong consistency required → DynamoDB supports strongly consistent reads via ConsistentRead parameter
• Real-time sync + offline support → DynamoDB Streams + Amplify (app-level)

BigQuery

Do not use this rubric to pick an AWS product. For any google_bigquery_* resource, follow `design-infra.md` → BigQuery specialist gate only: set aws_service to `Deferred — specialist engagement`, human_expertise_required: true, and direct the customer to their AWS account team and/or a data analytics migration partner. Do not output Athena, Redshift, Glue, EMR, or similar as the automated mapping in aws-design.json.

The sections below are background for humans after engagement — not for the agent to select automatically:

• Warehousing, SQL analytics, BI, and ML-on-data choices require assessment (e.g. query patterns, data volume, SLAs, cost model).
• BigQuery ML (google_bigquery_ml_*) uses the same specialist gate — no automated SageMaker/Redshift ML target from this plugin.

Memorystore (Redis)

• In-memory cache → ElastiCache Redis (fast-path, 1:1 mapping)
• Cluster mode enabled → ElastiCache Redis with cluster mode
• High availability required → ElastiCache Redis Multi-AZ with auto-failover

Cloud Spanner

• Global strong consistency → Aurora DSQL (distributed SQL with strong consistency across regions)
• Single-region relational → Aurora PostgreSQL (simpler, lower cost if global distribution not needed)
• Key-value access patterns dominant → DynamoDB Global Tables (if workload is mostly key-value lookups)

6-Criteria Rubric

Apply in order:

1. Eliminators: Does GCP config require AWS-unsupported features? If yes: switch 2. Operational Model: Managed (Aurora, DynamoDB) vs Provisioned (EC2-based RDS)?

• Prefer managed unless: Production + cost-optimized + predictable load → Provisioned RDS

3. User Preference: From preferences.json: design_constraints.database_tier, design_constraints.db_io_workload?

• If database_tier = "standard" → Standard Aurora Multi-AZ
• If database_tier = "aurora-scale" → Aurora DSQL considered for global active-active
• If db_io_workload = "high" → Aurora I/O-Optimized recommended

4. Feature Parity: Does GCP config need features unavailable in AWS?

• Example: Cloud SQL with binary log replication → Aurora (full support)
• Example: Firestore with offline-first SDK → DynamoDB (plus app-level sync)

5. Cluster Context: Are other resources in cluster using RDS? Prefer same family 6. Simplicity: Fewer moving parts = higher score

• Serverless > Provisioned > Self-Managed

Examples

Example 1: Cloud SQL PostgreSQL (dev environment)

• GCP: google_sql_database_instance (database_version=POSTGRES_13, region=us-central1)
• Signals: PostgreSQL, dev tier (implied from sizing)
• Criterion 1 (Eliminators): PASS
• Criterion 2 (Operational Model): Aurora Serverless v2 (dev best practice)
• → AWS: RDS Aurora PostgreSQL Serverless v2 (0.5-1 ACU, dev tier)
• Confidence: deterministic

Example 2: Firestore (mobile app)

• GCP: google_firestore_document (root_path=users, auto_id=true)
• Signals: NoSQL, real-time, offline-first (inferred from Firestore choice)
• Criterion 1 (Eliminators): PASS (DynamoDB supports eventual consistency)
• Criterion 2 (Operational Model): DynamoDB (managed NoSQL)
• Criterion 3 (User Preference): NoSQL type detected from GCP resource → DynamoDB confirmed
• → AWS: DynamoDB (on-demand billing for dev)
• Confidence: inferred

Example 3: BigQuery (analytics)

• GCP: google_bigquery_dataset (location=us, schema=[large table])
• Agent output: aws_service: `Deferred — specialist engagement`, human_expertise_required: `true`, confidence: `inferred`, rubric_applied: ["BigQuery specialist gate — no automated AWS service target"]
• User-facing: Engage AWS account team and/or data analytics migration partner before choosing AWS analytics architecture. Do not state Athena vs Redshift vs Glue as the plugin’s recommendation.

Output Schema

{
  "gcp_type": "google_sql_database_instance",
  "gcp_address": "prod-postgres-db",
  "gcp_config": {
    "database_version": "POSTGRES_13",
    "region": "us-central1",
    "tier": "db-custom-2-7680"
  },
  "aws_service": "RDS Aurora PostgreSQL",
  "aws_config": {
    "engine_version": "13.12",
    "instance_class": "db.r6g.xlarge",
    "multi_az": true,
    "region": "us-east-1"
  },
  "confidence": "deterministic",
  "human_expertise_required": false,
  "rationale": "1:1 mapping; Cloud SQL PostgreSQL → RDS Aurora PostgreSQL",
  "rubric_applied": [
    "Eliminators: PASS",
    "Operational Model: Managed RDS Aurora",
    "User Preference: database_tier=standard, db_io_workload=medium",
    "Feature Parity: Full (binary logs, replication)",
    "Cluster Context: Consistent with app tier",
    "Simplicity: RDS Aurora (managed, multi-AZ)"
  ]
}

Strands Agents + AgentCore Runtime Design Reference

Loaded by design-ai.md Step 0.6 when agentic_profile.is_agentic == true AND ai_constraints.agentic.migration_approach == "strands".

Prerequisites: references/shared/ai-migration-guardrails.md must already be loaded (Step 0.6 loads it before this file). Do NOT duplicate regional caveats, pricing rules, or effort estimation rules here.

---

What is Strands Agents

Strands Agents is an open-source SDK from AWS (open-sourced May 2025, 1.0 released July 2025) that takes a model-driven approach to building AI agents. It powers production features inside AWS services (Amazon Q Developer, AWS Glue, VPC Reachability Analyzer) and is the framework underlying the AgentCore Harness.

Key differentiators vs other frameworks:

• Model-driven: The LLM drives tool selection and planning autonomously — no hardcoded task flows
• Multi-agent primitives: Agents-as-Tools (hierarchical), Swarms (collaborative), Graphs (deterministic), A2A protocol (cross-organization)
• AWS-native deployment: First-class deployment on AgentCore Runtime with microVM isolation, 8-hour sessions, auto-scaling
• Multi-model: Supports Bedrock, OpenAI, Anthropic, and any OpenAI-compatible endpoint. Different models per agent in the same system.
• Session management: Built-in durable session persistence (S3, file-based, or custom DAO)
• Async-native: Full async support with streaming, concurrent agent evaluation, cancellation

When to recommend Strands (this path):

• Startup is on OpenAI Agents SDK or custom agent loops where retarget doesn't work well (tightly coupled to OpenAI API)
• Multi-agent system that would benefit from structured primitives (Graphs, Swarms, Agents-as-Tools)
• Team wants AWS-native agent infrastructure (AgentCore Runtime, Memory, Gateway, Identity, Observability)
• Team is willing to refactor orchestration code (accepts 2-6 week effort)
• Startup doesn't know Strands exists — this is the plugin surfacing an option they wouldn't discover from a base LLM

When NOT to recommend Strands:

• Working LangGraph/CrewAI/AutoGen system where retarget (model swap) is sufficient
• Team needs to ship in < 2 weeks (retarget or Harness is faster)
• Simple single-agent pattern (Harness is simpler — config vs code)
• Team has no Python/TypeScript expertise (Strands SDK is Python and TypeScript)

---

Framework-to-Strands Mapping

Map the detected agentic_profile.framework and orchestration_pattern to Strands primitives:

OpenAI Agents SDK → Strands Agent

Bridge option (Phase 0): Before full Strands rewrite, startups on OpenAI Agents SDK can do a partial retarget — route model calls through Bedrock using OpenAI-compatible endpoint format while keeping the Agents SDK orchestration intact. This buys time on AWS infrastructure without rewriting. Then migrate to Strands when ready.

LangGraph → Strands Graphs

Key difference: LangGraph nodes are arbitrary functions; Strands graph nodes are Agents. For non-agent nodes (pure data transformation), wrap in a minimal Agent with a focused system prompt and no tools.

CrewAI → Strands Swarms or Agents-as-Tools

Key difference: CrewAI pre-defines tasks and assigns them to agents. Strands is model-driven — the orchestrator agent (or swarm) decides dynamically which specialist to consult. This is more flexible but requires good system prompts.

AutoGen → Strands Agents-as-Tools or Swarms

Custom Agent Loops → Strands Agent

Custom while loops with LLM call + tool dispatch map most directly to a single Strands Agent:

# Before (custom loop):
while not done:
    response = openai.chat.completions.create(model="gpt-4o", messages=messages, tools=tool_schemas)
    if response.tool_calls:
        result = execute_tool(response.tool_calls[0])
        messages.append(tool_result)
    else:
        done = True

# After (Strands):
from strands import Agent
from strands.models import BedrockModel

agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-6-20250514-v1:0"),
    tools=[web_search, calculator, file_read],  # your existing tool functions with @tool decorator
    system_prompt="Your existing system prompt here"
)
result = agent("Your task here")

The Strands Agent handles the loop internally — model calls, tool dispatch, result parsing, context management. Your tool functions stay the same; just add the @tool decorator.

---

AgentCore Runtime Deployment

Strands agents deploy on AgentCore Runtime for production:

What AgentCore Runtime provides:

• Serverless microVM isolation per session (no shared state between users)
• Auto-scaling from zero to thousands of sessions
• Up to 8-hour session duration for long-running agent tasks
• Built-in observability via OpenTelemetry (traces to CloudWatch, Datadog, etc.)
• VPC support and PrivateLink for network isolation

Deployment model:

Memory integration:

---

Output: agentic_design in aws-design-ai.json

When Strands path is selected, write this to aws-design-ai.json:

{
  "agentic_design": {
    "migration_approach": "strands",
    "strands_config": {
      "agents": [
        {
          "agent_id": "from agentic_profile.agents[].agent_id",
          "strands_primitive": "Agent|Graph|Swarm",
          "model_id": "from bedrock_models[].aws_model_id",
          "system_prompt": "extracted or placeholder",
          "tools": ["from tool_manifest, mapped to @tool functions"],
          "role_in_system": "orchestrator|specialist|worker"
        }
      ],
      "orchestration_primitive": "single_agent|agents_as_tools|swarm|graph",
      "session_manager": "none|file|s3",
      "memory_service": false,
      "deployment_target": "agentcore_runtime",
      "bridge_phase": true,
      "source_framework": "from agentic_profile.framework"
    },
    "regional_fit": "available|preview|unavailable",
    "warnings": []
  }
}

Mapping `orchestration_pattern` → `orchestration_primitive`:

`bridge_phase`: Set to true if source_framework == "openai_agents" — indicates the partial retarget bridge (Phase 0) should be included in generated artifacts.

---

AgentCore Agent Performance Loop (Public Preview, May 2026)

AgentCore launched an observe-evaluate-optimize-deploy loop in public preview (May 2026). APIs may change before GA; CloudTrail audit logging is not yet supported for these features. Surface this as an optional post-migration capability for teams that care about production evals, regression testing, prompt/tool optimization, and A/B rollout — not as an unconditional migration advantage.

When to surface: agentic_profile.is_agentic == true AND the design targets AgentCore Runtime, Evaluations, or Gateway. Not gated on migration_approach == "strands" alone — the capability is tied to AgentCore, not the Strands SDK specifically.

Capabilities (all preview):

Caveats to surface explicitly:

• All capabilities are public preview — APIs may change before GA
• CloudTrail not yet supported — do not recommend for workloads requiring complete audit coverage
• User simulation incurs model invocation costs; estimate before enabling at scale
• Requires AgentCore traces/evaluations to be active before recommendations are useful

Output addition to `aws-design-ai.json`:

Add to agentic_design (optional — only when AgentCore Runtime/Evaluations/Gateway is in the design):

"performance_loop": {
  "status": "preview",
  "capabilities": ["recommendations", "batch_evaluations", "user_simulation", "ab_testing"],
  "recommended_when": ["production eval requirements", "regression testing needed", "prompt/tool optimization desired", "A/B rollout required"],
  "prerequisites": ["AgentCore traces and evaluations active", "AgentCore Gateway for A/B testing"],
  "caveats": ["preview APIs — may change before GA", "CloudTrail not supported yet", "user simulation incurs model invocation costs"]
}

---

Present Summary (Strands-specific additions)

After the standard model comparison summary from design-ai.md, add:

Agentic Migration: Strands Agents + AgentCore Runtime

- Source framework: [detected framework]

- Strands primitive: [orchestration_primitive] (mapped from [detected orchestration_pattern])

- Agents to convert: [count] ([list agent_ids])

- Tools to migrate: [count] (existing functions get @tool decorator)

- Deployment: AgentCore Runtime ([task_duration] sessions)

- Memory: [session_manager] + [AgentCore Memory if cross_session]

- Bridge phase: [yes/no — for OpenAI Agents SDK users]

- Estimated effort: [range] depending on [drivers from guardrails]

- Performance loop (preview): Because this design targets AgentCore Runtime, you can optionally add AgentCore's preview performance loop for evaluation, simulation, prompt/tool recommendations, and A/B validation. Note: CloudTrail not yet supported; user simulation incurs model costs.

- Note: Strands Agents is an open-source AWS framework (strandsagents.com) that powers AgentCore internally. It provides multi-agent primitives (Graphs, Swarms, Agents-as-Tools, A2A) with native AgentCore deployment.

AgentCore Harness Design Reference

Loaded by design-ai.md Step 0.6 when agentic_profile.is_agentic == true AND ai_constraints.agentic.migration_approach == "harness".

Prerequisites: references/shared/ai-migration-guardrails.md must already be loaded (Step 0.6 loads it before this file). Do NOT duplicate regional caveats, pricing rules, or effort estimation rules here.

---

When Harness Fits

Recommend Harness when:

• Single agent with tools (not complex multi-agent orchestration)
• OpenAI Assistants API migration (closest 1:1 mapping — Assistants → Harness declarations)
• Team wants managed runtime, memory, identity, and observability without building it
• Incremental migration: run existing OpenAI/Gemini models on AgentCore infrastructure, swap to Bedrock per-invocation
• Agent tasks run < 8 hours (Harness session limit)
• Team prefers config-first iteration over code-first

When Harness Does NOT Fit

Do NOT recommend Harness as primary path when:

• Complex multi-agent graphs with custom state management (recommend retarget or Strands)
• Team needs to stay in their current framework for velocity (recommend retarget)
• Agent count > 3 with inter-agent coordination (recommend retarget with AgentCore Runtime, or Strands)
• Custom runtime dependencies that can't be containerized (evaluate custom container image on Harness, or use AgentCore Runtime directly)

For these cases: fall back to retarget path (standard model-swap design in Parts 1–6 of design-ai.md).

---

Harness Configuration Mapping

Map discovered elements to Harness configuration:

Tool mapping decision:

For each tool in tool_manifest[]:
├── transport == "mcp" → remote_mcp (direct connection)
├── transport == "api"
│   ├── auth_hint == "oauth" or multiple tools share auth → agentcore_gateway (centralized auth)
│   └── auth_hint == "api_key" or "none" → remote_mcp (simpler, wrap as MCP)
├── transport == "function"
│   ├── tool does web browsing/scraping → agentcore_browser
│   ├── tool executes code/scripts → agentcore_code_interpreter
│   └── other local function → inline_function (client-side)
└── transport == "unknown" → inline_function (safest default; client controls execution)

---

Incremental Migration via Multi-Model Switching

If ai_constraints.agentic.incremental_migration == true:

Phase 0: Deploy on Harness with existing source provider model

1. Store source provider API key in AgentCore Identity token vault 2. Create Harness with source model as default (e.g., --model-provider open_ai --model-id gpt-4o) 3. Deploy and validate: existing behavior preserved on AWS infrastructure 4. Benefit: AWS observability, security, and scaling — without changing the model yet

Phase 1: A/B test with Bedrock model

1. Override --model-id per invocation with Bedrock model from design 2. Compare responses: quality, latency, tool-calling behavior 3. Run evaluation prompts from test_comparison.py against both models on same session

Phase 2: Switch default to Bedrock

1. Update Harness default model to Bedrock model ID 2. Keep source provider credentials as fallback 3. Monitor for 48 hours

Phase 3: Remove source provider

1. Delete API key from AgentCore Identity token vault 2. Remove source provider from Harness config 3. Migration complete

---

Output: agentic_design in aws-design-ai.json

When Harness path is selected, write this to aws-design-ai.json:

{
  "agentic_design": {
    "migration_approach": "harness",
    "harness_config": {
      "name": "from agentic_profile.agents[0].agent_id",
      "model_id": "from bedrock_models[0].aws_model_id",
      "system_prompt": "extracted from code or placeholder",
      "tools": [
        {
          "type": "remote_mcp|agentcore_browser|agentcore_code_interpreter|agentcore_gateway|inline_function",
          "name": "tool name from tool_manifest",
          "config": {}
        }
      ],
      "memory_enabled": true,
      "memory_type": "session|cross_session",
      "incremental_migration": true,
      "source_model_provider": "open_ai|google",
      "source_model_id": "from models[0].model_id"
    },
    "regional_fit": "available|preview|unavailable",
    "deployment_regions": ["us-west-2", "us-east-1"],
    "warnings": []
  }
}

Field rules:

• harness_config.name — Derived from first agent's agent_id. Use kebab-case.
• harness_config.model_id — The Bedrock model ID selected in Part 1 (e.g., us.anthropic.claude-sonnet-4-6-20250514-v1:0)
• harness_config.system_prompt — Extracted from agent code if available; otherwise "[TODO: Add system prompt from your agent definition]"
• harness_config.tools — Mapped from tool_manifest[] using the tool mapping decision tree above
• harness_config.source_model_provider — "open_ai" or "google" based on summary.ai_source
• harness_config.source_model_id — Original model ID from models[0].model_id
• regional_fit — Result of Step 0.5 regional check for AgentCore Harness in target region

---

Present Summary (Harness-specific additions)

After the standard model comparison summary from design-ai.md, add:

Agentic Migration: AgentCore Harness

- Approach: Config-based agent deployment on AgentCore

- Tools mapped: [count] tools → [types breakdown]

- Memory: [session/cross-session/none]

- Incremental migration: [yes/no]

- Regional availability: [available/preview in target region]

- Estimated effort: [range] depending on [drivers from guardrails]

Fast-Path: Direct GCP→AWS Mappings

Confidence: `deterministic` (1:1 mapping, no rubric evaluation needed)

What deterministic vs inferred means

Use these labels only as defined here — they describe _how the mapping was chosen_, not whether the AWS architecture is "obvious."

User-facing vocabulary (chat, MIGRATION_GUIDE, migration-report)

JSON artifacts must keep the confidence string values above. When speaking or writing for end users, lead with plain English — do not use "deterministic," "inferred," or "rubric" as the primary label unless the user asks for technical detail.

BigQuery / specialist gate rows still store confidence: "inferred" in JSON; in user-facing text you may say Tailored to your setup and emphasize specialist engagement (no automated AWS analytics target).

Canonical reference: This subsection — other phase files should point here instead of redefining wording.

Common confusion: references/design-refs/index.md lists a typical AWS target per GCP service. That is not automatically the same as `deterministic`. Confidence is deterministic only when the exact Terraform resource type appears in the Direct Mappings table above and its conditions are met; otherwise confidence is inferred via rubric evaluation.

Add-ons (ALB, NAT, etc.): A row may say "Fargate" while the architecture diagram also includes an ALB or NAT Gateway from other Terraform resources. Confidence is still per resource row — e.g. google_cloud_run_service = inferred; google_compute_forwarding_rule + backend = often inferred (see networking.md).

---

Direct Mappings use confidence: `deterministic` (fixed table lookup — no rubric for that resource)

Direct Mappings Table

Skip Mappings Table

These GCP resources do not require AWS equivalents in v1.0:

Preferred AWS Target Services

For the workload categories below, always steer toward the preferred AWS service. If rubric evaluation or LLM reasoning would select a non-preferred service, substitute the preferred alternative instead.

Enforcement: Check every resource mapping against this table before writing to aws-design.json or aws-design-billing.json. If a mapping would select a non-preferred service, substitute the preferred alternative.

Secondary Behavior Lookups

For resources in the Skip Mappings table but present in inventory:

1. Log as "secondary resource, no AWS equivalent needed" 2. Do not include in aws-design.json 3. Note in aws-design.json warnings array

---

Workflow:

1. Extract GCP resource type 2. Look up in Direct Mappings table 3. If found and condition met: assign AWS service (confidence = deterministic) 4. If found in Skip Mappings: skip it (confidence = n/a) 5. If not found: use design-refs/index.md to determine category → apply rubric in that category's file

.phase-status.json

Lightweight phase tracking. This is the SINGLE source of truth for the .phase-status.json schema. All steering files reference this definition.

{
  "migration_id": "0226-1430",
  "last_updated": "2026-02-26T15:35:22Z",
  "phases": {
    "discover": "completed",
    "clarify": "completed",
    "design": "in_progress",
    "estimate": "pending",
    "generate": "pending",
    "feedback": "pending"
  }
}

Field Definitions:

Rules:

• Phase status progresses: "pending" → "in_progress" → "completed". Never goes backward.
• Valid phase names: discover, clarify, design, estimate, generate, feedback.
• migration_id matches the $MIGRATION_DIR folder name (e.g., 0226-1430).