agent-advisor

---
name: agent-advisor
description: "Unified entry point for AI-agent work on AWS: evaluate and pick a runtime, generate a full migration plan (for existing workloads), and build an executable POC — all in one flow. Triggers on: which runtime for my agent, AgentCore vs ECS vs EKS vs Lambda, AgentCore vs Lambda MicroVMs, deploy an AI agent on AWS, agent architecture on AWS, I have an agent idea what do I build, move my agents to AWS, migrate my agents to AWS with a plan, agent migration plan, add AgentCore services, add memory/gateway/identity/policy to my agent, enable AgentCore Memory, add observability to my agent, I'm already on AWS and want to add agent capabilities, migrate Temporal workers to AWS, Temporal to AWS, run Temporal on AWS, Temporal workers on AWS, we use Temporal and want to move to AWS, our service is orchestrated by Temporal, what do I build on AWS for my Temporal workers, move a Temporal-based service to AWS, Temporal Cloud or self-hosted on AWS. Runs a phased flow: Intake (entry point + technical background), Discover (lightweight code detection), Clarify (adaptive questions), deterministic scoring, Design (runtime + deployment model + services + model), Estimate (coarse cost), Generate (layered recommendation doc + scaffolding), then optional gated stages: Migration Plan (full plan generated in-skill by reusing this plugin's gcp-to-aws engine, with the advisor's decisions carried over) and POC (deployment plan + deployable proof-of-concept on the recommended runtime — AgentCore, ECS, EKS, or Lambda; generated deliverables by default, or assisted build in your account on explicit opt-in). Systems with several workloads (interacting or independent agents, batch jobs, services) are decomposed into workload units, each getting its own verdict with a consolidation option. An add-capabilities branch (for teams already running agents on AWS) recommends which AgentCore services to enable on any runtime — no runtime scoring. Temporal systems dissolve into the same unit flow — worker polling tiers and Activity execution classes become units (rules in the Temporal decision reference); Workflow orchestration code is never rewritten — never a Step Functions translation. Requires at least one agentic component: a purely non-agent system (only plain services / batch jobs / HTTP endpoints, or a Temporal worker whose Activities are all non-agent) is out of scope — Clarify halts it (scope gate) and points to migration-to-aws / heroku-to-aws / llm-to-bedrock. Not for: pure compute/data migration with no AI agent; pure LLM SDK rewrite without agent architecture (use llm-to-bedrock); or detailed per-model pricing."
---

# AWS Agent Advisor

Helps startups decide how and where to run AI agents on AWS. Deterministic scoring
recommends a runtime; the conversation adapts to the user's technical background.
For AgentCore microVMs, default to V2 without a version-preference question; check applicability
and retain V1 only for an evidenced exception. Design and POC load
`references/decision-refs/agentcore-platform.md` for this policy.

## Definitions

- **"Load"** = Read the file with the Read tool and follow it. Do not summarize or skip.
- **`$RUN_DIR`** = the run directory under `.agent-advisor/` (e.g. `.agent-advisor/0630-1430/`),
  created in Intake.
- **`$PLUGIN`** = `${CLAUDE_PLUGIN_ROOT}` (the installed plugin root). On Claude Code this token
  substitutes inline. **If `${CLAUDE_PLUGIN_ROOT}` does not resolve** (some Cursor/Codex builds,
  or a literal `${CLAUDE_PLUGIN_ROOT}` string showing up in a path error), fall back to the
  skill's own directory: this SKILL.md lives at `<plugin>/skills/agent-advisor/SKILL.md`, so the
  engine and its data are all inside this skill — scripts at `./scripts/...`, runtime profiles at
  `./references/runtimes/...`, and decision refs at `./references/decision-refs/...` relative to
  it. Prefer `${CLAUDE_PLUGIN_ROOT}/skills/agent-advisor/...`; use the relative fallback only when
  it fails to resolve.

## Prerequisites

- `uv` available (for scoring). Check: `uv --version`. If missing, tell the user to install
  it from the official install guide (https://docs.astral.sh/uv/getting-started/installation/ — e.g. `brew install uv` or `pipx install uv`) and stop.

## Phase Structure (frontmatter)

Phase, fragment, and assembler files carry a YAML frontmatter block that declares how each
phase is composed — its inputs, triggers, fragments, assembler, artifacts, gates, and
ordering. The execution contract is the vendored `references/vendored/dsl/INTERPRETER.md`:
it defines every frontmatter key, the fragment/assembler model, the gate protocol
(`HANDOFF_OK` / `GATE_FAIL`), and the interpreter loop. **Load it first** (once, at the
start of a run), then execute each phase file's prose body. Elsewhere in this skill,
`INTERPRETER.md` (without a path) refers to this loaded contract.

## 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 backbone (intake → discover → clarify →
confirm → design → estimate → generate → migration-plan → poc → complete) and the
one sidebar branch (add-capabilities) are derived
from the phase files' frontmatter — they are not restated here.

**Cold start (entry phase).** With no run under `.agent-advisor/` carrying a
`.phase-status.json`, begin at `references/phases/intake/intake.md` — this skill's entry
phase (the one carrying `_init: true`). On a warm start, `current_phase` in
`.phase-status.json` is authoritative (`INTERPRETER.md` § The interpreter loop).

**Skill bindings (`INTERPRETER.md` § Skill bindings).** This skill declares:

- **Run root**: `.agent-advisor/` — `$RUN_DIR` is this skill's name for the run directory
  (`.agent-advisor/[MMDD-HHMM]/`). Intake's own prose performs the `_init` bootstrap.
- **State shape**: § State file below (advisor-specific keys such as `entry_point`,
  `audience`, `recommendation_reviewed`, `migration_plan_ctx`, `migration_plan_unavailable`);
  the shared state schema is not vendored.
- **Run seed (optional)**: `$RUN_DIR/seed.json`, else `.agent-advisor/seed.json` at the run root
  (schema `scripts/schemas/seed.json`) supplies
  machine-readable answers for a non-interactive run — the Clarify dimensions, the two gate
  answers, the POC mode, the live-probe answer, and a `co_recommend` tie-break. It is the
  HIGHEST-precedence source for every value it carries (clarify.md Step 2.5), which is what makes
  a repeated run's score comparable: the deterministic engine gets byte-identical input. A gate
  the seed omits is declined; a dimension the seed omits falls through to detection, then prose,
  then an `assumed` value that MUST be recorded in `$RUN_DIR/UNANSWERED.md`. With no seed, the
  interactive flow is unchanged.
- **Resolved statuses**: `skipped` (routing resolved the phase without running it), plus
  `not_applicable` for `migration_plan` only.
- **Conditional backbone routing**: the entry-point routing below. When a routing rule
  marks a phase not-applicable, set it `skipped` and advance through its `_advances_to` in
  the same state write.

## Routing & gates (orchestration)

Sidebar placement and conditional backbone routing are orchestration prose owned by
this file (`INTERPRETER.md` § Skill bindings, § Backbone vs sidebar).

**Entry-point routing:**

- `build_scratch` → skip Discover; Clarify → Confirm → Design → Estimate → Generate → **Gate 2 → POC (any winning runtime)**. No migration plan (nothing existing to migrate).
- `build_deploy` → Discover (if code) → Clarify → Confirm → Design → Estimate → Generate → **Gate 1 → Migration Plan (if existing non-AWS AI workload detected and user confirms)** → **Gate 2 → POC (any winning runtime)**.
- `migrate` → Discover (if code) → Clarify → Confirm → Design → Estimate (target-state run cost; migration TCO comparison stays with the Migration Plan engine) → Generate → **Gate 1 → Migration Plan (in-skill, reusing the sibling `gcp-to-aws` skill)** → **Gate 2 → POC (any winning runtime, when the plan was produced)**. Declining Gate 1 keeps the classic handoff: pointer to `/migration-to-aws:llm-to-bedrock` with `handoff-summary.md`.
- `add_capabilities` → load `references/phases/add-capabilities/add-capabilities.md` and follow it (no runtime
  scoring; writes `capabilities-recommendation.md`). This is a self-contained branch — it does
  NOT pass through Clarify / Confirm / Design / Estimate / Generate, so the phase gate
  below never applies to it.
- Temporal detection routes into `migrate` with temporal units pre-seeded (see discover).

**Gate semantics (backbone tail):**

- **Gate 1 → `migration_plan`** runs only when `generate` is done AND
  `recommendation_reviewed == true` (generate.md Step 5.5) AND entry point ∈ {migrate,
  build_deploy} AND the run is migration-eligible (generate.md Step 6) AND the user
  confirmed Gate 1. Otherwise resolve it: `not_applicable` (build_scratch / no migratable
  workload) or `skipped` (declined) — and advance.
- **Gate 2 → `poc`** runs only when `phases.poc == "in_progress"` (set when the user
  answers Gate 2 "yes" — asked in generate.md Step 7 or migration-plan.md Step 6) AND
  `recommendation_reviewed == true`. Any winning runtime (agentcore / ecs / eks / lambda /
  lambda_microvms) — the POC shape follows the verdict (poc.md Step 3 dispatch on
  `references/decision-refs/poc-shapes.md`). Gate 2 is only offered when `migration_plan`
  ∈ {completed, skipped, not_applicable} — or `in_progress` on build_deploy only (Stage 2
  failed/aborted; fallback POC from design.json per migration-plan.md failure handling);
  for entry point `migrate`, only when `migration_plan == "completed"` (the POC implements the
  plan) OR when the stage resolved `not_applicable` with `migration_plan_unavailable ==
  "engine_absent"` — a standalone deployment that does not bundle the migration engine, where
  Gate 2 is offered by migration-plan.md Step -1 and the POC is design-backed. A migrate-POC
  with no plan for any OTHER reason (the user declined) has nothing to implement.
- Persisting Gate 2 as `phases.poc = "in_progress"` BEFORE poc.md loads makes the
  confirmation resumable: if the session breaks between the "yes" and the load, the
  interpreter re-enters `poc` without re-asking. (A declared deviation from
  `INTERPRETER.md` § The interpreter loop step 5's gate-then-`in_progress` ordering — the
  user's confirmation is the entry event worth persisting.)

**Phase gate:** Do NOT load design.md / estimate.md / generate.md unless
`$RUN_DIR/.phase-status.json` exists and BOTH `phases.clarify == "completed"` AND
`phases.confirm == "completed"`. Confirm confirms the deployment model, the service
set, and (for a co_recommend tie) the user's `chosen_runtime` — Design and the diagram depend on
its `confirm.json` output, so it must not be skipped. If the user asks to skip Clarify or Pass 2,
refuse briefly and run it.

## State file (`.phase-status.json`)

```json
{
  "run_id": "0630-1430",
  "entry_point": "build_scratch",
  "audience": "technical",
  "current_phase": "clarify",
  "phases": {
    "intake": "completed",
    "discover": "skipped",
    "clarify": "in_progress",
    "confirm": "pending",
    "design": "pending",
    "estimate": "pending",
    "generate": "pending",
    "migration_plan": "pending",
    "poc": "pending"
  }
}
```

Status values: `pending` → `in_progress` → `completed`, plus `skipped`. Use read-merge-write:
read before each update, change only the advancing keys, keep prior phases.

`recommendation_reviewed` (top level, boolean) is set to `true` by generate.md Step 5.5 when
the user explicitly confirms they have seen the recommendation. Gate 1, Gate 2, and the
`migration_plan` / `poc` states all require it — no gate may be asked while it is absent.

`migration_plan` additionally uses `not_applicable` (build_scratch, or no migratable workload
detected). When Stage 2 runs, `migration_plan_ctx` is added at the top level:
`{"repo": "<abs path to target repo>", "migration_dir": "<abs path to .migration/<id>/>"}` —
Stage 3 reads gcp-to-aws artifacts ONLY via this recorded path, never by re-globbing.

## Files

| File                                                 | Purpose                                                                                                        |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `references/vendored/dsl/INTERPRETER.md`             | Vendored DSL execution contract (interpreter loop + gate protocol)                                             |
| `references/phases/intake/intake.md`                 | Entry point + technical background + open context                                                              |
| `references/phases/discover/discover.md`             | Lightweight code detection                                                                                     |
| `references/phases/clarify/clarify.md`               | Clarify orchestrator + answer mapping to scoring keys                                                          |
| `references/phases/clarify/clarify-technical.md`     | Technical-background question wording                                                                          |
| `references/phases/clarify/clarify-business.md`      | Business-background question wording                                                                           |
| `references/phases/confirm/confirm.md`               | Winner-specific follow-ups                                                                                     |
| `references/phases/design/design.md`                 | Assemble recommendation; Migrate handoff branch                                                                |
| `references/phases/estimate/estimate.md`             | Coarse cost magnitude                                                                                          |
| `references/phases/generate/generate.md`             | Layered recommendation doc + scaffolding                                                                       |
| `references/phases/migration-plan/migration-plan.md` | Stage 2: full migration plan via the sibling gcp-to-aws engine                                                 |
| `references/decision-refs/temporal.md`               | Temporal rules: Tier 1/2 tables, adapter, runbooks, commercials (consumed by discover/clarify/design/generate) |
| `references/decision-refs/poc-shapes.md`             | Per-runtime POC deploy shapes (ECS/EKS/Lambda/MicroVMs/Temporal)                                               |
| `references/decision-refs/*.md`                      | Runtime service cards, model defaults, freshness                                                               |
| `references/decision-refs/workload-classes.md`       | Deterministic verdicts for non-agent workload units (batch/service/io)                                         |
| `references/runtimes/*.json`                         | Runtime registry (read by scoring.py)                                                                          |
| `scripts/scoring.py`                                 | Deterministic scoring engine                                                                                   |
| `scripts/test_temporal_decision_refs.py`             | Content lock for the Temporal decision reference                                                               |
| `scripts/test_poc_shapes.py`                         | Content lock for the POC deploy shapes                                                                         |
| `scripts/test_workload_classes.py`                   | Content lock for workload-classes.md (verdicts table)                                                          |
| `scripts/test_unit_grouping.py`                      | Unit grouping + pattern matching (workload-class assignment)                                                   |
| `scripts/test_collapse_invariant.py`                 | Collapse-invariant ordering enforcement (A→B implies [B] ⊆ [A] outputs)                                        |

## Maturity and readiness contract

Intake persists `target_maturity` (`prototype`, `private_beta`, or `production`) in run state. Clarify carries it and the readable `readiness` record into `answers.json`. Current-run verification evidence remains exclusively in the sibling `$RUN_DIR/current-run-verifications.json` artifact: never copy it into `seed.json` or `answers.json`. Design and Generate may consume that artifact only after validating its schema and matching `run_id`, and may carry forward verified outcomes but not the raw evidence records. Load `references/decision-refs/maturity-readiness.md` whenever target maturity is selected. A cached volatile fact may inform discovery, but only a record verified in this run can make a verification-required constraint final; otherwise the score remains provisional with deferred verification requirements.

From awslabs/startups at 60e439e, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

• SKILL.md17 KB · 808e5bb40abc
• references/
• decision-refs/
• agentcore-platform.md8.1 KB · fd6a6a94f658
• agentcore.md5.8 KB · 70d6ea0a7298
• batch.md2.3 KB · 240f2977dab7
• cost-levers.md1.9 KB · 587a05f8b73e
• ecs.md1.3 KB · 487c32652edf
• eks.md1.1 KB · 90453618b244
• freshness.md12 KB · 7fca0fbb85d0
• lambda-microvms.md2.0 KB · c85d145904f3
• lambda.md1.1 KB · d77236097f50
• managed-alternatives.md793 B · 2bdb983cfc8f
• maturity-readiness.md2.8 KB · 347aff7d05db
• model-selection.md4.3 KB · 36f3f92b5159
• poc-shapes.md16 KB · db6da4d5e663
• temporal.md18 KB · 65e4a6587401
• workload-classes.md2.2 KB · 4339824f9dad
• diagram/
• build-diagram.md5.3 KB · a66ed884dd78
• handoff/
• handoff-migration.md2.2 KB · 34ceab76bc08
• models/
• anthropic-bedrock-2026-07-21.json6.6 KB · b7fd4153fff6
• openai-bedrock-2026-08-21.json17 KB · 03c029e77c05
• output-templates/
• recommendation-doc.md5.6 KB · 9d4690f855df
• phases/
• add-capabilities/
• add-capabilities-assemble.md951 B · 34bb66033c12
• add-capabilities.md4.7 KB · a256b583bea7
• clarify/
• clarify-assemble.md1.5 KB · a02ac7688a96
• clarify-business.md3.4 KB · f50e3113bddc
• clarify-technical.md2.8 KB · 5fbf761908a1
• clarify.md27 KB · 23f2816049bb
• confirm/
• confirm-assemble.md1.0 KB · b8e36b5f9dc3
• confirm.md15 KB · fa24d8dd315e
• design/
• design-assemble.md1.8 KB · c677b85ee4b9
• design.md30 KB · 6194758a2930
• discover/
• discover-assemble.md1.3 KB · 9d8c40412474
• discover.md10 KB · 28df42ada6ee
• estimate/
• estimate-assemble.md780 B · db4a73a86a64
• estimate.md21 KB · 37fd64223a70
• generate/
• generate-assemble.md1.1 KB · af21f507beff
• generate-report.md47 KB · 1b4d9e0d0f70
• generate.md16 KB · e14a75cbd8e9
• intake/
• intake-assemble.md991 B · 921aa7cd0928
• intake.md5.8 KB · be328ee51bd4
• migration-plan/
• migration-plan-assemble.md1.2 KB · 4a6edc36b3a7
• migration-plan-gcp-constraints.md3.9 KB · 7b67fd386972
• migration-plan.md31 KB · 5ea6a5df1a53
• model-recommend/
• model-recommend-assemble.md872 B · 6c7ff3267c3a
• model-recommend.md15 KB · 73b05656ce30
• poc/
• poc-assemble.md1.0 KB · 2b22e0b10800
• poc-report.md13 KB · cefbcd64dd70
• poc.md49 KB · 011bcd9e6a43
• report-help-banner.md6.1 KB · 0e813ec1b73a
• report-shell.md13 KB · 602885aef716
• runtimes/
• agentcore.json5.3 KB · 189f495b0ad7
• ecs.json1.5 KB · 3809262586ad
• eks.json1.5 KB · bd9ca4a2dd28
• lambda.json2.4 KB · bf612cd0e555
• lambda_microvms.json3.4 KB · f8462bd1de78
• vendored/
• README.md1.2 KB · 8cdd35333379
• dsl/
• INTERPRETER.md51 KB · 4b7461610bd7
• scripts/
• anthropic_model_recommendation.py29 KB · 5e9b3e97f748
• build_diagram.py22 KB · 891719fb7918
• model_recommendation.py7.9 KB · 75a46ae2ab2b
• openai_model_recommendation.py41 KB · 190f626c2c1a
• pyproject.toml170 B · c617718c4ac9
• schemas/
• current-run-verifications.json1.2 KB · 3c44b706da9d
• model-recommendation-input.json5.5 KB · 99f07fffb1c5
• model-recommendation.json13 KB · a4d1565e12db
• model-verification.json2.6 KB · f0d385e0a14c
• scoring-result.json3.5 KB · 91c88192a021
• seed.json5.7 KB · 69019731d340
• score_units.py3.0 KB · 0fb8d6f9c78b
• scoring.py17 KB · a144063950b9
• set_agentcore_platform.py3.7 KB · 3a391bbcf50d
• test_agentcore_platform.py19 KB · 8f82627e6c54
• test_build_diagram.py22 KB · 881b7ca27e67
• test_collapse_invariant.py2.1 KB · 785ae029a4a0
• test_cost_levers.py1.8 KB · 684d79c52d98
• test_model_recommendation.py13 KB · a7603db29f3a
• test_openai_model_recommendation.py26 KB · 9c7a582b73a4
• test_poc_shapes.py15 KB · c84fc61ece67
• test_scoring.py36 KB · bb34f55deca3
• test_temporal_decision_refs.py7.6 KB · 366204881b43
• test_unit_grouping.py73 KB · c25c48a97ab9
• test_verify_model_path.py8.3 KB · 91f949587321
• test_workload_classes.py5.4 KB · 344d797f053e
• uv.lock100 KB · d5196659551b
• verify_model_path.py8.2 KB · 5c86ef418cde

85 files, 1.0 MB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.