# Git Workflow

> 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. Use when this capability is needed.

- Skill: `tomevault-io/git-workflow-186` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-186`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-186/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/git-workflow-186

---


# 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

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

### 2. Lint Check

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

### 3. Type Check

```bash
pnpm type-check
# Or: pnpm check
```

### 4. Tests

```bash
# 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`

## Checking PR CI Status

Use the check-prs script to monitor CI status across PRs:

```bash
# Check specific PRs
./scripts/check-prs.sh 940 941 942

# Check all your open PRs
./scripts/check-prs.sh
```

### Polling a Specific Check

To wait for a specific check to complete:

```bash
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: `lint`, `test-e2e`, `test-jest`, `sonarcloud`, `Vercel`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/oaknational) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->