Playbooks

Write the plain-language procedure a workflow follows, reference task board fields and connected apps in it, and keep it in sync with the recording.

A playbook is a written, step-by-step description of what a workflow does and why. Where a recording captures the mechanics, a playbook captures the intent: the document you would hand a new teammate so they could finish the task without watching you do it.

Playbooks are also what Arro reads when it runs a workflow. They are the source of truth for what the agent should do, including the judgment calls, like which task to skip and what to do if a page loads slowly.

Playbooks work on every plan. The Free plan allows one playbook per workflow, created with the workflow, and a second is refused with a plan limit message. See Plan limits.

Where to find it

Open a workflow and click the Playbooks tab. If the workflow has none yet, click Create playbook to start fresh, or Generate from recording to have the agent draft one.

You write in a rich-text editor with headings, lists, and code blocks. A workflow can keep several playbooks as tabs, which suits one workflow handling several variations of the same task. Anyone with edit access to the workflow can edit its playbook.

The default playbook takes the workflow’s name. A new playbook starts with its name as the first heading and a blank paragraph below.

When an editable page or playbook opens, the cursor starts beneath the title, ready for you to type.

In pages and playbooks, clicks in the editor margins place your cursor beside the nearest text.

Where you click	Cursor position
Beside a line	Start or end of that line
Below the content	End of the last block

Generate from a recording

1. Open the workflow's Playbooks tab

   Look for the Generate playbook from recording prompt at the top.

2. Click Generate

   The agent reads the captured events and produces a written walkthrough, usually within a few seconds.

3. Review and edit

   Treat the draft as a starting point. Tighten the language, add domain context, and remove noise.

Reference data in a playbook

Type @ anywhere in the editor to open the mention picker.

Mention	What it references	What it does
Plugins	Any app in the catalog	Declares the workflow depends on it
Fields	Any field on an attached task board	Names an input the procedure needs

Field mentions let you write instructions like “open the URL in @Link” without hard-coding values. A task worker receives its assigned task’s values. A manual run asks you for missing inputs without selecting a task. Mentions render as pills and stay valid as long as the underlying field is attached.

If a field is removed, or its task board is detached, the pill shows a missing-state warning and the agent refuses to save further edits until you fix or remove every broken reference.

Type [[ to link to a page. A policy or a definition then lives once, in knowledge base, and every playbook that needs it links there instead of restating it. A link to a page that exists follows it through a rename and appears in that page’s Linked from list; a link to a page nobody has written yet never blocks saving, and lights up when someone writes it. An agent running the workflow opens the linked pages as it works.

There is no mention for a task board itself. Attach task boards on the workflow’s Data tab. For queued work, describe what to do with one task. The task board’s pick-up list determines which tasks receive workers. See running many tasks at once for starting the queue.

Plugin mentions declare what a workflow needs

You can mention a plugin before installing it. Double-click its mention to install it and complete any required connection setup. Authorization opens separately, keeping the playbook open. An already-connected mention opens the plugin’s page.

The workflow’s plugin strip shows what your account needs before the run can start. Each plugin must be installed, enabled and connected. Routine renewal happens automatically, but a connection marked for reconnection blocks the run.

Mention the app itself, not an individual action. There is no mention for a specific tool like “send a Slack message”. Describe the action in the step and let the agent pick the right tool at run time.

Keep a playbook in sync with the recording

When you update a workflow’s recording, the playbook can drift. Use Update from latest recording in the playbook header to have the agent reconcile the two.

Do not try to keep the playbook and the recording perfectly mirrored. Focus on intent (“Confirm the customer’s billing address matches the shipping zip”), not on rote step-by-step.

Working together

Playbooks support the same multiplayer editing you would find in a doc tool: live cursors showing who else is editing, inline comment threads on any paragraph, and @-mentions inside a comment to pull a teammate in. Resolve a thread when the change is in.

Inside the playbook body, @ is the picker for plugins and fields rather than for people.

You can also ask Arro Workspace Agent to refine a playbook so it is clearer, more specific, or up to date with the latest recording. Highlighting part of the body and clicking Ask Arro rewrites only that, the same as on a page.

Document size

See document size for guidance on long documents.

Related

Workflows

The container that holds the playbook.

Recordings

The captured events the agent uses to draft a playbook.

Plugins

The apps a playbook can name with an @ mention.