propose-conventional-commit

Propose Conventional Commit

Inspect staged changes and recent context, draft a Conventional Commits message, wait for approval.

Why This Is Best Practice

Adopted by: Standard at Google, Meta, Stripe, and most teams with structured engineering workflows. Conventional Commits format adopted by Angular, Vue, Electron, and thousands of OSS projects as the dominant commit message standard. Impact: Semantic Release (used by Angular, Electron, Vue) generates changelogs and bumps semver fully automatically from Conventional Commits — eliminating 30–60 min of manual release note writing per release. Type-prefixed commits also enable git bisect efficiency: engineers can skip style/chore commits when bisecting regressions. Why best: Freeform messages ("fix stuff", "wip") degrade under pressure and are unsearchable. Gitmoji uses emoji prefixes — visually distinct but no tooling support for automated changelogs. Conventional Commits has the broadest tooling ecosystem (Semantic Release, commitlint, changelogen, release-please) and is the only format with a published specification (conventionalcommits.org).

Sources: Conventional Commits specification, Angular commit message guidelines, Semantic Release documentation, Google Engineering Practices

Steps

1. Gather context

Run in parallel:

git diff --cached --stat
git diff --cached
git log --oneline -10

2. Draft message

• Derive type from nature of change: feat, fix, refactor, style, test, build, docs, chore
• Subject line: imperative mood, ≤72 chars, no period
• Body (optional): include only if the why is non-obvious — a hidden constraint, specific bug, or non-obvious trade-off
• No Co-Authored-By trailer — author is git user only

3. Present for approval

Show the proposed message as a plain fenced code block:

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

<optional body>

Then stop. Do NOT run git commit until the user explicitly approves (says "commit", "looks good", "yes", or sends the message back).

4. On approval

Run:

git commit -m "$(cat <<'EOF'
<approved message>
EOF
)"

Then report the commit hash.

Rules

• Never commit without explicit user approval in this turn
• Never add Co-Authored-By lines
• If nothing is staged, say so and stop
• If the diff is ambiguous (e.g., multiple unrelated changes), note it and suggest splitting