Breyta Authoring Loop Reference

Load this reference before creating or editing a Breyta flow, changing bindings,
running release/install operations, or making non-trivial CLI decisions.

Progressive Flow Development Playbook

Develop in small, proven slices. Do not try to solve the whole workflow in one
large flow definition.

1. Reuse first: run the bounded search ladder, choose one nearby pattern,
   and record what you will reuse or ignore.
2. Contract first: define distribution, :requires, :invocations,
   :interfaces, output shape, side effects, and :concurrency before writing
   orchestration.
3. Small skeleton: push a minimal flow with one manual interface, one safe
   input, a small output, and no external side effects. Run it once.
4. One boundary at a time: add one connection, provider call, table, job,
   agent, or child flow at a time; push, configure-check, run, and inspect output
   before adding the next boundary.
5. Persist early: if a response, file, export, transcript, report, page
   set, or generated media may be large or reused, add :persist at the producing
   step and pass refs, not large inline bodies.
6. Escalate references only when touched: load outputs/tables docs for
   :persist, resource refs, viewers, or tables; reliability docs for paging,
   fanout, waits, retries, or checkpoints; provider docs for external API shape.
7. Installable mindset: keep author-only workspace ids, emails, secrets,
   resource ids, and private URLs out of source; expose setup/run choices through
   :requires, :invocations, and :interfaces.
8. Proof loop: verify the same interface/input/target a user will exercise,
   then inspect the rendered output or resource preview before calling it done.

Draft And Live Lifecycle

Use precise lifecycle language:

• draft is the staging/current workspace authoring state. Use it for source
  edits, configure checks, low-risk smoke tests, and iteration.
• live is the released/runtime state. A flow is unreleased until a version is
  released or activated and the live path is verified.
• End-user installs, public Discover behavior, scheduled/webhook/MCP operation,
  and long-lived production use are live-shaped concerns.
• Do not call a flow released, complete, public-ready, or end-user ready from
  draft evidence alone. Say "draft verified" when only draft was exercised.
• Before release, inspect draft-vs-live with breyta flows diff <slug>. After
  release or promotion, smoke-run the live/install-shaped path when side effects
  are safe.

Solution Surfaces

Use reusable definition surfaces deliberately, then compose them in :flow.
Inline small first-proof transforms; extract repeated, bulky, public-facing, or
tool-exposed logic before release.
Assume each new or edited flow may later become public unless the user
explicitly says it is internal-only. Public-ready authoring is an architecture
constraint, not approval to publish.

Default authoring order:

1. :requires

• declare connections, secrets, installer inputs, form inputs, and worker dependencies first
• model environment-specific values as author/installer/run inputs instead of hardcoding workspace ids, user ids, emails, test resource ids, private URLs, credentials, or one-off local assumptions
• in hosted UI chat, when the workspace is explicitly reported as fresh/empty, skip broad flow/connection inventory
• start with targeted connection inventory:
  • breyta connections list
  • breyta connections show <id> for the connection you plan to reuse
  • breyta connections test <id> only when you plan to bind or debug that connection
• reuse existing workspace connections before inventing new setup
• if no healthy third-party connection exists, hand off the Breyta setup/edit URL
  and do not ask for secrets in chat
• protected setup/edit links should return through login
• choose stable slot names around business capability (:github-api, :crm, :llm, :slack) rather than transient provider names
• if packaged :steps or :agents depend on a broad connection, narrow them here with flow-local permission hints before exposing them as tools

1. :templates

• move prompts, request bodies, SQL, notification content, and other large static text here
• avoid large inline strings inside :flow or heavy step configs
• keep public-facing copy in named templates when it is reused by prompts, notifications, output artifacts, or publish descriptions

1. :functions

• put shaping, normalization, projection, and deterministic transforms here
• prefer named reusable transforms over long inline SCI in orchestration

1. :steps

• package heavy built-in step configs behind a smaller input/output contract
• especially for :http, :db, :notify, :function, and other broad raw surfaces
• prefer publishing packaged :steps as tools instead of exposing raw heavy step surfaces to agents

1. :agents

• define reusable named agent configs here when the behavior is agent-shaped
• put objective, instructions, memory, cost/evaluate/trace, and tool/delegation config in the named agent definition
• use :tools {:steps [...] :agents [...]} to compose agent-to-step and agent-to-agent delegation

1. :flow

• wire steps together in deterministic orchestration; extract inline logic when reuse or review size justifies it
• keep :flow focused on sequencing, branching, waits, persistence, and summary

For agentic/reviewer/fixer flows, the default pattern should be:

• :files for code/resource state
• packaged :steps for heavy or externally scoped operations
• named :agents for reviewer/fixer/coordinator roles
• orchestration last

Anti-patterns:

• large raw prompts embedded directly in :agent, :llm, or :http steps
• repeated one-off normalization logic in :flow
• giant all-in-one flows when a packaged step, child flow, or staged draft
  iteration would isolate risk
• exposing raw broad built-in step surfaces directly to agents when a packaged step would be safer
• treating :flow as the place to define reusable behavior
• hardcoding author workspace state into a flow that an installer or public user may run later

Function And Data Shape Discipline

Most step outputs and inline returns are ordinary Clojure maps with keyword
keys. Do not add broad defensive parsing layers unless the documented output
shape is genuinely mixed or external.

• Prefer destructuring, get, get-in, select-keys, update, assoc, and
  cond-> over custom parser functions.
• Put reusable transforms in top-level :functions; call them with
  flow/step :function and a small :input map.
• Use json/parse, json/write-str, and breyta.sandbox/* helpers inside
  :function code instead of bespoke JSON/base64/hash/date parsing.
• If a value is already a parsed map from an HTTP :accept :json, table query,
  resource picker, or Breyta step result, access it directly; do not stringify
  and parse it again.
• Keep function outputs shaped for the next step: maps for structured data,
  vectors of row maps for tables, and resource refs for large artifacts.

Task Mode Router

Choose one primary mode before running commands. Load the compact skill plus
the reference files for the touched surface. Escalate only when the evidence is
incomplete.

Scoped Discovery

Use docs and command help as scoped tools, not a global preflight.

• Skill drift check: treat CLI missing-skill and stale-skill warnings as drift,
  not noise; install or refresh with the command in the warning before creating
  or materially editing flows
• when guidance, CLI behavior, or returned shapes disagree, run
  breyta skills status --provider all, then verify the command shape with
  breyta help <command...> and a narrow docs search
• search docs once per changed primitive before opening docs pages
• for agent parsing, prefer breyta docs find "<query>" --limit 5 --format json; use the default TSV output only for quick human scanning
• use breyta help <command...> only when command shape or flags are uncertain
• avoid broad help/docs sweeps when the bundled reference already gives the command shape
• do not repeat an identical docs/help/search command unless state or the question changed
• cache inspected docs hits, example snippets, resource reads, and run ids in session notes

Lookup patterns before inferring implementation details:

• primitive or surface name:
  • breyta docs find "files materialize"
  • breyta docs find "packaged steps"
• exact phrase when you know likely wording:
  • breyta docs find "\"draft setup\""
  • breyta docs find "\"tool permissions\""
• command path or operator surface:
  • breyta docs find "source:cli connections test"
  • breyta docs find "source:cli flows configure check"
• API/runtime side when CLI docs are thin:
  • breyta docs find "source:flows-api form requirements"
  • breyta docs find "source:flows-api agent definitions"
• error text or recovery text:
  • breyta docs find "\"Bad credentials\""
  • breyta docs find "\"missing api base url\""

If the first search misses:

1. search the primitive name
2. search the command name
3. search the exact error text
4. search with a source filter
5. only then infer a fallback

If command shape is the question, finish with breyta help <command...> instead
of guessing flags.

Primitive-First Example Reuse

Use breyta flows search to inspect actual workspace flow metadata before
creating or editing behavior. Use breyta flows grep for workspace source and
config literals. Use breyta flows templates search/grep for approved
reusable templates. None of these are the public installable catalog.

The goal is to understand the smallest working approved pattern before
inventing structure. For step-level edits, do not start by pulling a full
template. Start with metadata, primitive snippets when available, and only the
dependencies referenced by the matching snippet.

Reuse ladder:

1. For new flows, search nearby workspace flows first: breyta flows search "<integration or pattern>" --limit 5. For existing flows, pull or show the current flow first.
2. Search docs for the primitives or surfaces you will touch.
3. Search workspace source/config when metadata is insufficient: breyta flows grep "<literal>" --surface definition,tools --or "<variant>" --step-type <type> --tool-name <name> --limit 5.
4. Search approved templates: breyta flows templates search "<problem or integration query>" --limit 5.
5. Review name, description, tags, providers, tool names, connection slots, step types, step count, compact publish/steps previews, and flow_web_url.
6. Extract or inspect the matching primitive snippet when available.
7. Include only referenced dependencies: :requires, :templates, and :functions.
8. Pull or inspect one full template only when architecture-level reuse is needed.
9. For edits, compare only the touched surface against the closest local or approved example before changing structure.
10. If no useful example exists, say that explicitly and continue from docs.

Stop discovery once you have current flow state, one relevant local or approved
pattern, and docs for the primitives you will touch.

Existing Data And Template Playbook

Before writing a new flow from scratch, make the reuse/data path explicit:

1. Search nearby workspace metadata: breyta flows search "<workflow or integration>" --limit 5.
2. Search workspace source only for exact primitives or strings: breyta flows grep "<literal>" --surface definition,tools --limit 5.
3. Search approved reusable templates: breyta flows templates search "<problem or integration>" --limit 5.
4. Search template source when metadata is not enough: breyta flows templates grep "<literal>" --surface steps,tools --limit 5.
5. Search docs for the chosen surface: breyta docs find "<primitive or command>" --limit 5 --format json, then open one focused section with breyta docs show <slug> --section "<heading>".
6. If the flow should reuse existing reports, uploads, or prior run output, search resources with breyta resources search "<query>" --limit 5 and read only the best match with breyta resources read <resource-uri> --limit 5.

Use full template/source/resource output only when compact metadata cannot answer
the design question. Record the selected and rejected workspace/template/data
patterns in the final discovery proof.

Full template inspection is required only for:

• cross-step architecture reuse
• public install patterns
• multi-flow orchestration
• fanout or child-flow behavior
• unclear snippet dependencies
• copying overall flow structure

Final reports must include:

• approved example queries run
• chosen snippet or template, if any
• rejected snippets or templates when they looked close but were not used
• which structure was reused or intentionally ignored

Do not treat a template name alone as enough context. The agent must understand
the step types, setup/run field shape, bindings, output shape, and public copy
before copying the pattern.

Command Budget

• Authenticate once per session unless auth/workspace state changes.
• Do not repeat an identical command unless state changed.
• Use one docs search per changed primitive before opening docs pages.
• Use one full template inspection at most for a normal create/edit task.
• Read each resource URI once unless the resource changed.
• Run one final breyta flows diff <slug> before release.
• After two failed edit/run cycles, stop and re-plan before pushing another change.
• Do not run breyta connections test --all by default. Test only the connection you plan to bind or debug.

Workflow Quality Contract

Before editing, write a contract scaled to the task mode:

• inputs and outputs
• side effects and exactly-once requirements
• idempotency or dedupe strategy
• failure behavior, retries, and timeouts
• observability proof: result fields, counters, run ids, resources, or side-effect evidence
• user-facing output review path

For primitive/step edits, scope the contract to the changed primitive. For new
flows, release work, public installs, and cross-step changes, cover the full
flow.

Manual CLI Smoke Interfaces

For new flows that must be smoke-tested from the CLI, declare the run input
contract once under :invocations and expose the author run button as a manual
interface. A brand-new flow also needs an explicit :concurrency policy before
it will push successfully:

{:concurrency {:type :keyed
               :key-field :query
               :on-new-version :supersede}
 :invocations {:default {:inputs [{:name :query
                                   :type :text
                                   :required true}]}}
 :interfaces {:manual [{:id :run
                        :label "Run"
                        :invocation :default
                        :enabled true}]}}

Pass test data with breyta flows run <slug> --input '<json>' --wait, or call an
authored HTTP interface with breyta flows interfaces call <slug> <interface-id> --input '<json>' --wait.

Old manual field shapes are still accepted so existing flows keep running, but
do not use that path in new source or new docs. Move run fields to
:invocations and expose the launch surface with :interfaces :manual.

For the enabled manual interface, breyta flows run <slug> --input '<json>' --wait
can use the default. Flow source may declare at most one manual interface; model
alternate manual paths as invocation inputs such as mode. Pass
--interface-id <id> only when you need to select that declared interface
explicitly. Keep --trigger-id for legacy compatibility only.

Real Payloads Early

When integrating webhooks, PR events, provider callbacks, or notification
flows, shape the first useful test from a real payload where possible. Use the
provider event body, gh pr view --json ..., a captured webhook request, or the
exact email/notification payload the flow will submit. Synthetic inputs are
useful for unit isolation, but they should not be the only proof before release.

Parent/Child Flow Grouping

When a flow calls child flows with flow/call-flow, :fanout child workflow
items, or a similar orchestration pattern, group the related flows so users can
see the relationship in Breyta.

Grouping is display/workspace metadata. It does not create the runtime
parent/child relationship and it does not round-trip through flows pull /
flows push. Runtime linkage still belongs in the parent flow body.

Use the same group metadata across related flows:

breyta flows update parent-flow \
  --group-key support-agent-suite \
  --group-name "Support Agent Suite" \
  --group-description "Parent and child flows for support automation" \
  --group-order 10

breyta flows update child-flow \
  --group-key support-agent-suite \
  --group-name "Support Agent Suite" \
  --group-order 20

Use spaced --group-order values such as 10, 20, and 30 so future child
flows can be inserted. Verify with:

breyta flows show parent-flow

Look for groupKey, groupName, groupOrder, and ordered groupFlows.

Canonical Execution Loop

1. Understand the contract:

• interface mode, integrations, expected output, and failure policy

1. Bootstrap from existing artifacts and connections:

• inventory the connections the flow needs before editing behavior, except in clearly empty hosted workspaces
• test only the connection you plan to bind or debug
• decide which business capabilities become :requires slots
• decide which existing workspace connections should satisfy those slots
• if a flow exposes packaged :steps or :agents as tools, decide whether reused connections need flow-local scope limits
• prefer existing flow file first:
  • breyta flows pull <slug> --out ./tmp/flows/<slug>.clj
• before changing structure, follow the discovery order:
  • current state
  • docs search
  • approved example metadata
  • primitive snippet
  • referenced dependencies
  • full template only if needed
  • compare
  • edit
  • draft proof
  • live/install proof

1. Working copy iteration:

• build :requires early, prove small slices, then extract repeated or bulky logic into :templates, :functions, packaged :steps, and :agents
• breyta flows push --file ./tmp/flows/<slug>.clj
• breyta flows configure <slug> ... when required
• breyta flows configure check <slug>
• if the flow belongs to a grouped sequence of dependent flows, set explicit order with breyta flows update <slug> --group-order <n>
• re-check grouping after metadata changes with breyta flows show <slug> so groupFlows and ordering metadata are visible
• live target updates after slot changes: use --target live --version <n|latest> and --from-draft when promoting draft setup
• optional read-only verification: breyta flows validate <slug>

1. Run and verify:

• canonical run: breyta flows run <slug> --input '<json>' --wait
• installation-targeted run when required: breyta flows run <slug> --installation-id <installation-id> --wait
• run with the same interface/input shape, target, bindings, and side-effect path that production will use
• for changed primitives, isolate the primitive first, then run the full flow end-to-end
• inspect run: breyta runs show <workflow-id>
• open or report webUrl and outputWebUrl when present
• inspect persisted artifacts with breyta resources search "<query>" --limit 5, breyta resources list --limit 10, and breyta resources workflow list <workflow-id> --limit 10
• inspect side effects directly: sent email payloads, created rows, updated records, external API responses, or callback/webhook delivery results
• for public/end-user work, do not say "ready for UI" from draft proof alone; verify the live/install-shaped path or state web UI not verified in the risk ledger

1. Advanced rollout only when needed:

• breyta flows diff <slug>
• breyta flows release <slug> --release-note-file ./release-note.md
• breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md
• breyta flows promote <slug>
• breyta flows installations configure <installation-id> --input '{...}'

Install Operations

Use these for end-user/runtime setup:

• breyta flows installations list <flow-slug>
• breyta flows installations get <installation-id>
• breyta flows installations interfaces <installation-id>
• breyta flows installations upload <installation-id> --file ./a.pdf for webhook-interface file ingress

Legacy webhook/upload flows can still run through the compatibility path, but new
callable ingress should use :interfaces and the installations interfaces
command.

Rollback

Capture pre-change state:

• breyta flows show <slug>
• breyta flows show <slug> --include versions

Rollback path:

• breyta flows promote <slug> --version <last-known-good>
• re-run representative verification and record evidence

Feedback Path

Use breyta feedback send for product issues, platform bugs, confusing errors,
missing docs or commands, and missing capabilities. Tell the user when feedback
is worth sending. These reports go directly to the Breyta team.