tzurot-git-workflow

lbds137's avatarfrom lbds137

Git workflow for Tzurot v3 - Rebase-only strategy, PR creation against develop, commit message format, and safety checks. Use when creating commits, PRs, or performing git operations.

⭐7stars🔀1forks📁View on GitHub🕐Updated Jan 2, 2026

When & Why to Use This Skill

The tzurot-git-workflow skill is a specialized Git management tool designed to automate and enforce a professional development lifecycle. It prioritizes a clean, linear project history through a strict rebase-only strategy and streamlines the transition from local development to production. By integrating conventional commit validation, automated Pull Request creation via GitHub CLI, and rigorous safety protocols, it ensures that every code contribution follows best practices while preventing accidental data loss or incorrect branch targeting.

Use Cases

  • Standardizing team-wide commit messages and branch naming conventions (e.g., feat/, fix/) to maintain repository organization.
  • Automating the creation of Pull Requests targeting the 'develop' branch with pre-configured titles and safety checks.
  • Executing safe rebase operations and conflict resolutions to maintain a linear history without merge commits.
  • Managing the release lifecycle using Changesets or automated version bumping scripts to ensure consistent package updates.
  • Preventing accidental data loss by enforcing confirmation prompts for destructive Git commands like 'git reset --hard' or 'git clean'.
nametzurot-git-workflow
descriptionGit workflow for Tzurot v3 - Rebase-only strategy, PR creation against develop, commit message format, and safety checks. Use when creating commits, PRs, or performing git operations.
lastUpdated'2026-01-17'

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

Never Merge Without User Approval

NEVER merge a PR without explicit user approval. This is non-negotiable.

  • ✅ CI passing is necessary but NOT sufficient for merging
  • ✅ User must explicitly approve/request the merge
  • ❌ NEVER merge just because "CI is green"
  • ❌ NEVER merge to "complete the task"
# Only merge with explicit user approval
gh pr merge <number> --rebase --delete-branch

Rebase-Only Workflow

NO SQUASH. NO MERGE COMMITS. ONLY REBASE.

GitHub settings enforce this - rebase and merge is the only option enabled. Merge commits and squash merges are disabled at the repository level.

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 <noreply@anthropic.com>
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:

Command Risk
git restore Discards uncommitted work
git reset --hard Undoes commits permanently
git clean -fd Deletes untracked files
git push --force Rewrites history

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 (Husky)

Managed by Husky - auto-installed on pnpm install.

Hook Tools What Speed
pre-commit lint-staged, secretlint Format staged files + secrets ~3s
commit-msg commitlint Validate conventional commits instant
pre-push Turborepo Cached build/lint/test varies

Configuration:

  • .husky/ - Hook scripts
  • .lintstagedrc.json - Staged file linting
  • commitlint.config.cjs - Commit message rules

Skip for docs-only changes: Pre-push auto-skips tests when only .md, .json, etc. files changed.

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

# During development: add changeset describing your changes
pnpm changeset

# Before release: check pending changesets
pnpm changeset:status

# Apply changesets and bump versions
pnpm changeset:version

# Review and commit
git add . && git commit -m "chore: version packages"
git push origin develop

Option 2: Manual Version Bump

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

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

Create Release PR

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

Anti-Patterns

❌ Don't ✅ Do
PRs to main (except releases) PRs to develop
Push without testing pnpm test && git push
Vague commits ("fix stuff") Descriptive commits
Skip hooks (--no-verify) Fix the issues
Force push to main/develop Only force-push feature branches
  • 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 Commands

🚨 Use ops gh:* Commands (Not gh pr edit)

The gh pr edit command is BROKEN due to GitHub's "Projects (classic) deprecation" GraphQL error. ALWAYS use the ops gh:* commands instead:

# ✅ PREFERRED - Use ops commands
pnpm ops gh:pr-info 478        # Get PR title, body, state
pnpm ops gh:pr-reviews 478     # Get all reviews
pnpm ops gh:pr-comments 478    # Get line-level review comments
pnpm ops gh:pr-conversation 478 # Get conversation comments
pnpm ops gh:pr-edit 478 --title "New title"  # Edit PR
pnpm ops gh:pr-edit 478 --body "New body"
pnpm ops gh:pr-edit 478 --body-file pr.md    # Body from file
pnpm ops gh:pr-all 478         # Get everything

# ❌ BROKEN - Do NOT use
gh pr edit 478 --title "..."   # GraphQL error!

Comment Types

PRs have THREE different comment types with different endpoints:

  • Issue comments (general): ops gh:pr-conversation or /issues/{pr}/comments
  • Review comments (line-specific): ops gh:pr-comments or /pulls/{pr}/comments
  • Reviews (APPROVE, etc.): ops gh:pr-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