Help

/runbooks:help answers a question about the plugin. It picks the area of the question, reads that area's files in the installed plugin, and answers from what it read. Every claim comes from a file, and the answer ends with the files and sections it used. It is read-only: it runs no runbook, writes no file and commits nothing.

By default, a question goes to a sub-agent on sonnet, and the main session prints its answer. Listing the areas or explaining one runs in the main session. The help rows of the models table set both, and --model overrides them for one question.

How it works

Three ways to ask

• With no argument, it lists the areas with one line each, and an example.
• With only --about, it explains the area: what it is for, its terms, how its pieces relate and its commands.
• With a question, with or without --about, it answers the question.

❯ /runbooks:help # list the areas
❯ /runbooks:help --about upstream # explain one area
❯ /runbooks:help --about roles "How do roles work?" # a question in one area
❯ /runbooks:help "Why does my mocked runbook not count as coverage?" # the command picks the area

The areas

Each area reads the files below, every path under the plugin's folder. references/ is short for skills/runbooks/references/, and instructions/ for skills/runbooks/instructions/, where the procedure of each command that can run in a sub-agent lives from 1.13.0. In a long reference, the command reads the sections the area names first, such as Roles in config.md, then any other section the question reaches.

The pages of this site cover the same ground: roles, contexts, permissions and the references. The command reads them for you and answers the one question you asked.

How it picks the area

• With --about, it takes that area. A command name such as run, or a term of the glossary such as case, maps to the area that holds it.
• An unknown name gets the list of areas, the closest first, and the command stops.
• Without --about, it picks the area from the glossary terms and the commands the question names. When two areas fit, it reads both. When none fits, it uses overview.

How it reads

• It always reads CONTEXT.md, the plugin's glossary: runbook, flow, surface, role, permission, context, case, outcome, review and the other terms. The answer uses these words.
• It follows a link or a file name in those files when the question needs it, such as an ADR a reference cites.
• It reads your config when it exists. It reads roles.json or a runbook only when the question is about this project, such as "Which roles do I have?", and then prefers the plugin's script: runbooks.mjs roles, list or check <id>.

How it answers

• In the language of the question. Without a question, in the config language, else English. Glossary terms, frontmatter keys, commands and file names stay as they are.
• The answer comes first, in a few sentences.
• Then what you need to act on it: an example in the runbook or config format, taken from the references, and the commands that do the work, with their parameters.
• When your config changes the answer, it says how. With roles.enabled off, for example, it says the roles behavior does not apply until /runbooks:settings roles turns tracking on.
• It ends with the files the answer came from, each with its section.