Migrate & Conquer

Need to migrate an old codebase to something new?
Move a feature set to a new home?
Relaunch a website?

Coding agents can help here a lot, even more with a little guidance Migrate & Conquer provides.

Quick start

You need:

• The "New" repo
• The "Old" code as reference, e.g. in a gitignored folder
• A short setup with migrate-and-conquer init
• A prompt:

"Audit this codebase using migrate-and-conquer. First, run mac guide to understand the workflow. Check configured attack vectors (mac vector list), inspect the predecessor source in .reference/, create mapping stubs (mac map add <vector> <id> --module <module>), and fill in predecessor context. If successor code exists in src/, compare features and record gaps; otherwise leave successor null and set status: "discovered". Run mac validate when done."

Once the Agent is done analysing and data was created, a nicely formatted HTML Page is generated which can be used by the Product Owner to validate findings.

Important concepts

Modules

Describe features which both applications, old, new or both have, e.g. "User Auth", "Calculator" or "User Manager".

Attack vectors

To be able to compare old and new, you need something which did not change. We have 5 preconfigured things ready:

• Routes: Useful for websites or webapps
• APIs: Reference to external apps, e.g. a Content API
• Components: CMS or Frontend components which need to be migrated
• Translations: Useful to check if really all features have been taken over
• Fields: Checks if really all the data available is accessed and used in both

Attack vectors produce mappings between old and new.

Mapping

Mappings are produced by attack vectors and can be attached to modules. The idea is to define where in the old and new code a specific API, Route, Component, Translation or Field is used.

The Agent can not determine what is really missing and does not know the goal of the migration. This only the product owner knows. The Agent will only analyse.

Use-Cases

This tool can be used whether only old code is available and a migration is planned, or if old and new code are already available and you want a classic gap analysis to validate, that really everything was migrated.

CLI & Data Model Reference

Temporary by design. This tooling exists only during migration. When all gaps are resolved and the predecessor is decommissioned, delete it.

Usage

Run via npx:

npx migrate-and-conquer init

Or install globally:

npm install -g migrate-and-conquer
mac init

CLI Commands

Run mac --help or mac to list all available CLI commands.

Data Model

The campaign data directory stores module definitions and vector mapping files:

.mac.json (project root)       ← campaign config
docs/migration/                ← data directory (configurable)
├── modules/                   ← functional module definitions
│   └── <module-id>.json
├── <vector-id>/               ← vector folders (e.g. route-map, apis-map)
│   └── <mapping-id>.json      ← individual mapping files
└── dist/                      ← generated static HTML report (gitignored)

• Modules: modules/<id>.json defines a functional unit
• Mappings: One JSON file per item in the configured <vector-id>/ directory
• Gaps: Recorded directly within each mapping file
• Instructions: Bundled in the CLI tool (view via mac vector describe <id>)
• Dashboard: Generated to dist/ (gitignored)

Workflow

1. mac map add creates JSON stubs with the full schema
2. Edit the files to fill in predecessor/successor context + gaps
3. mac validate catches schema errors
4. mac build / mac open generates the HTML report

LLMs use mac vector describe <id> to learn what to look for, then create stubs and edit files.

Design Principles

• File-per-mapping — no monolithic store, clean git diffs
• Stubs + edit — CLI creates schema-complete JSON, LLMs/humans fill it in
• Modules as first-class — functional grouping across vectors
• Pluggable vectors — add one in .mac.json, create a folder, done
• Class-based renderers — each vector can have its own HTML rendering
• Temporary — everything gets deleted when migration completes

CI / GitLab Pages

Validate and publish dashboard in .gitlab-ci.yml:

pages:
  image: node:24-alpine
  script:
    - npx migrate-and-conquer validate
    - npx migrate-and-conquer build
    - mv docs/migration/dist public
  artifacts:
    paths:
      - public
  only:
    - main