Agentic PR Workflow skill for Codex

An agent PR is trustworthy when its scope is obvious from the title, every claim in the description is backed by a command and result the reviewer can rerun, nothing outside the stated scope changed, and the reviewer knows exactly where human judgment is needed.

Ground rules

• One concern per PR. Unrelated cleanups go in a separate PR or a follow-up list.
• Never push, open, merge or force-push without explicit user confirmation in this conversation. Merging is always a human action.
• Never weaken a check to make it pass: no deleted or skipped tests, no new @ts-ignore, # type: ignore, eslint-disable or noqa without stating why in the description.
• Read AGENTS.md first for branch naming, commit style, test commands and any ## Code Review Rules section.

Workflow

- [ ] 1. Branch from an up-to-date base
- [ ] 2. Make the change in reviewable commits
- [ ] 3. Run the pre-PR gates
- [ ] 4. Self-review the diff with Codex review
- [ ] 5. Write the PR description from evidence
- [ ] 6. Confirm, push, open as draft
- [ ] 7. Handle review comments and CI

1. Branch

git fetch origin
git switch -c codex/<short-slug> origin/main    # follow AGENTS.md naming if it differs

Work in a worktree when another task is in progress (see codex-parallel-worktrees).

2. Reviewable commits

• Separate mechanical changes (renames, moves, formatting) from behaviour changes; a reviewer can skim the first and must read the second.
• Each commit builds and passes tests when feasible.
• Messages say why, not only what. Follow the repo’s convention (Conventional Commits if used).
• In workspace-write, .git is read-only, so commits need approval; batch them at logical points rather than asking for approval on every small edit.

3. Pre-PR gates

Run the project’s own commands from AGENTS.md; a typical set:

npm run lint && npm run typecheck && npm test           # or the repo's equivalents
git diff --stat origin/main...HEAD                       # scope check
git diff origin/main...HEAD --name-only | rg -v '^(src/billing|tests/billing)/' || true   # files outside scope
git diff origin/main...HEAD | rg -n -i '(api[_-]?key|secret|token|password)\s*[:=]' || true
git diff origin/main...HEAD | rg -n '^\+.*(ts-ignore|eslint-disable|noqa|type: ignore|\.skip\(|xit\(|@Disabled)' || true
git diff origin/main...HEAD --stat -- '*lock*' '*.snap'  # unexpected lockfile/snapshot churn

Every hit in the last four commands needs either a fix or a sentence in the PR description.

Size guide: under ~400 changed lines of non-generated code reviews well. Above that, split (stacked PRs or preparatory refactor first) unless the change is mechanical.

4. Self-review

codex review --base main               # non-interactive review of the branch diff
codex review --uncommitted             # before committing

Or /review in the TUI or IDE (base branch, uncommitted changes, or a commit). Fix real findings; list deliberate non-fixes in the description. review_model in config can point reviews at a stronger model.

5. PR description

Write it from evidence gathered above, not from memory of intent:

## What
Adds per-tenant rate limiting to public API routes (token bucket, Redis-backed).

## Why
Tenants can exhaust shared capacity (#482). Spec requires burst tolerance.

## Changes
- src/middleware/ratelimit.ts: token bucket + Redis adapter (new)
- src/server.ts: registers middleware after auth (L40-75)
- docs/api/limits.md: limits and headers

## Verification
| Check | Command | Result |
|---|---|---|
| Unit + integration | `npm test` | 1,302 passed, 0 failed |
| Types / lint | `npm run typecheck && npm run lint` | clean |
| Latency | `make bench` | p95 41ms -> 42ms |

## Risks and review focus
- Redis outage behaviour: fails open (allows requests). Please confirm this is acceptable.
- Not covered: websocket routes (follow-up #495).

## Authorship
Prepared with Codex (model: gpt-6.1-sol, session <id>). Reviewed by the agent with
`codex review --base main`; human review required.

6. Confirm, push, open as draft

Ask first, showing branch, commit count and target:

Ready to push codex/rate-limit (4 commits) and open a draft PR against main. Proceed?

After a clear yes:

git push -u origin codex/rate-limit
gh pr create --draft --base main --title "Add per-tenant API rate limiting" --body-file pr-body.md

Push needs network access and credentials; if the sandbox blocks it, hand the commands to the user instead of widening access.

7. Review comments and CI

• Fetch comments (gh pr view --comments, or the review UI), then address each one: change the code, or reply with the reason it stays. Never resolve a thread silently.
• Push follow-up commits during review; do not rebase or force-push an open PR unless the reviewer asks, because it breaks “changes since last review”.
• After pushing, reply with a summary: “Addressed 5/6 comments in a1b2c3d; kept X because Y.”
• CI failure: read the failing job log (gh run view <id> --log-failed | tail -n 200), reproduce locally, fix forward with a new commit, rerun the gate locally first.
• On GitHub with Codex code review set up, @codex review on the PR requests another review pass; repo-specific checks belong in ## Code Review Rules in AGENTS.md.

Gotchas

• Descriptions that claim “all tests pass” without the command and count are not evidence; reviewers learn to ignore them.
• Agent PRs often carry stray changes: formatting of untouched files, lockfile churn, debug logging. The scope check catches them; revert, do not explain them away.
• Generated files (snapshots, lockfiles, codegen) should be regenerated by the tool, not edited by hand, and called out in the description.
• A green CI run on a draft does not replace the local gates when CI skips jobs on drafts.
• Keep the session id in the description; it lets a reviewer inspect how a decision was reached.