The agent workflow

Atlas is designed so that an agent never has to guess. The system declares itself as data, and a tool answers the questions an agent would otherwise answer by reading many files.

Question an agent would otherwise answer by exploring	Command
What exists, and how does it connect?	atlas map (--json, --mermaid)
What do I need to know to change X, and what breaks if I do?	atlas context <capability>
Is the system consistent?	atlas check (--json)
Do the decisions behave as specified?	atlas test

The loop

1. atlas context <name> (or atlas map if you do not know the name).
2. Edit only the file it names. Add or update examples first: they are the spec.
3. atlas check: fix every error using its fix: line; re-run until clean.
4. atlas test: every example must pass.
5. Before finishing, the project’s full check (npm run check inside Atlas: typecheck, unit tests, atlas check, atlas test).

atlas context

The centerpiece. It prints the capability’s file, every upstream shape it relies on, and its field-level blast radius: which capabilities read which fields of what it produces. Real output on the repository’s orders capability:

orders — src/capabilities/orders.ts (112 lines)
intent: Customers place orders for themselves and cancel their own, at most once. The customer is the actor, never the payload.

CONTRACTS
  command PlaceOrder  access user  input { orderId: string, lines: { sku: string, quantity: int, unitPriceCents: int }[] }
  command CancelOrder  access user  input { orderId: string, reason: string }
  emits OrderPlaced { orderId: string, customerId: string, lines: { sku: string, quantity: int, unitPriceCents: int }[], totalCents: int }
  emits OrderCancelled { orderId: string, reason: string, lines: { sku: string, quantity: int }[] }
  ...

UPSTREAM (what this capability relies on)
  (nothing: this capability only reacts to commands from outside)

DOWNSTREAM BLAST RADIUS (who breaks if what this produces changes)
  OrderPlaced.orderId <- order-summary, stock
  OrderPlaced.customerId <- order-summary
  OrderPlaced.lines[].sku <- stock
  OrderPlaced.lines[].quantity <- order-summary, stock
  OrderPlaced.totalCents <- order-summary
  OrderPlaced: unused by consumers (safe to change): lines[].unitPriceCents
  ...
  orders.status <- cancel-unfulfillable (foreign read)
  PlaceOrder <- external callers only
  CancelOrder <- sent by cancel-unfulfillable

To change this capability, edit only: src/capabilities/orders.ts
Then run: node bin/atlas.ts check && node bin/atlas.ts test

atlas check

Every diagnostic is an instruction: the rule, the place, why it matters, and the exact fix.

error ATLAS003 consumer: consumes Made.lines[].sku, but producer does not emit it
  why: a consumer that requires a field its producer does not guarantee fails at runtime.
  fix: add `sku: t.string` to emits.Made (inside `lines[]`) in test/fixtures/broken/producer.ts, or remove it from needs of .on('Made') in test/fixtures/broken/consumer.ts.

It exits 1 on errors. Every code is listed in check rules.

atlas test

Runs every handler and query example, and prints one line per example plus a summary:

28 passed, 0 failed, 28 examples in 4 capabilities (13 ms)

atlas schema

atlas schema exports JSON Schema for every command input (with access and the rejection codes known statically), query input and output, fact and view row. atlas schema --openapi gives OpenAPI 3.1 paths for POST /commands/{type} (internal commands excluded) and GET /queries/{name}.

The skill

The repository ships skill/SKILL.md, an agent skill with the hard rules and a decision table (situation -> action) for working in an Atlas project. Point your agent at it.

Why it works

See the thesis: the cost of a change is find + understand + write + verify, and computed context attacks the first two terms.