Skip to main content
Authoring is describing a process you already have, not inventing a new one. The input is a team’s workflow — drawn from their docs, README, or a conversation. The output is a board whose stages match the real stages and whose gates match the real exit criteria. The goal is a substrate that holds agents to the same standard the team already holds itself.

​
Two Authoring Surfaces

Both take effect immediately — substrate-as-code is read fresh on every load, so there is no deploy step.

Edit the JSON directly

Write .substrate/boards/<id>.json by hand. Best when authoring a whole board at once or adapting an existing template.

Use the substrate-edit MCP tools

create_board, create_group, reorder_groups, create_policy, and the update_* / archive_* families. Each needs agent_name; updates need the current version. Best for incremental changes to a live board.

​
The Four Moves

1

Stages become groups

Each workflow stage maps to one group, ordered by position.
2

Per-item metadata becomes field_schema.task

Every distinct thing a work item tracks becomes a field — including a boolean gate field for each exit criterion you intend to enforce.
3

Rules become policies

Hard gates are transition_guard; conventions and reminders are agent_responsibility.
4

Prove the rails fire

A gate that never engages is worse than no gate. Validate every guard before relying on it.
The hard part is policies. A policy definition is free-form JSON, so the tool schema will not tell you the shape — and a definition the engine cannot read produces a gate that loads fine and silently never engages. Author against the DSL, then validate.

​
Start From the Worked Example

The bundled web-delivery template is a complete, working substrate: a Spec → Plan → Build → Review → QA → Done board with real gates, plus a substrate-template.json manifest that makes it a shareable template.
Reading its boards/delivery.json alongside these pages is the fastest way in. Adapting it beats authoring from scratch.

​
Tips

Keep ids stable and readable — for example, spec or gate-done. Policies and tasks reference them by id, so a rename is a migration.
Use enabled: false to keep a policy in the file as documentation without enforcing it. This is useful for gates you’re still designing.
Archive a stage you don’t use and drop its gate, rather than leaving both in place. A dead stage with a live gate produces confusing block messages.
Prefer extending a board over adding a new one. Two boards modelling one flow is how a substrate stops being a single source of truth.

Map a Process

Translate workflow stages and exit criteria into groups, fields, and gate fields.

Write Policies

The full policy DSL — transition guards and agent responsibilities.

Validate Gates

Prove your guards actually fire before you rely on them.

Publish a Template

Package your workflow for reuse and apply someone else’s.