name: breyta
description: >-
Use Breyta CLI for Breyta flows: create, edit, debug, run, validate, release,
install, publish public/Discover/marketplace flows, search approved templates,
inspect docs/bindings/tables/fanout/outputs/provider APIs/models, and report full
Breyta URLs.

Purpose

Use this skill for meaningful Breyta flow work. Keep this file as the router:
pick the task mode, load the smallest playbook/reference, run bounded commands,
and report proof with exact Breyta URLs.

Flow DSL Mental Model

A Breyta flow source file is orchestration DSL, not a general Clojure app.
Declare contracts early, compose bounded flow/step calls, inline small
first-proof transforms, and extract repeated or bulky pieces before release.
Keep side effects at step boundaries and persist large data as resource refs.

If the task is to import or migrate an n8n workflow JSON, use
breyta flows import n8n <workflow.json> first. Do not hand-write the initial
EDN conversion unless the CLI importer is unavailable or the user explicitly
asks for a manual conversion.

Start Of Session

1. If the CLI warns that this installed skill is stale, follow the shown
   breyta skills install ... or breyta skills status ... command before
   material flow edits. If CLI behavior and this guidance disagree, trust
   breyta help <command...> plus a narrow docs search.
2. Keep a tiny session capsule: task mode, workspace/flow, target/interface,
   refs consulted, chosen pattern, next proof command, known risks.
3. Use breyta help <command...> only when command shape is uncertain. Use
   breyta docs fields <step> [field...] for step config rows and
   breyta docs find "<query>" --limit 5 --format json for broader primitives.

Task Mode Router

Pick one primary mode before discovery. Escalate only when evidence is incomplete.

Playbook Matrix

Read one playbook by default:

• playbooks/author-flows.md: templates, existing data, interfaces, lint/push,
  single-step development, resource refs, installable source shape.
• playbooks/debug-and-verify.md: failed runs, UI mismatch, readback, side
  effects, feedback reports.
• playbooks/release-and-install.md: draft/live, release/promote, live target
  configuration, install-shaped proof.
• playbooks/public-and-marketplace.md: Discover, marketplace, public copy,
  paid/public surfaces, author approval.
• playbooks/advanced-reliability.md: fanout, paging loops, concurrency,
  checkpoints, large artifacts.

For complex flows, start with authoring and phase-load only the surface touched
next: provider/API, advanced reliability, outputs/tables, then release/public.

Load references only for exact field/step/schema truth:

• references/runtime-data-shapes.md
• references/outputs-and-tables.md
• references/provider-api-freshness.md
• references/reliability-and-concurrency.md

Default Command Budget

• Start with compact search/list defaults and --limit 5.
• Treat search like rg: keep hit refs, matched fields/surfaces,
  use grep --surface when noisy, and open one focused target at a time.
• Cache inspected flows, docs hits, template hits, refs, and workflow ids.
• Do not repeat identical search/help/docs commands unless state or the question
  changed.
• Use docs fields for step keys; otherwise one docs search before full docs.
• Inspect at most one full template for normal create/edit work.
• Read each resource URI once unless it changed.
• After two failed edit/run cycles, stop and re-plan.

Authoring Defaults

• Build small draft slices: contract, one manual interface, one meaningful
  boundary, lint, push, configure check, run, read output.
• New callable flows should use :interfaces and :invocations. Declare at
  most one manual interface; use invocation inputs for manual mode choices. Use
  --interface-id <id> only when selecting the declared manual interface
  explicitly. Treat --trigger-id as legacy compatibility.
• Run breyta flows lint --file ./flows/<slug>.clj before push when editing a
  local source file. Use --local-only for fast offline checks or --server
  when canonical pre-push checks are required.
• breyta flows validate <slug> checks stored draft/live state after push; it is
  not a substitute for runtime proof.
• Use breyta flows readiness <slug> before release passes to see definition,
  configuration, public/discover/marketplace, pricing, installability, blockers,
  and next commands in one compact report.
• Use breyta steps run --flow <slug> --source draft ... to isolate one
  draft-context primitive before rerunning the whole flow. Use inline --params
  for small maps, --params-file for larger inputs, compact resultPreview
  first, --result-path / preview limits for focused expansion, --result-file
  for full local capture, and --full only when necessary.
• Persist unknown/large payloads with :persist; pass refs and hydrate with
  :load only where needed. Use :tier :ephemeral for temporary HTTP blobs.
• Keep function steps map-oriented. Prefer map access, json/parse,
  json/write-str, and breyta.sandbox/* helpers.
• For third-party APIs/databases/OAuth/LLMs, check connections before building.
  If none fits, hand off a Breyta setup/connection URL.
• Never ask users to paste secrets in chat.

Lifecycle And Approval Boundaries

• Draft is staging/current workspace authoring. Live is released/runtime.
• Say draft verified when only draft was exercised.
• Use breyta flows release-check <slug> --public --marketplace for public paid
  release gates before changing visibility or telling a user the flow is ready.
• Do not call public/end-user work ready from draft proof alone; verify
  live/install-shaped behavior or state web UI not verified.
• Ask for concrete missing config; do not invent connections, secrets,
  installation inputs, private URLs, workspace ids, or user ids.
• Public visibility, marketplace visibility, paid-flow settings, release, and
  promotion require explicit author approval.
• For new source-authored paid apps, use
  :marketplace {:app {... :monetization {:plans [...]}}}. Preserve legacy
  :marketplace {:monetization ...} only for existing listings.

Proof Contract

Final reports should include:

1. Problem contract: interface, inputs, outputs, integrations, failure behavior.
2. Discovery proof: docs searched, template/workspace/resource searches,
   selected and rejected patterns.
3. Flow delta: slug, files, steps, bindings, config, lifecycle target.
4. Runtime proof: commands, workflow ids, target/version/install path, output or
   resource readback, side effects, full Breyta URLs.
5. Risk ledger: unverified surfaces, especially UI/install/public output gaps.
   Include significant authoring friction: excessive trial/error, misleading
   docs/help, unclear CLI/API behavior, or missing examples.

Output Guidance

• Public/end-user flow outputs should default to one readable Markdown artifact, or a deliberate table/media viewer when that is better for the user.
• The default rich output pattern is a Markdown report. If the report needs real Breyta resources, use fenced breyta-resource blocks to embed table snapshots, charts, downloads, images, video, nested Markdown, text, or JSON in document order.
• Keep raw debug maps, internal ids, res:// refs, and implementation-only fields
  out of final public output unless the user explicitly asked for them.
• Verify table resources with breyta resources read <table-uri>; workflow resource
  lists alone are not enough.
• For large artifacts, report resource refs, signed URLs, and short previews instead
  of pasting full table/resource content.
• Persist long Markdown reports or JSON bodies as blobs/resources and store refs plus
  short summaries in tables.

Definition Of Done

1. Working copy validates for intended flow changes.
2. At least one representative flows run succeeds for the default target.
3. At least one representative run reaches expected terminal status.
4. Required side effects/output are confirmed, not inferred.
5. Public/end-user output is a presentation surface, not a raw debug payload.
6. Returned artifacts are inspected and reviewed from the perspective of the intended user/audience.
7. Image artifacts are reviewed with vision analysis; video artifacts are sampled with screenshots and reviewed with vision analysis when tooling is available.
8. Table resources, when used, are read back with breyta resources read <table-uri>.
9. For public/end-user flows, live/install-shaped behavior is verified or the risk ledger says web UI not verified / install path not verified.
10. Report includes docs searched, template queries, chosen/rejected templates, target/version proof, evidence, full Breyta URLs, and unresolved risks.

Failure Triage

1. Command uncertainty: breyta help <command...>.
2. Primitive uncertainty: breyta docs find "<primitive or error>" --limit 5 --format json.
3. Config mismatch: auth, workspace, target, version, installation, required slots.
4. Runtime mismatch: start with breyta runs events <workflow-id> --limit 100;
   add --step <step-id> for one step or --installation-id <id> for an
   installed-profile run. Inspect one step with
   breyta runs step <workflow-id> <step-id> or
   breyta runs inspect <workflow-id> --step <step-id>, using --full only
   when captured output/error payloads are required. Isolate the primitive, then
   rerun the intended interface. For waits, approve deliberately with
   breyta runs continue <workflow-id> --approve-latest-wait.
5. Authoring friction or platform gap: breyta feedback send with full URLs,
   workflow ids, target, interface id, output/resource refs, commands tried,
   and why the loop was confusing or wasteful.