Skip to content
Menu

Documentation

The toolchain

An agent that starts each feature from an empty file invents a new layout every time. A rule it was only told about is a rule it can forget.

Sandloom puts three kinds of tools around every change. Generators write the starting code in the shape the framework expects. The project rules in AGENTS.md and the skills tell your agent how to change it. Checks fail when a change breaks a rule, and a broken framework rule carries a SANDLOOM-… code that sandloom explain turns into a fix. A change is done when uv run sandloom test prints sandloom test: OK.

The loop of a change

Step Tools Read
Start sandloom new, sandloom add, sandloom generate Generators, Generate contracts and snapshots
Work AGENTS.md, skills, sandloom docs, sandloom context, sandloom graph Agent tooling, Module maps for agents, Explore the architecture graph
Check sandloom check, sandloom test, sandloom explain Checks, Testing modules

One change through the loop

Start: in an application named demo, a generator adds an event, a message other modules can react to, to the notes module.

uv run sandloom add event notes NoteArchived --field note_id:UUID

It prints the file it edited (shortened here) and the generated files it rewrote:

  …/demo/modules/notes/events.py
wrote demo/shared/events/notes.note.archived.v1.json
wrote demo/modules/notes/module.snapshot.json
wrote .sandloom/inspection.json
generated files current (8 file(s))

Next: `sandloom test` (the module's tests and every gate).

Work: read AGENTS.md, map the module with uv run sandloom context notes, and write the code that publishes the event.

Check: run the module's tests, the rest of the suite and every check:

uv run sandloom test notes

When the change breaks a rule, the sandloom check step fails and names the file, the line and the code, such as SANDLOOM-C001. Checks walks one failure from the message to the fix.

The checks prove the structure; whether a feature does what you meant is for your tests.

Go deeper