aws-transform

What this skill does

# AWS Transform

## Overview

Domain expertise for migrating and modernizing workloads using AWS Transform. Covers .NET Framework to .NET 8/10, mainframe COBOL to Java, VMware to EC2, SQL Server to Aurora PostgreSQL, and custom code transformations (Java, Python, Node.js version upgrades, SDK migrations). Orchestrates assessment, planning, and execution through Managed Agents and AWS Transform CLI with human-in-the-loop checkpoints.

## Prerequisites

This skill requires the AWS Transform MCP server (`aws-transform-mcp`). Configure it in your agent's MCP settings:

```json
{
  "mcpServers": {
    "aws-transform-mcp": {
      "command": "uvx",
      "args": [
        "awslabs.aws-transform-mcp-server@latest"
      ]
    }
  }
}
```

The AWS Transform CLI is also required for custom transformations. Install via:

```bash
curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash
```

## Mandatory workflow

Follow these phases in order. Do NOT skip ahead. Authentication is handled just-in-time — only when a chosen action actually needs it. Do NOT probe auth before the user has declared an intent.

```
Resume        → Check .atx/context.json
Intent        → Ask user what they want to do
Discovery     → Scan workspace + query available agents
Scope         → User selects what to modernize (GATE 1)
Assessment    → Run workload assessment (NOT optional)
Requirements  → Draft from assessment report
Approval      → User approves requirements (GATE 2)
Tasks         → Generate tasks.md
Execute       → Run transforms, monitor, review diffs
```

**Discovery finds opportunities. Assessment produces detailed findings. Requirements come from the assessment — NOT from discovery.**

You MUST NOT create requirements without an assessment report.
You MUST NOT start execution without requirements.md and tasks.md.

## Resuming a prior session

Check for `.atx/context.json` (workspace-relative). NEVER read `~/.aws/atx/kiro-power-context.json`.

**This check is an internal bookkeeping operation. The user must never see it happen.** Do not announce the check, do not narrate what you are doing. No phrases like "checking for prior sessions", "let me check", "check for a prior session", "context file". On a fresh install, the first visible output must be the intent question — no preamble of any kind.

- **No context found:** Proceed directly to intent. Produce no user-visible output for this step.
- **Context found:** If the context has an active job (`assessment.jobId` or entries in `execution.activeJobIds`), try to refresh live state from the service, but do so invisibly:
  - **Check auth first** (no-auth-required). If sign-in is NOT configured, skip the refresh entirely — do not attempt service calls. Use local context only.
  - **If sign-in is configured**, fetch each resource your resume message depends on — at minimum the job itself and all pending user tasks. Surface every pending task to the user; do not cherry-pick one and omit the others. `BLOCKING` HITL tasks hold up progress even when the job status is active; `NON_BLOCKING` tasks still need attention but don't stall the job. Name every pending task; flag blocking ones. Don't infer one resource from another.
  - **If any call fails** for any reason, silently fall back to local context. **Do NOT reveal your reasoning about the refresh to the user** — no "sign-in isn't configured so I'll skip", no "the service isn't reachable". The user should see only the resume message. Do NOT demand auth or block the flow.

  Then tell the user about their prior session. Frame the offer explicitly as a **continuation** of that same session — not a new one. The message should make clear:
  - This is the specific session they previously worked on. Mention the phase reached, workspace/job identifiers if relevant.
  - **Refresh succeeded** → speak in present tense about live state ("your assessment job is running", "I need your input on X to continue"). If there is a pending HITL task, surface it — don't bury it under "your job is running."
  - **Refresh failed or was skipped** → use prior-session framing: "last time", "when you paused", "previously", "your last session had finished assessment." Do NOT present-tense claims about job state — local context may be stale. Offer sign-in as the path to current status ("sign in to see the latest status"), not as a gate.
  - **Resume** = continue where you left off, reusing the existing assessment report, workspace, and prior progress.
  - **Start fresh** = discard the prior session (local artifacts deleted) and begin a brand-new migration.

  Use language like "continue where you left off" or "pick up from where you stopped" — not ambiguous phrasing like "start a similar session." If user chooses start fresh, delete `.atx/context.json`, `.atx/discovery.json`, `.atx/assessment-report/`, and `.atx/specs/`, then proceed to intent. Otherwise follow the resume logic in [workflow reference](references/workflow.md).

## Determining user intent

Ask the user: "What would you like to focus on?" The first user-visible action in this phase is the question — no auth-probing tool calls precede it, no auth lecture precedes it.

With projects: [Discover This Workspace] [Browse My Jobs] [Start a Specific Transform]
No projects: [Browse My Jobs] [Open a Project Folder] [Start from Scratch]

**Just-in-time auth.** Once the user picks an intent, the next tool that action needs may require auth. If so, prompt for auth then, framed around the action the user just chose ("to browse your jobs, sign in to AWS Transform"). Which auth each MCP tool needs is reported by the MCP server — read it from the tool's description, `get_status`, or the error the tool returns. CLI transforms use AWS credentials only — do NOT prompt for sign-in for CLI-only intents, even when sign-in is unconfigured. If the user picks something that needs no service call (e.g., "Open a Project Folder"), do not probe auth.

See [auth reference](references/auth.md) for the MCP-vs-CLI auth split and how to present sign-in options.

## Discovery

Fast scan (~10 sec). Three things happen in parallel:

1. **Scan the workspace** — detect languages, frameworks, file types, and dependencies present in the project.
2. **Query available agents** — call `list_resources` with `resource: "agents"` (MCP). Skip if sign-in is not configured or the user's intent is CLI-only. This is a paginated API — fetch all pages to get the complete set. The results contain two levels:
   - **Orchestrator agents** — top-level agents you create jobs with. Each orchestrator may have sub-agents that provide deeper workload-specific capabilities.
   - **Sub-agents** — invoked through their orchestrator, not directly. They represent specialized skills within a workload type.
   - Some agents may not belong to a known orchestrator — treat these as standalone capabilities.
3. **List available transformation definitions** — call `atx custom def list` (CLI) to get the current set and what they transform. Skip if CLI is not available or the user's intent is MCP-only.

For the "Discover This Workspace" intent, Discovery is where sign-in is first required (other intents like "Browse My Jobs" need sign-in even earlier, per the just-in-time rule — handle those there). If `list_resources` returns NOT_CONFIGURED, prompt the user to sign in for the auth system needed — do not demand both.

Then **match** workspace signals against orchestrator capabilities and available transformation definitions. Before selecting an orchestratorAgent for any workload, read the matched workload's reference file — it may specify the exact agent to use. Save the matched results to `.atx/discovery.json` — include the orchestrator → sub-agent hierarchy so later steps know what deeper capabilities are available.

See [workflow reference](references/workflow.md) for the workspace scanning framework.

**Discovery is NOT assessment.** Discovery identifies opportunities and matches them to available agents. Asse