kirodotdev · ayn-builds · Aug 11, 2026
diff --git a/migration-to-aws/POWER.md b/migration-to-aws/POWER.md
diff --git a/migration-to-aws/mcp.json b/migration-to-aws/mcp.json
@@ -19,6 +19,10 @@
         "get_pricing_attribute_values",
         "get_pricing"
       ]
+    },
+    "temporal-docs": {
+      "type": "http",
+      "url": "https://temporal.mcp.kapa.ai"
     }
   }
 }
diff --git a/migration-to-aws/steering/INTERPRETER.md b/migration-to-aws/steering/INTERPRETER.md
diff --git a/migration-to-aws/steering/agent-advisor-add-capabilities-assemble.md b/migration-to-aws/steering/agent-advisor-add-capabilities-assemble.md
@@ -0,0 +1,20 @@
+---
+_assemble: assemble-add-capabilities
+_of_phase: add-capabilities
+_reads:
+  - current runtime + selected capabilities + native-vs-BYO choices (collected inline in agent-advisor-add-capabilities.md)
+_produces:
+  - capabilities-recommendation.md
+---
+
+# Add Capabilities — Assemble the recommendation
+
+> **Assembler unit.** The Add Capabilities branch asks the current runtime and
+> the capabilities needed, resolves native-vs-bring-your-own per capability,
+> verifies volatile facts, and writes `capabilities-recommendation.md` inline
+> within `agent-advisor-add-capabilities.md` (Step 5). This unit records the artifact-level
+> contract for the branch: it is the single creator of
+> `capabilities-recommendation.md`, and its postconditions (declared on the
+> phase) are the branch's completion gate. This is a self-contained sidebar
+> branch — no runtime scoring, no handoff; it ends after writing the file. See
+> `agent-advisor-add-capabilities.md` § Step 5 for the document contents.
diff --git a/migration-to-aws/steering/agent-advisor-add-capabilities.md b/migration-to-aws/steering/agent-advisor-add-capabilities.md
@@ -0,0 +1,77 @@
+---
+_phase: add-capabilities
+_title: "Add Capabilities (branch)"
+_kind: sidebar
+_requires_phase: intake
+_trigger: { _when: "intake is done AND entry_point == add_capabilities" }
+_input: workspace
+_assemble:
+  _file: agent-advisor-add-capabilities-assemble.md
+_produces:
+  - capabilities-recommendation.md
+_preconditions:
+  - _check_phase_completed: intake
+    _on_failure: _halt_and_inform
+_postconditions:
+  - _check_file_exists: capabilities-recommendation.md
+    _on_failure: _halt_and_inform
+  - _assert: "capabilities-recommendation.md lists the current runtime, the services to enable (with what/why + Identity-is-free), the native-vs-bring-your-own outcome per capability, integration pointers for the current runtime, a suggested enablement order, and the freshness footer (MCP-verified vs cached)"
+    _on_failure: _halt_and_inform
+---
+
+# Phase: Add Capabilities (branch)
+
+Reached when the Turn-1 entry point is `add_capabilities`: the user already runs
+an agent on AWS and wants to add AgentCore services. **No runtime scoring** —
+services run on any runtime. This is a self-contained branch: it does NOT pass
+through Clarify / Confirm / Design / Estimate / Generate.
+
+## Step 0 — Create the run directory
+
+Generate a run id from the current time as `MMDD-HHMM`. Create the run directory under the
+**user's current working directory** (run `pwd` and anchor to it) — NOT the plugin install tree:
+`<cwd>/.agent-advisor/<run_id>/`, plus `<cwd>/.agent-advisor/.gitignore` containing `*` (so run
+state is never committed). Call this directory `$RUN_DIR`.
+
+## Step 1 — Current runtime
+
+Ask which runtime they run on now: AgentCore / ECS / EKS / Lambda / other. (If the user already
+stated it in their opening message, skip this question.)
+
+## Step 2 — Capabilities needed (multi-select)
+
+Identity, Gateway, Memory, Policy, Observability, Managed KB, Code Interpreter, Browser,
+Web Search, Sandbox. For each selected, load the relevant section of
+`agent-advisor-agentcore.md`.
+
+## Step 3 — Native vs bring-your-own
+
+If they already use a third-party tool for a capability (Tavily/Pinecone/Browserbase/etc),
+present: switch to AgentCore native, or keep existing and connect via Gateway.
+
+## Step 4 — Volatile facts
+
+Load `agent-advisor-freshness.md`. This
+branch has no winning runtime profile, so verify the relevant "Hard limits" facts from
+`agent-advisor-agentcore.md` directly (per agent-advisor-freshness.md Procedure step 1). Follow its anti-fabrication rule:
+only list a fact as MCP-verified if you actually called the MCP this run; otherwise it's cached.
+
+## Step 5 — Output
+
+Write the recommendation to `$RUN_DIR/capabilities-recommendation.md` (so the user can keep and
+share it — consistent with the main skill's `recommendation.md`). Include:
+
+- **Current runtime** and the capabilities requested.
+- **Services to enable** — for each: what it does, why it fits, and (Identity) that it's free.
+- **Native vs bring-your-own** outcome per capability (from Step 3): which go AgentCore-native
+  and which stay third-party fronted via Gateway.
+- **Integration on the current runtime** — concrete setup pointers (IAM/task-role changes, SDK
+  calls, endpoints) for the user's runtime; note these services are standalone and require no
+  runtime/compute change.
+- **Suggested enablement order.**
+- **Freshness footer** (per `agent-advisor-freshness.md`: generation date, which facts were MCP-verified vs
+  cached).
+
+Then give a short in-chat summary and point the user to `$RUN_DIR/capabilities-recommendation.md`.
+This branch does not score runtimes or hand off — it ends here. Set
+`phases.add_capabilities` = completed (state → `complete`).
diff --git a/migration-to-aws/steering/agent-advisor-agentcore.md b/migration-to-aws/steering/agent-advisor-agentcore.md
@@ -0,0 +1,45 @@
+# AgentCore Runtime — Service Card
+
+## One-liner
+
+Serverless, agent-purpose-built runtime: managed session routing, true session
+isolation, built-in identity, $0 billing during I/O wait.
+
+## Best for
+
+Short agent sessions with high LLM I/O wait, human-in-the-loop, multi-tenant
+isolation, minimal ops, cross-session memory, high-volume session launch.
+
+## Hard limits (verify via MCP — volatile)
+
+- Session cap: 8h (extending — verify)
+- Compute cap: 2 vCPU / 8 GB (hard)
+- FedRAMP: authorization in progress (WIP) — verify current status; NOT a hard block
+
+## Deployment models
+
+- **Harness** — no-code, config-driven; single agent, greenfield, OpenAI Assistants migration.
+- **Framework on Runtime** — Strands / LangGraph / CrewAI / custom; multi-agent, complex orchestration.
+
+## Six dimensions
+
+- Identity: built-in (free), OAuth via enhanced Identity
+- Observability: auto OTEL traces
+- Guardrails: Bedrock Guardrails + Policy (Cedar) for high-risk actions
+- Scaling: 5,000 concurrent sessions, 25 TPS launch (adjustable)
+- Tool/Gateway: Gateway for external APIs / MCP
+- Protocols: HTTP/1.1, WebSocket; MCP, A2A
+
+## Conditional services (relevant but not always)
+
+- Payments: for agents that pay / transact on a user's behalf — surface only for
+  transactional / high-risk-action workloads.
+- Registry: agent/tool discovery and multi-agent orchestration — surface only for multi-agent setups.
+
+## Tradeoffs
+
+2 vCPU / 8 GB ceiling; no process-level suspend (Session Storage persists files only).
+
+## Serving & security notes
+
+Entry: POST /invocations + GET /ping. IAM: execution role with InvokeModel + Gateway/Registry/SessionStorage permissions as needed. Networking: public service endpoints over TLS; VPC endpoints only if policy demands.
diff --git a/migration-to-aws/steering/agent-advisor-batch.md b/migration-to-aws/steering/agent-advisor-batch.md
@@ -0,0 +1,45 @@
+# AWS Batch (Fargate) — Service Card
+
+## One-liner
+
+Managed batch job execution, scale-to-zero between runs, no always-on compute.
+
+## Best for
+
+Scheduled or event-triggered batch work (`batch` workload class, W2): long-running jobs
+(> 15 min), large fan-out over a work list, latency-tolerant processing that idles between
+runs.
+
+## Hard limits
+
+Not for interactive/synchronous request-response (no long-lived endpoint). Jobs run to
+completion and exit — there is no persistent server to receive traffic.
+
+## Six dimensions
+
+> The Bedrock-related items below describe a job that CALLS a model. A **model-less** batch job
+> (`model_recommendation: null` — a plain compute/data job) omits `bedrock:InvokeModel`, Bedrock
+> Guardrails, and the direct-Bedrock-call line; keep only its service-specific permissions (e.g.
+> S3). Design/Generate strip the Bedrock items for such a unit (see agent-advisor-design.md model-less rule).
+
+- Identity: IAM — job execution role + job role with `bedrock:InvokeModel` (model-bearing jobs only) + service-specific permissions
+- Observability: CloudWatch Logs per job; job state via the Batch console/API
+- Guardrails: bring-your-own + Bedrock Guardrails (when the job calls a model)
+- Scaling: managed compute environment scales to zero between jobs; pay per job-second
+- Tool/Gateway: not applicable (no agent runtime); a model-bearing job calls Bedrock directly
+- Protocols: none exposed — jobs are submitted, not served
+
+## Tradeoffs
+
+No inbound endpoint, so unsuitable for request-driven work; cold start per job (compute
+environment spins up). Wins on cost for spiky/scheduled batch because idle cost is zero.
+Hands off to migration-to-aws for compute-layer config.
+
+## Serving & security notes
+
+Entry: no served endpoint — jobs are SUBMITTED to a job queue (SubmitJob), run on a Fargate
+compute environment, and exit. IAM: job execution role (pull image, write logs) + job role with
+service-specific permissions scoped to the job's needs, PLUS `bedrock:InvokeModel` ONLY when the
+job actually calls a model (a model-less batch job omits it). Networking: jobs run in the default
+VPC's subnets with egress to S3 (and to Bedrock only for a model-calling job) over TLS; no ALB,
+no inbound listener; VPC endpoints only if policy demands.
diff --git a/migration-to-aws/steering/agent-advisor-build-diagram.md b/migration-to-aws/steering/agent-advisor-build-diagram.md
@@ -0,0 +1,102 @@
+# Build the architecture diagram
+
+Produces `$RUN_DIR/diagram.md` (a Mermaid block + ASCII fallback). This sub-step runs at TWO
+points in the flow, and which path applies depends on WHEN it runs:
+
+1. **During Generate** — the migration plan does not exist yet (Gate 1 comes AFTER Generate).
+   Always use **Path 1** (generic selection diagram).
+2. **After Migration Plan completes** — `aws-design-ai.json` now exists. Re-generate the
+   diagram using **Path 2** (plan-backed app architecture), overwrite `$RUN_DIR/diagram.md`,
+   and re-embed it into `recommendation.md` §4. This is invoked from agent-advisor-migration-plan.md's
+   final step, not from Generate.
+
+## Which path
+
+- **Path 1 — generic selection diagram** (deterministic composer). Shows the recommended
+  runtime + model + attached services, independent of any specific app. Used during Generate,
+  and as the only diagram when no migration plan is produced.
+- **Path 2 — plan-backed app architecture** (hand-composed). Reflects the user's ACTUAL app
+  components as they map onto AWS. Used only after Migration Plan completes
+  (`migration_plan_ctx` present AND `phases.migration_plan == "completed"` AND
+  `aws-design-ai.json` readable).
+
+## Path 1 — Generic selection diagram (deterministic composer)
+
+```bash
+uv run $STEERING/agent-advisor-build-diagram.py \
+  $RUN_DIR/scoring-result.json $RUN_DIR/confirm.json $RUN_DIR/design.json
+```
+
+This writes `$RUN_DIR/diagram.md` and prints `RESULT=ok RUNTIME=<id>`. If `confirm.json` is
+absent (e.g. co_recommend not yet resolved), the composer treats it as empty. Do not
+hand-edit — it is generated so it stays consistent with the scoring result.
+
+The composer renders the correct topology: `User → Runtime → Bedrock model` is the primary
+(solid) data flow; AgentCore services are cross-cutting capabilities grouped in a subgraph
+and attached with a dotted edge — NOT downstream call targets.
+
+## Path 2 — Plan-backed app architecture (hand-composed from the migration plan)
+
+The generic composer only knows runtime + model + services — it cannot show the app's real
+shape. When a migration plan exists, compose the diagram from the plan instead so it depicts
+what the user is actually deploying.
+
+**Read** `<migration_plan_ctx.migration_dir>/aws-design-ai.json` (path from
+`.phase-status.json`). Use these fields:
+
+- `ai_architecture.code_migration.primary_pattern` / `framework` — the app's framework
+  (e.g. langchain, direct SDK) and integration pattern.
+- `ai_architecture.code_migration.agentcore_entrypoint` — the serving contract
+  (`/invocations` + `/ping`) if present.
+- `ai_architecture.bedrock_models[]` / `design_blocks[]` — source model → target Bedrock
+  model (the provider swap).
+- `ai_architecture.services_to_migrate[]` — what each existing component maps to on AWS.
+- `$RUN_DIR/confirm.json` `agentcore_services` — the AgentCore services to enable.
+- The app's UI/interface layer from `$RUN_DIR/context-signals.json` (`ui_layer`, e.g.
+  chainlit) or the migration plan's file list.
+
+**Compose the Mermaid diagram to show the REAL components and their relationships**, using
+the same topology discipline as Path 1:
+
+- **Primary request flow (solid edges):** User → the app's entry surface (the runtime hosting
+  the migrated app + its `/invocations` entrypoint) → the app's orchestration layer (e.g.
+  LangChain) → the Bedrock target model. Show the provider swap explicitly — label the model
+  node with the migrated target (e.g. "Bedrock: Claude Sonnet 4.6") and note the source it
+  replaced where useful (e.g. "was: OpenAI gpt-3.5-turbo").
+- **State / memory (solid edge to a store):** if the app has conversation memory, show it as
+  its own node mapped to its AWS target (e.g. in-process `ConversationBufferWindowMemory` →
+  AgentCore Memory, per `services_to_migrate`), connected to the orchestration layer.
+- **AgentCore services (dotted, grouped):** the enabled services from `confirm.json` as a
+  subgraph attached to the runtime with a dotted edge — same as Path 1, cross-cutting
+  capabilities, not call targets. Do NOT duplicate the Memory node here if it's already shown
+  as a state store on the primary flow — show it once, on the flow, and note it's also an
+  AgentCore service.
+- **UI note:** if the source app has a browser UI (e.g. Chainlit) that becomes local-dev-only
+  after migration (the runtime serves `/invocations`, not a browser UI), represent that
+  honestly — a dashed/annotated "Chainlit UI (local dev)" node, not on the production request
+  path.
+
+Keep it readable — the real components (UI, entry/runtime, orchestration, model, memory/state,
+services) without inventing infrastructure the plan doesn't call for. Write BOTH a
+`flowchart TD` Mermaid block AND an ASCII fallback (same structure), in the same `diagram.md`
+format Path 1 emits:
+
+````markdown
+```mermaid
+flowchart TD
+    ...
+```
+
+<details><summary>ASCII (plain-text fallback)</summary>
+
+```
+...
+```
+
+</details>
+````
+
+## Step 2 (both paths) — Embed into the recommendation
+
+Insert the full contents of `$RUN_DIR/diagram.md` into Section 4 ("Architecture diagram") of
+`$RUN_DIR/recommendation.md`.