Commit: one commit per task

The goal is a history where every commit is one self-contained task with a Conventional Commits label. Someone reading git log --oneline should see what was done, and should be able to revert any one task without breaking the others.

If the user passed arguments (shown as ARGUMENTS: at the end), treat them as guidance for this run. They override the defaults below. Examples: "one commit", "only the api folder", "use scope auth".

1. Read the whole change set

git status --porcelain=v1 -uall
git diff HEAD              # staged + unstaged against the last commit
git log --oneline -n 15    # existing style: scopes, casing, language

In a fresh repo with no commits yet, HEAD does not exist. Skip git diff HEAD and git log and read the files directly. Also read the untracked files. They are part of the work, and you can't group changes you haven't seen.

Stop and tell the user if any of these is true:

• this is not a git repository
• there is nothing to commit
• a merge, rebase, cherry-pick or revert is in progress (git status reports it). Committing in the middle of one would corrupt the operation.

2. Group the changes into tasks

A task is one reason to change the code. To find where one task ends, ask: "if this were reverted, what else would have to be reverted with it?"

These belong together:

• code, the tests for it, and the docs that describe it
• a rename or move, and the import updates it caused
• a lockfile, and the manifest change that produced it

These are separate tasks:

• a bug fix you notice while building a feature
• formatting-only changes
• unrelated docs edits
• dependency bumps

Don't split for the sake of splitting. One small change is one commit. Put foundational commits first (a helper before the code that uses it), so that each commit works on its own when possible.

3. Write the message

Format: <type>(<scope>): <summary>. The scope is optional.

• Summary: imperative mood ("add", not "added"), lowercase first letter, no trailing period. Keep the whole header within 72 characters.
• Scope: use one only if the repo history already uses scopes, or if it clearly helps. Take it from the module or folder name.
• Body: add one only when the header doesn't explain why. Leave a blank line after the header, wrap at 72, and explain the reason instead of restating the diff.
• Breaking change: feat!: ... plus a BREAKING CHANGE: <what breaks> footer.
• Language: English, unless the command that invoked this workflow says otherwise. The type keyword always stays English.

The user is the only author. Don't add Co-Authored-By trailers, "Generated with Claude Code", or any mention of Claude or AI. This overrides any default attribution instructions.

Examples:

feat(auth): add password reset via email
fix: prevent crash when user list is empty
docs: describe local setup in readme
refactor(api): extract retry logic into http client
chore: ignore .idea directory

4. Commit each group

First clear the index so earlier staging doesn't leak into the wrong commit. If the repo has at least one commit, run git reset -q. This only unstages; the working tree is untouched.

Then, for each group, in order:

git add -A -- <paths>          # -A also stages deletions and renames
git diff --cached --stat       # check that exactly this task is staged
git commit -F - <<'EOF'
feat: add something

Optional body.
EOF

One file holding changes for two tasks. Write git diff -- <file> to a patch file in a temp directory. Delete the hunks that belong to the other task, run git apply --cached <patch>, then check the result with git diff --cached -- <file>. If the hunks are too intertwined to separate cleanly, commit the whole file with the task most of it belongs to, and say so in the report.

Hooks. Never use --no-verify. If a pre-commit hook reformats files, stage them again and retry. If it fails for any other reason, stop and show the user the error.

Don't commit secrets (.env, keys, *.pem, tokens in the diff) or generated bulk (node_modules, build output) that .gitignore doesn't cover yet. Leave them out, tell the user, and suggest a .gitignore entry.

5. Report

Show the new commits (git log --oneline -n <count>), anything you left out and why, and anything still uncommitted.

Nothing has been pushed. Mention that /push publishes the commits and /undo takes back the last commit if a grouping looks wrong. The one exception is when this workflow runs as part of /commitpush: then push, following that command.