> ## 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.
# Authoring a Substrate: Turn Your Process into Data
> How to turn an existing development workflow into Substrate boards, custom fields, and gates that hold agents to the same process.
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.
Write `.substrate/boards/.json` by hand. Best when authoring a whole board at once or adapting an existing template.
`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
Each workflow stage maps to one group, ordered by `position`.
Every distinct thing a work item tracks becomes a field — including a boolean gate field for each exit criterion you intend to enforce.
Hard gates are `transition_guard`; conventions and reminders are `agent_responsibility`.
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.
```sh theme={null}
substrate init --template web-delivery
```
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.
***
Translate workflow stages and exit criteria into groups, fields, and gate fields.
The full policy DSL — transition guards and agent responsibilities.
Prove your guards actually fire before you rely on them.
Package your workflow for reuse and apply someone else's.