> ## 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.

# The Agent Loop: Orienting and Advancing Work with Substrate

> How an agent orients a fresh session, records work, and advances tasks using Substrate's 32 MCP tools without losing state between sessions.

Every Substrate session starts cold — your agent has no memory of the last one. The 32 MCP tools are designed around that reality: a short, fixed sequence orients a fresh session, and every write returns an envelope that keeps the next step honest. Follow the loop below and the board stays trustworthy across sessions and agents.

## The Loop

<Steps>
  <Step title="Orient">
    Call `whoami` first. It returns the project, every board with its id, and a set of hints. One call is enough to orient a session that has no memory of the last one.

    Then call `get_board_substrate` for the board you'll work in. Cache the response — it carries the board's groups, `field_schema`, policies, and resolved team. That payload stops your agent from guessing ids or inventing field names.
  </Step>

  <Step title="See what exists">
    Call `list_tasks` before planning anything. Reconcile your plan with the board rather than adding a parallel copy of work already tracked.

    Filters are top-level parameters, not nested:

    | Parameter                                  | Purpose                     |
    | ------------------------------------------ | --------------------------- |
    | `board_id`                                 | Scope to a board            |
    | `group_id` / `in_groups` / `not_in_groups` | Scope to one or more groups |
    | `text_search`                              | Full-text match             |
    | `custom_field`                             | Match a custom data field   |
    | `missing_required_fields`                  | Find incomplete tasks       |
    | `parent_id` / `has_subtasks`               | Subtask navigation          |
    | `archived`                                 | Include archived tasks      |
    | `created_*` / `updated_*`                  | Time windows                |

    <Warning>
      An unrecognized key is silently ignored — a filter that doesn't narrow results usually means the parameter name is wrong.
    </Warning>
  </Step>

  <Step title="Record the work">
    Call `create_task` with `board_id`, `group_id`, `title`, and `agent_name`. Optionally include a markdown `description` and `custom_data` for any custom fields defined in the board's `field_schema`.
  </Step>

  <Step title="Advance it">
    Call `update_task` to change fields or move groups. Send only what changed, plus the `version` from your last read and your `agent_name`. Substrate uses optimistic concurrency — sending a stale version is refused so you never silently overwrite a peer's work.
  </Step>

  <Step title="Explain it">
    Call `add_comment` to record decisions and rationale. Call `get_task_history` to see what happened while you were away. State belongs in fields; reasoning belongs in comments.
  </Step>
</Steps>

## Read the Envelope

Every write returns a response envelope. Read it every time.

```json theme={null}
{
  "ok": true,
  "applied": { "entity": "task", "id": "…", "version": 4, "state": { "…": "…" } },
  "policies_fired": [ … ]
}
```

Two things to do with it on every write:

1. **Keep the returned `version`** for your next `update_task`. It is your concurrency token.
2. **Read `policies_fired`**. A `transition_guard` entry means a rail engaged. An `agent_responsibility` entry carries a `message` written by whoever authored the board, aimed at exactly this moment — surface it or act on it. Do not treat it as noise.

## When a Move Is Blocked

A blocked write returns `transition_blocked` with a message naming what is missing. Read the message, satisfy the prerequisite, and retry.

If the missing field is `human_only`: **stop trying**. Your write tools refuse it by design — that refusal is what makes the gate real. Call `list_pending_approvals` and report what is waiting, grouped by board, naming the exact command for each item:

```sh theme={null}
substrate approve <task_id> <field>
```

The human can also run `substrate pending-approval` for the same report, or see a "pending approval" pill on the task in the UI.

## Verify a Gate Without a Throwaway Task

`check_transition` dry-runs "would moving task X to group Y be allowed?" against the real guards and writes nothing. It returns:

```json theme={null}
{ "allowed": true, "from_group": "spec", "to_group": "build", "blocked_by": null }
```

Use it to confirm a gate is live and to see exactly what a move needs before you attempt it.

***

<Card title="Conventions for Reliable Agent Behavior" icon="shield-check" href="/agents/conventions">
  The habits that keep a shared Substrate board trustworthy across multiple sessions and concurrent agents.
</Card>