---
name: commit-conventions
description: How to write git commits for this repository. Use when committing changes, writing commit messages, or splitting work into commits. Covers conventional commit format and separating commits by concern.
---

# Commit Conventions

Follow these rules whenever you create a commit in this repository.

## Conventional Commits

Write every commit message using the [Conventional Commits](https://www.conventionalcommits.org/) format:

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

- **type**: `feat`, `fix`, `chore`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `style`.
- **scope** (optional): the area of the codebase the change touches. Use the workspace package or directory name when it's clear (e.g. `proxy`, `web`, `packages`). Omit when the change spans multiple areas.
- **subject**: imperative mood, capitalized, no trailing period, ≤ 50 characters.

Examples:

```
feat(proxy): add TTS streaming endpoint
fix(web): handle empty transcript in player
docs: document workspace layout
```

## Separate Commits by Concern

Do not bundle unrelated changes into a single commit. Split work so each commit is a focused, self-contained unit:

- One logical change per commit (a feature, a fix, a refactor, a doc update).
- Keep each commit buildable and independently reviewable.
- Separate concerns that have different types, scopes, or reasons to be reverted independently.
- If a change is large, split it into a series of smaller commits that each stand on their own.

## Message Body

Include a body only when it adds useful context beyond the subject. If the subject fully captures the change, omit it.

- Separate the subject from the body with a blank line.
- Wrap the body at 72 characters.
- Explain the *why* and *what* rather than restating the code.
- Do not repeat information already in the subject line.
- Use `BREAKING CHANGE:` in the body (or `!` after the type/scope) for breaking changes.

## When to Use This Skill

Activate this skill when:

- Creating a new commit.
- Writing or revising a commit message.
- Deciding how to split staged or unstaged changes into commits.