| name | github-workflow-best-practices |
| description | Master GitHub workflows including branching strategies, commit standards, PR processes, issue triage, sprint management, and git worktree usage. Activate when planning GitHub workflows, managing sprints, or establishing team conventions. |
| triggers | ["github workflow","PR best practices","github branching","sprint management","commit message","git worktree","github standards","issue triage","conventional commits"] |
GitHub Workflow Best Practices
Master professional GitHub workflows that scale from solo projects to large teams. This skill covers branching strategies, commit conventions, PR processes, issue management, sprint execution, and advanced git worktree patterns.
Branching Strategy
Branch Naming Conventions
Follow a consistent naming pattern that communicates intent:
<type>/<issue-number>-<brief-description>
Examples:
feature/123-user-authentication
bugfix/456-login-redirect
hotfix/789-security-patch
chore/update-dependencies
docs/api-documentation
Branch Types:
feature/ - New functionalitybugfix/ - Bug fixeshotfix/ - Urgent production fixeschore/ - Maintenance tasks (dependencies, config)docs/ - Documentation updatesrefactor/ - Code refactoring without behavior changetest/ - Test additions or updates
Branch Lifecycle
Main Branches:
main (or master) - Production-ready codedevelop - Integration branch for features (optional)
Feature Branch Flow:
1. Create branch from main
2. Develop and commit
3. Push to remote
4. Create PR
5. Code review
6. Merge to main
7. Delete branch
8. Clean up local/remote
Protection Rules:
- Require PR reviews before merge
- Require status checks to pass
- Require branches to be up to date
- Restrict force pushes
- Restrict deletions
See Branching Strategy Details for advanced patterns.
Commit Message Standards
Conventional Commits Format
Use the conventional commits specification for clarity and automation:
<type>(<scope>): <subject>
<body>
<footer>
Example:
feat(auth): add OAuth2 integration
Implement OAuth2 authentication flow with Google and GitHub providers.
Includes token refresh logic and session management.
Closes #123
Commit Types
| Type | Description | Example |
|---|
feat | New feature | feat(api): add user search endpoint |
fix | Bug fix | fix(login): resolve redirect loop |
docs | Documentation | docs(readme): update setup instructions |
style | Formatting, no code change | style(header): fix indentation |
refactor | Code restructure | refactor(auth): extract validation logic |
perf | Performance improvement | perf(query): optimize database indexes |
test | Test additions/updates | test(user): add integration tests |
chore | Maintenance | chore(deps): update dependencies |
ci | CI/CD changes | ci(github): add test workflow |
build | Build system changes | build(webpack): update config |
Commit Best Practices
Good Commits:
- ✅ Atomic (one logical change)
- ✅ Clear subject (< 50 chars)
- ✅ Imperative mood ("add feature" not "added feature")
- ✅ Detailed body when needed
- ✅ Reference issues/PRs
Bad Commits:
- ❌ "fix stuff"
- ❌ "WIP"
- ❌ Multiple unrelated changes
- ❌ Missing context
See Commit Message Examples for good patterns.
Pull Request Workflow
PR Creation
Before Creating PR:
- Ensure branch is up to date with main
- Run tests locally
- Run linter/formatter
- Review your own changes
- Write descriptive title and description
PR Title Format:
<type>(<scope>): <brief description>
Examples:
feat(auth): implement 2FA authentication
fix(api): resolve rate limiting issue
docs(contributing): add PR guidelines
PR Description Template:
## Summary
Brief description of what this PR does.
## Changes
- Change 1
- Change 2
- Change 3
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Screenshots (if applicable)
[Include screenshots for UI changes]
## Related Issues
Closes #123
Relates to #456
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
PR Review Process
As Author:
- Respond to all comments
- Make requested changes
- Re-request review after updates
- Resolve conversations when addressed
- Keep PR updated with main
As Reviewer:
- Review within 24 hours
- Check code quality, security, performance
- Ask questions for clarity
- Suggest improvements
- Approve when ready or request changes
Review Levels:
- 💬 Comment: Suggestion, not blocking
- 🔄 Request Changes: Must be addressed
- ✅ Approve: Ready to merge
See PR Workflow Details for comprehensive process.
Issue Triage Workflow
Issue Labels
Status Labels:
status: new - Needs triagestatus: accepted - Confirmed and prioritizedstatus: in-progress - Being worked onstatus: blocked - Cannot proceedstatus: on-hold - Deferred
Type Labels:
type: bug - Something brokentype: feature - New functionalitytype: enhancement - Improvement to existing featuretype: documentation - Docs updatetype: question - Support request
Priority Labels:
priority: critical - Production down, security issuepriority: high - Major functionality brokenpriority: medium - Normal prioritypriority: low - Nice to have
Size Labels:
size: XS - < 1 hoursize: S - 1-4 hourssize: M - 1 daysize: L - 2-3 dayssize: XL - 1+ week
Triage Process
Daily Triage (5-10 minutes):
- Review new issues
- Validate bug reports
- Add labels (type, priority, size)
- Assign to milestone/sprint
- Close duplicates
- Convert questions to discussions
Weekly Review (30 minutes):
- Review blocked/on-hold issues
- Update stale issues
- Close resolved issues
- Reprioritize backlog
Sprint Planning & Execution
Sprint Planning
Pre-Sprint Preparation:
- Groom backlog
- Estimate issues (size labels)
- Identify dependencies
- Check team capacity
Sprint Planning Meeting:
- Review sprint goal
- Select high-priority issues
- Break down large issues
- Assign issues to team members
- Confirm commitment
Sprint Artifacts:
- Sprint board (GitHub Projects)
- Sprint milestone
- Sprint goal documentation
Sprint Execution
Daily Standup Questions:
- What did I complete yesterday?
- What will I work on today?
- Any blockers?
Sprint Board Columns:
To Do → In Progress → In Review → Done
Mid-Sprint Adjustments:
- Add urgent issues (swap out equal size)
- Remove blocked issues
- Rebalance workload
End-of-Sprint Activities:
- Demo completed work
- Retrospective (what went well, what to improve)
- Close sprint milestone
- Archive sprint board
- Plan next sprint
Sprint Automation with GitHub CLI
Fetch Sprint Issues:
gh issue list --milestone "Sprint 23" --json number,title,labels
Bulk Update:
gh issue edit 123 --add-label "status: in-progress"
Create Sprint Report:
gh issue list --milestone "Sprint 23" --state closed --json number,title,closedAt
Git Worktree Patterns
When to Use Worktrees
Use Worktrees For:
- Working on multiple branches simultaneously
- Code review while preserving current work
- Parallel bug fix while developing feature
- Running different branches side-by-side
Advantages:
- No stashing required
- No branch switching
- Multiple dev servers running
- Compare branches easily
Worktree Commands
Create Worktree:
git worktree add ../project-feature-123 feature/123-user-auth
git worktree add -b feature/456-new-feature ../project-feature-456
List Worktrees:
git worktree list
Remove Worktree:
rm -rf ../project-feature-123
git worktree prune
Worktree Organization
Directory Structure:
~/projects/
myapp/ # Main worktree
myapp-feature-123/ # Feature branch worktree
myapp-bugfix-456/ # Bugfix branch worktree
myapp-review-789/ # Review worktree
Naming Convention:
<project>-<branch-type>-<issue-number>
Examples:
myapp-feature-123
myapp-bugfix-456
myapp-hotfix-789
Worktree Workflows
Parallel Development:
cd ~/projects/myapp-feature-123
npm run dev
cd ~/projects/myapp-review-456
git pull origin feature/456-other-feature
npm run dev -- --port 3001
Quick Bug Fix During Feature Work:
git worktree add ../myapp-hotfix-789 -b hotfix/789-critical-bug
cd ../myapp-hotfix-789
Agency Plugin Integration
Create Worktree for Issue:
/gh-worktree-issue 123
This command:
- Creates worktree directory
- Creates/checks out branch
- Sets up tracking
- Opens in new window (optional)
GitHub CLI Integration
Essential gh Commands
Issues:
gh issue list --assignee @me --state open
gh issue view 123
gh issue create --title "Bug: Login fails" --body "Description"
gh issue edit 123 --add-label "priority: high"
Pull Requests:
gh pr create --title "feat: add feature" --body "Description"
gh pr list --author @me
gh pr view 456
gh pr review 456 --approve
gh pr merge 456 --squash
Workflows:
gh workflow list
gh run list --workflow=test.yml
gh run view 123456
Automation Scripts
Daily Issue Check:
#!/bin/bash
echo "🎯 Your assigned issues:"
gh issue list --assignee @me --state open
echo "\n📝 PRs awaiting your review:"
gh pr list --search "review-requested:@me"
Sprint Progress:
#!/bin/bash
MILESTONE="Sprint 23"
TOTAL=$(gh issue list --milestone "$MILESTONE" --json number | jq length)
DONE=$(gh issue list --milestone "$MILESTONE" --state closed --json number | jq length)
echo "Sprint Progress: $DONE / $TOTAL completed"
Best Practices Summary
Branching:
- Use descriptive branch names with issue numbers
- Keep branches short-lived (< 1 week)
- Delete merged branches
- Protect main branch
Commits:
- Follow conventional commits format
- Write clear, atomic commits
- Reference issues in commit messages
- Use imperative mood
Pull Requests:
- Keep PRs small and focused
- Write descriptive titles and descriptions
- Respond to reviews promptly
- Keep PRs up to date with main
Issues:
- Triage daily
- Use consistent labels
- Keep issues updated
- Close resolved issues
Sprints:
- Plan thoroughly
- Track progress daily
- Adjust as needed
- Retrospect and improve
Worktrees:
- Use for parallel work
- Organize with naming convention
- Clean up after merging
- Leverage for reviews
Quick Reference
Branch: <type>/<number>-<description>
Commit: <type>(<scope>): <subject>
PR Title: Same as commit format
Issue Labels: type:, priority:, status:, size:
Worktree: git worktree add <path> <branch>
Related Skills
agency-workflow-patterns - Orchestrator and multi-agent workflowscode-review-standards - What to look for in reviewstesting-strategy - Test requirements and standards
Remember: Consistency in workflows reduces cognitive load and enables automation. Choose conventions that work for your team and stick to them.
