pair-runbook
Run a rollout runbook together with the user, one step at a time. Claude gives the next command and what to expect; the user checks it, runs it and pastes the output; Claude checks the output, fills in the stage's record in the run's working copy, updates the stage's sub-task, and moves on. Claude never runs a command against staging, production, outside services or a shared database itself. Stops at every gate and every failure, resumes from the working copy and the tracker, and after the production rollout updates the epic's build guides to show what shipped. Use when the user says "run the runbook with me", "let's do the PROJ-X rollout", "pair on the deploy", "what's the next runbook step", or pastes command output during a rollout.
Beakpoint-Insights · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Beakpoint-Insights/roost --skill pair-runbookAbout this skill
name: pair-runbook description: Run a rollout runbook together with the user, one step at a time. Claude gives the next command and what to expect; the user checks it, runs it and pastes the output; Claude checks the output, fills in the stage's record in the run's working copy, updates the stage's sub-task, and moves on. Claude never runs a command against staging, production, outside services or a shared database itself. Stops at every gate and every failure, resumes from the working copy and the tracker, and after the production rollout updates the epic's build guides to show what shipped. Use when the user says "run the runbook with me", "let's do the PROJ-X rollout", "pair on the deploy", "what's the next runbook step", or pastes command output during a rollout.
Pair Runbook
The user and you run a rollout runbook (written by write-runbook) together. You're the navigator: you say what to do, check what happened and keep the record. The user is the driver: they read each command, run it and paste back the output. Nothing changes in any environment except through their hands.
First, load the team config with roost-config.
Rules that always apply
- You never run a rollout command. Not against anything in
deploy.runbooks.never_run_against(and always not against staging, production or a shared database), and not "just a read-only check". The user runs every command in the runbook. You may read the runbook and the repo, keep the working copy, and read and update the tracker. The one exception: when the user explicitly hands you a step to do through a connected tool (for example "create the alerts through the monitoring MCP" or "delete the flag with the feature-flag MCP"), do that step, show what you did, and record it as done by you at their request. - Before asking the user anything, re-read their recent messages. The answer is often already there.
- One command per turn. Give one command (or one block the runbook groups as a single action), then wait for its output. Never queue up several.
- Secrets stay out. Never ask for a secret's value. Before a command whose output includes one (a key, a connection string, a webhook secret), say which part to blank out before pasting. If the user pastes a secret anyway, say so, and don't repeat it in your reply, the record or the tracker.
- The template stays as it is. Fill in the working copy, never the runbook in the repo. If a command in the runbook turned out wrong, record what was run instead and add it to the working copy's Runbook fixes list, to fix after the run.
- Plain language. Say what a stage proves and what the output means, in a sentence each.
Inputs
- The rollout ticket (the deploy ticket, for example PROJ-2795). Its description names the runbook; each stage of the runbook is one of its sub-tasks, with the same number and title.
Words used here
- A stage is one numbered unit of the runbook with its own sub-task (stage 6, "Apply the migrations to staging", is one sub-task). The runbook may call it a step.
- A stage holds one or more commands (6a, 6b …), each with its expected output, and one Record block.
- A gate is a go/no-go decision the runbook puts after a stage or a group of stages (Gate T after stages 5 to 8). A stage whose "Done when" names a gate isn't done until that gate is passed.
1. Set up, or resume
- Read the runbook. The ticket says where it is. Read the version on
mainindeploy.runbooks.repo; if it isn't merged yet, read the branch the ticket names, and tell the user which one you're using. - Check it matches the tracker. Every stage has its sub-task with the same number and title, and every open sub-task is a stage. If they don't match, stop and show the difference; the user decides which is right before anything runs.
- Find the working copy. The runbook's "How to record this run" names it (for example
~/PROJ-2795-run-<date>.md). Look for one from an earlier session.- None: create it by copying the runbook, then ask the user to start the transcript the runbook asks for (
script -a …) in the terminal they'll run commands in. Fill in the run header with them: date, operator, the environments this session will touch. - One exists: resume from what's recorded, not from the first blank. For each stage, read its Record (result pass, fail, or partly filled) and any gate block after it. The run picks up at the first stage that isn't recorded as pass, at the command after the last one recorded, or at a gate that hasn't been called; a failed stage comes back to its failure, not past it. Then check each stage against its sub-task: Done should mean the Record says pass and any gate it waits on is passed; In Progress is normal for a stage that's partly done. Show any other mismatch to the user to settle before you go on.
- None: create it by copying the runbook, then ask the user to start the transcript the runbook asks for (
- Show where things stand: one table, one row per stage: number, title, sub-task, status (done, in progress, failed, next, not started), then each gate and whether it's been called.
2. Each stage
- Start it. Move the stage's sub-task to In Progress, assigned to the user. It stays In Progress for all of the stage's commands.
- Give the command. Say the stage's number and title and what it proves (for its first command), then the next command exactly as the runbook has it, in a code block. Name any value the user must fill in and where it comes from. Then say what output to expect, in the runbook's words, and anything to blank out before pasting.
- Wait for the output. Don't guess what it will be.
- Check it against what the runbook expects: pass, fail, or unclear, with the reason in one line. For unclear, ask for the one extra thing you need (another command from the runbook, or more of the output).
- Record it in the working copy's Record block for the stage as you go: which commands have run, their results, the time, and