Workflows overview

A workflow is a reusable automation recipe written in YAML: a list of steps that an agent runs in order. Workflows are the building blocks of Kadmo. A playbook chains several of them into a gated, multi-step mission, an automation starts them when something happens in a tracker, and the task pool feeds them tickets. This page explains what a workflow is, where it lives, how you edit it in the app, and where it runs.

Agent workflows and playbooks

This page covers the workflow itself. For how workflows hand whole missions to agents and chain into playbooks with verdict gates, see Orchestrating agents.

What a workflow is

A workflow has an id, a title and a list of steps. Each step has a type that tells the agent what to do: open a page, click, run a shell command, ask an LLM, branch, call another workflow, read a ticket, open a pull request.

id: page_title
title: "Read a page title"
params:
  site_url: string
steps:
  - type: browser.navigate
    url: "{{site_url}}"
  - type: browser.extract
    selector: "h1"
    as: heading

Workflows come in two kinds, written in the same YAML:

Kind	What it does	How you recognise it
Step workflow	The agent runtime runs every step itself: browser, shell, LLM, data, issue and git steps. Same input, same steps, every time.	Ordinary steps only
Agent workflow	Opens a terminal on the agent and starts the agent's AI coding app with a mission prompt; the app does the work and reports back on the ticket. Playbooks are built from these.	metadata.agent: true and usually a metadata.role

The full syntax is in the DSL reference; how data flows between steps is in Variables.

Where workflows come from

Every workflow in the app comes from a skill pack. The Workflows page shows where each one comes from in its Source column:

Source	Meaning
Default	Shipped by Kadmo in the Kadmo Default Pack. Read-only as a file; editing one copies it into your account pack.
Account	Defined in your account's own skill pack repository.
Override	Your account's edited copy of a default workflow. It masks the default from then on.
Custom	A workflow saved in the app's database that no pack file backs. It cannot be edited as YAML.

Your account pack is a git repository. The app syncs it every 5 minutes, and agents refresh their own copy within about 5 minutes of a change. See Skill packs for how packs are structured and connected.

The Workflows page

Open Settings → Library → Workflows (app.kadmo.ai/workflows). The page lists every workflow your account can run, with a filter bar:

• Search workflows by name or description…
• a role filter (All roles), a source filter (All sources: Default, Account, Override, Custom) and a status filter (All statuses: Enabled, Disabled)
• Clear resets the filters

Each row shows the workflow, its version chip (v3), its Effort tier and Agentic app defaults (Auto unless set), its Source and when it was Updated, plus icons to view the file, edit the YAML and open the repository. A row marked with a role that no agent on the account can run says so (not a role here), so you know a run would wait for nothing.

Who can run this → in the header opens Capabilities → Workflows, which shows, per workflow, which agents in a workspace may run it and has the Run now button.

The workflow detail page

Click a workflow to open its page. It shows:

• the title, an Enabled / Disabled switch, the workflow id, the current version and pack commit, the step count and dates
• Steps: each step in order
• Recent Jobs: the last 10 runs with their status, linked to the job page
• Source: the repository, file path, branch and domain, with View file, Edit YAML and Repo
• Change log: the git history of the file
• Versions: the app's own revision history (see Versions)

Add a workflow

1. On the Workflows page, click Add workflow.
2. Pick a Domain: one of the domains registered in your account pack. If there are none, the dialog says to add one under Skills → Add domain first.
3. Enter a Workflow id: lowercase letters, digits, _ or -. It becomes the file name and the name you dispatch it by.
4. Enter a Title, and optionally a Role and a Commit message.
5. Click Create. Kadmo commits an empty-steps stub to your pack repository as you. Fill in the steps with Edit YAML once it appears.

Add workflow is disabled, with the reason on hover, when:

Reason shown	Fix
No git-backed skill pack is attached — connect one in Settings to edit files here.	Connect a skill pack repository in Settings.
Editing pack files needs an account admin role.	Ask an account admin to make the change.
Your 14-day trial has ended. Upgrade to keep editing your pack.	Upgrade the account.

The YAML editor

Edit YAML (on a row or the detail page) opens the workflow's file in an editor in the app. A save becomes a commit to your account pack; a save of a default workflow creates your account's override of it.

The editor checks the YAML as you type, with the same rules the agent's engine applies. The header shows either YAML valid · 3 steps · role: qa or the number of errors, and Save & commit stays off until every error is fixed. Each error is listed with its line, column and step path, for example:

line 9:15 · steps.2.then.0.type · unknown step type "browser.clik" — did you mean "browser.click"?

Click an error to jump to its line. Add an optional Commit message, then Save & commit.

What happens after a save depends on how your account pack is set up:

• Direct commits: Committed abc1234 — pipelines re-synced; library updated now, agents refresh within ~5 min.
• Pull requests: Opened a pull request for … — merge it to publish, then agents refresh within ~5 min. The workflow does not change until someone merges the pull request.

If the file changed in the repository since you opened it, the editor says This file changed upstream since you opened it. Saving now would overwrite it. Click Load upstream version to start again from the current file.

The check

One check decides whether a workflow is valid. The app and the agent's engine share it, so a workflow the app accepts is one an agent can run. It verifies that:

1. the text parses as YAML, into a mapping;
2. id and title are non-empty strings, and steps is a list;
3. every step is a mapping with a type the engine runs, including the nested steps of control.if (then, else_steps), control.retry and control.foreach (steps).

It reports every error at once, not just the first. The check runs in the editor as you type, on every save from the app, the Kadmo MCP server or Ask, and on every pack sync. A save that fails it is refused and nothing is committed.

Error	Fix
YAML does not parse: …	Fix the YAML syntax at the line shown (indentation, quotes, a stray tab).
workflow YAML must be a mapping with id, title and steps	The file is a list or a plain value; make it a mapping.
id is required / title is required	Add the key.
steps must be an array	Make steps a list (- type: …).
step must be a mapping with a "type" / step is missing a string "type"	Give the step a type: key.
unknown step type "…"	Fix the spelling; the message suggests the nearest type when one is close.
step type "chat.…" is not supported in this build: …	Chat steps are not available yet; remove the step.

When a pack sync brings in a broken file, Kadmo does not drop the workflow. It stays listed, marked Invalid YAML · vN still runs, with the errors, and the app keeps dispatching its last good version until the file is fixed. Open in editor on that banner takes you straight to the fix.

Versions

Every content change makes a new version: a save in the app, a save over MCP or in Ask, or a pack sync that changed the file. Each version records its number, the content hash, the pack commit and who made it. The detail page lists them under Versions with how each arrived (saved, pack sync or merged).

The version shows wherever the workflow does: on the list row, the detail page, the editor (editing v4) and the run dialog. Every job records the version it ran, so you can always tell which YAML produced a result.

Where workflows run

Workflows always run on an agent: a cloud or self-hosted machine with a browser, a terminal and the agent runtime. The app never runs steps itself; it queues a job, and an agent that may run the workflow's role claims it. See Agents.

You start a workflow in one of these ways:

From	How
Capabilities → Workflows	Run a workflow, or Run now on a row
Jobs page	Run Job
Agent Fleet	Run Job on an agent's card
A playbook	Each playbook step runs a workflow; see Playbooks
An automation	A tracker event or a schedule; see Automations
An AI client	The Kadmo MCP server's run tools; see MCP

The run dialog asks for the workflow's inputs, the agent (Run on agent), the Workspace, and optionally an Effort tier and Agentic app (both Auto by default, which uses the workflow's defaults). For an agent workflow it previews the Composed prompt the agent will receive. Click Run to queue the job; follow it on the Jobs page.

Step types

The engine knows 46 step types: 43 run today, and 3 chat steps are reserved and refused by the check until a chat provider is available.

Family	Count	Step types
Browser	18	browser.navigate, click, type, scroll, extract, extractAll, extractMap, wait, exists, hover, key, snapshot, screenshot, injectCSS, injectJS, select_option, scrollIntoView, fill
Shell and terminal	3	shell.run, terminal.open, terminal.run
LLM	3	llm.classify, llm.generate, llm.decide
Control flow	4	control.if, control.retry, control.foreach, control.stop
Workflow	1	workflow.call
Data	3	data.first, data.get, variable.set
Issues	6	issues.create, issues.get, issues.search, issues.attach, issues.transition, issues.comment
Git	5	git.listPRs, git.getPR, git.createPR, git.listIssues, git.getIssue
Chat (not yet available)	3	chat.listChannels, chat.readChannel, chat.readThread

Every step and its parameters are in the step types reference.

Next steps

• DSL reference: the complete YAML syntax
• Step types: every step and its parameters
• Variables: passing data between steps
• Examples: workflows to copy
• Orchestrating agents: agent workflows, playbooks and gates
• Playbooks and Tasks: running workflows on tickets