name: commit
description: Detect the repo's commit convention (Conventional Commits, Gitmoji, or a custom template) and create commits. Use when asked to commit, write a commit message, stage and commit changes, or commit and push work.

Commit

Follow the repo's existing convention, create the commit, verify, and push when requested.
Use the reference docs for detailed rules.

Workflow

1. Identify the convention
2. Read agent guidance first: AGENTS.md, CLAUDE.md, etc.
3. Check repo guidance or templates if present: CONTRIBUTING.md, README.md, commit templates, etc.
4. Scan history: git log -n 50 --pretty=%s
5. Choose exactly one: Conventional Commits, Gitmoji, or Custom.
6. If ambiguous, pause and ask using the user input guidance below.

7. Never invent new commit types or emoji codes.

8. Pull if requested

9. If --pull is set, run git pull before reviewing changes.

10. If conflicts occur, try to resolve them. If you cannot, pause and ask using the user input guidance below.

11. Review changes

12. git status -sb
13. git diff --stat
14. git diff (or git diff --staged)

15. Split unrelated changes into separate commits.

16. Stage intentionally

17. Prefer git add -p or git add <files>

18. Do not stage secrets or large generated artifacts unless explicitly requested.

19. Run verify steps

20. If the repo has tests, lint, or format checks, run them before committing.
21. Only proceed if they pass, unless the user requests --no-verify.

22. If checks fail, try to resolve them. If you cannot, pause and ask using the user input guidance below.

23. Compose the message

24. If a convention is identified, you MUST open the matching reference and follow its rules before composing the message.
25. Conventional Commits: follow references/conventional-commits.md.
26. Gitmoji: follow references/gitmoji.md.
27. Custom template: follow the exact pattern from history or the template file.

28. Use a body and trailers when needed (blank line before body, wrap at 72 chars).

29. Commit, inspect, and push

30. git commit -m "subject" (use a heredoc for a body).
31. git log -1 --format="%h %s"
32. git show --stat
33. If --push is set, push to the current branch after commit.
34. If push fails, pause and ask using the user input guidance below.

User input guidance

If you cannot proceed, pause and ask. Examples include: ambiguous convention, unresolved conflicts, failed checks, or a failed push.

• Summarize the current state and what you attempted.
• Offer a recommended option and why.
• List alternative options the user can choose.

Options

These options can be expressed in natural language, not just the flag form.
Honor the user's explicit request even if it does not use --flag syntax.

• --dry-run: analyze changes and recommend a commit message, but do not commit or push
• --no-verify: skip tests, lint, and format checks even if they exist
• --pull: run git pull before reviewing changes; attempt conflict resolution
• --push: push to the current branch after commit

Important Rules

• ALWAYS identify the repo convention and follow it over defaults.
• ALWAYS open the matching reference and follow its rules before composing the message.
• ALWAYS run verify steps if they exist, unless the user requests --no-verify.
• ALWAYS summarize state and propose options when you need user input.
• NEVER invent new commit types or emoji codes.
• NEVER stage secrets or large generated artifacts unless explicitly requested.
• NEVER push unless the user requests --push.
• NEVER compose a commit message without checking the matching reference.

References

• references/conventional-commits.md
• references/gitmoji.md