| name | commit-by-scope |
| description | Create one or more atomic Git commits from existing working-tree changes, grouping them by coherent scope and intent and writing Conventional Commits messages. Use only when the user explicitly asks to commit changes, create commits, split changes into commits, or commit each scope separately. Do not use for ordinary implementation work, commit planning without execution, amending history, rebasing, pushing, or opening pull requests unless the user separately requests those actions. |
Commit by Scope
Commit only the changes the user authorized, preserving unrelated work and producing a reviewable sequence of Conventional Commits.
Workflow
- Inspect repository instructions and the complete working-tree state with
git status --short, staged and unstaged diffs, and recent commit subjects.
- Identify the requested change set. Treat pre-existing or ambiguous changes as user-owned; do not include, discard, rewrite, or unstage them merely because they are present.
- Partition the requested changes by coherent intent and scope:
- create one commit when all changes form one indivisible behavior or maintenance unit;
- create multiple commits when groups have distinct purposes and each group remains valid and understandable on its own;
- keep implementation and its directly required tests, migrations, generated files, or localization updates together;
- do not split solely by file or directory when the files implement the same outcome;
- order dependent commits so every intermediate commit is internally consistent.
- Infer scopes from repository terminology and recent history. Prefer the narrowest stable subsystem name; omit the scope when no useful single scope exists.
- Choose the type from the actual intent:
feat for a user-visible capability;fix for a defect correction;refactor for behavior-preserving restructuring;perf for a performance improvement;test for test-only changes;docs for documentation-only changes;build for build system or dependency changes;ci for continuous-integration changes;chore for maintenance not better described above;revert for an explicitly requested revert.
- Stage only the first planned group. Use path-level or patch-level staging when a file contains changes for multiple groups. Never use broad staging such as
git add . unless every detected change is authorized and belongs to that commit.
- Review the staged name list, statistics, full diff, and
git diff --cached --check. If the index contains unrelated or ambiguous content that cannot be isolated safely, stop and ask the user how to proceed.
- Commit with the format
type(scope): concise imperative description, or type: concise imperative description when omitting scope. Add a body only when it explains non-obvious motivation or constraints. Mark a breaking change with ! and/or a BREAKING CHANGE: footer.
- Repeat staging, verification, and committing for each planned group. After every commit, confirm that the remaining working-tree changes match the uncommitted groups.
- Report the resulting commit hashes and subjects, plus any changes intentionally left uncommitted.
Safety Rules
- Require an explicit commit request; never commit as a side effect of implementing or reviewing code.
- Do not amend, squash, rebase, reset, restore, clean, delete, push, or force-push unless the user explicitly requests that separate action.
- Do not bypass hooks with
--no-verify or change Git identity or signing configuration.
- Do not claim validation succeeded unless it was actually run. If a hook fails, preserve the working tree, diagnose the failure, and report it; fix it only when the requested scope authorizes the change.
- Do not create empty commits unless explicitly requested.
- Follow the Conventional Commits 1.0.0 specification and prefer established repository conventions where the specification leaves choices open.
