How we work
These are the register's working rules. They moved here with the decisions on 2026-10-07 (D28) and now describe working in GitHub. Together with the accepted decisions, they outrank every other v2 doc.
Read them in full at the start of every working session. zuki may still change them, by merging a pull request; until he does, follow them as written. The automation ladder, the runbook step format and how rules are written are working rules too.
Order of authority
Section titled “Order of authority”When two sources disagree, the higher one wins, whatever their dates. A newer doc never outranks an older decision.
- Decisions and working rules: every accepted page under Decisions, and the working rules under Contributing. Only zuki accepts a decision.
- Specs: what to build, in the rule pages under System (D27) and the [Spec] Google docs not yet moved here. They must agree with the decisions.
- References: what exists, in the generated pages under Reference (D27) and the [Ref] Google docs not yet moved here. Generated from the code where possible.
- Guides and runbooks: how to do it, in the pages under Build and Operate and the [Guide] and [Runbook] Google docs not yet moved here.
- Background: the design canvas boards, chat transcripts, Slack threads, agent notes and the discussion in issues and pull requests. Useful history, never binding.
Intent and fact are kept apart. The decisions and the specs say what v2 should be; the migration files, the code and the references generated from them say what v2 is. When the two differ, either the code has a bug (fix the code) or the intent has to change (open a change request). Nobody closes the gap by quietly editing a doc.
This replaces the older order "migration files, then the plan, then the wiki, then the canvas". The migration files are still the truth about the schema as built, but they don't outrank a decision.
| Role | Who | Owns | Never |
|---|---|---|---|
| Owner | zuki | Accepting decisions, by merging their pages; deciding change requests; every run against staging or production; every promotion on the automation ladder; reviewing and merging every pull request (D27, D28) | |
| CTO | A Claude session in the SaaS Principal Engineer project with no other role named | Audits, drafts decisions and spec changes, keeps the decisions, these working rules and the timeline: its run order and its TL steps (workstation, repository and root tooling, CI, accounts and hosting), and the rule format and rule check in apps/docs (D27) | Writes production code; accepts its own drafts |
| Backend Engineer (BE) | A Claude session started with the BE prompt | supabase/, tools/db and tools/migration: migrations, Postgres functions, RLS and Storage policies, pgTAP tests, the nightly rehearsal. [Runbook] v2 backend: database and migration, including each module's Interface section | Edits the working rules or decisions; changes apps/web |
| Frontend Engineer (FE) | A Claude session started with the FE prompt | apps/web: pages, server actions, the database integration (generated types, RPC calls, error keys), Indonesian-first copy and labels, the design system in use, Playwright journeys. [Runbook] v2 frontend: web app | Edits the working rules or decisions; changes supabase/ |
| Docs Engineer (DOC) | A Claude session started with the DOC prompt | The written pages under System: each domain's rules with IDs, examples, error keys and roles, and the list of domain codes; moving [Spec] and [Ref] docs into apps/docs as their domain comes up | Writes tests, app code or decisions; edits generated pages; changes supabase/ or apps/web |
Every agent role works in the repository only through the Claude GitHub app, on branches and pull requests, and never merges (D28).
The Frontend Engineer asks for a new function, view or column by writing it under Interface in the backend runbook's module tab; the Backend Engineer answers with a step pack. Both work from the rules the Docs Engineer writes in apps/docs (D27). A new role, such as the backend API or the driver app, gets a row here before its first session.
Where docs live
Section titled “Where docs live”- Every v2 doc lives in apps/docs (D28): decisions under Decisions; rules, architecture and the glossary under System; generated pages under Reference; the timeline, runbooks and guides under Build; production runbooks under Operate, later; how we work under Contributing.
- A Google doc stays in force until its page merges here. On that day it gets a first line naming the new page and moves to 99 Archive. Until then, [Ref] Opleet v2 knowledge base maps the Google docs that are left.
- Product and process docs that team leads comment on stay in Drive.
- Agents never create docs in the Opleet Wiki. They write pages in apps/docs for the sections their role owns, through pull requests that zuki merges, and they discuss in issues.
- No new [Decision] docs. A decision is a page under Decisions. The two existing [Decision] docs stay as the long-form record behind D2 and D9.
- Long topics grow pages inside their section, not new sections. A new top-level section needs a decision.
Issues and the board
Section titled “Issues and the board”- Every task, open question, change request and decision proposal is an issue in Opleettop/monorepo (D28), opened from its form and labelled with its type and the role that owns it. The Opleet v2 board holds its status.
- A run of a step is logged as a comment on its issue: the date, what was run, and the output that mattered. The issue closes when the step or pack is done.
- Docs carry outcomes, never discussion. The discussion stays in the issue or the pull request; what it settles lands on a page.
- A pull request names what it closes ("Closes #26") and the decisions and rules it applies.
How a decision is made or changed
Section titled “How a decision is made or changed”- Someone raises it as an issue: an open question, or a change request when it conflicts with something already decided.
- A CTO session drafts it: the options and a recommendation, in the issue or in a decision proposal issue when it spans several. When zuki has chosen, the CTO session opens a pull request that adds the decision's page under Decisions, dated the day it is ready to merge, and changes every page the decision touches. A doc it can't change in the same pull request gets a task issue, labelled for its owner.
- zuki accepts it by merging, asks for changes in the review, or rejects it by closing the pull request. Merging closes the question or request.
An accepted page is never rewritten. To change it, a new decision supersedes it, and only the old page's status line changes, to "Superseded by Dn". Typos and broken links can be fixed in place.
How executors stay in line
Section titled “How executors stay in line”Every Backend Engineer, Frontend Engineer and Docs Engineer session follows this loop.
- Start: read the working rules, every decision newer than the conformance stamp on your runbook, and your open issues (your role's label).
- Before planning a module: list the decisions that apply under Applies in its runbook tab. Where your plan conflicts with one, change the plan.
- When a decision looks wrong or impossible: stop that item, open a change request with the evidence (error output, data, a failing test), and carry on with other work. Never work around a decision.
- End: update your runbook, comment on your issues with what changed and what is left, and stamp each runbook you touched: "Conforms to the decisions through Dn".
In the docs they own, executors may change anything that doesn't contradict a higher doc: steps, implementation detail, their own pages. The test: if your edit would make a sentence in a higher doc untrue, it is a change request, not an edit. In the timeline, executors change only the step IDs of their own rows, and may add a row marked Proposed; only a CTO session or zuki reorders rows or changes a TL step.
- D1, D2 and on: decisions, numbered in order and never reused, one page each. The next is D30.
- OQ1 to OQ24 and CR1: the open questions and the change request raised before the move. Their issues keep these IDs in their titles. Questions and change requests raised since are cited by issue number, such as #57.
- BE-M1-04, FE-M3-02: runbook steps. TL-M0-03: timeline steps, written by a CTO session. R-BC-03: rules in apps/docs, never reused (D27).
- Q1–Q9 and P1–P16 keep their names inside D9; M0–M7 are the modules.
Cite IDs wherever a doc, a commit message, a pull request or an issue depends on a decision, for example "per D14".