commit

Create minimal, cohesive commits from current changes.

Preconditions

• A message-only request authorizes drafting, not staging or committing.
• Never commit without reviewing the diff and confirming the intended scope.
• Stop on unresolved merge conflicts. Preserve existing staged work; ask if it conflicts with the requested commit.
• Never stage unrelated changes without user confirmation.
• Never use git add -A or git add ..
• Work artifacts (specs, plans, domain context, ADRs) live outside the repository in <work-area> = ~/.agent-work/<repo-key>/, where <repo-key> is the name of the git rev-parse --path-format=absolute --git-common-dir directory, or its parent's name when that is .git/.bare, without a trailing .git. A legacy in-repo .agent-work/ is not automatic commit content: do not stage it unless explicitly requested; if already staged, stop and ask rather than silently committing or unstaging it.
• When using work docs to establish commit intent, inspect <work-area>/work/<work-id>/spec.md and plan.md, follow reciprocal Spec/Plan links and Work-ID, and read acceptance criteria/non-goals. Use only an explicit user path, current-session confirmation, or validated reciprocal link. Otherwise shortlist titles/statuses/summaries and ask via question tool (even for one candidate), offering Other / None—standalone work; never guess from names, slugs, branch, or recency. If asking is unavailable, report the blocker. Missing docs need not be created. Selection does not authorize staging or commits.
• Never add Co-Authored-By trailers.
• Never amend an existing commit or create a fixup!/squash! commit unless the user explicitly asks. Never rebase, reset, stash, or push unless explicitly asked.

Workflow

1. Inspect state:

   git status --short
   git diff --stat

2. Read relevant diffs before deciding scope:

   git diff -- <path>
   git diff --cached -- <path>

3. Decide commit scope:
   • If all changes are one cohesive unit, commit them together.
   • If changes are unrelated, ask which files/hunks to include.
   • If generated or incidental files appear, call them out before staging.

4. Stage explicit files only. If a file mixes intended changes with unrelated hunks, ask before staging it; do not stage the whole file:

   git add -- path/to/file another/file

5. Write commit message:
   • Use one concise sentence for the title.
   • Prefer imperative mood.
   • Do not include a ticket or issue number unless the user explicitly requests it.
   • No trailers, including Co-Authored-By.
   • Default to a title only. Add a body only when omitting it would leave essential context unclear and a better title cannot convey that context. If in doubt, omit it.
   • A necessary body must be one short paragraph of clear, simple English. Explain only the essential reason, constraint or consequence; do not repeat the title, list changes or add filler.

6. Read the entire staged diff (git diff --cached) and run git diff --cached --check. A commit includes the whole index, not just the paths most recently staged. Confirm every hunk belongs to this commit; keep secrets and personal/customer data out of both diff and message. Then commit:

   git commit -m "Commit title"

   Only when a body meets step 5's strict necessity rule, append a second -m "Essential context" argument.

7. Report commit hash and title.

Failure handling

• If tests/lint are relevant and not run, mention that clearly.
• If git status --short shows unrelated changes, stop and ask for scope.
• If commit or a hook fails, report the redacted error and inspect status/diff for hook changes. Do not bypass hooks, blindly retry, or amend; propose the smallest fix.

Organize multiple commits

Use this branch when the user asks to organize commits, split changes into commits, or group staged/unstaged changes.

1. Inspect all changes:

   git status --short
   git diff --stat
   git diff --cached --stat

2. Read diffs before grouping:

   git diff
   git diff --cached

3. Propose commit groups before staging:
   • Group feature code with matching tests.
   • Keep docs/config/chore changes separate when they are independent.
   • Keep refactors separate from behavior changes when possible.
   • Call out unrelated or ambiguous files.
4. Ask for confirmation when:
   • More than one reasonable grouping exists.
   • Existing staged changes conflict with the proposed grouping.
   • Any file appears unrelated to the main work.
5. Create commits one group at a time:
   • Stage explicit files or hunks only.
   • Read git diff --cached and run git diff --cached --check before each commit; verify the entire index belongs to that group.
   • Default to title-only messages. Apply the message rules in Workflow step 5 separately to each commit; a body on one commit does not justify bodies on the others.
   • Repeat until intended changes are committed.
6. Finish with git status --short and list commit hashes/titles created.