vc-ship

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