| 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
git status and git diff — know exactly what you are about to commit.- Confirm you are on a feature branch, not the default branch. If you are on
main/master, create a branch first.
- 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
- 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.
git push -u <remote> <branch> for a new branch.- 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.
If this session is running an issue trace (/swarm issue --trace), call
record_issue_publication (issue number, PR number, canonical PR URL, HEAD sha)
right after the PR is opened so the issue-trace workflow can reach its terminal
published state — without it the trace stays at publication_handoff and is NOT
considered resolved.
