claude-skills/engineering/commit-craft
Claude d233831cc6
feat(engineering): commit-craft, a clean commit series from a mixed tree
Issue #1004 named a real gap: agents leave large mixed diffs, and
nothing in the catalog shapes them into commits before they exist.
Built independently from public sources.

- commit_planner.py groups the working tree in build-safe order
  (manifest with lockfile, moves, formatting, each change with its
  tests, docs, CI), holds back .env/keys/tfstate, and flags a move
  whose callers' import edits sit in another commit, because that
  commit would not build. A plain mv is detected as a rename.
- secret_gate.py blocks staged or pushed secrets, sensitive files and
  conflict markers with redacted output and reasoned waivers. On 174k
  lines added to this repo it raised 7 findings, all fake fixtures.
- message_linter.py blocks vague subjects, large changes with no why
  and fixup commits, and enforces Conventional Commits only where the
  repo already uses them.

Standalone plugin at 2.14.5, mirrored into engineering-advanced-skills
(bumped to 2.14.8, above the unreleased 2.14.7 on dev). The
bundle's G12 baseline grows by the new skill's 279 listing chars.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L8KYFJm9vze5Kqnyb5yvFs
2026-10-31 06:36:29 +00:00
..
.claude-plugin feat(engineering): commit-craft, a clean commit series from a mixed tree 2026-10-31 06:36:29 +00:00
agents feat(engineering): commit-craft, a clean commit series from a mixed tree 2026-10-31 06:36:29 +00:00
commands feat(engineering): commit-craft, a clean commit series from a mixed tree 2026-10-31 06:36:29 +00:00
skills/commit-craft feat(engineering): commit-craft, a clean commit series from a mixed tree 2026-10-31 06:36:29 +00:00
README.md feat(engineering): commit-craft, a clean commit series from a mixed tree 2026-10-31 06:36:29 +00:00

commit-craft

Turn a tangled working tree into a commit series a reviewer can read one commit at a time: one logical change per commit, in an order where each builds, with no secrets and a message that says why.

What it does

Script Job Blocks on
commit_planner.py Groups the working tree into commits: manifest with lockfile, pure moves, formatting, each module's change with its tests, docs, CI. Prints the git add commands .env, keys, tfstate in the tree (held back)
secret_gate.py Scans the lines a commit adds (staged, or a range before push) Provider tokens, high-entropy secrets, sensitive files, conflict markers
message_linter.py Lints one message or a series, matching the repo's convention Vague subjects, 72+ char subjects, large changes with no body, fixup!/WIP left before push

All three are stdlib Python, call git read-only, and never stage, commit or push. Each supports --help, --sample and --output json.

Install

/plugin marketplace add alirezarezvani/claude-skills
/plugin install commit-craft@claude-code-skills

Commands: /cs-commit-craft (plan, gate, commit a series) and /cs-commit-check (check staged work or a range). Agent: cs-commit-craft.

Optional git hooks run the gate and linter on every commit and push:

export COMMIT_CRAFT_SCRIPTS=/path/to/commit-craft/skills/commit-craft/scripts
cp skills/commit-craft/assets/hooks/{pre-commit,commit-msg,pre-push} .git/hooks/

Limits

  • The planner cannot read intent. It never chooses feat or fix, and two unrelated fixes in one file need git add -p.
  • The secret gate is pattern matching at commit time: no live-key verification and no history audit. Use an open-source history scanner for that.
  • WHY_MISSING is a keyword heuristic and only warns.

Origin

Proposed in issue #1004. Built independently from public sources (Git SubmittingPatches, the Linux kernel patch guide, Google's Small CLs, Conventional Commits 1.0.0, the OWASP Secrets Management Cheat Sheet); no code or text from the proposer's pack was used.

MIT © Alireza Rezvani