name: vc-ship description: >- Automates end-to-end git workflows from branch creation through PR submission. Organizes changes into atomic commits with clean history and quality checks. Use when shipping code, preparing changes for review, committing and pushing, creating pull requests, or cleaning up commit history.

Reference Files

• workflow-phases.md - Step-by-step phase instructions
• commit-format.md - Commit message formatting rules
• rebase-guide.md - History cleanup safety guidelines
• phase-0-protocol.md - Protected branch detection at start of work
• phase-5-protocol.md - Pre-push quality review checklist
• protected-branch-protocol.md - Push-time branch protection
• simple-feature.md - Single atomic commit example
• bug-fix.md - Mixed changes separated into logical commits
• large-refactor.md - Multi-commit refactoring with task tracking
• messy-history.md - Cleaning up WIP commits before push
• pr-creation.md - Multiple commits to PR with rich description
• eval-simple-feature.md - Evaluation: simple feature scenario
• eval-large-refactor.md - Evaluation: large refactor scenario
• eval-messy-history.md - Evaluation: messy history scenario
• eval-symlink-edge-case.md - Evaluation: symlinked files scenario

Git Workflow Skill

This skill provides intelligent, end-to-end Git workflow automation. It analyzes repository changes, organizes them into atomic commits with well-formatted messages, manages branches, cleans up commit history, and helps create pull requests.

Contents

• Workflow Overview
• Edge Case Quick Reference
• User Interaction Patterns
• Summary
• When NOT to Use

Workflow Overview

The skill follows an 8-phase workflow:

0. Branch Management - Ensure work is on appropriate branch
1. Repository Analysis - Understand current state and changes
2. Organize into Atomic Commits - Group related changes logically
3. Create Commits - Generate well-formatted commit messages
4. Commit History Cleanup - Optionally reorganize commits before push
5. Pre-Push Quality Review - Analyze commit quality and run tests (MANDATORY)
6. Push with Confirmation - Push changes to remote after approval
7. Pull Request Creation - Optionally create PR with generated description (Summary, Changes, Breaking Changes, Dependencies, Testing, Related Issues sections)

Key rules:

• Never use git rebase -i (requires interactive input) - use git reset --soft instead
• Always block pushes to protected branches (main/master/develop/production/staging)
• Commit messages: ≤72 chars, imperative mood, explain WHY not WHAT

Edge Case Quick Reference

User Interaction Patterns

Use AskUserQuestion for:

• Branch creation confirmation
• Commit plan approval
• Modifications to commit grouping
• Push confirmation
• PR creation confirmation
• Force push warnings
• Protected branch warnings

Use TaskCreate/TaskUpdate/TaskList for:

• Tracking multiple commits to create (3+ commits)
• Long workflow with many steps
• Keeping user informed of progress

Use Bash for:

• All git commands
• All gh commands
• Repository state inspection

Summary

This skill automates the entire Git workflow from analyzing changes to creating a PR. It emphasizes:

• Quality over speed — well-formatted commits are important
• Safety first — always check state and confirm destructive operations
• User control — ask for approval at key decision points
• Education — explain what's happening and why

Key workflow patterns:

• One logical change = one commit; don't mix unrelated changes
• Commits should build on each other (add new, migrate, remove old)
• Clean up messy history before pushing
• Include tests with the code they test
• Keep config changes separate unless tightly coupled to code
• Always branch per feature; never commit directly to main
• Explain WHY in commit messages, not just WHAT

When NOT to Use

This skill is not appropriate for:

• Simple single-file commits - Direct git add && git commit is faster
• Amending the last commit - Use git commit --amend directly
• Cherry-picking commits - Use standard git cherry-pick workflow
• Resolving merge conflicts - User must resolve manually first
• Submodule operations - Complex submodule workflows need manual handling
• Force pushing to shared branches - This skill blocks force pushes for safety