git-workflow

name	git-workflow
description	Conventional commit style, branch naming, and merge-conflict resolution, with commit-commands plugin and `gh` CLI integration. Use when working with version control, creating branches, writing commits, or resolving merge conflicts.

Git Workflow

Use these conventions when working with version control, creating branches, writing commits, or resolving merge conflicts.

Plugins for Git Work

Plugin / Tool	When to Use
commit-commands:commit	Create conventional commits — handles staging, message formatting, and pre-commit checks
commit-commands:commit-push-pr	Commit, push, and open a PR in one flow
commit-commands:clean_gone	Clean up local branches that have been deleted on remote (marked [gone]), including worktrees
gh CLI	GitHub operations — create/edit PRs, link issues, add labels, request reviewers, post comments (gh pr create, gh pr edit, gh issue create)

Prefer plugins/CLI over raw git for:

• Committing — commit-commands:commit enforces conventional commit format
• PR creation — commit-commands:commit-push-pr opens the PR; use the gh CLI for labels, linked issues, and reviewers
• Branch cleanup — commit-commands:clean_gone safely removes stale branches and worktrees

Commit Messages

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Good: feat(auth): add OAuth2 support for GitHub login Bad: fixed stuff

Branch Naming

<type>/<ticket>-<description>

Examples:

• feature/PROJ-123-user-authentication
• fix/PROJ-456-null-pointer-crash
• hotfix/PROJ-789-security-patch

Non-Interactive Git

All git commands must be non-interactive (see rules/execution-hygiene.md):

# Always use --no-pager or GIT_PAGER=cat
git --no-pager log -10
git --no-pager diff
GIT_PAGER=cat git show HEAD

# Commit with message (never open editor)
git commit -m "feat(auth): add login endpoint"

# Merge without editor
git merge --no-edit feature-branch

# Rebase non-interactively
git rebase --no-edit main

Common Operations

# Squash last N commits (non-interactive)
git reset --soft HEAD~N && git commit -m "squashed commit message"

# Cherry-pick specific commit
git cherry-pick <sha>

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Find commit that introduced bug
git bisect start
git bisect bad HEAD
git bisect good <known-good-sha>

# Stash with description
git stash push -m "WIP: auth middleware"
git stash pop

Merge Conflict Resolution

1. git status — identify conflicted files
2. Open file, look for <<<<<<<, =======, >>>>>>>
3. Keep correct code, remove markers
4. git add <file> then git rebase --continue or git merge --continue

When resolving conflicts, investigate both sides before choosing — the conflicting code may represent someone else's in-progress work.

Pre-Commit Checks

Always run before pushing:

• Linting/formatting
• Unit tests
• Type checking (if applicable)

# Example pre-push verification
npm run lint && npm test && npx tsc --noEmit && git push

Worktrees

For isolated feature work (used by superpowers:using-git-worktrees):

# Create a worktree for isolated feature work
git worktree add ../project-feature feature/PROJ-123-description

# List active worktrees
git worktree list

# Clean up after merge (or use commit-commands:clean_gone)
git worktree remove ../project-feature

Worktrees are useful when fullstack-agent orchestrates parallel task groups that need file-level isolation beyond what the task ownership rules provide.

Agent Integration

• fullstack-agent creates feature branches before starting spec-driven work
• coding-agent and devops-agent commit their changes with conventional commit messages matching the task scope
• All agents use --no-pager and GIT_PAGER=cat for non-interactive output
• review-agent may use git diff to identify the exact changeset under review
• After all review cycles pass, use commit-commands:commit-push-pr or superpowers:finishing-a-development-branch to handle merge/PR creation
• Use the gh CLI to link PRs to issues and add reviewers (gh pr edit)