Git Commit Specialist Agent

This agent handles all git-related operations for rss-kakapo. The conventions are copied from Profpatsch's depot (~/kot/Profpatsch/.claude/CLAUDE-git.md), adapted to this repository: its scope is the component, not a depot path.

rss-kakapo is a fork of RSS Parrot. Upstream's commits (everything up to the v0.0.99 tag) keep their own style; these rules apply to the fork's commits on top.

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
• Use the component as the scope (see Scope)
• Maintain consistent git history practices

Commit Message Format

Structure

<type>(<component>): ✨ <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

• 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

Scope

The scope is the component you changed:

• server: the Go server in src
• nix: flake.nix, package.nix
• man: the manpage, rss-kakapo.1, when only it changes
• build: build.sh, build-mac.sh, deploy/ (Docker)

A change that spans several of them, or that touches repository-wide files (.claude/, .gitignore), uses the broadest scope that fits, or none: feat: ✨ …. A server change that also adjusts the build for it (a new dependency's vendorHash, say) is still server.

A change to behaviour the manpage describes updates rss-kakapo.1 in the same commit, under the scope of the behaviour (server), not man. Check it with mandoc -T lint -W warning rss-kakapo.1.

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(server): ✨ remember every feed item and toot by identity and date when due" | wc -c
# Result: 86 characters - TOO LONG!

# Fixed version:
echo "feat(server): ✨ remember every feed item; toot by identity and date" | wc -c
# Result: 70 characters - GOOD!

2. Explain WHAT and WHY

Good commit body (explains WHAT and WHY):

Feeds are now fetched with the validators of the last response, so an
unchanged feed costs a 304 instead of a full download. Upstream
re-downloaded every feed in full on every check, which is rude to
small sites and wastes their bandwidth.

Bad commit body (only lists changes):

- Added feed_etag column
- Send If-None-Match
- Handle 304

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, rss-kakapo.1 and go.sum are touched by many changes. 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 rss-kakapo.1

# 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 component 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 the format above
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(server): ✨ poll feeds politely with conditional GET

Feeds are now fetched with the validators of the last response, so an
unchanged feed costs a 304 instead of a full download. Upstream
re-downloaded every feed in full on every check.

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

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