github-pr-codex-review-cycle
Use only when the user explicitly invokes `$github-pr-codex-review-cycle`, names `github-pr-codex-review-cycle`, or requests the full `github-issue-delivery` workflow for named issues.
SKILL.mdskills/local/github-pr-codex-review-cycle/SKILL.md
GitHubGitHub PR Codex Review Cycle
Scope
Use this orchestration skill to run the normal end-to-end cycle after an implementation is ready: publish the current work as a pull request, request Codex review, wait for the actual review output, address worthwhile AI review feedback, then commit, push, reply, and resolve the handled review threads.
This skill intentionally composes existing skills. Do not copy their detailed workflows here.
Required sub-skills:
github-pr-publishgithub-pr-review-requestgithub-pr-ai-review-followup
Use github:gh-address-comments whenever thread-level review state, inline
context, replies, or resolution matters.
This skill is not for:
- implementing feature work before publication
- Copilot review requests unless the user separately asks
- human review sweeps
- merging pull requests
- deleting branches or worktrees
- force pushing, rebasing, amending, or history rewriting
Approval Model
An explicit invocation of this cycle, or an explicit request for the full
github-issue-delivery workflow for named issues, selects this cycle on the
requested feature branches. Delegated calls follow
Delegated Authorization;
the exact target is the requested feature branches. Honor stricter applicable
approval instructions. Within those rules, treat the explicit request as
approval for the normal, non-destructive cycle:
- verification required by
github-pr-publish - ordinary commit of the requested implementation work
- normal push of the current feature branch
- pull request creation or reuse
- posting the
@codex reviewtrigger comment - applying worthwhile Codex or Copilot review fixes
- ordinary commit and normal push for review-follow-up fixes
- short GitHub replies to the latest AI review threads
- resolving latest AI review threads with dispositions that clearly close them:
applied,stale,duplicate, or fully answeredexplained
Still stop and ask before:
- publishing from the default branch
- staging secret-like files, credentials, local config, or unrelated changes
- force push, rebase, amend, reset, merge, branch deletion, or worktree removal
- dependency manifest or lockfile edits unless already explicitly part of the requested work
- resolving
needs-human-decision, ambiguous, conflicting, risky, or still reasonably disputed review feedback - broad formatting, generator, or snapshot changes not required for the review
Workflow
- Resolve the target branch or worktree.
- Resolve and process targets under
github-pr-publishstep 1, across the whole cycle. - On resume, revalidate any supplied PR/head/trigger and follow-up record. Reuse verified completed operations and enter the earliest incomplete phase. If a trigger already awaits output for the same published head, resume step 4 rather than posting another request. If matching output already completed, continue with Prepare or the pending publication/Writeback phase. Evidence for an older head does not satisfy a review of the current head.
- Resolve and process targets under
- Use
github-pr-publish.- Preserve that skill's verification, staging, commit, push, and PR rules.
- Capture the PR number, PR URL, branch, push remote, commit, and verification result.
- Use
github-pr-review-requestwith providercodexfor the resolved PR.- Treat
Codex request posted but not acknowledgedas a blocker unless the user explicitly asks to continue waiting or retry.
- Treat
- Wait for Codex review completion.
- Codex posts a summary comment starting with
<!-- codex-pull-request-review-summary -->and edits it in place. Read its<!-- codex-review-state:v1 {...} -->JSON only when the comment'supdated_atis later than the trigger comment'screated_at; an older marker belongs to an earlier request. Track onlycode_review; this cycle requests no security review. - Review completion requires actual Codex review output after the trigger:
a review, review threads, or inline comments; or a marker whose
code_review.statusiscompletedand whosecode_review.commit_shaequals the full published head SHA. - A marker with
code_review.statusrunning,null, or missing, or with anothercommit_sha, is not completion; keep waiting. - A completed marker with
has_any_findings: falsemeans no actionable feedback: continue at step 8. With findings, wait for the review threads before step 5. - If no summary comment has the marker or its JSON does not parse, fall back to a review summary/comment that indicates the run finished, and report that completion was inferred without the marker.
- Poll the PR comments/reviews/thread state at reasonable intervals and keep the user updated during long waits.
- If no actual review output appears within a practical bound, report the PR, trigger comment, acknowledgement state, and last checked time. Do not run review follow-up against stale or absent output.
- Codex posts a summary comment starting with
- Use only the Prepare phase of
github-pr-ai-review-followupon the latest Codex review feedback.- Forward any earlier dispositions and assessment defaults the caller supplied.
- Capture its prepared record, including per-thread dispositions, verification, proposed replies, and pending publication. Do not reply or resolve yet, even though this cycle authorizes later writeback.
- If review fixes changed files, commit and push the verified fixes.
- Reuse Prepare's successful verification if no relevant files changed after it; otherwise run the smallest relevant verification for the changed files.
- Stage only review-follow-up changes.
- Stop and report
<branch>unless it is a safe branch name: runnode <script> -- '<branch>', where<script>ischeck-branch-name.mjsresolved from this skill's directory, and continue only on exit 0. Write a name into this or any command only when it uses solely ASCII letters, digits,/,.,_, and-; any other name is not safe, without running the check. - Use a normal commit, then push with
git push <remote> <branch>:refs/heads/<branch>.<remote>is the push remote captured in step 2, used as is. On resume without it, resolve<remote>by the push target rule ingithub-pr-publishstep 2: runnode <push-script> resolve --github '<host>' '<owner>/<repo>'with the PR URL's host and the PR's head repository (gh pr view --json headRepository,headRepositoryOwner), writing the host into the command only when it uses solely ASCII letters, digits,., and-, optionally followed by:and digits, and<owner>/<repo>only when it uses solely ASCII letters, digits,.,_,-, and one/(otherwise stop and report), where<push-script>ischeck-push-target.mjsresolved from this skill's directory, and use line 1 on exit 0. Otherwise stop before the push and ask the user to confirm or name the remote; use a remote the user names as given. The explicit remote and refspec keepbranch.<branch>.pushRemoteorremote.pushDefaultfrom sending the fixes away from the PR head. - If verification is unsuccessful or unavailable, stop before commit or push. If verification, commit, or push fails, stop the cycle and report; do not enter step 7.
- Add the published commit to the prepared record.
- Use only the Writeback phase of
github-pr-ai-review-followup.- Pass the prepared record, publication evidence, and existing authorization for clearly closed latest AI review items under the Approval Model.
- Delegate target revalidation, replies, resolutions, and writeback verification to that phase. Do not reapply fixes or duplicate its writeback procedure.
- Verify final PR state when possible.
- Re-read thread state after writeback.
- Report unresolved, skipped, ambiguous, or human-decision items.
Completion Criteria
The cycle is complete only when one of these is true:
- Codex review output was inspected, worthwhile fixes were handled, verification passed, needed commits/pushes were done, and clearly closed threads were replied to and resolved.
- Codex produced no actionable feedback, and final thread/comment state was checked.
If a blocker prevents completion, report Blocked, or Partial when only some
targets or writebacks completed, with the exact next approval or external state
needed. Reporting a blocker does not make the cycle complete.
Final Report
Use this structure:
**Cycle Status: <Complete | Blocked | Partial>**
- Branch: `<branch>`
- PR: <url>
- Publish: `<commit, no new commit, or blocked>`; verification `<command and actual result>`
- Codex: `<acknowledged/completed/blocked summary>`
- Follow-up: `<applied/explained/skipped/pre-existing/stale/duplicate counts>`
- Not applied: one line per item not `applied`, from the prepared record:
`<thread>`: <finding> - `<reviewer label>` - `<triage class>` - `<disposition>`: <reason>; or "None"
- Review fix commit: `<sha>` or "No review-fix commit needed"
- Writeback: `<replied/resolved counts>`
**Open Items**
- <unresolved or human-decision items, or "None">