Runbook — generate the per-repo operational card
Produces .docs/runbook.md (or the docs folder this repo already uses — the runbook itself is what names that path for every other skill): the one card that carries everything project-shaped (IDs, tenants, checklists, deploy and git rules) so every other skill reads it instead of re-asking. This is the harvester that fills that card from context that already exists about the repo.
Sources to mine (in order — each fills part of the card)
- The repo itself — package manifests (stack, package manager, scripts),
.env.example / env key NAMES (never values), supabase/wrangler/vercel config, migrations, routes/edge functions, deploy scripts, CI. This is ground truth.
- Local Claude rules — the repo's
CLAUDE.md, .claude/settings.json, .claude/settings.local.json, AGENTS.md, .agents/. Pull repo-specific bans/identity (e.g. git/GitHub bans, committer identity, protected files, forbidden actions) straight into the card's git/deploy rules.
- Existing repo docs — architecture.md, decisions.md, integrations.md, any domain docs. Don't duplicate them; extract the operational facts (test tenants, IDs, deploy commands) into the runbook and cross-link.
- Agent memory — whatever persistent memory your setup keeps for this project (e.g.
~/.claude/projects/<slug>/memory/, or a memory MCP server). Mine recurring IDs, test accounts, known gotchas, deploy quirks.
- Past sessions — the repo's transcripts (e.g.
~/.claude/projects/<project-slug>/*.jsonl). Scan for values that got re-pasted (shop/tenant UUIDs, key IDs, webhook event lists, breakpoints, demo logins, "the test account is…", "deploy with…") — anything you had to be told more than once belongs in the card.
The card to produce
Only the sections that apply — drop the rest.
# <Repo> — Runbook
_Last refreshed: YYYY-MM-DD_
## Identity
Stack, package manager, runtime versions, entry point, hosting.
## Backend
Services, edge/serverless functions, cron jobs, queues.
## Test assets
Test tenants, demo logins, seed script, fixture data. Pointers to credentials, never the credentials.
## Health checks
One row per system: system → source of truth → passing threshold.
## Deploy & ship
Build/deploy commands, release channels, environments, git rules and any repo-level bans, dev-server port.
## Integrations
Per service: auth method, rate limits, dashboard URL, where its secret lives.
## Known IDs & constants
Anything that has been re-pasted more than once.
Rules
- Pointers, not secrets — "token in Keychain
X" / "env Y", never the value. If mining surfaces a raw secret in a session/config, flag it (→ hygiene) but do NOT copy it into the card.
- Verify, don't assume — a load-bearing value (tenant id, channel, deploy cmd) gets confirmed against the live repo/config before it's written as fact; tag anything uncertain
[unverified] for the user to confirm.
- Refresh-safe — if a runbook exists, update in place: add newly-discovered facts, correct stale ones, never clobber hand-edits.
- Report back short: written or updated, how many sections, which sources were mined, and any
[unverified] items needing confirmation.
1---2name: runbook3description: Build or refresh a repo's operational runbook by mining all available context — project code, agent memory, past sessions, and local CLAUDE.md/.claude rules. Use for "create the runbook", "build the runbook for this repo", "generate runbook", or the first time a skill needs a runbook that doesn't exist yet.4---56# Runbook — generate the per-repo operational card78Produces `.docs/runbook.md` (or the docs folder this repo already uses — the runbook itself is what names that path for every other skill): the one card that carries everything project-shaped (IDs, tenants, checklists, deploy and git rules) so every other skill reads it instead of re-asking. This is the harvester that fills that card from context that already exists about the repo.910## Sources to mine (in order — each fills part of the card)111. **The repo itself** — package manifests (stack, package manager, scripts), `.env.example` / env key NAMES (never values), supabase/wrangler/vercel config, migrations, routes/edge functions, deploy scripts, CI. This is ground truth.122. **Local Claude rules** — the repo's `CLAUDE.md`, `.claude/settings.json`, `.claude/settings.local.json`, `AGENTS.md`, `.agents/`. Pull repo-specific bans/identity (e.g. git/GitHub bans, committer identity, protected files, forbidden actions) straight into the card's git/deploy rules.133. **Existing repo docs** — architecture.md, decisions.md, integrations.md, any domain docs. Don't duplicate them; extract the operational facts (test tenants, IDs, deploy commands) into the runbook and cross-link.144. **Agent memory** — whatever persistent memory your setup keeps for this project (e.g. `~/.claude/projects/<slug>/memory/`, or a memory MCP server). Mine recurring IDs, test accounts, known gotchas, deploy quirks.155. **Past sessions** — the repo's transcripts (e.g. `~/.claude/projects/<project-slug>/*.jsonl`). Scan for values that got re-pasted (shop/tenant UUIDs, key IDs, webhook event lists, breakpoints, demo logins, "the test account is…", "deploy with…") — anything you had to be told more than once belongs in the card.1617## The card to produce18Only the sections that apply — drop the rest.1920```markdown21# <Repo> — Runbook22_Last refreshed: YYYY-MM-DD_2324## Identity25Stack, package manager, runtime versions, entry point, hosting.2627## Backend28Services, edge/serverless functions, cron jobs, queues.2930## Test assets31Test tenants, demo logins, seed script, fixture data. Pointers to credentials, never the credentials.3233## Health checks34One row per system: system → source of truth → passing threshold.3536## Deploy & ship37Build/deploy commands, release channels, environments, git rules and any repo-level bans, dev-server port.3839## Integrations40Per service: auth method, rate limits, dashboard URL, where its secret lives.4142## Known IDs & constants43Anything that has been re-pasted more than once.44```4546## Rules47- **Pointers, not secrets** — "token in Keychain `X`" / "env `Y`", never the value. If mining surfaces a raw secret in a session/config, flag it (→ hygiene) but do NOT copy it into the card.48- **Verify, don't assume** — a load-bearing value (tenant id, channel, deploy cmd) gets confirmed against the live repo/config before it's written as fact; tag anything uncertain `[unverified]` for the user to confirm.49- **Refresh-safe** — if a runbook exists, update in place: add newly-discovered facts, correct stale ones, never clobber hand-edits.50- Report back short: written or updated, how many sections, which sources were mined, and any `[unverified]` items needing confirmation.
danielimad