jack-git-commit

name

jack-git-commit

description

Structured git commit skill for all agents and humans. Use when: committing code changes, the user says "commit", "/jack-git-commit", a worker completes a task and needs to commit, or any agent needs to record work in git. Generates Conventional Commit messages with traceable metadata footers (Goal, Step, Worker) so git log serves as a self-documenting work ledger. Enforces atomic commits, staged-only policy, and NEVER pushes.

Jack Commit

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

NEVER push to remote. Only push if the human explicitly says "push" in the current message. Do not offer or suggest pushing.

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.

Field	When	Example
Goal:	Worker executing a goal bundle	Goal: P2-finance-dashboard
Step:	Multi-step execution	Step: 3/5
Worker:	Autonomous agent commit	Worker: claude, Worker: codex, Worker: kimi
Skill:	Skill(s) invoked during the work	Skill: jack-git-commit, drawio
Plugin:	Plugin(s) used	Plugin: ai-builder-kit/executive-loop
MCP:	MCP server(s) used	MCP: claude-in-chrome, context7
Tools:	Claude tools / notable Bash commands used	Tools: WebSearch, WebFetch, Bash(rg, jq, gh pr view)
Co-Authored-By:	Attribution desired	Co-Authored-By: Claude <[e-mail]>

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? → git add -A (default: commit everything)
• 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. Present the analysis:

I see 2 separate concerns in these changes:

1. docs: README rewrite + new technical highlights (README.md, docs/**)
2. feat(skills): new jack-git-commit skill (.claude/skills/jack-git-commit/*)

Split into separate commits?

• List each concern with its type, description, and files
• User says no → commit as-is
• User says yes → unstage all, then stage and commit each concern one at a time

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 and present

Proposed commit:

  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)

Commit with this message?

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. Confirm

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

Rules

1. Never push unless human explicitly says "push" right now
2. Stage smart — nothing staged → 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; flag 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