commit-pr · diff

git:20260713.efbd702 to git:20260716.3bade65

4 added, 0 removed. Audit A to A.

---

name: commit-pr

audience: swarm-plugin

description: >

Apply when committing, pushing, opening or updating a pull request, or closing

out CI. A portable, project-agnostic commit and PR workflow: verify before you

push, write conventional commits and a clear PR body, and never commit

generated or secret files.

effort: medium

---

# Commit & PR Protocol (portable)

A project-agnostic workflow for landing a change safely. It makes no assumptions

about the language, build tool, or hosting provider — discover each project's

own conventions and follow them. Do every step in order.

> If the repository ships its own commit/PR contract (a `CONTRIBUTING.md`, a

> pull-request template, a contributor-guide file, or a project-specific

> commit-pr skill), that contract wins over this generic guidance. Read it first.

## Step 0 — Working-tree hygiene

1. `git status` and `git diff` — know exactly what you are about to commit.

2. Confirm you are on a feature branch, not the default branch. If you are on

`main`/`master`, create a branch first.

3. Do not stage generated output, dependency directories, local caches, or

secrets (build/`dist` output, `node_modules`/`target`/`vendor`, `.env`,

credentials, keys). If any are tracked or unignored, fix `.gitignore` instead

of committing them.

## Step 1 — Discover the project's checks

Find the project's own validation commands rather than guessing:

- A package manifest's script section (e.g. `package.json` `scripts`,

`Makefile` targets, `pyproject.toml`, `Cargo.toml`, `justfile`, `Taskfile`).

- CI workflow files under `.github/workflows/` (or the provider's config) —

these are the checks that must pass to merge.

Run the project's build, test, lint, type-check, and format checks — whatever

exists. Pin tool versions to what the project declares so local results match

CI. If a check fails, fix the cause; do not weaken, skip, or delete the check.

## Step 2 — Verify before you push

Run the discovered checks and confirm they pass. Report the exact commands and

their results — never claim a check passed without having run it. Passing tests

mean the change is *plausible*, not automatically *correct*: make sure the change

actually does what the task intended.

## Step 3 — Commit

Write a clear, conventional commit message:

- Title: `<type>(<scope>): <summary>` where `<type>` is one of `feat`, `fix`,

`perf`, `refactor`, `docs`, `test`, `build`, `ci`, `chore`, `revert`.

- Keep the title short and imperative; put detail in the body.

- One logical change per commit where practical.

## Step 4 — Push

1. Identify the correct remote. If the repo has several remotes, push to the one

the PR targets (the upstream you are contributing to), not an unrelated fork.

2. `git push -u <remote> <branch>` for a new branch.

3. If a push is rejected because you rebased, use `git push --force-with-lease`

— never a plain, unconditional force push. `--force-with-lease` refuses to

overwrite commits the remote gained since your last fetch, so it cannot

silently clobber a teammate's work.

## Step 5 — Open or update the PR

Search the repo for a PR template

(`.github/PULL_REQUEST_TEMPLATE.md` or `.github/PULL_REQUEST_TEMPLATE/`). If one

exists, fill in its sections. Otherwise write a body with at least:

- **Summary** — what changed and why.

- **Test plan** — the checks you ran and their results.

- A linking keyword (`Closes #<issue>`) when the PR resolves an issue.

Use a PR title in the same conventional-commit form as your commit.

+ Before generating the PR body, check if `.swarm/issue-reference.json` exists. If it

+ does 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 `Closes #<issue-number>`.

## Step 6 — Close out CI

After the PR is open, watch its checks. If CI fails, read the logs, reproduce

locally, fix the real cause, and push again. A PR is not done until its required

checks are green and any review feedback is addressed. Do not merge over failing

required checks or disable a check to go green.