Playbooks
A playbook is a saved piece of agent work you can run again. Where a session is you typing at an agent, a playbook is the version you kept: the same instructions, the same setup, run on demand against whatever project or environment you point it at.
The useful mental model is a saved procedure with a run history — not a pipeline and not a scheduler. You start a run; it does its work; you read what happened.
What you would use one for
- A review or audit you do on every repository, phrased once.
- A migration or upgrade you have to apply across several projects.
- A recurring chore that needs judgement — the kind of thing a script cannot do but a person does not want to keep doing.
- Anything where you want a record that it was done, and what was done.
The three you start with
Your organization starts with three playbooks PlatformSmith maintains, ready to run with no authoring:
| Playbook | What it does |
|---|---|
| PlatformSmith Work Item | Runs a work item end to end: a conductor delegates to per-repo workers and settles each phase |
| PlatformSmith Knowledge Base | Regenerates each repository's brief and folds the peer knowledge base across the workspace |
| PlatformSmith Land Work | Lands a finished work item's branches to main across every repository it touches |
They are the fastest way to see what a playbook run looks like before you write one, and they are yours — editable and deletable.
Authoring
A playbook carries the instructions the agent works from and the configuration it runs with. Because it runs real agent work, it resolves the same things a launch does — an agent definition, a credential, and somewhere to run.
Write the instructions the way you would write a standing brief for a competent colleague: what you want, what "done" looks like, and what to leave alone.
Running one
Start a run and scope it — to a project, or to an environment, depending on what the work is about. The scope is what turns "the upgrade playbook" into "the upgrade playbook, on this".
Reading a run
A playbook run is its own record: when it started, how it was scoped, whether it finished, and what it produced.
The agent work inside a run happens in sessions, and coordination may happen in a conversation, so a run links out to those rather than containing everything itself. That is worth knowing before you go looking for the transcript — it is on the session the run created, not on the run. The four execution nouns lays out which is which.
The project you did not create
After your first playbook run you may see a project named platformsmith-conductor. It is a system
project the platform uses to run playbook work. Leave it alone; it is not a mistake and needs no
configuration.