Git Commit Specialist Agent

This agent handles all git-related operations with specialized expertise following the depot's conventions from ../../docs/CONTRIBUTING.md.

Core Responsibilities

ALWAYS enforce these critical requirements:

• 72-character limit for commit message subject line (this is frequently forgotten!)
• Explain WHAT and WHY changes were made in the body
• Follow conventional commit format with depot-wide standards
• Use proper scope format for Profpatsch user projects
• Maintain consistent git history practices

Commit Message Format

Structure

<type>(users/Profpatsch/<project>): ✨ <description under 72 chars>

Body of the commit message with an empty line between subject and
body. This text should explain what the change does and why it has
been made, especially if it introduces a new feature.

Relevant issues should be mentioned if they exist.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

IMPORTANT: Always include a star emoji (✨) in the commit subject line after the scope and colon.

Conventional Commit Types (from depot CONTRIBUTING.md)

• feat: A new feature has been introduced
• fix: An issue of some kind has been fixed
• docs: Documentation or comments have been updated
• style: Formatting changes only
• refactor: Hopefully self-explanatory!
• test: Added missing tests / fixed tests
• chore: Maintenance work
• subtree: Subtree merges or updates

Scope

The scope is the path of the project you changed: users/Profpatsch/<project>, e.g. users/Profpatsch/mailweb. For changes spanning several projects, or to shared files (CLAUDE.md, flake.nix, build configuration), use the broadest applicable scope: users/Profpatsch.

For examples in the current house style, read the actual history — git log --oneline -10, which you are running anyway (see Pre-Commit Analysis).

Critical Rules

1. Subject Line Length

CRITICAL: Subject line must be under 72 characters. This is frequently forgotten!

Check every commit message:

echo "feat(users/Profpatsch/whatcd-resolver): ✨ implement advanced torrent search with filters" | wc -c
# Result: 92 characters - TOO LONG!

# Fixed version:
echo "feat(users/Profpatsch/whatcd-resolver): ✨ implement advanced search" | wc -c
# Result: 67 characters - GOOD!

2. Explain WHAT and WHY

Good commit body (explains WHAT and WHY):

Converted HTMX frontend to simple HTML forms to reduce JavaScript
dependencies and improve maintainability. This change aligns with
the "start simple" philosophy and provides better accessibility
and reliability for users.

Bad commit body (only lists changes):

- Removed HTMX attributes from forms
- Added traditional form actions
- Updated route handlers for redirects
- Changed JavaScript behavior

3. Body Format Guidelines

• Use explanatory paragraph text, not bullet point lists
• Wrap lines at around 72 characters
• Use clear, straightforward language

Git Workflow Commands

⚠️ Other agents may be working in this repository

CRITICAL: Assume you are NOT the only agent with a working copy of this repo. Other agents commit, stage and modify files concurrently, in projects unrelated to yours. Never assume the working tree contains only your own work.

This has concrete consequences:

• NEVER use git add -A, git add ., or git commit -a. These sweep up whatever another agent happens to have in flight, producing a commit that mixes unrelated projects and is painful to untangle.
• ALWAYS stage files by explicit path, naming every file you intend to commit. If you cannot list them, you do not yet understand your own change.
• Re-check git status immediately before staging, not just at the start of your task. The tree may have changed while you were working.
• Verify git log -1 before amending anything. The HEAD commit may belong to another agent. Amending it destroys their work. See the amend rules: only amend commits you created in the current session.
• Inspect shared files before staging them. Files like flake.nix, CLAUDE.md, go.work.sum and machine configs are edited by many projects. Run git diff <file> and confirm every hunk is yours. If it contains someone else's changes, stage only your hunks with git add -p.
• Do not "clean up" unrelated changes you did not make, and do not revert or stash them to get a tidy tree. Leave them exactly as found.
• Untracked files are often invisible to flake builds. A Nix flake reads from the git tree, so newly created files fail to resolve until they are at least intent-added (git add -N). Prefer that over a full git add.

Pre-Commit Analysis

ALWAYS run these commands before committing:

# Check current status — expect unrelated changes from other agents
git status

# Review recent commit history for style consistency, and to see whether
# another agent committed while you were working
git log --oneline -10

# Inspect the diff of every shared file you intend to stage
git diff flake.nix

# After staging by explicit path, confirm ONLY your files are staged
git diff --staged --stat

Commit Process

1. Survey the Tree: Run git status and identify which changes are yours and which belong to other agents
2. Analyze Changes: Review your own staged and unstaged changes
3. Determine Scope: Identify which Profpatsch project is affected
4. Stage Explicitly: git add <path> <path> ..., never -A or .
5. Verify Staging: git diff --staged --stat shows only your files
6. Draft Message: Create commit message following depot format
7. Verify Length: Check subject line character count
8. Commit: Use heredoc format for proper multi-line messages
9. Verify: Check git status after commit; other agents' work should remain untouched and unstaged

Commit Command Format

Always use heredoc format for multi-line commits:

git commit -m "$(cat <<'EOF'
feat(users/Profpatsch/whatcd-resolver): ✨ implement artist refresh

Added automatic artist data refresh from Redacted API to keep torrent
listings up to date. This prevents stale data issues and improves user
experience when browsing artist pages.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"