Preflight
- Run the bundled
scripts/pr-preflightfrom the target worktree before review and again before publication. Never review or publish while blocked. - Inspect its prospective commits and complete diff for task scope.
- If the branch is default or spent, rebuild from the reported base with only intended commits, then rerun preflight.
- If base or head changes, repeat the affected review.
Review
- Use the preflight base and head; verify worktree HEAD before each review.
- Review the complete
base...headdiff. Report actionable findings and stop. - For every UI change, reuse supplied media or capture matched, reproducible before/after media from base and head:
- Use video for interaction, motion, or multiple steps; images otherwise.
- Match viewport, state, data, and action sequence.
- Keep media untracked through
.git/info/exclude. - Never publish with either side missing.
Package
- Use the repository PR template exactly when present.
- Title:
<type>(<scope>): <imperative summary>using the narrowest Conventional Commits type. Omit an unhelpful scope; reservestylefor formatting-only changes. - Add issue-closing syntax when the change resolves an issue.
- Do not invent template sections or include generic command output.
- Put UI
Before:andAfter:media under the best template heading. Without a template, use concise## Descriptionand optional## Comparison.
Publish
Immediately before publication, verify worktree HEAD equals the reviewed head. If not, restart preflight.
| Mode | Action |
|---|---|
| External repository | Write the exact body with local media references to DRAFT.md; write the exact title to .codex-pr-media/title and full reviewed head to .codex-pr-media/reviewed-head; ignore both paths through .git/info/exclude; report title, absolute draft path, and reviewed head. Never write to GitHub. |
| User-owned repository | Push and create or update the branch's draft PR with the same title and body. Stop without modification if its existing PR is not a draft. For UI changes, upload media through the GitHub editor, replace only local media references with attachment URLs, and verify no local paths remain. |
For a user-owned repository, verify the saved draft PR's base, head, and commits match the reviewed scope.
Only create or update drafts. Never mark ready, merge, request reviewers, enable auto-merge, or post GitHub review activity.