heroku-to-aws

Files (71)

• SKILL.md
• dyno-eb-sizing.json · knowledge/design/
• dyno-fargate-sizing.json · knowledge/design/
• eks-pod-sizing.json · knowledge/design/
• fast-path-addons.json · knowledge/design/
• kafka-msk-sizing.json · knowledge/design/
• postgres-rds-sizing.json · knowledge/design/
• redis-elasticache-sizing.json · knowledge/design/
• estimate-defaults.json · knowledge/estimate/
• clarify-assemble.md · references/phases/clarify/
• clarify-interview.md · references/phases/clarify/
• clarify.md · references/phases/clarify/
• design-assemble.md · references/phases/design/
• design-eks.md · references/phases/design/
• design-mapping.md · references/phases/design/
• design.md · references/phases/design/
• discover-assemble.md · references/phases/discover/
• discover-billing.md · references/phases/discover/
• discover-live-capture.md · references/phases/discover/
• discover-live.md · references/phases/discover/
• discover-terraform.md · references/phases/discover/
• discover.md · references/phases/discover/
• estimate-assemble.md · references/phases/estimate/
• estimate-cost-engine.md · references/phases/estimate/
• estimate.md · references/phases/estimate/
• feedback-assemble.md · references/phases/feedback/
• feedback-collect.md · references/phases/feedback/
• feedback.md · references/phases/feedback/
• generate-assemble.md · references/phases/generate/
• generate-docs.md · references/phases/generate/
• generate-eks.md · references/phases/generate/
• generate-report.md · references/phases/generate/
• generate-terraform.md · references/phases/generate/
• generate.md · references/phases/generate/
• workshop-assemble.md · references/phases/workshop/
• workshop-compare.md · references/phases/workshop/
• workshop-refresh.md · references/phases/workshop/
• workshop-sheet.md · references/phases/workshop/
• workshop.md · references/phases/workshop/
• README.md · references/shared/
• application-source-contract.md · references/shared/
• application-source-contract.schema.json · references/shared/
• heroku-pricing-cache.md · references/shared/
• report-decision-core.md · references/shared/
• schema-discover-heroku.md · references/shared/
• schema-workshop-scenarios.md · references/shared/
• README.md · references/vendored/
• INTERPRETER.md · references/vendored/dsl/
• complexity-tiers.json · references/vendored/estimate/
• estimation-infra.schema.json · references/vendored/estimate/
• pricing-mode.md · references/vendored/estimate/
• ri-sp-eligibility.md · references/vendored/estimate/
• aws-infra-pricing.json · references/vendored/pricing/
• phase-status.schema.json · references/vendored/state/
• PROTOCOL.md · references/vendored/telemetry/
• cli.py · references/vendored/telemetry/
• accept.py · references/vendored/telemetry/consent/
• cli.py · references/vendored/telemetry/consent/
• notice.py · references/vendored/telemetry/consent/
• opt_out.py · references/vendored/telemetry/consent/
• …and 11 more

SKILL.md (first lines)

# Heroku-to-AWS Migration Skill

The skill base directory is given in the "Base directory for this skill: X" line the
harness emits at load time. Call it `<SKILL_BASE>`. The report validator lives at
`<SKILL_BASE>/scripts/validate-heroku-migration-report.py` — resolve it relative to
`<SKILL_BASE>`, never assume a plugin-root `scripts/` directory, since a standalone
`npx skills add --skill heroku-to-aws` install carries only this skill's own
directory tree, not the plugin's top-level `scripts/`.

## Optional usage telemetry

Before starting or resuming, load `references/vendored/telemetry/PROTOCOL.md` and
run its read-only status check. Use the returned reporting mode rather than the
model's identity. Complete the existing notice exchange only when that protocol
requires it; unavailable or declined telemetry never blocks this skill.

## Philosophy

- **Full platform exit by default**: Heroku is in sustaining engineering (KTLO) — stability and support only, no new investment. Enterprise contracts are no longer sold to new customers. This skill assumes complete departure from Heroku (compute, data, and add-ons) within a user-defined window. Do not recommend indefinite continued use of Heroku.
- **PaaS-to-PaaS by default, recommendation-shaped**: Elastic Beanstalk (Docker platform, AL2023) is the default compute target because it preserves Heroku's managed platform model (source deployment, platform-managed environments, and lower operational burden than direct container orchestration). Clarify presents a per-formation compute recommendation before asking for confirmation. Fargate remains the override for direct container control and is used automatically for horizontally scaled non-web processes that EB SingleInstance cannot preserve; EKS remains the override for teams with Kubernetes expertise. ECS Express Mode may be mentioned only as a forward-look for the Fargate override path, not as a replacement for the EB default. Do not recommend AWS App Runner (no longer accepting new customers as of April 2026).
- **Interim cutover is bounded**: If a user chooses data-first migration (database on AWS, app temporarily on Heroku), treat this as a bounded phase (weeks, not quarters). Require a target exit date and surface KTLO platform risk warnings.
- **Re-platform by default**: Select AWS services that match Heroku workload types (e.g., Dynos → Elastic Beanstalk, Heroku Postgres → RDS/Aurora, Heroku Redis → ElastiCache, Kafka → MSK).
- **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 Heroku invoice line items in the infra estimate when billing exists) are allowed.
- **Live-first discovery, read-only and consent-gated**: The user's authenticated Heroku CLI is a first-class discovery source — most startups have no `heroku_*` Terraform, and the account is authoritative for what actually runs. Live capture is strictly read-only (an exact-command allowlist of list/info commands), requires explicit consent, never captures config var values (key names only), and never extracts the API token. Terraform files (`.tf` with `heroku_*` resources) and repo artifacts (Procfile, app.json) remain fully supported; when both live and Terraform data exist, live wins for current state, Terraform supplements structure and provenance, and disagreements are surfaced as drift — never silently resolved.
- **Flat resource model**: Heroku resources are organized per-app without dependency graphs or clustering. No topological sorting, typed edges, or cluster formation logic. Resources are processed as a flat list in input order.
- **Deterministic mappings**: Core services use fixed lookup tables (Dyno Type Table, Postgres Plan Table, Redis Plan Table, Kafka Plan Table). Common add-ons use the Fast-Path Table. Unknown add-ons hit the specialist gate.
- **DMS has Heroku constraints**: AWS DMS cannot perform continuous replication (CDC) with Heroku Postgres because Heroku does not grant the REPLICATION role. DMS is for one-time bulk migration with a cutover window only. The skill must surface this constraint when DMS is selected.
- **What-if after Estimate**: After costs are computed, SAs can enter an optional what-if workshop sidebar (`references/phases/workshop/workshop.md`) to change region, HA, compute target, or CPU architecture (x86 vs Graviton), refresh Design + Estimate, and compare up to 5 priced scenarios — without re-running Discover. Rates are cache-based (us-east-1 anchor; regional deltas are noted qualitatively). Workshop arch defaults to **x86_64** here (EB tables historically x86-first).

---

## 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/0315-1030/`). Set during Phase 1 (Discover).

---

## Phase Structure (frontmatter)

Phase and unit files carry a YAML frontmatter block that declares how the phase is
composed — its inputs, the fragments it runs, the assembler that combines them,
what it produces, its gates, and what it requires/advances-to. The DSL interpreter
contract is the vendored `references/vendored/dsl/INTERPRETER.md`: it defines every
frontmatter key, the fragment/assembler model, and the interpreter loop. **Load it
first** (once, at the start of a migration), then execute a phase file's prose
body. Elsewhere in this skill, `INTERPRETER.md` (without a path) refers to this
same loaded contract.

Frontmatter is being introduced phase-by-phase; a phase file without it runs from
its prose as before.

---

## 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 MUST NOT be loaded unless the condition is met. Do not speculatively load files.
- **No duplication:** 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.

Each phase declares its own conditional reference/knowledge loads in frontmatter (a fragment `_trigger` or a `_knowledge` entry's `_when`); do not maintain a separate load-condition table here.

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.

---

## Execution

This skill is driven by the interpreter loop in `INTERPRETER.md` (§ The interpreter
loop): it reads `.phase-status.json`, determines the current phase, runs each
phase's `_preconditions` / fragments / `_assemble` / `_postconditions`, advances on
`HANDOFF_OK` via `_advances_to`, and validates state. The phase set, ordering, and
gates are all derived from the phase files' frontmatter and `INTERPRETER.md` — they
are not restated here.

**Cold start (entry phase).** On a cold start — no `.migration/` run with a
`.phase-status.json` yet — begin at `references/phases/discover/discover.md`, this
skill's entry phase (the one carrying `_init: true`). The interpreter loads THIS
phase directly; it does not scan every phase's frontmatter to discover the root.
All subsequent phases are reached by following each phase's `_advances_to`. On a
warm start, `current_phase` in `.phase-status.json` is authoritative **except**
when deferred-advance sidebar resume applies (`INTERPRETER.md` § The
interpreter loop step 2 — Estimate completed + `workshop` pending/in_progress
must not re-run Estimate).

**Session tooling check (once per cold start).** Before Discover on a cold start,
probe tooling **once** — do not re-check every phase:

```bash
uv --version 2>/dev/null || echo "UV_MISSING"
uvx --version 2>/dev/null || echo "UVX_MISSING"
```

- If `UV_MISSING` or `UVX_MISSING`: warn the user **once** that
  [`uv` / `uvx`](https://docs.astral.sh/uv/) is required for the `llm-to-bedrock`
  and `agent-advisor` scripts. Continue Discover → Clarify → Design.
  At Estimate / workshop, price from the us-east-1 cache and set each
  service's `pricing_source.status` per the hierarchy in
  `references/vendored/estimate/pricing-mode.md` — `"cached"` for services the
  cache covers (`"cached_stale"` past the staleness threshold per Step 0a), and
  `"estimated"` / `"unavailable"` for services it doesn't.
  **Do not hard-stop** an infrastructure migration for missing `uv`.
- If both are present: proceed without nagging.
- Soft-warn once if `python3` is missing (Heroku report validation at Generate
  uses `<SKILL_BASE>/scripts/validate-heroku-migration-report.py`). Earlier phases
  (Discover → Estimate) may continue after the warning, but **Generate does not
  complete until the report validator runs successfully** — install `python3`
  before Generate. This matches `generate.md`'s Finish-Generate step and its
  `report-validation-status.json` postcondition: absent or `not_run` validation is a
  blocking `GATE_FAIL`, not a pass. Never report an unvalidated report as passing.

**Clarify is mandatory (heroku policy).** Do not skip Clarify or jump straight to
Design, Estimate, or Generate even if the user asks — there is no exception for
"quick" or "obvious" migrations. A `preferences.json` that was not produced by an
actual Clarify run does not count. If asked to skip, refuse briefly and run

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws