Git

Git

Commits are save points, branches are sandboxes, history is documentation. Treat them accordingly.

Commit messages

Conventional Commits — type(scope): subject. Types: feat, fix, refactor, chore, docs, test, build, ci, perf. Single-line subject, aim under 50 characters and never over 72. Do not put issue references or links in the subject ((#123), Fixes #123) — those belong in the PR body. Defer to the repo's AGENTS.md or contributing guide if it overrides this.

Commit discipline

• Commit after each successful slice. Don't accumulate work — a commit is a save point you can return to.
• One logical change per commit. A commit that refactors and adds a feature is two commits.
• Explain intent, not mechanics. Describe why the change matters, not what files were touched.

Change sizing

• ~100 lines per commit: good.
• ~300 lines: acceptable if one logical change.
• 1000+ lines: too large — split it.

Separate refactoring from feature work. Separate formatting from behavior changes.

Branch workflow

• Start from latest main branch.
• Use short topic branch names without type prefixes, e.g. signal-toolkit, not feat/signal-toolkit.
• Keep branches short-lived — merge within days, not weeks.
• Rewrite local history before pushing — amend, rebase, squash to keep history clean. Commit noise should never become permanent.
• Never amend commits already pushed to remote.
• Use --force-with-lease over --force.
• Never use git -C — always cd into the target first. It hides the real working directory and risks operating on the wrong repo.
• Land PRs with the repo's configured merge method. When none is set, default to squash — keeps history linear, one merge commit per PR.
• After a PR merges, prune the branch locally and on the remote, then git fetch --prune to clear stale tracking refs.

Save-point pattern

When exploring uncertain changes, commit early with a clear message. If the approach doesn't work out, you can revert cleanly. Uncommitted work can't be reverted — only lost.

Change summaries

After a set of changes, provide a structured summary:

• What changed — the diff in plain language
• What was intentionally excluded — scope discipline
• What to watch — potential concerns for reviewers

Red flags

• Long-lived branches diverging from main
• Commits with "misc", "fix", "update" as the entire message
• Force-pushing to shared branches
• Mixing unrelated changes in one commit
• Working without committing for extended periods

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cniska
• Source: cniska/skills
• License: MIT

Install and usage instructions live in the source repository linked above.