Skip to main content
These twelve tools edit substrate-as-code — the same thing you could edit by hand in .substrate/boards/<id>.json. Changes take effect on the next read: no migration step, no server restart required. All twelve require agent_name; all update and archive operations also require the current version of the entity you are changing.
Reach for these tools to extend an existing board. Creating a second board that models the same flow is the most common way a substrate stops being a single source of truth.

​
Project

​
update_project

Updates top-level project metadata. Send only the fields you are changing.
​
integer
required
The version from your last get_project read.
​
string
required
A stable identifier for the calling agent.
​
string
New project name.
​
string
New project description.

​
Boards

​
create_board

Creates a new board and returns it with its generated id.
​
string
required
Board name.
​
string
required
A stable identifier for the calling agent.
​
string
Board description.
​
object
Optional initial field schema. Validated structurally on creation.
​
string
Project to create the board under. Defaults to the current project.

​
update_board

Updates a board’s metadata or field schema. Send only what is changing.
​
string
required
The board id.
​
integer
required
The version from your last read.
​
string
required
A stable identifier for the calling agent.
​
string
New board name.
​
string
New board description.
​
object
Replaces the entire field schema. Use field_schema_patch when changing one field.
​
object
Merges into the existing schema key-by-key. Set a key to null to delete that field. Prefer this over field_schema when changing a single field.
Schema changes never reject existing task data — validation is lazy. Existing tasks are not revalidated when you tighten a schema.
update_board refuses to downgrade a human_only field. An agent can neither clear the human_only flag nor delete the field to escape a human gate. Both operations return forbidden.

​
archive_board

Soft-deletes a board. Idempotent.
​
string
required
The board id.
​
integer
required
The version from your last read.
​
string
required
A stable identifier for the calling agent.

​
unarchive_board

Restores an archived board. Idempotent.
​
string
required
The board id.
​
integer
required
The version from your last read.
​
string
required
A stable identifier for the calling agent.

​
Groups

​
create_group

Creates a new group on a board.
​
string
required
The board to add the group to.
​
string
required
Group name.
​
string
required
A stable identifier for the calling agent.
​
string
Group description.
​
integer
Display position. Defaults to the next available slot.
​
string
Display color for the group.

​
update_group

Updates a group’s display properties. Send only the fields you are changing.
​
string
required
The group id.
​
integer
required
The version from your last read.
​
string
required
A stable identifier for the calling agent.
​
string
New group name.
​
string
New group description.
​
integer
New display position.
​
string | null
New display color. Set to null to clear it.

​
reorder_groups

Reorders all groups on a board in one atomic write. You must supply every group id — partial lists are rejected.
​
string
required
The board whose groups to reorder.
​
string[]
required
The complete ordered list of group ids. Must be exactly the board’s current group ids.
​
string
required
A stable identifier for the calling agent.

​
archive_group

Archives a group. The group must have no active tasks — move them first. Idempotent once the group is already archived.
​
string
required
The group id.
​
integer
required
The version from your last read.
​
string
required
A stable identifier for the calling agent.
If active tasks still reference the group, the tool returns conflict. Move or archive the tasks first, then retry.

​
Policies

​
create_policy

Creates a policy on a board. The two policy types have different definition shapes.
​
string
required
The board to add the policy to.
​
string
required
Policy name.
​
'transition_guard' | 'agent_responsibility'
required
Policy class. Immutable after creation.
​
object
required
The policy logic. Shape is validated against type — see below.
​
string
required
A stable identifier for the calling agent.
​
string
Human-readable explanation of what the policy does.
​
integer
Evaluation priority. Lower numbers run first.
​
boolean
Defaults to true. Set to false to create a disabled policy.
Definition shapes: transition_guard — Blocks a matching move unless every require condition passes.
agent_responsibility — Never blocks. Attaches a message as a suggestion in the write envelope whenever when matches. An empty when matches every write.
Conditions are { field, op, value?, values? } or a compound { all_of | any_of | none_of: Condition[] }. Fields resolve literal-then-custom_data, so a custom gate field is referenced as task.<name>. See Authoring Policies for the full grammar.

​
update_policy

Updates a policy. Send only the fields you are changing. The policy type is immutable — archive the policy and create a new one to change class.
​
string
required
The policy id.
​
integer
required
The version from your last read.
​
string
required
A stable identifier for the calling agent.
​
string
New policy name.
​
string
New description.
​
object
Replacement definition. Re-validated against the policy’s existing type.
​
integer
New evaluation priority.
​
boolean
Enable or disable the policy.
Policy type is immutable. To change a policy from transition_guard to agent_responsibility (or vice versa), archive the existing policy and create a new one.

​
archive_policy

Archives a policy. Idempotent.
​
string
required
The policy id.
​
integer
required
The version from your last read.
​
string
required
A stable identifier for the calling agent.
Archiving a guard removes a rail. The action is git-visible and event-logged rather than silent — but an agent under pressure archiving the gate that blocks it is the residual risk in the model.

​
After Editing

Run substrate validate to check all board files for structural errors. Then prove the rail fires as expected: see Validate Gates.