---
name: git-workflow
description: This skill should be used when creating branches, writing commits, or creating pull requests. Enforces ISA-Frontend Git conventions including feature/task-id-name branch format, conventional commits without co-author tags, and PRs targeting develop branch.
---

# Git Workflow Skill

Enforces Git workflow conventions specific to the ISA-Frontend project.

## When to Use

- Creating new branches for features or bugfixes
- Writing commit messages
- Creating pull requests
- Any Git operations requiring adherence to project conventions

## Core Principles

### 1. Default Branch is `develop` (NOT `main`)

- **All PRs target**: `develop` branch
- **Feature branches from**: `develop`
- **Never push directly to**: `develop` or `main`

### 2. Branch Naming Convention

**Format**: `<type>/{task-id}-{short-description}`

**Types**:
- `feature/` - New features or enhancements
- `bugfix/` - Bug fixes
- `hotfix/` - Emergency production fixes

**Rules**:
- Use English kebab-case for descriptions
- Start with task/issue ID (e.g., `5391`)
- Keep description concise - shorten if too long
- Use hyphens to separate words

**Examples**:
```bash
# Good
feature/5391-praemie-checkout-action-card-delivery-order
bugfix/6123-fix-login-redirect-loop
hotfix/7890-critical-payment-error

# Bad
feature/praemie-checkout  # Missing task ID
feature/5391_praemie      # Using underscores
feature-5391-very-long-description-that-goes-on-forever  # Too long
```

### 3. Conventional Commits (WITHOUT Co-Author Tags)

**Format**: `<type>(<scope>): <description>`

**Types**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, missing semicolons)
- `refactor`: Code restructuring without feature changes
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `build`: Build system or dependencies
- `ci`: CI configuration
- `chore`: Maintenance tasks

**Rules**:
- ❌ **NO** "Generated with Claude Code" tags
- ❌ **NO** "Co-Authored-By: Claude" tags
- ✅ Keep first line under 72 characters
- ✅ Use imperative mood ("add" not "added")
- ✅ Body optional but recommended for complex changes

**Examples**:
```bash
# Good
feat(checkout): add bonus card selection for delivery orders

fix(crm): resolve customer search filter reset issue

refactor(oms): extract return validation logic into service

# Bad
feat(checkout): add bonus card selection

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

# Also bad
Added new feature  # Wrong tense
Fix bug            # Missing scope
```

### 4. Pull Request Creation

**Target Branch**: Always `develop`

**PR Title Format**: Same as conventional commit
```
feat(domain): concise description of changes
```

**PR Body Structure**:
```markdown
## Summary
- Brief bullet points of changes

## Related Tasks
- Closes #{task-id}
- Refs #{related-task}

## Test Plan
- [ ] Unit tests added/updated
- [ ] E2E attributes added
- [ ] Manual testing completed

## Breaking Changes
None / List breaking changes

## Screenshots (if UI changes)
[Add screenshots]
```

## Common Workflows

### Creating a Feature Branch

```bash
# 1. Update develop
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/5391-praemie-checkout-action-card

# 3. Work and commit
git add .
git commit -m "feat(checkout): add primary bonus card selection logic"

# 4. Push to remote
git push -u origin feature/5391-praemie-checkout-action-card

# 5. Create PR targeting develop (use gh CLI or web UI)
```

### Creating a Bugfix Branch

```bash
# From develop
git checkout develop
git pull origin develop
git checkout -b bugfix/6123-login-redirect-loop

# Commit
git commit -m "fix(auth): resolve infinite redirect on logout"
```

### Creating a Hotfix Branch

```bash
# From main (production)
git checkout main
git pull origin main
git checkout -b hotfix/7890-payment-processing-error

# Commit
git commit -m "fix(checkout): critical payment API timeout handling"

# Merge to both main and develop
```

## Commit Message Guidelines

### Good Commit Messages

```bash
feat(crm): add customer loyalty tier calculation

Implements three-tier loyalty system based on annual spend.
Includes migration for existing customer data.

Refs #5234

---

fix(oms): prevent duplicate return submissions

Adds debouncing to return form submission and validates
against existing returns in the last 60 seconds.

Closes #5891

---

refactor(catalogue): extract product search into dedicated service

Moves search logic from component to ProductSearchService
for better testability and reusability.

---

perf(remission): optimize remission list query with pagination

Reduces initial load time from 3s to 800ms by implementing
cursor-based pagination.

Closes #6234
```

### Bad Commit Messages

```bash
# Too vague
fix: bug fixes

# Missing scope
feat: new feature

# Wrong tense
fixed the login issue

# Including banned tags
feat(checkout): add feature

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
```

## Git Configuration Checks

### Verify Git Setup

```bash
# Check current branch
git branch --show-current

# Verify remote
git remote -v  # Should show origin pointing to ISA-Frontend

# Check for uncommitted changes
git status
```

## Common Mistakes to Avoid

```bash
# ❌ Creating PR against main
gh pr create --base main  # WRONG

# ✅ Always target develop
gh pr create --base develop  # CORRECT

# ❌ Using underscores in branch names
git checkout -b feature/5391_my_feature  # WRONG

# ✅ Use hyphens
git checkout -b feature/5391-my-feature  # CORRECT

# ❌ Adding co-author tags
git commit -m "feat: something

Co-Authored-By: Claude <noreply@anthropic.com>"  # WRONG

# ✅ Clean commit message
git commit -m "feat(scope): something"  # CORRECT

# ❌ Forgetting task ID in branch name
git checkout -b feature/new-checkout-flow  # WRONG

# ✅ Include task ID
git checkout -b feature/5391-new-checkout-flow  # CORRECT
```

## Integration with Claude Code

When Claude Code creates commits or PRs:

### Commit Creation
```bash
# Claude uses conventional commits WITHOUT attribution
git commit -m "feat(checkout): implement bonus card selection

Adds logic for selecting primary bonus card during checkout
for delivery orders. Includes validation and error handling.

Refs #5391"
```

### PR Creation
```bash
# Target develop by default
gh pr create --base develop \
  --title "feat(checkout): implement bonus card selection" \
  --body "## Summary
- Add primary bonus card selection logic
- Implement validation for delivery orders
- Add error handling for API failures

## Related Tasks
- Closes #5391

## Test Plan
- [x] Unit tests added
- [x] E2E attributes added
- [x] Manual testing completed"
```

## Branch Cleanup

### After PR Merge
```bash
# Update develop
git checkout develop
git pull origin develop

# Delete local feature branch
git branch -d feature/5391-praemie-checkout

# Delete remote branch (usually done by PR merge)
git push origin --delete feature/5391-praemie-checkout
```

## Quick Reference

```bash
# Branch naming
feature/{task-id}-{description}
bugfix/{task-id}-{description}
hotfix/{task-id}-{description}

# Commit format
<type>(<scope>): <description>

# Common types
feat, fix, docs, style, refactor, perf, test, build, ci, chore

# PR target
Always: develop (NOT main)

# Banned in commits
- "Generated with Claude Code"
- "Co-Authored-By: Claude"
- Any AI attribution
```

## Resources

- [Conventional Commits](https://www.conventionalcommits.org/)
- Project PR template: `.github/pull_request_template.md`
- Code review standards: `.github/review-instructions.md`
