Breyta CLI Skill

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.

When a hosted proactive system turn supplies a proactiveMessageId, preserve
that exact id. Finish read-only triage with breyta agent work classify and
finish an approved or automatic continuation slice with
breyta agent work status. Never infer approval from reply wording. The
--continue-unfinished-work preference applies only to already-approved
unfinished work; new initiatives always wait for explicit user approval.

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/public-app-pricing.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

• Before creating a persistent table in an existing workspace, load
  references/outputs-and-tables.md, inventory related tables, and trace each
  candidate's grain, key, writers, and consumers. Designate one canonical
  logical current-state table or partitioned family per durable entity and
  extend or migrate it by default. Do not create a flow- or campaign-specific
  copy of the same entity merely for convenience.
• Build small draft slices: contract, one manual interface, one meaningful
  boundary, lint, push, configure check, run, read output.
• Build one step at a time: after each new or changed step, run just that
  step and read its actual output before writing the next one. Use
  breyta flows steps run <slug> <step-id> --params '<json>' for packaged
  steps in the local source (request timeout defaults to 15 minutes; use
  --timeout for slower work), breyta steps run --type <type> --id <id> --params '<json>' for inline activity steps, or
  breyta steps run --flow <slug> --source draft ... against a pushed
  draft; prove :sleep, :wait, :fanout, and control-plane steps with a
  minimal flow run instead. Do not write five steps and then debug the
  composite.
• Use breyta flows run-step <slug> <step-id> --target draft --input '{...}' --wait as the canonical probe for named inline function/code steps
  and LLM steps that rely on draft-bound connection slots. Pass the invocation's
  root input shape. Reserve flows steps run for qualified top-level packaged
  :steps; steps run --flow is a lower-level primitive/config probe.
• When the intent is a public app (installable, Discover, or marketplace),
  design the end-user setup screen before the flow: at most one connection
  card per provider account and origin plus at most one required text field,
  then derive the flow from that screen. Load
  playbooks/public-and-marketplace.md and references/public-flows.md
  before writing source.
• 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. Local lint is offline and also reports missing qualified
  packaged-step references. Use --local-only for fast checks or --server
  when canonical pre-push checks are required; add --timeout <duration> when
  server lint needs more than the default 30 seconds.
• For a new flow, start with breyta flows init <slug>; repeat
  --input 'name:type[:required|optional[:label]]' to seed invocation inputs.
  It creates the canonical local source with a manual run interface (no-input
  only when --input is omitted) and empty :schedules. For an existing flow,
  use breyta flows pull <slug>.
• Use breyta flows steps create/update/remove to edit only the top-level
  packaged-step vector; removal is rejected while the local :flow references
  the step. Use breyta flows schedules add/update/remove to edit only the
  top-level :schedules vector, using --schedule-file for complete-map
  replacement when advanced fields are present. Use breyta flows compose to
  edit only the quoted :flow body. Use breyta flows steps run <slug> <step-id> ... to execute a packaged step from the complete local literal
  without persisting a draft. Its --timeout flag also applies to the --run
  modes of flows init and flows steps create/update. Push explicitly with breyta flows push;
  command-level --push flags are opt-in convenience, not implicit remote
  writes. Local lint also reports missing qualified packaged-step references;
  server lint/push remains canonical.
• 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.
• For file/document transformation workflows, follow the
  uploaded-file-to-downloadable-artifact paved path: declare :file or
  :resource inputs, keep uploaded files as resource refs, persist generated
  artifacts with :persist {:type :blob ...}, return Markdown with a
  breyta-resource :view :download embed, and prove the manual path with
  breyta flows run --upload.
• 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.
• For app requests, show a visible reuse checklist before editing source,
  duplicating a template, or asking for direct provider credentials. Include:
  needed outputs/functions; Discover searches tried; relevant paid apps found;
  and selected/rejected paid apps with reasons.
• Search Discover public and paid installable apps by requested outcome,
  business function, and output modality before building from scratch. For
  multimodal apps, check every needed function separately, including
  text-generation apps, image-generation apps, video-generation apps, and any
  relevant paid app. For an agent that creates ads, example searches include
  ad generator, copywriting, text-generation,
  OpenAI image generation, image-generation, and social ad creative.
• To evaluate one Discover hit in depth, use
  breyta flows discover show <workspace-id>/<flow-slug> (full public
  listing: publish copy, pricing, connections, versions) or open the hit's
  public_app_url. Do not run breyta flows show against another
  workspace's flow; that requires membership in the owning workspace and
  fails with access denied.
• Treat every non-placeholder <slot>.secret configuration value as an
  intentional plaintext create or replacement under the slot's workspace
  secret ref. The documented :generate sentinel requests server-side
  generation. Never pass a secret ID or :secret-ref name as the value to
  reuse it. Omit the secret field only to preserve an already-bound target
  value; omission does not bind an unconfigured draft target. Then run flows configure check and a provider-specific, read-only smoke test.
• For installable apps, keep shared platform credentials
  :provided-by :author and each customer's account or OAuth connection
  :provided-by :installer. Verify a fresh installation does not expose the
  author-owned secret.
• 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,
   visible reuse checklist, Discover searches tried, relevant paid apps found,
   and selected/rejected paid apps or patterns with reasons.
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, install-shaped behavior passed the install test matrix in playbooks/release-and-install.md (minimal-config install, plus per declared surface: optional integrations absent and broken, explicit-false toggles, malformed constrained text), 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;
   for an installed-profile run, add --installation-id <id>; add
   --step <step-id> for one step. 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.