git-workflow

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

<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

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

<branch_naming>

Branch Naming Conventions

Pattern

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

Branch Types

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

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

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

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 </checklist>

To load: Ask for the specific topic or check if context suggests it. </references>

Emit Outcome Sidecar

Write to ~/.claude/skill-analytics/last-outcome-git-workflow.json: {"ts":"[UTC ISO8601]","skill":"git-workflow","version":"1.0.0","variant":"default","status":"[success|partial|error]","runtime_ms":[ms],"metrics":{"commits_created":[n],"prs_opened":[n],"branches_managed":[n]},"error":null,"session_id":"[YYYY-MM-DD]"}