Playbooks
What a playbook is, how to get one, how to run and edit it, and how scheduled runs behave when nobody is watching.
A playbook is a reusable workflow your agent can run end to end: Start from a proven template, then run it whenever you need it.
Underneath, a playbook is a written document: a name, a one-line description, and a body of instructions in plain markdown. Running one hands those instructions to Terra as the opening brief of a fresh chat thread, and editing one is editing the instructions. There is no hidden configuration. Use a playbook for work you repeat and want done the same way each time: a monthly keyword pass over a page, a research-then-build routine for content pages, an import routine from a design file.
The Playbooks page
Three sections, top to bottom:
- On autopilot holds scheduled playbooks, with their schedule, last or next run, and an on/off switch. It is hidden when you have no schedules.
- Library holds your playbooks. Each card carries Run now and Schedule, with a search box above once you have some.
- Featured ready-to-run holds Iterant's templates, each with a Try button.
Getting a playbook
Press Try on a featured template. Iterant copies it into your library and opens it, yours to edit.
The catalog today:
| Template | What it does |
|---|---|
| Build a Content Page | Researches a topic, writes a page-content document, then builds and verifies the page from it. For comparison guides, listicles, how-tos, and pillar pages. |
| Keyword Optimization | Finds queries a page already earns impressions for but never mentions, and weaves them into the copy. Needs you to supply the page's search-performance export. |
| Import from Figma | Rebuilds a page from a Figma frame: renders the design first, derives its tokens, imports its assets, and verifies against measured values. |
| Connect Your Domain | Measures your live site, explains the ways to serve Iterant content on your own domain, captures your choice, and routes you into the matching setup. Changes nothing on its own. |
A copied playbook keeps a provenance line under its name, cloned from <template> v<version>. It is display only, and editing the playbook keeps it.
The detail page
Clicking a playbook opens its detail page: name, description, and provenance, then Run, Edit, Schedules (each row with a switch and a delete, plus Add schedule), and Run history down the side, newest first. With no schedules, that section reads This playbook runs only when you start it. Add a schedule to put it on autopilot.
Running one
Run now on a card, or Run on the detail page. You land in the chat thread where the run is already streaming, titled Run: <playbook name>. You can watch it and you can steer it: a manual run is an ordinary conversation that opens with a long brief. From a chat you're already in, the /playbook command browses your saved playbooks and starts one.
A playbook that builds pages takes minutes. The agent takes an exclusive hold on your brand's workspace while it works, so a second operation started during one does not queue behind it. It waits a short while for the workspace, then gives up, and you start it again. Let one finish before starting the next.
Run history
Each row shows how the run was triggered (Manual, Scheduled, or In chat), its status, a one-line summary, and when it happened. Clicking a row opens the thread it ran in, with the full transcript.
| Status | Meaning |
|---|---|
running | In flight right now. |
completed | Finished its work. |
blocked | Stopped before finishing. The summary says why: open plan items, unsaved changes, or unresolved visual-review findings. |
failed | The run errored out. |
A blocked run stopped short and recorded the reason. Open the thread and pick up where it left off.
Editing a playbook
Edit opens the playbook editor. Three things are yours:
- Name, the heading.
- Description, one line about when your agent should run this playbook. You and the agent both read it when deciding whether to reach for the playbook, so write it about the trigger.
- Body, the instructions themselves.
Everything saves as you type, with Saving… and Saved in the top bar.
Writing a good body
Read a template before writing your own. The shape they use works:
- When to use and when not to use, the guardrails that stop the playbook running on the wrong job.
- Phases with checklists, one line per step, in order.
- Halt conditions, where the agent should stop and ask instead of guessing. Templates lean on these hard.
- Rules, MUST and MUST NOT statements for the things that matter.
- Report, what to write down at the end.
Write it as instructions to a capable colleague. Terra reads it as prose.
A playbook has to fit in the run brief. Iterant refuses an oversized one when you try to run it, with a message telling you to split it into smaller playbooks.
If two people, or you and the agent, edit the same playbook at once, the editor tells you and offers Save my changes or Reload the latest version. Your unsaved text stays until you choose.
Scheduling
Schedule on a card, or Add schedule on the detail page, opens a plain builder: Choose when this playbook runs automatically.
| Field | |
|---|---|
| Frequency | Daily, Weekdays, Weekly, or Monthly. |
| Days | Weekly only: pick one or more weekdays. |
| Day of month | Monthly only: 1 to 28, capped so every month has the day. |
| Time | One 24-hour firing time. |
| Timezone | Defaults to your browser's. |
| Next runs | A live preview of the next three fires, so you can check the schedule before saving. |
| Enable now | On by default; turn it off to save a schedule without arming it. |
Save schedule commits it.
One schedule means one firing time. "Twice a day" is two schedules, each with its own switch, so you can pause one without touching the other.
Saved schedules appear under Schedules on the playbook and under On autopilot on the Playbooks page, each row showing its schedule, the last run and its outcome or the next run, a switch to pause and resume, and a delete.
How scheduled runs behave
Nobody is watching a scheduled run, so Iterant constrains it:
- The agent can't ask you questions. The ask-the-user step isn't available on a scheduled run, and the actions that depend on your confirmation, the ones that change your domain or republish your site, are removed from what it can do. Run a playbook that needs a decision from you by hand, or split it: the automatic part on a schedule, the decision part on demand.
- The run stops instead of overspending. A scheduled run has a token ceiling. If it reaches the ceiling, the run stops early and says so in its summary.
- Runs don't overlap. If a scheduled run is still going when the next fire comes due, Iterant skips that fire, records it as
skippedon the schedule, and moves to the next occurrence. If fires keep getting skipped, the playbook takes longer than the gap between them, so make the schedule less frequent or split the playbook. - Repeated failure turns the schedule off. After three consecutive failed runs, Iterant disables the schedule and shows the reason on the row: auto-disabled after 3 consecutive failed runs. Fix the cause, then switch it back on.
Every scheduled run lands in the run history with its own thread, so you can read what happened.
Troubleshooting
Last updated on