Git Workflow

Git Workflow

This skill governs the default Git shape of implementation work: which branch to use, how to name it, how to cut commits, and when it is safe to push or open a PR. It is intentionally lighter than the /git-commit-split custom command, which is for taking an already-dirty working tree and splitting it into commits or PRs.

Operating Rules

• Inspect Git state before edits: current branch, git status --porcelain=v1, and recent commit style when commit messages will be written.
• Never overwrite, reset, clean, or discard user changes unless the user explicitly asked for that exact destructive action.
• Do not force-push, merge PRs, or push directly to the default / protected branch.
• For implementation work, deliver through a feature branch and pull request unless the user explicitly asks for local-only work.
• Prefer one coherent VCS unit per applicable TSDD path. Both paths end Green. If the task is too small for multiple cycles, one commit is enough.
• Keep branch names and commit subjects aligned with the primary intent of the change, not with filenames.

Branch Policy

Prefer a feature branch in the current checkout for a single active task. Create a separate worktree only in the cases listed below.

Choose the workspace in this order:

1. If the user explicitly asks for a worktree, parallel work, isolated work, or another simultaneous task, create a sibling worktree.
2. If the user explicitly asks to avoid worktrees or continue in the current checkout, stay in the current checkout unless doing so would overwrite or mix unrelated changes.
3. If already on a suitable non-default branch for the task, stay there.
4. If on main, master, a release branch, or another protected/default branch:

• If the working tree is clean, create the task branch in the current checkout with git switch -c .
• If dirty changes clearly belong to this task, create the task branch in the current checkout and keep those changes.
• If dirty changes are unrelated to this task, create a sibling worktree.
• If ownership of dirty changes is unclear, ask before switching branches or creating a worktree.

1. If on a non-default branch for a different task:

• If the new request is a continuation of that branch, stay there.
• If the new request is unrelated, create a sibling worktree.

1. If the target branch is already checked out in another worktree, use that worktree or choose a different branch name. Do not force-checkout the same branch in two places.

Current-checkout branch creation:

git switch -c 

Task worktree creation:

git pull --ff-only  # when on the main worktree and updating the base branch
git fetch origin
git worktree add -b  ../- origin/
cd ../-

Rules:

• `` follows the branch name format below.
• ` is the branch name with / replaced by -`.
• Put task worktrees as siblings of the primary checkout under the same parent directory.
• Example: primary checkout /Users/kaito/ghq/github.com/furedea/agent-harness with branch ci/codex-conformance uses /Users/kaito/ghq/github.com/furedea/agent-harness-ci-codex-conformance.
• Append -2, -3, etc. to the worktree path if it already exists.
• When updating main itself, use git pull --ff-only in the main worktree. Do not use git pull --rebase origin main for the base branch.
• Do not remove, prune, move, or repair worktrees from the agent workflow; report stale worktrees to the user instead.

Branch name format:

/

Rules:

• ` is the Conventional Commits type that would be used for the primary commit: feat, fix, refactor, perf, docs, test, build, ci, chore, style, or revert`.
• `` is lowercase ASCII, hyphen-separated, derived from the imperative commit subject with no scope.
• Omit Conventional Commits scope from branch names.
• Append -2, -3, etc. if a local or remote branch already exists.

Examples:

feat/jwt-refresh-token-rotation
fix/parser-empty-input
refactor/extract-query-builder
docs/clarify-install-steps

Commit Granularity

Commit by intent, not by file.

• One user-visible feature, bug fix, refactor, documentation update, or config change per commit.
• Tests for a new behavior belong in the same commit as the implementation.
• Test-only coverage for existing behavior uses test:.
• Generated files and lockfiles belong with the change that caused them.
• Pure formatting belongs in style: when it would obscure a logic review.
• Do not fabricate splits. One cohesive change should be one commit.
• If one file contains multiple unrelated intents, split hunks or use the /git-commit-split custom command when the task is specifically to organize pending changes.

Before committing, verify the relevant test or quality gate is green. If the full suite is too expensive or unrelated failures exist, run the narrowest gate that proves the change and report the limitation.

Conventional Commits

Use Conventional Commits for every commit message.

(): 

Scope is optional:

• Use scope when all changed files clearly live in one module or area.
• Omit scope when the commit spans multiple top-level areas or repo-root files.
• Keep scope lowercase, single-word, and without slashes.

Subject rules:

• Imperative mood: add, fix, remove, rename.
• Lowercase first letter unless it is a proper noun or identifier.
• No trailing period.
• Aim for 50 characters or fewer; hard cap at 72.
• Describe behavior or intent, not filenames.

Use a body only when the why is not obvious from the subject. Wrap body text at about 72 columns.

Common types:

| type | when to use | | ---------- | ------------------------------------------------ | | feat | new user-visible capability | | fix | bug fix | | refactor | restructure without behavior change | | perf | performance-only change | | docs | documentation only | | test | test-only change for existing behavior | | build | build system, packaging, dependencies, lockfiles | | ci | CI configuration only | | chore | tooling/config that does not fit elsewhere | | style | formatting only, no logic change | | revert | reverts a previous commit |

Examples:

feat(auth): add JWT refresh-token rotation
fix(parser): handle empty input without panicking
refactor(db): extract query builder from repository
docs: clarify install steps for Apple Silicon
test(auth): cover refresh-token expiry edge case
build(deps): bump axios from 1.6.0 to 1.7.2

Delivery Flow

For implementation tasks:

1. Inspect branch and dirty state.
2. Select the checkout and branch using the Branch Policy above.
3. Classify the work under TSDD: use Red -> Green -> Refactor -> Green for a real contract gap; otherwise use Green baseline -> behavior-preserving change or Refactor -> Green.
4. Commit each coherent green unit when the user asked for commits or the repository workflow expects implementation work to be committed.
5. Unless the user asked for local-only work, push the feature branch and create a pull request:

• git fetch origin
• optionally git rebase origin/ before the first push when the feature branch should be refreshed onto the latest base
• git push -u origin
• gh pr create -f --base

1. Stop before merge; merging is a human decision unless the user explicitly asks for it.

For explicit commit requests:

1. Inspect all pending changes before grouping.
2. If changes are already mixed across multiple intents, switch to the /git-commit-split custom command instead of improvising partial commits here.
3. Otherwise commit one coherent intent with a Conventional Commits message.

For explicit PR requests:

1. Confirm the target base branch if it is not obvious from the repo default.
2. Push the feature branch with git push -u origin .
3. Create a normal PR with gh pr create -f --base .

For rebase and force-push:

• git rebase origin/ is allowed before the first push for a PR branch.
• git rebase --continue and git rebase --abort are allowed to complete or recover from that narrow workflow.
• Interactive rebase, --onto, and rebasing onto local branches are outside the default workflow; ask before using them.
• git push --force, git push --force-with-lease, and +refspec pushes are not part of the default workflow. Stop and ask the user if a remote history rewrite is genuinely required.

Relationship To /git-commit-split

Use this skill for normal work as it is being implemented.

Use the /git-commit-split custom command when the user's task is specifically to organize existing pending changes into multiple commits, multiple branches, or one PR per feature. Do not duplicate its hunk-splitting and PR-per-feature execution flow here.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: furedea
• Source: furedea/agent-harness
• License: MIT

Install and usage instructions live in the source repository linked above.