---
name: git-workflow
description: "Work safely with Git — keep changes scoped and reviewable, never overwrite the user's work, and produce clear history. Use before editing, branching, staging, or committing."
generated: true
source: .ai/skills/git-workflow.md
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/git-workflow.md and run `make generate-ai`.
-->

# Skill: Git Workflow

## Purpose

Work safely with Git: keep changes scoped and reviewable, never overwrite the
user's work, and produce clear history.

## When to Use This Skill

- Before editing files (inspect current state first).
- Branching, staging, or committing.
- Preparing a change set or pull request for review.

## Files to Read First

- `AGENTS.md` (git safety + scope rules).
- `docs/DEVELOPMENT_WORKFLOW.md`.
- The current diff/status of the repository.

## Core Principles

- **Inspect before editing.** Run `git status` and `git diff` to understand
  uncommitted work; never clobber the user's changes.
- **Keep changes scoped** to one task; avoid massive unrelated diffs.
- **Don't reformat or move files outside scope.**
- **Commit only when asked.** Do not auto-commit; never force-push shared
  branches or skip hooks.
- **Clear messages.** Use a conventional, scoped commit style.
- **No secrets.** Never stage `.env`, credentials, or large binaries.

## Process

1. **Inspect:** `git status` and `git diff` (and `git log --oneline -5` for
   message style). Note any pre-existing uncommitted work to preserve.
2. **Scope the change** to the current task; keep unrelated edits out.
3. **Stage deliberately** (`git add <paths>`) — review what's staged; ensure no
   secrets or ignored files sneak in.
4. **Commit when asked**, using the format below and a HEREDOC for the message.
5. **Summarize** the modified files in your final response.

## Commit message format

Use a conventional prefix:

- `feat:` a new feature/capability
- `fix:` a bug fix
- `refactor:` behavior-preserving restructuring
- `docs:` documentation only
- `test:` tests only
- `chore:` tooling/config/housekeeping

Example: `docs: consolidate agent instructions under .ai/`

## Checklist Before Finishing

- [ ] Inspected `git status`/`git diff` before editing; no user work clobbered.
- [ ] Change is scoped to one task; no unrelated churn.
- [ ] No secrets, `.env`, or large binaries staged.
- [ ] Commit message (if committing) uses the conventional format.
- [ ] Only committed because the user asked.
- [ ] Modified files summarized in the final response.

## Common Mistakes to Avoid

- Editing without first checking for uncommitted user work.
- Sweeping reformat/rename diffs mixed with logic changes.
- Committing secrets or ignored files.
- Auto-committing when not asked, or force-pushing shared branches.
- Vague commit messages with no scope/prefix.

## Expected Final Report

State: the result of the pre-edit inspection; the list of modified/created files
and how they map to the task; whether a commit was made (and its message); and
confirmation that no secrets or out-of-scope changes were included.