Generate Operational Runbook

Analyze the codebase in depth and produce a docs/runbook/ directory with operational reference documentation. Scales from a single consolidated doc for small projects up to 10 separate pages for large monorepos. Upserts — creates new or updates existing runbook content.

Instructions

0. Check for existing runbook

Before launching any agents, check if a docs/runbook/ directory already exists.

• If it exists: Read docs/runbook/README.md and skim the other files. Use the existing structure, formatting, and still-valid content as a starting point. The explore agents should focus on finding new or changed information. When writing, preserve valid existing content, update stale sections, and add new discoveries — don't start from scratch.
• If it doesn't exist: Proceed normally from step 1.

1. Launch 3 parallel explore agents for codebase understanding

Launch these 3 agents simultaneously using the Agent tool with subagent_type: "Explore" and run_in_background: true. Each should do a thorough exploration of its assigned area:

1. Architecture & Stack — Read README, CLAUDE.md, package.json/go.mod/pyproject.toml/Cargo.toml, monorepo config (turbo.json, pnpm-workspace.yaml, nx.json, Cargo workspace), and source directory structure. Identify all services/apps/packages, their runtimes, how they communicate, database setup, auth system, key frameworks and libraries with versions.
2. Operations & Infrastructure — Explore Dockerfiles, docker-compose files, CI/CD workflows (.github/workflows/, .gitlab-ci.yml, Jenkinsfile), deployment configs (render.yaml, fly.toml, vercel.json, k8s manifests, Pulumi/Terraform), scripts/ directory, environment variable templates (.env.example), and observability setup (logging, metrics, tracing, error tracking).
3. Development & Testing — Explore dev scripts, test configurations (vitest/jest/pytest/go test), E2E test setup (Playwright/Cypress), test fixtures, seed scripts, linting config, hot-reload setup, and any existing docs/ or guides/. Also check for security patterns (auth guards, middleware, compliance requirements).

Wait for all 3 agents to complete before proceeding.

2. Assess project scope and choose document structure

Based on exploration results, assess the project's complexity:

Small project (single app, simple deployment, 1 database, no CI/CD or minimal):

• Produce 1-2 files: a single README.md runbook covering all topics in consolidated sections, plus optionally a troubleshooting.md if there's enough to say.

Medium project (multiple packages or a backend+frontend split, CI/CD, some infrastructure, testing):

• Produce 3-6 files: separate pages for the topics that have substantial content. Combine thin topics into a single page (e.g., merge "database" into "architecture" if there are only a few tables, merge "security" into "deployment" if there's no compliance framework).

Large project (monorepo with multiple services, complex infrastructure, multiple deployment targets, compliance/security requirements, extensive testing):

• Produce up to 10 files: one per topic where each has enough depth to warrant its own page.

The candidate topics (include only those relevant to the project):

3. Write the runbook

For each file, write content that goes deeper than the README. The audience is an engineer who needs to develop, deploy, debug, or maintain the system.

Content guidelines:

• Use actual values from the codebase: real file paths, real env var names, real port numbers, real commands
• Include tables for structured data (ports, env vars, services, commands)
• Include code blocks for commands and config examples
• Include diagrams (ASCII art) for service maps and request flows where helpful
• Reference specific source files that an engineer would need to read
• For troubleshooting: structure as Symptom → Cause → Fix
• Never include secret values — only variable names

README.md must always include:

• Table of contents linking to all other runbook pages
• Quick-reference table: ports, key commands, health check endpoints

4. Report completion

Tell the user:

• How many files were created/updated
• The document structure chosen and why (small/medium/large)
• A brief summary of the key operational details captured