Patterns (Do/Do Not)
Quick Answer
Use this guide for proven Breyta flow patterns and anti-patterns across bindings, templates, persistence, and orchestration.
Configuration flow
| Pattern | Why |
|---|---|
Declare :requires in the flow definition. | Makes runtime dependencies explicit and bindable. |
Configure required slots/inputs with flows configure. | Binds slots and activation inputs without code edits. |
Use flows release only for explicit rollout/governance. | Keeps authoring and rollout concerns separated. |
Use explicit run targeting only when needed (--target live, --installation-id). | Keeps default authoring runs simple and deterministic. |
Template usage
| Pattern | Why |
|---|---|
Put large payloads in :templates. | Reduces flow payload size and review noise. |
Reference with :template and :data. | Keeps step configs concise and reusable. |
Output sizing
| Pattern | Why |
|---|---|
| Estimate output size before adding data-producing steps. | Avoids late failures from size caps. |
| Keep inline outputs small and predictable. | Maintains stable orchestration payloads. |
Default to :persist for unknown/unbounded size. | Prevents inline overflow for exports/pagination/files. |
Pass refs downstream (:body-from-ref, :from-ref). | Avoids rebuilding large inline payloads repeatedly. |
Cross-flow handoff
| Pattern | Why |
|---|---|
Persist shared state to KV and read with :kv operations. | Supports structured handoff across runs/flows. |
| Use deterministic keys (workspace + period + shard/page). | Keeps retries idempotent and traceable. |
Use flow/call-flow only when child binding context is guaranteed. | Prevents profile-context runtime failures. |
Handle child :requires explicitly. | Missing profile context can fail with requires a flow profile, but no profile-id in context. |
Polling
| Pattern | Why |
|---|---|
Use flow/poll for external completion checks. | Provides bounded deterministic polling behavior. |
Set :timeout or :max-attempts. | Prevents unbounded polling loops. |
Use :return-on and :abort-on. | Makes success/fail conditions explicit. |
Prefer :backoff over manual interval math. | Centralizes retry interval control. |
Set :id for sleep step stability. | Improves trace/test consistency. |
Working copy vs release
| Command | Effect |
|---|---|
flows push | Creates/updates working copy and draft target. |
flows release | Publishes an immutable release and updates live install for the selected workspace by default. |
Do And Do Not
| Do | Do not |
|---|---|
| Keep flow body deterministic. | Hardcode secrets in steps. |
Use :function steps for transforms. | Use map/filter/reduce in flow body. |
| Include a manual trigger for discoverability. | Call nondeterministic functions in flow body. |
| Use connection slots for credentials. | Keep large/unpredictable payloads inline instead of :persist. |
Public reusable flows
| Pattern | Why |
|---|---|
| Name reusable/public flows around one clear query intent. | Stronger landing pages and easier discovery in search and AI-search tools. |
| Use outcome-first titles with the main integration when useful. | Helps users understand value quickly. |
Rewrite visible step :title labels into plain-language actions. | Improves public-page quality and operator readability. |
| Keep slug, title, description, and tags aligned around the same use case. | Prevents mixed search signals and thin page positioning. |