Git Workflow

Use this skill for Git procedures. Mandatory authorization and preservation gates remain in the Git rule (${HANDBOOK_ROOT}/rules/130-git.mdc) and the agent audit rule (${HANDBOOK_ROOT}/rules/020-agent-audit.mdc).

Non-Negotiable Workflow

1. Inspect the repository before changing it:

   GIT_REPO_ROOT="$(git rev-parse --show-toplevel)"
   git -C "$GIT_REPO_ROOT" status --short --branch
   git -C "$GIT_REPO_ROOT" branch --show-current
   git -C "$GIT_REPO_ROOT" rev-parse HEAD

2. Use the quoted GIT_REPO_ROOT variable for repository-relative paths and artifacts. Never derive the root from pwd or a workspace assumption.
3. Preserve unrelated user changes. Never discard, stash, rewrite, or relocate them merely to simplify the task.
4. Treat commit, push, force update, history rewrite, restore/discard, worktree creation, worktree removal, and destructive branch deletion as separate authorization boundaries. Never create a worktree without explicit HITL approval of the exact repository, path, branch, base ref, and command.
5. Run applicable tests, lint, formatting, type checks, and build steps before proposing a commit.
6. Before committing, show the complete message and exact file list, then wait for explicit confirmation.
7. Respect repository signing policy. If signing fails, stop; never silently create an unsigned commit.
8. Before pushing, fetch with pruning and inspect upstream divergence. Do not blindly pull, rebase, merge, or force-push.

Common Workflows

Create a feature branch

Start from a refreshed remote base.

For a clean worktree:

git fetch origin --prune
git switch main
git pull --ff-only
git switch -c feat/your-feature

When the current worktree has unrelated changes, preserve it. If an isolated worktree is proposed, show the exact repository, destination path, branch, base ref, and command, then wait for explicit HITL approval:

git fetch origin --prune
git worktree add -b feat/your-feature ../project-your-feature origin/main

The command above is a preview, not authorization to execute it. A request to implement, create a branch, parallelize work, or preserve unrelated changes does not authorize worktree creation.

Do not use git switch -c in a dirty worktree: compatible uncommitted changes can follow the new branch. Do not create a replacement worktree unless the human explicitly approves it.

Prepare a commit

Inspect status, staged and unstaged changes, and recent message style. Record the pre-task path baseline and treat every unrelated path as potentially owned by another user or agent session.

Stage explicit task paths, never the whole worktree by default. Avoid broad commands such as git add -A, git add ., or git commit -a when unrelated changes exist.

Run required hooks and generation after staging the intended change. Then compare status and the staged diff with the baseline:

• Include formatting, generated files, manifests, lockfiles, or configuration changes produced directly by task-scoped pre-commit hooks or an authorized dependency/tool upgrade when they are required for the commit.
• Review those induced changes, rerun applicable verification, and describe material hook or upgrade effects in the commit message.
• Leave all pre-existing and concurrently created unrelated files untouched and unstaged. A hook modifying unrelated paths is not permission to absorb them.
• Stop and investigate if provenance is ambiguous or a hook causes unexpectedly broad changes.

Before requesting commit approval, inspect the exact staged diff and show its complete added, modified, renamed, and deleted file list. Use the format and review gate in git-workflow.md (${HANDBOOK_ROOT}/skills/git-workflow/git-workflow.md).

Push an existing branch

git fetch origin --prune
git status --short --branch
git log --oneline --left-right --boundary HEAD...@{upstream}

• Ahead only: push after authorization.
• Behind only: fast-forward only when repository policy permits.
• Diverged: stop and choose merge or rebase based on repository policy and whether commits are shared.
• Dirty worktree: do not rebase or merge until unrelated work is understood and preserved.

Use git push -u origin HEAD only for a new branch without an upstream. Never force-push unless that exact update was explicitly authorized; never force-push a protected default branch.

Recover safely

Inspect reflog and repository state before choosing a recovery operation. Prefer creating a recovery branch or restoring a specific object over destructive reset. See git-reflog.md (${HANDBOOK_ROOT}/skills/git-workflow/git-reflog.md).

References

• Git fundamentals (${HANDBOOK_ROOT}/skills/git-workflow/git-fundamentals.md) - refs, remotes, fetch/pull, and branch workflows
• Git workflow (${HANDBOOK_ROOT}/skills/git-workflow/git-workflow.md) - commits, signing, branches, PRs, and repository hygiene
• Modern Git commands (${HANDBOOK_ROOT}/skills/git-workflow/git-modern-commands.md) - switch, restore, moves, and worktrees
• Reflog (${HANDBOOK_ROOT}/skills/git-workflow/git-reflog.md) - recovery and history inspection
• Pre-commit (${HANDBOOK_ROOT}/skills/git-workflow/git-pre-commit.md) - hook setup and maintenance