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:

<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.

Search AI Tools

Install this agent skill to your Project

SKILL.md

Git Workflow Management Skill

When This Skill Activates

What This Skill Does

User Intent Detection and Routing

Branch Validation

Commit Message Validation

PR Readiness Check

PR Preparation (Automated)

Repository Status

Milestone Branch Management (RECOMMENDED)

Worktree Management

General Git Questions

Quick Command Reference

Git Workflow Standards

Branch Naming Conventions

Conventional Commit Format

PR Preparation Workflow (AUTOMATED)

Signing Configuration

Integration with Other Skills

Pre-Commit Validation

Security Validation

Assumption Verification

Common Workflows

Starting a New Milestone (RECOMMENDED)

Parallel Feature Development

Creating a Feature Branch (Manual)

Preparing a Pull Request

Fixing Commit Issues

Updating Feature Branch

Workflow Best Practices

Branch Management

Commit Practices

PR Guidelines

Repository Hygiene

MCP Integration

PR Prepare Tool

Resources