Skip to main content

Runbooks

What lives here: step-by-step operational procedures for humans โ€” incidents, deploys, recovery, environment setup, one-off but repeatable tasks.

Use vs. siblings: a Skill is an AI procedure (machine-executed); a runbook is a human procedure. A Methodology doc is why; a runbook is how to do it now.

Template: Runbook ยท filename: docs/runbooks/<name>.md

Step-by-step operational procedures. Each runbook is loadable via /runbook <name> once the command is wired in.

Availableโ€‹

  • install-bewith-plugin.md โ€” one-time per-developer setup that wires the bewith plugin into every Claude Code session.
  • uniform-ci.md โ€” the shared reusable lint/test/typecheck CI workflow, the per-repo caller, and the adoption sweep for existing repos (the CI hard gate).
  • repo-migration.md โ€” the per-repo procedure to onboard an existing repo onto the platform (CLAUDE.md, the CI caller, retiring legacy .cursor rules, verification). Automatable via /claude-init.
  • mobile-release-pipeline.md โ€” how a Flutter app ships to the Play internal track + TestFlight from one GitHub Actions pipeline, with all signing/store secrets pulled from one 1Password vault. Reference impl: leaders-app.
  • session-mission-control.md โ€” see every concurrent Claude session (the /sessions command, an HTML dashboard, a SwiftBar menu-bar plugin) and get notified when one needs you (the notify-attention hook), plus the permission allowlist that cuts the prompts.
  • claude-usage-menubar.md โ€” an optional SwiftBar menu-bar icon showing your Claude account usage (5-hour session + weekly limits), kept warm by a launchd LaunchAgent (producer/consumer, no network on the hot path).
  • claude-status-menubar.md โ€” the public status.claude.com health folded into the same menu-bar plugin: shows up only on an active incident, and annotates one when it names a model one of your live sessions is running on.
  • sentinel-triage.md โ€” read-only production/staging signal triage (/sentinel-check): verify in Loki, locate the code in GitHub, check the known-issue registry, return one JSON verdict. Runs on your subscription (no API key); needs the Grafana MCP added to the CLI.

Planned runbooksโ€‹

  • incident-response.md โ€” kick off, war-room link, status updates, post-mortem skeleton.
  • database-failover.md โ€” Aurora / MongoDB failover steps.
  • secret-rotation.md โ€” coordinated rotation across services (Hard Floor โ€” manual confirmation required).
  • deploy-rollback.md โ€” /rollback <tag> flow.
  • sandbox-recovery.md โ€” when the local infra-mcp stack is broken.

Conventionsโ€‹

Every runbook follows the template at /templates/runbook. The Process Guardian agent (when added) will verify runbook structure on PR.