Commit

commit

> Requires: the sibling protocols skill (shared protocol masters); uses skills.config.json when present. Missing protocols → tell the user to install the full supermodo package.

One line. Conventional Commits (conventionalcommits.org/en/v1.0.0). The diff is the source of truth; the message is its index entry — written for someone scanning git log --oneline a year from now.

The message is always the deliverable. Running the commit is an opt-in extra the skill offers after the message exists — never the default, never silent.

Read the changes

1. git status --porcelain — what's staged, unstaged, untracked.
2. Anything staged → describe ONLY the staged changes (git diff --cached).

Staged is what the commit will contain; unstaged noise is not your business.

1. Nothing staged → describe all uncommitted work: git diff HEAD plus

untracked files (read them if small, --stat view if large).

1. git log --oneline -15 — absorb the repo's vocabulary and format habits.
2. Session context tells you intent; the diff tells you what actually changed.

On conflict, the diff wins.

Large diff: read --stat first, then open only files whose purpose the stat doesn't reveal.

Format

()!:

• Types: feat, fix, refactor, perf, docs, test, chore, build, ci, style,

revert. Choose by what the change does, not where it lives. The common confusion: feat = new capability, fix = wrong behavior corrected, refactor = same behavior, new shape.

• Scope: diff confined to one package/app/area → its short name

(packages/data → data, apps/dashboard → dashboard). Multiple areas → omit scope. Never invent junk scopes like (core) or (misc) — an uninformative scope is worse than none.

• ! after type/scope when the change breaks consumers: removed or renamed

public API, changed behavior callers rely on, schema/format change.

• Description: imperative mood ("add", "fix", "remove" — not "added",

"adds"), lowercase start (acronyms and proper nouns keep their caps), ≤50 chars when possible, hard cap 72, no trailing period.

• Language: English. Reuse the project's own vocabulary from the diff and

the log — package names, task IDs (MC-1, RA-14), domain terms (materialize, watermark). The message should read like the team wrote it.

One line — hard rule

No body. A breaking change is carried by !, not prose. Only exception: breaking/security/migration cases where one line cannot hold the essential warning — then at most ONE body line, blank-line separated (spec format):

feat(api)!: rename /v1/orders to /v1/checkout

BREAKING CHANGE: /v1/orders returns 410 after 2026-06-01

Never more than that.

Mixed-concern diffs

When the diff contains genuinely unrelated changes, produce two outputs:

1. Default message — one line covering everything honestly. Same type:

concatenate with + (docs: lease spec + entity bridge design). Different types: lead with the dominant type (feat > fix > refactor > perf > docs > test > chore) and + the rest.

1. Split suggestion — after the message, propose the cleaner history.

Each suggested commit is a pair of ready-to-run commands — git add with its exact files, then git commit -m — in its own fenced code block so the user can click-copy and run the whole pair. If the session is working in a worktree or a non-main branch checkout (compare git rev-parse --show-toplevel / pwd with where the user's shell likely sits), open with a cd block to that path so the commands land in the right tree:

```` Better as 2 commits:

``bash cd /path/to/worktree ``

1. ``bash git add packages/data/src/watermark.ts git commit -m "fix(data): guard null watermark" ``

2. ``bash git add docs/architecture/lease.md git commit -m "docs: pipeline lease spec" ` ```

Every changed file appears in exactly one suggested commit. Skip this section entirely for single-concern diffs — don't manufacture splits.

Never in the message

• "This commit...", "I", "we", "now", "currently" — the diff already says what
• AI attribution ("Generated with Claude...") — unless the repo's own rules

require a trailer

• Emoji (unless the repo's log shows that convention)
• File names the scope already implies

Deliver

Both steps, in order — neither substitutes for the other:

1. Copy to clipboard via the Bash tool (skip silently if pbcopy unavailable):

``bash pbcopy EOF ``

1. Print the message in your FINAL text response, alone in its own fenced

code block, so the user sees it and can click-copy it. The pbcopy tool call is invisible to the user — a message that only appears inside the heredoc was never delivered. Then say it's on the clipboard.

Offer to commit (after the message)

Once the message is printed and on the clipboard, ASK the user whether the agent should commit for them. Ask per the shared question protocol (../protocols/references/questions.md): plain chat by default, one plain-language line of what will happen, with declining as the default. Example:

> Commit these changes with that message? (default: no — message only) > 1. Claude suggests: commit the N files that make up this change > 2. Codex counters: unavailable (single-model) — or the adversary's take if run > 3. More detail — show the full staged diff and per-file reasoning, then re-ask > 4. Your own answer (e.g. exclude a path, split the commit)

Decline (the default) → done. Message only. Never touch git state.

Explicit yes → this yes IS the authorization that overrides any standing no-commit policy for THIS commit only. Then, in order:

1. Inspect the index first. git status --porcelain. If anything is

already staged, or a tracked file has both staged and unstaged hunks (mixed-hunk), those are the user's own in-flight changes. REFUSE to proceed unless the user separately authorizes including them — do not quietly sweep them into the commit. State exactly what is pre-staged and ask whether to include it or stop.

1. Stage only the relevant paths — the specific files the message

describes, named explicitly (git add …). Never git add -A / ..

1. Preview the final staged diff (git diff --cached --stat then the full

git diff --cached) so the user sees exactly what will be committed.

1. Show the exact commands you are about to run — the literal git add …

and git commit -m … lines — in a fenced block.

1. Run them. Never amend, never push, never force. One commit.

Still never: push, merge, rebase, amend, force-anything, or any git mutation the user did not authorize with the yes above.

Flow integration

When invoked by the flow orchestrator, commit is stage 8 (final):

• Diff scope is the flow baseline. Flow records the git status/diff

baseline before stage 1; the message is generated ONLY from flow-owned changes (including librarian's stage-1/7 doc edits), never from pre-existing user changes in the tree. Read the baseline from the run state (.skills/supermodo/runs//state.json).

• Ambiguous overlap → ask, don't guess. If flow-owned changes overlap or

interleave with pre-existing user changes (mixed hunks, shared files), stop and ask the user rather than deciding what belongs to the flow.

• Write the stage report per ../protocols/references/reports.md to

.skills/supermodo/runs//08-commit.md (skill: commit, status, summary = the message + whether a commit was made or just proposed).

• The ask-to-commit prompt and its safety steps above are unchanged in flow;

decline default still means message only.

Examples

Staged diff: rounding bug fixed in invoice totals ✅ fix(billing): round invoice totals half-up

Staged diff: new CSV export module in packages/data with tests ✅ feat(data): add csv export for fact tables

Unstaged diff: crash guard in config loader + unrelated README quickstart ✅ fix: guard empty config on boot + docs quickstart …followed by a 2-commit split suggestion.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: supermodo
• Source: supermodo/skills
• License: MIT

Install and usage instructions live in the source repository linked above.