<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Alexander Larin on Medium]]></title>
        <description><![CDATA[Stories by Alexander Larin on Medium]]></description>
        <link>https://medium.com/@neurotracer1?source=rss-57207c2d3d0b------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*s46QN64UwKycm460.jpg</url>
            <title>Stories by Alexander Larin on Medium</title>
            <link>https://medium.com/@neurotracer1?source=rss-57207c2d3d0b------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 12:02:13 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@neurotracer1/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The Plan for the Plan: Teaching AI to Run a Whole-Codebase Migration]]></title>
            <link>https://medium.com/@neurotracer1/the-plan-for-the-plan-teaching-ai-to-run-a-whole-codebase-migration-56817b176f56?source=rss-57207c2d3d0b------2</link>
            <guid isPermaLink="false">https://medium.com/p/56817b176f56</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[migration]]></category>
            <dc:creator><![CDATA[Alexander Larin]]></dc:creator>
            <pubDate>Mon, 20 Jul 2026 08:08:31 GMT</pubDate>
            <atom:updated>2026-07-20T08:08:31.670Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How a one-page prompt grew into a Copilot-native agentic system designed to port a React + Swift + Kotlin stack into a single React Native codebase — phase by phase, gate by gate.</em></p><h4>Three codebases, one product</h4><p>Picture a mature e-commerce product that has been shipping for years on three parallel stacks: a React web app, a native iOS app written in Swift (SwiftUI and UIKit), and a native Android app written in Kotlin. Three implementations of every feature. Three backlogs. Three sets of bugs that are almost — but never exactly — the same.</p><p>The strategic decision was already made when I entered the picture: unify on React Native. Not a big-bang rewrite, but a brownfield migration — React Native modules compiled into binaries and linked into the existing native apps as ordinary dependencies, screen by screen, while React Native for Web gradually replaces the website. A shared library of UI primitives (buttons, inputs, dropdowns) had already been ported, so the foundation existed.</p><p>The interesting decision came next: the migration itself would be executed by AI agents. Not “AI as autocomplete” — the whole loop. Analyze the legacy code, derive the behavioral spec, port the code, validate the result, produce the evidence. My job was to build the system that could do that.</p><p>This article is the story of building that system — from the first prompt to an installable agentic overlay for GitHub Copilot — and what I learned along the way about making AI plans that actually hold together. It’s not a story about running the migration (that’s a different article); it’s about how you get a plan that is, at least on paper, complete enough to migrate a codebase of any size on its own.</p><h4>Step zero: don’t write the plan — grow it</h4><p>Planning a migration across three mature codebases is too big to one-shot. If you ask a model to “write a migration plan,” you get something that reads beautifully and falls apart the moment two phases have to hand work to each other.</p><p>So instead of writing <em>the plan</em>, I wrote a <strong>plan for the plan</strong> — and grew the real thing in three deliberate stages:</p><ol><li><strong>The outline</strong> (the “plan for the plan”): a structured document describing every phase the future plan must have, what each phase consumes and produces, and the non-negotiable rules. Cheap to iterate — it went through seven revisions.</li><li><strong>The generated plan</strong>: the outline, run through a generation step, expanded into an operational plan — dozens of markdown files: prompts, agent definitions, templates, format specs.</li><li><strong>The Copilot conversion</strong>: the operational plan repackaged into GitHub Copilot’s native customization layers, so a developer drives it with slash commands instead of hand-running markdown prompts.</li></ol><p>Between stages two and three sits the step I’m most glad I didn’t skip: an <strong>adversarial audit</strong>, where the model was asked to tear its own plan apart. More on that later — it found real holes.</p><figure><img alt="The three-stage pipeline: a one-page brief grows into an outline, the outline generates an operational plan, an adversarial audit hardens it, and the result is converted into a Copilot-native overlay." src="https://cdn-images-1.medium.com/max/1024/1*CJW63XMgbLVa4fhyPq_XuQ.png" /></figure><p>The economics of this pipeline matter. The outline is one document — you can afford to rewrite it seven times. The generated plan is forty-plus files — you never want to hand-edit those in bulk. Keeping a single upstream source of truth and regenerating downstream is the same discipline we apply to code generation, applied to planning.</p><h4>The first prompt</h4><p>The whole thing started with roughly one page of text. It contained the context (three codebases, brownfield approach, gradual migration), a rough sequence of eight steps I suspected we’d need — and two non-negotiable requirements that ended up shaping everything downstream:</p><p><strong>First: traceability.</strong> Every migrated symbol must carry a machine-parseable breadcrumb pointing at the exact source it was ported from:</p><pre>// @src: web/src/features/wishlist/WishlistGrid.tsx:41–118<br>// @src: ios/Modules/Wishlist/WishlistViewModel.swift:12–87<br>export function WishlistGrid(props: WishlistGridProps) {<br> // …<br>}</pre><p><strong>Second: semantic validation.</strong> “It compiles and the tests are green” was explicitly rejected as a completion criterion. The migrated code has to be <em>judged</em> — does it still do what the original did?</p><p>Everything else in the prompt was negotiable, and I told the model so. What came back was the first structured outline — discovery, strategy, migration, validation, closeout — each phase with entry criteria, exit criteria, and named artifacts.</p><h4>The phases</h4><p>The shape survived all seven revisions, so it’s worth walking through. The setup phases run once for the whole program; the rest form the migration loop itself.</p><figure><img alt="Phase flow: Discovery, Strategy, and Tooling run once as setup; Migrate, Validate, and Finalize form the migration loop, with validation feeding issues back to migration." src="https://cdn-images-1.medium.com/max/1024/1*6-0xnh5n0VUa7oWKevPNeA.png" /></figure><p><strong>Discovery.</strong> Analyze all three codebases: architecture maps, feature inventories with per-platform divergence flags, tech-stack audits — and, crucially, the <em>seams</em>: which host-app capabilities (auth, analytics, push, consent) the React Native modules must bridge versus replace, and how sessions, deeplinks, and API contracts survive the handoff. Brownfield migrations rarely die in the React code; they die at the seams. Discovery also harvests the program-level business requirements <em>from the code itself</em>, because in a years-old product, code is the only place the full truth lives.</p><p><strong>Strategy.</strong> The model proposes <em>three genuinely different migration strategies</em>— not three flavors of one idea — then compares them pairwise against a fixed rubric, and a human picks the winner. Open questions that surfaced along the way (target versions, styling system, navigation library, bridge-vs-replace calls) become numbered decision documents that a human signs. Forcing alternatives is cheap insurance against the model marrying its first idea — and against <em>you</em> marrying it too.</p><p><strong>Tooling</strong> (added later — that’s a story in itself). Build the `<a href="http://twitter.com/src">@src</a>` lint rule, the traceability indexer, the coverage reporters. The things every later phase silently depends on.</p><p><strong>Migrate.</strong> Resolve exactly which source files are in scope, harvest a behavioral specification, port the code with breadcrumbs and tests, wire it into both native hosts, publish the web target.</p><p><strong>Validate.</strong> A QA agent walks the running app against the spec, a judge reviews semantic equivalence symbol by symbol, a compliance check verifies analytics parity and conformance to the team’s engineering decisions.</p><p><strong>Finalize.</strong> Produce the closeout report and the evidence bundle, extract reusable templates, update the single-pane status rollup. The first pass through the loop <em>teaches the system</em>: its templates become the starting point for everything that follows.</p><h4>The ideas that carry the plan</h4><p>A phase list is just a table of contents. What makes the plan trustworthy are a handful of load-bearing ideas that repeat across every phase. Each one exists to answer an uncomfortable question.</p><p><strong>Traceability — how do you know you migrated <em>everything</em>?</strong> The scariest failure mode of a big migration isn’t a bug; it’s silent loss — a validation rule, an edge case, an analytics event that quietly doesn’t make the trip, and nobody notices for months. The plan’s answer is to make the link between old code and new code physical. Every migrated symbol carries an `<a href="http://twitter.com/src">@src</a>` breadcrumb naming the exact source lines it replaces; a lint rule fails the build if one is missing; and an indexer walks all the breadcrumbs to check coverage from both ends. Every piece of source code must end up in one of exactly two buckets: <em>referenced by migrated code</em>, or <em>explicitly dropped</em> with a justification a human accepted. Nothing is allowed to just disappear. “I’m pretty sure we ported everything” becomes a number on a dashboard: covered, dropped-with-reason, unaccounted-for — and the migration isn’t done until the last bucket is empty.</p><p><strong>The spec is the arbiter — when platforms disagree, which one is “right”?</strong> This one changed my mental model the most. Early drafts treated the web codebase as the source of truth — until the obvious question landed: what if iOS does it differently, and the iOS behavior is the one users love? With three implementations that were never at feature parity, “faithful to the source” is ambiguous. The fix: before any code is written, an agent distills a <strong>consolidated behavioral specification</strong> from every platform where the behavior exists. Every requirement in it must trace back to real code — edge cases are harvested, never invented. Where platforms disagree, the agent doesn’t pick a winner; it files a structured <strong>conflict</strong>, and a human signs a decision. Code migration is blocked until every conflict is resolved. From that point on, “correct” means <em>satisfies the spec</em> — not <em>matches some codebase</em>.</p><p><strong>Judged equivalence — do green tests prove the port is right?</strong> No. Tests can only vouch for the paths somebody thought to test, and in a years-old codebase the original tests never covered everything the code actually does. So for every migrated symbol, a judge agent reads the original code (reachable via the breadcrumbs), the migrated code, the relevant slice of the spec, and the team’s engineering decisions — compares inputs, outputs, side effects, error paths — and issues a structured verdict:</p><pre>judgment: equivalent<br> | equivalent-with-justified-deviation<br> | not-equivalent</pre><p>A symbol that faithfully reproduces the source but contradicts the spec — or violates one of the team’s engineering decisions — is <em>not equivalent</em>, no matter how exact the port. Tests still run, of course, and they support the verdict. They just don’t get to <em>be</em> the verdict.</p><p><strong>Bounded loops — when is an agent allowed to say “done”?</strong> Validation is a loop: a QA walker agent exercises the migrated app against the spec and files structured issues; a fixer agent resolves them; repeat. Every loop carries an explicit iteration budget, and exhausting it doesn’t mean “ship it anyway” — it means an abort report and a human. “Done” is defined mechanically, not emotionally: full traceability coverage, passing equivalence verdicts, an empty issue list. Proof, not vibes.</p><p><strong>Everything is an artifact — what did the agents actually do all day?</strong> Every step consumes named markdown files and produces named markdown files. Decisions, specs, conflicts, verdicts, QA iterations, deferrals — all of it lands in a predictable tree, rolled up into one always-current status page. If it isn’t written down in the tree, it didn’t happen. And this is more than bookkeeping: the artifact tree is what made the whole plan auditable — as the next sections show, auditable even by the model itself.</p><h4>Seven revisions, seven lessons</h4><p>The outline went through seven numbered revisions before it was allowed to generate anything. Each revision, in hindsight, fixed a whole class of future failures — this is where the “make the phases actually fit together” work happened.</p><p><strong>”Source of truth” became “spec is the arbiter.”</strong> The original framing — port from web — collapsed the first time I asked: what happens when iOS does it differently <em>and the iOS behavior is the one users love</em>? The spec-and-conflict machinery replaced it.</p><p><strong>Engineering decisions became a co-arbiter.</strong> An early gap: an agent can faithfully port a legacy pattern you are deliberately migrating <em>away</em> from. The fix: the team’s tech decisions (state management, data fetching, analytics, styling) live in the target repo’s docs, are read-only to the migration, and the equivalence judge treats violating them as non-equivalence. Faithful-but-wrong is still wrong.</p><p><strong>Validation got an honest scope.</strong> Later revisions pinned validation to what an agent can actually verify on a developer’s machine — dev server, iOS simulator, Android emulator — and split it into <em>pre-PR gates</em> (behavioral parity, analytics parity, decision compliance, no crashes) versus everything else.</p><p><strong>The gates were narrowed deliberately.</strong> Accessibility, performance budgets, memory ceilings, formal stability SLOs — all <em>deferred</em> to post-PR human QA, recorded in an explicit deferrals ledger. Not because they don’t matter, but because the legacy baselines weren’t trusted enough to gate on. A gate you can’t measure honestly is a gate agents will find a way to wave through. Deferring loudly beats gating dishonestly.</p><p><strong>Scope became mechanical.</strong> Early drafts described what to migrate in fuzzy product terms — “the wishlist feature.” The final revision made scope concrete: a folder in the source tree, transitively pulling in the pieces it composes, stopping at explicit boundaries (code already migrated, shared primitives). Resolving what’s in scope became a file-system walk instead of a judgment call — which is exactly the kind of question you want answered mechanically before agents start porting.</p><p>The meta-lesson: version your outline like code. Diffing revision N against N−1 tells you exactly which class of failure you just eliminated, and the numbered documents become the design history nobody has to reconstruct later.</p><h4>Generating the operational plan</h4><p>With the outline stable, a generation runbook expanded it into the operational plan: a <strong>constitution</strong> of non-negotiable contracts, <strong>24 step prompts</strong> (one per phase step), <strong>9 specialized agent definitions</strong> (discovery analyzer, specification harvester, migration executor, QA walker, dev fixer, equivalence judge…), <strong>10 artifact templates</strong>, <strong>4 tooling format specs</strong>, and a stack of numbered decision documents.</p><p>The design rule for every prompt: it must be self-contained and explicit about its I/O. Here’s the shape (abridged from the real spec-harvesting prompt):</p><pre>## Inputs<br>- Pinned source revisions ... executions/pinned-revisions.md<br>- Resolved source surface ... executions/source-surface.md<br>- Business requirements ..... discovery/business-requirements.md<br>- Spec template ............. templates/specification.md<br>## Outputs<br>- executions/specification.md<br>- executions/specification-conflicts.md<br>## Exit criteria<br>- Every requirement traces to source code via @src references<br>- Every cross-platform divergence is a CONFLICT entry, unresolved</pre><p>No prompt assumes conversation context. Files in, files out, exit criteria. The artifacts are the API between phases — which is precisely what made the next step possible.</p><h4>The audit: asking the model to break its own plan</h4><p>Before converting anything to Copilot format, I ran the step that taught me the most: I asked the model to <strong>audit the plan it had just generated</strong> — adversarially, as if reviewing a stranger’s work — and to walk a small pilot migration through the phases on paper.</p><p>The verdict was humbling and precise: <em>strong on description, weak on connective tissue</em>. Every phase read beautifully in isolation. But the audit found <strong>seven seam gaps</strong> — places where a downstream step consumed an artifact that no upstream step produced, or where a rule existed only as prose:</p><ul><li>The migrate phase required a “source surface definition” — the exact list of source files to port — as input. <strong>Nothing produced it.</strong> Every run would have started with an ad-hoc scoping conversation.</li><li>The traceability tooling — the lint rule and indexer everything depends on — <strong>had no owner</strong>. Every phase assumed it existed; no step built it. (That’s how the tooling phase was born.)</li><li>The human conflict gate was described but not enforced — and in the paper pilot, the agent <strong>auto-resolved both conflicts and sailed straight through</strong> the gate meant to stop it.</li><li>Nothing verified the migrate phase actually produced its required artifacts before validation started; code could reach “validated” with no migration log and no judgments, and the absence would surface only at closeout.</li></ul><p>Each gap became a concrete fix: new producer steps for orphaned inputs, an owner for the tooling, and — most importantly — soft gates converted into <strong>machine-checkable preconditions</strong>. “Do not proceed until every conflict has a signed decision document” stopped being a sentence and became a check on files in a folder.</p><p>If you take one thing from this article, take this: <strong>an agentic plan is only as strong as its artifact graph.</strong> Phases don’t hand off intentions; they hand off files. Audit the graph — every input needs a producer, every gate needs a mechanical check — or your agents will do what my pilot did: walk politely through the gaps.</p><h4>Making it native: the Copilot conversion</h4><p>At this point the plan worked, but driving it meant hand-running 24 markdown prompts in the right order with the right arguments. The final stage converted it into GitHub Copilot’s customization layers, so the process lives in the IDE. The mapping turned out to be delightfully clean, because Copilot’s layers compose:</p><ul><li>The constitution’s hard rules became <strong>always-on instructions</strong> — injected into every request, impossible to forget.</li><li>The nine role “agents” collapsed into <strong>three custom agent modes</strong> — <em>planner</em> (read-mostly analysis and specs), <em>executor</em> (writes code), <em>reviewer</em> (validates, adversarial by charter) — each with its own tool allowlist, model preferences, and handoff buttons to the next mode.</li><li>The phase entry points became <strong>six slash commands</strong>: `/discover`, `/plan-strategy`, `/build-tooling`, `/migrate`, `/validate`, `/finalize`.</li><li>The 24 step prompts became <strong>25 skills</strong> — self-contained runbooks the commands orchestrate. The heavy ones run as <em>forked subagents</em>: isolated context per step, live progress in the UI.</li><li>Device access (browser, iOS simulator, Android emulator, design files) went to <strong>MCP servers</strong>; and <strong>hooks</strong> enforce what prose can’t — a write-fence that blocks edits to the process and docs folders, and a lint pass on every edited file.</li></ul><figure><img alt="The layer stack: always-on instructions on top of three agent modes, six commands, twenty-five skills, with MCP device drivers and deterministic hooks underneath." src="https://cdn-images-1.medium.com/max/1016/1*Tyhhy_AmJ9AaRnsw0sXSfw.png" /></figure><p>The one-sentence mental model: <strong>a command, running under a mode, orchestrates skills as forked subagents, while instructions and hooks enforce the rules.</strong></p><p>Here’s what it looks like when a developer kicks off a migration:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*p7hapdTVs_9HypBwVeT9HQ.png" /></figure><p>The command validates its input first (if you forget to say what to migrate, it asks — guessing is banned), runs a short intake wizard, then builds a visible TODO list and works through it, forking one subagent per skill. The spec-harvesting step still ends at the same human gate the audit hardened: no signed decisions, no code. After the code steps, a self-check loop iterates on lint, types, and tests until everything is clean — the phase polices its own output before it’s allowed to hand off. Then a button appears: <em>Validate</em>, pre-filled, switching to the reviewer mode.</p><p>And a small but satisfying detail — a skill is just a folder with a markdown file:</p><pre>---<br>name: harvest-behavioral-spec<br>description: Harvest a consolidated behavioral spec<br> from every platform where the behavior exists;<br> flag cross-platform conflicts for human decision.<br>context: fork # runs as an isolated subagent<br>user-invocable: true # can also be run standalone<br>---</pre><p>The whole system — process, agents, gates, guardrails — is versioned markdown and JSON in a `.github/` folder. It merges into the target repo like any other overlay, and a new team member gets the entire migration methodology with `git pull`.</p><h4>What we ended up with</h4><p>Step back, and the assembled machine looks like this: legacy code enters on one side, and a fully specified pipeline carries the migration from scoping to closeout, pausing only where a human signature is genuinely required.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1020/1*5X0ZpecZPlCVNzeBQH3Bzw.png" /></figure><p>In theory — and I want to be careful to say <em>in theory</em>, because this article is about the plan, not the war stories — this is a fully automatic migration system for a codebase of any size. Nothing in it is specific to one screen, one feature, or one team: you can point it at a single widget or, in principle, at the entire application, and the process is exactly the same. Each pass extracts the templates that make the next one cheaper; the status rollup always shows how much of the source universe is covered, dropped, or in flight. Humans appear at exactly six points — strategy selection, program decisions, spec conflicts, design overrides, PR review, closeout sign-off — and every one of them is a <em>decision</em>, not a chore.</p><h4>Wait — isn’t this just BMAD?</h4><p>If you’ve followed the agentic-development scene, this may sound familiar. BMAD and similar frameworks (agentic planning + context-engineered development) are built on the same convictions: specialized agent roles, self-contained context units per work item, human approval gates, everything as markdown.</p><p>We arrived at the same shape independently, which I take as convergent evidence rather than reinvention. The mapping is almost embarrassing: planner/executor/reviewer ≈ analyst/dev/QA personas; the intake-plus-spec bundle ≈ the sharded story file; the equivalence and compliance checks ≈ QA gates; the constitution ≈ always-loaded core config.</p><p>The difference is specialization. Generic frameworks have no notion of the things this plan treats as crown jewels: line-level source traceability enforced by lint, symbol-by-symbol equivalence verdicts, a requirement-origin taxonomy (ported vs. net-new vs. design-override), coverage judged relative to the platforms where the behavior actually exists. A migration is not a greenfield project with extra steps — it’s <em>porting with proof</em>, and the proof machinery is most of the value.</p><p>My honest recommendation mirrors what I’d do again: <strong>borrow, don’t adopt. </strong>Steal BMAD’s story-sharding discipline for your context handoffs; keep your domain-specific guarantees hand-built. And whichever framework you start from, run the seam audit — it’s framework-agnostic, and it’s where the real defects live.</p><h4>Takeaways</h4><ul><li><strong>Plan the plan.</strong> Iterate on a cheap outline; generate the expensive operational plan from it. Never hand-edit forty files when you can regenerate them from one.</li><li><strong>Artifacts are the API between phases.</strong> Every input needs a producer, every output a consumer. Audit the graph like you’d audit function signatures.</li><li><strong>Gates must be machine-checkable.</strong> A rule that lives only in prose is a rule your agents will eventually walk through. Files in folders beat sentences in prompts.</li><li><strong>Make the spec the arbiter.</strong> With multiple divergent sources, “faithful to the source” is undefined. Harvest a spec, force humans to resolve conflicts, judge against the spec.</li><li><strong>Judge equivalence; don’t infer it from green tests.</strong> Tests can’t vouch for paths they never covered.</li><li><strong>Let the model audit its own plan — adversarially.</strong> It found seven real defects in its own work, including a human gate it had already walked through. Cheapest review I ever commissioned.</li><li><strong>Defer loudly what you can’t gate honestly.</strong> An explicit deferrals ledger beats a gate nobody trusts.</li></ul><p>The migration plan now sits in the repo as a set of markdown files that any Copilot-equipped developer can drive with six slash commands. Whether the machine performs as designed at scale — that’s the subject for another article.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=56817b176f56" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>