A runbook that checks itself against the running system.
A runbook says do X and you will see W. Nothing checks whether that is still true. vibe-runbook writes one by inspecting your app, then walks its claims against a running system — read-only, never spends, and honest about what it could not check. Every report says checked N of M enumerated.
Includes7 commands · 8 skills
Seven commands, from drafting a runbook to keeping it true.
Scan reads, walk checks, remediate rewrites, author drafts. The walk is read-only and never spends; the rewrite diffs by default and backs up every file it touches.
Inventory every claim.
Reads a runbook and classifies each claim by shape: a pin, a status assertion, a past-tense receipt, a question. Ambiguity escalates to a question instead of a guess, and the extraction reports its own confidence.
Reach for it before you trust a runbook, to see what in it a machine can actually check.
Check it against a named environment.
Walks the machine-checkable claims with six verdicts: PASS, FAIL, BLOCKED, SPENDS, HUMAN, QUESTION. Read-only, never spends, and --env is required. A missing credential hard-stops as BLOCKED with the exact ask instead of quietly walking your local machine.
Reach for it when you want to know which lines of the runbook are still true today.
Fix the stale pin.
Rewrites a stale pin as the command that answers it where the reader has a shell, or as the list it was summarizing where they do not. Diffs by default; --apply writes, with a backup beside every file it touches.
Reach for it after a walk shows a pin that went stale.
Draft the runbook from the repo.
Inspects the app and writes an operations runbook from what it can derive: a revision pin that answers itself, the run commands, deploy and rollback scripts where they exist, the names of the configuration keys. What a repo cannot tell you comes out as explicit questions. It proposes beside your runbook and never overwrites it.
Reach for it when the runbook does not exist yet, or the one you have was written from memory.
Health of the local state.
Checks the local vibe-runbook state.
Reach for it when a run behaves oddly and you want to rule out the plugin's own state.
Improve the plugin itself.
Reflects on past runs and proposes improvements to the plugin. Writes proposals; never edits a skill. Session logging is not wired yet, so it has little to draw from today.
Reach for it once the plugin has real runs behind it.
State-aware router.
Reads what exists (a cached scan, a config, a runbook) and recommends one next move. Never walks or writes on its own.
Reach for it when you are not sure which step comes next.
Honest about what it could not check.
A document that says it tested 17 rooms is not lying when there are now 12. So a receipt is reported and never failed: past-tense coverage records drift because the world moved. Pins are different. A pin is a value that identifies the running system, and the walk checks it. Enumeration is mechanical and exhaustive, never sampled, and every report states checked N of M enumerated.
Four invariants hold on every walk. Credential preflight hard-stops. Nothing spends: a billable check is reported as SPENDS with what a full walk would cost, and never run. No secret is printed: shapes, statuses and counts only. The contract source beats the guess: when the runbook is ambiguous about an interface, it reads the route table or client definition.
It earned those on a real service. Walked read-only against a live Cloud Run service's hand-written smoke list, it returned 5 claims PASS, 3 FAIL, and 8 of 8 numbered steps unreachable. The write-guard probe sent a request that fails validation against a resource that does not exist, and found six routes answering 422 with the missing field name instead of 401. All six were fixed the same day and re-walked.
The author is just as plain about its limits. Run against two real applications that already carry hand-written runbooks, it fabricated nothing: it wrote only what it could verify, asked for the rest by name, and listed what it failed to gather. Expect questions, not a finished document. Most of a real operations runbook is not in the repository.
Install.
Stable marketplace
Tagged releases, promoted via the Vibe Plugins marketplace.
/plugin marketplace add estevanhernandez-stack-ed/vibe-plugins /plugin install vibe-runbook@vibe-plugins
Read-only walk, and <code>--env</code> is required. Remediate diffs by default and backs up before <code>--apply</code> writes. Node engine with no runtime dependencies.
One plugin in a family.
Vibe Plugins are a coordinated family — installed independently, composed when present.
