Prerequisites
- Require GitHub CLI
gh. Checkgh --version. If missing, ask the user to installghand stop. - Require authenticated
ghsession. Rungh auth status. If not authenticated, ask the user to rungh auth login(and re-rungh auth status) before continuing.
Naming conventions
- Branch:
codex/{description}when starting from main/master/default. - Commit:
{description}(terse). - PR title:
[codex] {description}summarizing the full diff.
Workflow
- If on main/master/default, create a branch:
git checkout -b "codex/{description}" - Otherwise stay on the current branch.
- Confirm status, then stage everything:
git status -sbthengit add -A. - Commit tersely with the description:
git commit -m "{description}" - Run checks if not already. If checks fail due to missing deps/tools, install dependencies and rerun once.
- Push with tracking:
git push -u origin $(git branch --show-current) - If git push fails due to workflow auth errors, pull from master and retry the push.
- Open a PR and edit title/body to reflect the description and the deltas:
GH_PROMPT_DISABLED=1 GIT_TERMINAL_PROMPT=0 gh pr create --draft --fill --head $(git branch --show-current) - Write the PR description to a temp file with real newlines (e.g. pr-body.md... EOF) and run pr-body.md to avoid \n-escaped markdown.
- PR description (markdown) must be detailed prose covering the issue, the cause and effect on users, the root cause, the fix, and any tests or checks used to validate.