How Code Moves
How code moves from a branch to production, the checks it passes, and the decisions that stay with people.
How Product Work Moves explains how an issue moves from intake to done. This page explains how the code for it moves from a branch to production. How We Ship covers the release rhythm and hotfixes.
The same rules apply to people and to coding agents (Codex, Cursor, Claude). Where a rule can be checked by a machine, it is: CI, the AI review or an agent permission.
Branches
Every branch is named after its Linear issue, with the issue ID in lowercase and nothing else:
| Issue type | Branch |
|---|---|
| Feature | feature/dev-1234 |
| Bug | bug/dev-1234 |
Work without an issue gets one before it gets a branch. The rule applies to branches that coding agents create, too; only Dependabot names its own branches.
The validate / checks CI check fails on a pull request whose branch has another name.
Commits
A commit message says what the change does. It leaves out the issue ID: the branch name already ties every commit on it to the issue.
Before the pull request opens
The author runs the repo's lint, type-check and tests, then gets a fresh-context review of the change: a reviewer that hasn't seen the work, such as the local-review skill. Problems found here cost no reviewer time, so they are fixed before anyone is asked to look.
The pull request uses the repo's template. What and why, Testing, Risk and How to revert are all answered; "not tested" is allowed with a reason, an empty section isn't. An agent can draft the description, and the author reads and owns it before asking for review.
Pull request size
A pull request over 400 changed lines is hard to review well. Lockfiles, snapshots, generated files and files copied from harness don't count.
Over the limit, CI warns and the AI review suggests a split. Neither blocks the merge: some changes can't be split, and the author says why in the description.
Required checks
Every change reaches main or master through a pull request. It merges only when:
validate / checksis green on a branch that is up to date with the base. It runs the repo's lint, type-check and tests, checks the branch name, and fails when a file copied fromharnesswas edited in the repo.- One person approves it who didn't push its last commit. A new commit dismisses earlier approvals, and a bot's approval doesn't count.
- Every review thread is resolved, the AI review's included.
A failing check is fixed, never skipped. A flaky test is fixed right away; it doesn't get deleted or marked skip to get a pull request green.
The AI review
Codex reviews every pull request before a person does. It follows the repo's REVIEW.md, which says what counts as a P0, P1 or P2 finding in that repo and what to skip.
Every finding is fixed, or answered with the reason it isn't, and then resolved. After a fix, the author asks for a new review with @codex review. A pull request merges only after the AI review has finished.
Codex also runs a security review on every pull request. It follows the repo's SECURITY.md, which says what the repo protects, where its trust boundaries are and which patterns to flag. A security finding is a review thread like any other, so it blocks the merge until it's fixed or answered and resolved.
The AI review doesn't replace the human approval: it takes the line-by-line checking off the reviewer, who can then judge the change itself.
Endpoints and metrics
An endpoint change updates the repo's Postman collection in postman/ in the same pull request. CI warns, on the changed route file, when a routes.ts changes and nothing under postman/ does, and the AI review flags it too.
A new metric ships with its Grafana panel, in the same pull request. In virgo-api, a test fails when a registered metric appears on no dashboard, and the AI review flags a new endpoint, consumer or external call that no metric measures.
Database and ClickHouse changes
Migrations run only after merge, through CI. Nobody applies a migration to production from a laptop or an agent session, or before its pull request is merged. A migration applied early runs code nobody has approved, and a revert can't take it back.
ClickHouse schema and access change only through Virgo's provisioner. That covers tables, views, users, roles, dictionaries and named collections, for every tenant. Every DDL statement uses ON CLUSTER, and cluster_2S_2R is the only cluster. Nobody runs DDL by hand on a production node: the FX named collection was once created by hand on one node, and the dictionary failed on all of them.
Production changes ship through CI. Nobody queries or writes to production databases or ClickHouse from an agent session, and secrets never go into code, SQL, scripts, tests or fixtures.
Agent permissions
Each repo ships its agent rules: AGENTS.md for the context and rules, plus hooks that block what must never happen. The hooks run in Claude Code, Codex and Cursor, and stop an agent from:
- reading or editing
.envfiles - running
psql,pg_dumporclickhouse-clientagainst a host that isn't local - calling the production ClickHouse gateway, proxies, nodes or Keepers
- running migrations or ops scripts against a database or service that isn't local
A second hook sends the agent back to fix the errors when the repo's type-check fails. It gives up after three rounds in a row, so a broken base branch can't trap the agent.
The hooks are a guardrail against mistakes, not a security boundary. When one blocks something the work needs, the agent stops and asks a person; it doesn't look for a way around it.
What stays with people
Agents write code, run checks and draft descriptions. People make these decisions:
- Security boundaries: authentication, permissions, tenant isolation, secrets, and anything that changes who can read or write which data.
- Product calls: what the change should do, scope changes, and trade-offs the issue doesn't settle.
- What ships: approving a pull request, merging it, and releasing it to customers.
When an agent meets one of these, it asks instead of deciding.
When an agent keeps getting it wrong
After two corrections that didn't fix the problem, stop correcting. Start a new session with a better prompt: what the goal is, what went wrong, and the constraint the agent kept missing. A long session full of failed attempts steers the agent back to the same mistakes.
When an agent gets the same thing wrong twice across sessions, it goes into the repo's AGENTS.md under "Corrected twice", in the weekly harness review. If it keeps happening after that, it becomes a check or a hook.