GitHub Workflow

Quick Start

1. User requests a git action (commit, PR, branch, push, issue)
2. Check repo state: git status, git branch, git log --oneline -5
3. Execute the appropriate workflow below
4. Confirm result to user

Workflows

1. Branching

# Create feature branch from main
git checkout main && git pull origin main
git checkout -b <type>/<name>
# Types: feature/, bugfix/, docs/, refactor/, test/, chore/

• Always branch from up-to-date main
• Use conventional naming: feature/add-jwt-testing, bugfix/fix-port-detection

2. Committing

# Stage specific files (never git add -A blindly)
git add <file1> <file2>
# Commit with conventional format
git commit -m "type(scope): description"

• Types: feat, fix, docs, refactor, test, chore
• Message focuses on why, not what
• Never commit .env, credentials, or secrets
• See reference/commit-conventions.md [blocked]

3. Pushing

# First push (set upstream)
git push -u origin <branch-name>
# Subsequent pushes
git push

• Never force-push to main/master without explicit user approval
• If push is rejected, git pull --rebase first

4. Pull Requests

# Create PR linking to issue
gh pr create --title "Short title < 70 chars" --body "$(cat <<'EOF'
## Summary
- What changed and why

## Test plan
- [ ] How to verify

Fixes #<issue-number>
EOF
)"

• Title < 70 chars, details in body
• Always link to issue: Fixes #N or Closes #N
• See reference/pr-workflow.md [blocked]

5. Issues

gh issue create --title "type: description" --body "$(cat <<'EOF'
## Problem
What needs to change

## Proposed solution
How to fix it

## Acceptance criteria
- [ ] Criteria 1
EOF
)"

6. Code Review

# Review a PR
gh pr view <number>
gh pr diff <number>
gh pr checks <number>
# Comment or approve
gh pr review <number> --approve
gh pr review <number> --comment --body "feedback"

Reference

• commit-conventions.md [blocked] — Commit message format and examples
• pr-workflow.md [blocked] — PR creation, review, and merge workflow
• branch-strategy.md [blocked] — Branching model and naming conventions

Critical Rules

• NEVER force-push to main/master without explicit user approval
• NEVER commit secrets, .env files, or credentials
• NEVER use git add -A without reviewing what's staged
• NEVER skip pre-commit hooks (--no-verify) unless user explicitly asks
• NEVER amend published commits — create new commits instead
• ALWAYS use conventional commit format: type(scope): description
• ALWAYS link PRs to issues
• ALWAYS check git status before committing
• ALWAYS pull before pushing to avoid conflicts
• ALWAYS create branches from up-to-date main