commit-craft

name: commit-craftdescription: "Turn a mix of changes into clean, reviewable commits with good messages, blocking staged secrets and .env files. Use whenever the user says commit this, wants to split work into commits, write a commit message, or is about to push."argument-hint: "[repo path | diff file | commit range]"license: MITmetadata:   version: 1.0.0  build_pattern: "Three deterministic stdlib scripts over git (series planner, staged-secret gate, message and series linter) with blocking exit codes and git hooks; rules cited to Git SubmittingPatches, the Linux kernel patch guide, Google's Small CLs, Conventional Commits 1.0.0 and the OWASP Secrets Management Cheat Sheet"  distinct_from: "changelog-generator (turns merged commits into release notes; this shapes the commits before they exist); pr-review-expert and code-reviewer (review a pushed change); git-worktree-manager (parallel branches); security-guidance (warns on risky code patterns while editing, not on secrets at commit time)"

Commit Craft

Portability: 3 stdlib Python scripts that call git read-only. No network. The scripts never stage, commit or push. You do, one group at a time, after the gate passes.

Agents leave large mixed diffs: a feature, a reformat, a dependency bump and a stray .env, all in one tree. Committed as one blob, that diff cannot be reviewed, reverted or bisected. This skill turns it into a series where each commit is one logical change, builds on its own, holds no secrets and says why.

Workflow

# 1 - Plan: which commits, in which order, staged how?
python scripts/commit_planner.py                 # working tree vs HEAD, untracked included
# 2 - For each group: stage exactly its files, then gate what is staged
git add -- <files of group N>                     # or git add -p for MIXED_FORMATTING files
python scripts/secret_gate.py                     # blocks before the commit exists
# 3 - Write the message, lint it, commit
python scripts/message_linter.py -m "<message>" --staged && git commit -m "<message>"
# 4 - Before push: the whole series, and proof every commit builds
python scripts/message_linter.py --range @{upstream}..HEAD
git rebase -x "<test command>" @{upstream}

Step 1 groups files: manifest with lockfile, pure moves, whitespace-only files, each module's changes with their tests, then docs and CI. It holds back .env, keys and tfstate (exit 4), flags files that mix formatting with real hunks, and flags a move whose callers' import edits sit in another group, since that commit would not build. It never picks feat vs fix: decide from what the change does.

Step 2 scans only the added lines of what is staged: provider-shaped tokens, high-entropy values assigned to key/secret/token/password, sensitive files and conflict markers. Output is redacted. A false positive is waived in .commit-craft-allow by fingerprint or path, with a reason.

Step 3 blocks vague subjects ("fix", "update"), subjects over 72 characters, no blank line after the subject, and a change of 40+ lines or 4+ files with no body. It enforces Conventional Commits only if the repo already uses them.

Step 4 also blocks fixup!/squash!/WIP commits and warns on duplicates and revert pairs. Install assets/hooks/ to run steps 2 to 4 on every commit and push.

Hard rules

• Never git add -A or git add . on a mixed tree. Stage each group by name or by hunk.
• A blocked gate means no commit. Remove the value and load it at runtime. Never --no-verify, never waive a real secret.
• A pushed secret is rotated first. Deleting it in a new commit leaves it in history (references/secret_response.md).
• Each commit builds. Tests ride with their change; moves carry their callers.
• The body says why. The diff already says what.
• Rewrite only unpushed history. Rebasing or amending shared commits is the user's call.

Scripts

All support --help, --sample and --output json.

References and assets

• references/commit_series_design.md: split, order and verify, with sources (7)
• references/message_discipline.md: subject, why-body, breaking changes, trailers (7)
• references/secret_response.md: what the gate catches, its limits, and the leak response order (7)
• assets/hooks/: pre-commit, commit-msg, pre-push
• assets/commit-craft-allow.example: waiver format
• assets/series_checklist.md: pre-push sign-off