---
name: git-workflow
description: >
  Atomic commit grouping, selective staging, conventional commit messages, and clean git history hygiene.
  Use when preparing commits, staging changes selectively, reviewing git diffs, or standardizing commit messages.
concerns: [system-one-balance]
---

# Git Workflow & Atomic Staging

Enforces clean, logical version control hygiene, atomic commits, and conventional commit standards across repositories.

---

## Phase 0: Setup and Protocols

1. **Non-Negotiable Invariants**:
   - **Never Stage Unrelated Edits**: Inspect `git status` and diffs before staging. Stage only files directly relevant to the current task. Preserve untouched user work.
   - **Never Use Destructive Resets**: Never execute `git reset --hard` or `git checkout .` without explicit user instruction.
   - **Verify Before Committing**: Run quality gates (tests, linter) before creating commits.

---

## Phase 1: Ingest and Check

1. Run `git status` to inspect modified, staged, and untracked files.
2. Review `git diff` for staged vs. unstaged changes to ensure no extraneous edits or debug logs are included.
3. Identify the logical boundaries of the work to separate independent changes.

---

## Phase 2: Processing (Core Logic)

### Step 1: Logical Commit Grouping
Group changes into focused, cohesive commits rather than bulk-committing unrelated subsystems:
1. **Infrastructure & DDL**: Table migrations, config schemas, and models.
2. **Core Logic**: Services, domain algorithms, and processors.
3. **API & Routes**: Web endpoints, controllers, and schemas.
4. **Tests & Docs**: Automated tests, documentation, and specs.

### Step 2: Selective Staging
- Stage specific files explicitly:
  ```bash
  git add path/to/file1 path/to/file2
  ```
- Avoid blanket `git add .` when unstaged experimental edits exist in the workspace.

### Step 3: Conventional Commit Formatting
Follow standard conventional commit prefixes:
- `feat(<scope>):` New functionality or feature.
- `fix(<scope>):` Bug fix or regression resolution.
- `refactor(<scope>):` Code restructuring without behavioral change.
- `perf(<scope>):` Performance optimization.
- `sec(<scope>):` Security hardening or vulnerability fix.
- `docs(<scope>):` Documentation updates.
- `test(<scope>):` Adding or updating tests.
- `chore(<scope>):` Tooling, dependencies, or maintenance.

---

## Phase 3: The System One Balance Pass

- **Augment, Don't Handcuff**:
  - Safe operations (e.g. `git status`, `git diff`, staging known files, creating a commit) must be frictionless fast paths.
  - Do NOT prompt the user with interactive confirmation modals for routine commits during an ongoing implementation.
  - Reserve confirmation prompts strictly for irreversible actions (`git push --force`, `git branch -D`, `git clean -fdx`).

---

## Phase 4: Output Execution & Verification

1. Create the commit with a concise, descriptive message.
2. Verify commit creation:
   ```bash
   git log -n 1 --oneline
   ```
3. Confirm working tree status remains clean and expected.