feat(advisor): port migration-to-aws skills into aws-startup-advisor

[icarthick]

Problem

The migration skills (gcp-to-aws, heroku-to-aws, llm-to-bedrock, agent-advisor, tf-best-practices) currently live in a standalone migration-to-aws plugin at migrate/plugins/migration-to-aws/. A stale, outdated copy of one skill (migration-to-aws, the old prose gcp-to-aws) ships inside aws-startup-advisor. Leadership has asked for one canonical plugin — aws-startup-advisor — containing all skills, published to Claude Code, Codex, and Cursor.

Solution

Port the 5 migration skills + canonical shared/ + 6 agents + CI tooling into advisor/plugins/aws-startup-advisor/, making it the consolidated plugin (v2.0.0). The standalone migration-to-aws plugin is intentionally left in place — retirement is a follow-up.

What moved:

• 5 skills: agent-advisor, gcp-to-aws, heroku-to-aws, llm-to-bedrock, tf-best-practices + canonical skills/shared/
• 6 agents: generic-phase-worker-rw, llm2bedrock-code-analyzer, -code-rewriter, -log-ingestor, -prompt-evaluator, -report-generator
• CI tooling: tools/ (frontmatter-validator, sync-vendored-shared, fixtures-check, pricing-staleness, run-asserters), tests/, fixtures/, scripts/, docs/, bandit.yml, tsconfig.json

What changed (not just copied):

• 27 plugin-scoped invocation prefixes rewritten: migration-to-aws: → aws-startup-advisor:
• Prose/diagram references rewritten to name actual sibling skills — with careful distinction between platform-generic handoffs and genuinely gcp-specific references
• .mcp.json: added temporal-docs + aws-pricing-calculator servers
• All 4 manifests bumped to 2.0.0 with expanded descriptions/keywords/defaultPrompts
• CI tools parameterized by plugin path (one source, two validation targets)
• mise.toml extended to validate both plugins in parallel
• .github/workflows/security-scanners.yml bandit job: three-pass
• .checkov.yaml skip-paths mirrored for advisor fixtures
• JSON Schema $id URLs → URN form (no GitHub Pages publishing; avoids skills.sh flags per fix: replace github.io URLs to resolve skills.sh security scan flags #204)
• advisor/README.md, AGENTS.md, setup.md refreshed for the 9-skill plugin
• Root README.md Plugins table now lists aws-startup-advisor

Deleted:

• advisor/plugins/aws-startup-advisor/skills/migration-to-aws/ (stale old copy)

Type of Change

• New plugin/power/tool
• Enhancement to existing content
• Documentation update
• Guardrail/CI update

Team Folder

• advisor/
• Other: root (.checkov.yaml, mise.toml, .github/workflows/, .claude-plugin/marketplace.json, README.md)

Checklist

• I have read the CONTRIBUTING.md guidelines
• My changes do not include hardcoded secrets, credentials, or internal-only content
• I have run mise run build locally and it passes
• I have updated documentation if needed
• My changes are scoped to my team's folder only (NOTE: extends into root CI/manifests by necessity — advisor needs its fixtures in .checkov.yaml, its bandit pass in the CI workflow, and its entry in marketplace.json)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

---

Testing performed

Static validation:

• mise run build green (lint:frontmatter ×4 roots, shared:check ×2, fixtures ×4, pricing ×2, types ×2, test 57 pass, fmt:check, full security suite)
• agent-advisor pytest: 230 pass
• File-count parity verified; vendored byte-identity confirmed
• Enforcement bite-test: broke advisor frontmatter → validator failed (exit 1), reverted

Runtime validation (headless Claude Code with --plugin-dir):

• gcp-to-aws: 7-phase EXIT=0, 12 Terraform files + 4 scripts + docs
• heroku-to-aws: 7-phase EXIT=0, Beanstalk Terraform + CI/CD + pg_dump script
• llm-to-bedrock: EXIT=0, cross-skill delegation to aws-startup-advisor:gcp-to-aws proven
• agent-advisor: 6-phase DSL backbone EXIT=0, scoring → AgentCore verdict, recommendation doc

Adversarial review (3 independent passes):

• Pass 1: found semantic regression (compute handoffs narrowed to GCP-only) + stale refs. Fixed.
• Pass 2: found stale AGENTS.md. Fixed.
• Pass 3: verdict READY TO PR, 0 blocker/high.

Design decisions

1. Old plugin stays live — retirement is a separate follow-up
2. Tool parameterization — one tool source validates both plugin trees
3. Platform-generic vs gcp-specific — compute handoffs say "gcp-to-aws or heroku-to-aws"; migration-plan refs stay gcp-specific (by design)
4. Schema $id as URN — avoids skills.sh flags without breaking schema identity
5. Version 2.0.0 — material scope expansion warrants a major bump

Known items (intentional follow-up)

• Root README migration-to-aws narrative — accurate while old plugin lives
• generic-phase-worker-ro/-git in INTERPRETER.md docs but not shipped — pre-existing, no phase dispatches them
• aws.github.io/eks-charts Helm URL — load-bearing, no github.com substitute

[leon1418]

[🤖 AI review 🤖]

Summary

Large consolidation PR (405 files, +51K/-2.3K) porting the 5 migration skills + 6 agents + CI tooling from migrate/plugins/migration-to-aws/ into advisor/plugins/aws-startup-advisor/. The scope is primarily additive (new skill copies) with surgical modifications to root CI, manifests, and existing advisor files. Overall well-structured — CI parameterization is sound, prefix rewrites are consistent, and the deleted stale migration-to-aws/ copy inside advisor is appropriate.

Findings

1. Blocking: Third-party MCP dependency (sample-aws-pricing-calculator-mcp) — The .mcp.json adds a new stdio MCP server running npx -y sample-aws-pricing-calculator-mcp@latest. This is maintained by a single individual (frumania, info@frumania.com), has no repository URL, no homepage, and no visible AWS org affiliation. Consider pinning to a specific version instead of @latest (supply-chain risk) and/or adding a comment about provenance.

2. Nit: Schema $id URN still says migration-to-aws — The vendored schemas at skills/heroku-to-aws/references/vendored/*/ and skills/shared/*/ use URN urn:awslabs:startups:migration-to-aws:.... Per PR description this is intentional (namespace identity, not invocation prefix), but it could confuse contributors. A one-line comment in each schema noting this is the canonical URN namespace (not a skill reference) would help.

What looks good

• 27 invocation-prefix rewrites from migration-to-aws: → aws-startup-advisor: are complete — no stale migration-to-aws: invocation references remain in skill files.
• Three-pass bandit scan correctly isolates per-plugin configs with proper exclusion logic.
• CI mise.toml parallelization validates both plugin trees with a single tool source.
• Pricing cache refreshed to 2026-07-17 with Graviton ARM64 rows, Claude Fable 5/Sonnet 5/Opus 4.8, and EOL lifecycle updates.
• Proper phase-status schema evolution (workshop sidebar added consistently).
• Deleted stale skills/migration-to-aws/ is the old prose copy — no SKILL.md was lost.

Validation gaps

• Could not run mise run build or the full test suite (405-file PR exceeds API diff limit; no local checkout performed). PR description claims green CI locally.
• No GitHub Actions status checks visible (empty statusCheckRollup), so automated CI result cannot be verified.
• The temporal-docs HTTP MCP server (https://temporal.mcp.kapa.ai) is a third-party service — no availability/uptime SLA is documented.

Merge recommendation

Not yet merge-ready — pin sample-aws-pricing-calculator-mcp to an exact reviewed version before merge. Apart from this blocker, the port is scoped correctly for a major version bump.

[icarthick]

Thanks for the review. Addressed both findings in 38ce478:

1. Blocking (pinned): sample-aws-pricing-calculator-mcp@latest → @1.2.8. The @latest pattern was inherited from the source migration-to-aws plugin — we improve on it here by pinning. Package metadata: MIT-0 license, single maintainer (frumania), no repo/homepage. Worth tracking upstream separately if we want the source plugin pinned too.

2. Nit (done): Added $comment to all 4 JSON Schema files (2 canonical + 2 vendored) clarifying the URN migration-to-aws is a stable schema namespace identity, not a plugin name or invocation prefix.

Re: validation gaps noted:

• mise run build passes locally (just re-verified after this fix commit). CI should run on this push.
• The temporal-docs MCP server (temporal.mcp.kapa.ai) is the same third-party dependency already shipping in the published migration-to-aws plugin (v1.6.0) — no new availability risk introduced by this consolidation. Agreed it has no documented SLA; that's a pre-existing consideration for both plugins.

[ayn-builds]

The scheduled strict staleness gate didn't come along for the ride.

mise run build is warn-only by design, so .github/workflows/pricing-staleness.yml is the only place a stale cache actually fails somebody. The mise task got extended to both plugins here, but the workflow still runs the unparameterized form:

node migrate/plugins/migration-to-aws/tools/pricing-staleness.ts --strict

PLUGIN defaults to migrate/plugins/migration-to-aws, so that pass walks the 5 caches under migrate/ and never looks at advisor/. Now that advisor is the canonical plugin, its caches are the ones users are actually estimating from, and they're the ones with no gate behind them.

Not on fire yet - advisor's caches are dated 2026-07-17 and 2026-07-19 against 30-day windows, so the first one tips over on 2026-08-16.

      - name: Check pricing cache freshness (strict)
        run: |
          node migrate/plugins/migration-to-aws/tools/pricing-staleness.ts --strict
          node advisor/plugins/aws-startup-advisor/tools/pricing-staleness.ts advisor/plugins/aws-startup-advisor --strict

Worth noting the default shell is bash -e: if the migrate pass goes stale first, the advisor pass never runs and you only see half the picture. Two separate steps, or collecting exit codes the way the bandit job already does, would avoid that.

Header comment says "the migration-to-aws pricing caches" and wants the same touch-up.

[ayn-builds]

Heads up that this branch predates #200, #201 and #202, and it forks advisor copies of every
file those three fix. There's no file overlap between this PR and any of them, so all four merge
cleanly with no conflict - the advisor plugin just lands carrying all three bugs.

I checked each fix against the advisor copies on 4ae3f40. All ten are absent:

From #201, in advisor/plugins/aws-startup-advisor/skills/llm-to-bedrock/scripts/bedrock_pricing.py:

• Opus 4.8 is still 0.015/0.075, Opus 4.1's legacy rate. Should be 0.005/0.025.
• The regression test for it is missing from test_bedrock_pricing.py.
• tools/pricing-staleness.ts has no drift check, so nothing catches the row going stale again.

This one has teeth: STATIC_FALLBACK is consulted before the PriceList API, so the wrong row is
the primary source rather than a fallback, and every Opus 4.8 estimate comes out 3x high.

From #200, under advisor/plugins/aws-startup-advisor/skills/heroku-to-aws/:

• knowledge/design/dyno-fargate-sizing.json has 19 rows, no eco or basic.
• knowledge/design/eks-pod-sizing.json same, 19 rows.
• references/phases/design/design-eks.md still says halt-on-unknown-dyno instead of
  reject-warn-continue.
• references/shared/schema-discover-heroku.md still lists 7 dyno types instead of 21.
• tools/run-asserters.py doesn't register the non-web asserter, and there's no
  fixtures/heroku-nonweb-scaling/ on the advisor side at all, so that's an absent test rather
  than a stale copy.

The effect is an eco or basic worker at quantity > 1 dropping out of the design with only
a warning.

From #202, in advisor/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate-artifacts-scripts.md:

• No has_bigquery flag.
• The bq extract / gs:// to s3:// block is still there, which is what the specialist gate
  exists to prevent.

Worth calling out that this PR also forks pricing-staleness.ts and run-asserters.py, so the
gates #200 and #201 added to catch these don't run against advisor either. The fixes and the
tests that would catch their absence are missing on the same side.

Simplest sequence is probably to let those three land first and rebase, rather than hand-porting
ten changes. Either way it'd be worth re-running mise run fixtures:assert and the staleness
task against the advisor plugin afterwards to confirm the ported gates actually fire.

[az-zhu]

npx skills add - the only install command advisor's own docs give - copies one directory per skill and nothing above skills/, so agents/ never lands and llm-to-bedrock's Phase C can't resolve its five llm2bedrock-* subagents. Inline mode isn't an escape either..

[az-zhu]

Is it safer to rebase it before merge? It's 4 PRs behind

[ayn-builds]

Inline notes on seven specific spots below. They share one root cause, which I'll write up separately: the ported trees are a pre-#195/#196/#197/#199/#200/#201 snapshot, and because the port copies files to new paths, the two merges from main couldn't conflict on any of it.

[ayn-builds]

Something worth knowing before this merges: the two merges from main don't mean what they look like they mean.

The port copies the five skill trees to new paths under advisor/, so git has nothing to conflict on. merge-base says main is fully merged - and it is - but the copies underneath have been drifting the whole time. Both merges came back clean and there was no way for anyone to notice.

The fork point is b401bb1 (08-07). 54 files have changed under migrate/plugins/migration-to-aws/skills/ since:

• 32 are ported but stale - the advisor copy is a byte-exact older revision
• 22 were never ported at all

I checked these by blob-hash matching against upstream history rather than reading diffs, so the deliberate prefix rewrites don't muddy the count. The consequences worth acting on are inline: the RDS guidance, dyno halt, dyno types, the Opus 4.8 rate, the policy validator, plugin-root resolution, tool defaults.

The stuff that's missing rather than stale

agent-advisor predates #195, so a whole feature is just absent: references/phases/model-recommend/, references/models/{anthropic,openai}-bedrock-2026-07-21.json, four *_model_recommendation.py / verify_model_path.py scripts with their tests, and the four schemas under scripts/schemas/.

seed.json is the one I'd care about most. It's the highest-precedence input to the deterministic scorer, which is what makes a headless run reproducible - without it there's no byte-identical replay, and the validation runs in the PR description are leaning on exactly that.

The other 7 never-ported files are the tf-best-practices fixtures, which are the tests that would have caught the validator problem.

Why nothing caught any of this

I went looking for a gate that should have fired. shared:check compares vendored against canonical inside a plugin - advisor's three vendored trees are byte-clean, I checked by hand, so it passes and it's right to pass. Nothing compares advisor against migrate.

The bigger issue is that the PR duplicates tests/, fixtures/, and tools/ next to the skills. So each parameterized gate validates a tree against its own stale copy of the tests. That's how you get a green build sitting on top of four fixes that landed last week.

Two ways out, and I don't have a strong preference:

• A cross-plugin diff in mise.toml - diff -r over the five trees with an allowlist for the ~20 files that legitimately differ. Cheap, and it fails loudly the next time a fix lands on one side only.
• Or stop duplicating: one source plus a sync step, which is what sync-vendored-shared.ts already does a level down. More work up front, but the drift class disappears.

For this PR specifically I'd re-copy the five trees from current main and re-apply the 27 prefix rewrites, rather than hand-porting 32 files and hoping the list is complete.

Worth watching on merge order

#202 is a different shape to the four above - it's still open, so nothing is reverted yet. But it fixes gcp-to-aws/references/phases/generate/generate-artifacts-scripts.md, and this PR forks that exact file into advisor. Both copies carry the bug right now. If #206 lands first, merging #202 only fixes the migrate/ side and the advisor copy keeps prescribing a BigQuery data lake on S3 until someone knows to go looking. Same applies in reverse to anything else in flight that touches the five ported trees.

One from my earlier comment

.github/workflows/pricing-staleness.yml still isn't touched here, so it runs only the unparameterized migrate pass and advisor's caches have no strict gate behind them. Couldn't leave this inline since the file isn't in the diff. gcp-to-aws/references/shared/pricing-cache.md is dated 2026-07-17 against a 30-day window, so it tips over on the 16th. The bash -e ordering point still applies, and the header comment still says "the migration-to-aws pricing caches".

The consolidation itself is sound, and the CI parameterization is the good kind of fiddly. It's the drift I'd want cleared before this lands - as it stands it puts back four fixes from the last week, two of them security guidance and one a policy validator.

[icarthick]

@ayn-builds thanks for the deep review — the copy-to-new-path drift analysis was exactly right. Addressed in c2e2a49.

Re-synced instead of hand-porting

Rather than hand-port the drifted files, I re-copied all 5 skill trees + shared/ + agents/ + tools/tests/fixtures/scripts/docs fresh from current main's migrate/ source (which now carries the merged fixes), then re-applied the mechanical rewrites (27 invocation prefixes, repo paths, URN schema $ids + $comment, tool path params) and the semantic relabels (platform-generic compute handoffs, sibling repoints). Advisor is now current with:

• fix(llm-to-bedrock): correct Opus 4.8 fallback rate to $5/$25 per 1M #201 — Opus 4.8 fallback is 0.005/0.025 (was the 3x-high 0.015/0.075)
• fix(heroku-to-aws): add eco/basic rows to the Fargate + EKS dyno sizing tables #200 — eco/basic rows in the Fargate + EKS dyno sizing tables; the non-web asserter + fixtures/heroku-nonweb-scaling/ came along
• fix(heroku-to-aws): replace 0.0.0.0/0 interim RDS exposure with a scoped allowlist #199 — RDS interim-exposure guidance
• fix(tf-best-practices): detect IPv6 public ingress and fix order-dependent IPv4 check in Terraform policy validator #196 / fix(tf-best-practices): read quoted integer ports in policy validator #197 — tf-best-practices policy validator (IPv6 ingress, quoted ports) + the tf-best-practices fixtures
• feat(agent-advisor): Model Recommend phase (Anthropic + OpenAI→Bedrock) + seeded runs #195 — the whole agent-advisor Model Recommend phase (references/phases/model-recommend/, the model JSONs, the *_model_recommendation.py / verify_model_path.py scripts + tests, the schemas) and seed.json — so deterministic replay is real again

New cross-plugin drift gate (the structural fix)

Added tools/cross-plugin-drift.ts + a drift:check mise task, wired into lint (so mise run build and CI both run it). It compares the two plugin copies directly — normalizing the intentional prefix/path/schema-id differences and allowlisting the ~25 deliberately-divergent prose files — and fails loudly the next time a fix lands on one side only. Verified it bites: a simulated unported change to a non-allowlisted file exits 1. This closes the "green build on top of last week's fixes" gap you flagged — nothing compared advisor against migrate before.

Current state: 250 identical, 25 allowlisted across 6 skill trees.

pricing-staleness workflow

.github/workflows/pricing-staleness.yml now runs a strict advisor pass as a separate step (so bash -e ordering can't mask it if the migrate pass trips first), and the header comment is updated.

On merge order (#202)

#202 is still open and touches gcp-to-aws/references/phases/generate/generate-artifacts-scripts.md, which this PR also forks. Both copies carry the BigQuery-on-S3 bug right now, so they're consistent-with-source. Whichever lands first, the drift gate will now flag the other side as soon as the fix lands on one — so it won't silently persist.

mise run build is green.