Commit Message Guidelines

Guidelines for writing clear, consistent git commit messages.

Conventional Commits Format

Use the conventional commits style:

<type>[optional scope]: <description>

CRITICAL: Single-line only. Never add a body or footer. The code and spec speak for themselves.

Commit Types

• feat: New feature
• fix: Bug fix
• test: Adding or updating tests
• docs: Documentation changes
• refactor: Code refactoring (no functional changes)
• style: Code style changes (formatting, whitespace)
• chore: Maintenance tasks, dependencies
• perf: Performance improvements
• ci: CI/CD configuration changes
• build: Build system changes

Scope (Optional)

Add scope in parentheses to provide additional context:

Breaking Changes

Indicate breaking changes with ! after type/scope:

Description Guidelines

• Use imperative mood ("add feature" not "added feature")
• Start with lowercase
• No period at the end
• Keep under 72 characters
• Be specific and descriptive

No Body, No Footer

Never add a commit body or footer. Every commit must be a single line only.

Do NOT include AI attribution, co-authored-by lines, or any other footers.

Before Committing

CRITICAL — all of the following MUST be true before committing:

1. All tests pass (GREEN)
2. Pre-commit hooks pass — run prek run --all-files and fix every issue
3. Check for remote updates: git fetch
4. Review your changes: git status and git diff
5. Stage relevant files: git add <files>
6. Write clear commit message

❌ NEVER commit with failing tests ❌ NEVER commit without running pre-commit hooks ❌ NEVER commit half-finished work

When to Commit

Commit once per completed requirement in the STDD cycle:

spec written → tests RED → tests GREEN → hooks pass → COMMIT

• One commit per requirement (or tightly related group of requirements)
• Each commit must represent a complete, working state
• Do not batch multiple requirements into one commit

Integration with STDD Workflow

When following the spec-test-driven development workflow:

1. Pick a requirement from spec.yaml
2. Write test → see RED
3. Implement → see GREEN
4. Run ALL tests → all pass
5. Run prek run --all-files → all hooks pass
6. Commit with a single-line conventional commit message
7. Repeat for next requirement