commit-twiddle

name	commit-twiddle
description	Validates and corrects commit messages against project guidelines after a commit is created. Invoke automatically after every git commit to ensure messages conform to .omni-dev/commit-guidelines.md.
argument-hint	["commit-hash|range"]
allowed-tools	Bash(mkdir *), Read, Write, Edit, "omni-dev *"

Commit Twiddle

Validate and correct commit messages to conform to .omni-dev/commit-guidelines.md.

If $ARGUMENTS is provided, use it as the commit hash or range. Otherwise default to HEAD.

Step 1 — Analyse

omni-dev git commit message view $ARGUMENTS

The output is self-describing. Read the explanation.fields section to understand all available fields, then extract the values needed for Step 2.

Key fields to look at:

• commits[].original_message — the current message
• commits[].analysis.detected_type and detected_scope — what omni-dev detected
• commits[].analysis.diff_file — read this file to understand what actually changed
• ai.scratch — base path for temporary files

Step 2 — Craft corrected messages

For each commit, write a corrected message that conforms to the guidelines. Constraints:

• Type and scope must match the actual changes — read the diff if uncertain
• Scope must be one of the values defined in .omni-dev/scopes.yaml
• Subject line must be lowercase, imperative mood, no trailing period, ≤72 chars total
• No Co-Authored-By footers — do not add AI attribution lines
• Body required for changes >50 lines or architectural changes; wrap at 72 cols

Write the amendments file to <ai.scratch>/amendments-<random-8-hex>.yaml:

amendments:
  - commit: "<exactly 40 lowercase hex chars>"   # full SHA, not abbreviated
    message: |
      <type>(<scope>): <subject>

      <optional body wrapped at 72 cols>

      <optional footers — no Co-Authored-By>

Create the directory if the write fails:

mkdir -p <ai.scratch>

Step 3 — Apply

omni-dev git commit message amend <ai.scratch>/amendments-<random-8-hex>.yaml

Constraints

• The target commit must be at the branch tip with no merge commit above it. If a merge commit is present the amend will fail — work on the branch before merging.
• Use the exact 40-character SHA from the commits[].hash field. An abbreviated hash silently skips the amendment or errors.
• If the message is already correct, do nothing and say so.

Troubleshooting

If omni-dev is not installed: https://crates.io/crates/omni-dev (requires ≥ v0.3.0)