AmplifierSkills and tools for thoughtful work

Skill

Migrate

Change the language. Preserve the experience.

A whole-application migration skill. Observe how the source behaves, turn it into sequenced stories, and rebuild one complete slice at a time with data, failure and recovery checks.

Use MigrateWatch the 72-second filmWalk through an example
What you getFictional illustration
Fictional story: recover from failed save
Given: edited buffer and unwritable destination
When: save fails
Then: buffer remains; reason is visible; retry is possible
Depends on: editor state and file boundary
Evidence: source observation + target terminal probe
State: inventoried; target implementation pending

Fictional worked example. It illustrates the intended output; it is not a measured result or a real customer story.

Capture the app people use

Inventory commands, screens, hidden state, errors and persistence instead of translating files line by line.

Rebuild in the target’s idioms

Use source-derived acceptance criteria while respecting the target language and host architecture.

See what is actually complete

Keep implemented, independently verified, blocked and cut over as separate states.

The film

Move the behavior, not the lines.

In 72 seconds, Wendell the hermit crab, your app, gets copied line by line into a new shell: tests pass, then a save fails and a page of edits vanishes. Migrate starts from the app people use, every command, error and save, including how it fails. Each behavior becomes a story card with a real terminal check, built in the new language’s own style and checked by a verifier blind to the builder’s tests. Captions are on the player; a transcript is below.

Download the film 15-second cut Captions
Read the transcript

Wendell, a hermit crab, is your app. He’s outgrown his shell.

So you copy him across, line by line.

Tests pass. Then a save fails, and a page of edits vanishes.

Migrate starts with the app people use: every command, error and save, including how it fails.

Each behavior becomes a story card, foundations first.

Each card gets a real terminal check first, then a build in the new language’s own style.

A verifier checks it against the old app, blind to the builder’s tests. A miss reopens the card.

This release proves the bookkeeping, not a finished migration. Data and cutover stay your call.

On screen: Move the behavior, not the lines.

Migrate. Change the language without losing the application.

The app and its failure are a fictional example. This release proves the bookkeeping, not a finished migration. The film shows how the skill behaves; it does not report results.

See the work take shape.

Fictional worked example. It illustrates the intended output; it is not a measured result or a real customer story.

Inventory the source

Keep it read-only and describe observed capabilities as dependency-ordered stories with testable criteria.

Fictional example

Preserve the failure path too

The brief A fictional terminal editor is migrating languages; its save dialog preserves an unsaved buffer after a write failure.

Before

Translate the save function and count a successful unit test as parity.

After applying the method

Observe the source failure state, put buffer preservation and recovery in the story, write the terminal probe first, then implement in target idioms.

The observable contract includes failures, state, and recovery—not the source language’s line structure.

A clear job.
A useful stopping point.

Use when behavior, data, interfaces, and deployment must survive a whole-app migration.

Use it when

  • A whole app must move to a different language or runtime.
  • A rewrite needs source-based acceptance rather than visual resemblance.
  • Data compatibility and failure recovery must survive the move.

Choose another route when

  • A guarantee of parity from a green ledger or unit test alone.
  • An implicit data migration or permission to cut over a production system.

Inventory

The source app must become a rebuildable specification.

Observed surfaces, sequenced story cards, data/interface contracts, and acceptance criteria.

Rebuild

A story’s prerequisites and acceptance are known.

An idiomatic vertical slice with unit and real-surface evidence.

Verify

Builder-created checks need an independent challenge.

Source-derived parity findings, bounded reopen decisions, and retained unresolved cases.

Read the canonical method

Migrate

Change the language without losing the application.

Two phases, one behavioral contract

Migrate the whole application's behavior, not its syntax. The original principles, story format, and runbook preserve the distinct two-phase method and optional native graph interface. Historical model names and “proven” statements are context for that engine, not current requirements or comparative results.

Inventory the source

  • Declare read-only source, target language/runtime, included surfaces, excluded work, data stores, protocols, deployment targets, and rollback needs. Preserve original data and capture a recoverable snapshot before any authorized migration of it.
  • Inspect source code and operate the real app where available. Inventory screens/commands/flows, hidden state, edge cases, errors, persistence, and recovery. Label inferred behavior that could not be observed.
  • Write one story per observable capability with source evidence, Given/When/Then criteria, data/interface compatibility, and concrete checks. A builder who never saw the source should be able to implement from the card.
  • Order stories by real dependencies: storage/model/protocol primitives before their consumers. Record depends-on explicitly. File order is the default sequence, not proof that arbitrary stories can run in parallel.

Rebuild one vertical slice

Observe the selected source behavior; distinguish what to preserve from source-language idioms to discard. Write the target acceptance test and real-surface probe before implementation. Rebuild idiomatically, using existing target seams. Deliver feature, tests, normal CI gate, state/data handling, and recovery together. Terminal apps need a real-terminal check; GUI, API, or service surfaces need their corresponding real observable checks. Unit tests alone do not prove parity.

Use an isolated branch; keep protected branches and publication outside the loop until authorized. Bound attempts (the retained engine uses at most three), then record acknowledged blocker with a reproducible case and smallest handoff. Acknowledged is not implemented or verified.

Independently verify

After the builder's checks, derive verification from the source behavior with only the story identity and intended scope—not builder claims, implementation, or builder-authored expected answers. Record the independence actually achieved. A second role using the same model is not independent human evidence. Failed verification reopens the story within a declared bound; preserve findings. If the criterion was wrong, propose and adjudicate a story amendment with evidence; never silently weaken it to pass.

Finish with evidence

Return inventory coverage, story states, exact unit/real-surface commands and results, data/rollback status, independent findings, blocked stories, and known behavior differences. “Implemented,” “verified,” “acknowledged,” “cut over,” and “accepted by users” are separate states. The repository's ledger/eval self-tests validate mechanics, not a completed migration.

Limits and prerequisites
  • The source remains read-only. Keep data migration and rollback explicit; code parity alone cannot establish data safety.
  • The optional Gene-Migration graph, ledger, Forge tool, and Amplifier are not required to install this method.
  • A ledger fitness curve measures declared completion, not independently established behavioral parity.

Your first useful run.

Bring the read-only source, target language and the surfaces that must survive.

The download contains the complete skill folder. Extract it into the skills directory supported by your agent, keeping its references and license together. Or use the source installer below. Python 3.11+ is required for that installer.

Download the portable skillSource on GitHub

Start from the public source

git clone https://github.com/michaeljabbour/amplifier-skill-migrate.git
cd amplifier-skill-migrate
python3 scripts/capability.py doctor
python3 scripts/capability.py install --dest ~/.agents/skills
Native tools and optional execution
amplifier bundle add ./bundle.md

These commands are for the optional native surface. Follow its installation guide and prerequisites; portable method installation is separate.

Keep the complete skill folder together, including its references and license. The host applies the method in your context; the skill does not start a background service.

  • Requires Git and Python 3.11+ for the repository installer. The portable method itself can be read by a compatible agent without a service or provider account.
  • The destination is a skills-parent folder. Use the discovery path supported by your agent; ~/.agents/skills is an example, not a universal host setting.
  • Keep the complete installed folder, references and license together. Identical reinstall is safe; conflicts are refused. A deliberate --replace keeps a dated backup.

Try this with your agent

Use Migrate to inventory this fictional terminal editor for a Rust rebuild. Keep the Python source read-only. Start with open, edit, save and failed-save recovery; write dependency-ordered story cards and acceptance probes before implementation.

Use after installing in a host that loads skill folders. Supply your own task files and review the result.

Keep the guide nearby

Read the guide · License · Changes · Release metadata · Install guide · Migration · Validation · Native guide · consolidation

Know what you can rely on.

Retained graph syntax, ledger ratchet and sequence fixtures pass, and the portable install is checked. They validate orchestration mechanics; this release does not claim a newly completed app migration or production cutover.

Read the checks and their scope
  • Ledger ratchet and sequence detector — passed

    Builder/verifier state regressions rejected and synthetic fixture curve read. These are fixture mechanics, not an app migration or behavioral parity measurement.

  • Executable graph syntax — passed

    All three retained graphs parse. No graph/orchestration changes or paid pipeline execution.

  • Portable packaging and install — passed

    All operations passed. No runtime activation or effectiveness measured.

  • Skill discovery metadata — passed

    Skill is valid. This is a structural check, not a behavioral benchmark.

Retained graph syntax, ledger ratchet and sequence fixtures pass, and the portable install is checked. They validate orchestration mechanics; this release does not claim a newly completed app migration or production cutover.

Fictional examples explain the capability. Tests check the stated behavior. Outside-user outcomes need their own evidence.