building-workflows
Build 3B workflows
Read references/interfaces.md when choosing or using an editing interface. Read references/testing.md before running a step or creating, updating, or running step tests.
Layout
README.md
<Step name>/
README.md
config.toml
Dockerfile
...
Within a workflow checkout, each top-level directory is a uniquely named step. Keep a README.md at the root and in every step. The UI already displays the workflow or step name, so do not repeat it as the opening heading.
The workflow README should explain its business purpose, triggers, flow, boundary inputs and outputs, external services, side effects, useful operational notes, and where to make common changes. A step README should identify its trigger and explain its behavior, non-obvious input and output shapes, external endpoints, and connectors. Link to workflow files with relative Markdown paths, wrapping paths containing spaces in angle brackets. Update a README when behavior or structure changes materially, but not for a behavior-preserving refactor.