--- name: git-hygiene description: How to track our work through commits, pull-requests, and pushes. Maintain proper git hygiene in our chaotic, multi-agent environment through atomic commits, with the option to have code reviewed by AI agents with PRs. --- # Git Hygiene ## Rules - link associated **Linear** issues (e.g., `XY-123`) when committing (when present) - keep local work on `main`; use PR branches only for review/delivery when asked - I am a one man team, working too fast to deal with endless PRs and branches - prefer **atomic commits**: only committing your work, listing paths explicitly and checking the code for changes from other agents - prefer **explicit paths** (or `git add -p`) over `git add .` - quote paths containing brackets/parentheses so the shell doesn't treat them as globs/subshells. - do not let a dirty working tree block progress - commit only staged changes (your files); ignore other dirty files - never stage/commit someone else’s changes “just to clean things up” - avoid operations that require a clean working tree (rebases, non-ff merges) unless explicitly needed - commit by default - Do **not** push or open PRs unless the user explicitly asks for it - do **not** run destructive git ops (`git reset --hard`, force pushes, etc.) unless explicitly instructed - Before deleting files (or using deletion to "fix" tests/lint), stop and ask - never discard file content you didn't author (e.g., `git restore `, `git checkout -- `) unless explicitly instructed - `git restore --staged ...` is allowed for staging hygiene (it does not discard working tree changes) - always double-check `git status` before and after each commit ## Dirty Working Tree (Multi-Agent Reality) Goal: keep shipping without stepping on other agents. - You can always commit your work while other files are dirty: stage only your paths, then commit. - Prefer fetch-only “sync” (`git fetch origin --prune`). It never touches the working tree. - Avoid rebasing and avoid merging `origin/main` into a dirty working tree unless explicitly required (e.g., GitHub shows unavoidable conflicts / branch protection requires up-to-date). ## Remote Sync (origin/main) Default: stay productive. Fetch for awareness. Only “integrate” when necessary. - Always safe: `git fetch origin --prune` - Avoid `git pull` by default (it bakes in merge/rebase behavior that’s easy to forget). - If you ever run `git pull` and it blocks/conflicts: do not stash or commit random work “to unblock”. Stop and ask Ian for input. - Prefer merge commits on PR merge (see **Commit + PR Workflow**) so local commits keep their SHAs. 1. **Refresh your view of remote** - `git fetch origin --prune` 2. **Check divergence** - `git rev-list --left-right --count origin/main...HEAD` - Output is ` ` (how many commits you are behind/ahead of `origin/main`) 3. **Pick the safe action** - `behind>0` and `ahead=0`: optional fast-forward (only if the working tree is clean) - `git merge --ff-only origin/main` - `behind=0` and `ahead>0`: you’re ahead locally; OK to keep committing locally - `behind>0` and `ahead>0`: you have local commits *and* `origin/main` moved - default: do nothing; keep committing your work; publish via PR branch when asked - avoid rebasing local `main` (rewrites history) unless explicitly instructed ## Modes - **Commit-only (default):** create atomic commits locally. - **Commit + PR (only when explicitly requested):** create atomic commits, push to a `pr/...` branch, open PR, optionally trigger AI review, and (optionally) merge. ## Commit Messages Use a conventional prefix, then a concise summary. If a Linear issue exists, include it consistently. - prefixes: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `agents:` - preferred issue format: append in parentheses: `... (XY-123)` ## Staging Cookbook Keep these moves in muscle memory: - stage interactively: `git add -p` - stage explicit paths: `git add path/to/file.ts path/to/other.ts` - unstage (keep edits): `git restore --staged path/to/file.ts` - amend last commit (local only): `git commit --amend` - inspect staged-only scope: `git diff --staged --name-only` ### Commit Workflow (DEFAULT) 1. **Snapshot state + sanity-check scope** - `git status -sb` - `git diff` - `git diff --staged` - `git diff --staged --name-only` - `git diff --name-only` (optional; useful to spot other-agent edits you should ignore) - `git log -5 --oneline` 2. **Refresh remote view (cheap)** - `git fetch origin --prune` 3. **Propose a commit plan** - Group changes by issue or intent & suggest commit titles (see **Commit Messages** above) - Call out anything ambiguous and ask before proceeding 4. **Execute commits one by one** - Stage minimally (`git add -p` or explicit paths) - Avoid `git add .` unless the user explicitly asks for a "one big commit" - Run the smallest relevant verification (tests / lint / build) - Write a clear message; include linked issue IDs when applicable (Linear/GitHub) 5. **Final check** - Confirm your intended changes are committed (or explain what remains dirty) - Summarize what each commit contains + any follow-ups ## Commit + PR Workflow (WHEN REQUESTED) 1. Do the **Commit** workflow above first 2. **Fetch before publishing** - `git fetch origin --prune` - `git rev-list --left-right --count origin/main...HEAD` - If you are `behind>0` and `ahead=0` and the working tree is clean: optionally fast-forward (`git merge --ff-only origin/main`) - Otherwise: do not block; proceed to publish PR branch 3. **Push to a PR branch (without switching branches)** - Branch naming: `pr/` - `git push origin HEAD:pr/` 4. **Create PR**: prefer non-interactive creation and self-assigning: - `gh pr create --head pr/ --base main --assignee @me --fill` 5. **Review loop**: set a 5 minute timeout and then check the PR’s GitHub comments for AI code-review agent feedback (automatically triggered on PR creation) - if straightforward/clear, do yourself and commit/push; if unclear/opinionated, ask for feedback - repeat **review loop** until satisfactory (check-in if repeated issues) 6. **Merge**: once everything looks good, provide a summary and ask for merge approval - prefer merge commits to avoid rewriting commit SHAs (keeps local `main` compatible with `origin/main`): - `gh pr merge --merge --delete-branch` - if blocked (required reviews/checks), leave a handoff with PR number + what's missing ## Rebase Safety If rebasing is required, avoid interactive editor prompts: - prefer scoping to a single command (avoid persistent shell env changes): - `GIT_EDITOR=: GIT_SEQUENCE_EDITOR=: git rebase origin/main` - (or use `--no-edit` when safe)