| name | git-workflow |
| description | Git workflow management โ use when the user mentions git, conventional commits, commit quality, branch management, worktree operations, GitFlow, changelog generation, semantic versioning, release notes, backlog management, or issue tracking integration. NOT for CI/CD pipelines or pipeline YAML (use cicd-pipelines), NOT for non-git workflow orchestration (use skillstack-workflows or multi-agent-patterns), NOT for code review content or PR quality assessment (use code-review). |
| allowed-tools | Bash, Read, Grep, Glob, Write |
Git Workflow - Comprehensive Git Management Skill
Unified skill for commit management, branch workflows, worktree operations, and story backlog management.
When to Use / Not Use
Use when:
- Writing, validating, or reviewing commit messages for conventional commits compliance
- Grouping changed files into logical atomic commits
- Managing feature branches and worktrees with GitFlow conventions
- Generating changelogs from commit history
- Calculating next semantic version from commit types
- Managing a hierarchical story backlog linked to code changes
- Running
/commit, /validate, /changelog, /version commands
Do NOT use when:
- CI/CD pipeline configuration or deployment YAML -> use
cicd-pipelines
- Non-git workflow orchestration -> use
skillstack-workflows or multi-agent-patterns
- Code review content (security, performance, design) -> use
code-review
Decision Tree
What Git workflow task do you need?
โโโ Write commits
โ โโโ Single logical change -> /commit (auto-analyze staged diff)
โ โโโ Multiple changed files, unclear grouping -> python scripts/group-files.py --analyze
โ โโโ Validate message format -> /validate "feat(auth): add JWT refresh"
โ โโโ Amend/fix last commit -> /fix
โโโ Branch management
โ โโโ New feature branch -> feature/{name}, use GitFlow conventions
โ โโโ New fix branch -> fix/{name}
โ โโโ Critical production fix -> hotfix/{name} from main
โ โโโ Need parallel work -> git worktree (scripts/create_worktree.sh)
โโโ Release workflow
โ โโโ Generate changelog -> python scripts/changelog.py --version X.Y.Z
โ โโโ Determine next version -> python scripts/version.py --verbose
โ โ โโโ Has BREAKING CHANGE -> major (X.0.0)
โ โ โโโ Has feat commits -> minor (0.X.0)
โ โ โโโ Only fix/other -> patch (0.0.X)
โ โโโ Clean up merged worktrees -> scripts/cleanup_worktrees.sh --merged
โโโ Story backlog
โ โโโ Initialize tree -> "Initialize story tree"
โ โโโ Generate stories -> "Generate stories for [epic-id]"
โ โโโ View tree -> python scripts/tree-view.py --show-capacity
โ โโโ Update from commits -> "Update story tree"
โโโ Issue integration
โ โโโ Sync issues -> python scripts/issue-tracker.py sync assigned
โ โโโ Suggest refs for staged changes -> python scripts/issue-tracker.py suggest-refs
โโโ Not a Git workflow question? -> See related skills
Part 1: Commit Management
Conventional Commits Format
<type>(<scope>): <subject>
<body>
<footer>
Types (from Angular convention):
| Type | Purpose |
|---|
feat | New feature |
fix | Bug fix |
docs | Documentation only |
style | Formatting, whitespace |
refactor | Code change without behavior change |
perf | Performance improvement |
test | Adding or correcting tests |
chore | Build/tooling changes |
ci | CI/CD changes |
build | Build system/dependencies |
revert | Reverts a previous commit |
Subject Rules:
- Imperative mood: "add feature" not "added feature"
- No period at end
- Lowercase
- Under 100 characters
Footer:
BREAKING CHANGE: - Breaking changesCloses #N / Fixes #N - Closes issue on mergeRefs #N - References issue without closingCo-authored-by: - Multiple authors
Commit Quality Standards
Good commit message:
feat(auth): add JWT token refresh mechanism
Implements automatic token refresh 5 minutes before expiration
to maintain seamless user sessions.
Closes #142
Commit size guidelines:
| Size | LOC | Action |
|---|
| Tiny | < 10 | Single logical change |
| Small | 10-50 | Typical atomic commit |
| Medium | 50-200 | Feature component |
| Large | 200-500 | Consider splitting |
| Too Large | > 500 | Definitely split |
Slash Commands
| Command | Action |
|---|
/commit | Smart commit helper with auto-analysis |
/validate <msg> | Validate commit message format |
/types | Show all commit types |
/scopes | Explain scopes with examples |
/breaking | Breaking change guide |
/changelog | Generate changelog from commits |
/version | Determine next semantic version |
/examples | Show commit examples |
/fix | Help amend/fix last commit |
Intelligent File Grouping
When multiple files need committing, group by:
- Scope-Based - Group by functional area (auth, api, ui)
- Type-Based - Separate implementation, tests, docs
- Relationship-Based - Keep related files together
Workflow:
python {baseDir}/scripts/group-files.py --analyze
Issue Integration
Automatic issue detection from:
- Branch name:
feature/issue-42 -> #42
- Keyword matching with file paths
- Label correlation with file patterns
Issue reference types:
Closes #N - Auto-closes on mergeFixes #N - Same as Closes (for bugs)Refs #N - References without closingProgresses #N - Partial progress
Part 2: Branch & Worktree Management
GitFlow Branch Conventions
Branch Types:
| Type | Pattern | Purpose |
|---|
| Feature | feature/{name} | New features |
| Fix | fix/{name} | Bug fixes |
| Hotfix | hotfix/{name} | Critical production fixes |
| Release | release/{version} | Release preparation |
Naming Guidelines:
- Use kebab-case (lowercase with hyphens)
- Be descriptive but concise (2-4 words)
- No spaces or special characters
Worktree Operations
Directory Structure:
project-root/ <- Main repository
project-root-worktrees/ <- Worktree parent
feature/
email-notifications/ <- feature/email-notifications
fix/
login-timeout/ <- fix/login-timeout
Commands:
./scripts/create_worktree.sh feature email-notifications
./scripts/list_worktrees.sh --detailed
./scripts/cleanup_worktrees.sh --merged --dry-run
Benefits:
- Parallel development on multiple features
- No stashing needed
- Fast switching (just
cd)
- Isolated build artifacts
Part 3: Release Management
Changelog Generation
python {baseDir}/scripts/changelog.py --version 2.0.0
Output format:
## [2.0.0] - 2025-01-18
### BREAKING CHANGES
- **auth**: change token format to JWT (#234)
### Features
- **auth**: add OAuth2 login (#123)
- **api**: add user search endpoint (#145)
### Bug Fixes
- **api**: prevent null pointer in user lookup (#156)
Semantic Versioning
python {baseDir}/scripts/version.py --verbose
Bump rules:
- Major (X.0.0) - Has breaking changes
- Minor (0.X.0) - Has features/fixes, no breaking
- Patch (0.0.X) - Only other changes
Part 4: Story Tree Management
Purpose
Maintain a self-managing tree of user stories where:
- Each node represents a story at some granularity level
- Nodes have capacity (target child count)
- Git commits are analyzed to mark stories as implemented
- Under-capacity nodes are identified for story generation
Database
Location: .claude/data/story-tree.db
Pattern: Closure table for hierarchical data
CRITICAL: Use Python's sqlite3 module (NOT sqlite3 CLI):
python -c "
import sqlite3
conn = sqlite3.connect('.claude/data/story-tree.db')
cursor = conn.cursor()
cursor.execute('SELECT * FROM story_nodes')
print(cursor.fetchall())
conn.close()
"
Story Format
### [ID]: [Title]
**As a** [specific user role]
**I want** [specific capability]
**So that** [specific benefit]
**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
**Related context**: [Git commits or patterns]
Workflow Commands
| Command | Action |
|---|
| "Update story tree" | Run full workflow |
| "Show story tree" | Visualize current tree |
| "Tree status" | Show metrics only |
| "Set capacity for [id] to [N]" | Adjust capacity |
| "Mark [id] as [status]" | Change status |
| "Generate stories for [id]" | Force generation |
| "Initialize story tree" | Create new database |
Tree Visualization
python {baseDir}/scripts/tree-view.py --show-capacity
Status symbols:
| Status | Symbol | Meaning |
|---|
| concept | . | Idea, not approved |
| approved | v | Human approved |
| epic | E | Needs decomposition |
| planned | o | Plan created |
| in-progress | D | Partially complete |
| implemented | + | Complete/done |
| ready | # | Production ready |
Anti-Patterns
| Anti-Pattern | Problem | Solution |
|---|
| Dumping all changes in one commit | Un-reviewable, un-revertable; hides logical changes | Group by scope/type using group-files.py; one logical change per commit |
| Vague commit messages ("wip", "fix stuff", "updates") | Cannot generate changelog; bisect useless | Use conventional commits: type(scope): imperative subject |
| Non-imperative subject ("added feature") | Inconsistent with conventional commits; reads as past tense | Use imperative mood: "add feature" not "added feature" |
| Missing issue references | No link between code and requirements; lost knowledge | Include Closes #N or Refs #N in commit footer |
| Commit too large (>500 LOC) | Too much surface area for review; hard to revert independently | Split into atomic commits; group-files.py suggests groupings |
| Mixing concerns in one commit (impl + tests + docs) | Hard to revert just tests or just docs; bloats review | Separate: feat commit, test commit, docs commit |
Breaking change without BREAKING CHANGE: footer | Changelog misses breaking changes; version bump wrong | Always document breaking changes in footer; triggers major version |
| Working on main instead of feature branch | No isolation; hard to revert; messy history | Use GitFlow: feature/ for new work, fix/ for bugs, hotfix/ for prod |
| Stashing instead of worktrees | Lost context; stash conflicts; no parallel work | Use git worktree for parallel feature development |
| Missing changelog before release | Manual, incomplete release notes | Run changelog.py auto-generated from conventional commits |
| Guessing version number | Incorrect semver; surprises in release | Run version.py -- auto-calculated from commit types |
Scripts Reference
Commit Scripts
| Script | Purpose |
|---|
analyze-diff.py | Analyze staged changes, suggest commits |
validate.py | Validate commit message format |
changelog.py | Generate changelog from commits |
version.py | Calculate next semantic version |
commit-analyzer.py | Full commit quality analysis |
conventional-commits.py | Conventional commits helper |
group-files.py | Intelligent file grouping |
issue-tracker.py | Issue sync and detection |
Workflow Scripts
| Script | Purpose |
|---|
create_worktree.sh | Create worktree with GitFlow conventions |
list_worktrees.sh | List all worktrees with status |
cleanup_worktrees.sh | Clean up merged/stale worktrees |
init-environment.py | Initialize GitHub workflow environment |
Story Tree Scripts
| Script | Purpose |
|---|
tree-view.py | ASCII tree visualization |
References
Commit References
references/conventional-commits.md - Full specificationreferences/commit-patterns.md - Patterns and anti-patternsreferences/examples.md - Commit examplesreferences/slash-commands.md - Detailed command workflows
Workflow References
references/gitflow-conventions.md - GitFlow reference
Story Tree References
references/schema.sql - Database schemareferences/sql-queries.md - SQL query patternsreferences/common-mistakes.md - Error preventionreferences/rationales.md - Design decisionsreferences/epic-decomposition.md - Epic workflowreferences/workflow-diagrams.md - Visual workflowsreferences/orchestrator-workflow-complete.md - Full orchestrator flowreferences/orchestrator-workflow-current.md - Current workflow
Assets
assets/commit-templates.json - Template patterns for commit types
Integration Points
With Issue Tracking
python {baseDir}/scripts/issue-tracker.py sync assigned
python {baseDir}/scripts/issue-tracker.py suggest-refs
With PR Reviews
- Validate commits in PRs
- Report format violations
- Suggest improvements before merge
With CI/CD
- Generate changelogs automatically
- Determine version bumps
- Validate commit messages in pipeline
Error Handling
Common issues:
| Issue | Recovery |
|---|
| Empty commit message | Generate from changes |
| No staged changes | Prompt to stage |
| Format violations | Suggest correction |
| Missing issue reference | Search and suggest |
| Commit too large | Recommend splitting |
| Database not found | Initialize first |
| Checkpoint rebased | Run full scan |
Source Skills
This skill was merged from:
story-tree---autonomous-hierarchical-backlog-managermanaging-commits-skillgit-commit-assistantgit-workflow-manager-skill
