hermes

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 a BREAKING CHANGE: footer that says what users must change. Write BREAKING CHANGE in 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: value form (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 of This reverts commit SHA. with the real sha.
  • Remember how release tools read these: fix produces a patch release, feat a 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

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install conventional-commits-rules --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill conventional-commits-rules -a claude-code

Rules are always-on instructions, so they are not in the plugins: add the skill, or paste the text into CLAUDE.md.

PromptGit and version control

Write 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-message
PromptGit and version control

Recover 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-work
PromptGit and version control

Resolve 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-conflict
PromptGit and version control

Write 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-description
PromptGit and version control

Choose 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-strategy
PromptGit and version control

Clean 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