git-commit-writer-free

name	git-commit-writer-free
description	Generate conventional commit messages from staged git changes. Use when the user asks to write commit message, generate commit, what should my commit say, or after the user runs git add and wants a commit message for staged files.
metadata	{"version":"1.0.0","author":"JustHandled Labs","triggers":["write commit message","generate commit","what should my commit say","git add"]}

Git Commit Writer

Generate a conventional commit message from staged changes only.

Workflow

1. Run git status --short.
2. Determine whether any files are staged by checking the first status column for anything other than a space or ?.
3. If no files are staged, do not suggest a commit message. Tell the user to stage changes first with git add <files> or git add ..
4. Run git diff --cached --stat to summarize staged file impact.
5. Run git diff --cached to inspect the staged patch.
6. Analyze the staged changes and return one primary commit recommendation in conventional commit format, plus optional alternatives if useful.

Use only staged changes. Do not base the commit message on unstaged, untracked, or working-tree-only changes.

Required Commands

git status --short
git diff --cached --stat
git diff --cached

If git diff --cached is empty, the correct response is:

No staged changes found. Run `git add <files>` first, then ask me to write the commit message.

Commit Format

Use this format:

type(scope): imperative summary

- Optional bullet describing notable staged change
- Optional bullet describing another notable staged change

Use type(scope)!: summary when the staged changes introduce a breaking change.

Keep the summary under 72 characters when practical. Use imperative mood: add, fix, update, remove, refactor, not added, fixed, or updates.

Type Reference

• feat: Adds or exposes user-facing functionality.
• fix: Fixes a bug, regression, crash, bad output, broken state, or incorrect behavior.
• docs: Changes documentation only.
• style: Changes formatting, whitespace, lint-only style, or visual styling without behavior changes.
• refactor: Restructures code without intended behavior change.
• test: Adds or changes tests, fixtures, mocks, or test infrastructure.
• chore: Changes maintenance files, build config, dependencies, scripts, metadata, or repository housekeeping.

When multiple types apply, choose the type that best represents the user-visible reason for the commit. Prefer feat or fix over chore when product behavior changes. Prefer test only when the commit is primarily test work.

Scope Detection Rules

Choose a concise lowercase scope from the most specific shared path or domain:

• src/auth/, app/auth/, lib/auth/, login, session, password, OAuth, token: auth
• src/api/, app/api/, routes, controllers, endpoints, request/response contracts: api
• src/ui/, components/, pages/, views/, templates, CSS tied to interface changes: ui
• tests/, test/, __tests__/, specs, fixtures, mocks: test
• .github/, workflow files, CI config: ci
• package.json, lockfiles, dependency manifests: deps
• docs, README, markdown guides: docs
• build tools, bundlers, release scripts: build
• database migrations, schema files, SQL models: db

If staged files share a clear parent directory, use that parent directory name as the scope, such as auth for src/auth/reset.ts. If no useful scope exists, omit the scope: chore: update repository metadata.

For multi-area changes, choose the scope that matches the main intent. If the commit genuinely spans unrelated areas, omit scope or use a broad existing project term such as core.

Breaking Change Detection

Add ! after the type or scope when staged changes appear to break downstream callers or users. Treat these as breaking indicators:

• Public function, method, class, CLI command, endpoint, event, config, schema, or exported type is removed or renamed.
• Required parameters are added to public APIs.
• Parameter order or return shape changes for exported functions or documented endpoints.
• Database schema changes remove columns, rename columns, or add non-null required fields without defaults.
• CLI flags, environment variables, config keys, or response fields are removed or renamed.
• The diff or docs explicitly mention BREAKING CHANGE, breaking, migration required, or an incompatible version bump.

Do not mark ! for internal-only refactors unless there is clear evidence of public contract impact.

Output Rules

• Start with the recommended commit message in a fenced text block.
• Include 2-4 short bullets explaining why that message fits when the diff is non-trivial.
• If the type or scope is uncertain, briefly name the uncertainty and provide one alternate message.
• Never invent files or behavior not present in the staged diff.
• Never suggest a commit message when no files are staged.

Quality Checks

Before answering, verify:

• git status --short shows at least one staged file.
• The message reflects staged changes from git diff --cached, not unstaged changes.
• Multiple file types are handled by intent, not by extension alone.
• The selected type is one of feat, fix, docs, style, refactor, test, or chore.
• The scope is lowercase, concise, and derived from paths or domain terms.