Getting started

Install the plugin, write a first playbook in your repository, and run it from the Playbooks panel.

Requirements

• Paseo 0.14 or later (the plugin declares >=0.14.0).
• Plugins enabled on the daemon: Settings → Plugins → Enable plugins, or pluginsEnabled: true in the daemon's config.json.
• A git repository opened as a Paseo project. Each run gets its own Paseo worktree.

1. Install the plugin

paseo plugin install https://github.com/lerenn/paseo-playbooks.git --ref v0.7.0

To develop it, install from a local checkout instead (not from a Paseo worktree, which can be archived), then reload after each change:

git clone https://github.com/lerenn/paseo-playbooks
cd paseo-playbooks && npm install
paseo plugin install "$PWD"
paseo plugin reload paseo-playbooks

Check that paseo plugin ls shows paseo-playbooks as running.

2. Write a first playbook

Create .paseo/plugins/playbooks/ (or the shorter .paseo/playbooks/) in your repository:

.paseo/plugins/playbooks/
├── defaults/
│   └── main.yaml
├── hello.yaml
└── roles/
    └── writer/
        ├── role.yaml
        └── instructions.md

defaults/main.yaml

agent:
  provider: claude
  model: claude-sonnet-5-5
manager:
  mode: default

roles/writer/role.yaml

title: Writer
readonly: false

roles/writer/instructions.md

You write short documentation changes. Edit only the files you are asked to change,
with your file edit tool. Do not run shell commands and do not commit.
Return what you changed in the `changes` output.

hello.yaml

title: Hello
description: Write a short note, then wait for approval.

inputs:
  topic: { type: string, required: true, description: What the note is about }

steps:
  - id: write
    role: writer
    agent: { mode: acceptEdits }
    inputs: [topic]
    outputs:
      changes: { type: string }
    prompt: "Add a short NOTES.md section about {{ inputs.topic }}."

  - id: approve
    needs: [write]
    gate: Approve the note, or reject it with a comment to send it back.
    on:
      rejected: { goto: write }

The reference lists every field, and the examples page has a full pull-request playbook.

3. Validate and commit

Any agent in the workspace can call the validate_playbooks tool. It runs the same checks as the panel and lists every error with its file and field.

Press Start and fill in the inputs: the workspace's agent becomes the manager and runs the playbook in this workspace. To use a new manager agent here instead, open the arrow next to Start and choose Start on a new agent. To run in a separate worktree with a new manager, choose Start in a new workspace; commit the folder first, because the worktree branches from the current commit.

4. Start a run

1. Open the Playbooks panel in the workspace's right-hand sidebar, or press Ctrl+K (Cmd+K on macOS) and choose Open Playbooks. Each playbook is a card with its title, file path and step graph.
2. Press Start. A form built from the playbook's inputs opens. Start makes the workspace's most recently used agent (the one you last sent a message to) the Playbook Manager and runs the playbook in this workspace, on its current branch. Start is disabled when the workspace has no agent that can manage a run. To have a new agent manage the run in this workspace, open the arrow next to Start and choose Start on a new agent. To use a separate worktree instead, choose Start in a new workspace: it creates a worktree on a new branch named playbooks/<playbook>-<short id> (for example playbooks/pr-3a9c1f), starts a Playbook Manager agent there, and opens that workspace.
3. Watch the graph. The running step pulses. Press a node to open its agent's conversation, or ⓘ for its details: inputs and their sources, the manager's brief, the report and every attempt.
4. When the run reaches a gate, the gate node turns amber. Approve, or reject with a comment. A rejected gate with on.rejected: { goto: … } sends the work back with your comment as feedback.