git_workflow_agents v1.0.0

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: <short note>") 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:

<type>/<issue-or-ticket>-<short-description>

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 <specific files> 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 (<type>[scope]: <description>), 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 <type>/<ticket>-<description>, 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.