How it flies

Published 27/10/2026

Every change in an ADE project is a card, and every card lands through the same loop. This page walks through both, then the parts that keep agents informed while they work.

Cards#

A card is the smallest useful piece of work: a title, the paths it may touch, and a done line that says what finished looks like.

ade card add "rate-limit the login form" --path src/auth/*.py --path tests/test_auth.py \
  --done "a sixth attempt within a minute is refused, and a test says so"

Cards live in your records, not in a hand-edited file. ade card list shows the board and ade cockpit shows each open card with its state and the next command to run.

The loop#

ade loop c1 walks five stages. Each stage either advances or stops with the next command:

1. Lane. The card gets its own git worktree on its own branch, outside your checkout, so builders never touch the files you are working on. Before starting, ADE notes anything that changed under the card's paths since it was written, and any name the card mentions that the code does not contain.
2. Build. One engine, Claude Code or Codex, makes the change in the lane with the card's title, paths and done line. ADE commits the result. A change outside the card's paths stops the loop for you to look at.
3. Review. Changes that only touch prose land without review. Code gets one light round from the reviewer role, which answers with approval or a patch. ADE applies the patch once and moves on, so a review never turns into a long thread.
4. Test. The graph picks the tests that reach the files the change touched. A file no test reaches adds a small critical set you configure, never the whole suite. Paths you mark as proof-grade always run every test that reaches them. A test that is already failing on your main branch is noted, not blamed on the card.
5. Land. With an approved review and passing tests, ADE merges the lane, writes one outcome record, removes the lane and, unless you turned it off, pushes.

When the loop stops#

A stop is one of two kinds:

• Wait: something outside the loop has to change first, such as uncommitted work on your main branch. Nobody is woken.
• Needs judgement: a person or a model has to decide, such as a review patch that does not apply.

Either way the loop prints the command to run next, and running ade loop again resumes where it stopped. Review and test results are cached by the exact state of the lane, so nothing is repeated.

Flying the whole board#

ade conduct runs the loop on every open card and handles each stop the same way every time, using a small routing table, ade/route.toml, that says what to do at each kind of stop: retry once, wait for a condition, wake a model to judge, or park the card for you. A model is woken only where the table says so, so a board with no surprises costs nothing beyond the building and reviewing itself. A card that needed a model twice, or an engine over its share of the week, parks for you instead.

Put together, every card flies the same seven legs: pick (the conductor takes the oldest open card, or you name one), the five stages above, and the hold, where any stop is routed and the card later rejoins the course where it left it.

ade session start board -- conduct runs the same thing detached from your terminal, on any platform. ade session attach board follows it, and ade session stop board ends it.

The graph#

graph.json is a map of your project: every file, what it imports, who calls it, which tests reach it and which docs mention it. ade graph regenerates it from the code itself, and ade graph --check fails in CI if the committed copy is stale. Adding a language is adding one small reader; Python and TypeScript/JavaScript are built in.

Code files can carry an optional five-line header (id, what, cmd, reads, writes). Nothing requires it in a project you bring to ADE, and it makes the briefings richer.

Briefings and handovers#

• The first-edit briefing. The first time an agent edits a file in a session, ADE tells it who calls the file, which tests reach it, which decisions govern it, which docs describe it and which helper to reuse. It is capped at 250 tokens (on ADE's own code they measure 34 to 144, about 100 typical) and comes straight from the graph.
• The handover. ade handover --role builder prints a role's whole working context: open cards, decisions, recent observations and the parts of the graph that matter, within a fixed token budget. Claude Code receives it automatically at the start of every session and after compaction, so a fresh start and a resumed one are the same thing.

Records#

Everything ADE knows about your project's history is a record, written by one command each:

Records are plain JSON lines in .ade/. The ones worth keeping are also committed to an ade-records branch that travels with the repository, so a fresh clone gets its history back.

Refusals#

When ADE refuses something, the message names the cause and the cure, and the refusal is counted. A refusal that keeps firing on work that was fine is treated as a bug in ADE, not in your work.