Jack Commit

Git history is the ledger. Every commit is queryable, traceable to its origin, and reviewable without external databases.

Commit, then push. Finished work goes to the remote on the current branch without asking, unless the project's instructions say not to. See step 7 for when to stop. Never force-push unless the human asks in the current message.

Format

type(scope): summary

Body: why, not what. Skip if diff is self-explanatory.

Footer metadata (one per line, only what's known)

Types: Standard Conventional Commits — feat, fix, refactor, docs, test, chore, style, perf.

Scope: Infer from primary directory/module. Examples: (vendor), (executive-loop), (skills). Omit if changes span too many areas.

Summary: Imperative mood, lowercase after colon, no period, max 72 chars total.

Body: Only when the why isn't obvious. What motivated the change, what was rejected, what edge case this covers.

Footer Metadata

Key: value lines that make git log --grep a queryable ledger.

Only include fields you actually know. Zero footer fields is fine — but if a skill, plugin, MCP server, or notable tool was used to produce the change, always record it. These are provenance: which capability authored what.

Workflow

1. Read state

git status --porcelain
git diff --staged --stat
git diff --staged
git log --oneline -5

Nothing staged and nothing modified → stop with "Nothing to commit."

2. Check .gitignore

Before staging, verify .gitignore exists and covers common entries. Warn the user if any of these are missing:

node_modules/
.env
.env.*
.DS_Store
dist/
*.log

If .gitignore doesn't exist at all, warn and ask before proceeding — don't commit without one.

3. Stage

• Nothing staged? → Stage the files this work changed, by path. Other agents may share the checkout, so leave changes you didn't make alone. Never git add -A.
• Something already staged? → Only commit what's staged, don't add more
• After staging, run git status to show what will be committed

3a. Always sweep in prompt logs and session records

Prompt logs (ai-docs/**/prompt-log*.md, ai-docs/**/*session*.md, .claude/projects/**/session-*.md) and retros (ai-docs/**/retro-*.md) are the provenance trail for the commits around them. They should NEVER be filtered out as "unrelated" — git history is only queryable if the why-we-did-this note lands in the same branch as the what-we-did diff.

Before proposing the commit:

git status --porcelain | grep -E '^\?\? .*(prompt-log|retro-|session).*\.md$' || true

If any match:

• Stage them into the current commit (do not split into a separate commit unless the user explicitly asks)
• Mention them in the commit body under a Provenance: line if space allows
• If the user said "commit only X," still ASK before dropping a prompt log — never silently exclude

This rule exists because on 2026-04-11 a prompt log for v2.1.6 was left untracked for two commits, breaking the "git log is the ledger" guarantee.

4. Check for mixed concerns

Review the staged diff and group changes by logical intent. If there is more than one concern, make one commit per concern, in dependency order, without asking. Only stop to ask if the split isn't clear.

4a. Record skills, plugins, MCP servers, and tools used

Before composing the message, recall what capabilities produced the staged changes:

• Skill(s) invoked this session that shaped the diff (e.g., drawio, pptx, excalidraw, playwright-cli)
• Plugin(s) active during the work
• MCP server(s) whose tools were called to produce or verify the change (e.g., context7 for docs lookups, claude-in-chrome for browser testing, stitch for design)
• Tools — Claude built-in tools (WebSearch, WebFetch, Agent, NotebookEdit, etc.) and notable Bash commands that materially shaped the change (e.g., rg, jq, gh pr view, curl, npm test, pytest, terraform plan)

Add each as a footer line (Skill:, Plugin:, MCP:, Tools:). If none were used, omit. Never fabricate — only list what was actually invoked in the conversation that produced this commit.

What counts as "notable" for Tools::

• ✅ External research (WebSearch, WebFetch, gh, curl to a real API)
• ✅ Verification / test runs whose output influenced the diff (npm test, pytest, terraform plan, cargo check)
• ✅ Code analysis that drove decisions (rg/grep, jq, ast-grep)
• ✅ Spawned Agent subagents
• ❌ Trivial built-ins: Read, Edit, Write, ls, cat, git status/diff/log, mkdir

When in doubt: if the tool's output shaped what you wrote, record it. If it was just navigation, skip it.

5. Generate message

  feat(vendor): add Kimi wire protocol support

  Implements bidirectional streaming for Kimi agent SDK,
  replacing the CLI fallback with native wire communication.

  Goal: P1-multi-vendor-workers
  Step: 2/4
  Worker: claude
  Skill: jack-git-commit
  MCP: context7
  Tools: WebSearch, Bash(rg, npm test)

6. Commit

git commit -m "$(cat <<'EOF'
<the approved message>
EOF
)"

HEREDOC for multi-line. Never --no-verify. Hook failure → show output and stop.

7. Push

Push the current branch once the work is committed, without asking:

git push origin HEAD      # first push of a branch: git push -u origin HEAD

8. Confirm

Committed: feat(vendor): add Kimi wire protocol support
  3 files changed, 147 insertions(+), 12 deletions(-)
  Pushed: origin/feat-multi-vendor

Rules

1. Push by default: follow step 7. Never force-push unless the human asks
2. Stage smart: nothing staged → stage the paths this work changed, never git add -A; something staged → commit only that
3. Always sweep prompt logs & retros — ai-docs/**/prompt-log*.md, ai-docs/**/retro-*.md, session records. These are provenance, not "unrelated files." Never silently exclude them.
4. Atomic: one logical change per commit; split mixed concerns
5. Respect hooks — never --no-verify
6. Don't fabricate — only include metadata you actually know
7. Always record capability provenance — if a skill, plugin, MCP server, or notable tool/Bash command materially shaped the change, add Skill: / Plugin: / MCP: / Tools: footer lines. Never silently omit.
8. Ask when uncertain — unclear intent → ask before committing
9. Universal — same format for human, Claude, Codex, Kimi