runbooks / command
Update a runbook
Updates the steps of a runbook after the behavior it records changed
❯ /runbooks:update <id> --from spec <path> | diff [base] | ticket <id> | text \"<description>\" | file <path> | dir <path> | route <url> [--model <model>]❯ $runbooks:runbooks-update <id> --from spec <path> | diff [base] | ticket <id> | text \"<description>\" | file <path> | dir <path> | route <url> [--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.
An update changes what the runbook expects, so it is investigated like a new runbook, but only where the change reaches. Every edited or added ui step names a real route, a real control and the exact text the UI shows; every api step a real endpoint, role, request and the exact status and body (${RUNBOOKS_PLUGIN_ROOT}/skills/runbooks/instructions/create.md, step 3).
With role tracking on (roles.enabled in the config), also read the Roles and Review sections of references/format.md and references/config.md. The role steps below apply only then. With tracking off, ignore them.
Parameters
Name the runbook, then pick exactly one source after --from for what changed.
| Parameter | What it does |
|---|---|
<id> |
The runbook to update, as <capability>.<flow>. A deprecated runbook is not updated. |
--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. |
--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 update 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:update billing.issue-invoice --from spec docs/spec.md # from a spec
/runbooks:update billing.issue-invoice --from diff # diff since git.base
/runbooks:update billing.issue-invoice --from diff origin/main # diff since origin/main
/runbooks:update billing.issue-invoice --from ticket CHE-602 # from a ticket
/runbooks:update billing.issue-invoice --from text "Add a due date" # from a description
/runbooks:update billing.issue-invoice --from spec docs/spec.md --model sonnet # on sonnet, this time only