🚀 Migrating your Fire OS App to Vega with ADBT

[Siddhesh_Pandit]

Migrating your existing Fire OS App to Vega OS with ADBT

This walkthrough shows how to use Amazon Devices Builder Tools (ADBT) to take an existing Fire OS app and migrate it to Vega OS.

Before you begin, please note that this workflow will require your Fire OS app’s source code as a reference, do ensure you have access to it.

What is ADBT?

ADBT is a suite of AI-powered development tools for Fire TV that contains ADBT Model Context Protocol (MCP) Server and Agent skills. These capabilities make your coding agents such as Claude Code, Cursor, and Kiro aware of specialized Fire TV knowledge and best practices, eliminating guesswork from development and debugging tasks.

Overview: How ADBT migrates an app

The ADBT workflow runs six phases as listed below, always in order, and won’t jump ahead until each one is done.

1. Validate: ADBT looks at the app’s source code, confirms it’s a real, supported app, and figures out its identity ( Type of App : RN/Native/Webapp, name, package).
2. Plan: ADBT reads through the entire original app every screen, image, layout, and feature and writes it all down as a migration guide (migration_guide.md). Think of it as the blueprint: a written map of what the app has and how each piece becomes its Vega equivalent.
3. Execute: ADBT now writes the actual Vega app, screen by screen, strictly from the migration guide. Everything like icons, screens, text, data should come from the partner’s real app. Nothing should be invented.
4. Build & Verify: ADBT builds the app and you install/run it on a device to see it live.
5. Guided AI Review: In this phase, your agent goes through NextSteps.md a file that lists things ADBT couldn’t finish automatically. Think of this as TO-DOs your agentic AI can refer to and help complete remaining items.
6. Performance Comparison (optional step): ADBT compares the migrated app’s performance against FOS app.

Note: ADBT transcribes your existing app into Vega. It does not design a new app. Everything in the migrated app should come from your original app. If something looks invented, that’s a bug to catch.

Part 1: Prerequisites

From the official Vega docs, ADBT needs only:

Node.js 18 or later
Vega SDK v0.22 or later

Onboarding and getting ADBT running

In a terminal window, where you would like to initialize this project, copy-paste the following prompts to begin with

npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context

npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status

Part 2: Running a migration (step by step)

Step 1 : Start a session with your AI agent in the same directory where you set up ADBT

We recommended using Claude Opus 4.8 model for this guided flow.
In the same folder where you ran init-context in the last step, open your AI agent and start a fresh chat session (Kiro, Cursor, Claude Code etc.) This is critical because that’s where ADBT’s steering or context lives and the your agent gets the context from the same folder. Starting the session anywhere else means the agent won’t have ADBT’s guidance loaded. Ensure the that your agent has ADBT context before beginning next step, if you run into any issues, check the troubleshooting table below.

Step 2 : Confirm ADBT (the MCP server) is connected

Before starting, make sure the agent can actually see the ADBT tools:

• In Claude Code, run the /mcp command — it lists connected MCP servers and their status. You should see the Amazon Devices Builder Tools server connected.

• In other agents, or as a universal check, just ask the agent in the chat:

  “List the tools provided by Amazon Devices Builder Tools and Agent Skills”

  • It should return tools like list_documents, read_document, search_documentation. If it does, ADBT is running.
  • If nothing shows up, ADBT isn’t connected — go back to Part 2 (or run the terminal check:
    npx -y @Amazon Quick Internal - Devices/amazon-devices-buildertools-mcp@latest check-status).

Step 3: Kick off the migration with this prompt

Use the amazon-devices-vega-app-migration skill to migrate the Fire OS app at <path to the FOS app source> to Vega.

Complete each phase fully, in order and confirm before moving on:

  - After Phase 2 (Plan): Confirm the migration guide covers every screen and feature of the original app. If anything is missing, add it now before starting Phase 3.

  - After Phase 3 (Execute): Confirm every screen from the guide is built with real content -no stubs or placeholders, before finishing.

Part 3: Tips for a Better Migration

You can rerun the whole migration as many times as you want.
Although, do ensure if you are running the migration again, do it deliberately and not by default.
A full rerun regenerates the entire app (Plan + Execute over every screen) and it costs tokens.

Rerun from scratch only when the foundation is wrong:
Cases like,
▎ Phase 2 (Plan) came out broadly incomplete ie FOS source code was not entirely translated into the guide as plain English
▎ Phase 3 (Execute) produced mostly stubs/placeholders.

For smaller issues like a few broken screens, a missing asset, a feature not wired, visual bugs , don’t rerun. Use the Guided AI Review (Phase 5) or reprompt the agent to fix just that screen. It’s far cheaper and keeps the good output you already have.

When you do a rerun, point the output to a fresh sub-folder (vega-app-run2/, vega-app-run3/) so each attempt stays clean and comparable. Keep the session in the folder where ADBT was set up so the steering doc still loads.

Ensure Phase 2 (Plan) and Phase 3 (Execute) each finish completely and in order.
Use the pause after Phase 2 (Plan) to review the blueprint. In practice, the agent usually stops after plan phase to let you review the files it created before it starts building. When it stops, don’t just say “continue”, use a few follow-up prompts to make sure nothing in the plan was missed.

Note that the migration guide is the blueprint: whatever’s missing here will be missing in the app, so this is the easiest place to catch obvious gaps.

The simplest way to enforce is to ask the agent to confirm each phase is complete before moving on. After the plan is written, prompt:

“Confirm that Phase 2 (Plan) is fully complete. The migration guide must cover every screen and feature of the original app before you start Phase 3. If anything is missing, add it now.”

After the app is generated, prompt:

“Confirm that Phase 3 (Execute) is fully complete. every screen from the guide is built with real content, no stubs or placeholders before finishing.”

When something looks off, take a screenshot instead of describing the screen in words. Rather than spelling out where a button sits, what color something is or how a row its laid out, ask the agent to take a screenshot. Agent will captures the Vega screen so it can see exactly the part you’re referring to. You can still tell it what’s wrong. The screenshot just makes sure you’re both looking at the same thing, so the agent understands you without a long written description.

Example prompts:

Take a screenshot : The movie posters in the second row are overlapping the row title.
Take a screenshot : The hero image at the top isn’t loading, it’s just a blank box.
Take a screenshot : This button is squished into the top-left corner, it should be centered.
Take a screenshot: I just changed the header ; the logo is still off-center.

Part 4: Help us with feedback

Note: This feedback goes to the Amazon team that builds ADBT and is used only to improve the tool.

After each migration, we request you to kindly fill in ADBT_Migration_Feedback_Checklist.md (2.2 KB). As this feedback helps us improve the tool.

The feedback only captures the following details:

• FOS app details
• The AI model and tool used
• Whether it launched
• The screen completeness
• The visual & data fidelity
• What broke
• The manual effort put in
• Overall verdict

Once you are done generating the feedback, we also request you to attach your FOS app’s (original app’s) screenshots, Vega (generated app’s) screenshots and the migration guide (migration_guide.md) that was generated through the process, please open a forum post in the Feature Request or Bug Report section and attach the feedback there.

Part 5: Troubleshooting

Symptom	Fix
Copilot starts the wrong migration type (e.g., begins a WebView migration for a Native app)	Stop it and prompt it to follow the correct app type. Example: if it started WebView but the app is native → “Stop. This is a native app — follow the FOS Native → VegaScript migration path.”
MCP troubleshooting:
check-status → Context Not found	You’re probably not in the folder where you ran init-context. cd into it (or re-run init-context there)- the steering doc is read from the current directory only
check-status → Context Corrupted	Rerun init-context and overwrite: “init-context —force”.
check-status is all but the agent still can’t see ADBT tools	The server isn’t started in your agent session. Restart the IDE/agent and re-check “/mcp”
ADBT detected/started the wrong app type (e.g. a WebView migration for a Native app)	Stop immediately and prompt it in right direction. Please report this as feedback to ADBT

Glossary

Term	Meaning
ADBT	Amazon Devices Builder Tools (ADBT) : is an AI-assisted tool that follows an in built migration flow and does the heavy lifting of reading your existing app source code to generate the Vega version step by step.
Migration guide (migration_guide.md)	The written plan ADBT produces in the Plan phase, before any code. It maps every screen, image, and feature of the original app to its Vega equivalent. ADBT builds the app from this file. So if something’s missing here, it’ll be missing in the app. Worth a quick review before Execute.
NextSteps.md	A TO-DO list ADBT writes for anything it couldn’t fully migrate automatically e.g. a missing asset, an unreachable API, or a feature needing manual work.

Resources

Setup Amazon Devices Builder Tools for AI-Powered Development
Accelerate FireTV App Development using your preferred AI agent