heroku-to-aws

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