Workflow

Git Workflow

Main is always deployable. No exceptions.

Branching Strategy (GitHub Flow)

main (protected - always deployable)
  ├── feature/user-auth
  ├── feature/search-api
  ├── fix/login-timeout
  └── chore/upgrade-deps

Branch Naming

| Prefix | Use | |--------|-----| | feature/ | New functionality | | fix/ | Bug fixes | | refactor/ | Code restructuring with no behavior change | | chore/ | Build config, dependencies, CI, docs |

Rules:

• Lowercase, hyphens only. No spaces, no underscores.
• Short and descriptive: feature/user-search, not feature/implement-the-user-search-functionality-with-filters.
• One concern per branch. Don't mix a feature with a refactor.

Creating a Branch

git checkout main
git pull origin main
git checkout -b feature/your-feature

Commit Conventions

Format: type: short description

feat: add user search endpoint
fix: correct pagination off-by-one
refactor: extract auth middleware into separate module
chore: upgrade dependencies to latest
test: add unit tests for rate limiting

Types: feat, fix, refactor, chore, test, docs

Rules:

• Present tense, imperative mood ("add" not "added" or "adds").
• First line under 72 characters.
• Commit often. Small, atomic commits that each do one thing.
• Never commit: .env, credentials, API keys, large binaries.

Pull Request Process

1. Before Opening PR

• [ ] All commits follow conventions
• [ ] Code builds without errors
• [ ] All tests pass
• [ ] No new warnings introduced
• [ ] Self-review: read your own diff

2. Open PR

gh pr create --title "feat: add user search" --body "$(cat <<'EOF'
## Summary
- Brief description of what changed and why

## Test plan
- [ ] Unit tests pass
- [ ] Manual verification of key flows
EOF
)"

3. CI Must Pass

Automated checks run on every PR. All must pass before merge.

4. Code Review

Run /review on the PR changes. Address all CRITICAL and WARNING items.

5. Merge to Main

gh pr merge --squash

Squash merge keeps main history clean. The PR title becomes the merge commit message.

6. Clean Up

git checkout main
git pull origin main
git branch -d feature/your-feature

What Goes Directly to Main (Never)

Nothing. Even a one-line fix gets a branch and PR. The CI gate and review step catch things humans miss.

Hotfix Process

Same as above but with urgency:

git checkout main && git pull
git checkout -b fix/critical-issue
# fix, commit, push, PR, CI passes, merge

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pvnarp
• Source: pvnarp/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.