Conventional Commits rules
Makes the assistant write every commit in Conventional Commits 1.0.0 format, one logical change per commit, with honest breaking-change footers. Use in repos that release from commits.
When you write a commit message, follow Conventional Commits 1.0.0.
- Write the header as
type(scope): description. The scope is optional; leave it out unless the repo already uses scopes, and then use the same scope names. - Use one of these types:
feat(new behaviour for users),fix(a bug fix),docs,style(formatting only),refactor(no behaviour change),perf,test,build,ci,chore,revert. Do not invent new types unless the repo's commitlint config lists them. - Write the type and scope in lowercase. Write the description in the imperative mood ("add", not "added"), with no trailing period.
- Keep the header under 72 characters.
- Put one logical change in each commit. If the staged changes do two things, say so and suggest splitting them instead of writing a header that joins them with "and".
- After a blank line, add a body that explains why the change was made when the header does not make that obvious. Wrap it at 72 characters. Do not narrate the diff.
- Mark a breaking change in two places: an exclamation mark before the colon (
feat(api)!: drop the v1 endpoints) and aBREAKING CHANGE:footer that says what users must change. WriteBREAKING CHANGEin uppercase. - A change is breaking when existing users must change code, configuration or data to keep working. Removing a public function, renaming a CLI flag and changing a default are breaking; internal refactors are not.
- Put footers after the body, one per line, in
Token: valueform (Refs: #123,Reviewed-by: Name). Only reference issues that exist in the task or the branch; never invent an issue number. - For a revert, use
revert:followed by the reverted header, and a body ofThis reverts commit SHA.with the real sha. - Remember how release tools read these:
fixproduces a patch release,feata minor release and any breaking change a major release. Choose the type by its effect on users, not by the size of the diff. - Do not add tool or assistant attribution trailers unless the user asks for them.
details
- kind
- Rule: standing instructions for everything the assistant does
- domain
- Software engineering
- category
- Git and version control
- level
- Beginner
- made for
- Software engineer, Open-source maintainer
- risk
- read-only
- version
- v1.0.0 · incubating
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md, ChatGPT, claude.ai
use in
npx @hermes-hq/hodios install conventional-commits-rules --target claude-codenpx skills add hermes-hq/hodios-dist --skill conventional-commits-rules -a claude-codeRules are always-on instructions, so they are not in the plugins: add the skill, or paste the text into CLAUDE.md.
pairs well with
All of Git and version controlWrite a commit message
Writes a commit message that states what changed and why, in the repo's own convention, and flags staged changes that should be split. Use before committing.
write-commit-messageRecover lost Git work
Recovers commits, branches, stashes and staged files lost to a reset, rebase or dropped stash, using reflog and fsck after a backup, explaining each command. Use right after a git mistake.
recover-lost-git-workResolve a merge conflict
Resolves merge, rebase or cherry-pick conflicts by reading both sides and their common base, keeps the intent of each, and asks when the intents contradict. Use when git stops on a conflict.
resolve-merge-conflictWrite a pull request description
Writes a pull request description that tells reviewers why the change exists, what to look at first, how to test it and what could break. Use when opening a PR.
write-pr-descriptionChoose a branching strategy
Recommends a branching and release strategy such as trunk-based, GitHub flow or release branches for a team's size, cadence and environments, with rules, protections and migration steps.
choose-branching-strategyClean up a branch's commit history
Plans an interactive rebase that turns a messy branch into logical, reviewable commits, with a backup, the exact todo list and a check that the code is unchanged. Use before merging a WIP branch.
clean-up-commit-history