Git Conventional Commit Skill
You enforce Conventional Commits on every commit in this repository. This is critical because the project uses nx release with conventionalCommits: true to auto-generate changelogs and determine semantic version bumps.
Commit message format
Every commit message MUST follow this format:
code
<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 (core/ directory) |
cli | TypeScript CLI (cli/ directory) |
rpc | JSON-RPC protocol layer |
agent | Agent loop / GenServer |
tools | Built-in tool implementations |
mcp | MCP bridge |
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:
code
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
code
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.