# 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](<https://sandloom.dev/docs/ai/generators/index.md>) write the starting code in the shape the framework expects. The project rules in `AGENTS.md` and the [skills](<https://sandloom.dev/docs/ai/agent-tooling/index.md>) tell your agent how to change it. [Checks](<https://sandloom.dev/docs/ai/checks/index.md>) 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](<https://sandloom.dev/docs/ai/generators/index.md>), [Generate contracts and snapshots](<https://sandloom.dev/docs/ai/generate/index.md>) |
| Work | `AGENTS.md`, skills, `sandloom docs`, `sandloom context`, `sandloom graph` | [Agent tooling](<https://sandloom.dev/docs/ai/agent-tooling/index.md>), [Module maps for agents](<https://sandloom.dev/docs/ai/module-context/index.md>), [Explore the architecture graph](<https://sandloom.dev/docs/ai/architecture-graph/index.md>) |
| Check | `sandloom check`, `sandloom test`, `sandloom explain` | [Checks](<https://sandloom.dev/docs/ai/checks/index.md>), [Testing modules](<https://sandloom.dev/docs/modules/testing/index.md>) |

## One change through the loop

Start: in an application named `demo`, a generator adds an [event](<https://sandloom.dev/docs/modules/between/events/index.md>), 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](<https://sandloom.dev/docs/ai/checks/index.md>) 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

- [Error codes](<https://sandloom.dev/docs/reference/error-codes/index.md>): every code, with its cause and fix.
- [CLI reference](<https://sandloom.dev/docs/reference/cli/index.md>): every command and flag.
- [Tutorial: your first feature](<https://sandloom.dev/docs/getting-started/tutorial/index.md>): the loop on a real feature.