Git Workflow Management Skill

Comprehensive git workflow assistance including branch validation, commit conventions, PR preparation, and repository health checks.

When This Skill Activates

This skill automatically activates when user mentions:

•"git" or "git workflow"
•"branch" or "branch validation" or "branch naming"
•"commit" or "commit message" or "conventional commits"
•"pull request" or "PR" or "create PR"
•"merge" or "rebase"
•"git status" or "repository status"
•"workflow" or "git workflow helpers"
•"milestone" or "start feature" or "start work"
•"worktree" or "parallel work" or "parallel development"
•"semantic release" or "version bump"

What This Skill Does

Provides comprehensive git workflow management:

•Milestone Management: Auto-detect branch vs worktree, semantic release alignment, parallel work
•Branch Management: Validate branch names, create feature branches, manage strategy
•Worktree Orchestration: Create, manage, and cleanup worktrees for parallel development
•Commit Conventions: Validate conventional commits, ensure signing, check formatting
•PR Preparation: Automated PR creation with GitHub integration and What the Diff
•Repository Health: Status checks, conflict detection, PR readiness validation
•Workflow Automation: Pre-commit checks, secrets detection, file size validation

User Intent Detection and Routing

Branch Validation

Triggers: "validate branch", "check branch name", "branch naming conventions"

Route to: /git/branch workflow

Examples:

•"validate my branch name"
•"check if branch follows conventions"
•"create a feature branch"

Commit Message Validation

Triggers: "validate commit", "check commit message", "conventional commits"

Route to: /git/commit workflow

Examples:

•"validate my last commit message"
•"check commit conventions"
•"does my commit follow standards?"

PR Readiness Check

Triggers: "check PR", "ready for PR", "PR readiness", "can I create a PR"

Route to: /git/pr-check workflow

Examples:

•"is my branch ready for a pull request?"
•"check if I can create a PR"
•"validate PR readiness"

PR Preparation (Automated)

Triggers: "create PR", "prepare PR", "make pull request", "generate PR description"

Route to: /git/pr-prepare workflow (MCP integration)

Examples:

•"create a pull request"
•"prepare PR with What the Diff"
•"generate PR description for my changes"

Repository Status

Triggers: "git status", "repo status", "check repository", "what changed"

Route to: /git/status workflow

Examples:

•"show me git status"
•"what files have changed?"
•"summarize repository status"

Milestone Branch Management (RECOMMENDED)

Triggers: "start feature", "start work", "new milestone", "begin implementation", "start fix"

Route to: /git/milestone workflow

Examples:

•"start working on user authentication feature"
•"begin implementing the dashboard"
•"I need to fix a bug while working on this feature"
•"start a new milestone for API refactoring"

Key Feature: Auto-detects when to use worktree vs simple branch based on:

•Current uncommitted changes
•Whether already on a feature branch
•Type of work (hotfix requires isolation)

Worktree Management

Triggers: "worktree", "parallel work", "parallel branch", "need isolation"

Route to: /git/milestone workflow (worktree subcommand)

Examples:

•"create worktree for parallel development"
•"I need to review a PR while keeping my changes"
•"set up isolated workspace for hotfix"
•"list my active worktrees"

General Git Questions

Triggers: "git workflow", "git best practices", "branch strategy", "commit standards"

Action: Load relevant context files and explain concepts

Examples:

•"explain git workflow best practices"
•"what are the branch naming conventions?"
•"how should I format commit messages?"

Quick Command Reference

bash

# === MILESTONE MANAGEMENT (RECOMMENDED) ===

# Start new feature (auto-detects branch vs worktree)
/git/milestone start feat/user-dashboard

# Start bug fix
/git/milestone start fix/api-timeout

# Force worktree for parallel work
/git/milestone worktree feat/parallel-feature

# Complete milestone (validates, suggests PR)
/git/milestone complete

# List active branches and worktrees
/git/milestone list

# === BRANCH MANAGEMENT ===

# Validate branch name
/git/branch validate

# Create feature branch
/git/branch create feature/123-add-auth

# === COMMIT VALIDATION ===

# Validate last commit
/git/commit validate

# === PR WORKFLOW ===

# Check PR readiness
/git/pr-check

# Create PR with What the Diff (RECOMMENDED)
/git/pr-prepare --include_wtd=true --target_branch=main

# Force WTD for large PRs
/git/pr-prepare --include_wtd=true --force_wtd=true

# === STATUS ===

# Repository status summary
/git/status

Git Workflow Standards

Branch Naming Conventions

Follow this pattern: <type>/<issue-number>-<short-description>

Valid types:

•feature/ - New features
•fix/ - Bug fixes
•hotfix/ - Critical production fixes
•chore/ - Maintenance tasks

Examples:

•feature/123-user-authentication
•fix/456-memory-leak
•hotfix/789-security-patch
•chore/101-update-dependencies

Conventional Commit Format

Follow Conventional Commits specification:

code

<type>(<scope>): <description>

[optional body]

[optional footer]

Valid types: feat, fix, docs, style, refactor, test, chore, ci, perf

Examples:

bash

feat(auth): add user login functionality
fix(api): resolve timeout issue in payment endpoint
docs(readme): update installation instructions
chore(deps): upgrade dependencies to latest versions

PR Preparation Workflow (AUTOMATED)

ALWAYS use mcp__zen-core__pr_prepare for PR creation:

•Branch Safety Validation: Ensures proper branch strategy
•Dependency Updates: Regenerates requirements files automatically
•Security Scanning: Checks for dependency vulnerabilities
•What the Diff Integration: Includes AI-generated summary
•GitHub Integration: Creates draft PR with comprehensive description

Default behavior:

•Includes What the Diff shortcode ()
•Validates branch targeting and naming
•Updates dependency files if needed
•Runs security checks
•Generates comprehensive PR description

What the Diff Integration:

•Shortcode:  (HTML comment format)
•Placement: Inserted where AI summary is desired
•Additional options: , 
•Disable: Use --include_wtd=false (rare)

Signing Configuration

All commits MUST be signed:

bash

# Configure signing key
git config --get user.signingkey  # Must be configured

# Check SSH signing
ssh-add -l  # Must show SSH key

# Check GPG signing
gpg --list-secret-keys  # Must show GPG key

Integration with Other Skills

Pre-Commit Validation

Works with quality skill:

bash

/quality/precommit  # Runs before commit
/git/commit validate  # Validates after commit

Security Validation

Complements security skill:

bash

/security/validate-env  # Check signing keys
/git/pr-prepare  # Includes security scan

Assumption Verification

Integrates with RAD skill:

bash

/rad/verify --scope=changed-files  # Before PR
/git/pr-prepare  # After verification

Common Workflows

Starting a New Milestone (RECOMMENDED)

bash

# 1. Start milestone with automatic branch/worktree detection
/git/milestone start feat/user-dashboard

# 2. Work through your TODO items with proper commits
git add .
git commit -m "feat(dashboard): add initial component"
git commit -m "feat(dashboard): implement data fetching"
git commit -m "test(dashboard): add unit tests"

# 3. Complete milestone validation
/git/milestone complete

# 4. Create PR
/git/pr-prepare --include_wtd=true

Parallel Feature Development

bash

# 1. Start first feature
/git/milestone start feat/feature-a

# 2. Need to work on something else? Start parallel worktree
/git/milestone worktree fix/urgent-bug

# 3. Switch between worktrees as needed
cd ../project-worktrees/fix-urgent-bug
# ... work on fix ...
/git/milestone complete

# 4. Return to original feature
cd ../project
# ... continue feature work ...
/git/milestone complete

# 5. Clean up
git worktree list
git worktree remove ../project-worktrees/fix-urgent-bug

Creating a Feature Branch (Manual)

bash

# 1. Create and checkout feature branch
git checkout -b feature/123-add-feature

# 2. Validate branch name
/git/branch validate

# 3. Make changes and commit
git add .
git commit -m "feat(module): add new feature"

# 4. Validate commit
/git/commit validate

Preparing a Pull Request

bash

# 1. Check PR readiness
/git/pr-check

# 2. Verify assumptions (if using RAD)
/rad/verify --scope=changed-files

# 3. Run pre-commit validation
/quality/precommit

# 4. Create PR with What the Diff
/git/pr-prepare --include_wtd=true --target_branch=main

# 5. Review generated PR description and push

Fixing Commit Issues

bash

# 1. Check last commit
/git/commit validate

# 2. If invalid, amend commit message
git commit --amend -m "feat(auth): add user login"

# 3. Re-validate
/git/commit validate

Updating Feature Branch

bash

# 1. Fetch latest changes
git fetch origin

# 2. Rebase on main
git rebase origin/main

# 3. Resolve conflicts if any
# 4. Force push (if already pushed)
git push --force-with-lease

Workflow Best Practices

Branch Management

•Keep branches focused on single features/fixes
•Use descriptive branch names with issue numbers
•Delete branches after merging
•Never work directly on main/master

Commit Practices

•Write clear, conventional commit messages
•Keep commits atomic (one logical change per commit)
•Sign all commits for security
•Never commit secrets or sensitive data

PR Guidelines

•Keep PRs under 400 lines when possible
•Include comprehensive description
•Link to related issues
•Use What the Diff for AI-generated summaries
•Request appropriate reviewers

Repository Hygiene

•Run pre-commit hooks before every commit
•Keep dependencies up to date
•Address security vulnerabilities promptly
•Maintain clean commit history with rebase

MCP Integration

PR Prepare Tool

The mcp__zen-core__pr_prepare tool provides comprehensive PR preparation:

Features:

•Branch strategy validation and migration assistance
•Automatic dependency file updates (requirements.txt, poetry.lock)
•Security vulnerability scanning
•What the Diff shortcode integration
•GitHub PR creation with rich descriptions
•Size analysis and splitting suggestions

Usage:

bash

# Standard PR with WTD
mcp__zen-core__pr_prepare --include_wtd=true

# Custom parameters
mcp__zen-core__pr_prepare \
  --include_wtd=true \
  --target_branch=develop \
  --change_type=feat \
  --title="Add new authentication system"

# Force WTD for large PRs
mcp__zen-core__pr_prepare --force_wtd=true

Resources

•Milestone Management: See workflows/milestone.md (RECOMMENDED)
•Branch Strategies: See context/branch-strategies.md
•Commit Standards: See context/conventional-commits.md
•PR Preparation: See workflows/pr-prepare.md
•Global Standards: See CLAUDE.md > Automated Branch Creation Strategy
•Worktree Reference: See ~/.claude/standards/git-worktree.md

Consolidated from workflow-git-helpers command and MCP pr_prepare integration.