git-workflow

This skill complements worktree-manager-skill (which handles parallel development) by providing the conventions for commits and PRs within those worktrees.

<quick_start> Conventional Commit format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Example:

git commit -m "feat(auth): add JWT refresh token rotation

Implements automatic token refresh 5 minutes before expiry.
Closes #123"

Branch naming: <type>/<ticket>-<short-description>

git checkout -b feat/AUTH-123-refresh-tokens

</quick_start>

<success_criteria> Git workflow is successful when:

• All commits follow conventional commit format
• Branch names follow <type>/<ticket>-<description> pattern
• PRs use consistent template with summary, test plan, and checklist
• Merge strategy matches branch type (squash for features, merge for releases)
• Commit history tells a clear story of changes
• No force pushes to main/master without explicit team agreement </success_criteria>

<conventional_commits>

Conventional Commits Specification

Based on conventionalcommits.org

Commit Types

Type	Description	Changelog Section	Version Bump
feat	New feature	Features	Minor
fix	Bug fix	Bug Fixes	Patch
docs	Documentation only	-	-
style	Formatting, no code change	-	-
refactor	Code change, no feature/fix	-	-
perf	Performance improvement	Performance	Patch
test	Adding/fixing tests	-	-
build	Build system changes	-	-
ci	CI configuration	-	-
chore	Maintenance tasks	-	-

Breaking Changes

Add ! after type or BREAKING CHANGE: in footer:

# Method 1: Bang notation
feat(api)!: change response format to JSON:API

# Method 2: Footer
feat(api): change response format to JSON:API

BREAKING CHANGE: Response structure changed from { data } to { data, meta, links }

Scope Guidelines

Scope is optional but recommended. Use consistent scopes per project:

# Good scopes
auth, api, ui, db, config, deps

# Examples
feat(auth): add OAuth2 support
fix(api): handle null response from external service
docs(readme): add installation instructions

Commit Message Structure

<type>(<scope>): <subject>
│       │         │
│       │         └─> Summary in present tense, no period, max 50 chars
│       │
│       └─> Component/area affected (optional)
│
└─> Type: feat, fix, docs, style, refactor, perf, test, build, ci, chore

[blank line]
[optional body - explain what and why, not how]
[blank line]
[optional footer(s) - breaking changes, issue references]

Good vs Bad Examples

Bad	Good	Why
fixed bug	fix(auth): prevent token expiry race condition	Specific, scoped
updates	refactor(api): extract validation middleware	Describes change
WIP	feat(ui): add loading skeleton (WIP)	Clear intent
misc changes	chore: update dependencies to latest versions	Typed, meaningful
</conventional_commits>

<branch_naming>

Branch Naming Conventions

Pattern

<type>/<ticket-id>-<short-description>

Branch Types

Type	Use For	Example
feat/	New features	feat/AUTH-123-oauth-login
fix/	Bug fixes	fix/API-456-null-response
hotfix/	Urgent production fixes	hotfix/PROD-789-payment-failure
docs/	Documentation	docs/README-update
refactor/	Code restructuring	refactor/cleanup-legacy-api
test/	Test additions	test/add-auth-integration
chore/	Maintenance	chore/update-deps
release/	Release branches	release/v2.1.0

Naming Rules

1. Lowercase only - feat/auth-login not feat/Auth-Login
2. Hyphens for spaces - fix/null-response not fix/null_response
3. Include ticket ID when available - feat/JIRA-123-description
4. Keep short - 50 chars max including type prefix
5. Be descriptive - feat/user-profile not feat/feature1

Protected Branches

Branch	Protection	Merge Strategy
main	Require PR + review	Squash merge
develop	Require PR	Merge commit
release/*	Require PR + CI pass	Merge commit

Examples

# Feature work
git checkout -b feat/PROJ-123-user-authentication

# Bug fix
git checkout -b fix/PROJ-456-login-redirect-loop

# Hotfix (from main)
git checkout main
git checkout -b hotfix/PROJ-789-payment-timeout

# Documentation
git checkout -b docs/api-endpoint-reference

# Chore
git checkout -b chore/upgrade-node-20

</branch_naming>

<pr_templates>

Pull Request Templates

Standard PR Template

## Summary
<!-- 1-3 bullet points describing the change -->
-

## Type of Change
<!-- Check one -->
- [ ] feat: New feature
- [ ] fix: Bug fix
- [ ] docs: Documentation
- [ ] refactor: Code restructuring
- [ ] test: Test coverage
- [ ] chore: Maintenance

## Test Plan
<!-- How did you verify this works? -->
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated (if needed)
- [ ] No console.log or debug code
- [ ] No sensitive data exposed

## Related Issues
<!-- Link related issues -->
Closes #

## Screenshots
<!-- If UI change, add before/after -->

Minimal PR Template (for small changes)

## What
<!-- One sentence -->

## Why
<!-- One sentence -->

## Test
<!-- How verified -->

Closes #

Release PR Template

## Release v{VERSION}

### Changes Since Last Release
<!-- Auto-generated or manual list -->

### Breaking Changes
<!-- List any breaking changes -->

### Migration Guide
<!-- If breaking changes, how to migrate -->

### Deployment Notes
<!-- Any special deployment steps -->

### Rollback Plan
<!-- How to rollback if issues -->

</pr_templates>

<merge_strategies>

Merge Strategies

Strategy by Branch Type

Branch Type	Strategy	Rationale
feat/*	Squash	Clean single commit in main
fix/*	Squash	Clean single commit in main
hotfix/*	Merge	Preserve hotfix history
release/*	Merge	Preserve release commits
refactor/*	Squash or Rebase	Depends on commit count

Git Commands

# Squash merge (recommended for features)
git checkout main
git merge --squash feat/my-feature
git commit -m "feat(scope): description"

# Merge commit (for releases)
git checkout main
git merge --no-ff release/v2.0.0

# Rebase (for clean linear history)
git checkout feat/my-feature
git rebase main
git checkout main
git merge feat/my-feature

# Interactive rebase (clean up before PR)
git rebase -i HEAD~5

Squash vs Merge Decision Tree

Is this a feature or fix branch?
├── Yes → Squash merge
└── No → Is this a release or hotfix?
    ├── Yes → Merge commit (preserve history)
    └── No → Consider context

</merge_strategies>

<commit_hooks>

Commit Hooks (Optional Enforcement)

commitlint Configuration

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore'
    ]],
    'scope-case': [2, 'always', 'lowercase'],
    'subject-case': [2, 'always', 'sentence-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100],
  }
};

Husky Setup

# Install
npm install -D husky @commitlint/cli @commitlint/config-conventional

# Initialize
npx husky init

# Add commit-msg hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Pre-commit Checks

# .husky/pre-commit
#!/bin/sh
npm run lint
npm run test -- --run

</commit_hooks>

Version Format

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └─> Bug fixes (fix:)
  │     │
  │     └─> New features (feat:)
  │
  └─> Breaking changes (feat!: or BREAKING CHANGE:)

Version Bump Rules

Commit Type	Example	Version Change
fix:	fix: null check	1.0.0 → 1.0.1
feat:	feat: new endpoint	1.0.1 → 1.1.0
feat!:	feat!: new API format	1.1.0 → 2.0.0

Automated Versioning

# Using standard-version
npx standard-version

# Using semantic-release (CI)
npx semantic-release

<workflow_examples>

Complete Workflow Examples

Feature Development

# 1. Create feature branch
git checkout main
git pull origin main
git checkout -b feat/PROJ-123-user-profile

# 2. Make commits (conventional format)
git add .
git commit -m "feat(ui): add profile avatar component"
git commit -m "feat(api): add profile update endpoint"
git commit -m "test(profile): add integration tests"

# 3. Rebase if needed
git fetch origin
git rebase origin/main

# 4. Push and create PR
git push -u origin feat/PROJ-123-user-profile
gh pr create --title "feat(profile): add user profile page" \
  --body "## Summary\n- Add profile avatar\n- Add update endpoint\n\nCloses #123"

# 5. After approval, squash merge
gh pr merge --squash

Hotfix Flow

# 1. Create from main
git checkout main
git pull origin main
git checkout -b hotfix/PROD-456-payment-timeout

# 2. Fix and commit
git commit -m "fix(payment): increase timeout to 30s

Production payments timing out during high load.
Closes PROD-456"

# 3. Push and merge (no squash to preserve hotfix history)
git push -u origin hotfix/PROD-456-payment-timeout
gh pr create --title "hotfix: payment timeout" --body "Emergency fix"
gh pr merge --merge

Release Flow

# 1. Create release branch
git checkout develop
git checkout -b release/v2.1.0

# 2. Version bump
npm version minor
git commit -am "chore(release): v2.1.0"

# 3. Merge to main
git checkout main
git merge --no-ff release/v2.1.0
git tag v2.1.0

# 4. Back-merge to develop
git checkout develop
git merge release/v2.1.0

</workflow_examples>

Before each commit:

• Commit message follows conventional format
• Type is accurate (feat/fix/docs/etc.)
• Scope matches affected component
• Subject is imperative, present tense
• Breaking changes marked with ! or footer

Before creating PR:

• Branch name follows convention
• Rebased on latest main/develop
• All commits are meaningful (squash fixups)
• PR template filled out completely
• Related issues linked

Before merging:

• All CI checks pass
• Required reviews obtained
• No merge conflicts
• Correct merge strategy selected

Topic	Reference File	When to Load
Commit message examples	reference/commit-examples.md	Need more examples
PR template variants	reference/pr-templates.md	Project-specific templates
Git hooks setup	reference/git-hooks.md	Setting up enforcement

To load: Ask for the specific topic or check if context suggests it.