Analyze changes and generate a Conventional Commits message explaining the motivation behind the change.

Mode: analyze

Inspect staged or unstaged changes and classify the commit type and scope.

Steps:

1. Run git diff --staged — if empty, run git diff HEAD to capture unstaged changes
2. Group changed files by logical concern (feature, fix, refactor, docs, config, tests, ci)
3. Identify the type from the change pattern:
   • feat — new capability or behavior added
   • fix — corrects broken or incorrect behavior
   • refactor — restructures code without changing behavior
   • perf — measurably improves performance
   • test — adds or corrects tests only
   • docs — documentation only
   • chore — build tooling, dependency updates, config changes with no production effect
   • ci — changes to CI/CD pipelines or workflow files
   • revert — reverting a prior commit
4. Infer scope from the most specific common ancestor: module name, service name, directory, or filename
5. Check for breaking changes: API removals, signature changes, config renames, behavior inversions — flag with ! and add BREAKING CHANGE: footer
6. Report: detected type, scope, whether breaking, and a one-line WHY summary

Reference: references/conventional-commits.md → Type Classification, Scope Rules

Mode: generate

Generate a complete conventional commit message from diff or description.

Steps:

1. Run analyze mode first to determine type, scope, and breaking status
2. Write the subject line:
   • Format: <type>(<scope>): <imperative verb> <what and why>
   • Max 72 characters
   • Imperative mood: "add", "fix", "remove", "update", "extract" — not "added", "fixes"
   • Focus on the WHY, not just the what: "fix(auth): validate token expiry before redirect" not "fix(auth): update token check"
3. Write the body (when the subject line is insufficient):
   • Wrap at 72 characters
   • Explain the problem being solved and the approach chosen
   • One blank line between subject and body
4. Write footers:
   • BREAKING CHANGE: <description> for breaking changes (also add ! to subject)
   • Fixes #<issue> or Closes #<issue> for linked issues
   • Co-authored-by: if applicable
5. Output the full message in a code block ready to copy

Message structure:

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

<body — optional, explains motivation and approach>

<footers — optional>

Reference: references/conventional-commits.md → Message Structure, Body and Footer Rules

Mode: stage

Intelligently stage files for a logical, atomic commit.

Steps:

1. Run git status to list all modified, added, and deleted files
2. Group files by logical change:
   • Source files that implement a single feature or fix together
   • Test files that cover those source changes
   • Documentation that describes those changes
   • Config or build changes that support those changes
3. Separate unrelated changes into distinct groups — each group should be a separate commit
4. If multiple logical groups exist: present the groupings and ask which to stage first
5. Stage the chosen group: git add <files>
6. Confirm staged set with git diff --staged --stat
7. Run generate mode to produce the commit message for the staged group

Reference: references/conventional-commits.md → Atomic Commits

Mode: validate

Validate an existing commit message against the Conventional Commits specification.

Steps:

1. Accept the message as input (or read from git log -1 --format=%B)
2. Check subject line:
   • Has valid type from the allowed list
   • Scope (if present) uses lowercase, no spaces
   • ! before : only when BREAKING CHANGE footer is also present
   • Subject after : starts with lowercase, no period at end, ≤ 72 chars
3. Check body (if present):
   • Separated from subject by exactly one blank line
   • Lines wrap at 72 characters
4. Check footers (if present):
   • BREAKING CHANGE: value is non-empty
   • Issue references use correct format (Fixes #N, Closes #N)
5. Report: PASS or list of violations with the exact rule broken and the corrected line

Reference: references/conventional-commits.md → Validation Rules