| name | git-commit-formatter |
| description | Structure and format Git commits under the Atomic Commit Protocol (ACP) — every commit self-contained, tested, documented, one logical change, in Conventional Commits format. Use whenever you are about to commit, or when ACP is mentioned and you need the rules or what the acronym means. This skill is the canonical definition of ACP. Triggers on: 'git commit', 'commit this', 'commit these changes', 'ACP', 'atomic commit', 'atomic commit protocol', 'conventional commits', 'what is ACP', 'commit message'.
|
Commit — Atomic Commit Protocol (ACP)
ACP = Atomic Commit Protocol. A specification for Git micro-commits: each
commit is a complete, self-contained, logically indivisible unit of work —
code, tests, and docs together, one logical change, never leaving the codebase
inconsistent. Not to be confused with Agent Client Protocol, an unrelated
Copilot CLI server mode.
You must adhere to the Atomic Commit Protocol (ACP) before making any git commit. The ACP guarantees that every commit is a complete, self-contained, and logically indivisible unit of work.
Core ACP Composition Rules
An Atomic Commit MUST contain the following elements. Do not commit until all conditions are met:
- One Logical Change: Do NOT mix functional changes with refactoring or formatting. Split unrelated changes into separate commits.
- Implementation & Verification:
- You MUST include TDD tests that validate the implementation. At least one test MUST have failed prior to the implementation and pass afterward.
- Run the test suite and confirm it passes. Never commit broken code.
- Documentation: You MUST include updates to end-user documentation or inline code comments that reflect the change and explain non-obvious logic.
- Cleanliness: You MUST remove all temporary files, build artifacts, debug statements (
console.log, print), and leftover comments before committing.
- Intentional Staging: Use
git add <files> for specific paths. Do NOT use git add . blindly.
For the full formal specification, including rationale and TDD mapping, read: references/acp-spec.md
Commit Message Format
<type>(<scope>): <Summary starting with Capital letter>
<Body explaining the "why", wrapped at 72 chars>
<Impact and Testing evidence>
1. The Header (Subject Line)
- Type (Required):
feat, fix, docs, refactor, chore, test, perf, style, ci
- Scope (Optional): Short noun for the affected area (e.g.,
auth, api)
- Summary (Required):
- MUST be 50 characters or less.
- MUST be in the imperative mood (e.g., "Add feature", not "Added feature").
- SHOULD be Capitalized.
- MUST NOT end with a period.
2. The Body
- MUST be separated from the header by a single blank line.
- MUST explain the reasoning and context behind the change (the "why"), rather than just repeating what the code does.
- SHOULD wrap lines at 72 characters.
- SHOULD include an
Impact: section and a Testing: section detailing how the code was verified (see Appendix B in the spec for an example).
What NOT to Do
- Do NOT add
Signed-off-by or sign-off footers unless explicitly requested.
- Do NOT include breaking-change markers or BREAKING CHANGE footers unless explicitly requested.
- Do NOT push — only commit. The user decides when to push.
Steps Before Committing
- Review Diff: Run
git diff --cached to catch accidental debug lines or unrelated changes.
- Verify Tests: Run tests (e.g.,
make test, pytest, npm test) and ensure the GREEN state.
- Match Conventions: Run
git log -n 5 --pretty=format:%s to match existing project style.
- Draft Message: Ensure it follows the ACP format and explains the "why".
- Commit: Execute the commit. If the change spans multiple logical units, make separate, sequential atomic commits.
