Playbooks

A playbook is a written, step-by-step description of what a workflow does and why. It is 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. Every workflow has exactly one playbook, on every plan. It is created with the workflow and cannot be deleted, only emptied.

​

Where to find it

Open a workflow and click the Playbook tab. Start writing, or generate it from a recording. You write in a rich-text editor with headings, lists, and code blocks. When one workflow handles variations of the same task (“international invoices need a customs form”), write each variation as a branch inside the playbook. Work different enough to need its own playbook belongs in its own workflow. Anyone with edit access to the workflow can edit its playbook. The title above the playbook is the workflow’s name. Type in it to rename the workflow. A workflow with no title shows as Untitled workflow, and searching for that finds it. Press Enter to move from the title into the playbook. When an editable page or playbook opens, the cursor starts in the body, ready for you to type. An untitled one starts in its title. In pages and playbooks, clicks in the editor margins place your cursor beside the nearest text. The workflow tour introduces the Playbook tab alongside the task board and Start workflow.

​

Generate from a recording

A workflow made in watch mode arrives with a playbook drafted from the recording. To add to it later, record steps into the playbook. A playbook drafted from a new recording shows each step’s screenshot, with a short caption and a marker where you clicked. Add or change images the same way as on a page. Treat the draft as a starting point. Tighten the language, add domain context, and remove noise.

​

Record steps into a playbook

Add steps by demonstrating them. You need permission to edit the playbook, and recording needs the desktop app. Choose Record steps in the toolbar or the + menu, or right-click a block and choose Record steps here. A dialog lists the playbook’s headings with a bar showing where the new steps go. Click a heading, or use the arrow keys, to move the bar. It starts after the last step, or below the block you right-clicked. Arro puts the steps where you chose, unless the recording clearly belongs somewhere else in the playbook. Every step is renumbered after they land, and so is each “Step 3” the playbook’s text mentions. On web, confirm with Open desktop app. In the desktop app, confirm with Start recording. Demonstrate the missing steps, review them, and click Submit. On the computer you recorded on, the playbook shows the progress until the steps arrive, so keep the desktop app open. If processing pauses, Show playbook takes you back to it. When it finishes, a card in the corner opens the playbook at the first new step, with each step’s screenshot. If the heading you chose is deleted or moved before the steps arrive, Arro places them where they fit, or at the end of the playbook.

​

Reference data in a playbook

Type @ anywhere in the editor to open the mention picker. Field mentions let you write instructions like “open the URL in @Link” without hard-coding values. A run working a task board card receives that card’s values. If the card leaves a required field empty, the run stops before the first step and fails the card, naming the field. An empty optional field is gone without, unless a step cannot be done without it. A manual run asks you for missing required inputs without selecting a task. Mentions render as pills and stay valid as long as the field is on the workflow’s task board. To mention a field the task board does not have yet, type its name after @ and choose New field. Pick its type, then choose Create to add it to the task board. Turn off Show on the task form for a value the workflow fills in itself, so a scheduled task does not ask for it. 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. Mention a teammate to name them in a step, such as who approves a refund. The first time a playbook mentions someone, they get a notification that opens the playbook, as long as they can open it. While the playbook still mentions them, later edits do not notify them again. Mentioning yourself notifies nobody. An agent running the workflow reads the mention as the person’s name. There is no mention for a task board itself, because a workflow has exactly one, on its Tasks tab. For queued work, describe what to do with one task. The task board’s pick-up list determines which tasks receive workers. A scheduled task for a workflow whose playbook mentions fields adds a task with the schedule’s details each time; see What a schedule does. 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 notice shows what your account still 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.

​

Keep a playbook current

When the work changes, record the new steps into the playbook. For any other change, tag Arro in a comment on the playbook and say what changed.

​

Working together

Playbooks support the same multiplayer editing you would find in a doc tool: live cursors showing who else is editing, and inline comment threads on any paragraph. Tag @Arro in a comment to have Arro make the change and reply there. See Comments. Inside the playbook body, @ also offers fields, pages, members and plugins. To point someone at one step, copy a link to its block. To have Arro refine a passage so it is clearer or more specific, select it and choose Ask Arro. See Changes made with AI.

​

Icon and cover

A playbook can have an icon and a cover, and its workflow’s card in your library shows them too. They work the same way as on pages.

​

Document size

See document size for guidance on long documents.

​

Related