Commit & PR
Use this skill for Codex-side publication work in opencode-swarm.
Source Of Truth
Read and follow ../../../.claude/skills/commit-pr/SKILL.md in full before committing, pushing, opening, or updating a PR.
That Claude skill remains the repository's canonical publish protocol. This Codex-native skill is the adapter layer: it tells Codex which tools to use, how to handle existing PRs, and how to finish the post-open lifecycle without drifting from the repo contract.
If instructions conflict:
AGENTS.md
docs/engineering-invariants.md
../../../.claude/skills/commit-pr/SKILL.md
- this file
Codex Execution Rules
- Use the available shell execution tool for
git, gh, build, test, and CI commands.
- Use
apply_patch for manual file edits.
- Use the runtime's parallel-execution capability for independent reads, status checks, and non-conflicting repo inspections.
- Do not stage
.Codex/, IDE-local files, or unrelated worktree changes.
- Do not open a second PR when one already exists for the branch. Update the existing PR instead.
Publish Modes
Infer the mode from the user request and branch state:
new-pr: branch is ready to publish and no PR exists yet
pr-followup: a PR already exists and you are addressing review feedback or syncing validation
closeout: a PR already exists and you are updating body text, waiting on CI, marking ready, or confirming merge prerequisites
Required Follow-Through
Existing PR updates
If the branch already has a PR:
- inspect unresolved PR feedback surfaces before updating or readying the PR:
review threads/comments, requested-changes reviews, CI/check failures,
mergeability/conflicts, and whether check data belongs to the current head SHA
- update the existing PR body instead of creating a new PR
- refresh
## Summary, ## Invariant audit, and ## Test plan when validation counts, caveats, or evidence changed
- verify the PR still points at the pushed branch head after any force-push
- use
$swarm-pr-feedback when feedback needs fixes before closeout
Draft vs ready
Default behavior:
- open or keep the PR as draft while follow-up edits are still expected, required checks are pending, or known caveats still need explanation
- mark the PR ready only after the body is current and required remote checks are green
If the user explicitly asks for a ready PR sooner, obey that request and document any remaining CI state clearly.
Remote checks are authoritative
When the user asks to open, ship, ready, or close out a PR:
- inspect remote checks with
gh pr view <n> --json statusCheckRollup,... or gh pr checks <n>
- verify check data belongs to the current
headRefOid after every follow-up push
- if a required job is
cancelled and downstream jobs are skipped, inspect the run and rerun failed/cancelled jobs
- if an obsolete older-head run is already failed or still consuming concurrency, inspect it before cancellation and cancel only when it is no longer the PR head under validation
- wait for required checks to finish when practical
- after conflict resolution, verify GitHub reports both
mergeable: MERGEABLE and mergeStateStatus: CLEAN; local conflict-marker cleanup is not enough, and branch drift must appear in the closure ledger when it affected the PR
- when
gh pr checks looks stale, inspect the workflow run directly with gh run view <run-id> --json headSha,status,conclusion,jobs,url, and keep watching downstream integration/smoke jobs after unit jobs pass
- if you edit the PR body after checks are green, expect PR Standards/title checks to rerun and re-check before calling the PR green
- do not call the PR merge-ready while a required check is
cancelled, skipped, in_progress, or otherwise non-green unless the user explicitly accepts that state
Recommended commands:
gh pr view <number> --json body,headRefName,headRefOid,isDraft,mergeable,mergeStateStatus,state,statusCheckRollup,url
gh pr checks <number> --watch --fail-fast
gh run view <run-id> --json headSha,status,conclusion,jobs,url
gh run rerun <run-id> --failed
dist/ is generated output and is not committed (#1047); do not stage it and there is no dist-check drift gate. If package-check fails, inspect the CI log: it is a source / build / package.json#files problem (an incomplete or unbuildable tarball), not generated-file drift. Fix the source or manifest and rerun bun run package:smoke locally.
After a forced install on Windows, EPERM while reading refreshed node_modules
is usually host friction; rerun the exact focused command with approved access
before treating it as a code failure.
Issue comment requirement
If the PR closes an issue:
- confirm the issue comment exists with the PR link, what changed, how to use it, and migration notes
- if the PR merged before the comment was posted, add the missing issue comment immediately
Working Pattern
- Read
AGENTS.md, docs/engineering-invariants.md as needed, and the canonical Claude commit-pr skill.
- Run the required local validation from the canonical skill.
- Stage only intended files.
- Create or update the PR.
- Refresh PR body text if the branch changed after review feedback.
- Watch remote checks to a useful conclusion when the user asked for publication or closeout.
- Verify issue comments, ready/draft state, and merge-readiness claims before finishing.
Clean-Main And CI Reality Checks
When local validation is noisy or host-limited:
- compare suspicious failures against a clean
origin/main worktree before blaming the branch
- document proven pre-existing failures in the PR body
- use remote CI as the cross-platform source of truth for merge-readiness
Final Sanity Check
- one branch, one PR
- PR head matches pushed
HEAD
- PR body matches current validation evidence
- issue comment exists when the PR closes an issue
- draft or ready state matches user intent
- required remote checks are green, or any remaining non-green state is explicitly explained
1---2name: commit-pr3description: >4 Mandatory Codex/Copilot publication adapter for opencode-swarm. Use for every5 GitHub issue assignment that results in code changes, commits, pushes, draft PRs,6 PR body edits, PR readying, release notes, or CI closeout. Must be loaded before7 `git push`, `gh pr create`, `gh pr edit`, or `gh pr ready`. Routes to the single8 canonical source of truth at `.claude/skills/commit-pr/SKILL.md`.9metadata:10 source: https://skillmd.com/skills/zaxbyhub/commit-pr11 audience: swarm-plugin12---1314# Commit & PR1516Use this skill for Codex-side publication work in `opencode-swarm`.1718## Source Of Truth1920Read and follow [`../../../.claude/skills/commit-pr/SKILL.md`](../../../.claude/skills/commit-pr/SKILL.md) in full before committing, pushing, opening, or updating a PR.2122That Claude skill remains the repository's canonical publish protocol. This Codex-native skill is the adapter layer: it tells Codex which tools to use, how to handle existing PRs, and how to finish the post-open lifecycle without drifting from the repo contract.2324If instructions conflict:25261. `AGENTS.md`272. `docs/engineering-invariants.md`283. `../../../.claude/skills/commit-pr/SKILL.md`294. this file3031## Codex Execution Rules3233- Use the available shell execution tool for `git`, `gh`, build, test, and CI commands.34- Use `apply_patch` for manual file edits.35- Use the runtime's parallel-execution capability for independent reads, status checks, and non-conflicting repo inspections.36- Do not stage `.Codex/`, IDE-local files, or unrelated worktree changes.37- Do not open a second PR when one already exists for the branch. Update the existing PR instead.3839## Publish Modes4041Infer the mode from the user request and branch state:4243- `new-pr`: branch is ready to publish and no PR exists yet44- `pr-followup`: a PR already exists and you are addressing review feedback or syncing validation45- `closeout`: a PR already exists and you are updating body text, waiting on CI, marking ready, or confirming merge prerequisites4647## Required Follow-Through4849### Existing PR updates5051If the branch already has a PR:5253- inspect unresolved PR feedback surfaces before updating or readying the PR:54 review threads/comments, requested-changes reviews, CI/check failures,55 mergeability/conflicts, and whether check data belongs to the current head SHA56- update the existing PR body instead of creating a new PR57- refresh `## Summary`, `## Invariant audit`, and `## Test plan` when validation counts, caveats, or evidence changed58- verify the PR still points at the pushed branch head after any force-push59- use `$swarm-pr-feedback` when feedback needs fixes before closeout6061### Draft vs ready6263Default behavior:6465- open or keep the PR as draft while follow-up edits are still expected, required checks are pending, or known caveats still need explanation66- mark the PR ready only after the body is current and required remote checks are green6768If the user explicitly asks for a ready PR sooner, obey that request and document any remaining CI state clearly.6970### Remote checks are authoritative7172When the user asks to open, ship, ready, or close out a PR:73741. inspect remote checks with `gh pr view <n> --json statusCheckRollup,...` or `gh pr checks <n>`752. verify check data belongs to the current `headRefOid` after every follow-up push763. if a required job is `cancelled` and downstream jobs are `skipped`, inspect the run and rerun failed/cancelled jobs774. if an obsolete older-head run is already failed or still consuming concurrency, inspect it before cancellation and cancel only when it is no longer the PR head under validation785. wait for required checks to finish when practical796. after conflict resolution, verify GitHub reports both `mergeable: MERGEABLE` and `mergeStateStatus: CLEAN`; local conflict-marker cleanup is not enough, and branch drift must appear in the closure ledger when it affected the PR807. when `gh pr checks` looks stale, inspect the workflow run directly with `gh run view <run-id> --json headSha,status,conclusion,jobs,url`, and keep watching downstream integration/smoke jobs after unit jobs pass818. if you edit the PR body after checks are green, expect PR Standards/title checks to rerun and re-check before calling the PR green829. do not call the PR merge-ready while a required check is `cancelled`, `skipped`, `in_progress`, or otherwise non-green unless the user explicitly accepts that state8384Recommended commands:8586```powershell87gh pr view <number> --json body,headRefName,headRefOid,isDraft,mergeable,mergeStateStatus,state,statusCheckRollup,url88gh pr checks <number> --watch --fail-fast89gh run view <run-id> --json headSha,status,conclusion,jobs,url90gh run rerun <run-id> --failed91```9293`dist/` is generated output and is not committed (#1047); do not stage it and there is no `dist-check` drift gate. If `package-check` fails, inspect the CI log: it is a source / build / `package.json#files` problem (an incomplete or unbuildable tarball), not generated-file drift. Fix the source or manifest and rerun `bun run package:smoke` locally.9495After a forced install on Windows, `EPERM` while reading refreshed `node_modules`96is usually host friction; rerun the exact focused command with approved access97before treating it as a code failure.9899### Issue comment requirement100101If the PR closes an issue:102103- confirm the issue comment exists with the PR link, what changed, how to use it, and migration notes104- if the PR merged before the comment was posted, add the missing issue comment immediately105106## Working Pattern1071081. Read `AGENTS.md`, `docs/engineering-invariants.md` as needed, and the canonical Claude `commit-pr` skill.1092. Run the required local validation from the canonical skill.1103. Stage only intended files.1114. Create or update the PR.1125. Refresh PR body text if the branch changed after review feedback.1136. Watch remote checks to a useful conclusion when the user asked for publication or closeout.1147. Verify issue comments, ready/draft state, and merge-readiness claims before finishing.115116## Clean-Main And CI Reality Checks117118When local validation is noisy or host-limited:119120- compare suspicious failures against a clean `origin/main` worktree before blaming the branch121- document proven pre-existing failures in the PR body122- use remote CI as the cross-platform source of truth for merge-readiness123124## Final Sanity Check125126- one branch, one PR127- PR head matches pushed `HEAD`128- PR body matches current validation evidence129- issue comment exists when the PR closes an issue130- draft or ready state matches user intent131- required remote checks are green, or any remaining non-green state is explicitly explained