Adopt an existing app

mainsdk adopt moves an existing app onto MainSDK without a rewrite. It scans the app, ranks the gaps, locks the flows that must keep working, then changes one module per branch.

npx mainsdk adopt scan      # main.yaml as the app is, no code change
npx mainsdk adopt report    # the gaps against Main 27: secrets, access, data, the rest
npx mainsdk adopt lock      # record sign-in and checkout as locked flows
npx mainsdk adopt next      # one module, one branch, gated by check and the locked flows
npx mainsdk adopt finish    # Main 27 met, or exactly what remains

adopt:
  driver: builtin

Quick start

npx mainsdk adopt scan      # main.yaml as the app is, no code change
npx mainsdk adopt report    # the gaps against Main 27: secrets, access, data, the rest
npx mainsdk adopt lock      # record sign-in and checkout as locked flows
npx mainsdk adopt next      # one module, one branch, gated by check and the locked flows
npx mainsdk adopt finish    # Main 27 met, or exactly what remains

mainsdk adopt with no step runs the next one, so it is safe to re-run. It runs fully on your machine and sends nothing. Opening the pull request is left to you, your agent or gh: adopt only creates the branch and the commit.

Configuration

adopt has no main.yaml section. Its first step writes main.yaml for you, and its progress lives in .mainsdk/adopt.json, which is git-ignored:

{ "step": "module", "done": ["secrets", "auth"], "next": "data", "locked": 6, "byo": ["byo-identity:clerk"] }

byo lists what the app already runs and adopt keeps: a Clerk sign-in stays auth.driver: clerk, an OpenFGA model stays access.driver: openfga. Nothing is replaced.

What you get

Code that cannot move to an interface yet stays behind that interface's raw() escape hatch, and finish lists it.

With your coding agent

mainsdk adopt mcp starts a stdio MCP server with six tools: adopt.scan, adopt.report, adopt.lock, adopt.plan_module, adopt.verify_module and adopt.finish. mainsdk adopt skill writes the skill for Claude Code (.claude/skills/mainsdk-adopt/SKILL.md), Cursor (.cursor/rules/mainsdk-adopt.mdc) and any agent that reads AGENTS.md. The agent follows the same five steps and cannot skip the lock.

Errors and checks

The full list is in check codes.

Swapping drivers

adopt has one driver, the built-in one, which reads your files and runs git. There is nothing to swap.

Testing

A failing module step leaves your main branch untouched and keeps its branch for review. The scan is deterministic, so a test can run it twice and compare the two main.yaml files. Run mainsdk check after any step to see the same findings the gate uses.

Next

• Adopt an existing app, the walk-through
• Migrate from raw providers
• The CLI reference