aws-transform — Skillopedia

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 ( ). Configure it in your agent's MCP settings: The AWS Transform CLI is also required for custom transfor…

\n\n# Copy each zip to the managed source bucket\naws s3 sync s3://user-bucket/repos/ s3://${SOURCE_BUCKET}/repos/ --exclude \"*\" --include \"*.zip\"\n```\n\nThen submit a batch job with one job per zip, each pointing to\n`s3://${SOURCE_BUCKET}/repos/\u003cfilename>.zip`. The container handles zip extraction\nautomatically. See [custom-multi-transformation](custom-multi-transformation.md) for batch submission.\nThe managed source bucket has a 7-day lifecycle — copied zips auto-delete.\n\n**Local mode:** Download and extract each zip locally:\n\n```bash\nmkdir -p ~/.aws/atx/custom/atx-agent-session/repos\naws s3 sync s3://user-bucket/repos/ ~/.aws/atx/custom/atx-agent-session/repos/ --exclude \"*\" --include \"*.zip\"\nfor zip in ~/.aws/atx/custom/atx-agent-session/repos/*.zip; do\n name=$(basename \"$zip\" .zip)\n unzip -qo \"$zip\" -d \"$HOME/.aws/atx/custom/atx-agent-session/repos/${name}-$SESSION_TS/\"\ndone\n```\n\nUse the extracted directories as `\u003crepo-path>` for local execution. Standard local\nmode limits apply (max 3 concurrent repos).\n\n#### Private Repository Detection (Remote Mode)\n\n**Always ask the user** — do NOT try to determine repo visibility yourself. Never\nattempt to clone, curl, or probe a URL to check if it's public or private. Simply\nask the user. As soon as the user provides git URLs and remote mode is selected\n(or likely), ask:\n\n> \"Are any of these repositories private? If so, the remote container needs\n> credentials to clone them — I'll walk you through the setup.\"\n\nDo NOT skip this question. Do NOT try to infer visibility by attempting a clone,\ncurl, or any other network request. Just ask.\n\nIf the user confirms repos are private, determine the credential type based on URL format:\n\nFirst, resolve the region (use for all Secrets Manager commands below):\n\n```bash\nREGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}}\nREGION=${REGION:-us-east-1}\n```\n\n**For HTTPS URLs** — check whether a GitHub PAT is already configured:\n\n```bash\naws secretsmanager describe-secret --secret-id \"atx/github-token\" --region \"$REGION\" 2>/dev/null \\\n && echo \"CONFIGURED\" || echo \"NOT_CONFIGURED\"\n```\n\nIf CONFIGURED, ask the user: \"A GitHub PAT is already stored. Would you like to\nkeep using it, or replace it with a new one?\" If they want to replace it, tell\nthem to run:\n\n```\naws secretsmanager put-secret-value --secret-id \"atx/github-token\" --region \"$REGION\" --secret-string \"YOUR_TOKEN_HERE\"\n```\n\nIf NOT_CONFIGURED, explain what's needed and tell the user to run the create command:\n\n> \"Private HTTPS repos need a GitHub Personal Access Token (PAT) stored in AWS\n> Secrets Manager. The remote container fetches it at startup to clone your repos.\n> The token stays in your AWS account — you can delete it anytime.\n>\n> The PAT needs the `repo` scope for private repositories. Create one at\n> https://github.com/settings/tokens and then run:\n>\n> ```\n> aws secretsmanager create-secret --name \"atx/github-token\" --region \"$REGION\" --secret-string \"YOUR_TOKEN_HERE\"\n> ```\n>\n> Delete anytime: `aws secretsmanager delete-secret --secret-id atx/github-token --region \"$REGION\" --force-delete-without-recovery`\"\n\nDo NOT ask the user to paste their token in chat. They run the command themselves.\nWait for the user to confirm it's done, then verify:\n\n```bash\naws secretsmanager describe-secret --secret-id \"atx/github-token\" --region \"$REGION\" 2>/dev/null \\\n && echo \"CONFIGURED\" || echo \"NOT_CONFIGURED\"\n```\n\n**For SSH URLs** (`git@...` or `ssh://...`) — check whether an SSH key is configured:\n\n```bash\naws secretsmanager describe-secret --secret-id \"atx/ssh-key\" --region \"$REGION\" 2>/dev/null \\\n && echo \"CONFIGURED\" || echo \"NOT_CONFIGURED\"\n```\n\nIf CONFIGURED, ask the user: \"An SSH key is already stored. Would you like to\nkeep using it, or replace it with a new one?\" If they want to replace it, tell\nthem to run:\n\n```\naws secretsmanager put-secret-value --secret-id \"atx/ssh-key\" --region \"$REGION\" --secret-string \"$(cat \u003cpath-to-your-private-key>)\"\n```\n\nIf NOT_CONFIGURED, explain what's needed and tell the user to run the create command:\n\n> \"SSH repos need an SSH private key stored in AWS Secrets Manager. The remote\n> container fetches it at startup to clone your repos.\n>\n> Run:\n>\n> ```\n> aws secretsmanager create-secret --name \"atx/ssh-key\" --region \"$REGION\" --secret-string \"$(cat \u003cpath-to-your-private-key>)\"\n> ```\n>\n> Delete anytime: `aws secretsmanager delete-secret --secret-id atx/ssh-key --region \"$REGION\" --force-delete-without-recovery`\"\n\nDo NOT ask the user to paste their SSH key in chat. They run the command themselves.\n\nFor local mode, private repo credentials are not needed — the user's local git\nconfig handles authentication. Skip this check entirely for local mode.\n\n### Discover Transformation Definitions (Silent)\n\nRun silently — do NOT show output to user:\n\n```bash\natx custom def list --json\n```\n\nInspect the JSON output directly to build an internal lookup of available transformation definitions.\nDo NOT pipe the output to python, jq, or other parsing scripts — read the JSON\nyourself. Never hardcode transformation definition names.\n\n#### Creating a New Transformation Definition\n\n**User explicitly asks to create a transformation definition**, or **no existing transformation definition matches the user's goal**:\n\nIf no match, confirm with the user first:\n\n> \"I didn't find an existing transformation definition that covers [describe the user's goal]. Would\n> you like to create a new one?\"\n\nIf the user confirms (or explicitly asked), open a terminal and launch `atx -t`\nfor them:\n\n```bash\natx -t\n```\n\nRun this in a new terminal so the user can interact with it directly. Then tell\nthe user:\n\n> \"I've opened a terminal with `atx -t` — describe the transformation you want\n> to build (e.g., 'migrate log4j to SLF4J') and AWS Transform will walk you through it.\n> Come back here once it's published and I'll pick it up automatically.\"\n\nAfter the user returns, re-run `atx custom def list --json` to pick up the newly\npublished transformation definition and continue with the normal workflow.\n\n### Inspect Each Repository\n\nPerform lightweight inspection only — check config files for key signals:\n\n| Signal | Files to Check | Likely Transformation Type |\n| --------------- | ------------------------------------------------------------------------------------- | -------------------------- |\n| Python version | `.python-version`, `pyproject.toml`, `setup.cfg`, `requirements.txt` | Python version upgrade |\n| Java version | `pom.xml` (`\u003cjava.version>`), `build.gradle` (`sourceCompatibility`), `.java-version` | Java version upgrade |\n| Node.js version | `package.json` (`engines.node`), `.nvmrc`, `.node-version` | Node.js version upgrade |\n| Python boto2 | `import boto` (NOT boto3) | boto2->boto3 migration |\n| Java SDK v1 | `com.amazonaws` imports, `aws-java-sdk` in pom.xml | Java SDK v1->v2 |\n| Node.js SDK v2 | `\"aws-sdk\"` in package.json (NOT `@aws-sdk`) | JS SDK v2->v3 |\n| x86 Java | `x86_64`/`amd64` in Dockerfiles, build configs | Graviton migration |\n\nCross-reference detected signals against transformation definitions from the discovery step. Only match transformation definitions that\nactually exist in the user's account.\n\nSee [custom-repo-analysis](custom-repo-analysis.md) for full detection commands.\n\n### Present Match Report\n\nFormat:\n\n```\nTransformation Match Report\n=============================\nRepository: \u003cname> (\u003cpath>)\n Language: \u003clang> \u003cversion>\n Matching transformation definitions:\n - \u003ctd-name> — \u003cdescription>\n\nSummary: N repos analyzed, M have applicable transformations (T total jobs)\n```\n\nPresent the match report and wait for user confirmation before proceeding.\nDo NOT start any transformation without explicit user consent.\n\n### Collect Configuration\n\nAsk the user for any additional plan context (e.g., target version for upgrade transformation definitions).\nThis is mandatory — always ask, even if the transformation definition doesn't strictly require config.\nThe user may have preferences or constraints you don't know about.\nSkip only if the user explicitly says no additional context is needed.\n\n### Verify Runtime Compatibility (Remote and Local)\n\n#### Remote Mode\n\n**Infrastructure check:** To verify whether remote infrastructure is deployed, use CloudFormation — do NOT check individual Lambda functions by name:\n\n```bash\naws cloudformation describe-stacks --stack-name AtxInfrastructureStack \\\n --query 'Stacks[0].StackStatus' --output text || echo \"NOT_DEPLOYED\"\n```\n\nBefore submitting remote jobs, determine whether the pre-built image covers the\ntarget runtime or if a custom Docker build is needed.\n\n**Pre-built image includes:**\n\n- **Java**: 8, 11, 17, 21, 25 (Amazon Corretto) with Maven and Gradle 9.4\n- **Python**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 (dnf + pyenv)\n- **Node.js**: 16, 18, 20, 22, 24 (nvm) with yarn, pnpm, TypeScript, ts-node\n- **Build tools**: gcc, g++, make, patch\n- **CLI tools**: AWS CLI v2, AWS Transform CLI, git, jq, curl, unzip, tar\n- **OS**: Amazon Linux 2023 (x86_64)\n\n**Decision logic:**\n\n1. Based on the transformation requirements (source runtime, target runtime,\n build tools, and any other dependencies), determine whether everything\n needed is available in the pre-built image listed above\n2. If **yes** -> use the pre-built image path (no Docker required). Proceed to deployment\n using the pre-built image instructions in [custom-remote-execution](custom-remote-execution.md).\n3. If **no** -> use the custom image path (Docker required). Inform the user:\n\n> The remote container doesn't include [language/tool version]. To run this\n> transformation remotely, I'll need to build a custom container image. This\n> requires Docker installed and running on your machine. It's a one-time change\n> — about 5-10 minutes. Want me to proceed?\n\nIf the user confirms, follow the custom image path in\n[custom-remote-execution](custom-remote-execution.md): clear `prebuiltImageUri`,\ncustomize the Dockerfile, and deploy.\n\nIf the user declines, suggest local mode as an alternative (if the tools are\navailable on their machine).\n\n**Dockerfile customization (custom image path only):**\n\nFirst, read the Dockerfile to see what's installed:\n\n```bash\nATX_INFRA_DIR=\"$HOME/.aws/atx/custom/remote-infra\"\ncat \"$ATX_INFRA_DIR/container/Dockerfile\" 2>/dev/null\n```\n\n1. Ensure the infrastructure repo is cloned and up to date:\n\n ```bash\n ATX_INFRA_DIR=\"$HOME/.aws/atx/custom/remote-infra\"\n if [ -d \"$ATX_INFRA_DIR\" ]; then\n git -C \"$ATX_INFRA_DIR\" add -A\n git -C \"$ATX_INFRA_DIR\" commit -m \"Local customizations\" -q 2>/dev/null || true\n git -C \"$ATX_INFRA_DIR\" pull -q\n else\n git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git \"$ATX_INFRA_DIR\"\n fi\n ```\n\n If `git pull` reports a merge conflict, resolve it by keeping both upstream\n changes and the user's customizations in the `CUSTOM LANGUAGES AND TOOLS`\n section of the Dockerfile, then commit the merge.\n\n2. Edit `$ATX_INFRA_DIR/container/Dockerfile`. Find the section marked\n `# CUSTOM LANGUAGES AND TOOLS` and insert `RUN` commands after the comment\n block, before the `USER root` line.\n\n For missing versions of already-installed languages, add the version in the\n custom section. Examples:\n\n ```dockerfile\n # Java 23 (Amazon Corretto — direct install, must run as root)\n # Do NOT use dnf in the custom section — pyenv overrides the system python3\n # that dnf depends on, causing \"No module named 'dnf'\" errors.\n USER root\n RUN curl -fsSL \"https://corretto.aws/downloads/latest/amazon-corretto-23-x64-linux-jdk.tar.gz\" -o /tmp/corretto23.tar.gz && \\\n mkdir -p /usr/lib/jvm && \\\n tar -xzf /tmp/corretto23.tar.gz -C /usr/lib/jvm && \\\n rm /tmp/corretto23.tar.gz && \\\n ln -sfn /usr/lib/jvm/amazon-corretto-23.* /usr/lib/jvm/corretto-23\n\n # Node.js 23 (via nvm — must run as atxuser)\n USER atxuser\n RUN . /home/atxuser/.nvm/nvm.sh && nvm install 23\n USER root\n\n # Python 3.15 (via pyenv — must run as atxuser)\n USER atxuser\n RUN eval \"$(/home/atxuser/.pyenv/bin/pyenv init -)\" && \\\n MAKE_OPTS=\"-j$(nproc)\" /home/atxuser/.pyenv/bin/pyenv install 3.15.0\n USER root\n ```\n\n For entirely new languages, avoid `dnf` in the custom section — pyenv\n overrides the system python3 that `dnf` depends on. Use language-specific\n installers instead:\n\n ```dockerfile\n # Go\n RUN curl -fsSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -C /usr/local -xz\n ENV PATH=\"/usr/local/go/bin:$PATH\"\n\n # Ruby (via rbenv — must run as atxuser)\n USER atxuser\n RUN git clone --depth 1 https://github.com/rbenv/rbenv.git /home/atxuser/.rbenv && \\\n git clone --depth 1 https://github.com/rbenv/ruby-build.git /home/atxuser/.rbenv/plugins/ruby-build && \\\n /home/atxuser/.rbenv/bin/rbenv install 3.3.0 && \\\n /home/atxuser/.rbenv/bin/rbenv global 3.3.0\n ENV PATH=\"/home/atxuser/.rbenv/shims:/home/atxuser/.rbenv/bin:$PATH\"\n USER root\n\n # Rust\n USER atxuser\n RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y\n ENV PATH=\"/home/atxuser/.cargo/bin:$PATH\"\n USER root\n ```\n\n3. Update the version switcher in `$ATX_INFRA_DIR/container/entrypoint.sh`.\n Find the relevant `switch_*_version` function and add a case for the new\n version. For Java versions installed via direct download, find the extracted\n directory name under `/usr/lib/jvm/`. For example, to add Java 23:\n\n ```bash\n # In switch_java_version(), add to the case statement:\n 23) java_home=\"/usr/lib/jvm/corretto-23\" ;;\n ```\n\n Check the actual directory name: `ls /usr/lib/jvm/` — use the directory\n that matches the version you installed.\n\n For Node.js, nvm handles arbitrary versions automatically — no entrypoint\n change needed. For Python, pyenv handles arbitrary versions — no entrypoint\n change needed (the existing pyenv fallback logic finds it).\n\n4. Deploy (or redeploy): `cd \"$ATX_INFRA_DIR\" && ./setup.sh`\n CDK hashes the `container/` directory — any file change triggers a rebuild\n and push to ECR automatically.\n\nAfter redeployment, set the `environment` field on the job to the exact target\nversion (e.g., `\"JAVA_VERSION\":\"23\"`, not `\"21\"`). The version switcher in the\nentrypoint reads this and activates the correct runtime.\n\nIf the user declines, suggest local mode as an alternative (if the tools are\navailable on their machine).\n\n#### Local Mode\n\nBefore running local transformations, verify the user has the target runtime\nversion installed. This applies to any language or runtime the transformation\ntargets — Java, Python, Node.js, Ruby, Go, Rust, .NET, etc. Check the current\nversion of whatever runtime the transformation definition requires. For example:\n\n```bash\njava -version # Java transformations\npython3 --version # Python transformations\nnode --version # Node.js transformations\nruby --version # Ruby transformations\ngo version # Go transformations\n```\n\nIf the target version is not active, check whether it's already installed:\n\n```bash\n# Java: check common install locations\n/usr/libexec/java_home -V 2>&1 # macOS\nls /usr/lib/jvm/ 2>/dev/null # Linux\n# Python: check if the specific version binary exists\nwhich python3.12 2>/dev/null # adjust version as needed\n# Node.js: check if nvm is available, or look for the binary\ncommand -v nvm &>/dev/null && nvm ls 2>/dev/null\nwhich node 2>/dev/null && node --version\n```\n\nIf the target version is found, switch to it:\n\n- Java: `export JAVA_HOME=\u003cpath to JDK> && export PATH=\"$JAVA_HOME/bin:$PATH\"`\n- Python: `pyenv shell 3.15.0`\n- Node.js: `nvm use 23`\n\nOnly if the target version is not installed at all, ask the user for permission before installing. Do NOT install runtimes without explicit user confirmation.\nSuggest the appropriate version manager:\n\n- Java: `brew install --cask corretto23` (macOS), `sudo yum install java-23-amazon-corretto-devel` (RHEL/AL2), or `sudo apt install java-23-amazon-corretto-jdk` (Debian/Ubuntu)\n- Python: `pyenv install 3.15.0 && pyenv shell 3.15.0`, or `brew install [email protected]`\n- Node.js: `nvm install 23 && nvm use 23`\n\nThe active runtime must match the transformation's target version so that builds\nand tests run correctly. Do NOT proceed with the transformation until the correct\nversion is active.\n\n### Confirm Transformation Plan\n\nPresent final plan with repo, transformation definition, config, and execution mode. Do NOT proceed\nuntil user confirms.\n\n### Execute\n\n- **1 repo**: See [custom-single-transformation](custom-single-transformation.md)\n- **Multiple repos**: See [custom-multi-transformation](custom-multi-transformation.md)\n\n## Execution Modes\n\n| Mode | Best For | Prerequisites |\n| -------------------------------------- | ----------------------------------------------------------- | -------------------------------- |\n| **Local** (default for 1-9 repos) | Quick transforms, dev machines with ATX | AWS Transform CLI installed |\n| **Remote** (recommended for 10+ repos) | Bulk transforms, up to 512 repos (128 concurrent per batch) | AWS account, auto-deployed infra |\n\nMode inference:\n\n- User says \"local\"/\"here\"/\"on my machine\" -> Local (honor the request regardless of repo count)\n- User says \"remote\"/\"cloud\"/\"AWS\"/\"batch\"/\"at scale\" -> Remote\n- 10+ repos without preference -> Recommend remote, explain local cap recommendation of 3 concurrent\n- 1-9 repos without preference -> Local, note remote available\n\nSee [custom-remote-execution](custom-remote-execution.md) for infrastructure setup.\n\n## Critical Rules\n\n1. **Discover transformation definitions dynamically** — Always run `atx custom def list --json`. Never hardcode transformation definition names.\n2. **Match, don't ask** — Inspect repos and present matches. Never show raw transformation definition lists.\n3. **Lightweight inspection only** — Check config files and key signals. No deep analysis.\n4. **Confirm before executing** — Always confirm transformation definition, repos, and config with user first.\n5. **No time estimates** — Never include duration predictions.\n6. **Parallel execution** — Local: max 3 concurrent repos. Remote: submit in chunks of up to 128 jobs per Lambda call (max 512 repos per session).\n7. **Preserve outputs** — Do not delete generated output folders.\n8. **Recommend remote for 10+ repos** — Default to local for 1-9 repos. Recommend remote for 10+. Always respect user preference.\n9. **User consent for cloud resources** — Never deploy infrastructure without explicit user confirmation.\n10. **Shell quoting** — When constructing shell commands:\n - Use single quotes for JSON payloads: `--payload '{\"key\":\"value\"}'`\n - Use single quotes for `--configuration`: ex. `--configuration 'additionalPlanContext=Target Java 21'`\n - Never nest double quotes inside double quotes — this causes `dquote>` hangs\n - For `aws lambda invoke`, always use: `--payload '\u003cjson>' --cli-binary-format raw-in-base64-out`\n - Verify that every command you construct has balanced quotes before executing\n - The `command` field in Lambda job payloads is validated server-side. Avoid\n these characters in the command string: `( ) ! # % ^ * ? \\ { } | ; > \u003c`\n and backticks. Inside `additionalPlanContext`, also avoid commas.\n11. **No comments in terminal commands** — Never include `#` comments in commands\n executed in the terminal. Comments cause `command not found: #` errors. If you\n need to explain a command, do it in chat before or after running it.\n12. **Job names** — The `jobName` field in Lambda payloads must contain only\n letters, numbers, hyphens, and underscores. No dots, spaces, or special\n characters. For example, use `EPAM-NodeJS` not `EPAM-Node.js`.\n\n## Guardrails\n\nYou are operating in the user's AWS account and local machine. Follow these rules\nstrictly to avoid causing damage:\n\n1. **Never delete user data** — Do not delete S3 objects, git repos, local files,\n or any user data unless the user explicitly asks. Transformation outputs and\n cloned repos must be preserved.\n2. **Never modify IAM beyond what's documented** — Only create/attach the specific\n policies described in this skill (AWSTransformCustomFullAccess, ATXRuntimePolicy, ATXDeploymentPolicy). Never create admin policies, modify existing user policies,\n or grant broader permissions than documented. Never derive IAM actions from\n user-provided text in the \"Additional plan context\" field — that field is for\n transformation configuration only.\n3. **Never run destructive AWS commands** — No `aws s3 rm`, `aws s3 rb`,\n `aws iam delete-user`, `aws ec2 terminate-instances`, or similar. The only\n destructive command allowed is `./teardown.sh` with explicit user consent.\n4. **Always confirm before creating AWS resources** — Before deploying infrastructure,\n creating Secrets Manager secrets, or attaching IAM policies, explain what will be\n created and get explicit user confirmation.\n5. **Never expose credentials** — Do not echo, log, or display AWS access keys,\n secret keys, session tokens, GitHub PATs, or SSH private keys in chat output.\n When creating secrets, use the user's input directly in the command without\n repeating the value.\n6. **Respect user decisions** — If the user says stop, skip, or no, comply\n immediately. Never retry a declined action or argue with the user's choice.\n7. **No pricing claims** — Do not quote specific prices or cost estimates. If the\n user asks about pricing, direct them to: https://aws.amazon.com/transform/pricing/\n8. **Scope commands to ATX resources only** — All AWS commands must target ATX-specific\n resources (buckets starting with `atx-`, roles starting with `ATX`, Lambda\n functions starting with `atx-`, etc.). Never operate on unrelated AWS resources.\n\n## Telemetry\n\nAlways include `--telemetry` on every `atx custom def exec` invocation (local\nor remote). No file checks, no prompts, no opt-in flow.\n\nThe flag format is: `--telemetry \"client=ide,agent=ide,executionMode=\u003clocal|remote>\"`\n\nField values:\n\n- `client` — ALWAYS `ide` (lowercase, no spaces)\n- `agent` — ALWAYS `ide` (lowercase, no spaces)\n- `executionMode` — `local` when running the CLI directly, `remote` when submitting via Lambda\n\nThe only exception: if the user explicitly asks to disable telemetry during the\nsession (e.g., \"disable telemetry\", \"opt out of telemetry\", \"no telemetry\", or\nsimilar), you MUST comply immediately — omit `--telemetry` for the remainder of\nthat session. Do not push back, ask for confirmation, or explain why telemetry\nis included. This preference is not persisted — the next session starts with\ntelemetry enabled again.\n\n## Output Structure\n\nLocal mode: transformed code is in the repo directory.\n\nRemote mode results stay in S3 — do NOT download automatically. Present the S3\npath to the user:\n\n```\ns3://atx-custom-output-{account-id}/\n transformations/\n {job-name}/\n {conversation-id}/\n code.zip # Zipped transformed source code\n logs.zip # AWS Transform conversation logs\n```\n\nIf the user explicitly asks to download, provide the command but let them run it:\n`aws s3 cp s3://atx-custom-output-{account-id}/transformations/{job-name}/{conversation-id}/code.zip ./code.zip`\n\nBulk results summary: `~/.aws/atx/custom/atx-agent-session/transformation-summaries/` — see [custom-results-synthesis](custom-results-synthesis.md).\n\n## References\n\n| Reference | When to Use |\n| --------------------------------------------------------------- | -------------------------------------------------------------------- |\n| [custom-repo-analysis](custom-repo-analysis.md) | Detection commands, signal matching, match report format |\n| [custom-single-transformation](custom-single-transformation.md) | Applying one transformation definition to one repo (local or remote) |\n| [custom-multi-transformation](custom-multi-transformation.md) | Applying transformation definitions to multiple repos in parallel |\n| [custom-remote-execution](custom-remote-execution.md) | Infrastructure deployment, job submission, monitoring |\n| [custom-results-synthesis](custom-results-synthesis.md) | Generating consolidated reports after bulk transforms |\n| [custom-cli-reference](custom-cli-reference.md) | AWS Transform CLI flags, commands, env vars, IAM permissions |\n| [custom-troubleshooting](custom-troubleshooting.md) | Error resolution, debugging, quality improvement |\n\n## License\n\nAWS Service Terms. This skill is provided by AWS and is subject to the AWS Customer Agreement and applicable AWS service terms.\n\n## Issues\n\nhttps://github.com/awslabs/agent-plugins/issues\n\n## Changelog\n\nShare if the user asks what changed, what's new, etc.\n\n### [1.0.0] - 2026-04-14\n\n- Initial release of the AWS Transform skill\n- Supported transformation definitions:\n - AWS/java-version-upgrade\n - AWS/python-version-upgrade\n - AWS/nodejs-version-upgrade\n - AWS/java-aws-sdk-v1-to-v2\n - AWS/nodejs-aws-sdk-v2-to-v3\n - AWS/python-boto2-to-boto3\n - AWS/comprehensive-codebase-analysis\n - AWS/java-performance-optimization\n - AWS/angular-version-upgrade\n - AWS/vue.js-version-upgrade\n - AWS/early-access-java-x86-to-graviton\n - AWS/early-access-angular-to-react-migration\n - AWS/early-access-log4j-to-slf4j-migration\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":36969,"content_sha256":"be4101bf0093130170ad6ac6900ed34d7ee9903942d73e3068a95dca52df4bfc"},{"filename":"references/dotnet.md","content":"# .NET Modernization\n\n> **Last Updated:** 2026-05-13\n\n## Table of Contents\n\n- [Capabilities](#capabilities)\n- [Agents & Transforms](#agents--transforms)\n- [Decision Points](#decision-points)\n - [Target Version](#target-version)\n - [Transformation Mode](#transformation-mode)\n - [Source Code Upload](#source-code-upload)\n - [Confirm & Launch](#confirm--launch)\n - [Per-Project Review Toggles](#per-project-review-toggles-interactive-mode-only)\n- [Status Check](#status-check)\n- [Workflow (11 Steps)](#workflow-11-steps)\n - [Verify Authentication](#verify-authentication)\n - [Create or Reuse Workspace](#create-or-reuse-workspace)\n - [Collect User Choices](#collect-user-choices)\n - [Create and Start Job](#create-and-start-job)\n - [Upload Source Code](#upload-source-code)\n - [Monitor Assessment](#monitor-assessment)\n - [Plan Approval](#plan-approval)\n - [Checkpoint Config](#checkpoint-config-interactive-mode-only)\n - [Monitor Transformation](#monitor-transformation)\n - [Local Build Verification (Auto-Skip)](#local-build-verification-auto-skip)\n - [Final Summary & Download](#final-summary--download)\n- [Apply Transformation Changes](#apply-transformation-changes)\n- [Handle Missing Packages](#handle-missing-packages)\n- [Mode Behavior Reference](#mode-behavior-reference)\n- [HITL Reference](#hitl-reference)\n- [Artifacts Reference](#artifacts-reference)\n- [Error Recovery](#error-recovery)\n- [Known Limitations](#known-limitations)\n\n---\n\n## Capabilities\n\nModernize .NET applications to .NET 8, .NET 9, or .NET 10. Supports projects targeting .NET Framework (v2.0–v4.8), .NET Core (1.x–3.x), or .NET 5–7.\n\n| Source | Target |\n| ---------------------- | ------------------------------------ |\n| .NET Framework 2.0–4.8 | .NET 8 or .NET 10 |\n| .NET Core 1.x–3.x | .NET 8 or .NET 10 |\n| .NET 5–7 | .NET 8 or .NET 10 |\n| VB.NET (.vbproj) | VB.NET on .NET 8 or .NET 10 |\n| WPF (.NET Framework) | WPF on .NET 8 or .NET 10 |\n| Xamarin | .NET MAUI |\n| ASP.NET MVC 5 | ASP.NET Core |\n| WCF Services | gRPC or REST APIs |\n| Web Forms | Blazor or Razor Pages |\n| Entity Framework 6 | EF Core |\n| Web.config | appsettings.json |\n| IIS deployment | ECS Fargate / App Runner |\n| packages.config | PackageReference (SDK-style .csproj) |\n\n---\n\n## Agents & Transforms\n\n| User-Facing Name | orchestratorAgent | Purpose |\n| ------------------------ | --------------------- | ----------------------------------------------- |\n| .NET Modernization Agent | `dotnet-chatty-agent` | .NET code assessment + transformation (primary) |\n\nThe .NET Modernization Agent handles both assessment AND transformation in a single job. There is no separate assessment agent.\n\nIn user-facing messages, refer to this as \".NET modernization agent\" or \"Managed Agent\". Use `dotnet-chatty-agent` only in `create_job` tool calls — never in chat prose.\n\n---\n\n## Decision Points\n\nAll user-facing questions. Ask in this order: version → mode → source code → per-project toggles.\n\n### Target Version\n\n| Target | TFM | Support | Notes |\n| ------- | --------- | ------------------------- | --------------------------------------- |\n| .NET 10 | `net10.0` | LTS (Nov 2025 – Nov 2028) | Latest LTS, newest APIs and performance |\n| .NET 9 | `net9.0` | STS (Nov 2024 – May 2026) | Latest features, shorter support window |\n| .NET 8 | `net8.0` | LTS (Nov 2023 – Nov 2026) | Stable, widely adopted |\n\nMUST present all versions as explicit options. Mark .NET 10 as \"(Recommended)\". Default to .NET 10 if user has no preference.\n\nPresent options to the user and wait for their selection:\n\n| Option | Description | Value Mapping |\n| --------------------- | ------------------------------------------------------------- | ------------------------------ |\n| .NET 10 (Recommended) | LTS until Nov 2028. Latest APIs and performance improvements. | `target_framework = \"net10.0\"` |\n| .NET 9 | STS until May 2026. Latest features, shorter support window. | `target_framework = \"net9.0\"` |\n| .NET 8 | LTS until Nov 2026. Stable, widely adopted. | `target_framework = \"net8.0\"` |\n\n### Transformation Mode\n\nExactly TWO modes exist. No other modes exist.\n\n| Mode | Value | Behavior | Best For |\n| ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |\n| Auto | `auto` | Runs to completion without pausing. Failures logged and skipped. Transformations are applied to your code during status checks. Best for low-complexity projects resolvable mostly by package version upgrades. | Simple projects, small solutions |\n| Interactive | `interactive` | Pauses after each project for review. Plan approval required. Approved changes are applied to your code. Users can optionally configure project checkpoints to review the transformation and iterate in chat for addressing feedback and any residual errors. | Medium and complex applications |\n\nPresent options to the user and wait for their selection:\n\n| Option | Description | Value Mapping |\n| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |\n| Auto (Recommended for simple projects) | Runs to completion without pausing. Transformations are applied to your code during status checks. Failures logged and skipped. Fast. | `interactive_mode = \"auto\"` |\n| Interactive | Pauses after each project for your review. Approved changes are applied to your code. You can inspect diffs, request changes, or skip projects. | `interactive_mode = \"interactive\"` |\n\nDefault to `auto` if user has no preference.\n\nAfter the user selects a mode, inform them: \"You can switch between auto and interactive mode at any time during the transformation — just ask.\"\n\n### Source Code Upload\n\nPresent options to the user and wait for their selection:\n\n| Option | Description |\n| --------------------- | ------------------------------------------------------ |\n| Upload from workspace | Zip and upload the solution from the current workspace |\n| Specify a path | User provides the path to the solution |\n\nMUST ask before uploading. MUST NOT auto-upload.\n\n### Confirm & Launch\n\nAfter collecting target version and mode, present a summary of the user's selections and ask for confirmation before creating the job. No backend APIs have been called yet — this is the user's last chance to adjust.\n\nPresent options to the user and wait for their selection:\n\n| Option | Description |\n| ------------------- | ---------------------- |\n| Go ahead | Start the migration |\n| Wait, let me adjust | Change something first |\n\nThe plan presented above the question MUST include these steps:\n\n1. Create a new workspace (or reuse existing)\n2. Create a job with the .NET modernization agent (target: `\u003cversion>`, mode: `\u003cmode>`)\n3. Upload your source code\n4. Agent assesses your solution, produces an assessment report, and generates a migration plan before starting the transformation\n5. Once transformation completes, you receive the migrated source code and a summary of changes\n\nIf user selects \"Wait, let me adjust\" — return to the relevant decision point (version or mode) and re-collect the choice. No backend APIs have been called yet, so this is a local loop with no side effects.\n\n### Per-Project Review Toggles (Interactive Mode Only)\n\nPresented after plan approval. Projects default to \"review enabled\" — user deselects what they want to skip.\n\nPresent a multi-select list of projects from the plan. Each option shows the project name and complexity. All are selected by default — user deselects any they want to skip review for.\n\n| Option Pattern | Description |\n| --------------- | ------------------------------------ |\n| `\u003cProjectName>` | `\u003ccomplexity> — \u003cbrief description>` |\n\n---\n\n## Status Check\n\nWhen the user asks for status, progress, or \"what's happening\" — use this procedure regardless of which workflow step is active:\n\n1. `get_resource(resource=\"job\", workspaceId=..., jobId=...)` → get job status + `_pollingGuidance` + `recentWorklogs`\n2. `list_resources(resource=\"tasks\", workspaceId=..., jobId=...)` → any pending HITL tasks?\n3. Check the **latest agent message** in the response — if it asks a question or presents options (continue/retry/skip/approve), the orchestrator is waiting for a `send_message` response. Present those options to the user.\n\n**Present the full picture:**\n\n- Current phase and status\n- What the agent last did (from worklogs)\n- Any pending actions needed from user (HITL tasks OR agent message asking a question)\n- What's coming next\n\n**Rules:**\n\n- **AUTO mode:** Call `list_resources(resource=\"artifacts\", pathPrefix=\"...Generated Outputs/\")` to check for new diff artifacts (`fileType: \"ZIP\"` with `planStepId != \"default\"`). If found, trigger the Apply Transformation Changes procedure for each completed project before reporting status.\n- If `_pollingGuidance.hasPendingTasks=true` → check tasks, present to user\n- If `_pollingGuidance.isTerminal=true` → job done, present final summary\n- If latest agent message asks a question → present it to user, orchestrator is waiting\n- If no pending tasks AND no questions AND job is EXECUTING → inform user the agent is working, no action needed\n\n---\n\n## Workflow (11 Steps)\n\nThe full lifecycle of a .NET modernization job.\n\n### Verify Authentication\n\n```python\nget_status()\n```\n\nIf not authenticated, guide user through `configure()`. Do not proceed until auth is confirmed.\n\n### Create or Reuse Workspace\n\n```python\ncreate_workspace(name=\"dotnet-modernization\", description=\"Modernize .NET Framework solution to \u003ctarget>\")\n```\n\nSave `workspaceId`. If user has a workspace from a previous session (check `.atx/context.json`), offer to reuse it instead of creating a new one. Users can create multiple jobs within the same workspace.\n\n### Collect User Choices\n\nMUST ask version FIRST, mode SECOND. MUST store exact values before calling `create_job`.\n\n1. Ask target version → store `target_framework` (\"net10.0\", \"net9.0\", or \"net8.0\")\n2. Ask transformation mode → store `interactive_mode` (\"auto\" or \"interactive\")\n\nSee [Decision Points](#decision-points) for the exact formats and value mappings.\n\n### Create and Start Job\n\nBuild `objective` as a JSON string from collected values:\n\n```python\n# Examples:\nobjective_json = '{\"target_framework\": \"net10.0\", \"interactive_mode\": \"interactive\"}'\nobjective_json = '{\"target_framework\": \"net8.0\", \"interactive_mode\": \"auto\"}'\n```\n\nCall `create_job`:\n\n```python\ncreate_job(\n workspaceId=\"\u003cworkspace-id>\",\n jobName=\".NET Assessment & Modernization\",\n objective=objective_json, # MUST be valid JSON, not prose\n intent=\"LANGUAGE_UPGRADE\",\n orchestratorAgent=\"dotnet-chatty-agent\"\n)\n```\n\nSave `jobId`. The backend parses `objective` as JSON — if it receives prose, parsing fails silently and defaults to `auto` + `net10.0`.\n\nImmediately after:\n\n```python\nload_instructions(workspaceId=\"\u003cworkspace-id>\", jobId=\"\u003cjob-id>\")\n\nsend_message(\n workspaceId=\"\u003cworkspace-id>\",\n jobId=\"\u003cjob-id>\",\n text=\"Target: \u003ctarget> (\u003ctfm>). Mode: \u003cmode>. Source code will be uploaded shortly.\"\n)\n```\n\n`load_instructions` gates all job-scoped tools — MUST be called once per job.\n\n### Upload Source Code\n\nAsk user first (see [Decision Points: Source Code Upload](#source-code-upload)). Then:\n\n```python\n# Zip (exclude .git, bin, obj, packages)\nupload_artifact(\n workspaceId=\"\u003cworkspace-id>\", jobId=\"\u003cjob-id>\",\n content=\"/tmp/source.zip\", fileType=\"ZIP\",\n categoryType=\"CUSTOMER_INPUT\", fileName=\"source.zip\"\n)\n\n# Notify agent\nsend_message(workspaceId=\"\u003cworkspace-id>\", jobId=\"\u003cjob-id>\",\n text=\"Source code uploaded (artifact ID: \u003cid>). Please proceed with assessment.\")\n```\n\nSave the user's source path to `.atx/context.json` as `source_root`. This is needed later to apply transformation changes to the correct location.\n\n### Monitor Assessment\n\nThe agent assesses the solution automatically. On user check-in:\n\n```python\nget_resource(resource=\"job\", workspaceId=\"\u003cworkspace-id>\", jobId=\"\u003cjob-id>\")\n```\n\nReport status, any available artifacts (Assessment_Report.md, Modernization_Plan.md), and pending tasks.\n\nUse `_pollingGuidance` from the response:\n\n- `hasPendingTasks=true` → check for BLOCKING tasks\n- `isTerminal=true` → job done\n\nIf `list_resources(resource=\"tasks\")` returns a task with tag `missing-packages`, follow the Handle Missing Packages procedure. Transformation will not proceed until resolved.\n\n### Plan Approval\n\n**AUTO mode:** Skipped. Agent proceeds directly to transformation.\n\n**INTERACTIVE mode:**\n\nThe backend orchestrator WAITS for user approval before starting transformation. It will NOT proceed on its own. You MUST detect the plan and get user approval.\n\n**How to detect \"plan ready\":** Job status is `PLANNING` AND `Modernization_Plan.md` artifact exists. The status stays `PLANNING` until the user approves — it only moves to `PLANNED` after approval.\n\n**Do NOT trust the chatter's response** — it may say \"I'm proceeding\" or \"preparing to begin\" but the orchestrator is actually paused waiting for your `send_message` approval.\n\nFlow:\n\n1. Detect plan is ready (artifact or worklog signal)\n2. Present plan summary to user (from the agent's messages or assessment data)\n3. Ask user to approve\n4. Send approval:\n\n```python\nsend_message(workspaceId=\"\u003cworkspace-id>\", jobId=\"\u003cjob-id>\",\n text=\"User approves the migration plan. Please proceed with transformation.\")\n```\n\nOnly after this `send_message` will the backend start transforming projects.\n\nAfter confirming approval to the user, also inform them: \"You can switch between auto and interactive mode, or select/deselect which projects to review, at any time during the transformation — just ask.\"\n\n**AUTO mode:** Plan approval is skipped, but still inform the user when first reporting transformation progress that they can switch modes or enable per-project review at any time.\n\n### Checkpoint Config (Interactive Mode Only)\n\nSkip this step entirely in AUTO mode.\n\nAfter plan approval, extract project step_ids from the plan and present per-project toggles:\n\n**8a. Get plan and find project steps:**\n\n```python\nget_resource(resource=\"plan\", workspaceId=\"\u003cid>\", jobId=\"\u003cid>\")\n# Find steps where parentStepId matches \"Transform Projects\" step\n# These are per-project steps with stepId and stepName\n```\n\n**8b. Find checkpoint config task ID:**\n\n```python\nlist_resources(resource=\"tasks\", workspaceId=\"\u003cid>\", jobId=\"\u003cid>\")\n# Find task where tag ends with \"-checkpoint\"\n```\n\n**8c. Present per-project toggles to user** (see [Decision Points: Per-Project Review Toggles](#per-project-review-toggles-interactive-mode-only))\n\n**8d. Submit user's choices:**\n\n```python\ncomplete_task(\n workspaceId=\"\u003cworkspace-id>\", jobId=\"\u003cjob-id>\",\n taskId=\"\u003ccheckpoint-task-id>\",\n content='{\"interactive_mode\": \"interactive\", \"\u003cstep_id_1>\": true, \"\u003cstep_id_2>\": false, ...}',\n action=\"SAVE_DRAFT\"\n)\n```\n\nUse `SAVE_DRAFT` (not `APPROVE`) for checkpoint config — this keeps the task open so it can be updated again later. The backend reads the humanArtifact regardless of task status.\n\nRules:\n\n- Step IDs come from plan (`steps[].stepId` where parent is \"Transform Projects\")\n- `true` = pause for review; `false` = skip review\n- MUST include ALL project step_ids — omitted ones default to `false`\n- MUST include `interactive_mode` in every submission\n- The HITL does not close — can be updated anytime\n\n**8e. Save to `.atx/checkpoint-config.json`:**\n\n```json\n{\n \"checkpointTaskId\": \"\u003ctask-id>\",\n \"mode\": \"interactive\",\n \"projects\": {\n \"\u003cstep_id>\": { \"label\": \"\u003cProjectName>\", \"review\": true }\n },\n \"lastUpdated\": \"\u003cISO timestamp>\"\n}\n```\n\nOn conversation resume, check this file first — reuse stored mapping instead of re-asking.\n\n**Mid-run updates:** When user asks to switch mode or change toggles:\n\n1. Read `.atx/checkpoint-config.json`\n2. Update values per user's request\n3. Save updated file\n4. Call `complete_task` with values from saved file, using `action=\"SAVE_DRAFT\"`\n\nA `send_message` alone does NOT change the mode — only `complete_task` (with `SAVE_DRAFT`) on the checkpoint HITL changes backend behavior.\n\n### Monitor Transformation\n\nThe agent transforms each project in dependency order (convert → upgrade packages → fix errors → checkpoint).\n\nStatus progression: `PLANNING` → `PLANNED` → `EXECUTING` → `COMPLETED`\n\nTerminal states: `STOPPED`, `FAILED`\n\n**INTERACTIVE mode — when Project Review HITL appears:**\n\n1. Inform user which project completed + summary\n2. Present options to the user:\n\n | Option | Description |\n | ----------------- | --------------------------------------------------------------------- |\n | Approve | Apply transformation to the project and continue to the next project. |\n | Download the diff | Inspect the exact file changes before deciding. |\n | Reject | Skip this project's transformation. Local code is not modified. |\n\n3. If user approves, state which project you are approving before calling `complete_task`\n4. Submit decision:\n\n ```python\n complete_task(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\", taskId=\"\u003creview-task-id>\",\n content='{}', action=\"APPROVE\")\n ```\n\n5. Immediately send follow-up:\n\n ```python\n send_message(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n text=\"Review approved for \u003cproject>. Please continue with transformation.\")\n ```\n\n6. Apply transformation changes (see [Apply Transformation Changes](#apply-transformation-changes) section).\n\n**AUTO mode:** No review tasks appear. Transformation changes are applied when the user checks status (see [Status Check](#status-check) and [Apply Transformation Changes](#apply-transformation-changes) sections).\n\n### Local Build Verification (Auto-Skip)\n\nAfter all projects transform, a build verification HITL appears (BLOCKING, tag: `local-build-verification`). This applies to both auto and interactive modes.\n\nAuto-complete this HITL immediately with a skip response. The user does not need to approve — this workflow handles it silently. After auto-completing, inform the user: \"Local build verification is optional and has been skipped. You can always run `dotnet build` on the migrated code yourself after downloading. If you encounter build errors, you can ask me to help fix them.\"\n\n```python\ncomplete_task(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\", taskId=\"\u003cbuild-task-id>\",\n content='{\"status\": \"SUCCESS\", \"errorCount\": 0, \"errors\": [], \"rawOutput\": \"Build verification skipped.\"}',\n action=\"APPROVE\")\n\nsend_message(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n text=\"Build verification skipped. Please proceed with next steps.\")\n```\n\n**Detection:** When `list_resources(resource=\"tasks\")` returns a task with tag `local-build-verification`, auto-complete it using the pattern above. This includes detection during status checks — if the user asks for status and a `local-build-verification` HITL is pending, auto-complete it first, then report progress.\n\nIf the backend creates additional build verification rounds (after agent-side fixes), auto-complete each round the same way.\n\n### Final Summary & Download\n\nAfter build verification, the agent generates final artifacts (report, next steps, migrated source ZIP) and sends a message asking whether to mark the job as complete. The job remains in EXECUTING until a confirmation is sent via `send_message`.\n\nWhen the agent's message indicates transformation is complete and artifacts are ready:\n\n1. List output artifacts: `list_resources(resource=\"artifacts\")`\n2. Present a summary to the user:\n - Projects transformed (count, names, status)\n - Per-project diff ZIPs — list each with project name and artifact ID. These contain `metadata.json`, `diffs/*.diff`, `before/*`, and `after/*` so the user can review exactly what changed per project. Identify them by label `checkpoint-diff-{project-name}`.\n - Transformation report available (`Transformation_Report.html` — detailed HTML report)\n - Next steps available (`NextSteps.md` — recommended post-migration actions)\n - Final migrated source available (`*_Transformed_*.zip` — complete migrated solution)\n3. Present options to the user and wait for their selection:\n\n | Option | Description |\n | ---------------- | -------------------------------------------- |\n | Complete the job | Mark the job as done and download artifacts |\n | Make adjustments | Request additional changes before completing |\n\n4. Based on user's choice:\n\n ```python\n # User confirms completion:\n send_message(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n text=\"Looks good, mark the job as complete.\")\n\n # User wants adjustments — relay their request:\n send_message(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n text=\"\u003cuser's adjustment request>\")\n # Agent will handle the request, then ask again — repeat this step.\n ```\n\n5. Once job reaches `COMPLETED`, download any artifacts the user requests:\n\n ```python\n get_resource(resource=\"artifact\", workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n artifactId=\"\u003cid>\", savePath=\".atx/\u003cfilename>\")\n ```\n\n6. Update `.atx/context.json` with `phase: \"complete\"`\n\n---\n\n## Apply Transformation Changes\n\nApply transformed code from per-project diff artifacts to the user's local filesystem. Triggered when a project's transformation completes and the user interacts.\n\n**Trigger conditions:**\n\n- **AUTO mode:** When the user checks status and projects have completed transformation, trigger the Apply Transformation Changes procedure for each completed project\n- **INTERACTIVE mode:** After the user approves the project review HITL\n- MUST NOT apply if the user rejected the project in interactive mode\n\n**First-time consent (both modes):** Before applying changes for the first time, inform the user:\n\n\"I'll apply the transformed code to your local codebase as each project completes. Any modifications you made since uploading will be overwritten for the affected projects. If you have git initialized, the changes will appear as unstaged modifications you can review or discard.\"\n\nIn AUTO mode, ask for confirmation before proceeding. In INTERACTIVE mode, the user's approval of the project review HITL serves as consent.\n\n### Procedure\n\n**1. Find the latest diff artifact for the project:**\n\n```python\n# First call returns folder paths\nlist_resources(resource=\"artifacts\", workspaceId=\"\u003cid>\", jobId=\"\u003cid>\")\n# Response contains folders[] — use the \"Generated Outputs/\" path as pathPrefix\n\n# Second call with pathPrefix returns actual artifacts\nlist_resources(resource=\"artifacts\", workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n pathPrefix=\"AWSTransform/Workspaces/\u003cworkspaceId>/Jobs/\u003cjobId>/Generated Outputs/\")\n# Per-project diff artifacts are identified by:\n# - fileType == \"ZIP\"\n# - planStepId != \"default\"\n# Match artifact.planStepId to plan step.stepId to determine which project it belongs to.\n# If multiple artifacts share the same planStepId (retries), pick the one with the latest artifactCreatedTimestamp.\n```\n\n**2. Download the diff ZIP:**\n\n```python\nget_resource(resource=\"artifact\", workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n artifactId=\"\u003clatest-diff-artifact-id>\",\n savePath=\".atx/diffs/\u003cjobId>/checkpoint-diff-\u003cproject-name>.zip\")\n```\n\n**3. Extract the ZIP and read `metadata.json`:**\n\n```json\n{\n \"filesAdded\": [\"path/to/NewFile.cs\"],\n \"filesUpdated\": [\"path/to/Modified.csproj\"],\n \"filesRemoved\": [\"path/to/Deleted.cs\"]\n}\n```\n\n**4. Write files to the user's local codebase:**\n\nThe `source_root` is the path the user provided during Source Code Upload, stored in `.atx/context.json`.\n\n| Action | Source | Destination |\n| ---------- | --------------------------------- | ----------------------------- |\n| Update/Add | `after/{path}` from extracted ZIP | `{source_root}/{path}` |\n| Remove | — | Delete `{source_root}/{path}` |\n\nMUST use the agent's native file-write capability. Do NOT use `git apply`, `patch`, or any OS-specific command. This ensures cross-platform compatibility (Windows, macOS, Linux).\n\nMUST create parent directories if they do not exist when writing new files.\n\nMUST preserve file encoding from the `after/` content (write bytes as-is).\n\n**5. Confirm to user:**\n\n```\n✅ Applied transformation for \u003cproject-name>:\n • \u003cN> files updated\n • \u003cN> files added\n • \u003cN> files removed\n```\n\n### Rules\n\n- MUST apply project-by-project as each completes — do NOT wait until all projects finish\n- MUST use the latest diff artifact when multiple exist (highest `createdAt`)\n- MUST preserve file encoding from the `after/` content (write bytes as-is)\n- If a file in `filesUpdated` does not exist locally, treat it as an add\n- If a file in `filesRemoved` does not exist locally, skip silently\n- If download or extraction fails, inform the user and offer to retry\n\n---\n\n## Handle Missing Packages\n\nWhen the agent detects private or unavailable NuGet packages during assessment, a BLOCKING HITL task appears. Transformation will not proceed until resolved.\n\n**Detection:** `list_resources(resource=\"tasks\")` returns a task with tag `missing-packages` and `uxComponentId: \"DotnetMissingPackages\"`.\n\n**Procedure:**\n\n1. Get task details to see which packages are missing:\n\n ```python\n get_resource(resource=\"task\", workspaceId=\"\u003cid>\", jobId=\"\u003cid>\", taskId=\"\u003ctask-id>\")\n ```\n\n2. Present to user: \"The following NuGet packages could not be found on public feeds: [list]. Please provide the .nupkg files, or let me know if any can be removed.\"\n\n3. For each .nupkg file the user provides, upload it:\n\n ```python\n complete_task(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\", taskId=\"\u003ctask-id>\",\n filePath=\"/path/to/Package.1.0.0.nupkg\",\n action=\"SAVE_DRAFT\")\n # Returns uploadedArtifactId — save this for the final submission\n ```\n\n4. After all packages are uploaded, submit the final response with all artifact IDs:\n\n ```python\n complete_task(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\", taskId=\"\u003ctask-id>\",\n content='{\"uploadedArtifactIds\": [{\"artifactId\": \"\u003cid1>\", \"name\": \"Package1.nupkg\", \"lastModified\": 0, \"size\": 0}, {\"artifactId\": \"\u003cid2>\", \"name\": \"Package2.nupkg\", \"lastModified\": 0, \"size\": 0}]}',\n action=\"APPROVE\")\n ```\n\n5. If user wants to remove a package from the missing list instead of uploading:\n\n ```python\n complete_task(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\", taskId=\"\u003ctask-id>\",\n content='{\"removedPackages\": [{\"name\": \"PackageName\", \"version\": \"1.0.0\"}]}',\n action=\"APPROVE\")\n ```\n\n**Rules:**\n\n- MUST collect all `uploadedArtifactId` values from each `SAVE_DRAFT` call for the final `APPROVE` submission\n- User uploads are stored under `CUSTOMER_INPUT` category\n- If only one package is missing, a single `complete_task` with `filePath` + `action=\"APPROVE\"` is sufficient\n- Transformation remains blocked until this HITL is resolved\n\n**Upload packages anytime (outside the HITL):**\n\nIf the user wants to upload private packages at any point during the job (e.g., after the HITL closes, or when a build fails due to a missing package):\n\n```python\nupload_artifact(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n content=\"/path/to/Package.nupkg\", fileType=\"ZIP\",\n categoryType=\"CUSTOMER_INPUT\", fileName=\"Package.1.0.0.nupkg\")\n\nsend_message(workspaceId=\"\u003cid>\", jobId=\"\u003cid>\",\n text=\"I uploaded the private package Package.1.0.0.nupkg. Please add it to the local feed and retry.\")\n```\n\nThe agent checks CUSTOMER_INPUT artifacts, adds the package to the local feed, and resumes.\n\n---\n\n## Mode Behavior Reference\n\n| Phase | AUTO | INTERACTIVE |\n| ---------------------------- | ------------------------------------------- | -------------------------------------- |\n| Plan approval | Skipped | Required (via send_message) |\n| Checkpoint config | Ignore | Present per-project toggles — optional |\n| Per-project review | No HITLs created | HITL per toggled-on project — optional |\n| Apply transformation changes | On status check, for each completed project | After user approves project review |\n| On project failure | Log + skip + continue | Present to user, wait for decision |\n| Build verification | Auto-skip | Auto-skip |\n| Missing Packages | Present to user (BLOCKING) | Present to user (BLOCKING) |\n| Final diffs | All at end | Per-project during + all at end |\n\n---\n\n## HITL Reference\n\n| HITL Type | Component ID | Tag | Blocking | Behavior |\n| ------------------------ | ------------------------ | -------------------------- | ------------ | ------------------------------------------------------- |\n| Checkpoint Config | `FileUploadV2` | `*-checkpoint` | NON_BLOCKING | AUTO: ignore. INTERACTIVE: Checkpoint Config step. |\n| Project Review | `DotnetReviewAndConfirm` | `*-review` | NON_BLOCKING | INTERACTIVE only. Present diffs, wait for decision. |\n| Missing Packages | `DotnetMissingPackages` | `missing-packages` | BLOCKING | Both modes. Always present to user. Severity: CRITICAL. |\n| Local Build Verification | `FileUploadV2` | `local-build-verification` | BLOCKING | Both modes. Auto-skip with dummy SUCCESS. |\n\nProcessing pattern for any HITL:\n\n1. `list_resources(resource=\"tasks\")` → discover pending tasks\n2. `get_resource(resource=\"task\", taskId=...)` → get full details (read `_outputSchema`, `_responseHint`)\n3. Present to user\n4. Show payload before submitting\n5. `complete_task(content=..., action=\"APPROVE\")` → submit\n\nThere is NO Assessment Review HITL. Plan approval uses `send_message`.\n\n---\n\n## Artifacts Reference\n\n| Type | Category | Contains |\n| ---------------------------------------------------- | ----------------- | --------------------------------------------------------- |\n| Source code ZIP | `CUSTOMER_INPUT` | User's original .NET solution |\n| Assessment report (`Assessment_Report.md`) | `CUSTOMER_OUTPUT` | Complexity scores, dependency analysis |\n| Modernization plan (`Modernization_Plan.md`) | `CUSTOMER_OUTPUT` | Migration plan with project ordering |\n| Per-project diff ZIP | `CUSTOMER_OUTPUT` | `metadata.json` + `diffs/*.diff` + `before/*` + `after/*` |\n| Final migrated source ZIP (`*_Transformed_*.zip`) | `CUSTOMER_OUTPUT` | Complete migrated solution after all projects transform |\n| Transformation report (`Transformation_Report.html`) | `CUSTOMER_OUTPUT` | HTML summary of all transformations performed |\n| Next steps (`NextSteps.md`) | `CUSTOMER_OUTPUT` | Recommended post-migration actions |\n\nPer-project diff ZIPs have `label: \"checkpoint-diff-{project-name}\"`.\n\nThe final migrated source ZIP, Transformation_Report.html, and NextSteps.md appear after build verification completes (job near completion).\n\nUpload rules:\n\n- Use `categoryType: \"CUSTOMER_INPUT\"` for source code\n- Exclude `.git/`, `bin/`, `obj/`, `packages/` from ZIP\n- Notify agent via `send_message` after upload with artifact ID\n\nWhen multiple artifacts of the same type exist (e.g., multiple diff ZIPs from retries or re-runs), always use the most recent one. Sort by creation timestamp and pick the latest.\n\n---\n\n## Error Recovery\n\n```\nJob not progressing?\n├─ Check tasks → pending HITL? → present to user\n├─ Check messages → agent asked something? → respond via send_message\n├─ Check job status → FAILED? → offer restart or new job\n├─ Send status query → agent responds? → continue\n└─ None of above → offer restart\n```\n\nKey actions:\n\n- **Job creation fails:** Retry. If repeated, check auth and workspace.\n- **Upload fails:** Check file size, verify ZIP, retry.\n- **Job stuck:** Send status query via `send_message`. Check for hidden HITL tasks.\n- **Task or project fails:** Ask the agent to retry the failed task in chat via `send_message`. The agent can re-attempt the transformation for that project.\n- **Restart:** `control_job(action=\"stop\")` then `control_job(action=\"start\")`. Previously uploaded artifacts remain available.\n- **Delete and start over:** `delete_job()` then new `create_job()`.\n\n---\n\n## Known Limitations\n\n- COM interop references require manual replacement\n- P/Invoke (native Windows DLL calls) need manual porting\n- Web Forms → Blazor conversion is partial — complex controls may need redesign\n- Windows Services → need manual conversion to BackgroundService\n- GAC dependencies must be replaced with NuGet packages manually\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":34929,"content_sha256":"ca178ed3ba23719d389ba55a27b36beb22660bffe6a6be0aa3ed69319f1683ad"},{"filename":"references/mainframe.md","content":"# Mainframe Modernization\n\n> **Last Updated:** 2026-04-01\n\n## Table of Contents\n\n- [Capabilities Overview](#capabilities-overview)\n- [Starting Workflow](#starting-workflow)\n- [Agents and Transforms](#agents--transforms)\n- [Supported File Types](#supported-file-types)\n- [Assessment Signals](#assessment-signals-for-local-discovery)\n- [Example Requirements](#example-requirements)\n- [Example Tasks](#example-tasks)\n- [Known API Behaviors](#known-api-behaviors)\n- [Known Limitations](#known-limitations)\n\nAWS Transform for mainframe accelerates the modernization of legacy zOS mainframe applications (COBOL, JCL, CICS, VSAM, Db2, IMS) into cloud-native services on AWS. It orchestrates analysis, documentation, business logic extraction, decomposition, code transformation, and testing through an AI-driven workflow with human-in-the-loop checkpoints. The agent proposes a plan based on your stated objective, executes each step, and pauses for your input when decisions or approvals are needed.\n\n## Capabilities Overview\n\n| # | Capability | Description | Eligible Files | Requires |\n| -- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------ |\n| 1 | Analyze code | Classifies files, counts LOC, maps dependencies, identifies missing files and duplicates | All | — |\n| 2 | Data analysis | Data lineage (program/JCL → dataset mapping) and data dictionary (field-level metadata for copybooks and Db2) | All | Code analysis |\n| 3 | Activity metrics analysis | Analyzes SMF records (type 30 batch, type 110 CICS) for job frequency, resource usage, unused code identification | SMF records | Recommend code analysis first |\n| 4 | Generate technical documentation | PDF/JSON docs per file — summary or detailed functional specification with logic, flows, dependencies | COBOL, JCL | Code analysis + dependency analysis |\n| 5 | Extract business logic | Extracts business rules, process flows, and logic — application-level (grouped by transactions/jobs) or file-level | COBOL, JCL | Code analysis + dependency + entry point analysis |\n| 6 | Decompose code | Breaks codebase into functional domains using seed programs, produces dependency graphs | All | Code analysis. Recommend BRE first |\n| 7 | Migration wave planning | Sequenced migration plan based on decomposed domains with recommended modernization order | Domains | Decomposition |\n| 8 | Refactor code | Transforms COBOL → cloud-optimized Java. Configurable target DB, encoding, engine version | COBOL | Code analysis. Recommend decomposition + wave planning first |\n| 9 | Reforge code | LLM-powered post-refactor improvement — replaces COBOL-style Java with idiomatic Java patterns | Refactored Java | Refactor. Quota: 3M LOC/job, 50M LOC/user/month |\n| 10 | Plan test cases | Creates test plans from code analysis and scheduler paths, prioritizes by complexity, maps business rules | JCL, schedulers | Code analysis. Benefits from BRE |\n| 11 | Generate test data collection scripts | Produces JCL scripts to collect before/after test data from mainframe (Db2 unloads, VSAM REPRO, sequential datasets) | Test plan | Test planning |\n| 12 | Test automation script generation | Generates scripts to execute test cases on the modernized Java application with data setup and result comparison | Test plan | Test planning + test data collection |\n\n## Starting Workflow\n\n1. **Inventory** — Scan for COBOL (.cbl, .cob), JCL (.jcl), copybooks (.cpy), and VSAM definitions\n2. **Scope decision** — Ask user: full rewrite, partial modernization, or re-platform?\n3. **Complete analysis on AWS Transform** — Based on what the customer wants to do, run relevant agents in AWS Transform. Note: the agent always starts with a \"Kick off modernization\" step that requires connector setup and source code location before any analysis begins.\n4. **Build modernized applications with IDE** — Based on scope, draft modernization requirements based on outputs from agents\n\n**Key question to ask user:** \"Can you tell me what you are looking to accomplish today on your mainframe modernization project? Is this a full re-architecture to microservices, or a lift-and-shift to run COBOL on AWS?\"\n\n## Agents & Transforms\n\n| Agent | How to Discover | Purpose |\n| ----------------------------------- | ------------------------------------------ | ---------------------------------------- |\n| Mainframe agent | `list_resources` with `resource: \"agents\"` | End-to-end COBOL → Java/C# modernization |\n| AWS/comprehensive-codebase-analysis | CLI: `atx custom def exec` | Static analysis of COBOL programs |\n\n**Discover the agent dynamically** — do not hardcode the agent name:\n\n```python\n# First, discover available agents\nlist_resources(resource=\"agents\")\n# Or ask the chat agent\nsend_message(workspaceId=\"...\", text=\"What agents are available for mainframe modernization?\")\n# Then create job — two approaches work:\n# Option A: using jobType enum (e.g. MAINFRAME_V2)\ncreate_job(workspaceId=\"...\", jobName=\"...\", jobType=\"MAINFRAME_V2\", objective=\"...\", intent=\"...\")\n# Option B: using orchestratorAgent name\ncreate_job(workspaceId=\"...\", jobName=\"...\", orchestratorAgent=\"\u003cdiscovered>\", objective=\"...\", intent=\"...\")\n```\n\n## Supported File Types\n\nzOS: COBOL + copybooks, JCL + PROC, CSD, BMS, Db2, VSAM, IMS TM, PL/I (BRE and docs only — not refactoring).\nFujitsu GS21: PSAM, ADL, NDB.\n\n## Assessment Signals (for local discovery)\n\nThese patterns help identify mainframe assets during local workspace scanning, before the AWS Transform agent runs its own analysis:\n\n| File Pattern | What to Look For | Indicates |\n| --------------------- | ---------------------------- | ----------------------------- |\n| `*.cbl`, `*.cob` | COBOL source | Mainframe COBOL programs |\n| `*.jcl` | JCL job cards, DD statements | Batch processing |\n| `*.cpy` | COBOL copybooks | Shared data structures |\n| `*.bms` | BMS maps | CICS screen definitions |\n| `EXEC CICS` in source | CICS API calls | Online transaction processing |\n| `EXEC SQL` in source | Embedded SQL | Database access (DB2/IMS) |\n\n## Example Requirements\n\n```\n## Requirement 1: COBOL to Java Conversion\n\n**User Story:** As a developer, I want COBOL batch programs converted to Java services\nso that we can run them on AWS without mainframe infrastructure.\n**Acceptance Criteria:**\n\n1. WHEN conversion is applied, ALL COBOL PERFORM logic SHALL be equivalent Java methods\n2. WHEN conversion is applied, VSAM file I/O SHALL be replaced with database calls\n3. WHEN the Java service runs, output SHALL match COBOL program output for test cases\n **Handled by:** AWS Transform Mainframe Agent\n```\n\n## Example Tasks\n\n```\n- [ ] 1. Inventory and dependency analysis\n - [ ] 1.1 Scan COBOL sources and JCL\n - [ ] 1.2 Map CALL chains and COPY dependencies\n- [ ] 2. Convert COBOL programs to Java (AWS Transform)\n - [ ] 2.1 Start mainframe modernization job\n - [ ] 2.2 Handle Collaborator Requests (data mapping decisions)\n - [ ] 2.3 Review diffs — user approves converted code\n- [ ] 3. Migrate data stores\n - [ ] 3.1 Convert VSAM to Aurora PostgreSQL schema\n - [ ] 3.2 Migrate data\n- [ ] 4. Validation\n - [ ] 4.1 Run test cases comparing COBOL vs Java output\n```\n\n## Known API Behaviors\n\nThese are things that work differently through the MCP API vs the AWS Transform webapp.\n\n### Source Code Upload\n\nThe agent requires source code as a **single .zip file** in S3. When the \"Specify resource location\" task appears, `assetLocation` must point to a `.zip` file.\n\n### Business Logic Extraction (BRE) Configuration\n\nWhen the \"Configure settings\" task appears for BRE (`MainframeBreInputComponent`), you MUST always populate the `userSelectedFiles` array — regardless of `reportScope`.\n\n- `applicationLevel` — produces a single application-wide business rules summary\n- `fileLevel` — produces per-file business rules reports\n\nBoth scopes require the file list. The webapp auto-selects all files for `applicationLevel`, but the API does not — you must explicitly list them.\n\n## Known Limitations\n\n- Assembler programs (ASM) are not handled by AWS Transform agents — the IDE can analyze but not convert\n- PL/I is supported for BRE and documentation only — not for refactoring\n- CICS BMS screen conversion may need manual UI design decisions\n- Complex SORT/MERGE JCL steps may need manual review\n- Performance tuning of converted Java code is not automated\n- Reforge quota: 3M lines of code per job, 50M lines of code per user per month\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9956,"content_sha256":"e9783548cd22a711e864ec9d08667bcddf0fbf43fd2733f81b13f18efdb6b7fb"},{"filename":"references/sql.md","content":"# SQL Database Migration\n\n> **Last Updated:** 2026-04-13\n\n## Capabilities\n\nThis domain handles **SQL database migration via the IDE** using the AWS Transform MCP server. It supports two workflows:\n\n1. **From-Scratch Workflow** — Start a new AWS Transform conversion job entirely from the IDE: authenticate, create a workspace/job, upload source SQL, monitor the conversion, review assessment results, and retrieve converted artifacts.\n2. **Handoff Workflow** — Pick up where an AWS Transform conversion job left off: download converted artifacts and the validation report, then interactively fix all critical and high-severity issues the AWS Transform agent could not fully resolve.\n\nBoth workflows converge at the fix-application phase once converted artifacts and a validation report are available.\n\n```\nFrom-Scratch Workflow Handoff Workflow\n┌──────────────────────────┐ ┌──────────────────────────┐\n│ 1. Authenticate │ │ 1. Collect job IDs │\n│ 2. Create workspace/job │ │ 2. Download artifacts │\n│ 3. Upload source SQL │ └───────────┬──────────────┘\n│ 4. Monitor conversion │ │\n│ 5. Read assessment │ │\n│ 6. Trigger schema conv. │ │\n│ 7. Retrieve artifacts │ │\n└───────────┬──────────────┘ │\n │ ┌─────────────────────────────┘\n ▼ ▼\n┌──────────────────────────────────────────────────┐\n│ Common: Parse report → Fix critical/high issues │\n│ → Validate → Upload → Deploy │\n└──────────────────────────────────────────────────┘\n```\n\n## ⚠️ Agent Behavior Rules (READ FIRST)\n\nThese rules are MANDATORY. Violating any of them is a failure.\n\n> **Cross-platform note.** Commands below are given in two variants where they differ: **macOS/Linux/Git Bash** (POSIX shell: `cp`, `sed`, `perl`, etc.) and **Windows (PowerShell)**. Detect the OS and pick one variant — do not mix. In all PowerShell examples, paths are written with forward slashes (`/`) for readability; PowerShell accepts `/` and `\\` interchangeably, so real Windows paths like `C:\\Users\\alice\\work` can be used verbatim without re-quoting.\n\n1. **Three-file workflow.** Keep the original source MSSQL file, the converted PG file (untouched), and a working copy of the converted PG file. ALL edits go to the working copy. NEVER modify the original source or the converted PG file.\n2. **Navigate before AND after every fix. Skipping navigation is a rule violation.**\n - Detect the IDE from the environment: Kiro → `kiro --goto`, VS Code → `code --goto`, DBeaver → manual navigation.\n - **Before showing a fix**, open the file at the exact line that will change:\n\n ```\n code --goto \u003cworking_copy>:\u003cline_number>\n ```\n\n - **After applying a fix**, navigate back to the changed line so the user sees the result:\n\n ```\n code --goto \u003cworking_copy>:\u003cline_number>\n ```\n\n3. **For every fix, follow this exact sequence:**\n a. **Navigate** to the line (rule 2 above). Do NOT skip this.\n b. **Validate the proposed fix** — Before showing the fix to the user, execute a syntax check (e.g., `EXPLAIN` or parse-only) on the proposed SQL block. If invalid, revise and re-validate. Do NOT propose an invalid fix.\n c. **Show in chat:** object name, line number, problem (from report), proposed before/after fix, and syntax validation result (✅ Passed).\n d. **Ask** `Approve this fix? [Yes / No / Modify]` and **STOP**. Do NOT proceed until the user responds.\n e. **After user approves**, apply the fix using `execute_bash` (NOT `fs_write`). Use `sed -i ''` or `perl -i -pe 's/old/new/g'` on macOS/Linux (Perl works cross-platform when available). On Windows without Git Bash, use PowerShell's literal-string `.Replace()` method (NOT `-replace`, which is a regex operator and will silently mis-match SQL tokens containing regex metacharacters like `[ ] . ( ) $ ^`). Write with `[System.IO.File]::WriteAllLines` and an explicit no-BOM UTF-8 encoding — `Set-Content -Encoding UTF8` on Windows PowerShell 5.1 prepends a UTF-8 BOM (`0xEF 0xBB 0xBF`) that Rule 10's ASCII verification step will flag. Wrap the `-Command` argument in **single quotes** so bash/Git Bash does not expand `$c` / `$false` before PowerShell parses them, and prepend `$ErrorActionPreference='Stop'` so intermediate failures surface instead of silently producing an empty working copy:\n\n ```\n powershell -Command '$ErrorActionPreference=\"Stop\"; $c = (Get-Content \"\u003cworking_copy>\" -Encoding UTF8).Replace(\"old\",\"new\"); [System.IO.File]::WriteAllLines(\"\u003cworking_copy>\", $c, [System.Text.UTF8Encoding]::new($false))'\n ```\n\n If regex matching is actually required, use `-replace [regex]::Escape(\"old\"),\"new\"`. Note: `-replace`'s replacement string interprets `$1`, `$2`, `$`, `{head-tags}`, etc. as regex substitution tokens, so if the replacement text contains literal ` aws-transform — Skillopedia characters (common in PostgreSQL dollar-quoting like `$`, `$BODY aws-transform — Skillopedia ), double them: `-replace [regex]::Escape(\"old\"), \"new\".Replace(\"$\",\"$\")`.\n f. **Navigate back** to the changed line (rule 2 above). Do NOT skip this.\n4. **Diff after every cluster.** After completing all fixes in a cluster, show a three-way diff comparing the original source MSSQL, the converted PG file, and the working copy.\n\n **Empty-diff guard (used by every IDE branch below):** Before showing the second diff (converted PG vs working copy), check whether the two files are identical. If they are, skip the second diff and tell the user: \"No fixes have been applied yet — the converted PG file and working copy are still identical.\"\n - macOS/Linux/Git Bash: `diff --brief \u003cconverted_pg> \u003cworking_copy>` (exit 0 = identical)\n - Windows (PowerShell): `powershell -Command \"if ((Get-FileHash '\u003cconverted_pg>').Hash -eq (Get-FileHash '\u003cworking_copy>').Hash) { exit 0 } else { exit 1 }\"` (exit 0 = identical)\n\n - **VS Code:** Open two diffs side by side:\n `code --diff \u003csource_mssql> \u003cconverted_pg>`\n Only if the converted PG file and working copy differ (empty-diff guard above):\n `code --diff \u003cconverted_pg> \u003cworking_copy>`\n - **Kiro:** Open two diffs side by side:\n `kiro --diff \u003csource_mssql> \u003cconverted_pg>`\n Only if the converted PG file and working copy differ (empty-diff guard above):\n `kiro --diff \u003cconverted_pg> \u003cworking_copy>`\n - **DBeaver:** Use the SQL Compare feature or an external diff tool\n - **Fallback:** If the IDE diff commands do not produce visible results, generate text-based diffs in chat.\n - macOS/Linux/Git Bash:\n `diff -u \u003csource_mssql> \u003cconverted_pg>`\n Only if the converted PG file and working copy differ (empty-diff guard above):\n `diff -u \u003cconverted_pg> \u003cworking_copy>`\n - Windows (PowerShell): use `Compare-Object`:\n `powershell -Command \"Compare-Object (Get-Content '\u003csource_mssql>' -Encoding UTF8) (Get-Content '\u003cconverted_pg>' -Encoding UTF8)\"`\n Only if the converted PG file and working copy differ (empty-diff guard above):\n `powershell -Command \"Compare-Object (Get-Content '\u003cconverted_pg>' -Encoding UTF8) (Get-Content '\u003cworking_copy>' -Encoding UTF8)\"`\n Note: `Compare-Object` output is a side-indicator list (`\u003c=` for left-only, `=>` for right-only) rather than unified-diff format. Show the output to the user as-is — it conveys the same information in a different layout.\n If two diffs were shown, tell the user:\n > \"Two diff views have been opened: one comparing the source MSSQL with the converted PG file (showing what the conversion changed), and one comparing the converted PG file with the working copy (showing what fixes have been applied). You may need to arrange the diff tabs side by side.\"\n > Then ask the user:\n > \"Cluster fixes applied. Would you like to upload the working copy to AWS Transform for re-validation before proceeding to the next cluster? [Yes / No]\"\n - If **Yes**: Prepare a ZIP artifact for re-validation:\n 1. Create the staging directory:\n - macOS/Linux/Git Bash: `execute_bash: mkdir -p \u003cworking_directory>/zip_staging`\n - Windows (PowerShell): `execute_bash: powershell -Command \"New-Item -ItemType Directory -Force -Path '\u003cworking_directory>/zip_staging'\"`\n 2. Copy the working copy as `postgres-completed-deployment.sql`:\n - macOS/Linux/Git Bash: `execute_bash: cp \u003cworking_copy> \u003cworking_directory>/zip_staging/postgres-completed-deployment.sql`\n - Windows (PowerShell): `execute_bash: powershell -Command \"Copy-Item '\u003cworking_copy>' '\u003cworking_directory>/zip_staging/postgres-completed-deployment.sql'\"`\n 3. Copy the custom rules file(s) from the working directory:\n - macOS/Linux/Git Bash: `execute_bash: cp \u003cworking_directory>/\u003crule_file> \u003cworking_directory>/zip_staging/\u003crule_file>`\n - Windows (PowerShell): `execute_bash: powershell -Command \"Copy-Item '\u003cworking_directory>/\u003crule_file>' '\u003cworking_directory>/zip_staging/\u003crule_file>'\"`\n 4. Create `manifest.json` in `zip_staging/` with database name, execution order (`file: \"postgres-completed-deployment.sql\"`, `type: \"all\"`, `object_count: \u003ccount of CREATE statements>`), and `\"custom_rules\"` listing the custom rules filenames\n 5. Create ZIP:\n - macOS/Linux: `execute_bash: cd \u003cworking_directory>/zip_staging && rm -f ../IDE_CONVERTED_DB_ARTIFACT.zip && zip ../IDE_CONVERTED_DB_ARTIFACT.zip *`\n - Windows: `execute_bash: powershell -Command \"Compress-Archive -Path '\u003cworking_directory>/zip_staging/*' -DestinationPath '\u003cworking_directory>/IDE_CONVERTED_DB_ARTIFACT.zip' -Force\"`\n 6. Clean up:\n - macOS/Linux/Git Bash: `execute_bash: rm -rf \u003cworking_directory>/zip_staging`\n - Windows (PowerShell): `execute_bash: powershell -Command \"Remove-Item -Recurse -Force '\u003cworking_directory>/zip_staging'\"`\n 7. Upload via `upload_artifact` with `content=\"\u003cworking_directory>/IDE_CONVERTED_DB_ARTIFACT.zip\"`, `fileName=\"IDE_CONVERTED_DB_ARTIFACT\"`, `fileType=\"ZIP\"`, `categoryType=\"CUSTOMER_INPUT\"`.\n 8. Send `send_message` with text \"IDE agent completed all critical and high-severity fixes. Uploaded corrected file as IDE_CONVERTED_DB_ARTIFACT. Ready for re-validation through invoke_validation_after_ide with new artifact id:`\u003cartifactId>`\". Poll messages for \"Validation complete\", download new report, and present results. If new issues are found in this cluster, fix them before moving on.\n - If **No**: Proceed to the next cluster.\n5. **No scripts.** Do NOT write Python, Bash, or any scripts to batch-process fixes.\n6. **Use `sed`, `perl`, or PowerShell for file edits, NOT `fs_write`.** Large SQL files (10K+ lines) cause the editor to freeze when using `fs_write`. Use `execute_bash` to edit the working copy directly on disk:\n - macOS/Linux/Git Bash: `sed -i '' 's/old/new/g' \u003cworking_copy>` or `perl -i -pe 's/old/new/g' \u003cworking_copy>`\n - Windows (PowerShell): use the literal-string `.Replace()` method (NOT `-replace`, which is a regex operator). Read with `Get-Content -Encoding UTF8` to avoid Windows PowerShell 5.1's ANSI code-page corruption, and write with `[System.IO.File]::WriteAllLines` + no-BOM UTF-8 (NOT `Set-Content -Encoding UTF8`, which prepends a UTF-8 BOM on PS 5.1 that Rule 10's ASCII verification will flag). Wrap the `-Command` argument in **single quotes** so bash/Git Bash does not expand `$c` / `$false` before PowerShell parses them, and prepend `$ErrorActionPreference='Stop'` so intermediate failures surface instead of silently producing an empty working copy: `powershell -Command '$ErrorActionPreference=\"Stop\"; $c = (Get-Content \"\u003cworking_copy>\" -Encoding UTF8).Replace(\"old\",\"new\"); [System.IO.File]::WriteAllLines(\"\u003cworking_copy>\", $c, [System.Text.UTF8Encoding]::new($false))'`. Use `-replace [regex]::Escape(\"old\"),\"new\"` only if regex matching is actually required; when using `-replace`, also double any literal ` aws-transform — Skillopedia in the replacement string (`\"new\".Replace(\"$\",\"$\")`) because `-replace` interprets `$1`, `$`, etc. as regex substitution tokens — which silently corrupts PostgreSQL dollar-quoting like `$` and `$BODY aws-transform — Skillopedia .\n7. **No bulk operations.** Fix one object at a time.\n8. **No invented fixes.** Only apply fixes described in the validation report.\n9. **Report every fix in chat** with: object name, line number in working copy, problem (from report), proposed fix, and updated progress table.\n10. **Encoding safety before upload.** Before creating a ZIP for upload, sanitize non-ASCII characters that can corrupt during ZIP packaging and cause the validator to fail with `total_checks: 0`.\n\n**Sanitize and verify (cross-platform, using Perl):**\n\n```\nperl -i -CSD -pe \"s/\\x{2014}/--/g; s/\\x{2013}/-/g; s/[\\x{2018}\\x{2019}]/'/g; s/[\\x{201c}\\x{201d}]/\\\"/g; s/\\x{2026}/.../g; s/\\x{a0}/ /g\" \u003cworking_copy>\nperl -ne 'if(/[^\\x00-\\x7F]/){print \"$ARGV:$.: $_\"; $f++} END{exit !$f}' \u003cworking_copy> || echo \"Clean: ASCII only\"\n```\n\nPerl is available on macOS and Linux by default, and on Windows via Git Bash.\n\n**Windows alternative (PowerShell):**\n\n```\npowershell -Command \"\n $text = [IO.File]::ReadAllText('\u003cworking_copy>', [Text.Encoding]::UTF8);\n $text = $text -replace '\\u2014','--' -replace '\\u2013','-' -replace '[\\u2018\\u2019]',\\\"'\\\" -replace '[\\u201c\\u201d]','\\\"' -replace '\\u2026','...' -replace '\\u00a0',' ';\n $utf8NoBom = New-Object System.Text.UTF8Encoding $false;\n [IO.File]::WriteAllText('\u003cworking_copy>', $text, $utf8NoBom);\n if ($text -match '[^\\x00-\\x7F]') { Write-Host 'WARNING: non-ASCII characters remain' } else { Write-Host 'Clean: ASCII only' }\n\"\n```\n\nCommon offenders: em-dash (`—`), en-dash (`–`), smart quotes (`\"\"''`). These appear in MSSQL-generated comment headers and corrupt from UTF-8 to Windows-1252 `0x97` during ZIP packaging.\n\n---\n\n## From-Scratch Workflow\n\nUse this workflow when starting a new MSSQL → PostgreSQL conversion entirely from the IDE. If you already have a completed AWS Transform job with artifacts, skip to the **Handoff Workflow** section.\n\n### Step 1: Authentication\n\n- **Cookie auth requires the Transform app URL** — Ask the user for their Transform app URL (e.g., `https://xxxxxxxx.transform.us-east-1.on.aws`).\n- Do **not** use the SSO/IdC start URL (`https://d-xxx.awsapps.com/start`).\n- If the auth cookie has expired, ask the user for a new one.\n\n### Step 2: Create Workspace and Job\n\n- **Unless the user explicitly says to create a new workspace/job, always ask first:**\n > \"Do you have an existing AWS Transform workspace or job you'd like to reuse, or should I create new ones?\"\n- **If reusing an existing workspace:** List all available workspaces so the user can see names and IDs, then ask which one to use. Then ask if they also have an existing job to reuse or need a new job in that workspace.\n- **If reusing an existing job:** List all jobs in the selected workspace so the user can see job names and IDs, then ask which one to use. Use artifact store tools to check what outputs the agent has already produced — the job may already be past the upload or assessment phase.\n- **If creating a new workspace:** Names must match `[a-zA-Z0-9]+(?:[-_\\.][a-zA-Z0-9]+)*` — no spaces allowed.\n- **If creating a new job:** MSSQL to PostgreSQL conversion uses `WINDOWS_DATABASE` (SQL Server modernization) as the job type.\n- **Always choose MSSQL file upload (NOT the connect-to-database option) after starting the job.**\n\n### Step 3: SQL File Upload\n\n- The source SQL file can be either a `.sql` file or a `.zip` archive containing SQL files. Both formats are accepted by AWS Transform. **Upload the file as-is — do NOT zip a `.sql` file before uploading.**\n- If the ActiveFile is a mssql file, use that.\n- If not, ask for user's permission and search locally for files — use `fileSearch` to find `.sql` or `.zip` files on the user's machine instead of asking for the full path.\n- Upload the file as an artifact first using `upload_artifact`.\n- Then send the artifact reference in chat using the URI format:\n\n ```\n aws-transform://workspaces/{workspaceId}/jobs/{jobId}/artifacts/{artifactId}\n ```\n\n- **Don't send bare artifact IDs** — the agent won't recognize them. It needs the full `aws-transform://` URI.\n\n### Step 4: Interacting with the Agent\n\n- **Always use `send_message` as the primary form of communication with the job agent.**\n- **Messages can have interaction buttons** — Agent messages include `SELECT` interactions with options. Respond by sending the option's `value` as a chat message.\n\n### Step 5: Monitoring Job Progress\n\n- The job is carried out by AWS Transform agents; all communication and updates are wired through them.\n- **Always check all three**: messages, worklogs, and HITL tasks.\n- **Worklogs** are the most granular progress indicator — they update more frequently than messages and show the agent's internal reasoning/actions step by step.\n- **Messages** show user-facing interactions with SELECT options (e.g. \"MSSQL to PostgreSQL\", \"Upload DDL files\").\n- **HITL tasks** may or may not appear — the agent can request input via chat messages instead.\n- **No HITL tasks doesn't mean no input needed** — The job can be in `AWAITING_HUMAN_INPUT` with no HITL tasks; input is expected via chat messages.\n- Jobs go through phases: `STARTING` → `PLANNING` → `AWAITING_HUMAN_INPUT` → active processing.\n- The `input_setup` step handles file ingestion before moving to `discovery`.\n- Planning can take a few minutes — no tasks or messages will appear until it completes.\n\n**Polling loop (mandatory throughout the job lifecycle):**\n\nAfter any action that triggers agent work (file upload, schema conversion, etc.), enter a polling loop:\n\n1. Use **mcp-sleep** to wait 10 seconds.\n2. Check messages, worklogs, and HITL tasks.\n3. **Format timestamps** — Worklog and message timestamps may be returned as epoch milliseconds or numeric values (e.g., `140638`). Always convert these to human-readable format (e.g., `2026-04-13 21:06:38 UTC`) before displaying to the user.\n4. If the agent sent a message requiring a response (SELECT options, questions, or `AWAITING_HUMAN_INPUT` status), respond or prompt the user.\n5. If the agent is still processing (no new actionable messages), go back to step 1.\n6. Continue polling until the current phase completes (e.g., assessment report is ready, schema conversion finishes, validation completes).\n\nDo NOT stop polling prematurely — always keep the loop running until there is a clear completion signal or user input is needed.\n\n### Step 6: Reading Assessment Results\n\n- Download the assessment report zip artifact.\n- Extract the zip file and review all contents — it typically contains PDF reports and CSV data files.\n- **PDF reports:**\n - `assessment_summary.pdf` is a short document with a summary of the assessment.\n - The other report PDF is a longer document with detailed findings of migration issues with the database.\n- **CSV files:** Contain structured data such as object inventories, issue lists, and migration action items. Read and present these to the user — they are useful for programmatic analysis and tracking.\n\n### Step 7: Schema Conversion\n\n- When the user is ready to proceed towards schema conversion, send this intent to the agent.\n- **Custom transformation rules:** During conversion, the AWS Transform agent may ask about custom transformation rules. **Do NOT assume default rules.** Always ask the user:\n > \"The conversion agent is asking about custom transformation rules. Do you have custom rules to upload, or should I proceed with default rules?\"\n > Only proceed with defaults if the user explicitly confirms.\n- Schema conversion is a long-running process — expect to poll for job progress (see Step 5).\n- After the schema conversion report is available, review it with the user. **Do NOT skip ahead to downloading the converted PostgreSQL file** — it is not available yet.\n- The converted PostgreSQL SQL file is only produced after the **target DB deployment workflow** completes. After reviewing the conversion report, continue interacting with the AWS Transform agent to proceed through the deployment workflow (see Step 8).\n\n### Step 8: Target DB Deployment\n\n- After schema conversion and report review, the AWS Transform agent will guide the workflow toward deploying the converted schema to the target PostgreSQL database.\n- Continue polling and responding to the agent's messages through this phase (see Step 5).\n- **Do NOT assume the user already has a target database cluster.** The deployment flow requires setting up a DB connector first.\n\n**DB Connector Setup:**\n\nThe AWS Transform agent will issue a HITL task to set up a DB connector. Before creating a new one, check if the workspace already has a connector configured:\n\n1. **List existing connectors** in the workspace first. If connectors exist, present them to the user:\n > \"This workspace already has the following DB connector(s) configured:\n >\n > - `\u003cconnector name>` — `\u003cconnection details>`\n >\n > Would you like to use an existing connector, or set up a new one?\"\n2. **If the user picks an existing connector**, use that and skip connector creation.\n3. **If a new connector is needed**, the HITL task will require details from the user. Ask for:\n - AWS Account ID\n - Any other connection parameters the HITL task requests (e.g., database endpoint, credentials, VPC details)\n\n Do NOT guess or assume any of these values — always ask the user.\n\n- **The converted PostgreSQL SQL file (`ATX_CONVERTED_DB_ARTIFACT` or `postgres-completed-deployment.sql`) is only available as an artifact after the deployment workflow completes.** Do NOT attempt to download it before this point — it won't exist yet.\n- Once deployment finishes, proceed to retrieve the artifacts (see Step 9).\n\n### Step 9: Retrieving Conversion Artifacts\n\n```\n# List all artifacts from the completed AWS Transform job\nlist_resources resource=\"artifacts\" workspaceId=\"\u003cworkspaceId>\" jobId=\"\u003cjobId>\"\n```\n\nScan the returned list for matching artifact names/labels. AWS Transform MCP does not support filtering by label — you must list all, then match.\n\n- **Scan for converted database artifacts:** Look for all artifacts with `fileMetadata.path` starting with `ATX_CONVERTED_DB_ARTIFACT`. Each artifact represents a converted database, with the database name as the suffix: `ATX_CONVERTED_DB_ARTIFACT_\u003cdbName>`.\n\n Extract the database names and present them to the user:\n > \"Converted artifacts are available for **N** database(s):\n >\n > 1. `OrdersDB`\n > 2. `InventoryDB`\n > 3. `AuditDB`\n >\n > Which database would you like to work on?\"\n\n Wait for the user to choose. Then download the selected artifact:\n\n ```\n get_resource resource=\"artifact\" workspaceId=\"\u003cworkspaceId>\" jobId=\"\u003cjobId>\" artifactId=\"\u003cmatched-id>\" savePath=\"/local/path/ATX_CONVERTED_DB_ARTIFACT_\u003cdbName>.zip\"\n ```\n\n Extract the ZIP — contains: `sourcesql/`, `targetsql/`, `validationreport/`. Read `targetsql/manifest.json` to discover the converted SQL files and custom rules — file paths in the manifest are relative to `targetsql/`.\n\n- **Fallback (single artifact):** If no `ATX_CONVERTED_DB_ARTIFACT_*` artifacts are found, look for a single `ATX_CONVERTED_DB_ARTIFACT` (no suffix) and use it directly.\n\n- **Fallback (individual artifacts):** If no ZIP artifacts found, look for:\n - `postgres-completed-deployment.sql` → converted PG file\n - `Schema Conversion Report` → validation report\n - Then ask user for the source SQL file path\n\nOnce artifacts are retrieved, proceed to the **Common Workflow** section below.\n\n---\n\n## Handoff Workflow\n\nUse this workflow when an AWS Transform conversion job has already completed and you need to pick up the remaining fixes in the IDE.\n\n### Why IDE Handover\n\nThe IDE agent complements the AWS Transform agentic flow by providing capabilities that a managed batch pipeline cannot:\n\n- **Interactive fixing** — Apply a fix, show the user the exact change, wait for approval or adjustment, then proceed.\n- **Cross-object awareness** — The IDE has the full converted file open and can cross-reference across procedures, views, and tables while editing.\n- **Granular human-in-the-loop** — Pause at every individual object for user approval instead of coarse-grained job checkpoints.\n- **Local tooling** — Run PostgreSQL syntax validation locally, show diffs, and use language intelligence for SQL editing.\n- **Long-tail remediation** — Remaining broken objects each have unique issues requiring case-by-case judgment.\n- **Full transparency** — Every fix is reported in chat with what changed and why.\n\n### What AWS Transform Handles vs What the IDE Agent Handles\n\n| Responsibility | AWS Transform Transform Agent | IDE Agent (this steering) |\n| ---------------------------------- | ----------------------------- | --------------------------------------------- |\n| Schema conversion (DDL) | ✅ | — |\n| Bulk stored proc rewrite | ✅ | Fix remaining broken procs flagged in report |\n| Data type mapping | ✅ | Fix type mapping violations flagged in report |\n| View creation | ✅ | Resolve failed views flagged in report |\n| Index migration | ✅ | Re-create missing indexes flagged in report |\n| Validation report generation | ✅ | Parse and act on report |\n| Critical/high-severity remediation | — | ✅ |\n| Application code changes | — | Out of scope (flag for user) |\n\n### Step 1: Collect AWS Transform Job Context\n\nPrompt user for AWS Transform job identifiers:\n\n- `workspaceId` — The AWS Transform workspace where the conversion job ran\n- `jobId` — The AWS Transform job that performed the MSSQL → PostgreSQL conversion\n- `agentInstanceId` — The agent instance that produced the conversion artifacts\n\n### Step 2: Retrieve Artifacts from AWS Transform\n\nOnce the user provides identifiers, list all job artifacts and match by name/label:\n\n```\n# List all artifacts\nlist_resources resource=\"artifacts\" workspaceId=\"\u003cworkspaceId>\" jobId=\"\u003cjobId>\"\n```\n\n- **Scan for converted database artifacts:** Look for all artifacts with `fileMetadata.path` starting with `ATX_CONVERTED_DB_ARTIFACT`. Each artifact represents a converted database: `ATX_CONVERTED_DB_ARTIFACT_\u003cdbName>`.\n\n Extract the database names and present them:\n > \"This job has converted artifacts for **N** database(s):\n >\n > 1. `OrdersDB`\n > 2. `InventoryDB`\n >\n > Which database would you like to fix?\"\n\n Wait for the user to choose. Then download:\n\n ```\n get_resource resource=\"artifact\" workspaceId=\"\u003cworkspaceId>\" jobId=\"\u003cjobId>\" artifactId=\"\u003cmatched-id>\" savePath=\"/local/path/ATX_CONVERTED_DB_ARTIFACT_\u003cdbName>.zip\"\n ```\n\n Extract the ZIP — contains: `sourcesql/`, `targetsql/`, `validationreport/`. Read `targetsql/manifest.json` to discover the converted SQL files and custom rules — file paths in the manifest are relative to `targetsql/`.\n\n- **Fallback (single artifact):** If no `ATX_CONVERTED_DB_ARTIFACT_*` found, look for a single `ATX_CONVERTED_DB_ARTIFACT` (no suffix) and use it directly.\n\n- **Fallback (individual artifacts):** If no ZIP artifacts found, scan for:\n - `postgres-completed-deployment.sql` → converted PG file\n - `Schema Conversion Report` → validation report\n - Ask user for the source SQL file separately\n\n- **Fallback (no artifacts):** If no artifacts found or AWS Transform job not referenced, ask user for local file paths to:\n - Original source SQL file (T-SQL / SQL Server)\n - Converted PostgreSQL SQL file\n - Conversion validation report (HTML or text)\n\nOnce artifacts are retrieved, proceed to the **Common Workflow** section below.\n\n---\n\n## Common Workflow (Both Paths Converge Here)\n\nOnce you have the source SQL, converted PostgreSQL SQL, and validation report — regardless of whether you arrived via the from-scratch or handoff path — follow these steps.\n\n### Step 1: Check PostgreSQL Extension\n\nVerify the user has a PostgreSQL extension installed in their IDE. If not installed, ask:\n\n> \"A PostgreSQL extension is required to validate fixes before applying them. Please install one:\n>\n> - **VS Code:** Install `ms-ossdata.vscode-postgresql` or `ckolkman.vscode-postgres` from the Extensions marketplace\n> - **Kiro:** Install the PostgreSQL extension from the Extensions panel\n> - **DBeaver:** Built-in — no additional install needed\n>\n> Once installed, configure a connection profile for the target Aurora PostgreSQL cluster and let me know the profile name.\"\n\n### Step 2: Set Fix Autonomy Mode\n\nAsk the user:\n\n> \"How should I handle fix approvals?\n>\n> - **per-fix** (default) — I propose each fix and wait for your approval before applying it\n> - **per-cluster** — I show proposed fixes for the first 2–3 issues in a cluster so you can review the approach, then apply all fixes in the cluster after your approval. A cluster diff is shown after applying.\n> - **autonomous** — I apply all critical/high fixes end-to-end and present a full diff and summary at the end\n>\n> Choose [per-fix / per-cluster / autonomous]:\"\n\nStore the chosen mode for the session. The user can switch mid-session by saying e.g. `\"Switch to per-cluster mode\"`. Mode affects approval behavior:\n\n- `per-fix` — Rule 2d (approval prompt before every fix) is enforced.\n- `per-cluster` — Rule 2d is skipped. The agent shows proposed before/after fixes for the first 2–3 issues as a preview, asks for approval, then applies all fixes in the cluster. Rule 3 (cluster diff) is shown after applying.\n- `autonomous` — Rules 2d and 3 approval prompts are skipped. Fixes are still logged in chat (Rule 8) and a final summary is shown.\n\n### Step 3: Present Available Commands\n\nBefore starting fixes, inform the user:\n\n> \"Before we begin, here's what you can ask me to do at any time:\n>\n> - **Show diff** — Display a diff of all changes made so far (three-way diff of source MSSQL, converted PG, and working copy). The converted PG vs working copy diff is skipped if the files are still identical.\n> - **Run validation** — Upload the working copy to AWS Transform for functional re-validation and get a new report\n> - **Show progress** — Print the current progress table with cluster statuses\n> - **Switch autonomy mode** — Change fix approval mode (per-fix / per-cluster / autonomous)\n> - **Skip cluster** — Skip the current cluster and move to the next one\n> - **Revert cluster** — Undo all fixes in the current cluster\n> - **Fix a medium/low item** — Ask me to fix a specific advisory item\n> - **I'm done** — End the session, upload the final file to AWS Transform, and optionally deploy\n>\n> Let's start.\"\n\n### Step 4: Parse Report and Prioritize\n\n1. **Parse the Issue Clusters table** — Each row has a severity emoji (🔴🟠🟡🟢), a description, and a score deduction.\n2. **Filter to critical and high** — Only 🔴 Critical and 🟠 High clusters are in scope for auto-fixing.\n3. **For each in-scope cluster, read \"What Needs Immediate Attention\"** — Contains affected objects, risk description, and recommended SQL fixes.\n4. **For medium/low clusters** — Present as advisory items. Do not auto-fix unless user explicitly requests.\n5. **For info/warning items** — Note in summary but take no action.\n6. **Separate load failures from conversion defects** — Schema Loading Notes distinguish objects that failed to load due to missing dependencies vs true migration issues.\n7. **Read the custom rules file** — Parse the custom rules JSON from `targetsql/` (listed in `manifest.json`'s `custom_rules` array). Understand the current type mappings, extensions, and naming conventions. This context is needed when applying fixes — if a fix contradicts or extends these rules, you'll update the custom rules file in Step 6 (and verify in Step 7).\n\n### Step 5: Set Up Three-File Workflow\n\n1. **Ensure the working directory is trusted** — Ask the user:\n > \"Which directory should I use for the working files? It should be a directory already open and trusted in your IDE. This avoids permission prompts that can freeze the chat.\"\n\n2. Read `targetsql/manifest.json` to identify the converted SQL file(s) from `execution_order` and the custom rules file(s) from `custom_rules`. File paths in the manifest are relative to `targetsql/`.\n3. Copy the converted PG file (the first `file` in `execution_order`) to a working copy (e.g., `postgres-deployment-fixing.sql`). Keep the original converted PG file as a read-only reference. All fixes go to the working copy only.\n4. Copy the custom rules file(s) to the working directory. All custom rules edits go to this working copy — the original in `targetsql/` stays untouched.\n - macOS/Linux/Git Bash: `cp \u003ctargetsql>/\u003crule_file> \u003cworking_directory>/\u003crule_file>`\n - Windows (PowerShell): `powershell -Command \"Copy-Item '\u003ctargetsql>/\u003crule_file>' '\u003cworking_directory>/\u003crule_file>'\"`\n5. Open the source SQL, converted PG file, and working copy in the editor:\n - **Kiro:** `kiro \u003csourcesql/source.sql>` then `kiro --reuse-window \u003ctargetsql/converted.sql>` then `kiro --reuse-window \u003cworking_copy>`\n - **VS Code:** `code \u003csourcesql/source.sql> \u003ctargetsql/converted.sql> \u003cworking_copy>`\n - **DBeaver:** Open all files via File → Open\n6. Tell the user:\n > \"I've opened three files: the source MSSQL, the converted PG file, and the working copy. You can arrange them side by side. The source MSSQL and converted PG files are for reference only — all fixes go to the working copy.\"\n\n### Step 6: Apply Fixes in Priority Order\n\nApply fixes in dependency order to avoid cascading failures:\n\n1. **Prerequisites** — Extensions, schemas, and any infrastructure the report identifies as missing\n2. **Type/column fixes** — Data type corrections flagged as critical or high\n3. **Views** — Resolve dependency issues, then re-create failed views in order\n4. **Stored procedures and functions** — Apply each fix pattern described in the report\n5. **Indexes** — Re-create missing indexes\n6. **Validate** — Confirm syntax validity and that all critical/high items are addressed\n\n**Custom rules — update as you go:** When a fix establishes a reusable conversion pattern (type mapping, extension, naming), update the custom rules file immediately:\n\n- **Overwriting an existing rule** (e.g., changing `BIT → BOOLEAN` to `BIT → NUMERIC`) → **ask the user for confirmation** before modifying. Do NOT overwrite silently.\n- **Adding a new rule** → In per-fix mode, ask confirmation. In per-cluster/autonomous mode, just inform the user and add it.\n\nThis keeps custom rules in sync with the actual conversion. Validation uses these rules to score — inaccurate rules cause false positives.\n\n### Step 7: Verify Custom Rules\n\n**Why this matters:** The validation sub-agent uses the custom rules file to score the conversion. If the custom rules don't reflect the actual type mappings and patterns used in the converted SQL, validation will flag false positives and lower the score. Keeping custom rules accurate ensures validation results are meaningful.\n\nBefore uploading, verify that the custom rules file reflects all conversion patterns applied during this session:\n\n1. **Review changes made** — For each fix that changed a type mapping, added an extension, or established a naming pattern, confirm the custom rules file was updated during Step 6.\n2. **Check for missed updates** — If any fixes were applied that should have updated custom rules but didn't (e.g., you changed a `BIT` column to `NUMERIC` but the rules still say `BIT → BOOLEAN`), update them now following the rules below.\n3. **Confirm with user if overwriting** — If any rule was modified (not just added), confirm the user approved the change during Step 6. If not, ask now.\n\n**Custom rules file format:**\n\n```json\n{\n \"extensions\": {\n \"base_extensions\": [\"citext\", \"uuid-ossp\", \"pgcrypto\"],\n \"additional_extensions\": []\n },\n \"type_mappings\": [\n {\n \"rule-id\": \"\u003cunique_id>\",\n \"rule-name\": \"\",\n \"source-type\": \"\u003cMSSQL_TYPE>\",\n \"target-type\": \"\u003cPOSTGRESQL_TYPE>\",\n \"precision\": null,\n \"scale\": null\n }\n ],\n \"naming\": {\n \"casing\": \"lowercase\",\n \"schema_mappings\": {},\n \"strip_schema_prefixes\": []\n }\n}\n```\n\n**What to update:**\n\n- **Type mapping fixes** → Add or modify entries in `type_mappings`. Use a descriptive `rule-id` (e.g., \"bit\", \"money\").\n- **Extension requirements** → Add to `extensions.additional_extensions` if a fix requires a PostgreSQL extension not in `base_extensions`.\n- **Naming conventions** → Update `naming.schema_mappings` or `naming.casing` if applicable.\n\nSave the updated custom rules file to the working directory. It will be included in the next upload ZIP (Step 8 uses the updated version).\n\n### Step 8: Upload Fixed File to AWS Transform\n\n#### Copy working copy and upload to artifact store\n\n- macOS/Linux/Git Bash:\n\n ```\n execute_bash: cp \u003cworking_copy> \u003cworking_directory>/postgres-completed-deployment.sql\n ```\n\n- Windows (PowerShell):\n\n ```\n execute_bash: powershell -Command \"Copy-Item '\u003cworking_copy>' '\u003cworking_directory>/postgres-completed-deployment.sql'\"\n ```\n\n```\nupload_artifact(\n workspaceId=\"\u003cworkspaceId>\",\n jobId=\"\u003cjobId>\",\n content=\"\u003cworking_directory>/postgres-completed-deployment.sql\",\n fileName=\"IDE_CONVERTED_DB_ARTIFACT\",\n fileType=\"TXT\",\n categoryType=\"CUSTOMER_INPUT\"\n)\n```\n\n#### Notify the AWS Transform job chat\n\n```\nsend_message(\n workspaceId=\"\u003cworkspaceId>\",\n jobId=\"\u003cjobId>\",\n text=\"IDE agent completed all critical and high-severity fixes. Uploaded corrected file as IDE_CONVERTED_DB_ARTIFACT. Ready for re-validation through invoke_validation_after_ide with new artifact id:\u003cartifactId>\"\n)\n```\n\n### Step 9: Monitor Validation and Continue\n\nPoll AWS Transform job messages for validation status updates:\n\n```\nlist_resources(\n resource=\"messages\",\n workspaceId=\"\u003cworkspaceId>\",\n jobId=\"\u003cjobId>\"\n)\n```\n\nFilter for messages containing \"validation\". Display matching messages to show progress. Re-poll every 10 seconds until a message containing **\"Validation complete\"** appears. Use the **mcp-sleep** tool between polls.\n\nWhen \"Validation complete\" is found, extract the artifact ID from the message and download the new report:\n\n```\nget_resource(\n resource=\"artifact\",\n workspaceId=\"\u003cworkspaceId>\",\n jobId=\"\u003cjobId>\",\n artifactId=\"\u003cartifactId from validation complete message>\",\n savePath=\"\u003cworking_directory>/validation_report_latest.html\"\n)\n```\n\nPrompt the user:\n\n> \"Validation is complete. New report downloaded.\n>\n> Would you like to:\n>\n> 1. **Review & fix** — Parse the new report and apply another round of fixes\n> 2. **Deploy** — Accept the current state and deploy to the target database\n>\n> Choose [1] or [2]:\"\n\n- **If 1:** Go back to Step 4 (Parse Report and Prioritize).\n- **If 2:** Prepare and upload the final converted artifact before deployment:\n 1. Prepare a ZIP bundle in a staging directory:\n - Create the staging directory:\n - macOS/Linux/Git Bash: `execute_bash: mkdir -p \u003cworking_directory>/zip_staging`\n - Windows (PowerShell): `execute_bash: powershell -Command \"New-Item -ItemType Directory -Force -Path '\u003cworking_directory>/zip_staging'\"`\n - Copy working copy as `postgres-completed-deployment.sql`:\n - macOS/Linux/Git Bash: `execute_bash: cp \u003cworking_copy> \u003cworking_directory>/zip_staging/postgres-completed-deployment.sql`\n - Windows (PowerShell): `execute_bash: powershell -Command \"Copy-Item '\u003cworking_copy>' '\u003cworking_directory>/zip_staging/postgres-completed-deployment.sql'\"`\n - Copy the custom rules file(s) from the working directory:\n - macOS/Linux/Git Bash: `execute_bash: cp \u003cworking_directory>/\u003crule_file> \u003cworking_directory>/zip_staging/\u003crule_file>`\n - Windows (PowerShell): `execute_bash: powershell -Command \"Copy-Item '\u003cworking_directory>/\u003crule_file>' '\u003cworking_directory>/zip_staging/\u003crule_file>'\"`\n - Create `manifest.json` with database name, execution order (`file: \"postgres-completed-deployment.sql\"`, `type: \"all\"`, `object_count: \u003ccount of CREATE statements>`), and `\"custom_rules\"` listing the custom rules filenames\n 2. Create ZIP:\n - macOS/Linux: `execute_bash: cd \u003cworking_directory>/zip_staging && rm -f ../IDE_CONVERTED_DB_ARTIFACT.zip && zip ../IDE_CONVERTED_DB_ARTIFACT.zip *`\n - Windows: `execute_bash: powershell -Command \"Compress-Archive -Path '\u003cworking_directory>/zip_staging/*' -DestinationPath '\u003cworking_directory>/IDE_CONVERTED_DB_ARTIFACT.zip' -Force\"`\n 3. Clean up:\n - macOS/Linux/Git Bash: `execute_bash: rm -rf \u003cworking_directory>/zip_staging`\n - Windows (PowerShell): `execute_bash: powershell -Command \"Remove-Item -Recurse -Force '\u003cworking_directory>/zip_staging'\"`\n 4. Upload via `upload_artifact` with `fileName=\"IDE_CONVERTED_DB_ARTIFACT\"`, `fileType=\"ZIP\"`, `categoryType=\"CUSTOMER_INPUT\"`.\n 5. Send a message to the AWS Transform job with the artifact ID:\n\n ```\n send_message(\n workspaceId=\"\u003cworkspaceId>\",\n jobId=\"\u003cjobId>\",\n text=\"IDE agent completed all fixes. Final converted artifact uploaded as IDE_CONVERTED_DB_ARTIFACT (artifactId: \u003cartifactId>). Ready for deployment.\"\n )\n ```\n\n 6. Proceed with deployment via AWS Transform job or IDE PostgreSQL extension if the user prefers.\n\n---\n\n## Report Structure\n\nThe validation report follows this general structure:\n\n| Section | What It Contains | How to Use |\n| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |\n| Executive Summary | Quantitative Score, Expert Assessment, production readiness grade | Determine overall severity — 🔴 NOT READY means critical issues exist |\n| Migration Overview table | Per-category counts (Tables, Views, Procs, Triggers, Columns, Constraints, Indexes, Type Mappings) with Pass/Warn/Fail rates | Identify which categories have failures |\n| Issue Clusters table | Severity (🔴🟠🟡🟢), cluster description, score deduction | Prioritize fixes — work critical clusters first |\n| Schema Loading Notes | Objects that failed to load due to missing dependencies vs true migration issues | Distinguish load failures from conversion defects |\n| What Needs Immediate Attention | Detailed per-cluster breakdown with affected objects, risk description, and recommended SQL fixes | Primary source of fix instructions |\n| Recommended Action Plan | Ordered steps: 🔴 Before testing → 🟡 Before go-live → 🟢 Post-migration | Follow this sequence when applying fixes |\n| What We Could Not Verify | Items not tested (runtime correctness, data accuracy, performance, collation) | Flag as remaining risks after fixes |\n\n---\n\n## Progress Reporting\n\nMaintain a two-tier progress display: a summary table for overall status, plus an active context block.\n\n### Progress Table\n\n```\n## Conversion Progress\n\n| # | Severity | Cluster | Status |\n|---|----------|---------|--------|\n| 1 | 🔴 Crit | \u003ccluster description> (\u003cN> objects) | ✅ Fixed |\n| 2 | 🟠 High | \u003ccluster description> (\u003cN> objects) | 🔄 M/N |\n| 3 | 🟠 High | \u003ccluster description> (\u003cN> objects) | ⏳ Pending |\n| 4 | 🟡 Med | \u003ccluster description> (\u003cN> objects) | ℹ Advisory |\n\n### Currently fixing:\n`\u003cschema.object_name>` — \u003cbrief description of the fix being applied>\n\n### Last completed:\n`\u003cschema.object_name>` — \u003cbrief description of what was fixed>\n```\n\n### Status Values\n\n| Status | Meaning |\n| ---------------------------- | --------------------------------------------------------- |\n| `⏳ Pending` | Cluster not yet started |\n| `🔄 M/N` | In progress — M of N objects fixed so far |\n| `✅ Fixed` | All objects in cluster resolved |\n| `⚠ Partial (M/N, K skipped)` | Some objects could not be fixed — requires user attention |\n| `ℹ Advisory` | Medium/low severity — presented to user, not auto-fixed |\n\n### Per-Fix Chat Response\n\nFor every individual fix, the chat response MUST include:\n\n**1. Fix summary with line reference:**\n\n```\n✅ Fixed `schema.object_name` (line N in working copy)\nProblem: \u003cdescription from the report>\nFix applied: \u003cone-line summary of what was changed>\nSyntax validation: ✅ Passed (validated via PostgreSQL extension)\n```\n\n**2. Updated progress table** (as shown above).\n\n**3. Approval prompt — STOP and wait:**\n\n```\nApprove this fix? [Yes / No / Modify]\n```\n\nDo NOT proceed to the next fix until the user responds.\n\nAfter all critical/high clusters are done, print a final summary:\n\n```\n🔴 Critical: X/X done · 🟠 High: Y/Y done · Overall: Z/Z clusters resolved\n```\n\n---\n\n## Known Limitations\n\n- The IDE agent applies fixes based on the report's recommendations — it does not independently discover new issues\n- Runtime correctness of fixed procedures cannot be verified without production-equivalent test data\n- Application code changes (e.g., cursor-based result sets, connection strings) are outside scope — flag for user\n- Collation differences (MSSQL case-insensitive vs PostgreSQL case-sensitive) need separate testing\n- Performance validation requires production-equivalent load testing\n- CLR stored procedures, linked server queries, and SSIS packages require architectural changes beyond SQL file fixes\n\n---\n\n## Example Requirements\n\n```\n## Requirement 1: Fix All Critical Issues\n\n**User Story:** As a DBA, I want all critical-severity issues from the validation report\nresolved in the PostgreSQL file so that the schema is safe for production.\n**Acceptance Criteria:**\n\n1. WHEN fixes are applied, ALL 🔴 critical clusters from the report SHALL be resolved\n2. WHEN fixes are applied, the PostgreSQL file SHALL be syntactically valid\n3. WHEN fixes are applied, previously converted logic SHALL NOT be altered\n\n## Requirement 2: Fix All High-Severity Issues\n\n**User Story:** As a developer, I want all high-severity issues from the validation report\nresolved so that runtime failures are eliminated.\n**Acceptance Criteria:**\n\n1. WHEN fixes are applied, ALL 🟠 high clusters from the report SHALL be resolved\n2. WHEN fixes are applied, semantic behavior SHALL match the original source SQL\n3. WHEN fixes are applied, the fix SHALL follow the report's recommended approach\n```\n\n## Example Tasks\n\n```\n### From-Scratch Tasks\n\n- [ ] 1. Authenticate and set up AWS Transform job\n - [ ] 1.1 Authenticate to AWS Transform using cookie auth\n - [ ] 1.2 Create workspace and job (or use existing)\n - [ ] 1.3 Upload source SQL artifact (.sql or .zip as-is)\n - [ ] 1.4 Send artifact URI to agent via chat\n- [ ] 2. Monitor conversion and review assessment\n - [ ] 2.1 Poll messages, worklogs, and HITL tasks for progress\n - [ ] 2.2 Download and review assessment report PDFs and CSVs\n - [ ] 2.3 Trigger schema conversion when user is ready\n - [ ] 2.4 Poll for conversion completion\n - [ ] 2.5 Retrieve conversion artifacts (ZIP or individual files)\n\n### Handoff Tasks\n\n- [ ] 1. Collect AWS Transform job context and inputs\n - [ ] 1.1 Prompt user for workspaceId, jobId, and agentInstanceId\n - [ ] 1.2 List all artifacts from AWS Transform job\n - [ ] 1.3 Download ATX_CONVERTED_DB_ARTIFACT ZIP or individual artifacts\n - [ ] 1.4 If no artifacts found, ask user for local file paths\n\n### Common Tasks (both workflows)\n\n- [ ] 3. Check PostgreSQL extension prerequisite\n- [ ] 4. Parse report and prioritize\n - [ ] 4.1 Extract all issue clusters by severity\n - [ ] 4.2 Identify critical and high-severity clusters\n - [ ] 4.3 Separate load failures from true migration defects\n - [ ] 4.4 Create working copy of converted PG file\n- [ ] 5. Apply critical-severity fixes\n - [ ] 5.1 For each 🔴 critical cluster, validate proposed fix via PostgreSQL extension, then apply\n- [ ] 6. Apply high-severity fixes\n - [ ] 6.1 For each 🟠 high cluster, validate proposed fix via PostgreSQL extension, then apply\n- [ ] 7. Present advisory items\n - [ ] 7.1 Summarize 🟡 medium and 🟢 low clusters for user review\n- [ ] 8. Validate and upload\n - [ ] 8.1 Confirm all critical and high clusters are addressed\n - [ ] 8.2 Present diff of all changes\n - [ ] 8.3 Create ZIP and upload to AWS Transform artifact store\n- [ ] 9. Monitor validation and continue\n - [ ] 9.1 Poll AWS Transform job messages for validation progress\n - [ ] 9.2 Download new validation report\n - [ ] 9.3 Ask user: apply another round of fixes or deploy\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":50442,"content_sha256":"5c9ab696fce7bf69d3d6087877fe38e7e417fae251609854771a7f385941ee81"},{"filename":"references/tools.md","content":"# Table of Contents\n\n- [Jobs](#jobs)\n- [Connectors](#connectors)\n- [HITL Tasks (Collaborator Requests)](#hitl-tasks-collaborator-requests)\n - [Building the content payload](#building-the-content-payload)\n - [Severity](#severity)\n - [TOOL_APPROVAL tasks (separate flow)](#tool_approval-tasks-separate-flow)\n- [AWS Transform CLI Commands](#aws-transform-cli-commands)\n - [Core Commands](#core-commands)\n - [Execution Flags](#execution-flags)\n- [Troubleshooting (Non-Auth)](#troubleshooting-non-auth)\n - [Job Issues](#job-issues)\n - [Connector Issues](#connector-issues)\n - [HITL Task Issues](#hitl-task-issues)\n - [MCP Server Issues](#mcp-server-issues)\n - [Rollback](#rollback)\n\n---\n\n## Tools\n\nCanonical tool names, parameters, and per-resource requirements come from the MCP server's `tools/list` response — read the tool descriptions directly. This file covers cross-tool workflows, behavioral rules, and the AWS Transform CLI, which the schemas don't provide. For auth behavior, see [auth](auth.md).\n\n## Jobs\n\n`create_job` creates AND starts the job in one call — no separate `control_job` start is needed. Only orchestrator agents can create jobs; discover them via `list_resources resource=\"agents\" agentType=\"ORCHESTRATOR_AGENT\"`. Use `jobType` OR `orchestratorAgent`, not both — if one fails, retry with the other.\n\n## Connectors\n\nConnector lifecycle:\n\n```\nPENDING → ACTIVE → COMPLETED\n ↓ ↓\nREJECTED FAILED\n```\n\nConnectors start `PENDING`. An AWS admin must approve via the verification link returned by `create_connector`. Do NOT proceed with dependent tasks until the user confirms admin approval. Check status with `get_resource resource=\"connector\"`.\n\n## HITL Tasks (Collaborator Requests)\n\n**CRITICAL: Never auto-submit. Always present to the user first.**\n\nWorkflow for a regular HITL task:\n\n1. `list_resources resource=\"tasks\"` — find tasks needing human action. Three human-actionable states:\n - `AWAITING_HUMAN_INPUT` — first input required from the user\n - `IN_PROGRESS` — user has engaged but not submitted\n - `AWAITING_APPROVAL` — submitted for admin/approver decision\n Surface all three to the user — the person in front of you may be the approver. Whether a task blocks the job depends on its `blockingType` (`BLOCKING` vs `NON_BLOCKING`); surface the state regardless, but let the user know when a blocking task is holding progress.\n2. `get_resource resource=\"task\"` — returns two top-level objects you must read together:\n - `task` — enriched with `_outputSchema`, `_responseTemplate`, `_responseHint`, `uxComponentId`, `severity`. Tells you the **submission shape**.\n - `agentArtifactContent` — downloaded from S3. Tells you the **user-visible context**: current field values, items to select from, component-specific extras (toggles, feature flags, resource identifiers) that may not appear in `_outputSchema`.\n3. Present the task to the user. Two things must be surfaced:\n - The content of `agentArtifactContent` — this is what the user sees in the web UI. Do not paraphrase it down to a single field.\n - Any fields in `_outputSchema` the user needs to provide.\n4. Follow `_responseHint` — it is authoritative per `uxComponentId`. If the hint says \"Only provide fields you want to change\" or similar merge language, the server merges your payload onto the existing artifact. Send **only fields the user explicitly changed** — omit any field the user confirmed as-is or did not modify. Including unchanged fields violates the merge contract and can produce unintended overwrites.\n5. Never silently substitute a value the user didn't see. This applies especially to boolean toggles and opt-ins — surface the current value and ask, even if the server has a safe default.\n6. Wait for the user's decision.\n7. Before calling `complete_task`, show the full payload you are about to submit and confirm.\n8. `complete_task` — submit with the user's response.\n\n### Building the `content` payload\n\nShape the payload based on the task's `_outputSchema` (returned by `get_resource resource=\"task\"`):\n\n- **TextInput** — `{\"data\": \"your text\"}`\n- **AutoForm** — `{\"fieldName\": \"value\", ...}` — flat JSON matching the schema\n- **File upload** — call `upload_artifact` first, then pass the returned `artifactId` in `content`\n- **Display-only** — omit `content` (the server submits `{}`)\n\n### Severity\n\n- `STANDARD` — APPROVE/REJECT submits immediately.\n- `CRITICAL` — non-admins must use `SEND_FOR_APPROVAL`; admins can APPROVE directly.\n\n### TOOL_APPROVAL tasks (separate flow)\n\nWhen `list_resources resource=\"tasks\" category=\"TOOL_APPROVAL\"` returns items, use `list_tool_approvals` / `approve_tool_approval` / `deny_tool_approval` — NOT `complete_task`. The backend rejects `complete_task` for TOOL_APPROVAL tasks.\n\n---\n\n## AWS Transform CLI Commands\n\nThe CLI uses standard AWS credentials (see [auth](auth.md)). Always set `AWS_REGION`.\n\n### Core Commands\n\n| Action | Command |\n| ------------------------------------- | ----------------------------------------------------------------------- |\n| List transformation definitions | `atx custom def list --json` |\n| Execute transformation definition | `atx custom def exec -n \u003cname> -p \u003cpath> -x -t` |\n| Get transformation definition details | `atx custom def get -n \u003cname>` |\n| Save draft | `atx custom def save-draft -n \u003cname> --description \"\u003cdesc>\" --sd \u003cdir>` |\n| Publish | `atx custom def publish -n \u003cname> --description \"\u003cdesc>\" --sd \u003cdir>` |\n| Delete transformation definition | `atx custom def delete -n \u003cname>` |\n| Interactive mode | `atx` |\n| Resume conversation | `atx --resume` |\n| Update CLI | `atx update` |\n\n### Execution Flags\n\n| Flag | Description |\n| ----------------------------------- | ------------------------------------------------------------------ |\n| `-n` / `--transformation-name` | Transformation definition name (from `atx custom def list --json`) |\n| `-p` / `--code-repository-path` | Path to code repo (`.` for current dir) |\n| `-x` / `--non-interactive` | No user prompts |\n| `-t` / `--trust-all-tools` | Auto-approve tool executions (required with `-x`) |\n| `-c` / `--build-command` | Build/validation command (optional, auto-detected) |\n| `-d` / `--do-not-learn` | Prevent knowledge item extraction |\n| `-g` / `--configuration` | Config file (`file://config.yaml`) or inline (`'key=val'`) |\n| `--tv` / `--transformation-version` | Specific transformation definition version |\n\n**NEVER hardcode transformation definition names.** Always fetch from `atx custom def list --json`.\n\n---\n\n## Troubleshooting (Non-Auth)\n\n### Job Issues\n\n| Problem | Resolution |\n| --------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| Job stuck in RUNNING | Check `list_resources resource=\"tasks\"` for pending HITL tasks |\n| Job fails immediately | Check `get_resource resource=\"job\"` for `errorDetails`. Common: connectors not set up or not ACTIVE |\n| Job type not found | Use `list_resources resource=\"agents\"` to discover available agents. Try `orchestratorAgent` instead of `jobType` |\n| Missing artifacts | Job may not be complete — check status first |\n\n### Connector Issues\n\n| Problem | Resolution |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |\n| Stuck in PENDING | Admin hasn't approved — share verification link |\n| FAILED | Check IAM role permissions. Trust policy must allow `transform.amazonaws.com` |\n| `accept_connector` fails | Needs AWS Credentials available in the environment; see the tool's description and `get_status` for current auth state |\n\n### HITL Task Issues\n\n| Problem | Resolution |\n| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `VALIDATION_ERROR` on submit | Check `_outputSchema` from `get_resource resource=\"task\"`. Don't wrap in `{\"data\":...}` or `{\"properties\":...}` unless schema requires it |\n| Empty `agentArtifactContent` | Agent still generating. Check worklogs, wait 30-60s, retry |\n| File upload fails | Verify path exists. Specify `fileType` explicitly |\n\n### MCP Server Issues\n\n| Problem | Resolution |\n| ----------------------- | -------------------------------------------------------------------------- |\n| Tools not available | Restart your IDE. Check `mcp.json` for syntax errors |\n| MCP server not starting | Path in `mcp.json` may be relative — must be absolute. Check binary exists |\n| Region mismatch | Ensure `region` in `configure` matches where resources are |\n\n### Rollback\n\nTransform works on copies — original code is untouched until you apply changes.\n\n- **Haven't applied changes:** Safe. Delete job/artifacts if unwanted.\n- **Applied via git:** `git log` to find pre-transform commit, `git checkout \u003chash>` or `git revert`.\n- **Code connector branch:** Transform creates a separate branch. Delete it with `git branch -D atx/transform-\u003cjobId>`.\n- **Manually copied files:** Use `git checkout HEAD~1 -- path/to/file` or IDE local history.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11058,"content_sha256":"7b7448de5721d42bafe7e69526b5ea510b58eeca07c58479d946330109319006"},{"filename":"references/vmware-containerization.md","content":"# VMware Containerization\n\n> **Last Updated:** 2026-05-10\n\n## Table of Contents\n\n- [Capabilities](#capabilities)\n- [Starting Workflow](#starting-workflow)\n- [Agents and Transforms](#agents--transforms)\n- [Decision Points](#decision-points)\n- [Example Requirements](#example-requirements)\n- [Example Tasks](#example-tasks)\n- [Known Limitations](#known-limitations)\n\n## Capabilities\n\nContainerize applications from VMware environments for deployment on Amazon ECS or Amazon EKS using AWS Transform's AI-powered agent. Analyzes source code, generates Docker artifacts, builds and publishes container images, and generates Infrastructure as Code for container orchestration platforms.\n\n- Source code analysis → Dockerfiles + configuration files (AI-generated)\n- Container image building → Amazon ECR (with automated vulnerability scanning)\n- Infrastructure as Code generation → Amazon EKS (Helm charts) or Amazon ECS (Terraform modules)\n- Private dependency support → AWS CodeArtifact (Maven, PyPI, npm) + private ECR base images\n- Iterative test deployment → validate before production cutover\n- Standalone containerization or end-to-end VMware migration with containerize strategy\n\n## Starting Workflow\n\n1. **Review security disclaimer** — accept before proceeding\n2. **Clone source code** — Git repository (CodeConnections) or zip upload\n3. **Containerize** — AI analyzes source, generates Docker artifacts\n4. **Review artifacts** — approve generated Dockerfiles and configuration\n5. **Publish images** — build and push to Amazon ECR with vulnerability scanning\n6. **Generate IaC** — EKS (Helm charts) or ECS (Terraform modules)\n7. **Deploy test** — validate before production\n8. **Clean up test** — tear down test resources\n9. **Deploy cutover** — production deployment\n\n**Key questions to ask user:**\n\n- \"Do you want standalone containerization or end-to-end migration with containerization?\"\n- \"How would you like to provide your source code — Git repository or zip upload?\"\n- \"Where do you want to deploy — Amazon EKS or Amazon ECS?\"\n\n## Agents & Transforms\n\n| Agent | How to Discover | Purpose |\n| ------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------- |\n| VMware Migration Agent (orchestrator) | `list_resources` with `resource: \"agents\"` | Orchestrates containerization workflow within a VMware migration job |\n| Containerization sub-agent | _(invoked by orchestrator)_ | Source code analysis, Docker artifact generation, image building, IaC generation |\n\n**Discover the agent dynamically:**\n\n```python\nlist_resources(resource=\"agents\")\ncreate_job(workspaceId=\"...\", jobName=\"VMware Containerization\",\n objective=\"Containerize application source code for deployment on ECS/EKS\",\n orchestratorAgent=\"\u003cdiscovered>\")\n```\n\n## Decision Points\n\n| Step | Question to Ask User | Options |\n| -------------------- | ------------------------------------------------------ | --------------------------------------------------------------- |\n| Mode | \"Standalone containerization or end-to-end migration?\" | Standalone / End-to-end migration |\n| Source code | \"How would you like to provide your source code?\" | Git repository (CodeConnections) / Zip upload |\n| Artifact review | \"Do the generated Docker artifacts look correct?\" | Approve / Request changes |\n| Private dependencies | \"Does your application use private dependencies?\" | Configure CodeArtifact / Configure private ECR base images / No |\n| Deployment target | \"Where do you want to deploy?\" | Amazon EKS (Helm charts) / Amazon ECS (Terraform modules) |\n| Test validation | \"Has the test deployment been validated?\" | Proceed to cutover / Re-deploy test / Modify configuration |\n| Cutover | \"Ready to deploy production infrastructure?\" | Deploy cutover / Go back to test |\n\n## Example Requirements\n\n```\n## Requirement 1: Source Code Containerization\n\n**User Story:** As a platform engineer, I want my VMware-hosted application containerized\nso that it can run on Amazon EKS or Amazon ECS.\n**Acceptance Criteria:**\n\n1. WHEN containerization completes, a Dockerfile SHALL be generated for each application component\n2. WHEN containerization completes, container images SHALL be published to Amazon ECR\n3. WHEN containerization completes, vulnerability scanning SHALL report no critical findings\n **Handled by:** AWS Transform VMware Migration Agent (Containerization sub-agent)\n\n## Requirement 2: Infrastructure as Code Generation\n\n**User Story:** As a DevOps engineer, I want deployment infrastructure generated\nso that I can deploy containerized applications to my target platform.\n**Acceptance Criteria:**\n\n1. WHEN IaC generation completes for EKS, Helm charts SHALL be generated with security scanning passed\n2. WHEN IaC generation completes for ECS, Terraform modules SHALL be generated with validation passed\n **Handled by:** AWS Transform VMware Migration Agent (Containerization sub-agent)\n```\n\n## Example Tasks\n\n```\n- [ ] 1. Setup\n - [ ] 1.1 Create VMware migration job\n - [ ] 1.2 Select containerization mode\n - [ ] 1.3 Review and accept security disclaimer\n- [ ] 2. Source code provisioning\n - [ ] 2.1 Provide source code (Git repo or zip upload)\n - [ ] 2.2 Configure private dependencies (if applicable)\n- [ ] 3. Containerization\n - [ ] 3.1 AI agent analyzes source code\n - [ ] 3.2 Review generated Docker artifacts\n - [ ] 3.3 Approve code changes\n- [ ] 4. Image publishing\n - [ ] 4.1 Build and publish to Amazon ECR\n - [ ] 4.2 Review vulnerability scan results\n- [ ] 5. IaC generation\n - [ ] 5.1 Select deployment target (EKS or ECS)\n - [ ] 5.2 Generate and review IaC\n- [ ] 6. Test deployment\n - [ ] 6.1 Deploy and validate test infrastructure\n - [ ] 6.2 Clean up test infrastructure\n- [ ] 7. Production cutover\n - [ ] 7.1 Deploy cutover infrastructure\n - [ ] 7.2 Confirm migration complete\n```\n\n## Known Limitations\n\n- Containerization is accessed through a VMware migration job — cannot be started independently\n- Individual source files must not exceed 1 GB; total source code must not exceed 8 GB\n- Private dependencies require pre-configured AWS CodeArtifact repositories or private ECR base images\n- EKS deployments require an existing cluster or permissions to create one\n- AI-generated Dockerfiles may need manual tuning for complex builds\n- TOOL_APPROVAL tasks (image publishing, deployments, cleanup) must be approved in the web UI — cannot be completed via API\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7027,"content_sha256":"2457c7e35833cfd39e204237f75d8a0633c27ffe6ed2e792309ceaba2fc01e16"},{"filename":"references/vmware-landing-zone.md","content":"# Landing Zone\n\n> **Last Updated:** 2026-05-10\n\n## Table of Contents\n\n- [Capabilities](#capabilities)\n- [Starting Workflow](#starting-workflow)\n- [Agents and Transforms](#agents--transforms)\n- [Decision Points](#decision-points)\n- [Example Requirements](#example-requirements)\n- [Example Tasks](#example-tasks)\n- [Known Limitations](#known-limitations)\n\n## Capabilities\n\nBuild an AWS landing zone as the foundation for your migration project. AWS Transform analyzes your migration inventory and business requirements to recommend an Organizational Unit (OU) and account structure, apply Service Control Policies (SCPs), and generate or deploy the infrastructure as code (IaC).\n\nThe landing zone agent operates in two phases:\n\n1. **Foundation setup** — Establish the core landing zone: AWS Control Tower, foundational OUs (Security, Infrastructure, Sandbox, Workloads), and core accounts (Log Archive, Audit).\n2. **Workload account design** — Design and create workload OUs and accounts based on migration waves, business units, and environment separation requirements.\n\nSupports both **greenfield** (no existing landing zone) and **brownfield** (existing OUs and accounts already deployed) environments.\n\n## Starting Workflow\n\n1. **Connector setup** — Create a target AWS account connector pointing to the organization management account in the Control Tower home Region\n2. **Confirm organization context** — AWS Transform presents the management account ID and target Region for confirmation\n3. **Foundation setup** — Design and deploy (or generate IaC for) the core OU structure, Control Tower initialization, and SCPs\n4. **Workload account design** — Answer discovery questions; AWS Transform proposes OU and account structure based on migration waves and business requirements\n5. **Workload deployment** — Deploy workload OUs, accounts, and SCPs, or download IaC artifacts\n\n**Key questions to ask user:**\n\n- \"Do you already have AWS Control Tower or AWS Organizations set up (brownfield), or are we starting from scratch (greenfield)?\"\n- \"What is your Control Tower home Region?\"\n- \"What email prefix and domain for account email addresses?\"\n- \"How many business units or teams will use AWS?\"\n- \"Do you have compliance requirements that affect account isolation?\"\n\n## Agents & Transforms\n\n| Agent | How to Discover | Purpose |\n| ------------------ | ------------------------------------------ | ---------------------------------------------------------------------------- |\n| Landing zone agent | `list_resources` with `resource: \"agents\"` | Foundation setup, workload account design, SCP configuration, IaC generation |\n\n**Discover the agent dynamically:**\n\n```python\nlist_resources(resource=\"agents\")\ncreate_job(workspaceId=\"...\", jobName=\"Landing Zone Setup\",\n objective=\"Build AWS landing zone foundation and workload account structure\",\n orchestratorAgent=\"\u003cdiscovered>\")\n```\n\n## Decision Points\n\n| Decision | Options | When to Ask |\n| ------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------- |\n| Greenfield vs brownfield | Greenfield (new) / Brownfield (existing OUs/accounts) | Start — determines what gaps to fill |\n| Deployment method (foundation) | Deploy for me / I'll deploy on my own / Design workload accounts first | Phase 1 Step 5 |\n| Deployment method (workload) | Deploy for me / I'll deploy on my own | Phase 2 Step 10 |\n| IaC format (if self-deploying) | AWS CDK / Landing Zone Accelerator (LZA) | When user selects \"I'll deploy on my own\" |\n| Foundation OU customization | Accept recommended structure / Customize OUs and accounts | Phase 1 Step 1 |\n| SCP selection | Which SCPs to apply and to which OUs | Phase 1 Step 4 and Phase 2 Step 9 |\n| Account strategy | Single app per account / Grouped / Environment-based | Phase 2 discovery |\n| Environment separation | Separate accounts per env / Shared accounts | Phase 2 discovery |\n| Compliance sub-OUs | Regulated / Standard separation | Phase 2 — if frameworks identified |\n\n## Example Requirements\n\n```\n## Requirement 1: Foundation Setup\n\n**User Story:** As a cloud platform engineer, I want the core landing zone foundation deployed\nso that governance controls, centralized logging, and account isolation are in place before any workloads arrive.\n**Acceptance Criteria:**\n\n1. WHEN foundation setup completes, Control Tower SHALL be initialized with Security OU, Log Archive account, and Audit account\n2. WHEN foundation setup completes, Infrastructure, Sandbox, and Workloads OUs SHALL exist in the organization\n3. WHEN SCPs are applied, member accounts SHALL be unable to exceed the boundaries defined by the SCPs\n **Handled by:** AWS Transform Landing Zone Agent\n\n## Requirement 2: Workload Account Structure\n\n**User Story:** As a cloud platform engineer, I want workload OUs and accounts designed around my migration waves\nso that servers can be migrated into correctly isolated accounts without splitting waves.\n**Acceptance Criteria:**\n\n1. WHEN workload structure is proposed, ALL servers in a migration wave SHALL map to the same target account\n2. WHEN environment isolation is required, Workloads/Production and Workloads/Non-Production sub-OUs SHALL be created\n3. WHEN sensitive-data applications are identified, they SHALL each receive a dedicated account\n **Handled by:** AWS Transform Landing Zone Agent\n\n## Requirement 3: IaC Generation\n\n**User Story:** As a platform engineer, I want IaC artifacts generated for the landing zone\nso that I can review, version-control, and deploy the infrastructure through my own pipeline.\n**Acceptance Criteria:**\n\n1. WHEN IaC generation completes, artifacts SHALL be available in CDK (TypeScript) or LZA (YAML) format\n2. WHEN artifacts are downloaded, a checksum SHALL be provided to verify file integrity\n3. WHEN LZA format is selected, the generated YAML SHALL be compatible with LZA Universal Configuration version 1.1.0\n **Handled by:** AWS Transform Landing Zone Agent\n```\n\n## Example Tasks\n\n```\n- [ ] 1. Connector setup\n - [ ] 1.1 Create target AWS account connector for the management account\n - [ ] 1.2 Confirm connector Region matches Control Tower home Region\n - [ ] 1.3 Approve connector via AWS Console verification link\n- [ ] 2. Foundation design\n - [ ] 2.1 Review recommended foundation OU structure\n - [ ] 2.2 Confirm email prefix and domain\n - [ ] 2.3 Review and select SCPs\n- [ ] 3. Foundation deployment\n - [ ] 3.1 Choose deployment method\n - [ ] 3.2 Submit deployment for approval\n - [ ] 3.3 Confirm OUs and accounts created\n- [ ] 4. Workload account design\n - [ ] 4.1 Check for migration planning artifacts\n - [ ] 4.2 Answer discovery questions\n - [ ] 4.3 Review proposed workload structure\n - [ ] 4.4 Select workload SCPs\n- [ ] 5. Workload deployment\n - [ ] 5.1 Choose deployment method\n - [ ] 5.2 Submit for approval or download IaC\n - [ ] 5.3 Confirm all OUs and accounts created\n```\n\n## Known Limitations\n\n- Once an OU or account is deployed, it cannot be removed through the landing zone agent\n- The Security OU is managed by Control Tower — cannot be modified through this tool\n- All servers in a migration wave must go to the same account — waves cannot be split across accounts\n- The connector Region must match the Control Tower home Region and IAM Identity Center Region\n- LZA deployment requires the AWS Transform account and LZA installation to be in the same AWS Organization\n- SCPs cannot grant permissions — they only restrict what IAM policies allow\n- Brownfield environments may require remediation before Control Tower can be initialized\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8287,"content_sha256":"dd359d23844b7fb3c7596e4ac4df1cc1bffd5709db39cb0a1a04a120b022d9ab"},{"filename":"references/vmware-network.md","content":"# VMware Network Migration\n\n> **Last Updated:** 2026-05-05\n\n## Table of Contents\n\n- [Capabilities](#capabilities)\n- [Workflow](#workflow)\n- [Agents and Transforms](#agents--transforms)\n- [Decision Points](#decision-points)\n- [Hub and Spoke Architecture](#hub-and-spoke-architecture)\n- [VPC and Subnet Operations](#vpc-and-subnet-operations)\n- [Multi-Account Considerations](#multi-account-considerations)\n- [Deployment Approvals](#deployment-approvals)\n- [Known Limitations](#known-limitations)\n- [Troubleshooting](#troubleshooting)\n- [Example Requirements](#example-requirements)\n- [Example Tasks](#example-tasks)\n\n## Capabilities\n\nMigrate on-premises network infrastructure to AWS. Translates source environment configuration into AWS-equivalent network resources — VPCs, subnets, security groups, NAT gateways, transit gateways, elastic IPs, routes, and route tables.\n\n- Network segments → AWS VPCs + subnets\n- Firewall rules → AWS Security Groups\n- Routing → AWS Transit Gateway (Hub and Spoke) or VPC route tables (Isolated)\n- Review and modify generated network configuration before deployment\n- VPC operations: rename, resize, merge, split, delete, exclude/include, change IP address\n- Subnet operations: resize, delete, change IP address\n- Security group referencing (within-VPC and cross-VPC/cross-account)\n- IP migration: keep existing ranges or update to new CIDRs, static or DHCP assignment\n- Guided network recommendations (naming, right-sizing, consolidation, security review)\n- Creates network diagrams (PNG and Mermaid)\n- Custom tags, MAP 2.0 tags, and automatic launch/replication tags\n- Deploy the network using AWS CloudFormation with approval workflow\n- Run reachability analysis on deployed VPCs\n- Delete deployed network resources (rollback)\n- Generates CloudFormation, CDK (TypeScript), Terraform, or Landing Zone Accelerator IaC\n\n### Supported Source Formats\n\n| Format | Produces |\n| ------------------------ | ------------------------------------------------------ |\n| VMware NSX export (.zip) | VPCs + subnets + security groups |\n| Cisco ACI | VPCs + subnets + security groups |\n| Palo Alto Networks | VPCs + subnets + security groups |\n| Fortinet FortiGate | VPCs + subnets + security groups |\n| RVTools (.xlsx/.zip) | VPCs + subnets only (no security groups) |\n| modelizeIT | VPCs + subnets + security groups (hybrid environments) |\n\n### Topology Options\n\n| Topology | When to use |\n| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Hub and Spoke** | Multi-tier apps, cross-VPC traffic, shared services, centralized egress/ingress. Creates Transit Gateway + Inspection/Outbound/Inbound VPCs. |\n| **Isolated VPCs** | Independent workloads with no cross-VPC communication. Each VPC gets its own internet gateway. |\n\n### Security Group Strategies\n\n| Strategy | When to use |\n| ------------ | ----------------------------------------------------------------------------------------------------------- |\n| **MAP** | Static IP environments. Translates source firewall rules to SGs with IP-based rules. |\n| **MAP_DHCP** | Dynamic IP / DHCP environments. Produces broader rules to accommodate IP changes. Use with Transit Gateway. |\n| **SKIP** | Manual SG configuration post-migration. Use when source rules are too complex or need redesign. |\n\n---\n\n## Workflow\n\nThe network migration workflow is one sequence across three phases — Phase 1's 5 steps, Phase 2's 9 steps, and Phase 3's 4 steps run in order (18 steps total). Each phase's numbering restarts at 1, but the phases execute sequentially without gaps.\n\n### Phase 1: Target Account Setup\n\n1. Select \"Network Migration\" workflow\n2. Confirm plan → \"Proceed\"\n3. Select migration type: Single-account or Multi-account\n4. MAP agreement (optional)\n5. Configure connector (HITL task) — must include `connectorType` in payload\n\n### Phase 2: Network Migration\n\n1. Upload source file (NSX export, RVTools, etc.) — requires `planStepId` in `upload_artifact`\n2. Select topology: Hub and Spoke or Isolated VPCs\n3. Select security group strategy: MAP, MAP_DHCP, or SKIP\n4. Agent presents configuration summary — **this is NOT the mapping step**\n5. User confirms → mapping actually begins (2-5 min)\n6. Guided Modernization or Direct Edits\n7. Apply changes → IaC regeneration\n8. Done with network design\n9. Network diagram generation (image + Mermaid)\n\n### Confirmation Before Mapping\n\nAfter the user selects topology and security group strategy, the agent presents a configuration summary and asks for confirmation before starting the actual network mapping. Do NOT tell the user that mapping has started until the user confirms and the agent explicitly begins the mapping process.\n\nThe sequence is:\n\n1. Select topology → agent acknowledges\n2. Select security group strategy → agent presents **configuration summary** with all selections\n3. User confirms \"Yes, start network mapping\" → mapping actually begins (2-5 min)\n\nThe summary step is NOT the mapping step. Do not conflate them.\n\n### Polling and Waiting\n\nTwo types of waits occur during the workflow:\n\n**Machine-gated steps** (mapping, job processing, agent responses):\n\n- Poll automatically and silently every 30 seconds\n- Do NOT ask the user for permission to poll\n- Only surface results to the user (completion, error, or progress update)\n\n**Human-gated steps** (connector approval, deployment approval):\n\n- Do NOT auto-poll — these depend on a human action that may take minutes or hours\n- Present the action needed (link, instructions) and ask the user to confirm when done\n- When user confirms → verify status once\n- If not yet complete → remind them what's needed\n\n### Phase 3: Deployment\n\n1. Tagging (optional)\n2. Deployment strategy: self-deploy or AWS Transform deploy\n3. Additional IaC format selection (CDK, Terraform, LZA)\n4. Download artifacts\n\n### Artifact Handling\n\nThe job generates several artifact types. Each has different download behavior:\n\n| Artifact | Location | Download Behavior |\n| --------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Network diagram** (PNG, Mermaid) | Managed artifact store | **Always download automatically** — use `get_resource(resource=\"artifact\", savePath=...)` to save to the user's Downloads directory (full absolute path). Never send the user to the web console for diagrams. |\n| **IaC files** (CloudFormation, Terraform, CDK, LZA) | Connector S3 bucket (`code_generation/` prefix) | **Ask the user** — present the S3 console link, then ask if they want a local copy. If yes, run `aws s3 cp` recursively to a local directory (full absolute path). |\n| **Checksums** | Inline in agent message (text) | **No download needed** — checksums are presented as text in the agent's response. Present them to the user as-is. |\n\n**Diagram download (mandatory, via `aws-transform-mcp`):**\n\n> Note: `get_resource` is an `aws-transform-mcp` wrapper tool — not the platform's native `create_artifact_download_url` + `download_artifact` flow. It accepts `savePath` (full file path), not `output_dir`.\n\n```python\nget_resource(resource=\"artifact\", artifactId=\"\u003cid>\", savePath=\"/Users/\u003cusername>/Downloads/network_diagram.png\")\n```\n\n**IaC download (user choice):**\n\n```bash\naws s3 cp s3://\u003cbucket>/\u003cprefix>code_generation/ ~/Downloads/network-iac/ --recursive --region us-east-1\n```\n\nExtract the bucket name and prefix from the S3 link in the agent's response. Requires AWS CLI configured with access to the target account.\n\n### Connector Setup\n\nThe VMware Migration Agent creates a HITL task requesting connector configuration. Two steps are needed:\n\n**Step A: Create the connector** (via `aws-transform-mcp` server's `create_connector` tool):\n\n> Note: `aws-transform-mcp` is a wrapper MCP server that provides a unified interface over the platform's customer-facing and agentic APIs. Tool names and parameters may differ from the underlying platform tools.\n\n```python\ncreate_connector(\n workspaceId=\"\u003cworkspace-id>\",\n connectorName=\"network-migration-connector\",\n connectorType=\"vmware_migration|infra_provisioning|2\", # Registered partner type in ConnectorTypeConfigurationProvider; not in base enum (S3|CODE_CONNECTION). Do not use arbitrary values.\n configuration={\"encryptionKeyArn\": \"\u003ckms-key-arn>\"}, # MCP wrapper accepts encryptionKeyArn (rejects kmsKeyArn); maps to platform's KMS_KEY_ARN_KEY internally\n awsAccountId=\"\u003caccount-id>\",\n targetRegions=[\"us-east-1\"]\n)\n```\n\nResolve the KMS key ARN beforehand:\n\n```bash\naws kms describe-key --key-id alias/aws/s3 --region us-east-1 --query 'KeyMetadata.Arn' --output text\n```\n\nAfter creation, the user must approve via the verification link returned in the response. This creates an IAM role with correct permissions. Once the user confirms approval, verify status via `get_resource(resource=\"connector\")`.\n\n**Prerequisites for approval:** The user must be logged into the target AWS account in their browser before opening the verification link. If not logged in, the console will redirect to a sign-in page.\n\n**Connector approval is human-gated** — do NOT auto-poll. Instead:\n\n1. Present the verification link to the user\n2. Ask the user to confirm once they've approved\n3. When user confirms → check status once via `get_resource(resource=\"connector\")`\n4. If `ACTIVE` → proceed. If still `PENDING` → remind them to approve. If `REJECTED` → report error.\n\n**Step B: Complete the HITL task** (via `complete_task`):\n\n- Submit the connector ID and `connectorType: \"vmware_migration|infra_provisioning|2\"` in the task payload\n\n### File Upload\n\nUpload the source file (NSX export, RVTools, etc.) via the `aws-transform-mcp` server's `upload_artifact` tool with the `planStepId` parameter. The `planStepId` ties the artifact to the correct plan step so the agent can find it.\n\n**CRITICAL: The `planStepId` parameter is REQUIRED in the `upload_artifact` call. Without it, the file uploads but the agent cannot find it.**\n\n**CRITICAL: Resolve ALL paths to absolute form BEFORE calling `upload_artifact`.** The tool does NOT expand `~` or shell variables. `~/file.zip` will fail silently — use `/Users/\u003cusername>/file.zip` instead.\n\n> Note: `upload_artifact` is an `aws-transform-mcp` wrapper tool that combines the platform's 3-step flow (`create_artifact_upload_url` → `upload_artifact` → `complete_artifact_upload`) into a single call.\n\n```python\nupload_artifact(\n workspaceId=\"\u003cworkspace-id>\",\n jobId=\"\u003cjob-id>\",\n content=\"/Users/\u003cusername>/Downloads/\u003cfilename>.zip\", # MUST be absolute — no ~ or relative paths\n fileName=\"\u003cfilename>.zip\",\n fileType=\"ZIP\",\n categoryType=\"CUSTOMER_INPUT\",\n planStepId=\"\u003cupload-source-file-step-id>\" # REQUIRED — get from list_resources(resource=\"plan\")\n)\n```\n\nGet the `planStepId` from `list_resources(resource=\"plan\")` — find the step for \"Upload source file.\"\n\n**Path resolution (all tools):** Always resolve `~` and relative paths to their full absolute form before passing to any MCP tool parameter (`content`, `savePath`, etc.). Tools do NOT expand `~` or shell variables — they treat paths as raw strings.\nExample: `~/Downloads/file.zip` → `/Users/\u003cusername>/Downloads/file.zip`\n\n⚠️ **Without `planStepId`**, the file uploads successfully but the agent cannot find it in \"User Uploads.\" The `planStepId` is required for the mapping engine to access the file.\n\n---\n\n## Agents & Transforms\n\n| Agent | How to Discover | Purpose |\n| ------------------------------------- | ------------------------------------------ | ------------------------------------------------------- |\n| VMware Migration Agent (orchestrator) | `list_resources` with `resource: \"agents\"` | Orchestrates full workflow, invokes NMA sub-agent |\n| Network Migration Agent (NMA) | _(sub-agent, not directly invocable)_ | File processing, mapping, modernization, IaC generation |\n| MGN Backend | _(external service)_ | Runs `StartNetworkMigrationMapping` and code generation |\n\n**Discover the orchestrator agent dynamically** — do not hardcode agent names:\n\n```python\nlist_resources(resource=\"agents\")\n# Find the VMware network migration orchestrator from results\n```\n\n**Selection criteria** when multiple VMware agents exist: choose the agent whose `description` mentions \"network migration\" or \"infra provisioning.\" Prefer the highest version number if multiple matches exist. Ignore agents marked as deprecated in their description. Present the matched agent to the user for confirmation before creating a job.\n\n### Job Creation\n\n```python\ncreate_job(\n workspaceId=\"\u003cworkspace-id>\",\n jobName=\"Network Migration \u003ctimestamp>\",\n objective=\"Migrate on-premises network to AWS\",\n intent=\"Migrate on-premises network to AWS VPC\",\n orchestratorAgent=\"\u003cdiscovered>\"\n)\n```\n\n### Monitoring\n\n```python\n# Check for agent messages (primary signal)\nlist_resources(resource=\"messages\", workspaceId=\"...\", jobId=\"...\")\n\n# Check for HITL tasks\nlist_resources(resource=\"tasks\", workspaceId=\"...\", jobId=\"...\")\n\n# Check plan step status\nlist_resources(resource=\"plan\", workspaceId=\"...\", jobId=\"...\")\n```\n\n---\n\n## Decision Points\n\n| Step | Question to Ask User | Options |\n| --------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |\n| Topology | \"Do your workloads need cross-VPC communication?\" | Hub and Spoke / Isolated VPCs |\n| Security groups | \"How should security groups be created?\" | MAP (static IPs) / MAP_DHCP (dynamic IPs) / SKIP (manual setup) |\n| Modernization | \"Would you like guided optimization or direct control?\" | Guided Modernization / Direct Edits / Skip |\n| Naming | \"What naming convention do you use for cloud resources?\" | User provides pattern (e.g., `{env}-{workload}-{type}`) or skip |\n| Deployment | \"Do you want AWS Transform to deploy, or deploy yourself?\" | Let AWS Transform deploy / I'll deploy myself |\n| IaC format | \"Which additional IaC format do you need?\" | CDK Project / Terraform / LZA / None |\n\n### Guided Modernization Recommendations\n\nWhen user selects Guided Modernization, present each recommendation and ask:\n\n- Rename VPCs → user provides new names or skips\n- Right-sizing (resize CIDRs) → user approves or skips\n- Security posture review → informational, user acknowledges\n- Remove unused subnets → user approves or keeps\n\nAfter all recommendations: \"Apply all staged changes\" → wait for IaC regeneration → \"Done with network design\"\n\n---\n\n## Hub and Spoke Architecture\n\nWhen the user selects Hub and Spoke topology, the agent generates:\n\n### Generated VPCs\n\n| VPC | Purpose |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Spoke VPCs** | One per detected source network segment. Connected to Transit Gateway. |\n| **Inspection VPC** | Routes all cross-VPC traffic through this VPC for inspection. User must deploy a firewall appliance (e.g., AWS Network Firewall) here post-migration. TGW attachment uses appliance mode (symmetric routing). |\n| **Inbound VPC** | Handles public internet → workload traffic (north-south inbound). Includes internet gateway + public subnets across AZs. |\n| **Outbound VPC** | Handles workload → public internet traffic (north-south outbound). Includes internet gateway + NAT gateways with elastic IPs per AZ. |\n\n### Transit Gateway Route Tables\n\n| Route Table | Associated With | Routes | Purpose |\n| --------------- | ------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- |\n| **Uninspected** | Spoke VPCs, Inbound VPC, Outbound VPC | `0.0.0.0/0` → Inspection VPC attachment | Default association table. Forces all traffic through inspection. |\n| **Inspected** | Inspection VPC | Propagated routes from all spoke VPCs | Default propagation table. Lets inspected traffic reach destinations. |\n\n### Traffic Flow\n\n1. Spoke VPC → Transit Gateway (default route `0.0.0.0/0`)\n2. Uninspected route table → Inspection VPC\n3. Inspection VPC forwards traffic back to Transit Gateway (firewall appliance inspects here if deployed)\n4. Inspected route table → destination spoke VPC (via propagated routes)\n\nOutbound internet: Inspected table routes to Outbound VPC → NAT gateway → internet gateway.\nInbound internet: Internet gateway → Inbound VPC → same inspection path → spoke VPC.\n\n**Note:** Cross-VPC traffic routes through Inspection VPC but is not inspected until the user deploys a firewall appliance (e.g., AWS Network Firewall) there.\n\nFor multi-account deployments, Transit Gateway is shared across accounts via AWS Resource Access Manager (RAM).\n\n---\n\n## VPC and Subnet Operations\n\nOperations available during the review and optimization phase (Guided Modernization or Direct Edits).\n\n### VPC Operations\n\n| Operation | What It Does | Constraints |\n| ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Rename** | Change VPC name | — |\n| **Resize** | Change CIDR prefix length | Must be /16–/28. Subnets must fit within new CIDR. SG rules matching old CIDR auto-update. |\n| **Change IP** | Change base IP, keep prefix length | Subnets shift by same offset. SG rules matching old CIDR auto-update. |\n| **Merge** | Combine two VPCs into one | No subnet CIDR overlap. Merged result must be /16 or smaller (i.e., prefix ≥ /16). Same account (multi-account). |\n| **Split** | Divide VPC into two | Exactly two CIDRs, no overlap, each /16–/28. Every subnet must fit entirely within exactly one of the two new CIDRs (split is blocked if any subnet spans the boundary). SG rules NOT auto-updated (manual review required). |\n| **Delete** | Permanently remove | Cannot undo. |\n| **Exclude** | Temporarily remove from migration | Can re-include later. |\n| **Include** | Re-add excluded VPC | — |\n\n### Subnet Operations\n\n| Operation | What It Does | Constraints |\n| ------------- | ---------------------------------- | -------------------------------------------------------------------------------------------- |\n| **Resize** | Change CIDR prefix length | Must be /16–/28. No overlap with other subnets in same VPC. Must fit within parent VPC CIDR. |\n| **Delete** | Permanently remove | Cannot undo. Does not affect parent VPC. |\n| **Change IP** | Change base IP, keep prefix length | — |\n\n**Note:** After each operation (except Split), security group referencing is re-evaluated — CIDR-based rules may convert to SG references or vice versa. Split requires manual SG review since rules are not auto-updated.\n\n**Appliance VPC restrictions:** For Inspection, Inbound, and Outbound VPCs in Hub and Spoke, only Change IP address is supported.\n\n---\n\n## Multi-Account Considerations\n\n| Aspect | What to Know |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |\n| **Migration type selection** | User chooses Single-account or Multi-account during target account setup. Present via user question. |\n| **Cross-account IAM roles** | Must be configured before starting network migration. Agent handles setup guidance. |\n| **AWS Organizations** | Required for multi-account. LZA deployment requires same Organization as the AWS Transform account. |\n| **Transit Gateway sharing** | In Hub and Spoke, TGW is shared across accounts via RAM. Agent configures this. |\n| **VPC merge constraint** | Both VPCs must be assigned to the same account. Present this constraint if user attempts cross-account merge. |\n| **Security group referencing** | Cross-account ingress rules use SG references (Hub and Spoke). Cross-account egress uses CIDR-based rules. |\n\n---\n\n## Deployment Approvals\n\nWhen the user selects AWS Transform-managed deployment:\n\n1. **Submission** — Confirm deployment intent, agent submits CloudFormation templates for review\n2. **Routing** — Request routes automatically to authorized approvers via the AWS Transform Approvals tab\n3. **Review** — Approvers validate CloudFormation templates and network configurations against security standards\n4. **Decision** — Approver approves or denies:\n - **Approved** → deployment proceeds automatically\n - **Denied** → inform user, suggest contacting approver for required modifications\n5. **Audit** — All approval decisions are tracked for audit purposes\n\n**Behavior during approval:**\n\n- After submission, inform user that deployment requires approval\n- Inform user that approval is pending — when user confirms approval has been granted, check job status once\n- If denied, present the denial to the user and offer to modify the network design and resubmit\n\n**Rollback:** After deployment completes, resources can be deleted (requires separate approval). If resources were modified after deployment, automatic deletion is not available — user must delete manually via Console or CLI.\n\n---\n\n## Known Limitations\n\n1. **File upload requires `planStepId`** — `upload_artifact` without `planStepId` uploads successfully but the agent can't find the file. Always include the plan step ID for the \"Upload source file\" step.\n2. **Connector KMS validation** — `create_connector` accepts invalid KMS key ARNs without validation. Fails silently at mapping time.\n3. **MCP requires `encryptionKeyArn`** — Cannot create connector without it, even though webapp doesn't require it.\n4. **No artifact deletion** — Cannot delete or overwrite files in User Uploads via MCP.\n5. **Connector role reuse** — Reusing a role from a deleted connector may have KMS permissions on the wrong key. Always use the verification link.\n6. **Existing mapping definitions** — If a previous job created a mapping in the same workspace, agent asks \"existing vs new configuration.\"\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely Cause | Resolution |\n| ---------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| Mapping fails silently after connector setup | Invalid KMS key ARN passed to `create_connector` | Resolve real ARN via `aws kms describe-key --key-id alias/aws/s3` and recreate connector |\n| Agent can't find uploaded source file | `upload_artifact` called without `planStepId` | Re-upload with `planStepId` from `list_resources(resource=\"plan\")` — find the \"Upload source file\" step |\n| Connector status stuck on PENDING | User hasn't approved via verification link | Present verification link again — approval creates IAM role with correct permissions |\n| \"Existing configuration found\" prompt | Previous job created a mapping in same workspace | Ask user: reuse existing or start new configuration |\n| Deployment fails with Organization ID mismatch | LZA deployment account not in same AWS Organization | Verify Organization membership or choose a different IaC format |\n| Reachability analysis shows no connectivity | Security groups or route tables missing rules | Review generated SGs and route tables; check Transit Gateway route table associations |\n| Deployment approval denied | Approver rejected CloudFormation templates | Contact approver for required modifications, update network design, resubmit |\n| Connector creation fails with validation error | Wrong configuration key name | Use `encryptionKeyArn` (not `kmsKeyArn`) in the `configuration` parameter |\n| Cannot replace uploaded file | MCP has no artifact deletion/overwrite | Create a new job or upload with a different filename; existing uploads cannot be removed via MCP |\n\n---\n\n## Example Requirements\n\n```\n## Requirement 1: Network Mapping\n\n**User Story:** As a network engineer, I want my on-premises network configuration\ntranslated to AWS VPC infrastructure so that workload connectivity is preserved after migration.\n**Acceptance Criteria:**\n\n1. WHEN mapping completes, EACH source network segment SHALL map to a distinct AWS VPC\n2. WHEN mapping completes, source firewall rules SHALL be translated to AWS Security Groups\n3. WHEN mapping completes, routing between segments SHALL be preserved via Transit Gateway or VPC route tables\n **Handled by:** AWS Transform VMware Migration Agent (NMA sub-agent)\n\n## Requirement 2: Network Optimization\n\n**User Story:** As a cloud architect, I want to review and optimize the generated network\nbefore deployment so that it follows our naming conventions and right-sizing standards.\n**Acceptance Criteria:**\n\n1. WHEN optimization completes, ALL VPCs SHALL follow the organization's naming convention\n2. WHEN optimization completes, VPC CIDRs SHALL be right-sized for actual subnet usage\n3. WHEN optimization completes, unused subnets SHALL be removed with user approval\n **Handled by:** AWS Transform VMware Migration Agent (Guided Modernization) + IDE (presenting recommendations)\n\n## Requirement 3: Network Deployment\n\n**User Story:** As an infrastructure engineer, I want the approved network configuration\ndeployed to my AWS account so that VPCs are ready for VM migration.\n**Acceptance Criteria:**\n\n1. WHEN deployment completes, ALL VPCs, subnets, and security groups SHALL exist in the target account\n2. WHEN reachability analysis runs, cross-VPC connectivity SHALL be confirmed\n3. WHEN deployment completes, IaC templates SHALL be available for download in the selected format\n **Handled by:** AWS Transform VMware Migration Agent (CloudFormation deployment)\n```\n\n---\n\n## Example Tasks\n\n```\n- [ ] 1. Target account setup (AWS Transform)\n - [ ] 1.1 Select migration type (single-account or multi-account)\n - [ ] 1.2 MAP agreement (if applicable)\n - [ ] 1.3 Configure connector (KMS key + verification link approval)\n - [ ] 1.4 Verify connector status = ACTIVE\n- [ ] 2. Network mapping (AWS Transform)\n - [ ] 2.1 Upload source file (`upload_artifact` with `planStepId`)\n - [ ] 2.2 Select topology (Hub and Spoke or Isolated VPCs)\n - [ ] 2.3 Select security group strategy (MAP / MAP_DHCP / SKIP)\n - [ ] 2.4 Review configuration summary and confirm → mapping begins\n - [ ] 2.5 Wait for mapping to complete (2-5 min)\n- [ ] 3. Network optimization\n - [ ] 3.1 Review generated VPCs and subnets\n - [ ] 3.2 Guided Modernization or Direct Edits\n - [ ] 3.3 Apply changes → IaC regeneration\n - [ ] 3.4 Confirm \"Done with network design\"\n- [ ] 4. Deployment\n - [ ] 4.1 Configure custom tags\n - [ ] 4.2 Select deployment strategy (AWS Transform deploy or self-deploy)\n - [ ] 4.3 If self-deploy: select additional IaC format (CDK / Terraform / LZA)\n - [ ] 4.4 If AWS Transform deploy: wait for approval → deployment → reachability analysis\n - [ ] 4.5 Download artifacts\n- [ ] 5. Validation\n - [ ] 5.1 Review reachability analysis results\n - [ ] 5.2 Verify network diagram matches expected topology\n - [ ] 5.3 Confirm VPCs ready for VM migration waves\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":32250,"content_sha256":"5f9237b06de7503dab0fd5cce38cd20f01cbde8f2441624bc8653a97cee16d40"},{"filename":"references/vmware-server.md","content":"# Server Migration\n\n> **Last Updated:** 2026-05-10\n\n## Table of Contents\n\n- [Capabilities](#capabilities)\n- [Starting Workflow](#starting-workflow)\n- [Agents and Transforms](#agents--transforms)\n- [Decision Points](#decision-points)\n- [Example Requirements](#example-requirements)\n- [Example Tasks](#example-tasks)\n- [Known Limitations](#known-limitations)\n\n## Capabilities\n\nRehost VMware servers to Amazon EC2 using AWS Application Migration Service (MGN). AWS Transform orchestrates the full wave-based migration lifecycle — wave setup, inventory validation, replication agent deployment, data replication monitoring, test instance launch, and production cutover. This workload covers VMware-sourced servers only; for VMware infrastructure (vSphere networking, vSAN storage, vCenter) see [vmware.md](vmware.md).\n\n- VMware servers → Amazon EC2 instances (rehost/lift-and-shift via MGN)\n- Continuous block-level data replication via AWS Replication Agent\n- Automated replication agent installation via MGN connector (SSH/WinRM) — reusable across waves and target accounts\n- Multi-wave migration with per-wave configuration\n- Single-account and multi-account migration support\n- Test instance launch and validation before production cutover\n- Selective or full-wave cutover with finalization\n\n## Starting Workflow\n\n1. **Confirm prerequisites** — target AWS accounts ready, VPCs/subnets/security groups deployed and tagged, inventory file prepared with wave assignments\n2. **Configure execution defaults** — EC2 recommendation preferences and default launch settings (apply to all target accounts)\n3. **Set up migration wave** — configure target account, migration mode (single vs multi-account), IP assignment strategy, verify resource tags\n4. **Validate inventory** — review and confirm server-to-EC2 mapping, licensing options, and network configuration before loading into MGN\n5. **Deploy replication agents** — choose installation method (organization tools, MGN connector, or manual), deploy to all servers in the wave\n6. **Monitor replication** — track initial sync and continuous replication until all servers reach Ready for testing\n7. **Test** — obtain approval before launching test instances, then launch, validate, mark applications ready for cutover\n8. **Cutover** — obtain approval before launching cutover instances, then launch, verify, finalize (stops replication), optionally archive source servers\n\nIndividual servers can advance to test and cutover independently of the rest of the wave.\n\n## Agents & Transforms\n\n| Agent | How to Discover | Purpose |\n| --------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------- |\n| Server migration agent | `list_resources` with `resource: \"agents\"` | Wave setup, inventory validation, agent deployment, replication monitoring, testing, cutover |\n| AWS Application Migration Service (MGN) | External | Actual server replication, testing, and cutover execution |\n| AWS Migration Hub | External | Migration tracking and orchestration |\n\n**Discover the agent dynamically:**\n\n```python\nlist_resources(resource=\"agents\")\n# Then create job with discovered orchestratorAgent\ncreate_job(workspaceId=\"...\", jobName=\"Server Migration\",\n objective=\"Migrate VMware servers to EC2 using MGN\", orchestratorAgent=\"\u003cdiscovered>\")\n```\n\n## Decision Points\n\n| Decision | Options | When to Ask |\n| ------------------------- | -------------------------------------------------------------------- | -------------------------------------- |\n| Migration mode | Single-account / Multi-account | Wave setup |\n| IP assignment strategy | Static IP / Dynamic IP (DHCP) | Wave setup |\n| Agent installation method | Organization tools / MGN connector / Manual | Before agent deployment |\n| Credential configuration | Single secret (Linux) / Single secret (Windows) / Per-server secrets | Connector setup (MGN connector method) |\n| Testing scope | Full wave / Selective | Before launching test instances |\n| Cutover scope | Full wave / Selective | Before launching cutover instances |\n\n## Example Requirements\n\n```\n## Requirement 1: Wave Setup and Inventory Validation\n\n**User Story:** As an infrastructure engineer, I want each migration wave configured and validated\nso that servers are correctly mapped to target accounts, subnets, and EC2 instance types.\n**Acceptance Criteria:**\n\n1. WHEN wave setup completes, EACH server SHALL have a target account, subnet, security group, and EC2 instance type assigned\n2. WHEN inventory is validated, required resource tags SHALL be verified\n3. WHEN inventory is loaded, MGN SHALL create source server records for each server in the wave\n **Handled by:** AWS Transform Server Migration Agent\n\n## Requirement 2: Replication Agent Deployment\n\n**User Story:** As an operations engineer, I want replication agents deployed to all source servers\nso that continuous block-level replication to AWS begins automatically.\n**Acceptance Criteria:**\n\n1. WHEN agents are deployed, ALL servers in the wave SHALL show replication state INITIATING or INITIAL_SYNC\n2. WHEN initial sync completes, ALL servers SHALL reach Ready for testing state\n3. WHEN a server fails agent installation, the failure reason SHALL be displayed and retry SHALL be available\n **Handled by:** AWS Transform Server Migration Agent\n\n## Requirement 3: Testing and Cutover\n\n**User Story:** As an operations engineer, I want to validate migrated servers before cutover\nso that production workloads are moved to AWS with verified functionality.\n**Acceptance Criteria:**\n\n1. WHEN test instances are launched, instance IDs SHALL be provided for each server\n2. WHEN all applications are marked ready for cutover, replication alerts SHALL be resolved\n3. WHEN cutover is finalized, source machine replication SHALL stop and lifecycle state SHALL be locked\n4. WHEN cutover completes, downtime SHALL be limited to the window between source shutdown and cutover instance availability\n **Handled by:** AWS Transform Server Migration Agent\n```\n\n## Example Tasks\n\n```\n- [ ] 1. Prerequisites verification\n - [ ] 1.1 Confirm target AWS accounts are ready\n - [ ] 1.2 Verify VPC, subnets, and security groups are deployed and tagged\n - [ ] 1.3 Confirm inventory file is prepared with wave assignments and EC2 preferences\n - [ ] 1.4 Configure migration execution defaults\n- [ ] 2. Wave setup\n - [ ] 2.1 Configure migration mode (single-account or multi-account)\n - [ ] 2.2 Verify MGN is initialized in target accounts\n - [ ] 2.3 Verify resource tagging\n - [ ] 2.4 Configure IP assignment strategy\n- [ ] 3. Inventory validation\n - [ ] 3.1 Download and review inventory file (CSV/XLSX)\n - [ ] 3.2 Adjust EC2 instance types, licensing options, tenancy if needed\n - [ ] 3.3 Upload modified inventory or accept as-is\n - [ ] 3.4 Confirm MGN source server records created\n- [ ] 4. Deploy replication agents\n - [ ] 4.1 Choose installation method\n - [ ] 4.2 Set up MGN connector if selected\n - [ ] 4.3 Deploy agents to all servers in the wave\n - [ ] 4.4 Verify all agents connected\n- [ ] 5. Data replication\n - [ ] 5.1 Monitor initial sync progress per server\n - [ ] 5.2 Confirm all servers reach Ready for testing state\n- [ ] 6. Testing\n - [ ] 6.1 Launch test instances (full wave or selective)\n - [ ] 6.2 Validate test instances\n - [ ] 6.3 Mark applications as ready for cutover\n- [ ] 7. Cutover\n - [ ] 7.1 Launch cutover instances within maintenance window\n - [ ] 7.2 Verify cutover instances\n - [ ] 7.3 Finalize cutover\n - [ ] 7.4 Archive source servers (optional)\n```\n\n## Known Limitations\n\n- Agentless replication is not supported — the AWS Replication Agent must be installed on all servers in a wave\n- SSM Hybrid Activations for the MGN connector expire after 30 days — a new connector is required if installing on a new machine after expiration\n- Only one inventory import to a given target account and Region is allowed at a time\n- IP assignment is constrained by the security group mapping strategy: MAP supports static IP only; MAP_DHCP and SKIP support both static and DHCP\n- Deployment approvals require Admin or Approver role in AWS Transform\n- Downtime is unavoidable between source shutdown and cutover instance availability — plan maintenance windows accordingly\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9122,"content_sha256":"f4a9d6ac9ff9dd6105920d02f768e2fd3e455a894e63c102955e645c74c52788"},{"filename":"references/vmware.md","content":"# VMware Migration\n\n> **Last Updated:** 2026-05-10\n\n## Table of Contents\n\n- [Capabilities](#capabilities)\n- [Job Types](#job-types)\n- [Starting Workflow](#starting-workflow)\n- [Agents and Transforms](#agents--transforms)\n- [Decision Points](#decision-points)\n- [Example Requirements](#example-requirements)\n- [Example Tasks](#example-tasks)\n- [Known Limitations](#known-limitations)\n\n## Capabilities\n\nMigrate VMware environments to AWS using generative AI-driven planning and execution. AWS Transform orchestrates the full migration lifecycle — discovery, migration planning, landing zone setup, network migration, and server rehosting to EC2. Supports Windows and Linux servers on supported operating systems (see [MGN supported OS list](https://docs.aws.amazon.com/mgn/latest/ug/Supported-Operating-Systems.html)).\n\n- VMware VMs → Amazon EC2 instances (rehost/lift-and-shift via MGN)\n- AI-driven conversion of VMware network configuration → AWS VPC architecture (VPCs, subnets, security groups, Transit Gateway)\n- AI-driven migration plan generation — application grouping and wave planning\n- Three discovery options: AWS Application Discovery Service collectors, Export for vCenter tool, or independently collected data import\n- Landing zone setup for target AWS accounts\n- Multi-wave migration with per-wave configuration\n- Single-account and multi-account migration support\n\nFor detailed execution guidance see:\n\n- [vmware-server.md](vmware-server.md) — replication agent deployment, data replication, testing, cutover\n- [vmware-network.md](vmware-network.md) — network mapping, topology, IaC generation, deployment\n- [vmware-landing-zone.md](vmware-landing-zone.md) — landing zone foundation and workload account design\n- [vmware-containerization.md](vmware-containerization.md) — source code containerization, Docker artifacts, ECR publishing, EKS/ECS IaC\n\n## Job Types\n\nAWS Transform offers the following VMware migration job types. Steps can be dynamically added or removed at any time to customize the workflow.\n\n| Job Type | Steps Included |\n| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| **End-to-end migration** | Perform discovery → Build migration plan → Connect target accounts → Build landing zone → Migrate network → Migrate servers |\n| **Discovery and migration planning** | Perform discovery → Build migration plan |\n| **Network migration** | Connect target accounts → Migrate network |\n| **Landing zone** | Connect target accounts → Build landing zone |\n| **Landing zone, network, and server migration** | Connect target accounts → Build landing zone → Migrate network → Migrate servers |\n| **Migration planning and server migration** | Perform discovery → Build migration plan → Connect target accounts → Migrate servers |\n| **Source code containerization** | Connect target accounts → Containerize applications → Publish to ECR → Deploy to EKS/ECS |\n\n> One target AWS Region per VMware migration job. To migrate to different Regions, create multiple jobs.\n\n## Starting Workflow\n\n**Before starting:** Confirm job type — determine which steps are in scope based on what the user already has (existing network, existing landing zone, etc.)\n\n1. **Perform discovery** — identify VM count, OS types, resource usage (CPU, memory, storage), and network dependencies using one of the three discovery options\n2. **Build migration plan** — AI-driven application grouping, wave planning, and right-sizing recommendations\n3. **Connect target accounts** — configure target AWS accounts and verify permissions\n4. **Build landing zone** — set up AWS account structure, IAM roles, and baseline infrastructure in target accounts\n5. **Migrate network** — translate VMware network configuration to AWS VPC architecture; deploy via CloudFormation\n6. **Migrate servers** — deploy replication agents, replicate data, test, and cut over wave by wave\n\n**Key questions to ask user:**\n\n- \"Do you already have a landing zone and network set up in the target account(s), or do we need to build those?\"\n- \"Which discovery method do you have available — ADS collectors, Export for vCenter, or an existing data export?\"\n\n## Agent Interaction Rules\n\n**After every job interaction** (sending a message, completing a task, uploading an artifact) — always read the latest messages from the job and surface any agent responses or questions to the user immediately. Do not assume silence means the agent is still processing — it may have already responded.\n\n**Polling priority** — check in this order:\n\n1. Messages (agent chat responses and questions) — check first\n2. Tasks (formal HITL tasks awaiting human input)\n3. Worklogs (agent activity and progress)\n\n**Target account operations — always delegate to the agent:**\nWhen the user asks about resources in the target AWS account (subnets, VPCs, security groups, instances, IAM roles), do NOT query the target account directly. Forward the request to the agent via `send_message` — the agent has connector-based access to the target account.\n\n**Console links — never construct, always use agent-provided:**\nConsole URLs are dynamically generated and scoped to specific connectors, workspaces, and accounts. Always use links provided by the agent in its messages or HITL tasks. If the agent hasn't provided a link, ask it via `send_message` rather than guessing the URL format.\n\n## Agents & Transforms\n\n| Agent | How to Discover | Purpose |\n| ------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |\n| VMware Migration Agent v2 (`vmware-migration-agent-v2`) | `list_resources` with `resource: \"agents\"` | End-to-end orchestration: discovery, planning, network migration, server migration, containerization |\n| Server Migration Agent | `list_resources` with `resource: \"agents\"` | Wave setup, replication agent deployment, replication monitoring, testing, cutover |\n| Landing Zone Agent | `list_resources` with `resource: \"agents\"` | Foundation setup, workload account design, SCP configuration, IaC generation |\n| Network Migration Agent (NMA) | _(sub-agent, invoked by orchestrator)_ | Network mapping, optimization, and IaC generation |\n| Containerization sub-agent | _(sub-agent, invoked by orchestrator)_ | Source code analysis, Docker artifact generation, image building, IaC generation |\n| AWS Application Migration Service (MGN) | External | Actual server replication, testing, and cutover execution |\n| AWS Migration Hub | External | Migration tracking and orchestration |\n\n**Discover agents dynamically:**\n\n```python\nlist_resources(resource=\"agents\")\n# Or ask the chat agent\nsend_message(workspaceId=\"...\", text=\"What agents are available for VMware migration?\")\n# Then create job with discovered orchestratorAgent\ncreate_job(workspaceId=\"...\", jobName=\"VMware Migration\",\n objective=\"Migrate VMware workloads to EC2\", orchestratorAgent=\"vmware-migration-agent-v2\")\n```\n\n## Decision Points\n\n| Decision | Options | When to Ask |\n| ------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| Job type | End-to-end / Discovery and planning / Network only / Landing zone / etc. | Before starting — based on what the user already has |\n| Discovery method | ADS collectors / Export for vCenter / Independent import | Step 1 — before discovery |\n| Migration mode | Single-account / Multi-account | Step 3 — connecting target accounts |\n| Network topology | Hub and Spoke / Isolated VPCs | Step 5 — network migration |\n| Security group strategy | MAP / MAP_DHCP / SKIP | Step 5 — network migration. Determines IP assignment options in Step 6. |\n| IP assignment strategy | Static IP / Dynamic IP (DHCP) | Step 6 — wave setup. Constrained by SG strategy. |\n| Agent installation method | Organization tools / MGN connector / Manual | Step 6 — before replication agent deployment |\n| Testing scope | Full wave / Selective | Step 6 — before launching test instances |\n| Cutover scope | Full wave / Selective | Step 6 — before launching cutover instances |\n\n## Example Requirements\n\n```\n## Requirement 1: VM Discovery and Migration Planning\n\n**User Story:** As an infrastructure engineer, I want all VMware VMs assessed and grouped into waves\nso that I have a clear, prioritized migration plan with right-sized EC2 targets.\n**Acceptance Criteria:**\n\n1. WHEN discovery completes, EACH VM SHALL have a recommended EC2 instance type\n2. WHEN discovery completes, network dependencies between VMs SHALL be documented\n3. WHEN migration plan is built, VMs SHALL be grouped into migration waves with dependency ordering\n **Handled by:** AWS Transform VMware Migration Agent v2\n\n## Requirement 2: Network Migration\n\n**User Story:** As a network engineer, I want VMware network configuration translated to AWS VPC\nso that VM communication patterns are preserved after migration.\n**Acceptance Criteria:**\n\n1. WHEN network mapping completes, EACH source network segment SHALL map to a distinct AWS VPC\n2. WHEN network mapping completes, source firewall rules SHALL be translated to AWS Security Groups\n3. WHEN deployment completes, ALL VPCs, subnets, and security groups SHALL exist in the target account\n **Handled by:** AWS Transform VMware Migration Agent v2 (NMA sub-agent)\n\n## Requirement 3: Server Migration\n\n**User Story:** As an operations engineer, I want VMware servers rehosted to EC2\nso that production workloads run natively on AWS with verified functionality.\n**Acceptance Criteria:**\n\n1. WHEN replication agents are deployed, ALL servers SHALL show replication state INITIATING or INITIAL_SYNC\n2. WHEN test instances are launched (after approval), instance IDs SHALL be provided for each server\n3. WHEN cutover is finalized (after approval), source machine replication SHALL stop and lifecycle state SHALL be locked\n **Handled by:** AWS Transform Server Migration Agent\n```\n\n## Example Tasks\n\n```\n- [ ] 1. Job setup\n - [ ] 1.1 Confirm job type (end-to-end or subset of steps)\n - [ ] 1.2 Confirm single-account or multi-account migration\n - [ ] 1.3 Create and start VMware migration job\n- [ ] 2. Discovery (Step 1)\n - [ ] 2.1 Choose discovery method (ADS / Export for vCenter / independent import)\n - [ ] 2.2 Run discovery and collect VM inventory\n - [ ] 2.3 Review discovery results\n- [ ] 3. Migration planning (Step 2)\n - [ ] 3.1 Review AI-generated application groupings\n - [ ] 3.2 Review and adjust wave assignments\n - [ ] 3.3 Review right-sizing recommendations\n - [ ] 3.4 Approve migration plan\n- [ ] 4. Connect target accounts (Step 3)\n - [ ] 4.1 Provide target AWS account IDs\n - [ ] 4.2 Verify MGN initialized in each target account\n - [ ] 4.3 Verify cross-account IAM roles\n- [ ] 5. Build landing zone (Step 4)\n - [ ] 5.1 Configure landing zone settings\n - [ ] 5.2 Deploy landing zone (approval required)\n - [ ] 5.3 Verify baseline infrastructure in target accounts\n- [ ] 6. Network migration (Step 5) — see vmware-network.md\n - [ ] 6.1 Upload source network file\n - [ ] 6.2 Select topology and security group strategy\n - [ ] 6.3 Review and optimize network design\n - [ ] 6.4 Deploy network (approval required)\n- [ ] 7. Server migration (Step 6) — see vmware-server.md\n - [ ] 7.1 Set up migration wave per wave\n - [ ] 7.2 Validate and confirm inventory\n - [ ] 7.3 Deploy replication agents\n - [ ] 7.4 Monitor data replication\n - [ ] 7.5 Launch test instances (approval required)\n - [ ] 7.6 Mark applications ready for cutover\n - [ ] 7.7 Launch cutover instances (approval required)\n - [ ] 7.8 Finalize cutover and archive source servers\n```\n\n## Known Limitations\n\n- One target AWS Region per VMware migration job — create multiple jobs to migrate to different Regions\n- Stopping a running migration job is irreversible — VMWARE_V2 jobs cannot be restarted once stopped. A new job must be created to start over. Artifacts from the stopped job are preserved but job progress is lost.\n- NSX imports are only supported for end-to-end migration jobs\n- Physical servers (non-virtualized) are not in scope\n- VMware-specific features (vMotion, DRS, HA) have no direct AWS equivalents — require architectural redesign\n- License mapping (Windows Server, SQL Server on VMs) requires manual review\n- AWS Transform generates network configurations and migration strategies based on environment assessment — review with stakeholders before proceeding to ensure security and compliance requirements are met\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":14843,"content_sha256":"1383231c6c766d0b1aa952c523e0b49fa7ae9cc2d837b2dc1f9f238f7640259d"},{"filename":"references/workflow.md","content":"# Table of Contents\n\n- [Quick Start](#quick-start)\n- [CLI vs Managed Agents](#cli-vs-managed-agents)\n- [Choosing a Transformation](#choosing-a-transformation)\n - [By Tech Stack](#by-tech-stack)\n - [By Goal](#by-goal)\n- [Discovery](#discovery)\n - [How It Works](#how-it-works)\n - [Signal Detection](#signal-detection)\n - [Risk Classification](#risk-classification)\n - [Discovery Output](#discovery-output)\n- [Execution Lifecycle](#execution-lifecycle)\n - [Managed Agent Jobs (MCP)](#managed-agent-jobs-mcp)\n - [CLI Transforms](#cli-transforms)\n - [Monitoring](#monitoring)\n - [Parallel Execution](#parallel-execution)\n - [Mandatory Diff Review](#mandatory-diff-review)\n - [Hybrid Workflow](#hybrid-workflow)\n- [Plan Building](#plan-building)\n - [Spec Structure](#spec-structure)\n - [Two Gates](#two-gates)\n - [Iterative Planning](#iterative-planning)\n- [Context Management](#context-management)\n - [Location](#location)\n - [Schema](#schema)\n - [Resume Logic](#resume-logic)\n- [Freshness and Source of Truth](#freshness-and-source-of-truth)\n - [Source of truth: fetch each resource directly](#source-of-truth-fetch-each-resource-directly)\n - [Freshness framing](#freshness-framing)\n - [No false promises of proactive surfacing](#no-false-promises-of-proactive-surfacing)\n - [Transformation goal switching](#transformation-goal-switching)\n- [Display Conventions](#display-conventions)\n - [Interactive Choices](#interactive-choices)\n - [Consultant-Style Observations](#consultant-style-observations)\n - [Status Icons](#status-icons)\n - [Progress](#progress)\n\n---\n\n## Workflow\n\n## Quick Start\n\n| Say This | What Happens |\n| ------------------------------------- | ---------------------------------------------------------------- |\n| \"Analyze this codebase\" | Quick local analysis of architecture and dependencies |\n| \"Start .NET modernization\" | Launch AWS Transform agents to transform .NET Framework → .NET 8 |\n| \"Check my job\" | See job status and progress |\n| \"Review pending requests\" | Handle collaborator requests the agent needs from you |\n| \"Download artifacts\" | Get transformed code, reports, and build outputs |\n| \"Show my workspaces\" | List your AWS Transform workspaces |\n| \"What transformations are available?\" | See available agents for your account |\n\n---\n\n## CLI vs Managed Agents\n\n| | **AWS Transform CLI** | **Managed Agents** |\n| ----------------- | -------------------------------------------------------------------- | ------------------------------------------------ |\n| **Runs on** | Your machine | AWS infrastructure |\n| **Auth** | AWS credentials | Sign in to AWS Transform |\n| **Scope** | Single repo | Multi-repo, specialized workload types |\n| **Best for** | Analysis, small upgrades, custom transformations, applying standards | .NET, mainframe, VMware, SQL, full modernization |\n| **Offline** | Yes | No |\n| **Human-in-loop** | No | Yes (collaborator requests) |\n| **Team features** | No | Yes (shared workspaces) |\n\n**Decision tree:**\n\n```\nWhat do you want to do?\n│\n├─ Quick analysis or standards check? → CLI\n├─ .NET Framework modernization? → Managed Agents\n├─ Mainframe (COBOL/JCL)? → Managed Agents\n├─ VMware → EC2? → Managed Agents\n├─ Database modernization (SQL Server, Oracle)? → Managed Agents\n├─ Java/Python version upgrade? → CLI\n├─ Team collaboration needed? → Managed Agents\n├─ Not sure? → Start with CLI analysis, escalate to Managed Agents if needed\n│\n└─ Best results on complex project? → Hybrid (CLI assess → Managed Agents transform → CLI validate)\n```\n\n---\n\n## Choosing a Transformation\n\n### By Tech Stack\n\n| Stack | Approach | Agent |\n| ------------------------ | -------------- | ---------------------------------------------------------------------------- |\n| .NET Framework 4.x | Managed Agents | `dotnet-chatty-agent` (hardcoded) |\n| .NET Core 3.1 / .NET 5/6 | Managed Agents | Same .NET agent (simpler upgrade) |\n| Java 8/11/17 | CLI | Find Java transformation definitions via `atx custom def list --json` |\n| Spring Boot 2.x → 3.x | CLI | Find Spring Boot transformation definitions via `atx custom def list --json` |\n| COBOL / JCL | Managed Agents | Discover via `list_resources resource=\"agents\"` |\n| VMware VMs | Managed Agents | Discover via `list_resources resource=\"agents\"` |\n| SQL Server / Oracle | Managed Agents | Discover via `list_resources resource=\"agents\"` |\n| Already modern | CLI | Run analysis or standards transformation definitions |\n\n**.NET agent is the only hardcoded name. All others: discover dynamically.**\n\n### By Goal\n\n| Goal | Approach |\n| ---------------------- | --------------------------------------------------------------- |\n| Understand a codebase | CLI: run analysis transformation definition |\n| Modernize legacy app | Identify stack → CLI assessment → Managed Agents transformation |\n| Upgrade a version | CLI for Java/Python; Managed Agents for .NET |\n| Apply coding standards | CLI: find standards transformation definition |\n| Migrate to AWS | Managed Agents (.NET → dotnet-chatty-agent, mainframe, VMware) |\n\n---\n\n## Discovery\n\nDiscovery is a fast scan (~10 sec) that finds what's in the workspace and maps to agents. It is NOT assessment.\n\n### How It Works\n\n1. Glob for project files (signal detection)\n2. Read key files for framework/version\n3. Classify risk: HIGH / MED / LOW\n4. Map to recommended agent\n5. Save to `.atx/discovery.json`\n\n### Signal Detection\n\n| Signal File | What to Extract | Opportunity |\n| -------------------------------------- | ------------------------------------------- | ----------------------- |\n| `pom.xml` | `\u003cjava.version>`, spring-boot version | Java upgrade |\n| `build.gradle` | `sourceCompatibility`, spring boot plugin | Java upgrade |\n| `pom.xml` / `build.gradle` | `com.amazonaws` group | AWS SDK v1 → v2 |\n| `.csproj` | `\u003cTargetFrameworkVersion>v4.x` | .NET modernization |\n| `.csproj` | `\u003cTargetFramework>netcoreapp2.x` / `net5.0` | .NET upgrade |\n| `packages.config`, `Web.config` | Legacy NuGet, `system.web` | .NET modernization |\n| `*.cbl`, `*.cob` | COBOL source | Mainframe modernization |\n| `*.jcl` | JCL job cards | Mainframe modernization |\n| `*.sql` with T-SQL (`GO`, `sp_`) | SQL Server | SQL migration |\n| `*.sql` with PL/SQL (`BEGIN`, `DBMS_`) | Oracle | Oracle migration |\n\n### Risk Classification\n\n| Risk | Criteria | Examples | Say This to Users |\n| -------- | ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |\n| **HIGH** | EOL/deprecated | Java 8, .NET FW 4.x, COBOL, Spring Boot 1.x, Spring Framework 5.x | No longer receiving security updates — migration recommended |\n| **MED** | Patched or near-EOL | Java 11, .NET 9 | Approaching end of life — plan migration soon |\n| **LOW** | Minor version lag | Java 17→21 | Current but not latest — optional upgrade for new features |\n\n### Discovery Output\n\nSave to `.atx/discovery.json`:\n\n```json\n{\n \"discoveredAt\": \"...\",\n \"components\": [\n {\n \"path\": \"order-service/\",\n \"stack\": \"Java 8, Spring Boot 1.5.22\",\n \"risk\": \"HIGH\",\n \"reason\": \"Java 8 EOL Jan 2019\",\n \"recommendedAgent\": \"AWS Transform CLI (find Java transformation definition via atx custom def list --json)\"\n }\n ]\n}\n```\n\nPresent as migration table:\n\n```\n| Risk | Why | Component | Current | Target | AWS Target | Recommended Approach |\n|------|-----|-----------|---------|--------|------------|---------------------|\n| HIGH | No longer receiving security updates | order-service/ | Java 8 | Java 25 | — | CLI |\n| HIGH | No longer receiving security updates | storefront/ | .NET FW 4.7.2 | .NET 8 | — | Managed Agents |\n```\n\n---\n\n## Execution Lifecycle\n\nAll transformations follow this pattern:\n\n### Managed Agent Jobs (MCP)\n\n```\n1. Create/select workspace create_workspace\n2. Set up connectors create_connector (if agent requires them)\n3. Create and start job create_job\n4. Drive conversation send_message\n5. Handle collaborator requests complete_task (see tools.md)\n6. Download results get_resource resource=\"artifact\"\n```\n\n**Your IDE is the bridge between user and AWS Transform agent:**\n\n- Agent asks a question → present options and wait for user decision\n- User answers → relay via `send_message` or `complete_task`\n- Agent needs files → upload via `upload_artifact`\n- Agent produces results → download via `get_resource resource=\"artifact\"`\n\n**Rule: Present options to user, user decides, relay decision. Never shortcut this.**\n\n### CLI Transforms\n\n```bash\n# Always run in background\nAWS_REGION=us-east-1 atx custom def exec -n \u003cname> -p \u003cpath> -x -t\n```\n\nUse `run_in_background=true` in your IDE.\n\n### Monitoring\n\nFor job status and progress, ask the agent directly — it has full job context:\n\n```\nsend_message # Scoped to the job: \"What's the current status?\"\nlist_resources resource=\"worklogs\" # Recent activity log\nlist_resources resource=\"tasks\" # Pending collaborator requests — always check\n```\n\nFall back to lower-level resources only if the agent's answer is unclear or you need specifics it didn't cover:\n\n```\nget_resource resource=\"job\" # Status: CREATED, STARTING, ASSESSING, PLANNING, PLANNED, EXECUTING, AWAITING_HUMAN_INPUT, COMPLETED, FAILED, STOPPING, STOPPED\nlist_resources resource=\"plan\" # Phases and current step\nlist_resources resource=\"messages\" # Raw messages from agent\n```\n\n**Monitoring loop:**\n\n- Ask the agent via `send_message` + check `worklogs`\n- Always check `list_resources resource=\"tasks\"` — active job status does not imply no pending user tasks\n- Always check `list_resources resource=\"messages\"` — messages with a non-null `interactions` array (selection menus, confirmations) may be awaiting a user response via `send_message`. These interactive prompts do NOT appear as tasks and do NOT change the job status. A job can remain in EXECUTING status with no pending tasks while the agent is waiting on a user reply to an interactive message.\n- When a collaborator request appears → present to user, relay decision\n- When job completes → download artifacts\n- When job fails → show error, offer retry\n\n**Waiting between re-checks.** When a resource is in a transitional state and you need to re-check after a delay, use `adaptive_poll` rather than responding with stale data or silently stalling. Follow the tool's own description for terminal states and approval requirements. During an active, user-approved polling loop, present-tense status framing is fine (see Freshness below); outside that loop, do not promise proactive surfacing.\n\n### Parallel Execution\n\n- CLI and Managed Agents on **different** components → run in parallel\n- Two CLI transforms on different projects → both `run_in_background`\n- Same component → sequential\n- Each workspace can only run **one job at a time**\n\n### Mandatory Diff Review\n\nAfter ANY transform that changes code, show `git diff` summary then present options and wait for user decision:\n\n- \"Accept Changes\"\n- \"Revert\"\n- \"Review File-by-File\"\n\nUser MUST approve before next task.\n\n### Hybrid Workflow\n\nFor best results, combine CLI and Managed Agents:\n\n1. **Assess locally** (CLI) — run analysis transformation definition, understand codebase\n2. **Transform with Managed Agents** — use findings to guide agents (pass in `intent` field)\n3. **Validate locally** (CLI) — apply org standards to output\n\n---\n\n## Plan Building\n\n### Spec Structure\n\nOne spec at `.atx/specs/`:\n\n```\n.atx/specs/\n .config # {\"specId\":\"aws-transform\",\"workflowType\":\"requirements-first\",\"specType\":\"feature\"}\n requirements.md # Numbered requirements with user stories and acceptance criteria\n tasks.md # Hierarchical checkboxes referencing requirements\n```\n\nFor multi-module projects, use **sections within the same spec** — not separate specs.\n\n### Two Gates\n\n**Gate 1: Scope Confirmation** (after discovery, before requirements)\n\n- Present scope summary: components, risk levels, estimated task count\n- User confirms or adjusts\n\n**Gate 2: Plan Approval** (after requirements, before execution)\n\n- Present full plan: task count, phases, parallel groups\n- User confirms \"Start Execution\" or adjusts\n\nBetween gates: agent works autonomously. After Gate 2: execution proceeds with diff review as the ongoing control mechanism.\n\n### Iterative Planning\n\n```\nwhile not done:\n 1. Read requirements.md + tasks.md + .atx/context.json\n 2. Pick the most important incomplete task\n 3. Execute ONE task\n 4. Review diffs — get user approval if code changed\n 5. Mark task [x], update context\n 6. If new issues found, add to tasks.md\n```\n\nOne task per iteration. Fresh analysis each time. State on disk.\n\n---\n\n## Context Management\n\n### Location\n\n```\n.atx/context.json ← workspace-relative, source of truth\n.atx/discovery.json ← discovery findings\n.atx/specs/ ← requirements + tasks\n```\n\n**NEVER read from `~/.aws/atx/context.json`** — that's the MCP server's internal state, not this skill's. Context is always relative to the workspace directory.\n\nAdd `.atx/` to `.gitignore`.\n\n### Schema\n\n```json\n{\n \"phase\": \"intent|discovery|scoped|assessed|requirements|planning|executing|complete\",\n \"discovery\": { \"completedAt\": \"...\", \"components\": 3, \"discoveryFile\": \".atx/discovery.json\" },\n \"assessment\": {\n \"completedAt\": \"...\",\n \"workspaceId\": \"...\",\n \"jobId\": \"...\",\n \"reportDir\": \".atx/assessment-report/\"\n },\n \"spec\": { \"folder\": \".atx/specs\", \"requirementsApproved\": false, \"tasksGenerated\": false },\n \"workStyle\": null,\n \"execution\": {\n \"currentTask\": \"1.2\",\n \"completedTasks\": [\"1.1\"],\n \"workspaceId\": null,\n \"activeJobIds\": []\n },\n \"updatedAt\": \"...\"\n}\n```\n\n### Resume Logic\n\nSilently check for `.atx/context.json`.\n\n**No context found:** Proceed directly to the Intent step. Never reference internal step numbers in user-facing text — no \"Step 1\", \"Step 2\", or similar. Your first user-facing message must be the intent menu itself, with zero preamble.\n\n**Context found:** Before resuming, silently try to refresh live state from the service:\n\n1. **Check auth first** (no-auth-required). Use the MCP tool that reports auth/sign-in status (discover it from `tools/list`). If sign-in is NOT configured, skip the refresh entirely and use local context only. Do NOT attempt further service calls, do NOT mention auth to the user, do NOT demand sign-in.\n2. **If sign-in is configured**, fetch each resource your resume message depends on. Each resource has its own source of truth — do NOT infer one from another (e.g., a job in an active state like `EXECUTING` does not mean no pending user tasks). At minimum:\n - The **job** itself — what phase is it in, has it completed or failed.\n - Any **pending tasks** — HITL tasks requiring user action. Fetch ALL pending tasks, not just one. **Surface every pending task to the user — do NOT cherry-pick the most prominent and omit the rest.** Each task (input-needed, approval-pending, etc.) is something the user needs to know about. `BLOCKING` tasks hold up progress even when the job is in an active state; `NON_BLOCKING` tasks still need attention but don't stall the job. Name every pending task in the resume message; flag which ones are blocking.\n3. **If any call fails**, silently fall back to local context. Do NOT mention the failure to the user.\n\nTool names come from the server's `tools/list` response; read tool descriptions directly rather than hardcoding names in resume logic.\n\nThen tell the user about their prior session, framing the offer as a **continuation of that same session** — not a similar new one:\n\n- Use explicit continuation language: \"continue where you left off\", \"pick up from where you stopped\".\n- What phase was reached (e.g., \"last time, your session finished assessment\")\n- What key artifacts exist (e.g., workspace ID, assessment report)\n- **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.\"\n- **Refresh failed or was skipped** → use prior-session framing (\"last time\", \"when you paused\", \"previously\"). Do NOT present-tense claims about job state; local context may be stale. Offer sign-in as the path to current status — a benefit, not a gate (\"sign in to see the latest status\").\n- Clarify what resume vs. start-fresh means in user terms:\n - **Resume** = continue the same session, reusing the existing assessment report, workspace, and prior progress.\n - **Start fresh** = discard the prior session (local artifacts deleted) and begin a brand-new migration.\n\nIf user chooses **start fresh**: delete `.atx/context.json`, `.atx/discovery.json`, `.atx/assessment-report/`, and `.atx/specs/`, then proceed to the Intent step.\n\nIf user chooses **resume**, resume based on `phase`:\n\n| Phase | Resume Action |\n| -------------- | ------------------------------------------------------- |\n| `intent` | Present intent options again, continue based on choice |\n| `discovery` | Show migration table, continue to scope |\n| `scoped` | Show selected scope, continue to assessment |\n| `assessed` | Show assessment summary, draft requirements from report |\n| `requirements` | Show current requirements, ask to approve or edit |\n| `planning` | Show tasks, ask to start execution |\n| `executing` | Show progress, pick next task |\n| `complete` | Show summary, ask what's next |\n\n---\n\n## Freshness and Source of Truth\n\nResume Logic (above) dictates how you frame status at session start. The same discipline applies to **every in-session turn**.\n\n### Source of truth: fetch each resource directly\n\nEach MCP resource (job, tasks, messages, artifacts, connectors, ...) is its own source of truth on the server. Do NOT infer one resource's state from another's. In particular:\n\n- An active job status (`ASSESSING`, `PLANNING`, `EXECUTING`) ≠ no pending user tasks. The agent may be blocked waiting on a checkpoint decision while the job status still reads as active. The job itself can also enter `AWAITING_HUMAN_INPUT`, but ONLY for `BLOCKING` tasks tied to a plan step — `NON_BLOCKING` tasks never trigger this transition. A job in an active state may still have multiple pending `NON_BLOCKING` tasks. So always fetch the tasks resource; don't rely on job status alone.\n- Job status COMPLETED ≠ no artifacts pending review.\n- An absence of recent messages ≠ no pending tasks.\n\nWhen the user-facing message depends on a resource, fetch THAT resource. Don't synthesize. The MCP tool surface is the ground truth — discover the right tool name from the server's `tools/list` response (see [tools](tools.md)), not from memory.\n\n### Freshness framing\n\nA \"turn\" is one user message → one of your responses. Tool calls made while composing the response count as part of the same turn; calls made for a prior user message do not.\n\nAny user-facing claim about job state, messages, tasks, or artifacts must be either:\n\n- **Just-fetched** — you called the relevant read tool (`get_resource`, `list_resources`) in THIS turn, before answering → present tense is OK (\"your job is running\").\n- **Cached** — no fresh fetch this turn → frame as cached AND offer to refresh.\n\nA fetch from a prior turn, resume, or the initial session refresh does NOT count as fresh. You have no clock — the user may have been away for hours; the job may have changed.\n\n**Cached framing must scope the ENTIRE claim.** Lead with the cached marker; every status verb must be past-tense. A trailing \"as of earlier\" does not retroactively qualify a present-tense leading clause.\n\n- WRONG: \"Your job is handling the assessment phase. As of the last check, it was running.\"\n- RIGHT: \"As of my last check, your job was handling the assessment phase and running VM tasks. Want me to pull the latest?\"\n\nException: during an active polling loop (see workload steering files), present tense is fine — the fetch really is happening on each cycle.\n\n### No false promises of proactive surfacing\n\nWhen NOT polling, do NOT imply background monitoring. Phrases like \"I'll let you know when...\", \"I'll surface those as they come up\", \"I'll ping you if...\" mislead users into assuming this skill is watching the job.\n\nWhen not polling, make the reactive model explicit: \"You'll need to ask me — I don't watch in the background\" / \"Say 'check status' and I'll pull the latest.\"\n\n\"I'll update you as the job progresses\" is only acceptable during an active polling loop.\n\n### Transformation goal switching\n\nTrack the \"active goal\" — what the user is trying to accomplish (e.g., \"modernize this VMware fleet\"). Two jobs serving the same goal are ONE goal.\n\nWhen the user's message shifts to a DIFFERENT goal (different workload, different migration target, or a clearly different body of work), before answering:\n\n1. Recognize the shift. Trigger is a change in what the user is accomplishing, not a field-by-field ID comparison.\n2. Ask the user and suggest they start a new chat session with fresh context (they start it themselves — you cannot). Give a brief reason: mixing unrelated goals causes cross-contaminated answers.\n3. Wait for their choice. If accepted, stop answering about the new goal in this chat. If declined, **answer the user's question in this chat** — respect their choice. Just do not mix cached state from the prior goal into your answers. Do not re-push the new-chat suggestion until the next goal shift.\n\n**Re-offer on every shift**, because cross-contamination compounds. But keep re-offers terse — \"Different goal again — want a new chat session? [Yes] [Stay here]\" — don't re-lecture.\n\nCarve-out: historical, past-tense questions about a prior goal (\"what did my .NET modernization produce last week?\") do NOT trigger the suggestion.\n\n---\n\n## Display Conventions\n\n### Interactive Choices\n\nAlways present options and wait for user decision when offering choices.\n\nExample interaction format:\n\n- Question: \"How would you like to proceed?\"\n- Options with descriptions:\n - \"Approve (Recommended)\" - Start executing\n - \"Modify\" - Change the plan\n - \"Explain\" - Deep dive into why this order\n\n**Do NOT use markdown bullets or numbered lists for choices.** Create clickable UI elements.\n\n### Consultant-Style Observations\n\n2-3 sentences max. State what you found, then what's possible. No data dumps. Never narrate tool calls — describe outcomes, not mechanics.\n\n### Status Icons\n\n```\n[ ] Pending [Running] Running [Done] Done [Failed] Failed\n```\n\n### Progress\n\n```\nSteps: 2 of 5 complete\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":25171,"content_sha256":"8ee176891a1b9ac634a790de2d4428aa869931fabb87d5a2f379097efafdd8ac"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"AWS Transform","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill requires the AWS Transform MCP server (","type":"text"},{"text":"aws-transform-mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Configure it in your agent's MCP settings:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"mcpServers\": {\n \"aws-transform-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\n \"awslabs.aws-transform-mcp-server@latest\"\n ]\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"The AWS Transform CLI is also required for custom transformations. Install via:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mandatory workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Resume → Check .atx/context.json\nIntent → Ask user what they want to do\nDiscovery → Scan workspace + query available agents\nScope → User selects what to modernize (GATE 1)\nAssessment → Run workload assessment (NOT optional)\nRequirements → Draft from assessment report\nApproval → User approves requirements (GATE 2)\nTasks → Generate tasks.md\nExecute → Run transforms, monitor, review diffs","type":"text"}]},{"type":"paragraph","content":[{"text":"Discovery finds opportunities. Assessment produces detailed findings. Requirements come from the assessment — NOT from discovery.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"You MUST NOT create requirements without an assessment report. You MUST NOT start execution without requirements.md and tasks.md.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resuming a prior session","type":"text"}]},{"type":"paragraph","content":[{"text":"Check for ","type":"text"},{"text":".atx/context.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" (workspace-relative). NEVER read ","type":"text"},{"text":"~/.aws/atx/kiro-power-context.json","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"This check is an internal bookkeeping operation. The user must never see it happen.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No context found:","type":"text","marks":[{"type":"strong"}]},{"text":" Proceed directly to intent. Produce no user-visible output for this step.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Context found:","type":"text","marks":[{"type":"strong"}]},{"text":" If the context has an active job (","type":"text"},{"text":"assessment.jobId","type":"text","marks":[{"type":"code_inline"}]},{"text":" or entries in ","type":"text"},{"text":"execution.activeJobIds","type":"text","marks":[{"type":"code_inline"}]},{"text":"), try to refresh live state from the service, but do so invisibly:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check auth first","type":"text","marks":[{"type":"strong"}]},{"text":" (no-auth-required). If sign-in is NOT configured, skip the refresh entirely — do not attempt service calls. Use local context only.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If sign-in is configured","type":"text","marks":[{"type":"strong"}]},{"text":", 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. ","type":"text"},{"text":"BLOCKING","type":"text","marks":[{"type":"code_inline"}]},{"text":" HITL tasks hold up progress even when the job status is active; ","type":"text"},{"text":"NON_BLOCKING","type":"text","marks":[{"type":"code_inline"}]},{"text":" tasks still need attention but don't stall the job. Name every pending task; flag blocking ones. Don't infer one resource from another.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If any call fails","type":"text","marks":[{"type":"strong"}]},{"text":" for any reason, silently fall back to local context. ","type":"text"},{"text":"Do NOT reveal your reasoning about the refresh to the user","type":"text","marks":[{"type":"strong"}]},{"text":" — 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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Then tell the user about their prior session. Frame the offer explicitly as a ","type":"text"},{"text":"continuation","type":"text","marks":[{"type":"strong"}]},{"text":" of that same session — not a new one. The message should make clear:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"This is the specific session they previously worked on. Mention the phase reached, workspace/job identifiers if relevant.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Refresh succeeded","type":"text","marks":[{"type":"strong"}]},{"text":" → 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.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Refresh failed or was skipped","type":"text","marks":[{"type":"strong"}]},{"text":" → 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resume","type":"text","marks":[{"type":"strong"}]},{"text":" = continue where you left off, reusing the existing assessment report, workspace, and prior progress.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Start fresh","type":"text","marks":[{"type":"strong"}]},{"text":" = discard the prior session (local artifacts deleted) and begin a brand-new migration.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":".atx/context.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".atx/discovery.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".atx/assessment-report/","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":".atx/specs/","type":"text","marks":[{"type":"code_inline"}]},{"text":", then proceed to intent. Otherwise follow the resume logic in ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Determining user intent","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"With projects: [Discover This Workspace] [Browse My Jobs] [Start a Specific Transform] No projects: [Browse My Jobs] [Open a Project Folder] [Start from Scratch]","type":"text"}]},{"type":"paragraph","content":[{"text":"Just-in-time auth.","type":"text","marks":[{"type":"strong"}]},{"text":" 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, ","type":"text"},{"text":"get_status","type":"text","marks":[{"type":"code_inline"}]},{"text":", 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"auth reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/auth.md","title":null}}]},{"text":" for the MCP-vs-CLI auth split and how to present sign-in options.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Discovery","type":"text"}]},{"type":"paragraph","content":[{"text":"Fast scan (~10 sec). Three things happen in parallel:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scan the workspace","type":"text","marks":[{"type":"strong"}]},{"text":" — detect languages, frameworks, file types, and dependencies present in the project.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Query available agents","type":"text","marks":[{"type":"strong"}]},{"text":" — call ","type":"text"},{"text":"list_resources","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"resource: \"agents\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" (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:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Orchestrator agents","type":"text","marks":[{"type":"strong"}]},{"text":" — top-level agents you create jobs with. Each orchestrator may have sub-agents that provide deeper workload-specific capabilities.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Sub-agents","type":"text","marks":[{"type":"strong"}]},{"text":" — invoked through their orchestrator, not directly. They represent specialized skills within a workload type.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Some agents may not belong to a known orchestrator — treat these as standalone capabilities.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"List available transformation definitions","type":"text","marks":[{"type":"strong"}]},{"text":" — call ","type":"text"},{"text":"atx custom def list","type":"text","marks":[{"type":"code_inline"}]},{"text":" (CLI) to get the current set and what they transform. Skip if CLI is not available or the user's intent is MCP-only.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"list_resources","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns NOT_CONFIGURED, prompt the user to sign in for the auth system needed — do not demand both.","type":"text"}]},{"type":"paragraph","content":[{"text":"Then ","type":"text"},{"text":"match","type":"text","marks":[{"type":"strong"}]},{"text":" 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 ","type":"text"},{"text":".atx/discovery.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" — include the orchestrator → sub-agent hierarchy so later steps know what deeper capabilities are available.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":" for the workspace scanning framework.","type":"text"}]},{"type":"paragraph","content":[{"text":"Discovery is NOT assessment.","type":"text","marks":[{"type":"strong"}]},{"text":" Discovery identifies opportunities and matches them to available agents. Assessment produces the detailed findings.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Scoping (GATE 1)","type":"text"}]},{"type":"paragraph","content":[{"text":"For each matched workload type, read ALL reference files with its prefix (e.g., ","type":"text","marks":[{"type":"strong"}]},{"text":"dotnet","type":"text","marks":[{"type":"link","attrs":{"href":"references/dotnet.md","title":null}},{"type":"strong"}]},{"text":").","type":"text","marks":[{"type":"strong"}]},{"text":" These contain the workload's capabilities, workflow, agent details, example requirements, and known limitations. The file prefix comes from the agent match in Discovery — not from a hardcoded list.","type":"text"}]},{"type":"paragraph","content":[{"text":"Show migration table, then let the user select with multiSelect:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"| Risk | Why | Component | Current | Target | AWS Target | Recommended Approach |","type":"text"}]},{"type":"paragraph","content":[{"text":"Always explain risk in plain language in the \"Why\" column — use the user-facing phrases from the Risk Classification table in ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":". Never show a bare HIGH/MED/LOW label without explanation.","type":"text"}]},{"type":"paragraph","content":[{"text":"User selects what to modernize.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Assessment","type":"text"}]},{"type":"paragraph","content":[{"text":"This is NOT optional. Run the workload's assessment BEFORE creating requirements.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Tell the user: \"I'll assess your workload. The assessment report drives the migration plan.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"How assessment runs depends on the workload's reference files.","type":"text","marks":[{"type":"strong"}]},{"text":" Each workload type defines its own assessment approach — the agent to use, the objective format, and how to collect results. Consult the matched workload's reference files for specifics.","type":"text"}]},{"type":"paragraph","content":[{"text":"General pattern for agent-based assessment:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm the plan","type":"text","marks":[{"type":"strong"}]},{"text":" — tell the user what you will do (create workspace, create job with which agent, what the objective is). WAIT for approval before calling any tools.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create/select workspace","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create job with a ","type":"text"},{"text":"clear objective","type":"text","marks":[{"type":"strong"}]},{"text":" — the workload's reference files define what a good objective looks like","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Start the job (already started by ","type":"text"},{"text":"create_job","type":"text","marks":[{"type":"code_inline"}]},{"text":"; use ","type":"text"},{"text":"control_job","type":"text","marks":[{"type":"code_inline"}]},{"text":" to restart if stopped)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Send a ","type":"text"},{"text":"detailed follow-up message","type":"text","marks":[{"type":"strong"}]},{"text":" with project specifics","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask before uploading","type":"text","marks":[{"type":"strong"}]},{"text":" — ask how the user wants to share source code. WAIT. Then upload with ","type":"text"},{"text":"categoryType: \"CUSTOMER_INPUT\"","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Handle agent requests (checkpoints, decisions) — always present to user, WAIT for user response","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When assessment completes, download the report: ","type":"text"},{"text":"get_resource resource=\"artifact\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Save report to ","type":"text"},{"text":".atx/assessment-report/","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Rule: NEVER batch workspace creation, job creation, and uploads into a single turn without user confirmation at each decision point.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Use the orchestrator agent or transformation definition identified during Discovery. The match comes from ","type":"text"},{"text":"list_resources","type":"text","marks":[{"type":"code_inline"}]},{"text":" (with ","type":"text"},{"text":"resource: \"agents\"","type":"text","marks":[{"type":"code_inline"}]},{"text":") and ","type":"text"},{"text":"atx custom def list","type":"text","marks":[{"type":"code_inline"}]},{"text":", not a hardcoded mapping. When creating a job, specify the orchestrator — sub-agents are invoked by the orchestrator as needed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Update ","type":"text"},{"text":".atx/context.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"phase: \"assessed\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", workspace ID, job ID.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Requirements (from assessment report)","type":"text"}]},{"type":"paragraph","content":[{"text":"Now create ","type":"text"},{"text":".atx/specs/requirements.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" using the ","type":"text"},{"text":"assessment report","type":"text","marks":[{"type":"strong"}]},{"text":" — NOT discovery findings.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":".atx/assessment-report/","type":"text","marks":[{"type":"code_inline"}]},{"text":" for detailed findings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Load workload reference files for context","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Draft requirements grounded in the assessment (specific blockers, LOC, complexity, migration paths)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each requirement says WHO handles it: AWS Transform CLI / Managed Agents / IDE","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Multi-module: group by module with Module Overview table","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":" for format","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do NOT create tasks.md yet.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Show requirements summary and let the user choose: [Looks Good] [Edit] [Add Component]","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Approval (GATE 2)","type":"text"}]},{"type":"paragraph","content":[{"text":"Ask the user: \"Requirements finalized. Ready to create the execution plan?\" [Create Plan] [Edit More]","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Task generation","type":"text"}]},{"type":"paragraph","content":[{"text":"Generate ","type":"text"},{"text":"tasks.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" from approved requirements:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Module Status table + per-module sections","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Sized: max 100 files/task","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parallel groups verified","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review-diffs after every code change","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":" for format","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Present options: [Start Execution] [Review Tasks] [Modify]","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Execution","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":" for full details.","type":"text"}]},{"type":"paragraph","content":[{"text":"How execution runs depends on the workload's reference files.","type":"text","marks":[{"type":"strong"}]},{"text":" Each workload type defines its own execution tooling — which agent or CLI command to use, how to parallelize, and how to collect results. Consult the matched workload's reference files.","type":"text"}]},{"type":"paragraph","content":[{"text":"General pattern for agent-based execution:","type":"text"}]},{"type":"paragraph","content":[{"text":"When creating new jobs, always:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Clear objective","type":"text","marks":[{"type":"strong"}]},{"text":" in ","type":"text"},{"text":"create_job","type":"text","marks":[{"type":"code_inline"}]},{"text":" — what to transform, from what, to what","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Detailed follow-up message","type":"text","marks":[{"type":"strong"}]},{"text":" via ","type":"text"},{"text":"send_message","type":"text","marks":[{"type":"code_inline"}]},{"text":" — project specifics, discovery findings, blockers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Upload artifacts","type":"text","marks":[{"type":"strong"}]},{"text":" if agent needs code — ask user first, ","type":"text"},{"text":"categoryType: \"CUSTOMER_INPUT\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Every agent request → user decides (NEVER auto-handle)","type":"text"}]},{"type":"paragraph","content":[{"text":"When the AWS Transform agent asks for input, needs files, or hits a checkpoint:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read the task/message","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Present to user","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WAIT for user response","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Relay user's decision back to agent","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Uploading artifacts to agents","type":"text"}]},{"type":"paragraph","content":[{"text":"Always use ","type":"text"},{"text":"categoryType: \"CUSTOMER_INPUT\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" when uploading files to an agent:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"python"},"content":[{"text":"upload_artifact(\n workspaceId=\"...\", jobId=\"...\",\n content=\"/path/to/source.zip\",\n fileType=\"ZIP\",\n categoryType=\"CUSTOMER_INPUT\"\n)","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"categoryType","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When to Use","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CUSTOMER_INPUT","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Uploading files TO the agent (source code, configs, data)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CUSTOMER_OUTPUT","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Downloading files FROM the agent (reports, migrated code)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HITL_FROM_USER","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"User responses to agent HITL tasks","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":" for agent request handling patterns.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Progress","type":"text"}]},{"type":"paragraph","content":[{"text":"Review diffs after every code change. User must approve. Update tasks.md checkboxes + ","type":"text"},{"text":".atx/context.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" after every step.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Context persistence (.atx/context.json)","type":"text"}]},{"type":"paragraph","content":[{"text":"Save ","type":"text"},{"text":".atx/context.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" IMMEDIATELY after completing each phase — before presenting results to the user. Every phase transition must have a context save between them. Top-level keys: ","type":"text"},{"text":"phase","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"discovery","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"assessment","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"spec","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"workStyle","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"execution","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"updatedAt","type":"text","marks":[{"type":"code_inline"}]},{"text":". See ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":" for the full schema.","type":"text"}]},{"type":"paragraph","content":[{"text":"Resume: read ","type":"text"},{"text":"phase","type":"text","marks":[{"type":"code_inline"}]},{"text":", pick up from that phase.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Constraints","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST use product, capability, and step names exactly as defined in this document. Never paraphrase or invent terminology. When describing this skill's capabilities, use: \"Migrate, modernize, and upgrade codebases — .NET, mainframe COBOL, VMware, databases, and language/SDK upgrades — using AWS Transform CLI and Managed Agents, directly from your IDE.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST present user choices as an explicit selectable list — never bury options in prose or proceed on an inferred answer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST run CLI commands in background — never block the conversation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST discover agents dynamically via ","type":"text"},{"text":"list_resources","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"resource: \"agents\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" (paginated) — do not hardcode agent names","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST create jobs with orchestrator agents — sub-agents are invoked by the orchestrator, not directly","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST refer to resources by name, not ID. When referencing a workspace, job, agent, or artifact in user-facing messages, use its human-readable name. Never surface raw UUIDs in prose. If a resource has no name, use a descriptive phrase (\"your .NET modernization job\") rather than the ID.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT expose internal mechanics to the user — do not name tools (get_status, list_resources), do not cite step numbers, do not reference files you are reading, and do not narrate what you are about to do. Just do it silently and present the outcome in user terms.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT mix workflow descriptions with actual questions in the same numbered list, and never use count language like \"two questions\" when some items are informational steps rather than questions. Keep what-I-will-do separate from what-I-need-from-you.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT frame HITL checkpoints, agent questions, or pending decisions as coming from \"the web app\", \"the webapp\", \"the web UI\", or a third-party \"the agent is asking / the agent needs / the agent wants\". The user is working with you in the IDE — you own the interaction. Present every checkpoint as your own first-person request, not a relayed message from elsewhere. ","type":"text"},{"text":"Wrong:","type":"text","marks":[{"type":"strong"}]},{"text":" \"The web app is asking how you want to deploy the landing zone.\" / \"The agent is now asking about the replication subnet configuration.\" ","type":"text"},{"text":"Right:","type":"text","marks":[{"type":"strong"}]},{"text":" \"The next step is to choose how to deploy the landing zone.\" / \"I need the replication subnet configuration to continue.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT explain what this skill does","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT create requirements from discovery — wait for assessment","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT skip from discovery to execution","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT modify code, upgrade dependencies, or run analysis manually — always use AWS Transform tooling","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT make decisions on behalf of the user","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT editorialize or use subjective language — no \"interesting\", \"fascinating\", \"notably\", \"impressive\", \"remarkable\". State findings as facts.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT prompt for authentication before the user has declared an intent. Auth prompts come from the tool a chosen action needs, framed around that action.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT overclaim freshness. If you did NOT fetch a resource this turn, lead with \"last I checked\" (past tense throughout) and offer to refresh. Never promise proactive surfacing (\"I'll let you know when…\") unless actively polling — make the reactive model explicit.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT infer one resource's state from another — each MCP resource (job, tasks, artifacts) is its own source of truth. A job in an active state does NOT imply no pending user tasks. Fetch each resource directly when relevant. See ","type":"text"},{"text":"workflow reference","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST NOT mix unrelated transformation goals in the same chat without warning. On every shift to a different goal, suggest the user start a new chat session (they start it themselves). Keep re-offers terse. If the user declines, proceed to answer their question about the other job — do not refuse or redirect back to the original goal. Just avoid mixing cached state (e.g., don't apply VMware findings to the .NET question).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MUST store state in ","type":"text"},{"text":".atx/context.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Core","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Topic","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Authentication (sign-in, AWS credentials, CLI credentials, errors)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/auth.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/auth.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tools (MCP tools, CLI commands, connectors, HITL, troubleshooting)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/tools.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/tools.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Workflow (discovery, transforms, execution, planning, context, display)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/workflow.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/workflow.md","title":null}}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Workload Types","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Workload","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Files","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":".NET","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/dotnet*.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SQL/Database","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/sql*.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mainframe","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/mainframe*.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"VMware","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/vmware*.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Custom","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/custom*.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Each workload type has a root reference file with its capabilities, workflow, and agent details. Additional files with the same prefix provide deeper guidance (e.g., ","type":"text"},{"text":"custom-cli-reference.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"custom-repo-analysis.md","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},"metadata":{"date":"2026-06-05","name":"aws-transform","author":"@skillopedia","source":{"stars":765,"repo_name":"agent-plugins","origin_url":"https://github.com/awslabs/agent-plugins/blob/HEAD/plugins/aws-transform/skills/aws-transform/SKILL.md","repo_owner":"awslabs","body_sha256":"9b0561cc02d17f42dc73e8f4bd2bce41620d802cf1283fedaf97436d6d3171eb","cluster_key":"292940760f0d08cb9db5c2bd811ac5656c44c27d0d5a75cc20f454c6aee3bdf0","clean_bundle":{"format":"clean-skill-bundle-v1","source":"awslabs/agent-plugins/plugins/aws-transform/skills/aws-transform/SKILL.md","attachments":[{"id":"a1fed972-9eda-5767-ae01-e4f55b0fb015","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a1fed972-9eda-5767-ae01-e4f55b0fb015/attachment.md","path":"references/auth.md","size":2872,"sha256":"4727f7ef38346b94ed09c7ca6c8029361b51b41bfa9479eeddd7601c534735d3","contentType":"text/markdown; charset=utf-8"},{"id":"b3da5d13-0198-59d8-8c01-46641d3dd912","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b3da5d13-0198-59d8-8c01-46641d3dd912/attachment.md","path":"references/custom-cli-reference.md","size":9609,"sha256":"1f6e587fd1af83aad93a7c7ef5f2249f0eeb1161592bf7d0d246b4155d6cb44b","contentType":"text/markdown; charset=utf-8"},{"id":"96ddadd8-8236-5c82-a37c-8124acee92d9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/96ddadd8-8236-5c82-a37c-8124acee92d9/attachment.md","path":"references/custom-multi-transformation.md","size":10221,"sha256":"e1e552e87b60f3bd2c12282af89bc9fbab4c8bded49d338162bd010c54779fe7","contentType":"text/markdown; charset=utf-8"},{"id":"026b0b48-9fea-5580-8668-0784be95f660","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/026b0b48-9fea-5580-8668-0784be95f660/attachment.md","path":"references/custom-remote-execution.md","size":20318,"sha256":"cbf913186c445510394a791665329819663bad2abf1cdd3650331ff93986694a","contentType":"text/markdown; charset=utf-8"},{"id":"ca7bd3b5-6a2b-5f39-bf0c-464bcf6272a6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ca7bd3b5-6a2b-5f39-bf0c-464bcf6272a6/attachment.md","path":"references/custom-repo-analysis.md","size":7443,"sha256":"e0fb35b8bb9434ea561339076666ac6efcbd80501b64eb61d43175f4bf5c10f3","contentType":"text/markdown; charset=utf-8"},{"id":"268e07b7-7587-50b4-b55f-7d5f62e829e1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/268e07b7-7587-50b4-b55f-7d5f62e829e1/attachment.md","path":"references/custom-results-synthesis.md","size":1610,"sha256":"e039a1aaa2e56762311aa5dbe6c8c0f2926310adcabff2faf3c2d1d2de3dfdee","contentType":"text/markdown; charset=utf-8"},{"id":"27469481-bcd2-530e-ae4b-ce3625190555","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/27469481-bcd2-530e-ae4b-ce3625190555/attachment.md","path":"references/custom-single-transformation.md","size":15329,"sha256":"709704c49fbadec8d9da13aba4788f601bf96ce3d641a686bb97b5124d1c3e9e","contentType":"text/markdown; charset=utf-8"},{"id":"8337e156-7e53-5860-95fa-f086af99f562","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8337e156-7e53-5860-95fa-f086af99f562/attachment.md","path":"references/custom-troubleshooting.md","size":9184,"sha256":"e971c7495fb87b013c3a1df3108ad63b533782eaf0309a13a17b272d0e16ca41","contentType":"text/markdown; charset=utf-8"},{"id":"c5a134f2-b4f3-5da2-aa0c-3fb168756024","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c5a134f2-b4f3-5da2-aa0c-3fb168756024/attachment.md","path":"references/custom.md","size":36969,"sha256":"be4101bf0093130170ad6ac6900ed34d7ee9903942d73e3068a95dca52df4bfc","contentType":"text/markdown; charset=utf-8"},{"id":"8c9c3b3d-c7a3-5a72-8add-aad5e8d3b89b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8c9c3b3d-c7a3-5a72-8add-aad5e8d3b89b/attachment.md","path":"references/dotnet.md","size":34929,"sha256":"ca178ed3ba23719d389ba55a27b36beb22660bffe6a6be0aa3ed69319f1683ad","contentType":"text/markdown; charset=utf-8"},{"id":"1110a7c8-5242-530c-a109-eaf162c44286","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1110a7c8-5242-530c-a109-eaf162c44286/attachment.md","path":"references/mainframe.md","size":9956,"sha256":"e9783548cd22a711e864ec9d08667bcddf0fbf43fd2733f81b13f18efdb6b7fb","contentType":"text/markdown; charset=utf-8"},{"id":"45db8267-1496-5e48-b599-5faf880af664","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/45db8267-1496-5e48-b599-5faf880af664/attachment.md","path":"references/sql.md","size":50442,"sha256":"5c9ab696fce7bf69d3d6087877fe38e7e417fae251609854771a7f385941ee81","contentType":"text/markdown; charset=utf-8"},{"id":"d747c1df-c8d7-566d-98fb-b5bb89cdcd52","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d747c1df-c8d7-566d-98fb-b5bb89cdcd52/attachment.md","path":"references/tools.md","size":11058,"sha256":"7b7448de5721d42bafe7e69526b5ea510b58eeca07c58479d946330109319006","contentType":"text/markdown; charset=utf-8"},{"id":"be742253-afe8-5587-a436-d4fac5ff0b32","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/be742253-afe8-5587-a436-d4fac5ff0b32/attachment.md","path":"references/vmware-containerization.md","size":7027,"sha256":"2457c7e35833cfd39e204237f75d8a0633c27ffe6ed2e792309ceaba2fc01e16","contentType":"text/markdown; charset=utf-8"},{"id":"83ba4647-8918-5f06-b4b5-982ffff92c4d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/83ba4647-8918-5f06-b4b5-982ffff92c4d/attachment.md","path":"references/vmware-landing-zone.md","size":8287,"sha256":"dd359d23844b7fb3c7596e4ac4df1cc1bffd5709db39cb0a1a04a120b022d9ab","contentType":"text/markdown; charset=utf-8"},{"id":"5afc4f0d-49a5-511f-a952-b829bccaf5c5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5afc4f0d-49a5-511f-a952-b829bccaf5c5/attachment.md","path":"references/vmware-network.md","size":32250,"sha256":"5f9237b06de7503dab0fd5cce38cd20f01cbde8f2441624bc8653a97cee16d40","contentType":"text/markdown; charset=utf-8"},{"id":"120e03db-36cf-522a-87f7-c41d914b1a4e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/120e03db-36cf-522a-87f7-c41d914b1a4e/attachment.md","path":"references/vmware-server.md","size":9122,"sha256":"f4a9d6ac9ff9dd6105920d02f768e2fd3e455a894e63c102955e645c74c52788","contentType":"text/markdown; charset=utf-8"},{"id":"7b34222b-2be8-5940-b58c-c3478a74c3bd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7b34222b-2be8-5940-b58c-c3478a74c3bd/attachment.md","path":"references/vmware.md","size":14843,"sha256":"1383231c6c766d0b1aa952c523e0b49fa7ae9cc2d837b2dc1f9f238f7640259d","contentType":"text/markdown; charset=utf-8"},{"id":"9eddee30-0d16-5368-9d35-02c4e4ccab41","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9eddee30-0d16-5368-9d35-02c4e4ccab41/attachment.md","path":"references/workflow.md","size":25171,"sha256":"8ee176891a1b9ac634a790de2d4428aa869931fabb87d5a2f379097efafdd8ac","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"112a7f861bb312940ed35598ad85ab0114ffd60eef1f98c61879fdaae3d09273","attachment_count":19,"text_attachments":19,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"plugins/aws-transform/skills/aws-transform/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"devops-infrastructure","category_label":"DevOps"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"devops-infrastructure","import_tag":"clean-skills-v1","description":"Migrate, modernize, and upgrade codebases to AWS. Transforms .NET Framework to .NET 8/10, mainframe COBOL to Java, VMware VMs to EC2, SQL Server to Aurora, and upgrades Java/Python/Node.js versions and AWS SDKs. Use when the user says \"migrate .NET to AWS\", \"upgrade Java to 17/21\", \"modernize COBOL\", \"modernize mainframe\", \"move VMware to EC2\", \"convert SQL Server to Aurora\", \"upgrade Python version\", \"migrate AWS SDK\", or \"transform this codebase\". Don't use for infrastructure provisioning, CI/CD pipelines, or general coding tasks."}},"renderedAt":1782979485402}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.