git-workflow

oaknational's avatarfrom oaknational

Oak's git conventions including branch naming (feat/fix/chore prefixes), commit messages (conventional commits format), PR creation with templates, code review process, and CI check monitoring. Use when working with git, creating branches, committing code, or managing pull requests.

⭐29stars🔀3forks📁View on GitHub🕐Updated Dec 18, 2025
[Developer Tools]

When & Why to Use This Skill

This Claude skill streamlines the software development lifecycle by enforcing Oak's Git conventions. It automates branch naming, commit message formatting according to Conventional Commits, and pull request creation. By integrating quality gates—such as linting, type-checking, and automated testing—alongside real-time CI/CD status monitoring, it ensures high code standards and efficient team collaboration.

Use Cases

  • Automated Branch Management: Generate standardized branch names (feat/, fix/, chore/) based on project requirements or ticket IDs to maintain a clean and searchable repository structure.
  • Standardized Commit Messages: Enforce the Conventional Commits format (type: description) to facilitate automated changelog generation and improve the readability of project history.
  • Quality Gate Enforcement: Automatically execute and verify essential checks like Prettier formatting, ESLint linting, and Jest unit tests locally before committing code to prevent build failures.
  • Efficient Pull Request Workflows: Create PRs using GitHub templates, manage reviewers via CLI, and utilize automated polling scripts to monitor the status of CI checks like SonarCloud, Vercel deployments, and E2E tests.
namegit-workflow
descriptionOak's git conventions including branch naming (feat/fix/chore prefixes), commit messages (conventional commits format), PR creation with templates, code review process, and CI check monitoring. Use when working with git, creating branches, committing code, or managing pull requests.

Git Workflow

Branch Naming

  • Feature branches: feat/AI-XXXX-description or feat/description (prefer ticket ID when available)
  • Bug fixes: fix/description
  • Chores: chore/description (for project/config changes)
  • Development: dev/description
  • Testing: test/description
  • Spikes: spike/description
  • Refactoring: refactor/description

Commit Messages

  • Format: type: description (conventional commits)
  • Types: feat:, fix:, docs:, style:, refactor:, perf:, test:, build:, ci:, chore:, revert:
  • Examples:
    • feat: add new lesson planner feature
    • fix: resolve authentication bug
    • docs: update API documentation

Quality Gates - How to Know Work is Correct

Before committing or creating a PR, verify all quality checks pass:

1. Format Check

pnpm prettier --write <changed-files>
# Or check all: pnpm prettier --check .

2. Lint Check

pnpm lint
# Or with auto-fix: pnpm lint:fix

3. Type Check

pnpm type-check
# Or: pnpm check

4. Tests

# Run all tests
pnpm test

# Run specific test
pnpm test -- -t "test name pattern"

# Run E2E tests (if relevant)
pnpm test-e2e

Pre-commit Notes

  • For small fixes to the last commit, consider using amend
  • Never skip hooks (--no-verify, --no-gpg-sign) unless explicitly requested

Pull Requests

  • Template: Follow the PR template in .github/pull_request_template.md
  • Formatting: All code must pass pnpm prettier --check . before submitting
  • Reviewers: Ask before adding reviewers (team vs individual depends on context)
    • Team reviews: gh pr edit <PR-number> --add-reviewer oaknational/ai-devs
    • Individual reviews: gh pr edit <PR-number> --add-reviewer username

Polling GitHub PR Checks

When waiting for GitHub checks to complete, use this inline pattern:

# Example: Poll a specific check with timeout
# Usage: Set PR, CHECK_NAME, TIMEOUT (seconds), and INTERVAL (seconds)
PR=733; CHECK_NAME="lint"; TIMEOUT=120; INTERVAL=10; \
end=$(($(date +%s) + TIMEOUT)); \
echo "Polling PR #$PR for '$CHECK_NAME' (timeout: ${TIMEOUT}s)..."; \
while [ $(date +%s) -lt $end ]; do \
  check_status=$(gh pr checks "$PR" | grep "^$CHECK_NAME" | awk '{print $2}'); \
  echo "$(date '+%H:%M:%S') - $CHECK_NAME: ${check_status:-not found}"; \
  [ "$check_status" != "pending" ] && echo "✓ Completed: $check_status" && break; \
  sleep $INTERVAL; \
done || echo "⏱️ Timeout reached"

Common checks to poll:

  • lint - Code style and TypeScript checks
  • test-e2e - End-to-end tests
  • test-jest - Unit tests
  • sonarcloud - Code quality analysis
  • Vercel - Deployment status