git-workflow

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

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.