# Workflows

> Workflows: subagents work in phases with checks and a result. How to ask the agent, follow a run, save it and run it again with arguments.

A **workflow** is a script by which several subagents do the work in phases: for example, two
reviewers look at a file, each with its own task, and a third merges their findings into a result. The agent writes and edits the workflow
— it is enough for you to describe in words what you need. The workflow runs in the background, you follow
the phases, and the result arrives in the session.

When a workflow is more useful than an ordinary request:

- the work can be split into independent parts, and they are worth doing in parallel;
- you need a view from several angles — different reviewers with different tasks;
- the result is checked by code: tests, a command, a comparison — not only by the agent’s words;
- you will repeat the same work with other inputs.

## How to ask

Describe in the chat who does what and what should come out:

```text
Make a workflow: two reviewers look at src/cart.js, each with its own task (one — errors
in calculations, the other — readability), a third merges their findings into a short result. Run it.
```

The agent writes the script, checks it before running (result types, phases, commands) and runs it.
While the run is in progress, the session shows a background work line, and the workflow’s agents ask
for permission like an ordinary subagent — marked “from a subagent”.

When the run ends, the agent gets the result and tells you what was found. The workflow’s result
(for example, a review summary) is saved as an artifact of the run.

## The “Workflows” screen

_Illustration: A saved workflow: what it does, when to use it, arguments — and “Run”._

- **Saved** — workflows you can run again. The card has the name, what it
  does, when to use it, and the arguments. **“Run”** asks for the argument values,
  **“More details”** — the description and arguments for editing.
- **Runs** — all runs: state, time, tokens, affected files and lines, where it was started from.
  **“Run progress”** opens the details:
  - the phases in order and the agents in each — with state, time and tokens;
  - artifacts — for example, “Review result” marked “Main result”, with a version;
  - “Open session” and “Fix in chat” — go back to the agent so it fixes the workflow.

_Illustration: Run progress: two phases, three agents, each one’s usage and the final artifact._

## Save and run again

If a workflow turned out well, say “save it”. The agent does not save on its own — it proposes
and waits for your agreement; you confirm the save.

```text
Save the workflow with arguments: the file path and two review focuses.
```

- **Arguments** — what changes from run to run: a file path, a branch, a review focus. An
  argument can have a default value and a “required” mark.
- **Name** — what the workflow is called on the screen. The file name is in Latin letters, the name is in
  your language; you can edit the name and description under “More details”.
- Saved workflows live with you, not in the repository: `~/.config/buff/workflows/`.

You can run a saved workflow from the “Workflows” screen or by asking the agent: “run the file
review for src/checkout.js”.

## Worth knowing

- A workflow’s agents are subagents: they see the project but not the main session’s conversation. The workflow
  passes everything they need in the assignment.
- A run with an error in the script does not start: the agent gets a description of the error with a line number and
  fixes the workflow.
- A workflow’s usage is charged to the organisation’s plan, like any turn; in the workspace it is visible in the session’s
  records.

## In the console

_Illustration: /workflows in the console._

`/workflows` — saved workflows with a run action, and runs with their state and usage. You can ask
the agent to make and save a workflow the same way as in the window.