04-commit-types.md

Commit types

@savvy-web/commitlint extends the standard conventional commit types with types for AI workflows, TDD cycles and releases.

Available types

Type	Description	Example
ai	AI/LLM agent document updates	ai: update CLAUDE.md with new context
build	Build system or dependencies	build: update webpack configuration
chore	Maintenance tasks	chore: update dependencies
ci	CI/CD configuration	ci: add GitHub Actions workflow
docs	Documentation changes	docs: update API reference
feat	New features	feat: add user authentication
fix	Bug fixes	fix: resolve memory leak in cache
perf	Performance improvements	perf: optimize database queries
refactor	Code restructuring	refactor: extract validation logic
release	Release commits	release: v1.2.0
revert	Revert previous commits	revert: undo feature X
style	Code formatting	style: fix indentation
tdd	TDD cycle checkpoint	tdd(7:green): implement sum()
test	Test changes	test: add unit tests for parser

Custom types

ai

Use ai for changes made by or for AI agents: CLAUDE.md files, agent configuration and prompt templates.

ai: update development context with new patterns
ai(context): add API usage examples for agents

release

Use release for version bump commits, whether generated by a release tool or written by hand.

release: v1.2.0
release: version packages
release(api): v2.0.0

tdd

tdd commits mark TDD cycle checkpoints. The scope is required and must follow the format {goalId}:{state}, where goalId is a numeric issue or goal ID and state is one of spike, red, green or refactor.

tdd(7:spike): explore approach for parser redesign
tdd(7:red): failing test for empty-input edge case
tdd(7:green): implement sum() to pass tests
tdd(7:refactor): extract validation into separate module

This type is enforced by the silk/tdd-scope rule, which rejects any tdd commit whose scope does not match \d+:(spike|red|green|refactor).

Commit message format

<type>(<scope>): <subject>

<body>

<footer>

Components:

• type - One of the allowed types (required)
• scope - Affected area, usually a package name (optional)
• subject - Short description in imperative mood (required)
• body - Detailed explanation (optional)
• footer - References, breaking changes, signoff (optional)

Examples

Feature with scope

feat(api): add rate limiting support

Implements token bucket algorithm for API rate limiting.
Configurable limits per user tier.

Closes #123
Signed-off-by: Developer Name <dev@example.com>

Bug fix

fix: prevent crash on empty input

Handle edge case where user provides empty string.

Signed-off-by: Developer Name <dev@example.com>

AI context update

ai: refresh development context after refactoring

Update CLAUDE.md to reflect new module structure
and coding patterns established in recent refactoring.

Signed-off-by: Developer Name <dev@example.com>

Breaking change

feat(api)!: change authentication method

BREAKING CHANGE: API now requires JWT tokens instead of
API keys. See migration guide for details.

Signed-off-by: Developer Name <dev@example.com>

DCO signoff

When DCO is enabled (default when a DCO file exists), all commits must include a signoff:

Signed-off-by: Your Name <your.email@example.com>

Pass -s to git commit, or configure your Git client to append the trailer automatically.

Programmatic access

Export commit types for use in your own tools:

import {
  COMMIT_TYPES,
  COMMIT_TYPE_DEFINITIONS,
} from "@savvy-web/commitlint";

// Array of type strings
console.log(COMMIT_TYPES);
// ["ai", "build", "chore", "ci", "docs", "feat", ...]

// Detailed definitions with descriptions
console.log(COMMIT_TYPE_DEFINITIONS);
// [{ type: "ai", description: "...", title: "AI Context" }, ...]