D28 · We work in GitHub: Team plan, agents in the repository, docs in apps/docs

Accepted · 2026-10-07 · zuki · Supersedes D26 and the agent fork in D27 · Closes OQ23

Decision: The Opleettop organization is on GitHub Team with one seat, zuki's; the repository is Opleettop/monorepo. Agents reach it only through the Claude GitHub app, which takes no seat and is granted this repository alone. They push branches and open pull requests; they never merge. A ruleset on main requires a pull request with the checks and pr-title jobs green, allows squash merges only, and blocks force pushes and deletion; zuki merges. Staging and production secrets go into GitHub environments that only main can use, from TL-M0-20 on. The agent fork (TL-M0-25) is withdrawn.

Work is discussed and tracked in GitHub. Every task, open question, change request and decision proposal is an issue in the repository, labelled by type and role, on the Opleet v2 Project, which holds its status. A run of a step is logged as a comment on its issue. Docs carry outcomes, never discussion.

Every v2 doc moves into apps/docs now, not at the M0 exit check: decisions/ (this register, one page per decision, accepted by merging), system/ (rules, architecture, glossary), reference/ (generated), build/ (the timeline, runbooks and guides), operate/ (production runbooks, later) and contributing/ (how we work). On the day a page merges, its Google doc gets a first line naming the new page and moves to 99 Archive; until then the Google doc stays in force. Product and process docs that team leads comment on stay in Drive.

Why: One seat costs about $4 a month (OQ23). It protects main on GitHub's side, keeps secrets away from unreviewed branches and removes the fork's manual steps. Agents work better from files in the repository than from Google Docs, and issues keep each discussion next to the work it changes.

Consequences: TL-M0-28 sets up the ruleset, the app's access, Dependabot alerts, the labels and the Project. TL-M0-27 becomes the CTO's pull request that moves this register and the timeline, right after TL-M0-28. Each role moves its own runbook and guides as they are, and open questions and change requests become issues. A second person who contributes gets a seat and a member's write access, and the ruleset applies to him as to everyone.