Playbooks

A playbook is a guided track for one job. The provided playbooks are:

• Replace the stale architecture doc
• Plan and track a migration
• Make an architecture decision and see it built
• Take a new project from idea to handover
• Map the enterprise landscape
• Follow dependencies across repositories
• Catch breaking changes before a release
• Give coding agents the architecture
• Catch architecture drift

The setup guide is a playbook too, the first one every workspace runs.

Each provided playbook is the product's half of a use case: the page tells the job in full, with a still of every step, and the playbook walks it. Run this playbook on a use-case page opens ProvenMap with that run started and the guide beside you, through sign-in or sign-up if you are not in yet. In the guide, the book icon in the run's header opens the use case in a new tab.

Each playbook is a set of steps. A step points at something the product already has: a plugin command, a control on screen, a question in chat, an insight skill, a work item or a publish.

How a step completes

You rarely tick a step. The board watches real state and marks a step done when the thing it asked for exists:

• The repository is bound.
• The sync finished.
• The context board this step drew exists.
• The work item this step drafted exists, or the one this run handed off came back ✓ Confirmed. On a playbook that runs on an epic, work items made at its steps are filed in that epic. A step about every work item, such as "every step confirmed", counts every one in the epic, including ones you add yourself.
• A board is published.

A step that asks you to do something in chat, or to hand off a work item, counts only what you did from that step. A conversation or a work item that was already there doesn't count.

A step that asks you to commit a board edit counts the work item the commit creates. The commit dialog shows Counts toward that step, ticked, with the playbook's epic picked under Filed under; untick it when the commit is other work.

A publish step counts whichever board you publish while the run is live, from wherever you publish it. For a playbook that runs on the workspace, any board counts, a context board included. For one that runs on an app, the app or a layer under it counts. A board that was already published before the run started does not.

Two steps are the exception, because the board cannot see them. The guide itself reports a visit to the hub. An acknowledge step asks a person to confirm something that happened outside the product, such as a stakeholder reading a published board. The guide names who should confirm and what, with a Confirm button and Copy link for the board the run published.

A confirmation that only means something later, like "a month on, the board is still current", stays closed until its date and says when it opens. Once confirmed, the step reads Marked done instead of naming evidence. A playbook may have at most three acknowledge steps, counting those in the playbooks it includes.

If you did a step's work outside the guide, such as asking the question in chat yourself, the step never sees it. Open the step and choose Mark as done; it reads Marked done by you, with the day, and you can take the mark back from the row. A step the board can see for itself, such as a sync or a bound repository, has no such control. If the board later finds what the step asked for, the proof replaces your mark.

Letting an agent run it

Every step has tools: what an agent may call to do it, the same tools Chat and the plugins use. A step's kind implies them.

Only the workspace plugin runs playbooks: its /run-playbook runs one with you. It does every step except the setup guide's and a command for the repository, and asks a person for these:

• A question in chat is the agent's to answer from the board. Once you are satisfied with the answer, it marks the step done.
• A choice, or the app, epic or layer the run is on, is yours; the agent asks and records your answer.
• An acknowledge step is the named person's. The agent records it once they have confirmed, never for them, and not before the step opens.
• A publish is yours (changed 30 September 2026). The agent asks you to publish the board from Publish, and the step ticks when you do.

An agent records only on a run it started. It can also skip an optional step, and what it marks done shows as marked, never proven.

The agent follows the playbook's instructions, generated from its steps and their tools. Read them in the composer under Instructions, or choose Edit this file to change the wording; once you save, agents receive your version. If you change a step afterwards, the button reads Instructions · outdated, with Regenerate and Keep mine in the dialog. Back to generated drops your wording.

Running one

The sidebar shows up to five playbooks. Click one to open its run, or to start it on the board you are looking at. If you aren't on a board, it starts on the root board and takes you there. The rest are under More playbooks.

An owner or admin chooses the five with the Sidebar switch on each row of Organization settings → Playbooks. Everyone in the organization sees the same five. Until someone chooses, the sidebar shows the setup guide and four provided playbooks. Only an enabled playbook can take a slot.

A run is yours. Each person in a workspace walks a playbook on their own run, with their own ticks, skips and choices. The setup guide starts for each person the first time they open the workspace. What a teammate's run produced never ticks a step of yours, and a teammate's run is read-only to you.

Add the Playbooks card to a hub from Add widget to see your runs, the playbooks you can start and teammates' live runs. A step that was already true when the run started, such as a repository bound before you began, reads Already in place. An unstarted playbook marks the steps the workspace already satisfies the same way.

A playbook that runs on an app or an epic opens with a Select target step, already done when you start it from an app's own hub. Otherwise, an app playbook lists the apps, and Show the landscape takes you to where a system becomes an app. An epic playbook sends you to Choose in Work items, where each epic's header offers Use for the waiting playbook, or you can name a new epic in the step. Every other step waits until the run has its target; then the guide's buttons open that app or epic. Sidebar shortcuts and the agent's start_playbook start these playbooks the same way.

A playbook that draws its work somewhere, such as Take a new project from idea to handover, follows the target with a Select layer step. It lists the root board and every layer in the board tree. Choose the landscape when the new systems sit beside your others, and a system's own layer when they extend it. From then on, the guide's canvas and chat buttons and the playbook's publish use that board, and its work item buttons still open the epic.

A run of yours has a menu, on the card and in the guide's header:

• Restart removes the run and what it recorded, then starts a fresh one, asking again for its app, epic or layer. Boards, work items and conversations the old run produced stay where they are.
• Remove deletes the run.

The guide opens in the sidebar and follows the run, one group of steps per stage.

You can open any later step to read what it asks. A step that needs something first, such as a connected repository, shows a lock and says Unlocks after that step, with no button until then. A step you finish out of order still counts.

A step that looks done but isn't says why under it. For example, Push the first analysis on an app with elements already on its board reads no analysis pushed yet and says those elements did not come from the repository.

Skip a step that isn't your job, and restore it later if it turns out to be. You can also turn off the setup guide in Workspace settings → Setup guide.

A run ends on its proof: a published board, a confirmed work item, or an acknowledgement. The run stays readable from the card.

You can start a playbook from chat too: describe the job, and ProvenMap confirms the playbook by name before starting it. The code plugin cannot run playbooks. In a repository, its /start lists the live runs on the bound board and leads with a run's next command step. /start --for <slug> starts one from the terminal.

Composing your own

Organization settings → Playbooks lists every playbook your organization sees. Fork opens a provided playbook in the composer, and Save as fork gives your organization its own copy. The fork replaces the original for your organization, and a later update to the original never changes it. New playbook starts from nothing.

A fork's source reads Your copy of ProvenMap's playbook. Once ProvenMap updates the original, it adds ProvenMap's is newer with the new version.

Before it changes anything, Use ProvenMap's version lists every difference:

• steps only in your copy, which go
• steps only in ProvenMap's, which arrive
• steps that read differently, and how
• playbook details that differ

Confirming deletes your copy and the original shows again. Runs already started keep the steps they started with.

Drag step kinds, building blocks or other playbooks from the library into named stages, or click one to add it to the last stage. The stages are the guide's groups, in order.

Selecting the playbook's title opens Name, Icon, Summary, The job, in the user's words, Started on (the workspace, an app board, or an epic) and Door. The icon can be a Lucide glyph, an emoji, or a cloud or brand icon from the icon catalogue.

A step's Tools field lists what its kind implies, under Implied by the step. Name tools only when the step needs something different: up to eight, each with the tool's own description or wording you write for this step. The composer offers only tools ProvenMap exposes to agents, and saving refuses any other name. If a step's tools can't make what proves it, or a step has no way for an agent to do it, the issues list says so.

An aspect step's Which aspect names the family /aspects has to bring in, such as The API surface. Left at Any aspect, any family on the board counts.

A choice's Skip when already true names a state of the workspace that makes the question pointless, such as The landscape has systems. When it holds, the guide doesn't ask, and a branch chosen before it held is dropped. Never always asks.

A work item step's Until is Drafted, Handed off or Confirmed by the code. A drafted step is done once the run has a draft. The guide opens Work items for it, with Draft in chat beside, for pasting a plan.

The issues list along the bottom names what blocks saving, such as a step with nothing to prove it or an end that is not a proof. The Save button stays disabled until there are none.

Open an issue to read its rule and, where the composer can make the change, what it will change, as before → after. For example, Add Select target names the steps that will wait on it. Applying a change marks the step Changed with Undo, and nothing is saved until you save. An issue the composer can't settle for you says what to change, with a button that opens the step.

Preview here shows the draft as the guide would, read against a workspace you pick. Steps that workspace already satisfies read Already in place, and you can try each branch of a choice. Turn Enabled on when the playbook is ready. Until then it isn't in the sidebar or on the hub, and nobody can start it.

ProvenMap drafts a playbook from a description in chat, and so does the workspace plugin's /author-playbook. The plugin interviews you about the job first and can use an existing playbook as its template. Either way, the draft saves as disabled for you to review and enable in the composer.

A draft that names a control the guide can't point at, or a step whose proof can never happen, comes back with its issues instead of being saved. You change an existing playbook in the composer.