Git Workflow Conventions
Purpose
This skill ensures consistent git practices across the codebase. It defines strict conventions for branch names, commit messages, and PR workflows that Claude should follow automatically when performing any git operations.
When to Use
- •Creating new branches for any work
- •Writing commit messages
- •Creating pull requests
- •Reviewing git history or suggesting git commands
Quick Reference
Branching Strategy (Solo Workflow)
code
feature/xxx ─┬─► staging ─────► main (production)
fix/xxx ─┤ (direct) (PR) │
chore/xxx ─┘ ▼
Railway auto-deploy
| Branch | Purpose | How to Integrate |
|---|---|---|
main | Production (auto-deploys) | PR from staging only |
staging | Integration/testing | Direct merge from features |
| Feature branches | Development | Squash merge to staging |
Solo workflow: Feature → staging is direct (no PR). Staging → main uses PR for deploy checkpoint.
⚠️ Never merge feature branches directly to main
Branch Format
code
<type>/<description>
| Type | Use For | Example |
|---|---|---|
feature | New functionality | feature/shopping-sync |
fix | Bug fixes | fix/auth-token-refresh |
chore | Maintenance, deps | chore/update-deps |
refactor | Code restructuring | refactor/api-client |
docs | Documentation | docs/api-reference |
test | Test changes | test/shopping-integration |
Description rules:
- •kebab-case only
- •2-4 words
- •No special characters except hyphens
Commit Format (Conventional Commits)
code
<type>: <description>
or with scope:
code
<type>(<scope>): <description>
| Type | Meaning | Example |
|---|---|---|
feat | New feature | feat: add shopping sync |
fix | Bug fix | fix: resolve auth token refresh |
chore | Maintenance | chore: update dependencies |
refactor | Restructure | refactor: simplify api client |
docs | Documentation | docs: add api docs |
test | Tests | test: add sync tests |
style | Formatting | style: fix indentation |
perf | Performance | perf: optimize query |
Commit rules:
- •Type is lowercase
- •Description starts lowercase
- •No period at end
- •Imperative mood ("add" not "added")
- •Under 72 characters
- •Always include co-author line
Co-Author Line
All commits must end with:
code
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
PR Title Format
Derive from branch name or summarize commits:
- •
feature/shopping-sync→ "Add shopping sync feature" - •
fix/auth-bug→ "Fix auth bug"
PR Body Template
markdown
## Summary - [Key changes in user terms] ## Changes - [Modified files/areas] ## Test Plan - [ ] [Testing steps] --- 🤖 Generated with Claude Code
Critical Rules
| Rule | ❌ Wrong | ✅ Correct |
|---|---|---|
| Branch type | bugfix/auth | fix/auth-bug |
| Branch case | feature/ShoppingSync | feature/shopping-sync |
| Commit type | FEAT: add feature | feat: add feature |
| Commit mood | added feature | add feature |
| Commit ending | feat: add feature. | feat: add feature |
| Commit separator | feat - add feature | feat: add feature |
Workflow
Starting Work
- •Ensure clean working tree or stash changes
- •Fetch latest from origin
- •Create branch from staging:
/git start <type> <description>
Committing
- •Stage relevant files (prefer specific files over
git add -A) - •Write conventional commit message
- •Include co-author line
- •Use
/git committo validate and commit
Merging to Staging (Solo Workflow)
- •Ensure all changes committed
- •Sync with staging if behind:
/git sync - •Merge directly to staging:
/git merge - •Branch is squash-merged and deleted
Deploying to Production
- •Test changes on staging
- •Create deploy PR:
/git deploy - •Review and merge PR in GitHub
- •Railway auto-deploys from main
Related
- •/git command - Dispatcher (routes to workflow files)
- •workflows/start.md - Create branch from staging
- •workflows/commit.md - Stage, validate, and commit
- •workflows/sync.md - Rebase on latest staging
- •workflows/merge.md - Squash merge to staging
- •workflows/deploy.md - PR from staging to main
- •workflows/pr.md - Push and create PR
- •workflows/status.md - Show status and suggest action