> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Development

> The standard workflow for parallel agent work, pull requests, integration, and main branch history.

## Operating model

**Current mode: direct pushes to `main`.** The owner has authorized direct pushes to `main` as the standard workflow. Work happens on `main` in the canonical checkout; commits are pushed directly without pull-request ceremony, and the staging/Vercel QA lane is skipped unless the owner requests it for a specific change. The Builder/Integration model below remains the reference for any change the owner flags for staged QA, and becomes the default again if this mode is revoked.

Direct-to-main does not relax the safety rules; they become local-verification requirements:

* Run checks proportional to the change before pushing (same evidence table as below).
* Keep `CHANGELOG.md` and the applicable living docs current in the same commit series.
* Push only fast-forward updates. The history-integrity ruleset still blocks force-pushes, resets, and branch deletion on `main` and `staging` for every actor including `DevelopedByDev`.
* Root `vercel.json` must keep `git.deploymentEnabled.main` set to `false`. After each push, verify that no production Vercel deployment was created.
* Keep commits to one coherent change each; the absence of a PR boundary is not license to mix unrelated work.

Overlay uses two agent roles. A Builder works in one isolated worktree and normally submits a pull request to `staging`. The Integration agent reviews and merges the owner-selected candidate base, tests the required revision, and promotes or deploys it according to the explicit release choice. The canonical checkout stays clean and remains the trusted source for production operations.

GitHub pull requests, checks, and commit history are the authoritative integration record. Do not maintain a second hand-written queue of open pull requests: it will drift. [`CHANGELOG.md`](https://github.com/LayerNorm/overlay-web/blob/main/CHANGELOG.md) is the concise record of changes that actually reached `main`.

## Reusable role prompts

When assigning work, tag [`BUILDER_AGENT_PROMPT.md`](https://github.com/LayerNorm/overlay-web/blob/main/docs/develop/BUILDER_AGENT_PROMPT.md) for implementation and PR submission, or [`INTEGRATION_AGENT_PROMPT.md`](https://github.com/LayerNorm/overlay-web/blob/main/docs/develop/INTEGRATION_AGENT_PROMPT.md) for review, staging QA, promotion, and production verification. These prompts restate the role boundaries below so an agent can execute the workflow without relying on a shortened task description.

## Roles

| Role              | Responsibility                                                                                                                                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Builder           | Owns one worktree and branch, implements one coherent change, runs focused validation, updates documentation and `CHANGELOG.md`, and opens a pull request against `staging`. The Builder stops at PR submission. |
| Integration agent | Reviews the change, resolves integration conflicts, merges it into `staging`, runs staging QA, promotes the tested `staging` revision to `main`, and verifies production.                                        |

Do not require separate Reviewer or Release Authority agents. The Integration agent owns those responsibilities so each change normally consumes only one Builder and one Integration agent.

Before Integration acts, it asks the owner: “Should this use a pull request or the owner-only direct-push fast path?”, “Should it target `staging` or `main`?”, and “Should Vercel deploy after integration; if so, staging or production?” If the current request already answers a question, the agent records that choice instead of asking again. The default remains a pull request to `staging` for hosted QA and no production Vercel deployment unless explicitly authorized.

## Owner-only direct pushes

Repository rules require pull requests and status checks on `main` and `staging` for every actor except the specific `DevelopedByDev` user. This exception is a release-velocity option for the owner, not the default agent workflow. An agent authenticated as `DevelopedByDev` may use it only when the owner explicitly requests a direct push for the current task; full access, account identity, or an earlier instruction is not authorization.

Two stacked rulesets keep the exception narrow:

* **Pull requests and checks** requires a pull request, conversation resolution, and the configured CI/security checks. Only `DevelopedByDev` has an always-bypass for direct pushes; repository administrators retain a PR-only bypass for stuck checks.
* **History integrity** blocks branch deletion and non-fast-forward updates to `main` and `staging` with no bypass actors. The owner exception therefore cannot be used to force-push, reset, or delete either branch.

Before an authorized direct push, fetch the target, verify the local target matches its remote, review the complete outgoing commit range and diff, run checks proportional to the change, and confirm the update is fast-forward. Push from the dedicated target worktree without force, then verify the remote SHA and post-push Actions. A direct push to `main` still requires the `CHANGELOG.md` and living-doc updates that a PR would carry, plus confirmation that no unauthorized production Vercel deployment was created.

A direct push to `staging` normally starts its branch-gated Vercel build. If the owner declines a staging deployment, do not push `staging` until the deployment trigger is deliberately suppressed or the owner chooses a different target.

## Worktree ownership

Worktrees are scoped to active work, not to every pull request:

* Each active Builder task gets one isolated `codex/<slug>` feature worktree. That worktree belongs to the Builder until the pull request is handed off.
* The Integration agent reuses one long-lived sibling worktree, `../overlay-landing-staging`, checked out on `staging`, for every sequential Builder pull request. After a merge, fetch and fast-forward that same worktree to `origin/staging`; do not create or retain a new Integration worktree for each PR, and do not check out feature branches in the staging worktree.
* Keep the canonical `main` worktree separate and clean for production operations. It is not an Integration scratch area.
* A short-lived temporary worktree is justified only for an exceptional conflict reproduction or side-by-side investigation. Remove it after the investigation and confirm its branch is no longer needed.

This keeps the working set small while preserving isolation: GitHub pull requests and the `staging` branch remain the integration record, and the dedicated staging worktree is the single local checkout used for staged QA.

## Start every task from `origin/main`

Fetch before creating the worktree. Never assume the local `main` branch is current.

```bash theme={null}
cd ~/Downloads/overlay-mono/overlay-landing
git fetch origin
git worktree add ../overlay-landing-<slug> -b codex/<slug> origin/main
cd ../overlay-landing-<slug>
```

Use a short, descriptive slug such as `agent-memory-retrieval` or `project-navigation`. One worktree belongs to one branch and one task. Agents must not share a feature branch or edit the canonical `main` checkout.

If a task depends on an unmerged pull request, branch from that pull request's reviewed head and declare the dependency in both pull requests. Otherwise, branch from `origin/main`.

## Make reviewable commits

Commits should describe reversible units of behavior. Keep tests and the documentation for a behavior change in the same commit when practical. Do not mix formatting, generated files, refactors, and unrelated product behavior merely to make the worktree clean.

Before opening a pull request:

1. Fetch `origin/main` and inspect the divergence.
2. Rebase or merge the latest `origin/main` into the feature branch before review when the base has moved materially.
3. Resolve conflicts by understanding both changes; never choose an entire side mechanically.
4. Run checks proportional to the changed surface.
5. Update the applicable living documentation and `CHANGELOG.md`.
6. Push the branch and open a focused pull request with `staging` as its base.

The Builder's handoff ends when the pull request is complete and ready for integration. Rewriting unpublished local commits is fine. Once integration review or staging QA has started, force-pushing or rewriting commits invalidates the recorded evidence and requires a fresh review.

## Pull request contract

Every pull request must state:

* the user or operational outcome;
* the important implementation decisions;
* touched systems and known dependencies;
* risk and rollback approach;
* exact checks run and their results;
* staging or browser evidence when the behavior needs it;
* migration, environment, Convex, or deployment steps;
* the base and tested head commit when release provenance matters.

The pull request is the detailed change record. `CHANGELOG.md` stays user-focused and concise.

## Checks should match risk

Overlay does not require the maximum possible gate for every change. It requires enough evidence for the actual risk:

| Change                                                       | Minimum evidence                                                                            |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Documentation only                                           | Link/docs health checks and review of rendered structure.                                   |
| Isolated UI behavior                                         | Targeted lint or tests plus visual QA at affected breakpoints.                              |
| Shared contract or cross-package code                        | Targeted tests and full typecheck.                                                          |
| Auth, billing, tenant boundaries, secrets, or data migration | Relevant security/contract tests, explicit rollback, and staging verification.              |
| Convex or production runtime behavior                        | Staging web and backend on the same revision, followed by production smoke after promotion. |

Required GitHub checks remain mandatory. Zero approving reviews is intentional for the current sole-maintainer setup; do not add a gate that the pull-request author cannot satisfy. The Integration agent performs the substantive review and may request Builder changes when evidence or implementation is incomplete.

## Preserve meaningful history

The default merge method is a **merge commit** when the pull request contains meaningful, reviewed commits. This preserves the exact branch commits, the pull-request boundary, and the ability to revert one independent commit without undoing the whole change.

Use a **squash merge** when the branch history is disposable—for example, a trivial one-commit change or a branch full of fixups that do not represent independently valid states. Rebase merging is disabled because it rewrites commit identities and loses the explicit integration boundary.

History preservation does not make a broken commit safe. Every commit retained through `staging` and `main` should build or be an intentionally inseparable part of the pull request. The Integration agent may ask the Builder to clean up a noisy history before merging.

To undo a retained commit, use `git revert <commit>`. To undo an entire merge-commit pull request, use `git revert -m 1 <merge-commit>`. Never reset or force-push `main` to perform a production rollback.

## Integration procedure

The Integration agent owns the change from PR review through production verification:

1. Before accepting a candidate, confirm `staging` contains the current `origin/main`. If it does not, synchronize `main` into `staging` without rewriting either branch, then verify the resulting tree.
2. Confirm the Builder PR targets `staging` and records its head SHA, scope, dependencies, risk, validation, and changelog entry.
3. Read the diff and relevant surrounding implementation. Test evidence is not a substitute for review.
4. Confirm which PRs are already present in `staging`. Prefer one release candidate at a time; if several PRs are intentionally batched, list and test the complete batch.
5. Verify the required checks, resolve conflicts deliberately, and merge the Builder PR into `staging`. Prefer a merge commit for meaningful commits; squash only disposable fixup history.
6. Test the exact resulting `origin/staging` SHA using the staging web and matching development Convex deployment. Record the SHA and evidence.
7. If `staging` or `main` changes after QA begins, incorporate the new state into `staging` and repeat the affected QA. Never promote a revision different from the one tested.
8. Open or update a release pull request from `staging` to `main`. Include every Builder PR in the candidate, the tested staging SHA, checks, rollback notes, and deployment steps.
9. Confirm root `vercel.json` still sets `git.deploymentEnabled.main` to `false`. After the release PR checks pass, merge it with a merge commit, verify the resulting commit on `origin/main`, and verify that Vercel created no production deployment for that SHA. The merge leaves that SHA merged but not deployed.
10. Fast-forward `staging` to the accepted `origin/main` merge commit before the next Builder PR. This keeps the two long-lived branches aligned without force-pushing and prevents the next review from containing old release-history differences.
11. Stop unless the user explicitly authorizes production deployment. When authorized, deploy the accepted `origin/main` revision from the clean canonical `main` worktree, verify the production web deployment, deploy production Convex when applicable and only after the web deployment is live, then run the production smoke test.

An administrator's pull-request-only ruleset bypass is for a demonstrably stuck or broken gate, not for skipping relevant validation. The `DevelopedByDev` direct-push bypass is available only through the explicit owner fast path above. Force-pushing and deleting `main` or `staging` remain prohibited by the separate history-integrity ruleset.

## Staging and production QA

The shared `staging` branch and staging Vercel project are the only hosted pre-production lane. Builder pull requests target `staging`; feature branches do not produce hosted previews. The Integration agent tests after the Builder PR reaches `staging`, then promotes `staging` through a separate pull request to `main`. Root `vercel.json` disables Git-triggered deployments for `main` while leaving `staging` available for hosted QA, so promotion and production deployment are separate, explicitly reported states. Do not rely on an account-level deployment-source policy alone; verify the source-controlled rule and the absence of a production deployment after every release merge.

The staging project is explicitly branch-gated to `staging` to prevent PR and other branch builds from consuming Vercel build minutes. Its Ignored Build Step runs `scripts/vercel-ignore-build.sh` with `DEPLOY_BRANCH=staging` in both Vercel environments. For that staging target the guard fails closed: only an exact `staging` Git ref runs a build; missing refs (including manual or hook-triggered deploys), unset targets, and every other branch are skipped. The shared script preserves no-ref manual releases for any separate, explicitly configured target. Preview deployment sources stay disabled. Verify these project settings when rotating Vercel projects or credentials.

Follow [Worktree Staging QA](/docs/develop/worktree-staging-qa) for staging integration, Convex deployment boundaries, smoke tests, and production promotion. A successful pull-request check does not prove the staging or production UI, and an HTTP response does not prove an authenticated browser flow.

## Maintain the changelog

Every pull request that changes user-visible behavior, developer workflow, deployment behavior, data, security posture, or operations adds a concise item under `Unreleased` in root `CHANGELOG.md`. Pure maintenance may omit an entry only when the pull request explains why it has no meaningful release impact.

At release time, the integration agent moves the shipped `Unreleased` entries into a dated section and leaves a fresh `Unreleased` heading. Link pull requests where that improves traceability; do not copy implementation detail already preserved in the pull request and Git history.

## Clean up completed work

After merge and verification:

```bash theme={null}
git fetch origin
git merge-base --is-ancestor <feature-head> origin/main
git worktree remove ../overlay-landing-<slug>
git branch -d codex/<slug>
```

The ancestry check works directly for merge commits because the feature head is retained. For squash merges, verify the pull request's merged state and resulting commit instead; the original feature head will not be an ancestor of `main`.