PR workflow

PRs use GitHub's native PR number as the canonical identifier. Do not add a separate agent-specific letter prefix to titles. In chat, docs, commit notes, and stacked-PR comments, refer to PRs by number, for example #1101.

PR title format

<conventional commit summary>

Examples:

fix(onboarding): keep custom goal chips to a single line
feat(dev-docs): scaffold @todayai-labs/dev-docs Fumadocs site with deploy pipeline
ci(release): create dedicated backmerge branches

Use type(scope): description. Common types: feat, fix, docs, refactor, test, chore, and ci. Scope is usually a package or domain such as onboarding, dev-docs, auth, release, or admin.

Branch naming

<owner-or-purpose>/<topic>

Examples: codex/backmerge-release-branch, codex/onboarding-goal-single-line, feature/dev-docs-research, hotfix/web-auth-origin.

Agent-authored branches should use the default codex/<topic> prefix unless the user requests a different name. Human-authored branches may use the team's normal feature, fix, hotfix, or release prefixes. Keep the topic descriptive and stable enough to recognize in GitHub and local checkout lists.

PR body conventions

Each PR's title and body are the canonical record once the PR is squashed into dev. The squash commit message inherits the PR title (and optionally body), so be exhaustive.

For omnibus PRs that touch multiple themes, group commits by theme and list them individually in the body so reviewers can spot-check:

## Summary

Touches three subsystems.

### Auth (commits 1-3)

- Switch to host-only session cookie
- ...

### CI (commits 4-5)

- Add visual regression for dialog
- ...

### Docs (commit 6)

- Update local-development guide

If the PR depends on or is stacked on another PR, explicitly link it in the body:

Stacked on top of [#731](https://github.com/todayai-labs/today-platform-web/pull/731).

Test plan

PR bodies should include a "Test plan" section listing the gates that ran:

## Test plan

- [x] `pnpm typecheck` — green
- [x] `pnpm test` — 200 files / 2,095 tests, green
- [x] `pnpm --filter @todayai-labs/dev-docs build` — 23 routes generated
- [ ] CI Build / Typecheck / Lint / Format / Unit Tests / Visual Regression
- [ ] Manual review of the rendered docs on Vercel preview

The "Test plan" is the agent's contract that local gates ran before push, and the reviewer's checklist of what to look for. Unchecked items are expected to flip green during CI.

Merging

gh pr merge <n> --auto enables auto-merge — the PR enters the merge queue once required checks pass. Do not pass --rebase or --squash — the merge queue rejects strategy overrides with "merge strategy set by merge queue."

See Merge queue for what happens after auto-merge fires.

Common pitfalls

• Pushing to a queued PR cancels auto-merge. If you push a fixup commit after enabling auto-merge, run gh pr merge <n> --auto again to re-queue.
• Adding duplicate PR identifiers to titles. Do not prefix titles with PR-A, PR-JG, or similar labels. GitHub already assigns the durable PR number.
• Vague branch names. fix-stuff or misc-cleanup are hard to track in checkout lists and CI views. Use a short topic that names the change.