Tzurot v3 Git Workflow

Use this skill when: Creating commits, pushing changes, creating PRs, or performing any git operations.

Quick Reference

# Start feature
git checkout develop && git pull origin develop
git checkout -b feat/your-feature

# Test before commit
pnpm test

# Create PR to develop
gh pr create --base develop --title "feat: description"

🚨 Critical Rules

Rebase-Only Workflow

NO SQUASH. NO MERGE. ONLY REBASE.

GitHub settings enforce this - rebase and merge is the only option enabled.

Always Target develop for PRs

# ✅ CORRECT
gh pr create --base develop --title "feat: your feature"

# ❌ WRONG - Never create feature PRs to main!
gh pr create --base main --title "feat: your feature"

Test Before Push

pnpm test && git push origin <branch>

Standard Workflow

1. Create Feature Branch

git checkout develop
git pull origin develop
git checkout -b feat/your-feature-name

Branch prefixes: feat/, fix/, docs/, refactor/, chore/, test/

2. Commit Changes

git commit -m "$(cat <<'EOF'
feat(ai-worker): add pgvector memory retrieval

Brief description of what and why.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
EOF
)"

Types: feat, fix, docs, refactor, test, chore, style, perf Scopes: ai-worker, api-gateway, bot-client, common-types, ci, deps

3. Push and Create PR

git push -u origin feat/your-feature
gh pr create --base develop --title "feat: description"

4. After PR Merged

git checkout develop
git pull origin develop
git branch -d feat/your-feature

Git Safety Protocol

🚨 NEVER Run Without Permission:

Golden Rules

1. Uncommitted changes = HOURS OF WORK - Never discard without confirmation
2. Use safe alternatives: --force-with-lease, git branch -d (not -D)
3. When user says "get changes" → They mean COMMIT, not DISCARD

Git Hooks

Source-controlled in ./hooks/ (not .git/hooks/)

Install: ./scripts/git/install-hooks.sh

Never skip: Don't use --no-verify

Handling Rebase Conflicts

git checkout develop && git pull origin develop
git checkout feat/your-feature
git rebase develop

# If conflicts:
# 1. Resolve files
# 2. git add <resolved>
# 3. git rebase --continue
# Repeat until done

git push --force-with-lease origin feat/your-feature

Release Workflow

Version Bump (ALL package.json files!)

# Use the bump-version script - handles all 9 package.json files
pnpm bump-version 3.0.0-beta.31

# Review changes
git diff

# Commit
git commit -am "chore: bump version to 3.0.0-beta.31"
git push origin develop

Script location: scripts/utils/bump-version.sh

Create Release PR

gh pr create --base main --head develop \
  --title "Release v3.0.0-beta.31: Description"

Anti-Patterns

Related Skills

• tzurot-code-quality - When lint fails, refactoring patterns
• tzurot-docs - Session handoff and CURRENT_WORK.md
• tzurot-testing - Run tests before committing
• tzurot-security - Pre-commit security checks

GitHub CLI Quirks

⚠️ ALWAYS check docs/reference/GITHUB_CLI_REFERENCE.md before running gh commands!

Known Broken Commands

# ❌ BROKEN - "Projects (classic) deprecation" error
gh pr edit 123 --body "new body"
gh pr edit 123 --title "new title"

# ✅ WORKAROUND - Use REST API directly
gh api -X PATCH repos/{owner}/{repo}/pulls/123 -f body="new body"
gh api -X PATCH repos/{owner}/{repo}/pulls/123 -f title="new title"

# ✅ Multiline body with HEREDOC
gh api -X PATCH repos/{owner}/{repo}/pulls/123 -f body="$(cat <<'EOF'
## Summary
- Changes here

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Comment Types

PRs have THREE different comment types with different endpoints:

• Issue comments (general): gh pr view --json comments or /issues/{pr}/comments
• Review comments (line-specific): /pulls/{pr}/comments
• Reviews (APPROVE, etc.): gh pr view --json reviews

References

• GitHub CLI Reference: docs/reference/GITHUB_CLI_REFERENCE.md ← CHECK THIS FIRST!
• Full workflow: CLAUDE.md#git-workflow
• Post-mortems: docs/postmortems/PROJECT_POSTMORTEMS.md