Skip to main content
skill CX Codex

commit-pr · zaxbyhub, claude — Claude Code skill for commits and PRs

Guides an agent through checks, commit preparation, and PR publication. Useful when a change must follow the opencode-swarm release process.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill commit-pr -a claude-code
Open on GitHub

What commit-pr does

Before publication, the skill requires reading project guidance and engineering invariants, then checking the diff and tests. The PR description must include evidence for each affected invariant. Some changes trigger extra checks: touching tool registration, for instance, calls for configuration and tool tests. The point is to keep a PR from going out without evidence for the invariants it changes.

It prescribes commit and PR title formats, plus a release-note fragment at docs/releases/pending/<unique-slug>.md. References in that fragment must be checked against the codebase. The workflow also removes specific publication-cache files and checks Git status. Do not clear .swarm/evidence wholesale: it contains task and gate evidence as well.

The described steps include bun commands for building, tests, and quality checks. If a SKILL.md file changed, a separate content-assertion check is required before committing. The source also refers to merge and post-PR lifecycle rules, but the full validation suite details are not present in the supplied excerpt.

What it helps with

  • audit changed invariants before publishing a PR
  • format commit and PR titles to match project rules
  • write release notes and verify referenced paths
  • run build, type, and code-quality checks

Example prompts for the agent

  • Prepare a commit and PR for these changes using the project workflow.
  • Audit the invariants, draft release notes, and prepare a PR for the current diff.
  • Run the required checks and verify the commit title before publishing this PR.

How to install commit-pr

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill commit-pr -a claude-code

2Manually: put the files in place

~/.claude/skills/commit-pr/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/commit-pr/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about commit-pr

How do I install commit-pr in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill commit-pr -a claude-code. The skill file will be at ~/.claude/skills/commit-pr/SKILL.md.

What does commit-pr do?

It guides commit and PR preparation through invariant checks, validation, title formatting, and a release-note fragment. The PR description must include evidence for affected invariants.

Which checks does commit-pr require for changed invariants?

For invariants 1, 2, or 3, it requires bun run build, node scripts/repro-704.mjs, and an import of dist/index.js. Changes to invariant 11 require configuration tests and tests for tool files.

Source text

SKILL.md · MIT
---
name: commit-pr
description: >
  Apply when committing, pushing, opening or updating a PR, writing a pull request,
  creating release notes, or closing out remote CI. Enforces the opencode-swarm
  invariant audit, release-note fragment workflow, full validation suite, issue
  comment requirement, and post-PR lifecycle rules.
metadata:
  audience: swarm-plugin
  effort: medium
---

# Commit & PR Protocol

## Graph-first evidence contract

Before publication, use `repo_map` `diff_context` and `impact_cone` as a final drift check, then verify the direct source, Git diff, and tests. Graph evidence is advisory only. If freshness is stale or inconclusive, confidence is low, source is missing, the language is unsupported/dynamic, the graph is absent, or an action fails, publication decisions rely on the direct evidence.

Follow every step in order. Do not skip steps.

## Step -1 - Mandatory invariant audit

Before any build, test, push, or PR action, read:

1. [`../../../AGENTS.md`](../../../AGENTS.md)
2. [`../../../docs/engineering-invariants.md`](../../../docs/engineering-invariants.md)

For every touched invariant, prepare concrete evidence for the PR body. The PR body must include:

```md
## Invariant audit
- 1 (plugin init): touched / not touched - <evidence>
- 2 (runtime portability): touched / not touched - <evidence>
- 3 (subprocesses): touched / not touched - <evidence>
- 4 (.swarm containment): touched / not touched - <evidence>
- 5 (plan durability): touched / not touched - <evidence>
- 6 (test_runner safety): touched / not touched - <evidence>
- 7 (test writing): touched / not touched - <evidence>
- 8 (session state): touched / not touched - <evidence>
- 9 (guardrails/retry): touched / not touched - <evidence>
- 10 (chat/system msg): touched / not touched - <evidence>
- 11 (tool registration): touched / not touched - <evidence>
- 12 (release/cache): touched / not touched - <evidence>
```

If a touched invariant cannot be proven from source and test output, do not push.

### Required validations for touched invariants

If invariants 1, 2, or 3 are touched, run all three:

```bash
bun run build
node scripts/repro-704.mjs
node --input-type=module -e "await import('./dist/index.js'); console.log('dist import OK')"
```

If invariant 3 is touched, audit changed source files for subprocess use:

```bash
git diff --name-only origin/main..HEAD | xargs -r grep -nE "bunSpawn\(|spawn\(|spawnSync\(" || true
```

If invariant 11 is touched, run:

```bash
bun --smol test tests/unit/config --timeout 60000
for f in tests/unit/tools/*.test.ts; do bun --smol test "$f" --timeout 30000; done
```

If invariant 7 is touched, confirm the writing-tests skill was loaded and that new test seams avoid leaking `mock.module`.

## Step 0 - Session start hygiene

Run before publication work:

```bash
git fetch origin main
rm -f .swarm/evidence/pr_body.md
rm -f .swarm/evidence/commit-pr-validation.md
rm -f .swarm/evidence/publication-evidence.json
git status --short
```

Delete ONLY those three exact publication-cache files. NEVER broad-delete
`.swarm/evidence/*.json` — that directory also holds authoritative task/gate
evidence (`{taskId}.json`), `final-council.json`, and phase-council records
(issue #2131 finding 4a).

On Windows, prefer temporary save branches over `git stash`. If you must stash, use `git stash push --include-untracked` and verify the stash contents.

If this changeset edited any SKILL.md file's wording, also run `file:.swarm/bundled-skills/skill-edit-validation/SKILL.md`'s content-assertion sweep before committing, to catch stale test assertions.

## Step 1 - Commit and PR titles

Use conventional commit format `<type>(<scope>): <description>` exactly.

- description is lowercase and does not end with a period
- allowed types: `feat`, `fix`, `perf`, `revert`, `docs`, `chore`, `refactor`, `test`, `ci`, `build`

Choose the PR title type by the main change:

- new capability -> `feat`
- bug fix only -> `fix`
- docs or chore only -> non-bump types

The squash merge commit message must match the PR title exactly.

> **Note:** The PR title MUST follow `<type>(<scope>): <description>` exactly — CI runs `action-semantic-pull-request` which will fail the `check-title` job if the format is wrong. Do not deviate from this format.

## Step 2 - Release note fragment

Create a pending release fragment and do not calculate a version manually.

Required file shape:

```text
docs/releases/pending/<unique-slug>.md
```

The fragment should cover:

- what changed
- why
- migration steps, if any
- breaking changes, if any
- known caveats

#### Ground-truth verification (mandatory)

Before finalizing a release note fragment, verify every concrete reference
against the actual codebase:

- **File paths**: `grep -r "path/to/file"` — confirm each referenced file
  exists at the stated path.
- **Script names**: check `package.json` scripts or `scripts/` directory.
- **Attribute/variable names**: grep for the exact identifier in `src/`.
- **Environment variables**: grep for the exact name in `src/` and config.

Remove or correct any reference that does not resolve. AI-generated
fragments frequently hallucinate paths and names — this step is not
optional.

Bot authors (e.g. `[bot]`, Copilot) are exempt from this requirement by CI. The user-visible surface is defined once, in `scripts/user-visible-paths.ts`, and covers `src/`, `bin/`, `binaries/`, `runners/`, `.github/workflows/`, the three native skill trees, `package.json`, and `docs/configuration.md` — so a workflow, skills, or `docs/configuration.md` PR **does** need a fragment. Tests-, scripts-, examples-, and dependency-manifest-only PRs do not: those paths never reach users.

Do not manually edit:

- `package.json` version
- `CHANGELOG.md`
- `.release-please-manifest.json` — exception: reconciliation when the manifest desyncs from actual releases (see below)

For the full release-please manifest desync diagnosis and fix protocol, read `references/pr-incident-playbook.md`.

## Step 3 - Mandatory validation suite

Run the full validation stack before pushing. The exact commands may be narrowed only when the repo contract or current task explicitly justifies it in evidence, not by intuition.

### Pre-flight

`dist/` is not committed (#1047) — do not stage it. Confirm the build succeeds:

```bash
bun run build
node --input-type=module -e "await import('./dist/index.js'); console.log('dist import OK')"
```

### Tier 1 - quality

Run both linter AND formatter — e.g., `bunx @biomejs/biome@<version> check --write .` or equivalent — because CI quality gates reject code that passes tests but fails style validation. **Pin the tool version** to match the version in `package.json` (`@biomejs/biome`); unversioned `bunx biome` resolves to a different version than the CI gate uses. (the repo script `bun run lint:ci` runs the pinned Biome version; prefer it over invoking `bunx biome` directly).

```bash
bun run typecheck
bun run lint:ci
bun run scripts/check-tool-registration.ts
bun run check:mock-cleanup
bun run check:invariants
bun run check:cross-contamination
bun run check:test-clock
bun run check:runtime-src-refs
bun run check:events
bun run check:retention
bun run check:registry-citations
bun run check:core-events
bun run check:shell-audit
bun run check:trajectory-store
bun run check:test-file-cap
bun run scripts/check-vacuous-assertions.ts
bun run check:pending-fragment
bun run check:gate-portability
bun run check:bare-spawn
bun run scripts/check-config-consumption.ts
bun run check:test-tmpdir
bun run check:bash-portability
bun run check:error-channel-discard
bun run check:path-identity
bun run check:token-formula
(cd scripts/swarm-model && node --test)
bun run package:smoke
```

The CI quality job also fails closed when either required dependency is not
successful before running the expensive checks:

```bash
if [[ "$DETECT_RELEASE_RESULT" != "success" || "$RELEASE_OWNER_RESULT" != "success" ]]; then
  echo "::error::required dependency failed: detect-release=$DETECT_RELEASE_RESULT, release-owner-guard=$RELEASE_OWNER_RESULT"
  exit 1
fi
```

This list is the FULL blocking CI quality contract (issue #2131 finding 4c):
every quality-job step in `.github/workflows/ci.yml` plus the `package:smoke`
pack check. `tests/unit/skills/commit-pr-validation-parity.test.ts` derives the
list from the workflow — if CI adds a quality step, the parity test fails until
this skill teaches it.

### Tier 2 - unit tests

```bash
bun run test:unit:ci               # CI-equivalent unit gate (quarantine ledgers + retry budget)
bun run test:unit:ci <file>...     # scoped mode: run only the listed repo-relative test files
```

`bun run test:unit:ci` runs `scripts/ci/run-unit-tests-local.ts`, the CI-equivalent unit gate with per-platform quarantine ledgers (`scripts/ci/quarantined-tests.txt`, `quarantined-tests-macos.txt`, `quarantined-tests-windows.txt`) and the retry budget. The full serial run is 45–90 min, so use the scoped mode (`bun run test:unit:ci <file>...`) when the evidence justifies narrowing (e.g. you only touched one module). This closes the gap the hand-rolled loops left (~40% of CI's colocated `src/**` tests were uncovered).

### Tier 3 - integration

```bash
bun test tests/integration ./test --timeout 120000
```

### Tier 4 - security and adversarial

```bash
bun test tests/security --timeout 120000
bun test tests/adversarial --timeout 120000
```

### Tier 5 - smoke

```bash
bun test tests/smoke --timeout 120000
```

### Pre-existing failure handling

If a failure looks unrelated, prove it on clean `origin/main` before carrying it into the PR body:

```bash
git worktree add /tmp/repro-check origin/main
cd /tmp/repro-check
bun install --frozen-lockfile
bun run build
bun --smol test <repo-relative-path-to-failing-test> --timeout 120000
cd ..
git worktree remove /tmp/repro-check
```

If the failure reproduces on `main`, document it under `## Pre-existing failures`. Do not silently inherit it.

### dist/ is generated, not committed

`dist/` is build output and is git-ignored (#1047); do **not** stage or commit it, and
there is no `dist-check` drift gate. The authoritative artifact check is `package-check`,
which runs `npm pack` and verifies the packed tarball is complete (type declarations,
grammar assets), installs it in a temp project, imports it under Node, and runs the CLI.

A `package-check` failure is a source / build / `package.json#files` problem — fix the
source or manifest and rebuild; never "commit dist to make CI green." CI builds `dist/`
itself (the `unit`, `package-check`, and `smoke` jobs run `bun run build`), and
release/publish builds from source.

## Step 4 - Workflow changes

If any `.github/workflows/*.yml` file changed, every third-party `uses:` must be pinned to a full 40-character SHA.

## Step 5 - History shape

Before opening a PR, verify no local-only files are staged:

```bash
git diff --name-only HEAD origin/main | grep -E '\.(local\.json|vscode|idea)' || true
```

Prefer a single clean commit for the branch before initial PR publication. Resolve the canonical remote first (see "Canonical remote resolution" below), then squash/push:

```bash
git fetch <canonical-remote> <base-branch>
git log --oneline <canonical-remote>/<base-branch>..HEAD
git reset --soft <canonical-remote>/<base-branch>
git commit -m "type(scope): description"
git push --force-with-lease -u <canonical-remote> <branch-name>
```

If a review cycle is already active and inline comments depend on current SHAs, avoid resquashing until threads are resolved.

If pushing to a PR branch owned by another agent or bot, push to the PR's actual head branch:

```powershell
$prBranch = gh pr view <number> --json headRefName --jq '.headRefName'
git fetch <canonical-remote> $prBranch
git push <canonical-remote> "<your-local-branch>:$prBranch" --force-with-lease
```

### Fork PR workflow approval

If the PR is from a fork (head repository differs from base repository), GitHub requires explicit workflow approval after every push. CI jobs will remain in "waiting" status until approved:

```bash
# List pending runs
gh run list --repo <upstream-owner>/<upstream-repo> --branch <branch-name> --limit 5

# Approve the pending run
gh api -X POST repos/<upstream-owner>/<upstream-repo>/actions/runs/<run-id>/approve
```

This requires `actions: write` permission on the base repository. See the `fork-pr-operations` skill for the full protocol including race conditions, permission requirements, and stale CI verification.

### Pre-push: Push Protection and Canonical Remote

Before `git push`, run both checks:

1. **Push protection scan** — scan for literal secret patterns that trigger GitHub push protection:
   ```bash
   git log origin/main..HEAD -p | grep -E 'sk_live|ghp_|xox[abprs]-|AKIA|eyJ|AIza' || true
   ```
2. **Canonical remote resolution** — push to the canonical-org remote, not a personal fork:
   ```bash
   git remote -v   # identify the org-owned remote
   git push -u <canonical-remote> <branch>
   ```

For full details, patterns, workarounds, and anecdotes, read `references/pr-incident-playbook.md`.

## Step 6 - PR creation

Before generating the PR body, read `.swarm/issue-reference.json`. If it exists and
contains a `number` field, auto-populate `Closes #<number>` as the first line of the
PR body. If the file does not exist, fall back to the `Closes #<issue-number>` placeholder.

PR body requirements:

- `Closes #<issue-number>` as the first line when the PR resolves an issue
- `## Summary`
- `## Invariant audit`
- `## Test plan`

CI enforces both the section ORDER (Summary, then Invariant audit, then Test plan) and that each heading is on its own line with nothing trailing but whitespace (see `.github/workflows/pr-standards.yml`).

### Publication-gate evidence

A repository publication gate (`.github/hooks/pr-publication-gate.json` ->
`scripts/copilot-pr-publication-gate.sh`) may block `gh pr create`, `gh pr edit`,
and `gh pr ready` until publication evidence exists. Before publishing, write:

- `.swarm/evidence/pr_body.md` — the exact PR body you will publish (must contain
  `## Summary`, `## Invariant audit`, and `## Test plan`).
- `.swarm/evidence/commit-pr-validation.md` — the validation commands you ran and
  their results.
- `.swarm/evidence/publication-evidence.json` — the versioned, freshness-bound
  receipt (issue #2131 finding 4b). The gate verifies it against the CURRENT git
  state and the EXACT body being published:

  ```bash
  BODY_SHA256=$(sha256sum .swarm/evidence/pr_body.md | cut -d' ' -f1)
  cat > .swarm/evidence/publication-evidence.json <<EOF
  {
    "schema_version": 1,
    "state": "validated",
    "repository": "$(git remote get-url origin)",
    "head_sha": "$(git rev-parse HEAD)",
    "body_sha256": "$BODY_SHA256",
    "validation_commands": ["bun run typecheck", "bun run lint:ci"],
    "recorded_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  }
  EOF
  ```

  `pr_number` may be added once the PR exists (for `gh pr edit` / `gh pr ready`).
  If HEAD changes, the body is edited, or you rerun validation, REGENERATE this
  receipt — a stale or mismatched receipt is rejected by the gate.

These files live under `.swarm/` (runtime state, never committed) and double as the
evidence the gate checks. Keep them current if you edit the PR body or rerun
validation. The CI `pr-standards` check enforces the same body contract server-side.

PowerShell-safe pattern:

```powershell
$refPath = ".swarm/issue-reference.json"
$closesLine = if ((Test-Path $refPath) -and ($ref = Get-Content $refPath -Raw | ConvertFrom-Json) -and $ref.number) {
    "Closes #$($ref.number)"
} else {
    "Closes #<issue-number>"
}
$body = @"
$closesLine

## Summary
- <bullet 1>
- <bullet 2>

## Invariant audit
- 1 (plugin init): not touched - <evidence>

## Test plan
- [ ] <validation item>
"@
$utf8NoBom = New-Object -TypeName System.Text.UTF8Encoding -ArgumentList $false
$prBodyPath = Join-Path ([System.IO.Path]::GetTempPath()) "pr_body.txt"
[System.IO.File]::WriteAllText($prBodyPath, $body, $utf8NoBom)
gh pr create --title "<type>(<scope>): <description>" --body-file $prBodyPath --base main
```
Detailed reference material moved to `.claude/skills/commit-pr/references/pr-publication.md` (issue #2907 progressive-disclosure budget).

## Step 7 - Existing PR follow-up and closeout

If a PR already exists for the branch:

1. do not open a second PR
2. 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
3. use `../swarm-pr-feedback/SKILL.md` when feedback needs fixes before closeout
4. update the existing PR body when summary, invariant evidence, test counts, caveats, or pre-existing failure notes changed
5. keep the PR draft while follow-up edits are still expected or required checks are still pending
6. mark the PR ready only after the body is current and required remote checks are green, unless the user explicitly wants it ready earlier
7. after any follow-up push or force-push, verify the PR head matches the expected commit and that reported checks belong to the current `headRefOid`:

```powershell
gh pr view <number> --json headRefOid,body,isDraft,state,mergeable,mergeStateStatus,statusCheckRollup,url
```

Useful commands:

```powershell
gh pr edit <number> --body-file "$env:TEMP\pr_body.txt"
gh pr ready <number>
gh pr checks <number> --watch --fail-fast
```

Detailed reference material moved to `.claude/skills/commit-pr/references/closeout-playbook.md` (issue #2907 progressive-disclosure budget), including the pre-queue merge-group CI simulation: before queueing, run `file:.swarm/bundled-skills/merge-queue-readiness/SKILL.md` per the playbook's Merge queue section.

## Step 8 - Cancelled jobs and skipped dependents

If a required GitHub Actions job is `cancelled` and downstream jobs are `skipped`:

1. inspect the run:

```powershell
gh run view <run-id> --json status,conclusion,jobs,url
```

2. if the cancellation looks like orchestration or infrastructure rather than a code failure, rerun the failed or cancelled jobs:

```powershell
gh run rerun <run-id> --failed
```

3. re-check the PR until required jobs are green:

```powershell
gh pr checks <number> --watch --fail-fast
```

Do not call the PR green or merge-ready while a required job is `cancelled`, `skipped`, `in_progress`, or otherwise non-green unless the user explicitly accepts that state.

## Step 9 - Pre-merge checklist

- [ ] invariant audit is complete and current
- [ ] required build and validation commands ran for touched invariants
- [ ] `test_runner` was not used with broad repo-validation scopes
- [ ] release fragment exists and version files are untouched
- [ ] `dist/` was NOT staged (it is generated output, not committed — #1047)
- [ ] PR body has `Closes`, `## Summary`, `## Invariant audit`, and `## Test plan`
- [ ] if this was review follow-up, the PR body was refreshed to match current evidence
- [ ] if the PR resolves an issue, the issue comment was posted with PR link, what changed, how to use it, and migration notes
- [ ] if any required job was cancelled and dependent jobs skipped, the run was rerun or the non-green state was explicitly accepted by the user
- [ ] for high-risk work (security, isolation, IPC, auth, payments, migrations), an independent adversarial review subagent ran before the final substantive push and all confirmed findings were addressed — if this was not done before pushing, run the review now and force-push a corrected commit before marking the PR ready
- [ ] all required CI checks are green before calling the PR merge-ready

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Git and GitHub →

commit-pr by other authors comes first.

commit-pr ZaxbyHub commit-pr — a checklist the agent must clear before it commits, pushes or opens a PR. Built for the case where an AI agent publishes the branch, not a person. CX Codex +1 ★ 539repo stars commit-pr ZaxbyHub commit-pr — a portable skill that verifies your code before push, writes conventional commits, and fills in a PR body. Guards against accidentally committing generated files or secrets. CX Codex +1 ★ 539repo stars commit-pr ZaxbyHub The commit-pr skill guides commits, pull request updates, and CI checks in opencode-swarm. Use it when publishing issue-related code changes or closing out a PR. CX Codex +1 ★ 539repo stars writing-commit-messages spencerpauly The writing-commit-messages skill gives the agent a fixed format for commit messages: type, scope, body, footer. Useful when the model writes the commits, not you. CX Codex +1 499installs commit-staged Fatih C. Akyon commit-staged automates commit creation: checks staged diffs, runs /simplify on code edits, and writes conventional commits using session rationale. CX Codex +1 ★ 1,216repo stars setup-pre-commit Matt Pocock The setup-pre-commit skill configures pre-commit checks for a JavaScript repository, running Prettier, type checking, and tests before each commit. CX Codex +1 489,289installs caveman-commit JuliusBrussee caveman-commit generates terse Conventional Commits messages focused strictly on intent. Ideal for keeping git history clean without boilerplate or AI signatures. CX Codex +1 441,600installs git-commit official github A GitHub Copilot skill that turns a working diff into a commit: it reads the changes, stages the related files, writes a Conventional Commits message and runs git commit. CX Codex +1 47,165installs conventional-commit official github A GitHub Copilot skill that builds commit messages in the Conventional Commits format. After you change files, it checks the diff and commits with a message assembled from an XML template. CX Codex +1 17,103installs

From the same set121

The whole set →
swarm Enables a multi-agent swarm workflow in the active session, running parallel subagents, independent review validation, and critic checks. CX Codex +1 ★ 539repo stars loop The loop skill takes a task through planning, implementation, review, and improvement while keeping run state on disk. Use it for gated, repeatable work toward a defined objective. CX Codex +1 ★ 539repo stars running-tests Sets the rules for running tests in opencode-swarm: when a shell bun call is enough, when to reach for test_runner, and how to keep the session from stalling. CX Codex +1 ★ 539repo stars issue-tracer issue-tracer drives bug reports from reproduction and root-cause analysis to verified PRs under a strict full-resolution contract. CX Codex +1 ★ 539repo stars swarm-ci-monitor swarm-ci-monitor is a Claude Code skill that monitors approved PRs, diagnoses CI failures, applies fixes for up to five cycles, and merges when required checks pass. CX Codex +1 ★ 539repo stars engineering-conventions engineering-conventions enforces non-negotiable engineering invariants for opencode-swarm development. It prevents initialization hangs, Bun mock leakage, and Node ESM runtime failures. CX Codex +1 ★ 539repo stars phase-wrap The phase-wrap skill guides phase closure with evidence checks, a retrospective, and conditional spec-drift review. It fits projects that use the swarm workflow. CX Codex +1 ★ 539repo stars graphify Turns a folder of code, docs, papers, images and video into a persistent knowledge graph you can question through /graphify. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open