commit-convention

name	commit-convention
description	Conventional Commits 1.0 enforcer. Two complementary modes: (1) AUTO-SUGGEST — when you say "commit", "commit my changes", "commit this", or invoke `/commit`, the skill inspects `git diff --staged`, proposes 1–3 conventional commit messages (type + optional scope + subject), and asks which one to use. You never have to remember the format. (2) VALIDATOR — every `git commit` passes through a PreToolUse hook that validates the first line of the message against the Conventional Commits regex. Non-conformant commits trigger a confirm prompt — they cannot slip through silently. Types allowed: feat, fix, refactor, perf, docs, test, chore, build, ci, style, revert. Optional scope in parentheses (lowercase kebab-case, ≤ 20 chars). Optional `!` and `BREAKING CHANGE:` footer. Use when: "commit", "commit my changes", "make a commit", "commit this", "validate commit", "/commit". Proactively invoke whenever the user says "commit" or runs `git commit` through the agent, and after a logical unit of work is staged and idle. Mirrors the format already enforced by the AI-Native-Dev-Stack itself (see CONTRIBUTING.md and AGENTS.md → "Git & collaboration").
origin	generic

/commit-convention — Conventional Commits 1.0 enforcer

Two complementary behaviors. Apply both — the user must be protected from non-conformant commits in every code path.

---

Mode 1 — Auto-suggest (primary entry point)

Invoke when the user says any of: "commit", "commit my changes", "commit this", "commit everything", "make a commit", /commit, or when a non-empty staged diff is idle and the user seems ready to commit.

Step 1 — Read the staged diff

git rev-parse --is-inside-work-tree 2>/dev/null || { echo "NOT_A_GIT_REPO"; exit 0; }

git diff --cached --stat | head -20
echo "---"
git diff --cached --shortstat

If nothing is staged, warn and fall back to unstaged:

echo "Nothing staged — falling back to unstaged changes."
git diff --stat | head -20

If still empty → "Nothing to commit, working tree clean." Stop.

Step 2 — Infer type, scope, subject

Apply heuristics IN ORDER. First match wins; if none, ask the user.

Type inference

Signal in the diff	Type
New files in tests/, *_test.*, *.test.*, spec/	test
Only .md / docs / CHANGELOG.md changes	docs
Only whitespace / formatting / lint fixes (no logic change)	style
.github/, .gitlab-ci.yml, Jenkinsfile, CI Makefile targets	ci
Cargo.toml deps, package.json deps, pyproject.toml, Dockerfile (no logic)	build
Build tooling configs (vite.config.*, tsconfig.*, Makefile)	build
Pure rename / extract / move with no behavior change	refactor
New public symbol/route/endpoint, additive change	feat
Bug fix — words "fix"/"bug"/"crash"/"regression" in message or hunks	fix
Performance — "perf"/"cache"/"memoize" or benchmark-driven	perf
Everything else (cleanup, housekeeping, no semantic change)	chore

Scope inference

Derive from the single most prominent directory of changed files (common parent). If the diff spans multiple unrelated scopes, leave scope empty. Limit scope to ≤ 20 chars, lowercase, kebab-case if multi-word.

Examples: feat(auth): …, fix(dsp-eq): …, docs(readme): …, chore(deps): …, refactor(audio-thread): ….

Subject generation

• Length: subject ≤ 72 chars (the part after the colon), full first line ≤ 100 chars (GitHub UI truncation point).
• Imperative mood ("add" not "added"; "fix" not "fixed").
• Lowercase after the colon.
• No trailing period.
• Completes the sentence "If applied, this commit will ___".

Step 3 — Propose with AskUserQuestion

Surface 1–3 candidates, best-first.

Question: "Pick a commit message (or write your own)"
Options:
  1. <type>(<scope>): <subject>      ← best guess
  2. <type>: <subject without scope> ← if scope was ambiguous
  3. chore: <subject>                ← safe fallback

The "Type your own answer" option is auto-added.

Step 4 — Execute (with confirmation)

Always confirm before running git commit. Build the command:

• Single-line, ≤ 200 chars → git commit -m "<M>"
• Multi-line (body or footer) → use -m per paragraph or -F <tmpfile>

MSG_FILE=$(mktemp)
cat > "$MSG_FILE" <<'EOF'
<subject>

<body>

<footer>
EOF
git commit -F "$MSG_FILE"
rm -f "$MSG_FILE"

---

Mode 2 — Validator (PreToolUse hook)

Runs automatically before every git commit — whether invoked by the agent, typed through the agent, or any other path. The agent cannot bypass the ask, only the user can.

Behavior

Input	Result
First line matches CC regex AND no soft warnings	PASS (silent allow)
First line matches CC regex BUT full line > 100 chars	ASK with [warn] prefix
First line matches CC regex BUT BREAKING CHANGE footer without !	ASK with [warn]
First line does not match	ASK with violation list
--no-verify present	PASS (user override)
No message extractable	ASK with "no commit message found"

Validator regex (POSIX extended)

^(feat|fix|refactor|perf|docs|test|chore|build|ci|style|revert)(\([a-z0-9-]{1,20}\))?!?: .{1,72}$

Only the first line of the message is checked. Body and footer are allowed but not line-validated.

Length rules

• Subject (after the colon): ≤ 72 chars — enforced by the regex.
• Full first line: ≤ 100 chars — soft warning (ASK) because GitHub UI truncates at 100.
• Trailing period on first line: ASK with hint.

Hook wiring (Claude Code)

.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash <STACK_ROOT>/skills/commit-convention/bin/validate-commit.sh"
          }
        ]
      }
    ]
  }
}

<STACK_ROOT> resolves to D:/App/ai-native-dev-stack/ on this machine. The hook ships with the stack installer (install.sh step 2). Other agents (Codex, OpenCode, MiniMax/Mavis) use the same bin/validate-commit.sh — see each agent's hook docs for the equivalent event name (pre_tool_use etc.).

Source layout

skills/commit-convention/
├── SKILL.md                        ← this file
├── bin/
│   ├── validate-commit.sh          ← the hook (called by PreToolUse)
│   └── extract_commit_msg.py       ← message extractor (called by the hook)
└── tests/
    └── test_validate.sh            ← 18 zero-dep smoke tests, all green

---

Format reference (canonical)

Allowed types

Type	When
feat	New user-visible feature
fix	Bug fix
refactor	Code change that neither fixes a bug nor adds a feature
perf	Performance improvement
docs	Documentation only
test	Adding or correcting tests
chore	Build, deps, tooling, housekeeping (no source change)
build	Build system or external dependencies
ci	CI configuration files and scripts
style	Formatting, whitespace, semicolons (no logic change)
revert	Reverts a previous commit (revert: feat(...): ...)

Anatomy

<type>[(<scope>)][!]: <subject>
<BLANK LINE>
<body>  (optional — wrap at 100 cols)
<BLANK LINE>
<footer>  (optional)

Breaking changes

Either feat(api)!: drop v1 endpoints OR a footer line BREAKING CHANGE: <description>. Both is fine.

Revert

revert: feat(auth): add OAuth login

This reverts commit abc123def.

---

Examples

✅ Good

feat(auth): add OAuth2 login flow
fix(dsp-eq): prevent denormal flush on idle
refactor(audio-thread): extract ring buffer
perf(renderer): cache glyph atlas between frames
docs(readme): document --release-plugins build flag
test(seno-materia): cover ADSR release edge cases
chore(deps): bump clap-host to 0.4.2
build(workspace): enable LTO on release profile
ci(github): cache cargo registry between runs
style(egui): run rustfmt on gui module
revert: feat(auth): add OAuth2 login flow
feat(api)!: drop v1 endpoints, migrate to v2

❌ Bad (validator rejects)

Added new feature                                # no type prefix
FEAT(auth): add oauth                            # uppercase type
feat: Add OAuth.                                 # trailing period (warn)
feat(authentication layer): add oauth            # scope has spaces
feat(auth): add oauth login flow with remember me # > 72 chars subject
fixed the bug in the eq                          # not a valid type

---

Boundaries

• Never auto-commit. Always confirm with the user before git commit.
• Never rewrite history (git commit --amend only on explicit request).
• Never force-push or rebase shared branches.
• Never push to remote unless explicitly asked.
• If the diff is huge (>100 files), surface scope as "unknown" — don't guess.