runbooks / command
Create a runbook
Writes a runbook from a spec, diff, ticket, description, code file, directory, route or placeholder, filling the matching placeholder, with one step per happy path, expected error and edge case it finds in the code; for a ui runbook, asks the screen sizes it runs at and links its screens to their designs
❯ /runbooks:create --from spec <path> | diff [base] | ticket <id> | text \"<description>\" | file <path> | dir <path> | route <url> | placeholder <id> [--model <model>]❯ $runbooks:runbooks-create --from spec <path> | diff [base] | ticket <id> | text \"<description>\" | file <path> | dir <path> | route <url> | placeholder <id> [--model <model>]When executing as a child, you cannot ask the user. When the main session executes this file inline, it asks the user directly and handles calls through the dispatcher. Where this file says to ask (AskUserQuestion, "ask the user", a diff approval), stop with status: question as agents.md says. Where it says to say something and stop, put the message in summary: and report status: done. Commit nothing: the main session commits after it prints your summary.
A runbook is worth what was investigated. Every ui step names a real route, a real control and the exact text the UI shows. Every api step names a real endpoint, a real role and the exact status and fields the response returns.
With role tracking on (roles.enabled in the config), also read the Roles sections of references/format.md and references/config.md. Every role step below applies only then. With tracking off, ignore them.
Parameters
Pick exactly one source after --from. Whatever the source, it fills a matching placeholder when there is one.
| Parameter | What it does |
|---|---|
--from spec <path> |
A spec or design doc in the repo. |
--from diff [base] |
The changes from base to HEAD. base defaults to git.base in the config. |
--from ticket <id> |
A ticket: read through a connected tracker MCP tool, else through tickets.fetch in the config, else you paste it. |
--from text "<description>" |
A plain description of the behavior, in quotes. |
--from placeholder <id> |
Fill this placeholder, written by /runbooks:map. |
--model <m> |
Run this invocation on one model: inline (in the main session), haiku, sonnet, opus or fable. Any value but inline runs the command in a sub-agent on that model. Without it, the command takes its row of the models table in the config: by default create runs on opus. On Codex, the values are inline, inherit (a sub-agent on the session's model) or a model ID the session supports, and the table is codex.models, where every row that is not inline defaults to inherit. See models. |
/runbooks:create --from spec docs/spec.md # from a spec
/runbooks:create --from diff # diff since git.base
/runbooks:create --from diff origin/main # diff since origin/main
/runbooks:create --from ticket CHE-581 # from a ticket
/runbooks:create --from text "Admin issues an invoice" # from a description
/runbooks:create --from placeholder billing.issue-invoice # fill a placeholder
/runbooks:create --from spec docs/spec.md --model sonnet # on sonnet, this time only