Spec Commit

Step 2: Determine commit message convention

Follow this priority order:

1. Repo conventions already in context -- If project instructions (AGENTS.md, CLAUDE.md, or similar) are already loaded and specify commit message conventions, follow those. Do not re-read these files; they are loaded at session start.
2. Recent commit history -- If no explicit convention is documented, examine the 10 most recent commits from Step 1. If a clear pattern emerges (e.g., conventional commits, ticket prefixes, emoji prefixes), match that pattern.
3. Default: conventional commits -- If neither source provides a pattern, use conventional commit format: type(scope): description where type is one of feat, fix, docs, refactor, test, chore, perf, ci, style, build.

When using conventional commits, choose the type that most precisely describes the change (the type list above). Where fix: and feat: both seem to fit, default to fix:: a change that remedies broken or missing behavior is fix: even when implemented by adding code. Reserve feat: for capabilities the user could not previously accomplish. Other types remain primary when they fit better. The user may override for a specific change.

Step 3: Consider logical commits

Before staging everything together, scan the changed files for naturally distinct concerns. If modified files clearly group into separate logical changes (e.g., a refactor in one directory and a new feature in another, or test files for a different change than source files), create separate commits for each group.

Keep this lightweight:

• Group at the file level only -- do not use git add -p or try to split hunks within a file.
• If the separation is obvious (different features, unrelated fixes), split. If it's ambiguous, one commit is fine.
• Two or three logical commits is the sweet spot. Do not over-slice into many tiny commits.

Step 4: Stage and commit

If the current branch from the context above is main, master, or the resolved default branch from Step 1, committing directly is not an option in this workflow. Display the proposed feature-branch name and require branch_mutation_authorization: authorized before creation; otherwise return branch_mutation_authorization_missing before staging or committing.

Derive the branch name from the change content, validate it, and create it from the current HEAD so uncommitted work and any local-only commits stay attached to the new branch:

BRANCH_NAME="<branch-name>"
git check-ref-format --branch "$BRANCH_NAME"
git checkout -b "$BRANCH_NAME"
git branch --show-current

Use the confirmed branch name for the rest of the workflow. If the branch already exists, derive a safe unique name and retry once. If branch creation still fails, stop before staging and report the failure; do not commit on the default branch.

Write the commit message:

• Subject line: Concise, imperative mood, focused on why not what. Follow the convention determined in Step 2.
• Body (when needed): Add a body separated by a blank line for non-trivial changes. Explain motivation, trade-offs, or anything a future reader would need. Omit the body for obvious single-purpose changes.

For each commit group, stage specific files by name over git add -A or git add . to avoid accidentally including sensitive files (.env, credentials) or unrelated changes. Write the message to a temp file and commit with -F so multi-line bodies are preserved without shell interpolation:

COMMIT_MSG=$(mktemp "${TMPDIR:-/tmp}/spec-commit-message.XXXXXX")
cat > "$COMMIT_MSG" <<'EOF'
type(scope): subject line here

Optional body explaining why this change was made,
not just what changed.
EOF
git add file1 file2 file3
git commit -F "$COMMIT_MSG"

Step 5: Confirm

Run git status after the commit to verify success. Report the commit hash(es) and subject line(s).