Atlas ADE charter

Status: approved by Connor, 26 Oct 2026; platforms, main path, review, graph feeding, permission mode and telemetry updated by Connor the same day. Command: ade.

Atlas ADE is a small, portable agentic development environment. It sets up Claude Code (and Codex) in any repository so that agents keep working context, do the right thing by default, and land changes through one short loop, while the person flies it from a cockpit. It is the Atlas CLI's ideas, rewritten small, with none of Atlas's code or history.

1. What a user can do (v1)#

1. Start a new project on ade, or install it into an existing repo, with one command: settings, conservative permissions, hooks, agents, skills, status line. Dry-run diff, idempotent, clean uninstall.
2. Configure one file, ade.toml: providers and models per role, test command, protected paths, rigour level per path.
3. Keep a board of cards as plain files, and pick the next one (the pick shows if its paths moved since it was written).
4. Record facts with verbs that write their own records (ade decide, ade card, ade land): append-only, typed, one writer per fact.
5. Ask the graph what a file is, who calls it, which tests cover it and which decisions govern it. The graph is generated from code and records, never hand-kept.
6. Get briefed on edit: the first edit of a file in a session brings its callers, tests, decisions and the blessed helper, in about 250 tokens.
7. Start or resume any role from one generated handover within the warm-up budget.
8. Run a builder lane in an isolated worktree, on either provider.
9. Review by policy: none for prose, light for code. The reviewer returns a patch, not a list.
10. Test what the change reaches, selected from the graph; an unknown path selects a small critical set, never everything. Tests are minimal (Connor, 27 Oct): as few as possible, each a robust, documented invariant that stays true (the date is dd/mm/yyyy), never a literal that is true today (the date is 27/10/2026). A changed file with no test lands, and the outcome notes it.
11. Land: merge, one verdict, one outcome record, reds carried to one residuals card. A driver walks the happy route and wakes a model only for judgement.
12. Decide: a queue of human decisions, each with a recommendation, a default and a deadline.
13. See usage: tokens, cost and time per call and per card, and the kit's spend against the share of the week Connor sets, all kept locally.
14. Pilot from Orca (desktop or phone), or from the CLI alone with nothing missing.

2. Design rules (each one is yes or no)#

1. Each path has one of two rigour levels, set in config; the kit's own files are orchestration-grade.
2. Nothing is hand-registered: every list, edge and index is generated from self-describing headers.
3. Each fact has one writer, a verb; storage is plain files or one SQLite file.
4. Facts come from graph queries, decisions attach to paths, procedures are scripts, history is never loaded.
5. Comments say why and how to change; who, when and which session live in git and records.
6. Core code stays within its line budget, and every merge prints net lines per component.
7. Every refusal names its cause and its cure; one that fires on correct work twice is a defect.
8. Tests sit at the edges (install, one full loop per config option) and assert invariants; no literal pins, no count pins, no tests of tests, and none added by reflex.
9. Claude Code and Codex are adapters; agent definitions are generated per provider from one source.
10. Platform first: each homegrown part names the platform feature that would let us delete it.
11. Configuration over code: a would-be refusal becomes a setting where it can.
12. An incident buys an exhibit, not a rule; a new check takes a budget slot or Connor's word, and to add one, remove one.

3. Budgets (the only standing gates)#

Blocking happens only for named error classes: secrets, destructive commands, protected config, and code landing with no test reaching it. Everything else adds context and never refuses.

4. Two rigour levels#

• Proof-grade, for paths whose output can cause harm (a project's clinical logic, data boundaries, releases, secrets): every test that reaches the paths touched, results keyed to the commit they proved.
• Orchestration-grade, for everything else, the kit included: fail loud, retry cheap, idempotent steps, simple state, light review.

A project lists its proof-grade globs in ade.toml; anything unlisted is orchestration-grade.

5. Acceptance tests#

1. Newcomer: someone new to agentic tooling starts a new project on ade and lands a first change in about 30 minutes, on Windows, macOS or Linux.
2. Warm-up: every role's generated handover is within 20k tokens.
3. Skeleton: the thin slice (install, config, one lane, review, tests, merge, record, graph, handover, cockpit stub) runs end to end twice from a clean clone, tagged checkpoint/skeleton.
4. Port: a small real project (first target below) runs its loop on ade with no kit-specific edits to its code.
5. Neighbour: with ADE installed and running, Practice Atlas sees no change: no atlas calls, no ATLAS_* variables, no tmux, no launchd jobs, no edits to ~/.claude/settings.json.

6. Constraints carried over#

Never read, print or commit secrets; pass keys by path. No patient or personal data in any artifact. Never rewrite git history. Bypass permission mode is allowed, because hooks hold the structural rules in every mode. No telemetry leaves the machine; internal telemetry and logs are kept. Never touch credential files, every allow rule explained. Money, accounts, public claims and anything external are Connor's. ADE is built outside Atlas's validation regime, under these rules only.

7. v1 scope decisions#

Generated from CHARTER.md when the site was built.