Breyta Docs
Docs
Build

Flow Naming

Quick Answer

Name public and reusable Breyta flows like pages that should satisfy a real query, not like internal implementation artifacts.

Good public flow naming should make a human think:

  • "Yes, this is what I was looking for"

And make search systems infer:

  • "This page directly answers the query and is about one clear use case"

When this matters most

Use this guidance for flows that are:

  • approved for reuse
  • user-facing
  • published to dedicated landing pages
  • likely to be discovered through Google, Perplexity, ChatGPT, Gemini, or other AI-search tools

For internal-only flows, operator readability still matters, but SEO/AEO pressure is lower.

Core rule

Do not name public flows like internal objects.

Prefer:

  • clear outcome
  • clear workflow, automation, or agent intent
  • clear integration or system when it narrows the use case

Avoid:

  • repo names unless they are part of actual search intent
  • implementation-heavy wording
  • vague labels like "processor", "handler", or "pipeline" when users search for "workflow", "automation", or "agent"

Optimize for query shapes, not formulas

Do not force a rigid pattern like:

  • Outcome workflow for integration

That is a useful drafting heuristic, not the final rule.

Real searches are usually shaped more like:

  • gmail ai support agent
  • github pull request automation
  • google drive folder sync workflow
  • meeting transcription workflow with assemblyai
  • stripe monthly mrr reporting automation
  • how to automate customer support emails in gmail

Your public naming should sound like a plausible search result, not a taxonomy label.

Choose one primary intent

Each public reusable flow should target one primary intent.

Typical intent buckets:

  • workflow
  • automation
  • agent
  • template
  • integration

Examples:

  • use agent when the flow behaves autonomously over time
  • use workflow when it is a repeatable process with multiple steps
  • use automation when the user mainly cares about the outcome being automated
  • use template when the searcher wants something reusable and ready-made
  • use integration when the cross-tool connection is the main reason to visit

Do not mix multiple primary intents in one title unless it reads naturally.

Field-by-field guidance

:name

Use a clear, rankable title.

Preferred ingredients:

  • outcome first
  • workflow, automation, or agent keyword when it matches intent
  • core integration or tool when it narrows the use case

Examples:

  • AI Support Agent for Gmail
  • GitHub Pull Request Automation with OpenAI and SSH
  • Google Drive Folder Sync Workflow
  • Meeting Transcription Workflow with AssemblyAI
  • Stripe Monthly MRR Reporting Automation

Avoid:

  • internal repo names
  • version suffixes unless needed
  • titles that only make sense to Breyta teammates

slug

Treat the slug as a search-facing URL, not an internal identifier.

Rules:

  • use lowercase hyphenated plain English
  • keep it short but descriptive
  • reflect the same primary intent as the title
  • avoid weak filler words

Good:

  • ai-support-agent-gmail
  • github-pull-request-automation-openai-ssh
  • google-drive-folder-sync-workflow
  • meeting-transcription-workflow-assemblyai

Weaker:

  • support-agent-llm
  • flows-api-codex-pr-agent
  • meet-assemblyai-transcribe

:description

Use one sentence, occasionally two.

It should answer:

  • what triggers it
  • what systems it uses
  • what outcome it produces

Good:

  • Automatically monitors a Gmail inbox, drafts AI replies, sends responses, and keeps support email moving without manual triage.
  • Runs Codex over SSH against a repository, applies code improvements, and creates a GitHub pull request with the result.

Avoid:

  • processes data
  • handles workflow logic
  • syncs things
  • wording that describes mechanics but not user outcome

tags

Tags should help discovery, reuse, and page clustering.

Include 4-8 terms from these buckets:

  • outcome
  • audience or use case
  • integration or tool
  • modality

Examples:

  • support, gmail, ai-agent, email-automation, customer-support
  • github, pull-request, code-automation, openai, ssh

Avoid:

  • only internal state tags like draft
  • generic words with no discovery value

Step titles for public flows

Even if the landing page is mostly metadata-driven, visible step names still shape perceived quality.

Use:

  • plain-language action titles
  • titles that reveal the job being done
  • verbs humans understand immediately

Prefer:

  • Check Gmail for support emails
  • Draft reply with AI
  • Create GitHub pull request
  • Start AssemblyAI transcription

Avoid:

  • normalize input
  • hydrate state
  • finalize result
  • prepare payload

If the internal step id must remain technical, improve the visible :title.

Human + AI-search test

Before finalizing a public flow name, ask:

  1. Would a human plausibly type this or click it?
  2. Would the first paragraph of the page clearly satisfy that query?
  3. Does the title sound like a result, not an internal object?
  4. Does the slug reinforce the same intent?
  5. Is the page targeting one strong long-tail query instead of several weak ones?

If any answer is no, rewrite.

Rewrite order

When renaming a reusable or public flow:

  1. Pick the primary query shape.
  2. Rewrite :name to match that shape.
  3. Rewrite the slug if the current slug is internal or weak.
  4. Rewrite :description around trigger + systems + outcome.
  5. Rewrite tags around outcome, use-case, and tool terms.
  6. Rewrite visible step titles to plain-language actions.

Quick examples

Weak:

  • support-agent-llm
  • Autonomous AI Support Agent for Gmail

Stronger if targeting practical long-tail:

  • AI Support Agent for Gmail
  • slug: ai-support-agent-gmail

Weak:

  • flows-api-codex-pr-agent
  • Autonomous flows-api Clojure improvement agent over SSH

Stronger if targeting outcome over repo internals:

  • GitHub Pull Request Automation with OpenAI and SSH
  • slug: github-pull-request-automation-openai-ssh

Weak:

  • meet-assemblyai-transcribe

Stronger:

  • Meeting Transcription Workflow with AssemblyAI
  • slug: meeting-transcription-workflow-assemblyai

Priority order when tradeoffs exist

For public reusable flows, optimize in this order:

  1. clarity of user outcome
  2. fit to likely query wording
  3. integration specificity
  4. operator readability in UI
  5. internal implementation fidelity

If internal precision and public clarity conflict, prefer public clarity in visible metadata.

Related

As of Mar 10, 2026