> ## Documentation Index
> Fetch the complete documentation index at: https://docs.substrate.42.pe/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Conventions for Reliable Substrate Board Behavior

> The do-and-don't habits every agent must follow to keep a shared Substrate board trustworthy across multiple sessions and concurrent writers.

A Substrate board is shared state. Multiple agents, multiple sessions, and human teammates all read and write the same data. The conventions below are what separate a board that stays coherent from one that drifts into noise. They are not suggestions — a board where any one of these is consistently violated stops being a reliable source of truth.

## Do

<CardGroup cols={1}>
  <Card title="Pass agent_name on every write" icon="tag">
    Use a stable identifier for yourself — for example, `"claude-code"`. It is an audit tag, not authentication, but a board where every write is attributable is the difference between a log and a guess.
  </Card>

  <Card title="Use optimistic concurrency properly" icon="arrows-rotate">
    `update_task`, `update_board`, `update_group`, `update_policy`, and `update_project` all require the `version` from your most recent read. On a `version_mismatch` error: re-read, reconcile, then retry. Never blindly overwrite.
  </Card>

  <Card title="Read before you write" icon="magnifying-glass">
    Resolve real board and group ids from `whoami` and `get_board_substrate`. Do not guess an id — a guessed id that happens to match an unrelated entity is silent corruption.
  </Card>

  <Card title="Merge custom_data key-by-key" icon="layer-group">
    Send only the keys you are changing. Pass `null` for a key to delete it. You do not need to resend the whole object — Substrate merges at the key level.
  </Card>

  <Card title="Put decisions in comments, state in fields" icon="comment">
    A policy can read a field; nothing reads prose. If a gate depends on a value, that value must be a field.
  </Card>
</CardGroup>

## Do Not

<CardGroup cols={1}>
  <Card title="Do not invent board or group ids" icon="ban">
    Resolve them from reads. An invented id that silently matches something else is worse than a clear error.
  </Card>

  <Card title="Do not skip agent_name or omit version on an update" icon="ban">
    Both are required for attribution and concurrency correctness. Omitting either is the most common cause of confusing audit logs and unexpected overwrites.
  </Card>

  <Card title="Do not duplicate a board or group that already fits" icon="ban">
    Extend the existing substrate. Two boards modelling one flow is how a substrate stops being a single source of truth.
  </Card>

  <Card title="Do not treat a block or a suggestion as noise" icon="ban">
    A `transition_guard` block and an `agent_responsibility` message are the point of the system, not friction in it. Read them and act.
  </Card>

  <Card title="Do not try to set a human_only field" icon="ban">
    Your tools refuse it. That refusal is what makes the gate real. Report it instead — see `list_pending_approvals`.
  </Card>
</CardGroup>

## Your Own Error Trail

Handled tool errors from your session are recorded to `.substrate/logs/substrate.log`. To surface only the errors:

```sh theme={null}
substrate logs --errors
```

<Note>
  Routine gate blocks and stale-version retries are intentionally excluded from this log — they are normal operation, not faults. What remains is worth reading when something is not behaving as expected, and worth attaching to a bug report alongside [`substrate diagnose`](/cli/diagnose).
</Note>