tomevault-io Git Conventional Commit Skill
You enforce Conventional Commits on every commit in this repository. This is critical for consistent changelogs and semantic version bumps.
Commit message format
Every commit message MUST follow this format:
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
Types (required)
| Type | When to use | Version bump |
|---|---|---|
feat |
A new feature or capability | minor |
fix |
A bug fix | patch |
docs |
Documentation only | none |
style |
Formatting, semicolons, whitespace — no logic | none |
refactor |
Code change that neither fixes a bug nor adds a feature | none |
perf |
Performance improvement | patch |
test |
Adding or correcting tests | none |
build |
Build system or external dependency changes | none |
ci |
CI configuration changes | none |
chore |
Maintenance tasks (deps, tooling, releases) | none |
Scopes (recommended)
Use a scope to identify the affected area:
| Scope | Meaning |
|---|---|
core |
Elixir core (lib/opal/ directory) |
cli |
TypeScript CLI (cli/ directory) |
rpc |
JSON-RPC protocol layer |
agent |
Agent loop / GenServer |
tools |
Built-in tool implementations |
ci |
GitHub Actions workflows |
release |
Release and versioning infrastructure |
docs |
Documentation |
sdk |
TypeScript SDK client |
Omit the scope only when the change truly spans the entire project.
Breaking changes
Append ! after the type/scope for breaking changes:
feat(rpc)!: change message envelope format
Or add a BREAKING CHANGE: footer in the body.
Rules
- Always use conventional commit format. Never commit with a bare message like "fix stuff" or "updates".
- Description must be lowercase, imperative mood, no period at the end.
- Scope should match the table above when the change is localized.
- Body is optional but encouraged for non-trivial changes — explain why, not what.
- One logical change per commit. Don't bundle unrelated changes.
- Before committing, verify the message parses as a valid conventional commit.
Examples
feat(cli): add --json flag for machine-readable output
fix(core): prevent crash when tool returns empty response
docs(tools): document edit tool hashline format
refactor(agent): extract token counting into dedicated module
ci: add Elixir dialyzer step to CI pipeline
chore(release): 0.1.10
feat(rpc)!: switch from JSON-RPC 2.0 to msgpack framing
BREAKING CHANGE: RPC wire format changed from JSON to msgpack.
Clients must update to sdk >= 0.2.0.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.