Skip to content
Opleet v2

Backend runbook

Moved here from the Google doc [Runbook] v2 backend: database and migration on 2026-10-07 (D28), with its step IDs unchanged.

Owner: @zuki · Written by the Backend Engineer · Last reviewed: 2026-10-07 · Conforms to the decisions through D29

The steps the Backend Engineer writes and zuki runs for the v2 database and the v1 to v2 migration, one page per phase or module.

How this runbook works

Section titled “How this runbook works”
  • The rules are in How we work and the runbook step format. This runbook follows them and the decisions, and never overrides them.
  • The Backend Engineer session writes the steps; zuki runs them. zuki logs each run as a comment on the pack's issue (D28): the date, what ran and the output that mattered. A step is done when its issue shows a clean run by zuki.
  • One page per phase or module, each with three sections: Applies (the decisions that govern the work), Interface (the functions, views and error keys the Frontend Engineer builds against, with their status), and Steps. In M0 every step has a page of its own.
  • The Frontend Engineer asks for what it needs in an issue labelled role: backend, naming the module. The Backend Engineer answers with a step pack and records the answer under Interface on that module's page.
  • How a pack reaches the repository. In M0, zuki copies each pack in from a zip, one step at a time, and opens its pull request, as the steps say. From the data phase on, the Backend Engineer opens each pack as a pull request through the Claude GitHub app, with its tests green in CI; zuki reviews and merges it, and runs by hand only what touches his Mac, staging or production (D28).
  • Every change to this runbook is a pull request from the Backend Engineer session, through the Claude GitHub app; zuki reviews and merges it (D28).
  • Commands are pnpm first, for zsh on zuki's Mac. Copy one numbered block at a time; each code block has a copy button. Secrets appear only as placeholders such as <STAGING_DB_PASSWORD>.
  • Stamp: at the end of each session, the Backend Engineer updates "Conforms to the decisions through Dn" above, in the same pull request.

Step format

Section titled “Step format”

Every step follows the runbook step format: ID and level at the top, then Goal, Before, Run, Expect, Check, If it fails, Undo and Runs as sections. Runs logged before 2026-10-07 stay in the page; later runs are comments on the step's issue.

Section titled “Related”