Commit

Commit workflow

Work the steps in order. A guard hook runs alongside them and refuses whole-tree staging along with any git commit you write out yourself. Step 8 names the one script that commits, and that script refuses an inline -m message, a --no-verify, and a draft the reviewer hasn't seen in its current form.

Those hooks stay registered for the rest of the session so they carry a scope. Preflight records the commit HEAD sits on now, and the guard refuses while HEAD is still there. Step 8 moves HEAD past that mark, and the guard refuses nothing after that. Work later in the session is none of the guard's business. A second commit means invoking this skill again rather than carrying on from here.

Preflight

!bash ${CLAUDE_SKILL_DIR}/scripts/preflight.sh

Step 0: the checklist

Track these steps with the session's task-list tools where it carries them. Newer harnesses leave those tools out by default, and a session without them works the list in order as written. They're the checklist the rest of this document expands.

1. Choose the rebase base
2. Group the changes into atomic commits
3. Stage the paths for this commit
4. Draft the message in COMMIT_AGENTMSG
5. Pass the prose gates with fix-prose
6. Review the draft with review-commit-message
7. Run the commit-msg gates
8. Confirm the message with the operator
9. Commit and rebase

Stop before any of it if preflight reports a rebase, merge, or cherry-pick in progress, or a missing precondition. Say what's wrong and hand back.

Step 1: choose the rebase base

Preflight computed this under == rebase base ==. Take its recommendation:

• Local default branch carries everything the remote has, so rebase onto the local branch.
• Local default branch sits behind the remote, so rebase onto origin/<default> and skip the stale local copy.

Record the base now. Step 9 rebases onto it without asking again. Worktrees under .claude/worktrees are the usual layout here, and each one has its own checkout of the branch.

Step 2: group the changes into atomic commits

Read the diff before deciding anything. One commit carries one logical change: the reader can state its purpose in a sentence, and reverting it undoes that purpose and nothing else.

Split when the outstanding work covers more than one of these:

• A behavior change and an unrelated refactor
• A fix and the formatting sweep that came with it
• A pair of features that don't depend on each other
• Production code and unrelated tooling or configuration

A dependency doesn't force a split. Code and the test that covers it belong together, as do a change and the documentation that describes it.

When the work splits, commit the first group through this workflow, then say which groups remain and run the workflow again for each. Never bundle them because bundling is quicker.

When one file mixes two logical changes, stage the relevant hunks with git add -p, or say so and let the operator decide.

Step 3: stage the paths for this commit

Name every path:

git add -- path/one path/two

Never git add -A, git add ., or git add --all. They sweep in whatever else is uncommitted, which is how an atomic commit stops being atomic. The guard hook refuses all three.

Confirm the result with git diff --cached --stat and git status --short. The staged set matches the group from step 2, and anything left unstaged belongs to a later commit.

Step 4: draft the message in COMMIT_AGENTMSG

Write the whole message to COMMIT_AGENTMSG at the repo root. A gitignore entry keeps it out of history, and a post-commit hook deletes it after the commit succeeds.

Subject

<type>(<scope>)?(!)?: <description>, with the type drawn from the list preflight printed. Imperative mood, present tense, lowercase after the colon, no trailing period, and the whole line inside the bounds preflight reported. Write the description as the instruction the commit carries out: explain the tools, not explains and not explained.

Body

The body answers why this change exists. The diff already says what changed, and a reader who wants the what reads the diff.

Write:

• The problem, the constraint, or the tradeoff that made this the answer
• Why this approach rather than the obvious alternative
• What breaks without it, or where the need came from
• A decision worth recording, so nobody relitigates it later

Avoid:

• Restating the diff. Adds a helper to foo.go and calls it from bar.go is the diff, spelled out longer.
• Counting. No file, line, test, function, or commit counts. A count goes stale as soon as other work merges, and it reads as padding.
• Provenance filler. Nothing about requests, review rounds, sessions, prompts, models, or tools. The Assisted-by trailer carries attribution.
• Claims you haven't checked. Leave out benchmark numbers you didn't measure and a fixes the flake for a flake you never reproduced.
• Selling it. Drop robust, comprehensive, significantly, seamlessly, and their neighbors.
• Markdown. No fenced blocks, headings, emphasis, links, or tables. Backticks around a literal identifier are fine.

Hard wrap the body at the width preflight reported. Wrap trailers at the footer width.

Trailers

Assisted-by before Signed-off-by, matching the format and the sign-off identity preflight printed. Never credit a model through Co-authored-by.

Step 5: pass the prose gates

Invoke the fix-prose skill before the review, passing the draft and the task that judges it:

Skill(fix-prose, args: "COMMIT_AGENTMSG mise run lint-commit-msg")

It runs the lint rounds in a subagent, so the findings and the retries stay out of this session. The commit scope is stricter than the repository-wide one, and a message copied verbatim out of the diff still fails it, so this is rarely a no-op.

Order matters here. The review in the next step signs the exact bytes it read, and a later lint fix voids that signature and costs another review round over a comma. Running fix-prose first holds the loop to one round.

Where it returns PROSE: PARTIAL, a finding needs a decision rather than another round. Read the short list, settle it, and send the answer back in the arguments.

Step 6: review the draft

Invoke the review-commit-message skill, passing the repo root from preflight as its argument. It runs as an independent agent that hasn't watched you work, which is the point: it reads the draft against the staged diff with no memory of what you meant to write.

This step is mandatory, and the script in step 8 enforces it. A clean verdict signs the exact bytes of the draft, and a finding erases any earlier signature, so the commit stays blocked until a review clears the text as it stands. Editing the draft afterward voids the signature the same way.

Fix everything it returns. Push back only when it's demonstrably wrong about the diff, and say why.