---
name: git
description: Enforce semantic versioning and strict Git commit message formats (topic-level). Use when committing code, parsing git history, or writing commit messages.
---

# Git Instructions

## 🎯 Purpose
Establish absolute control over Git execution and enforce high-level, topic-based commit message structures.

**🚨 CRITICAL: If the user asks for examples of formatting, or asks why their commit message style was rejected, you MUST use the `read_file` tool to read `.ai/skills/git/REFERENCE.md`.**

## 🚨 Prohibitions (Thou Shalt Not)

- **NEVER EVER execute state-modifying Git commands (`git add`, `git commit`, `git push`, `git reset`) without explicit user permission ("commit this now", "go ahead").** Show the command and wait.
- **NEVER list filenames in a commit message.** The git UI already shows which files changed.
- **NEVER include "CHANGES:", "Expected:", "Result:", or "Impact:" headers.** Commit messages describe the repository state change, not speculative outcomes.
- **NEVER write line-by-line technical mechanic breakdowns in the body.** Summarize the business/functional goal as a high-level topic.
- **NEVER describe runtime behavior, incident narrative, or manual operations** (e.g., "gitea failed on startup", "cleared redis cache").

## Workflows (Generating Commits)

When the user asks for a commit message:
1. **Analyze Diff:** Run `git diff --staged` (or `git diff`) and read what actually changed. Never guess.
2. **Docs Check:** Scan changed files and ask yourself: does a `README.md` or `docs/` file need updating based on this? If yes, alert the user but do not block the commit.
3. **Draft Message:** Write the message inside ONE fenced code block (`text`).
   - Subject: max ~72 chars, imperative mood (`<type>(<scope>): <high-level topic>`).
   - Body: optional, separating distinct topics if the `why` isn't obvious. Use prose (one sentence) for a single goal; use bullets ONLY for multiple completely distinct goals.
4. **Format Output:** Put *only* the commit message content inside the block. No "Suggested message:" text before or after it.

## ✅ / ❌ Examples

### Generating the Output
```text
// ❌ FORBIDDEN: Prose wrapped around the message, wrong message format
Here is the suggested commit message:
feat(api): add auth.js and modify user.js to support oauth
Expected impact: Users can log in properly.

// ✅ REQUIRED: Strict text block, topic-level summary
```text
feat(auth): enable oauth authentication flow
```

### High-Level Topic Summarization
```text
// ❌ FORBIDDEN: Line-by-line mechanics, lists files, mentions incidents
fix(docs): docs/ai-context.md added k3s target and fixed the helm crash

// ✅ REQUIRED: Intent-driven abstraction
fix(docs): document development environment and deployment context
```