Overlays and templates:

• overlays/forgotten-industries.md - public-safe project overlay for Forgotten Industries.
• templates/repo-AGENTS.md - starter root instructions for downstream repositories.
• templates/project-overlay.md - starter overlay for a new project.
• templates/continuity-capsule.md - private downstream handoff schema; never live archive state.

Plugin surface (generated — edit the sources, then regenerate):

• .claude-plugin/plugin.json - the plugin manifest.
• settings.json - plugin settings. Deliberately empty: ATLAS does not claim the main thread.
• agents/atlas.md - the compact core, inline. Built by bin/atlas-context --mode agent.
• skills/ - the thirteen council members (cores only, built by bin/atlas-skills), plus the hand-authored git-cleanup utility skill.
• skills-standalone/atlas/ - the /atlas rite. Built by bin/atlas-rite-skill.
• hooks/hooks.json - loads a project continuity capsule at session start, routes every prompt through Le Rouage, and draws Le Cadran after each turn.

Scripts and examples:

• bin/atlas-context - deterministic agent, compact, or doctrine-stripped portable builder.
• bin/atlas-skills, bin/atlas-rite-skill - generate the plugin's skills.
• bin/atlas-continuity - initializes and checks an untracked project continuity capsule.
• bin/atlas-session-start - the SessionStart hook. Emits the capsule as context.
• bin/atlas-route - the UserPromptSubmit hook. Routes each prompt through the train, records the winding, and seats the barrel when a member is named; it draws no dial. ATLAS_NO_ROUTE=1 turns it off.
• bin/atlas-settle - the Stop hook. Reads the turn back, takes each council skill the barrel invoked as a proposal, records a settle winding, and draws Le Cadran from what convened, named and unnamed together. Silent when nobody did.
• bin/atlas-windings - the windings log as counts: who convened, named or unnamed, and how many bare continuations stayed dark. Never prints prompt text.
• bin/atlas-doctor - verifies assembly, fingerprints, privacy boundaries, and doctrine stripping.
• bin/atlas-clones - reports which clone the /atlas symlink resolves to, and flags any clone holding work that exists nowhere else. Matches on origin or on shared root commit, so a clone left pointing at a pre-rename URL is still recognized.
• adapters/ - handoff instructions for Codex and file-less agents.
• runtime/ - ordered manifests, runtime contracts, codas, and assembly tests.
• examples/larchive/ - a worked example of ATLAS operating as L'Archive: an accession log plus its project-context file.

Level and modules:

• overlays/le-niveau.md - the leveling system: tiers, XP curve, and the module ledger.
• level/ - the level computed in code. Python, stdlib only, parses the ledger, 8 tests.
• modules/ - knowledge and skill modules that raise the level, one file each.

Requirements

• git - to clone the repository and link the rite.
• python3 3.9+, standard library only - no pip packages.
• Claude Code - to run ATLAS as a plugin.
• Standard POSIX tools (awk, sed, grep, cut, cmp, find, mktemp) - present by default on macOS and Linux.
• Network access is optional. The only outbound call is the update check when the crown is wound; it is bounded by a five-second watchdog and silent on failure, so ATLAS runs fully offline without it.

Le Conseil

Thirteen subroutines, gated and routed by overlays/le-conseil.md. They are operating modes of one agent, not thirteen agents.

The council is built as a diver's chronograph, and each part carries a real constraint:

Each file has an OPERATIONAL CORE for runtime and a DOCTRINE section below it for authoring. A router loads the core alone.

The distinctions that keep them separate: Le Sceptique attacks the claim, Le Fripon attacks the defence, Le Renégat attacks the consensus. Le Limier reconstructs the event, Le Cartographe maps the terrain, Le Forgeron changes the system, Le Messager controls the transmission.

The door is machinery and the last word is human: structural refusal happens at the escapement, where it needs no judgement, and what survives reaches Le Sceptique, where it needs a person.

Use In A Project

Each downstream project should keep its own local AGENTS.md. That file should point to local project rules first, then to any ATLAS overlay or copied ATLAS guidance.

Recommended project pattern:

PROJECT/
  AGENTS.md
  ATLAS.md
  atlas/AGENTS.md
  atlas/subroutines/

For larger projects, keep the project-specific instructions local and use this repository as the source of truth for shared ATLAS behavior.

The Plugin (Claude Code)

ATLAS is a Claude Code plugin. Enable it and every session starts as ATLAS, layered on top of the project you are already in. Type /atlas to wind the crown.

Quickstart

Inside Claude Code:

/plugin marketplace add SCADUMEN/ATLAS
/plugin install atlas@scadumen

The plugin stays enabled across sessions — no flag, no PATH entry, nothing in your shell rc. Then clone the repository once and link the rite so /atlas resolves:

git clone [email protected]:SCADUMEN/ATLAS.git
ln -s "$(pwd)/ATLAS/skills-standalone/atlas" ~/.claude/skills/atlas

Optionally, tell ATLAS who you are so it greets you by name instead of the generic "Operator":

ATLAS/bin/atlas-operator init   # scaffolds ~/.claude/atlas/operator.md

Edit the file's first heading to your name. See "Operator identity" for the full mechanism and the ATLAS_OPERATOR_FILE / ATLAS_NO_OPERATOR controls.

To work on ATLAS itself, point Claude Code at your checkout instead of installing:

claude --plugin-dir /path/to/ATLAS

Two install locations, and the reason is not arbitrary. A skill's invocation name comes from its directory, so a bare /atlas requires the rite to sit at ~/.claude/skills/atlas. The plugin cannot also live there, so it is enabled separately. Plugin skills are namespaced regardless — /atlas:le-limier — which is why only the rite needs the standalone slot.

What it does

agents/atlas.md is the session agent, and it is opt-in: launch it with claude --agent atlas:atlas, or pick it from /agents. A bare claude comes up as the built-in agent. When ATLAS is the agent, its prompt, model, and tools govern the main thread. That agent carries the compact core: ATLAS.md, rapport/AGENTS.md, overlays/le-conseil.md, the runtime contract, and the coda. The core is operator-agnostic: no specific person ships in it, and ATLAS addresses you as "Operator" until you set an operator profile (see "Operator identity"). ATLAS governs the interface; current direct instructions and project rules remain authoritative, and your own CLAUDE.md still applies.

The core is inline because it has to be. An agent's skills: field preloads full skill content for subagents, but not for the main-thread agent — tested, not assumed. So agents/atlas.md is generated:

bin/atlas-context --mode agent    # regenerate after editing any core file

It records a content fingerprint and no timestamp, so identical sources produce identical bytes. runtime/test_runtime.py regenerates and diffs, so a stale agent file fails loudly rather than loading quietly.

In the language of the movement: the plugin fits the running model as the barrel (overlays/le-barillet.md). The model supplies force; the doctrines supply shape.

The Arrival rite

/atlas

The rite renders the masthead, the trinity, and the live level — read at skill load by a shell command inside the skill, never hardcoded.

Because the level is read by a shell command that runs as the skill loads, Claude Code gates it behind Bash permissions. Pre-approve it with an allow rule in your user settings at ~/.claude/settings.json, using your own absolute home path:

{
  "permissions": {
    "allow": ["Bash(/Users/you/.claude/skills/atlas/level:*)"]
  }
}

It has to be user settings, and it has to be the absolute path. The plugin's own settings.json honours only agent and subagentStatusLine and silently drops everything else, so the rule cannot ship with the plugin. A ~/-relative Bash rule is not reliable either: the command is matched after $HOME is expanded, and the ~/ and // anchors that permissions document are for path rules (Read, Edit, Cd), not for Bash command rules. Skip the rule and the first /atlas prompts to approve the command; answering "Yes, and don't ask again" writes an equivalent rule for you.

Nothing fires it automatically, and that is a platform fact rather than a shortfall. No hook can submit a first turn: SessionStart adds context and cannot make the model speak. initialPrompt does auto-submit, but only for user-level agents, not plugin ones. The crown is the Operator's to turn.

The masthead is a framed panel — a globe borne by a kneeling figure, titled First Light, over the motto. rouage/premiere_lueur.py is its canonical source:

python3 rouage/premiere_lueur.py  # the canonical panel

The panel exists in three places — the module, the rite in runtime/compact-coda.md, and the generated /atlas skill. Two generators and two tests keep them equal; a hand edit to any copy fails the suite.

The council

Naming a member loads its OPERATIONAL CORE and nothing else. The thirteen doctrines are not loaded up front, because thirteen doctrines do not fit the reserve.

bin/atlas-skills          # regenerate after editing any subroutine
bin/atlas-skills --check  # fail if any skill is stale

The doctrine rule is now structural rather than honoured. A skill file carries the core alone, so a DOCTRINE section cannot reach a working context even by accident. /atlas:authoring is the deliberate way in.

Le Fripon carries disable-model-invocation: true. Doctrine says he never self-activates without L'Opérateur, and the harness enforces it: only /atlas:le-fripon reaches him.

Every other member convenes unnamed too. Each skill description carries both halves of its gate, and when a situation meets the automatic half the barrel invokes the member's skill with its reason as args. Le Cadran is drawn after the reply from whoever actually convened. evals/ holds the use cases that say when each one should, and should not:

python3 evals/suite.py --check   # the case files match evals/suite.json
claude plugin eval . --ablation none --runs 3 --keep-temp --json arm.json
bin/atlas-windings               # the same question, asked of your own log

Operator identity

ATLAS serves one Operator, and by default addresses them generically as "Operator". To be greeted by name, create a per-user operator profile:

bin/atlas-operator init

This scaffolds ~/.claude/atlas/operator.md (honouring CLAUDE_CONFIG_DIR). The first Markdown heading is your name; everything below — preferences, working context — is optional. The SessionStart hook loads it for every session, so ATLAS addresses you by that name and the rite reads "I'm here, <name>." Set ATLAS_OPERATOR_FILE to point elsewhere, or ATLAS_NO_OPERATOR=1 to skip it.

The profile is per-user, never a repository file: identity is the Operator's, not the movement's, so it is never baked into the core. profiles/matthew.md remains as an example of what one looks like.

Continuity between barrels

Initialize a private project-local capsule:

bin/atlas-continuity init

This creates .atlas/continuity.md with mode 600 and adds .atlas/ to the repository's local .git/info/exclude. It refuses to overwrite an existing capsule. The capsule separates verified state, operator testimony, inference, plans, the last safe state, and the next move. It is never canonical memory and must never contain secrets.

A SessionStart hook loads the capsule as read-only project state when one exists at the project root. Set ATLAS_NO_CONTINUITY=1 for a session that must not load it, or ATLAS_CONTINUITY_FILE to select an explicit capsule.

Run the diagnostic pulse:

bin/atlas-doctor

It verifies the runtime bundles, the generated agent, the council skills, the rite skill, and that no skill leaks its doctrine.

Other barrels

Build a self-contained bundle for Codex or an agent without repository access:

bin/atlas-context --mode portable --output /tmp/atlas-portable.md

Portable mode includes all thirteen OPERATIONAL CORE sections and excludes every DOCTRINE section. See adapters/codex/ and adapters/fileless/ for the downstream handoff pattern. Continuity is included in an exported bundle only when --continuity FILE is passed explicitly.

This is why the bundle assembler survives the plugin: no plugin mechanism emits a static prompt blob, and the adapters need one.

What changed from the launcher

bin/atlas and install.sh are gone. The plugin replaces both, and nothing writes to your shell rc files any more.

• atlas → claude, with the plugin enabled.
• atlas -c, atlas --model ... → the same claude flags directly.
• atlas --atlas-doctor → bin/atlas-doctor.
• atlas --atlas-context ... → bin/atlas-context ....
• atlas --atlas-continuity ... → bin/atlas-continuity ....

If install.sh previously added ~/.local/bin to your PATH, that line stays in your shell rc. Other tools may rely on it; removing it is your call.

Verification

python3 -m unittest discover runtime -v
python3 -m unittest discover rouage -v
python3 -m unittest discover evals -v
bin/atlas-doctor
claude plugin validate .

Le Niveau

ATLAS levels up. Every capability is a module with a tier and fixed XP (S=1000, A=500, B=250, C=100, D=50); the level is those XP on a 0–100 square-root curve, so the top levels are the steepest. It is deterministic: level/level.py parses the module ledger in overlays/le-niveau.md, verifies each module's file exists, sums the XP, and prints the level. A module earns nothing until its file is real.

python3 level/level.py            # full readout
python3 level/level.py --oneline  # boot banner

Current level: 100 · Grand Complication +1 (13,650 / 13,000 XP) — design-complete, with the first module earned past the line: archive verification, a knowledge pack drawn from real recovery incidents. The two S-tier modules are Reincarnation, the portable launcher above, and Le Rouage completed: the barrel boundary wired in both engines, recorded in rouage/CONFORMANCE.md. Design-complete is not finished — modules past XP100 earn Grand Complication +N, counted in modules, and prestige is uncapped where the level is not. To level ATLAS: build a module, list it in the ledger with a real path, and rerun the script. Full doctrine and the leveling schedule are in overlays/le-niveau.md.

Releases

ATLAS uses semantic versioning, declared once in .claude-plugin/plugin.json. To cut a release: bump that version, rename the CHANGELOG.md [Unreleased] section to the new version (day-to-day changes accrue under [Unreleased]), and merge to main. The Release workflow (.github/workflows/release.yml) then runs the suites and diagnostic, tags atlas--v<version> (the convention claude plugin tag expects) at the merge commit, and publishes a GitHub Release whose notes carry the changelog section and the movement's current Level — the level is surfaced at release time. It fires only when that tag does not yet exist, so an ordinary push to main with no version bump releases nothing.

PR titles follow Conventional Commits, enforced by .github/workflows/lint-pr-title.yml: feat → minor, fix/chore/docs/ci → patch, a trailing ! → major. The bump has to be in the PR's own diff, because the release fires on the version being new on main — a merge with no bump ships nothing, silently. One version per releasable PR.

Because a marketplace install caches the plugin by version, downstream users pick up a release with:

claude plugin marketplace update scadumen
claude plugin update atlas@scadumen

Bumping the version is what invalidates the cache; without it, an install keeps serving the old files.

Operating Principle

Usefulness comes first. Voice supports trust and momentum, but technical correctness, safety, and preservation override tone.

A thing documented is a thing not yet lost.