v1.0.0 to git:20260317.e64d556

---

name: git-github

description: "Git workflow and GitHub collaboration patterns including conventional commits, branch naming, PR workflow, and gh CLI usage. Use when creating commits, branches, or pull requests. TRIGGER when: git commit, branch, PR, pull request, merge, gh cli. DO NOT TRIGGER when: code implementation, testing, documentation without git operations."

allowed-tools: [Read, Bash]

---

# Git and GitHub Workflow Skill

Comprehensive guide for Git version control and GitHub collaboration patterns.

## When This Activates

- Creating commits or branches

- Opening or reviewing pull requests

- Managing GitHub issues

- Using the gh CLI

- Keywords: "git", "github", "commit", "branch", "pr", "pull request", "merge", "issue"

---

## Conventional Commits

All commit messages follow the conventional commits specification:

```

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

[optional body]

[optional footer(s)]

```

### Types

| Type | When to Use |

|------|-------------|

| `feat` | New feature or capability |

| `fix` | Bug fix |

| `docs` | Documentation only changes |

| `style` | Formatting, missing semicolons, etc. |

| `refactor` | Code change that neither fixes a bug nor adds a feature |

| `perf` | Performance improvement |

| `test` | Adding or correcting tests |

| `chore` | Build process, auxiliary tools, or maintenance |

| `ci` | CI/CD configuration changes |

### Examples

```bash

feat(auth): add JWT token refresh endpoint

fix(api): handle null response from upstream service

docs: update API reference for v2 endpoints

refactor(db): extract query builder into separate module

test(auth): add integration tests for OAuth flow

chore: upgrade dependencies to latest versions

```

### Breaking Changes

Use `!` after type or add `BREAKING CHANGE:` footer:

```bash

feat(api)!: change response format from XML to JSON

```

---

## Branch Naming Conventions

```

<type>/<issue-number>-<short-description>

```

### Patterns

| Pattern | Example |

|---------|---------|

| Feature | `feat/123-add-user-auth` |

| Bug fix | `fix/456-null-pointer-crash` |

| Docs | `docs/789-update-api-reference` |

| Refactor | `refactor/101-extract-helpers` |

### Rules

- Use lowercase with hyphens (no underscores or spaces)

- Include issue number when applicable

- Keep descriptions under 5 words

- Delete branches after merging

---

## PR Workflow with gh CLI

### Creating Pull Requests

```bash

# Create PR with title and body

gh pr create --title "feat: add user authentication" --body "$(cat <<'EOF'

## Summary

- Add JWT-based authentication

- Implement login/logout endpoints

## Test plan

- [ ] Unit tests for token generation

- [ ] Integration tests for auth flow

EOF

)"

# Create draft PR

gh pr create --draft --title "wip: refactor database layer"

# Create PR targeting specific base branch

gh pr create --base develop --title "feat: new feature"

```

### Reviewing Pull Requests

```bash

# List open PRs

gh pr list

# View PR details

gh pr view 123

# Check out PR locally

gh pr checkout 123

# Approve PR

gh pr review 123 --approve

# Request changes

gh pr review 123 --request-changes --body "Please fix the error handling"

# Merge PR

gh pr merge 123 --squash --delete-branch

```

### PR Best Practices

1. **Keep PRs small** - Under 400 lines changed when possible

2. **One concern per PR** - Don't mix features with refactors

3. **Write descriptive titles** - Use conventional commit format

4. **Include test plan** - Checklist of what to verify

5. **Link issues** - Use "Closes #123" in body

---

## Issue Management

### Creating Issues

```bash

# Create issue with title and body

gh issue create --title "Bug: login fails on Safari" --body "Steps to reproduce..."

# Create with labels

gh issue create --title "feat: dark mode" --label "enhancement,ui"

# Create with assignee

gh issue create --title "fix: memory leak" --assignee "@me"

```

### Issue Templates

Use labels to categorize:

| Label | Color | Purpose |

|-------|-------|---------|

| `bug` | red | Something broken |

| `enhancement` | blue | New feature request |

| `documentation` | green | Docs improvement |

| `good first issue` | purple | Beginner friendly |

| `priority: high` | orange | Needs immediate attention |

### Linking Issues to PRs

```bash

# In PR body

Closes #123

Fixes #456

Resolves #789

```

---

## Git Hooks Best Practices

### Pre-commit

```bash

# Format code

black --check src/

isort --check src/

# Lint

flake8 src/

# Check for secrets

detect-secrets scan

```

### Pre-push

```bash

# Run tests

pytest tests/ -x --timeout=60

# Type check

mypy src/

```

### Commit-msg

```bash

# Validate conventional commit format

pattern="^(feat|fix|docs|style|refactor|perf|test|chore|ci)(\(.+\))?!?: .{1,72}"

if ! echo "$1" | grep -qE "$pattern"; then

echo "Invalid commit message format"

exit 1

fi

```

---

## Common Git Operations

### Stashing Changes

```bash

git stash push -m "wip: authentication changes"

git stash list

git stash pop

```

### Interactive Rebase (cleanup before PR)

```bash

git rebase -i HEAD~3 # Squash last 3 commits

```

### Cherry-picking

```bash

git cherry-pick abc1234 # Apply specific commit

```

### Resolving Conflicts

```bash

git merge main # Trigger merge

# Fix conflicts in editor

git add .

git commit # Complete merge

```

---

## Key Takeaways

1. **Conventional commits** - Always use type(scope): description format

2. **Branch naming** - type/issue-description pattern

3. **Small PRs** - Under 400 lines, one concern each

4. **gh CLI** - Use for all GitHub operations

5. **Link issues** - Always connect PRs to issues

6. **Git hooks** - Automate quality checks

7. **Delete merged branches** - Keep repository clean

---

## Hard Rules

**FORBIDDEN**:

- Force-pushing to main/master without explicit approval

- Committing secrets, API keys, or credentials (use `.env` files)

- Merge commits with failing CI checks

- PRs without linked issues or description

**REQUIRED**:

- All PRs MUST have a description explaining the "why"

- Branch names MUST follow `type/issue-description` pattern

- Commits MUST use conventional commit format (`feat:`, `fix:`, `docs:`, etc.)

- All PRs MUST pass CI before merge