migration-to-aws — плагин для Claude Code: миграция в AWS

# Agent Skills for AWS Migration

> [!IMPORTANT]
> **This plugin has moved and was folded into another plugin.** Its skills now ship inside
> [**`aws-startup-advisor`**](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-startup-advisor)
> in [aws/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws). There is no
> `migration-to-aws` plugin in the Agent Toolkit — install `aws-startup-advisor` and you get all of
> these skills. `migration-to-aws` is no longer maintained here and receives no further updates of any
> kind — no new features, no fixes.
>
> ```bash
> /plugin marketplace add aws/agent-toolkit-for-aws
> /plugin install aws-startup-advisor@agent-toolkit-for-aws
> ```
>
> Every install command in the Installation section below points at this unmaintained copy. See the
> [repository README](../../../README.md#where-things-moved) for the full mapping.

AI agent skills for migrating workloads to AWS, built for [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Codex](https://openai.com/codex), and [Cursor](https://www.cursor.com/).

## What This Does

Point this plugin at your Heroku account (via your authenticated Heroku CLI, read-only and consent-gated), your Terraform files, application code, or billing data. It runs a structured 6-phase assessment — discovering what you have, asking the right questions, designing the AWS architecture, estimating costs with real pricing data, and generating runnable migration artifacts.

**Supported migration sources:**

- **GCP → AWS** — Cloud Run, Cloud SQL, GKE, Cloud Functions, Pub/Sub, Cloud Storage, VPC, and AI/agentic workloads
- **Heroku → AWS** — Dynos, Postgres, Redis, Kafka, Private Spaces, Pipelines, and 13+ common add-ons

**For infrastructure migrations:**

- **Maps your resources to AWS equivalents** — Cloud Run → Fargate, Cloud SQL → RDS or Aurora, Dynos → Elastic Beanstalk, Heroku Postgres → RDS/Aurora, and more
- **Generates production-ready Terraform** — `vpc.tf`, `compute.tf`, `database.tf`, `security.tf`, `baseline.tf` with account-wide security controls (GuardDuty, CloudTrail, IMDSv2, ECR scanning), and a full `terraform/README.md`
- **Selects the right database migration tool** — pg_dump for small databases, pgcopydb for parallel copy at scale, AWS DMS for zero-downtime migrations — based on your actual database size
- **Produces numbered migration scripts** — prerequisites validation, data migration, container image migration, secrets migration, and post-migration validation
- **Estimates costs across three tiers** — Premium, Balanced, and Optimized — using real-time AWS pricing, compared against your current spend

**For AI and agentic migrations:**

- **Detects your entire AI stack** — not just "you use GPT-4o" but your agents, tools, orchestration patterns, memory layers, and multi-model pipelines
- **Recommends three migration paths** for agentic workloads: retarget (keep your framework, swap models), AgentCore Harness (config-based managed agents), or Strands Agents (AWS-native multi-agent SDK)
- **Gives honest pricing comparisons** — finds the best Bedrock option for your workload with current pricing data, including side-by-side cost comparisons against your existing OpenAI/Gemini spend
- **Generates runnable AI artifacts** — `harness.json`, provider adapters, deployment scripts, incremental migration scripts — tailored to your specific models, tools, and architecture

## What You Get That a Base LLM Can't Give You

**Infrastructure:**

| Capability                 | Base LLM                          | This Plugin                                                                                                                                                                                         |
| -------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Terraform generation       | Generic templates                 | Your actual config translated — instance classes, storage sizes, region, VPC CIDRs, security groups                                                                                                 |
| Security baseline          | Not included                      | `baseline.tf` always emitted by both `gcp-to-aws` and `heroku-to-aws` Generate: GuardDuty, CloudTrail, IMDSv2, EBS encryption, budget alerts; ECR scan-on-push where ECR repositories are generated |
| Database migration tooling | "Use DMS"                         | Selects pg_dump / pgcopydb / DMS based on your actual database size; generates the right script                                                                                                     |
| Cost estimation            | Stale guesses                     | Three-tier pricing (Premium/Balanced/Optimized) using live AWS Pricing API, compared to your current bill                                                                                           |
| Migration plan             | Generic checklist                 | Phased timeline with Go/No-Go gates, rollback procedures, and data integrity checks                                                                                                                 |
| Migration report           | Generic summary or missing detail | `migration-report.html` with cost tiers, security baseline (GuardDuty, etc.), combined TCO, and appendices — validated for structural completeness                                                  |

**AI/Agentic:**

| Capability               | Base LLM                          | This Plugin                                                                                                                              |
| ------------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Model recommendation     | Generic "use Bedrock"             | Your specific models mapped with pricing, honest stay-or-migrate recommendation per model                                                |
| Agentic migration        | "Swap ChatOpenAI for ChatBedrock" | Detects your framework, agents, tools, orchestration pattern; recommends retarget vs Harness vs Strands with effort ranges               |
| Multi-model coordination | Generic advice                    | Warns about re-embedding requirements, cascade pair testing, tiered strategies — based on your actual model usage                        |
| Framework gotchas        | Not covered                       | LangGraph checkpointer incompatibility, CrewAI hierarchical failures with smaller models, async thread pool exhaustion                   |
| Regional validation      | Outdated region lists             | Live `aws___get_regional_availability` (AWS MCP Server) call — catches "AgentCore Harness isn't in your target region" before you commit |
| Generated code           | Generic templates                 | Your model IDs, your tool names, your system prompts, your region — in runnable scripts                                                  |
| Incremental migration    | Not suggested                     | Run existing OpenAI models on AgentCore infrastructure today, A/B test with Bedrock per-invocation, swap when confident                  |

## Plugins

| Plugin               | Description                                                                                                                                                                                                                                                                                                       | Status                                                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **migration-to-aws** | Assess, plan & execute: resource discovery, architecture mapping, cost analysis, execution planning (GCP and Heroku), LLM code rewrite to Bedrock (llm-to-bedrock skill), AI-agent runtime selection + POC on AWS (agent-advisor skill), and a read-only Terraform security policy gate (tf-best-practices skill) | Deprecated — moved into `aws-startup-advisor` in [aws/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws) |

## Installation

> [!IMPORTANT]
> **Every command in this section installs the deprecated copy from this repository**, which receives
> no further updates of any kind. These skills now ship inside `aws-startup-advisor` in
> [aws/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws) — install that instead:
>
> ```bash
> /plugin marketplace add aws/agent-toolkit-for-aws
> /plugin install aws-startup-advisor@agent-toolkit-for-aws
> ```

### Claude Code

```bash
# Add the marketplace
/plugin marketplace add awslabs/startups --sparse migrate/plugins

# Install the plugin
/plugin install migration-to-aws@startups
```

### Codex

```bash
# Add the marketplace
codex plugin marketplace add awslabs/startups

# Install the plugin
codex plugin install migration-to-aws
```

### Cursor

Install from the [Cursor Marketplace](https://cursor.com/marketplace) (AWS Agent Plugins collection):

1. Open **Cursor Settings**
2. Go to **Plugins**
3. Search for **AWS** or **Migration to AWS**
4. Click **Add to Cursor** and choose user or workspace scope
5. Confirm it appears under **Plugins → Installed**

Requires [Cursor >= 2.5](https://cursor.com/changelog/2-5). See the [Cursor plugins documentation](https://cursor.com/docs/plugins) for details.

> **Note:** Cursor installs are distributed via the [Agent Plugins for AWS](https://github.com/awslabs/agent-plugins) marketplace. Claude Code and Codex installs use the `awslabs/startups` marketplace above.

**Alternative (local development):** Clone this repository and symlink the plugin directory to `~/.cursor/plugins/local/migration-to-aws`, then reload Cursor:

```bash
ln -s "$(pwd)" ~/.cursor/plugins/local/migration-to-aws
```

## migration-to-aws

### Workflow

1. **Discover** — Scan Terraform files, application code, and/or billing data — or inventory your GCP project or Heroku account live via the authenticated `gcloud`/`heroku` CLI (read-only, consent-gated, with drift detection against any Terraform found). Detects infrastructure resources, AI models, agentic frameworks, tools, and orchestration patterns.
2. **Clarify** — Ask targeted questions about migration preferences, AI priorities, agentic migration approach, database sizing, and timeline.
3. **Design** — Map source services to AWS equivalents. For AI workloads: select Bedrock models with honest pricing comparison. For agentic workloads: design AgentCore Harness config or Strands architecture.
4. **Estimate** — Calculate monthly AWS costs using real-time pricing data. Compare to current spend. Writes a decision outcome alongside the execution path: **go / conditional_go / defer_for_evidence / stay** (`recommendation.outcome`), with named conditions, a measured/assumed/unknown decision basis, and "what would flip this" factors. Deferring is rare by design — it fires only when a responsible verdict is genuinely impossible (e.g. specialist-gated services that are a material share of spend and must cut over in the same window).
5. **Generate** — Create migration artifacts: Terraform, provider adapters, `harness.json`, deployment scripts, incremental migration scripts, `MIGRATION_GUIDE.md`, `README.md`, and **`migration-report.html`** (self-contained HTML assessment).
6. **Feedback** _(optional)_ — Collect anonymized feedback to improve the tool.

### Migration report (`migration-report.html`)

The Generate phase produces a browser-ready HTML report with:

- Executive summary (decision outcome as the verdict headline, execution shape and complexity as metadata, cost tiers, timeline, risks)
- Combined infra + AI total cost of ownership (when both tracks ran)
- Security baseline line items (GuardDuty, CloudTrail, budgets, etc.)
- **What This Assessment Rests On** (end of the executive summary): every defaulted assumption with its design consequence, a confidence gloss with the measured/assumed/unknown decision basis, and pricing provenance — linked from the verdict's confidence line
- Detailed appendices: service mappings, per-service costs, migration steps, AI migration, artifacts catalog

After the report is written, run the post-write validator:

```bash
python3 migrate/plugins/migration-to-aws/scripts/validate-migration-report.py \
  "$MIGRATION_DIR/migration-report.html" \
  --estimation-infra "$MIGRATION_DIR/estimation-infra.json" \
  --estimation-ai "$MIGRATION_DIR/estimation-ai.json" \
  --aws-design "$MIGRATION_DIR/aws-design.json"
```

Pass `--estimation-infra` / `--estimation-ai` / `--aws-design` only when those files exist. Resolve the script from the plugin root (`$PLUGIN_ROOT/scripts/validate-migration-report.py` in an installed copy).

**`REPORT_OK | structure=complete`** means required sections, TOC links, and appendix depth checks passed. It does **not** verify that every dollar figure matches the JSON — review numerics before executive sign-off. See [fixtures/README.md](fixtures/README.md) for the reference HTML + estimation JSON contract.

### What It Detects

#### GCP → AWS

| Category             | Examples                                                                                              |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| Infrastructure       | Cloud Run, Cloud SQL, GKE, Cloud Functions, Pub/Sub, Cloud Storage, VPC, DNS                          |
| AI Models            | OpenAI (GPT-4o, GPT-5.x, o-series, embeddings, image, speech), Gemini (Pro, Flash), Anthropic, Cohere |
| Agentic Frameworks   | LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, Strands, custom agent loops                            |
| Integration Patterns | Direct SDK, LangChain, LlamaIndex, LiteLLM, OpenRouter, MCP servers                                   |
| Agent Architecture   | Single agent, hierarchical, swarm, graph, sequential orchestration                                    |
| Tools & Memory       | Tool definitions with transport/auth classification, memory backends (Redis, Postgres, vector stores) |

#### Heroku → AWS

| Category   | Examples                                                                                                                                                              |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Compute    | Dynos (all types) → Elastic Beanstalk (default); Fargate override (direct container control, horizontally scaled non-web dynos), EKS override (Kubernetes preference) |
| Databases  | Heroku Postgres → RDS or Aurora (plan-matched sizing, DMS/pg_dump migration methods)                                                                                  |
| Caching    | Heroku Redis → ElastiCache (plan-matched node types, HA/encryption preserved)                                                                                         |
| Streaming  | Heroku Kafka → Amazon MSK (broker sizing, topic/partition/replication preserved)                                                                                      |
| Add-ons    | 13+ common add-ons → deterministic AWS mappings via Fast-Path Table; unknown → specialist gate                                                                        |
| Networking | Private Spaces → VPC with restricted security groups; VPC peering detection                                                                                           |
| CI/CD      | Pipelines and Review Apps → detect-only (recorded in inventory, no automated migration)                                                                               |
| Secrets    | Config vars → AWS Secrets Manager or SSM Parameter Store                                                                                                              |

### Agent Skill Triggers

| Agent Skill       | Triggers                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **gcp-to-aws**    | "migrate GCP to AWS", "move from GCP", "GCP migration plan", "migrate Cloud SQL to RDS or Aurora", "move Cloud Run to Fargate", "estimate AWS costs for my GCP infrastructure", "migrate my OpenAI app to Bedrock", "migrate my LangChain agents to AWS"                                                                                                                                                                 |
| **heroku-to-aws** | "migrate from Heroku", "Heroku to AWS", "move off Heroku", "migrate Heroku Postgres to RDS", "migrate dynos to Elastic Beanstalk", "migrate dynos to Fargate", "migrate Heroku Private Space", "leave Heroku", "estimate AWS costs for my Heroku app"                                                                                                                                                                    |
| **agent-advisor** | "which runtime for my agent", "AgentCore vs ECS vs EKS vs Lambda", "AgentCore vs Lambda MicroVMs", "deploy an AI agent on AWS", "I have an agent idea — what do I build", "move my agents to AWS with a plan", "add AgentCore memory/gateway/identity to my agent", "I'm already on AWS and want to add agent capabilities", "migrate Temporal workers to AWS", "run Temporal on AWS", "build a POC for my agent on AWS" |

### MCP Servers

| Server      | Purpose                                                                                      |
| ----------- | -------------------------------------------------------------------------------------------- |
| **aws-mcp** | AWS documentation, regional availability, architecture guidance (the unified AWS MCP Server) |

> **Auth note:** unlike the previous zero-auth knowledge endpoint, connecting to the AWS MCP Server may require a one-time AWS sign-in (OAuth 2.1) or SigV4 via a local proxy (`mcp-proxy-for-aws`); the doc/regional-availability tools themselves need no IAM permissions.

The `agent-advisor` Temporal branch reads public Temporal documentation directly, with no login. If a lookup fails, it uses dated cached values marked unverified.

## llm-to-bedrock

The `llm-to-bedrock` skill (bundled in this plugin) extends the assessment with actual code execution — rewriting your OpenAI / Gemini / Anthropic SDK calls to Amazon Bedrock, running quality evaluation against a golden dataset, and delivering a ready-to-merge git branch.

See [skills/llm-to-bedrock/SKILL.md](skills/llm-to-bedrock/SKILL.md) for full details on prerequisites, usage, and what it does to your repo.

## tf-best-practices

The `tf-best-practices` skill (bundled in this plugin) is a **read-only security policy gate** for AWS Terraform. `gcp-to-aws` calls it during its Generate phase to check the Terraform it emits, but it is **self-contained and has no dependency on the migration workflow** — it reads a `terraform/` directory, evaluates policy, and returns a verdict. It never edits `.tf` files or touches migration state.

It enforces a set of fail-open-on-ambiguity rules (internet-facing ALB TLS termination, no public database, no public admin/datastore-port ingress, no wildcard IAM, and RDS + ElastiCache encryption at rest) via a zero-dependency static HCL reader — no `terraform init`, no provider download, so it runs offline and in sub-second time. It complements, and does not replace, `terraform fmt/init/validate` and deeper scanners like `checkov`/`tfsec`.

**Using it directly** (outside a migration) — you can run the gate against any AWS Terraform directory as a pre-commit or CI check:

```bash
# Exit 0 = POLICY_OK, 1 = POLICY_FAIL (with violations), 2 = usage error
python3 skills/tf-best-practices/scripts/validate-terraform-policy.py ./terraform --json verdict.json
```

The `--json` verdict lists each violation with `file`, `line`, `rule`, and `fix_hint` for wiring into your own pipeline. For the authoring posture rules and the full rule list, see [skills/tf-best-practices/SKILL.md](skills/tf-best-practices/SKILL.md). (Scope note: `gcp-to-aws` and `heroku-to-aws` both consume the policy gate in their Generate phase; direct standalone use is also supported.)

## agent-advisor

The `agent-advisor` skill (bundled in this plugin) is the entry point for **running AI agents on AWS** — a different job from a cloud migration. It decides how and where to run agents and produces runnable proof.

- **Runtime selection** — deterministic scoring picks AgentCore, ECS/EKS, Lambda, AWS Batch, or Lambda MicroVMs from your agent's session duration, traffic shape, isolation, memory, and ops preferences.
- **Multi-workload systems** — a system of several agents, batch jobs, and services is decomposed into workload units, each scored independently, with a consolidation option (one platform vs best-fit-per-unit) and a whole-system architecture. A single-unit run collapses to the classic single-verdict flow.
- **Temporal workers** — self-hosted or Temporal Cloud; worker polling tiers and Activity execution classes become units; Workflow orchestration code is never rewritten (never a Step Functions translation).
- **Phased flow** — Intake → Discover → Clarify → deterministic scoring → Design → Estimate → Generate (a layered recommendation doc + `recommendation-report.html`), then optional gated stages: a full **Migration Plan** (generated in-skill by reusing this plugin's gcp-to-aws engine) and a deployable **POC** on the chosen runtime. It also has an add-capabilities branch for teams already running agents on AWS. Artifacts land in `.agent-advisor/<session>/`.

See [skills/agent-advisor/SKILL.md](skills/agent-advisor/SKILL.md) for the full trigger list, phases, and gates.

## Requirements

### First-session checklist

Before a long Clarify interview, make sure these are available on the machine (skills also probe `uv`/`uvx` once on cold start):

| Need                                                   | Why                                                                   | If missing                                                                                                                                                         |
| ------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Agent host (Claude Code / Cursor / Codex / Kiro, etc.) | Runs the skills                                                       | Install your agent                                                                                                                                                 |
| **Python 3**                                           | Terraform policy gate (gcp infra) + report validators at Generate     | gcp infra Generate cannot reach `POLICY_OK` — install before Generate                                                                                              |
| **`uv` / `uvx`**                                       | `llm-to-bedrock` / `agent-advisor` scripts                            | Infra Estimate uses **cached** rates; `llm-to-bedrock` and `agent-advisor` **cannot run** without it. Install from [docs.astral.sh/uv](https://docs.astral.sh/uv/) |
| AWS CLI credentials                                    | Optional for some paths; needed for live AWS checks / Bedrock execute | Configure when those paths run                                                                                                                                     |
| At least one discovery input                           | Live `gcloud` / `heroku`, Terraform, app code, and/or billing         | Skill stops if nothing can produce artifacts                                                                                                                       |

- Claude Code >=2.1.29, Codex (latest), or [Cursor >= 2.5](https://cursor.com/changelog/2-5)
- AWS CLI configured with appropriate credentials
- At least one input source: an authenticated `gcloud` or `heroku` CLI (live discovery), Terraform files, application code, or billing data
- **For GCP infrastructure migration:** an authenticated `gcloud` CLI (recommended — live, read-only discovery with your consent, with drift detection against any Terraform found) or Terraform files / billing exports
- **For GCP AI/agentic migration:** Application source code is required (billing/IaC/live discovery alone cannot detect agent architecture)
- **For Heroku migration:** an authenticated Heroku CLI (recommended) or Terraform files with `heroku_*` resources (Procfile/app.json supplements but cannot stand alone)

### Live GCP discovery — how it works

No Terraform or exports needed. If `gcloud auth login` works in your terminal, just
ask your agent to migrate ("Migrate my GCP infrastructure to AWS" or "Discover my
GCP project and estimate AWS costs"). The agent confirms the target project and asks
for your consent, then inventories it using read-only list/describe commands — it
captures resource names, types, regions, sizing, network topology, and env var
**names only**. It never reads env var values, secret values, database contents, or
access tokens, and never runs a command that creates, changes, or deletes anything.
If you also have Terraform, the agent cross-checks it against your live project and
reports drift. (AI/agentic workload detection still needs your application code.)

### Live Heroku discovery — how it works

No Terraform or exports needed. If `heroku login` works in your terminal, just ask
your agent to migrate ("Migrate my Heroku app to AWS" or "Discover my Heroku apps
and estimate AWS costs"). The agent asks for your consent, then inventories your
account using read-only list/info CLI commands — it captures app names, dyno types,
add-on plans and prices, domains, pipelines, and config var **key names only**. It
never reads config var values, credentials, or your API token, and never runs a
command that creates, changes, or deletes anything. If you also have `heroku_*`
Terraform, the agent cross-checks it against your live account and reports drift.

- **For AI execution (llm-to-bedrock skill):** Python 3.10+, `uv`, and Bedrock model access enabled
- **For agent-advisor:** `uv` (deterministic runtime scoring); source code when deploying/migrating existing agents (an idea-only run needs none); Temporal feature checks use public documentation, with dated, unverified cached values when web access is unavailable

## Architecture & contributing

This plugin ships four skills, built on **different architectures**, and this
matters if you contribute:

- **heroku-to-aws** and **agent-advisor** are built on the **phase DSL** — a declarative
  frontmatter grammar an LLM interprets at runtime, with a static validator that checks the
  structure before anything runs. heroku-to-aws is the reference implementation and the
  **direction for all new work**; agent-advisor follows the same pattern (and vendors the DSL
  interpreter contract).
- **gcp-to-aws** predates the DSL and uses the **older prose design**. It is maintained,
  but a future effort will port it onto the DSL. (It is also reused as the in-skill migration
  engine by agent-advisor's Migration Plan stage.)
- **llm-to-bedrock** is the AI-execution skill (SDK rewrite → Bedrock, eval, git branch),
  invoked from the migration skills' AI-execution step.

**New skills and phases follow the DSL pattern** (`heroku-to-aws`, `agent-advisor`), not the
prose pattern. The grammar is documented under [`docs/`](docs/) — start with
[docs/01-concepts.md](docs/01-concepts.md). For the full contributor workflow —
architecture, build/validate tasks, the vendored shared-files contract, and how to add
a validator check — see [CONTRIBUTING.md](CONTRIBUTING.md).

Quick start for a local change:

```bash
mise install     # install pinned tools
mise run build   # the full gate: lint (md, types, DSL frontmatter, shared-sync, tests) + fmt + security
```

### Migration report validator (unit tests)

When changing `generate-artifacts-report.md`, `scripts/validate-migration-report.py`, or `fixtures/migration-report-reference.html`:

```bash
cd migrate/plugins/migration-to-aws

pytest tests/test_validate_migration_report.py -q

python3 scripts/validat...