How it works

The plugin owns the deterministic part of a run. The Playbook Manager agent owns the judgment.

Plugin and manager

Plugin (rules)	Playbook Manager (judgment)
Loads and validates playbooks from the workspace	Picks the playbook that fits the request
Saves run state on the daemon	Writes each step's brief
Computes which steps are ready from `needs`, resets loops, enforces limits	Reads each step's result and chooses its outcome
Creates step agents with their role, prompt and labels	Decides whether to retry, nudge or loop
Wakes the manager when a step finishes or a gate is decided	Summarises the run for the human at a gate
Records gate decisions from the panel	Relays decisions that arrive by chat

The manager never edits run state directly. It calls the plugin's tools, and the plugin refuses anything the playbook does not allow, for example starting a step that is not ready.

Lifecycle of a run

Start. Start runs the playbook with the workspace's current agent (its most recent agent that manages no run): the plugin creates the run there, on the current branch, reloads the agent to give it the manager tools, and sends it the kickoff. If the agent is busy it is not interrupted: the kickoff waits for the end of its current turn. The arrow next to Start offers Start on a new agent, which creates a new manager agent in the same workspace, on its current branch, and Start in a new workspace, which creates a Paseo worktree on a new branch playbooks/<playbook>-<short id>, for example playbooks/pr-3a9c1f, and a manager agent in it, so the run never touches your checkout. Either way, one active run per workspace.
Steps. For each ready step the manager calls start_step with a brief. The plugin creates a subagent of the manager in the same worktree, with the role's instructions as system prompt and the rendered step prompt, inputs, loop feedback and brief as its first message.
Report. The step agent calls report_step_result with an outcome, a summary and its typed outputs, then ends its turn.
Wake-up. When a step agent's turn ends, the plugin checks readonly roles with git, then queues a message for the manager. Wake-ups are sent only while the manager is idle, merged into one prompt. The plugin does not cancel the manager's turn: it sends wake-ups as steer messages and relies on Paseo's busy tracking to know when the manager is idle.
Decide. The manager reads the report and calls complete_step. The plugin applies the transition and returns what is ready next, a gate to open, or the end of the run.
Gate. The manager opens ready gates with request_gate and ends its turn. You decide in the panel; the manager is woken with your decision.
End. The run completes, fails or is canceled. Its outputs appear in the expandable End pill in the graph.
Wrap-up. If the playbook has after: tasks, the auto ones start when the run completes or fails; manual ones start from a button in the panel. The same manager runs them like steps. They never change the run's status.

Tools

Tool	Who gets it	What it does
`list_playbooks`	manager	Lists this workspace's playbooks and explains the manager protocol.
`start_playbook`	manager	Creates a run with the caller as manager.
`start_step`	manager	Starts a ready step as a subagent with the manager's brief.
`complete_step`	manager	Records a step's outcome and applies the transition.
`request_gate`	manager	Opens a ready gate with a summary for the human.
`resume`	manager	Records a gate decision that arrived by chat.
`nudge_step`	manager	Sends a follow-up to a step's agent in the same conversation.
`get_run`	manager	Shows a run's steps, reports, outputs, gates and loops.
`list_runs`	every agent except step agents	Lists the active runs (or all unarchived runs) with their workspace, branch and manager.
`cancel_run`	every agent except step agents	Cancels a run and stops its running step agents; a manager is told when another agent cancels its run. On an ended run, cancels its running after-tasks.
`restart_run`	every agent except step agents	Reopens a finished or archived run from a step whose needs completed; a new manager takes over if the old one was archived.
`validate_playbooks`	every agent except step agents	Validates the workspace's playbooks with the panel's checks.
`report_step_result`	step agents	Reports the step's outcome, summary and outputs.

An agent gets the manager tools when its workspace contains a playbook, when it already manages a run, or when Start created it. Step agents are labelled by the plugin and get only report_step_result.

Plugin tools reach agents through Paseo's MCP server. For Claude agents created by the plugin (step agents and managers created by Start on a new agent or Start in a new workspace), the plugin pre-approves its own tools, so agents in default mode are not stopped by a permission prompt on them. Other providers may still ask.

Run state

Each run is one JSON file in $PASEO_HOME/plugin-data/paseo-playbooks/runs/, written atomically. It holds the playbook snapshot, inputs, every step's attempts, reports and outputs, gates, loop counts, queued wake-ups and history.
Run state is saved on disk, so runs survive daemon restarts and plugin reloads. On start the plugin checks running steps; agents that stopped without reporting are marked lost and the manager is told. Two limits: a plugin reload removes the playbook tools from agents already running until their next message (a step whose turn ends without a report gets one reminder from the plugin, which brings report_step_result back), and a busy agent's queued kickoff is kept in memory only, so a daemon restart before it is delivered leaves the run with nothing driving it (cancel it and start again).
When a run ends, its agents and worktree stay, so conversations remain reachable. Archiving the worktree cancels any active run in it and deletes its run files.
If the manager is archived during a run, the run fails and its running steps are stopped (no after-task starts; running ones are canceled). Archiving a manager also archives its runs.
On start, a run whose manager no longer exists is failed.

The Playbooks panel

Opens in the workspace's right-hand sidebar, or with Ctrl+K (Cmd+K) → Open Playbooks. React Native only, so it works on desktop, web and mobile.
Each playbook is a card showing its title and file path, validation errors, and a Start button.
Each run has a chevron menu with its details, then Pause (or Resume) and Cancel for active runs. Pausing lets running steps finish their turn but starts nothing new, and holds the manager's wake-ups until Resume. Finished runs offer Archive run, which hides the run from the panel; its agents and saved state are kept.
A finished run (completed, failed or canceled) can be restarted from a step: open the step's sheet and use Restart run from here. The step and everything after it run again with the same manager, or with a new Playbook Manager in the run's workspace if the old one was archived; completed steps before it keep their outputs, and after-tasks run again when the run ends. The step's needs must have completed. Agents can do the same with restart_run, archived runs included (list_runs with archived: true shows them and the steps they can restart from).
A completed run turns grey once you have opened its tab; until then it stays green. While its after-tasks run, its dot keeps its colour and pulses, and its tab says "wrapping up".
After-tasks appear below End, under "After the run", each in a frame with its status; manual ones have a Start button once the run has ended.
The graph is laid out top to bottom: each step one row below its deepest needs, parallel steps side by side, with connector lines between rows. Nodes widen with the panel from 132 to 240 px; the graph scrolls sideways only when they do not fit. Loops show as dashed lanes back up the graph, labelled with their outcome and loop count.
During a run, nodes show their state: the running step pulses (not with reduced motion), completed steps are green, failed red, gates and permission requests amber, and unreached steps dimmed.
Pressing a node opens its agent's conversation. Chips #1 #2 open earlier attempts. ⓘ opens a detail sheet with inputs and their sources, the manager's brief, the report, attempts and role instructions.
Gates show one button per choice (by default Approve and Reject), some with a comment field. Running steps can be nudged; the manager can be asked to retry a failed step; a run can be paused, resumed or canceled.
Start opens a form built from the playbook's typed inputs. It warns when an active run already has the same inputs, and refuses when the playbook's concurrency limit is reached.

Limits with Paseo 0.14

The plugin uses Paseo 0.14's server.on and server.before hooks. The SDK has no live subscriptions for plugins, so the panel polls: every 3 seconds while a run is active, every 30 seconds otherwise.
The SDK has no call to cancel a turn; the plugin stops a step agent by reloading its session.

The full design and its decisions are in the design record.