Atlas ADE DOCS
Docs / Guides / Porting a project

Porting a project

Published 27/10/2026

ADE is built for new projects first, and it moves into a project you already have with no changes to that project's code.

Run init and read what it found#

From a clean checkout of your main branch:

SH
ade init --dry-run       # what it would write, nothing changed
ade init

The first run reads the repository and prints what it found and what it chose:

  • Your trunk, whatever it is called, from the branch you ran init on.
  • Branch mirrors. If your git config pushes one branch to two names (master to main as well), ADE keeps the mirror. On GitHub it writes a small workflow so GitHub moves the mirror, and no machine has to push it.
  • Deploy triggers. If a push to your trunk would run a workflow that deploys, ADE turns its automatic pushing off and tells you which workflow, so landing a card never ships it.
  • Dependencies. Gitignored folders such as node_modules or .venv are linked into each lane instead of being installed again.
  • A typecheck script, which it runs on every change that touches code.
  • Whether its own line budget applies. That budget is for ADE-sized codebases; a larger project is left out of it.

Settle the rest in ade.toml#

Read the ade.toml init wrote and set what only you know:

TOML
[tests]
command = "npx tsx {test}"        # {test}: once per selected test file; {tests}: all of them in one run

[rigour]
proof_grade = ["src/payments/*"]  # paths where a mistake costs real money or data: every reaching test runs

[graph]
tests = ["scripts/test-*.ts"]     # where your tests live, if not in the usual places
exclude = ["generated/*"]

Then run ade init again to regenerate the settings, and commit:

SH
ade init
git add -A && git commit -m "install ade"

Living alongside your existing setup#

  • An existing .claude/settings.json is kept; ADE adds its permissions beside yours.
  • An existing AGENTS.md keeps its text; ADE adds one generated block between markers and owns only that. CLAUDE.md is left alone.
  • Your files never need ADE headers. A ported project requires nothing extra of its code; headers and tests are noted where missing, never forced.
  • Scripts and CI files that call ade are checked at every landing, so renaming an ADE command can never leave a script of yours behind.

A worked example#

One of the first projects ported was a TypeScript and React Native app of about 29,000 lines, with its own CLAUDE.md, its tests as 19 separate scripts, a trunk called master mirrored to main, and deploys run by hand.

  • ade init found the trunk, the mirror, the gitignored node_modules and the typecheck script on its own, and saw that no workflow deploys on a push, so landing could push.
  • By hand: the per-file test command, four proof-grade paths (the encryption code, the database migrations, the workers and the build check), and two generated folders to leave out of the graph.
  • The graph mapped 143 files to their tests, so a change to the search code runs only the search tests.
  • The first real card, built and reviewed by Claude, landed in 31 seconds for about $0.24, with the typecheck run and the missing test on that file noted rather than blocking. The project's code needed no changes.

Try it before trusting it#

Set ADE_PROVIDER=fake and land a small card first. The loop runs end to end, creates and removes a lane, runs your real tests and merges, with a fake engine that spends no usage. Then unset it and land the same kind of card for real.

PREVIOUSSafety and privacy