---
name: conventional-gitmoji
description: >
  Commit changes using the Conventional Commits spec with extended (Angular)
  types, prefixed with a gitmoji. Use automatically whenever the user asks you
  to commit — "commit", "commit this", "commit the changes", "write a commit
  message", "git commit" — or when you finish a piece of work and staged
  changes need committing. Produces messages like "✨ feat(auth): add login
  endpoint", stages related files, and runs git commit for you.
---

# Conventional Commits + Gitmoji

Commit the current work with a message that follows
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), uses
one of the **nine extended types** below, and carries a
[gitmoji](https://github.com/carloscuesta/gitmoji) so the intent reads at a
glance. You run the commit yourself; you don't just hand the user a message.

## Workflow

1. **Inspect.** Run `git status` and `git diff --staged` (also `git diff` for
   unstaged work). Read the whole change before you pick a type.
2. **Stage.** Stage the files that belong to one logical change:
   `git add <files>`. Prefer targeted adds over `git add -A` so unrelated
   edits don't get swept into the commit.
3. **Pick exactly one type** from the table below. No other types.
4. **Pick a scope** (optional): the code area affected, lowercase
   kebab-case — `auth`, `api`, `parser`, `npm`, `scheduler`.
5. **Write the subject.** Imperative mood, lowercase, no trailing period,
   subject ≤ 72 chars (aim ≤ 50).
6. **Add a body** when the "why" isn't obvious (see Rules).
7. **Run `git commit`** with the message.

## Format

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

<body (optional, blank line before)>

<footer (optional, e.g. "Closes #128")>
```

- The gitmoji comes **first**, then the type, then the optional scope, then
  `:` and a space.
- Emoji character (`✨`) is preferred. The emoji code (`:sparkles:`) is an
  acceptable equivalent when emoji chars are a problem (some CI, older
  terminals).

## Types → gitmoji

Use **only** these nine. Do not invent others (no `chore`, no `revert`).

| Type | Gitmoji | Code | Use when |
| ------ | --------- | ----------------- | ---------- |
| `feat` | ✨ | `:sparkles:` | A new feature |
| `fix` | 🐛 | `:bug:` | A bug fix |
| `docs` | 📝 | `:memo:` | Documentation-only changes |
| `style` | 🎨 | `:art:` | Changes that don't affect meaning: white-space, formatting, missing semi-colons (use 💄 only for UI/style-file visual changes) |
| `refactor` | ♻️ | `:recycle:` | A change that neither fixes a bug nor adds a feature |
| `perf` | ⚡️ | `:zap:` | A change that improves performance |
| `test` | ✅ | `:white_check_mark:` | Adding missing tests or correcting existing ones |
| `build` | 👷 | `:construction_worker:` | Build system or external dependency changes (gulp, broccoli, npm) |
| `ci` | 💚 | `:green_heart:` | CI configuration files and scripts (Travis, Circle, BrowserStack, SauceLabs) |

**Breaking changes:** append `!` after the type/scope **and** use 💥
(`:boom:`, "Introduce breaking changes") as the gitmoji, plus a
`BREAKING CHANGE:` trailer in the body.

```
💥 feat!: drop support for Node 14

BREAKING CHANGE: runtime now requires Node ≥ 18.
```

## Body rules

Add a body only when the subject alone doesn't explain the *why* — non-obvious
reasoning, migration notes, trade-offs, or breaking changes. Always include a
body for: breaking changes, security fixes, and data migrations. Wrap at 72
chars, put a blank line between subject and body, use `-` bullets.

## Guardrails

- **One intent per commit.** If the diff mixes intents (a fix and a refactor,
  two unrelated features), suggest splitting into separate commits.
- **Match the repo.** Check `git log --oneline` first; if the existing history
  uses `:code:` form, or a configured gitmoji/commit adapter is present, follow
  it.
- **No filler.** Don't restate file names the scope already implies; no "This
  commit does X", "I", "we", "now".
- **No AI attribution** unless the user explicitly asks for a
  `Co-authored-by` trailer.
- **Empty/staged mismatch.** If nothing is staged, stage the relevant files
  first; don't commit an empty message.
- **Failures.** If `git commit` fails (hooks, lint-staged, author config), read
  the error, fix it, and retry. Never retry with `--no-verify` to bypass hooks
  unless the user tells you to.

## Examples

```bash
git commit -F - <<'EOF'
✨ feat(auth): add token refresh endpoint

Mobile client needs refresh without a full re-login to keep
LTE bandwidth low on cold-launch screens.

Closes #128
EOF
```

```bash
git commit -F - <<'EOF'
🐛 fix(parser): handle empty input instead of crashing
EOF
```

```bash
git commit -F - <<'EOF'
♻️ refactor(utils): extract slugify into shared helper
EOF
```
