Context: migrating a 300+ screen app with LLM assistance
Shopify is moving its mobile apps from React Native back to native Swift and Kotlin. The Shop app migration took 12 weeks; the Shopify App, with more than 300 screens, is the next and largest target. LLMs are doing much of the rebuild, but raw model output is not consistently maintainable, so Shopify built Helix: a set of tools and skills that migrate features and screens from the React Native app while following a documented, opinionated architecture for the native apps.
Rather than gather everything into specs and task files and implement it in one pass, Helix assumes the first output will be wrong. Its design goal is reliable convergence: an attempt may be incorrect, but it cannot ship until it is correct.
The migration loop
- The engineer points Helix at a target: a whole screen or a single subscreen.
- Helix reads the React Native code and proposes an ordered sequence of checkpoints, which the engineer approves in minutes.
- Helix builds one checkpoint at a time. Before a checkpoint is committed and the next begins, it must prove behavior with tests, match the reference app in a visual review, pass two adversarial code reviews, and receive engineer approval.
- Feedback from each review is retained, so the process grows more autonomous over the course of a migration.
Checkpoints: small slices the engineer can actually review
Each migration starts from the existing React Native code and the running app. Helix splits the selected target into checkpoints of increasing complexity: typically a screen skeleton first, then one deliberately small section, with later checkpoints growing only after early decisions pass review.
Checkpoints are described in a few words on purpose. At this stage the engineer only needs to judge whether the sequence makes sense; a long generated document would be skimmed rather than reviewed. Small checkpoints also keep the working context small, so the agent reads the relevant part of the reference directly instead of leaning on a large spec file or task list. The reference code is the spec.
A subagent reads the reference and generates test cases for each checkpoint. These operate as integration tests, describing the feature from the user's perspective, and push the agent to look beyond the happy path for edge cases.
Four gates that block progress
A checkpoint advances only after passing four gates, in order. On failure, the agent fixes the implementation using the gate's feedback and reruns the check. It can retry indefinitely, but it cannot override a failed check on its own judgment.
1. Behavior
The CLI exposes the same screen state and actions as the app (for example, the analytics information and navigation actions of the home screen). The agent studies the reference, replicates it, and validates through CLI behavior tests; every relevant generated test case must pass. Because the CLI requires no simulator, the agent can iterate on behavior dozens of times before a single screenshot is taken.
2. UI review
Visual equivalence resists specification: people notice a too-small title or a slightly off icon immediately, yet those details rarely make it into a prompt, and pixel diffing fails because two UI frameworks do not produce byte-identical output. While teaching agents to drive simulators, the team found that current Gemini models have strong spatial awareness for this problem and can spot margin, padding and size discrepancies.
The orchestrator (GPT) captures implementation and reference screenshots in matching states and has Gemini review them as a perfectionist designer, checking structure, spacing and alignment and judging sizes proportionally against each screenshot's dimensions. Gemini must list every difference with a severity and an on-screen location; any difference fixable in code is treated as a blocker by default. It can also mark a comparison INVALID when the states do not match, such as an unfulfilled order versus a fulfilled one, in which case the orchestrator recaptures both apps and reruns the comparison.
Comparison scope follows the checkpoints completed so far. A skeleton checkpoint may only require checking the navigation bar and title. The first rendering need not be perfect; the gate only requires that defects can be seen, described, located and sent back for another attempt.
3. Adversarial code review
Working and near pixel-perfect code can still be poor underneath, so two independent, context-isolated reviewer agents check it against the documented architecture, including separate UI guidelines. Every finding must be fixed, affected tests rerun, and the UI review gate rerun if anything visibly changed. Reviewers then re-examine the changed code, repeating until both approve.
4. Engineer approval
The engineer inspects the code and the running app and judges whether the result meets expectations. Feedback goes two places: back to the agent, which addresses it and reruns the gates, and into Helix's memory, where it improves subsequent checkpoints.
This memory lets autonomy grow as a migration proceeds. Early checkpoints get more engineer attention while uncertainty is high; as approved code and feedback accumulate, later checkpoints run with less oversight, and some can skip approval when autonomous mode is enabled. Every checkpoint ends in a commit, and most engineers create branches and raise PRs from there.
The distinction from one-shot tools matters. A one-shot generated diff concentrates all review work at the end, across behavior, visual fidelity, two platforms and architecture. Helix moves feedback to the earliest useful point: the agent repeats implementation and responds to reviewers, while the engineer concentrates on scope, product judgment and taste, steering small validated changes that become the base for the next one.
Autonomous and parallel operation
Engineer approval is mandatory by default but can be relaxed: Helix can complete the next three checkpoints in one pass or skip approvals entirely and run for hours or overnight. Gates do not weaken when unobserved; every checkpoint still proves behavior, passes UI review and satisfies both adversarial reviewers before the next starts. Multiple screens can also migrate in parallel, each converging through its own gates.
An autonomous run produces a series of committed checkpoints with supporting evidence — archived UI reviews, passing tests and reviewer verdicts — rather than one large diff.
Reuse beyond migration
The loop is not migration-specific. New features can use designs and product docs as the reference and follow the same process; architecture migrations and refactors reuse the checkpoint-and-gate strategy, and a logic-only change simply skips the UI review gate. The design lesson is the shift from optimizing a perfect first attempt to reliable convergence: an attempt is allowed to be wrong, but it is not allowed to ship until it isn't.



