Appearance
Playbooks
A playbook is a reusable recipe for working one ticket from start to finish. It is an ordered list of steps, and each step gives a role (QA, SE, PM, …) a workflow to run on an agent. Between steps, a gate reads the verdict the agent posted on the ticket and decides whether the run continues, goes back, stops, or pauses for you. Bug Fix, for example, runs QA triage, then SE root cause, the fix as a pull request, review and merge, and a QA regression check.
Each step runs as an ordinary job with its own transcript, cost and agent, so one run can span several agents. The ticket is the shared record: every agent step posts one comment on it, and that comment is the gate's evidence. For the mechanics behind the gates, see Orchestrating agents.
The playbook library
Open Settings → Library → Playbooks (app.kadmo.ai/playbooks/library). The page, Account playbooks, lists every playbook your account can run:
- Seeded playbooks, managed by Kadmo: Bug Fix, Feature Implementation, Hotfix, Epic Analysis, Epic Plan, Landing Page Design, Documentation Page, QA Pass and QA Consolidation. You can view them and Duplicate them, but not edit them.
- Your own playbooks: blank ones and copies of seeds. These rows offer Edit, Duplicate and Delete.
| Column | Shows |
|---|---|
| Playbook | Name and description |
| Flow | The steps in order: ticket status, waits, role chips, ↻ for a re-run and ↩ for a send-back |
| Roles | The roles the steps need. needs ROLE means no agent on the account can run that role yet. |
| Sync | Whether runs move the ticket's status by default |
| Runs | How many runs it has had, linked to the run history |
| Updated | Last change |
| Enabled | On or off. Disabled playbooks are hidden from the intake and from automations, and their past runs keep their history. |
Filter by state (All, Enabled, Disabled) or by name. Only admins can create, duplicate, delete or enable playbooks; other members can open any row to view it. Deleting a playbook that has runs disables it instead, so its run history is kept.
Who can run this → opens Capabilities → Playbooks, which shows which agents in a workspace can run each playbook.
Create or edit a playbook
- Click New playbook. Choose Blank playbook to start from an empty canvas, or Start from a seed to copy its steps.
- Name the playbook. The slug is set on the first save and cannot be changed afterwards, because automations find playbooks by their slug.
- Build the flow on the canvas (below).
- Click Save playbook.
The editor
The canvas runs from Start (the ticket is bound or created at intake) to Run ends. Click ＋ to insert a block, drag ⋮⋮ to reorder, and click a block to edit it in the inspector on the right.
| Block | What it does |
|---|---|
| Agent step | Runs a role's workflow as one job, with transcript, cost and agent selection. The step's ticket comment gates it. |
| Jira status update | Moves the ticket to a status, by name. Nothing happens if the ticket is already there, and the block is skipped when the run has status sync off. |
| Wait | Pauses the run for a set time, for example to let a deploy settle before regression. You can skip it on the run page. |
| Slack notification | Not available yet. |
A status or wait block at the end of the flow ends the run as Resolved.
Playbook settings → holds the Name, Description, Sync Jira status by default (you can override it per run at intake), Default effort tier (Auto (inherit) unless set) and Enabled. The status list a status block offers comes from your tracker project or your account's task statuses. A name that is not on the list shows a warning but does not block saving.
Steps
An agent step has these fields:
| Field | Meaning |
|---|---|
| Role | One of the account's roles. Kadmo uses it to choose an agent automatically. |
| Workflow | An installed agent workflow for that role. A workflow you add to your skill pack can be picked here after the next sync. |
| Step hint | Extra instructions for this step only, up to 2,000 characters |
| Effort tier | Inherits from the playbook unless you set it |
| Gate | What each verdict does (see Gates) |
Gates
The heading in the inspector says it: Gate — the step's Jira comment decides. Each workflow declares the verdicts it can post, such as PR_OPEN, PASS, FAIL or BLOCKED. You route each verdict to one of these outcomes:
| Route | Effect |
|---|---|
| Continue ↓ | Go to the next block. |
| Re-run step ↻ | Run the same step again, for workflows that post a continuation token. Limited by Max attempts: 1 to 10, default 10. |
| Send back ↩ | Go back to an earlier step. Limited by Max loops: 1 to 5, default 2. |
| End run · Resolved / End run · No action / End run · QA Fail | End the run with that result. |
| Pause for review | Stop and wait for you on the run page. |
When you pick a workflow, the first verdict is routed to Continue, the others to Pause, and a continuation token to Re-run. A presence-only gate ignores the verdict and treats any comment as the outcome (Continue or End run). Read-only steps such as triage and analysis use it.
Gates are conservative. No comment, or a comment that matches no verdict, pauses the run. A run never moves on without evidence. On a step whose gate passes on a merge, Kadmo checks the live pull request on GitHub, GitLab or Bitbucket first.
The agent's session can outlast its job. In that case the run waits for the verdict comment while the session is still active, and the run page says so. A comment or merge that arrives after a step has paused re-checks the gate automatically, up to 3 times per run (shown as Auto-resume). A step that fails because the infrastructure did, not the work, is retried on another healthy agent up to 2 times.
Messages that block saving
Save playbook stays off, and the top bar reads Fix issues to save, until each of these is fixed:
| Message | Fix |
|---|---|
| A playbook needs a name… | Enter a name. |
| A playbook runs at least one agent step — add one with ＋ before saving. | Add an agent step. |
| Pick a workflow for this step. | Choose the step's workflow. |
| Enter a status name for this Jira block. | Type or pick a status. |
| The last step has no End run route… | Route at least one verdict of the last step to End run, or add a status or wait block after it. |
| No verdict on this step routes to Continue, so the blocks after it can never run… | Route a verdict to Continue, or remove the blocks below. |
The server checks the playbook again on save. It refuses, for example, a workflow that does not exist for the account (workflow "X" does not exist for this account) or a verdict routed twice.
Start a run
You start a playbook run from the Tasks page, on the Run a playbook side of the intake card:
- Pick a playbook from the pills. Only playbooks your agents can run are offered. Hover a pill to see its steps and gates.
- In the box, paste a ticket link or key, or describe a new problem. You can drop or paste screenshots and logs, or use Attach files (10 MB per file).
- Optionally open ⚙ Options:
- New ticket goes to / Project
- Workspace
- Effort tier
- Min spacing between steps
- Ticket status sync
- Validate resolution when done
- Click the button. Its label tells you what will happen:
| Button | When |
|---|---|
| Work on KEY | The box holds one ticket. The run works that ticket and reports each step on it. |
| Create Ticket and Work | The box holds a description. Kadmo creates the ticket first, with your attachments, then starts the run on it. |
| Start Run | No tracker ticket is involved. |
With no tracker connected, a new ticket becomes an internal task in Kadmo. See Tasks.
If a run is already working the ticket, the intake says Already driven by run #N and offers Open run #N or Start anyway.
A run started here starts at once. Tickets you add to the pool instead are run by the scheduler; see Tasks. Automations can also start runs from tracker events.
The run page
Each run has its own page, /playbooks/runs/<id>, reached from the Tasks page or from any run link. It shows:
- Header: Started, Elapsed, Cost and Steps, with a live marker while it runs
- Steps ribbon: each step's status
- LLM Usage: cost, tokens, turns, agents, steps passed, and active versus wall time
- Git outcome: the pull requests the run produced
- Activity: the live feed, updated every 5 seconds, filterable by All, Steps, Gates, Ticket and Operator
Jobs for this run ↗ lists every job the run dispatched.
Run statuses
| Status | Meaning |
|---|---|
| Running | A step is working. |
| Waiting | A wait block or a step spacing is counting down. |
| Paused | A gate found no clear verdict, or a step routed to Pause for review. Your move. |
| Awaiting pick | A step ran two experiment branches and waits for you to pick one. |
| Resolved | Finished successfully. |
| Closed · no action | Finished with nothing to do. |
| QA Fail | Ended because QA failed the work. |
| Escalated / Failed / Cancelled | Ended without a resolution. |
Controls
| State | Controls |
|---|---|
| Running | ⏸ Pause |
| Waiting | ⏸ Pause, ⏭ Skip wait |
| Paused | ▶ Resume at <step>, ↻ Re-run <step> |
| Halted at a gate | Recovery options such as Recover session, Re-run step and Override gate. Override moves on to the next step regardless of the verdict. |
| Any open run | ✓ Mark as done, ✕ Discard. While work is in flight they read ✓ Cancel & mark as done and ✕ Cancel & discard. |
| Finished | ▶ Continue at, ↻ Reopen task |
Re-running a step discards that step and every later one, then dispatches again. A finished run cannot be re-run; reopen its task instead.
Run history and cost
Every run ever started is listed under Tasks → Runs (app.kadmo.ai/tasks?view=runs), newest first. You can search it, filter it by playbook and status, and sort by #, Item, Ticket, Playbook, Status, Duration, Started, Completed, Updated or Cost. The list loads more as you scroll, and each row opens its run page. A playbook's Runs count in the library links here, filtered to that playbook.
Cost is the sum of the cost of every job in the run, in US dollars. It includes retries, re-runs, experiment branches and judges, so it is what the whole ticket took.
Issue type routing
Settings → Task setup → Issue type routing (app.kadmo.ai/playbooks/mappings) maps your tracker's issue types to playbooks. This is how a bug suggests Bug Fix wherever Kadmo suggests a playbook. Out of the box:
| Issue type | Playbook |
|---|---|
| Bug | Bug Fix |
| Story, Task | Feature Implementation |
| Hotfix | Hotfix |
For each type you can pick a playbook, — No default (operator picks) —, or ⊘ Do nothing — ignore, no task. Linear has no issue types, so it routes by the issue's first label, and you add labels with + Add label. With no tracker connected, the map covers the internal task types.
Run configuration on the same strip sets each workspace's Pool size: how many pooled runs may be active at once. See Tasks.
Errors you may see
| Message | Fix |
|---|---|
| Paste a ticket or describe the problem first. | Fill in the box. |
| A project key is required to create the ticket — set it under ⚙. | Choose a Project under ⚙ Options. |
| "file" exceeds the 10 MB per-file limit — remove it to continue. | Attach a smaller file or a link. |
| A run is already driving this ticket… | Open the existing run, or use Start anyway. |
| Cannot start … No agent on this account can run the ROLE role… | Give an agent that role under Capabilities → Agents. |
| Cannot start … ROLE is not a role on this account… | Register the role under Roles, then give it to an agent. |
| No playbook can start on this fleet — all N need a role no agent here runs | Give your agents the roles the playbooks need. |
| Daily limit reached for this account. | Wait for the countdown, or raise the limit. |
| Your 14-day trial has ended. Upgrade to keep making changes. | Upgrade the account. |
Related
- Tasks: the pool that runs many tickets in dependency order
- Automations: start playbooks from tracker events
- Orchestrating agents: agent workflows, verdicts and gates
- Agents: roles and which agent runs what