--- name: git_workflow_agents description: Git discipline for agent fleets: branch naming conventions, atomic conventional commits, rebase-versus-merge policy, worktree isolation so parallel agents do not collide, and commit templates that keep history readable months later. Use when an agent starts work in a shared repo, when two or more agents work on one repo in parallel, or when a repo's history needs cleanup rules. --- # Git Workflow for Agents ## Purpose Agents commit faster and sloppier than humans. That is fine, but the repo pays for it later: mystery commits, trampled branches, history that needs a translator. This skill gives a fleet a small set of rules that keeps any repo navigable: one branch per task, one logical change per commit, machine-readable messages, a clear policy on merge versus rebase, and worktrees so parallel agents never share a working directory. ## Workflow ### 1. Before touching the code Run the pre-flight check. Fix problems before writing code, not after. ```bash git status # clean tree required before switching tasks git branch --show-current # know which branch you are on git fetch origin # know what main looks like right now ``` If the tree is dirty and the changes belong to another task, stash them (`git stash push -m "wip: "`) or commit them. Never switch branches with uncommitted work and never mix two tasks in one working tree. ### 2. Branch for the task One task, one branch, one agent. Name it so the next person reading it knows what it is: ``` /- ``` Examples: `feat/123-user-auth`, `fix/456-payment-timeout`, `docs/api-readme`. Full naming schemes are in `references/discipline-details.md`. Never commit directly to `main`, `master`, or `dev`. Short-lived branch: merge back within a day, or it is a long-lived branch and needs an explicit plan. ### 3. Parallel agents get worktrees, not branches alone Two agents in one working directory will overwrite each other. Give each agent its own checkout of the same repo: ```bash git worktree add -b fix/456-payment-timeout ../myrepo-fix-456 ``` The agent works inside that directory and nowhere else. The primary checkout stays on main and is used only to review, merge, and push. A branch can be checked out in only one worktree at a time. When the task is done, `git worktree remove ../myrepo-fix-456` and `git worktree prune`. See `references/discipline-details.md` for the full pattern. ### 4. Commit as you go Commit early, commit often. One logical change per commit. Each commit must build and pass tests on its own, so any commit is safe to bisect or revert. If the subject needs "and", it is two commits. Stage deliberately: `git add ` or `git add -p`. Never blind `git add -A` or `git add .`. Before every commit, run `git diff --cached --stat` and confirm the diff covers exactly one concern. Message format is Conventional Commits (`[scope]: `), with an optional body for the why and footers for issue references. Copy `assets/gitmessage.txt` into the repo and point git at it: ```bash cp assets/gitmessage.txt .gitmessage git config commit.template .gitmessage ``` Run the included message linter as a local commit-msg hook (see `bin/check-commit-msg`). Details and full examples in `references/discipline-details.md`. ### 5. Land the work Decide how the branch lands using this rule set: - Cleaning up your own local commits before review: `git rebase -i` (squash fixups, reword, reorder). Only for history nobody else has seen. - Syncing your branch with upstream: `git pull --rebase`, which replays your commits on top and avoids noise merge commits. - Landing a feature into main: `git merge --no-ff` preserves the feature boundary, or squash-merge when the branch history is messy WIP. - Golden rule, never broken: **never rebase or force-push commits that exist outside your local repo.** If someone else may have pulled it, the history is immutable; use merge or `git revert`. - If force-push is unavoidable after a local rewrite, use `git push --force-with-lease`, never bare `--force`. - A rebase gone wrong: `git rebase --abort`, or recover from the reflog (`git reset --hard HEAD@{n}`). ## Output Contract A session run under this skill leaves behind: 1. A clean working tree (`git status` shows nothing unexpected). 2. One branch per completed task, named `/-`, off main. 3. Commits that each pass tests, each with a conventional commit message. 4. No commits on main/master/dev, no dirty shared state, worktrees removed and pruned. 5. Optionally: `.gitmessage` installed and the commit-msg hook active in the repo. ## Operating Rules 1. Dirty tree is a blocker, not a background detail. Never start a new task, switch branches, or merge into a dirty tree. Stash or commit first. 2. Every factual-looking claim in this skill was verified against the sources in `../skill-production/scratch/git-workflow-agents-sources.md` (repo is sibling to workspace). If a repo's own conventions conflict with this skill, the repo wins; match its existing history style (80 percent of recent commits sets the format). 3. Verify identity before any remote write: `git branch --show-current` and `git remote -v` before push. Push only the branch you were told to push. 4. Messages explain the why, not the how. The diff shows the how. Body wrapped at 72 characters, subject at 50 or fewer. 5. If quality of a commit cannot be verified (tests not run, diff spans two concerns), do not ship it; fix it in the run.