Playbooks

A playbook is a written process in your account's Handbook that starts tasks automatically and runs them as your agents. You describe when it should run and who does each step, and Wallfacer starts the task and routes the work when a matching event arrives.

An agent is an AI teammate with a name, a role, its own computer, and its own credentials. A task started by a playbook runs as one of your agents, and its work appears under that agent on GitHub and in your account.

Steps

A playbook is an ordered list of steps. Each step has a kind that says what it does:

Act. An agent runs a coding session to do the work.
Wait. The playbook pauses until its condition is met before moving on.

Set a step's kind from the step card. Changing the kind keeps the step's body text and rebuilds the rest for the new kind.

Nothing in a playbook waits for somebody to come into Wallfacer and press approve. Where a process must not continue until a person has decided, write a Wait step on the signal that decision leaves in your own system: an approving review on the pull request, a label on the issue, a passing check. You decide where you already work, and the playbook reads the result.

Who Performs a Step

Every step carries a Performed by line naming who does it. Both kinds run a session, so an agent performs every step, and the picker offers your account's agents.

An agent. What powers an agent, its computer, harness, and model, is set on the agent's own record, not on the step.
The task's performer. A step can follow whoever is already performing the task instead of naming a fixed agent. When the playbook's trigger routes an event to a specific agent, that agent performs the step; on a task with no routed performer, your account's default agent does. Pick this when one playbook should run as whichever agent the incoming event was meant for.

Picking a specific agent pins the step to that agent. Picking the task's performer clears the pin, so the step tracks the task instead. See Tasks for how a task shows which agent is performing it.

Waiting on Something

A Wait step watches for a condition and re-checks it on a cadence: a pull request that gets reviewed, an issue that moves, an answer to a question the agent asked. Give every wait an On failure route, so the playbook decides what happens when the condition is never met instead of the task stopping where it stands.

Write the check in plain English. The step's body says what to look at, what counts as passed, and what counts as failed. Each check is a session that re-reads the world and reports one of three verdicts: pass continues the playbook, fail takes the step's On failure route, and pending leaves the wait in place for the next check.

Set the cadence and the budget. The step card reads "Re-check every 5 minutes, 6 times", and both numbers are yours: an interval from a minute to a year, and anywhere from 1 to 1000 checks. A wait that spends its checks without passing fails through its On failure route, so a signal that never arrives ends the step rather than parking the task forever.

Waking on the Signal

Polling alone means the playbook moves at the cadence you set. Add a signal and it moves the moment the fact lands: under the cadence, wake early when an event arrives opens the same filter builder a trigger uses, so you name the source and type (github · pull_request_review) and the condition that makes the event this task's. The step then reads Wakes early when github · pull_request_review, and the task's callout reads Continues when github · pull_request_review arrives.

A wait with a signal parks without an eager check and lets the event wake it. A wake checks immediately and spends none of the scheduled checks, so the budget is what bounds the wait, not how often the world moves.

Match the event to this task. A filter that names only the source and type wakes every task waiting on that event. Match a field of the task as well, its branch or its issue number, and Wallfacer tells you so on the step card when you have not.

The filter builder is a browser control. A phone shows the signal read-only; write the cadence there and the filter at a desk.

The Seeded Playbooks as Examples

Every account starts with playbooks that pause this way, and they are the shortest way to see the pattern:

Implement Assigned GitHub Issues ends at "Wait for an approving code review". The check reads the pull request for the task's branch and passes when a person has submitted an approving review, fails when the newest review requests changes (which loops the work back to the step that wrote the code), and stays pending while only the reviewing agent has spoken. It wakes on github · pull_request_review for its own branch.
Validate and Triage Bugs ends at "Wait for someone to label the issue invalid". The agent posts its reasoning on the issue, and a person confirms it by adding the invalid label where they are already reading. It wakes on github · issues for that issue.
Research and Improve Ideas ends at "Wait for an Engineer to label the issue ready". Same shape, with the ready label as the sign-off.

All three check daily and give up after fourteen checks, about two weeks, then take their On failure route.

What the Task Shows While It Waits

A task parked on a wait carries a Waiting on a signal callout: the step's title, the check as you wrote it, the signal it continues on, when it checks again, and how many of its scheduled checks it has used. It ends with "Nothing to do here." There are no buttons on it, because there is nothing to press: the task is watching your systems, and it moves when they do.

A wait ends when the work it is watching ends. A pull request closed without merging, an issue somebody closes, and a question nobody answered are all endings. The wait settles as soon as one arrives and takes the step's On failure route, rather than re-checking for hours or days for a result that can no longer arrive. The wait's outcome names what ended and why.

A close is an ending only when the wait says so. The same closed issue means different things to different waits: to a playbook watching its sub-issues land it is progress, and to the task implementing one of them it is the end of the work. So a wait watching GitHub states which it means, and a wait that does not keeps reading a close as movement. A merged pull request is always movement.

When to Run This

Every playbook has a When to run this section. Write one sentence describing the event that should start it, and Wallfacer compiles it into a trigger. An event trigger fires on a source and type, shown as github · issue.opened or github · issue_comment.created. Add filters to narrow it to the issues and comments you care about, matching fields on the event with all of these or any of these conditions.

The pickers only offer event types and fields your account already receives, so you build triggers against the real shape of your GitHub issues and comments rather than a guessed schema.

A playbook with no trigger runs only when someone clicks Start task from the Tasks page.

Routing Work to an Agent

The Performs as line on a trigger decides which agent a started task runs as. By default the task runs as your default agent. Point it at a field on the event instead to route each task to the agent the event names. Wallfacer reads how to route from the kind of field you pick.

Match an identity field. Point Performs as at a structured identity field, such as the issue's assignee login, and the task runs as the agent whose GitHub username matches that field. Match on a different attribute, such as name, display name, email, or job title, when your agents are not keyed by GitHub username. At most one agent matches, so exactly one task starts.

@-mention in a free-text field. Point Performs as at a free-text field such as the issue body or a comment body, and every agent @-mentioned in that text gets its own task. Mention two agents in one issue or comment and each one picks up a separate task and does the work as itself, on its own computer and under its own identity. A handle counts as an address only when it stands on its own: @ada routes to Ada, while an email like [email protected] or a URL like github.com/ada does not.

Only your agents are addressable. A mention of a teammate who is not a runnable agent, or a handle that matches nobody, is skipped.

One Task at a Time

A trigger either opens a new task each time it fires, or keeps one task per entity you choose, for example one task per issue. When it keeps one task per entity, a repeat of the same event folds into the task that is already running instead of starting a duplicate: editing the same issue again updates the open task rather than spawning another.

A task that has finished or failed no longer holds its place. After a triggered task fails, repeating the action that started it, such as reassigning or relabeling the issue, starts a fresh task. The failed task stays in place so you can inspect it.

When routing fans out to several @-mentioned agents, each agent keeps its own task. Re-mentioning one agent folds into that agent's open task, while a first mention of another agent on the same issue starts a task for them.

Editing a Playbook on a Phone

The playbook editor works on iOS and Android as well as in a browser. A playbook opens read-only on a phone or tablet: tap Edit in the nav bar to change the title, description, steps, step routing, and the When to run this sentence, then tap Done. Changes save as you type, and leaving edit mode or the screen saves whatever is still in flight.

Three controls stay in the browser, and a phone shows them read-only:

The structured filter builder on a trigger. Write the trigger sentence instead, and Wallfacer compiles the filters from it.
The choice between opening a new task each time and keeping one task per entity.
The wake-early filter on a Wait step.

What's Next

Tasks: Create and manage tasks by hand.
GitHub Integration: Connect GitHub so agents can read issues and push code.
Accounts: Add members and agents to your account.