Playbooks

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

• Replace the stale architecture doc
• Get to know an inherited system
• Show architecture to people who aren’t engineers
• Keep the map moving with the code
• Plan and track a migration
• See the teams inside the architecture
• Make an architecture decision and see it built
• Take a new project from idea to handover

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

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 for Chat, an insight skill, a work item or a publish. A few steps set what the run is about: its app or epic, and the board it works on. A playbook adds no new place to type. Every step sends you to where the work happens.

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. The guide shows what proved each step, and the next step it is waiting on.

A publish step counts whichever board you publish while the run is live, and from wherever you publish it: the board menu, the hub, or the workspace listing. 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, and shows a Confirm button, with Copy link beside it 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 someone presses it, 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 Chat the question yourself, the step never sees it. Open the step and choose Mark as done. It reads Marked done by you, with the day, instead of naming what it found, 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; it ticks when the thing is true. 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 already use to draw a board or open a work item. A step's kind implies them.

A context-board step implies create_context_board, create_nodes and create_edges. A work item step implies create_work_item and transition_work_item, or only create_work_item when it stops at drafts. A publish step implies publish_board. A control on screen implies nothing, so it names the tools that do the same thing, such as get_hub_status for the attention queue.

Every step can be done by an agent, apart from the setup guide's, which walks the browser itself. The rest are a command for the repository, or a person the agent asks:

• A question for 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 asks them and records it once they have confirmed, never for them, and not before the step opens.
• A publish happens only after the agent asks you. It keeps the board's current visibility unless you name another.

A playbook writes its own instructions from its steps and their tools. They are one file that lists every stage in order, what each step asks for, which tools to call for it, and what proves it done. The architect plugin's /run-playbook reads that file and runs the playbook with you, through the same tools you would use. Every write from the agent names the run and the step, so the board credits that step with what the agent made.

No agent can prove a step. A step is finished when the board says so, the same rule that applies to you.

On a run it started, an agent can record what the board cannot see. That covers the app, epic or layer you picked, a branch you chose, and a confirmation the named person gave. It can also skip an optional step, or mark one done outside its door, such as a question it answered. A mark shows as marked, never proven, exactly as Mark as done does in the guide.

At a Select layer step, the architect plugin reads what is drawn on the likely layers, suggests one with its reason, and asks you.

Only the architect plugin runs playbooks. The code plugin cannot; in a repository, its /start shows the run's next command instead.

You can read the instructions in the composer under Instructions, copy them, and choose Edit this file when the generated wording isn't what you want. 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, each drawn with its icon in a ring that fills as its run advances. 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, grouped as Set up, Understand, Author, Operate and Share.

An owner or admin chooses the five with the Sidebar switch on each row of Organization settings → Playbooks. Choose sidebar playbooks, under More playbooks, opens that page. 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.

The Playbooks card on a hub lists your runs in progress first, then the playbooks you can start, then teammates' live runs and your finished ones. A playbook you haven't started shows its summary and an empty ring, never a count. Click a row to see its steps. A run shows what proved each one. A step that was already true when the run started, such as a repository bound before you began, reads Already in place rather than done by you. An unstarted playbook shows which steps the workspace already satisfies, marked Already in place. Open shows a live run in the guide, and Start begins one.

A playbook that runs on an app or an epic opens with a Select target step. Started from an app's own hub, that step is already done. Started anywhere else, 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: grouped by epic, each epic's header offers Use for the playbook waiting on one, or you can name a new epic right in the step. Every other step waits until the run has its target. Once it does, the guide's buttons open that app or that epic, not whichever board you last visited. Sidebar shortcuts and the agent's start_playbook start these playbooks the same way. A teammate's run is read-only.

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; choosing one opens that layer's canvas. 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. A playbook on an app or an epic asks which one again, and a playbook with a Select layer step asks for the layer again. Boards, work items and conversations the old run produced stay where they are.
• Remove deletes the run.

Boards, work items and conversations a run produced always stay.

The guide opens beside the sidebar and follows the run. It shows one group of steps per stage, named by whoever composed the playbook, with the active step open and one button.

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. It offers no button until then, because acting early would lead nowhere. A step you finish out of order still counts.

Skip a step that isn't your job, and restore it later if it turns out to be. With several runs live, the header switches between them. 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. Then the guide moves on, and the run stays readable from the card.

Chat can start a playbook too: describe the job, and it confirms the playbook by name before starting it. In a repository, the code plugin's /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, and the composer shows the same notice.

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.

The composer takes the full width of the screen. On the left is a library of step kinds, building blocks and other playbooks; across the rest are the steps, arranged in named stages.

Drag a step from the library onto a stage, or click it to add it to the last stage. Drag a card between stages or up and down within one. Rename a stage in place, move it with its arrows, remove it once it is empty, and add the next with Add stage at the right edge. The stages are the groups the guide shows, in that order. The zoom controls at the bottom left zoom in and out, or Fit all stages on screen.

Selecting a step opens its fields in a panel on the right. 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. It appears beside the playbook's name in the catalogue, the hub and the guide.

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.

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.

Along the bottom are the issues, 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 the rule behind it and, where the composer can make the change, exactly what it will change, as before → after. For example, Add Select target names the steps that will wait on it, and Use the run's epic shows the step's epic changing. Applying a change marks the step Changed on the grid 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.

Chat can draft a playbook from a description, and so can the architect 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 in the composer. It never goes straight to the sidebar or the hub. Preview it, then enable it; until you do, nobody can start it.

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.

Composing playbooks is a Pro feature. Saving, forking, enabling or disabling, deleting, and drafting through Chat or the architect plugin all need it. Running enabled playbooks is on every plan, and choosing the sidebar's five needs only the owner or admin role.