Git Workflow

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

(): 

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 changes
• Closes #N / Fixes #N - Closes issue on merge
• Refs #N - References issue without closing
• Co-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 | 500 | Definitely split |

Slash Commands

| Command | Action | |---------|--------| | /commit | Smart commit helper with auto-analysis | | /validate | 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:

1. Scope-Based - Group by functional area (auth, api, ui)
2. Type-Based - Separate implementation, tests, docs
3. Relationship-Based - Keep related files together

Workflow:

# Analyze all changes
python {baseDir}/scripts/group-files.py --analyze

# Output example:
# Group 1: feat(auth) - 3 impl files, 245 LOC
# Group 2: test(auth) - 2 test files, 128 LOC
# Group 3: fix(api) - 2 files, 15 LOC

Issue Integration

Automatic issue detection from:

1. Branch name: feature/issue-42 -> #42
2. Keyword matching with file paths
3. Label correlation with file patterns

Issue reference types:

• Closes #N - Auto-closes on merge
• Fixes #N - Same as Closes (for bugs)
• Refs #N - References without closing
• Progresses #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/               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 specification
- `references/commit-patterns.md` - Patterns and anti-patterns
- `references/examples.md` - Commit examples
- `references/slash-commands.md` - Detailed command workflows

### Workflow References
- `references/gitflow-conventions.md` - GitFlow reference

### Story Tree References
- `references/schema.sql` - Database schema
- `references/sql-queries.md` - SQL query patterns
- `references/common-mistakes.md` - Error prevention
- `references/rationales.md` - Design decisions
- `references/epic-decomposition.md` - Epic workflow
- `references/workflow-diagrams.md` - Visual workflows
- `references/orchestrator-workflow-complete.md` - Full orchestrator flow
- `references/orchestrator-workflow-current.md` - Current workflow

## Assets

- `assets/commit-templates.json` - Template patterns for commit types

## Integration Points

### With Issue Tracking
```bash
# Sync issues before committing
python {baseDir}/scripts/issue-tracker.py sync assigned

# Find related issues for staged changes
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:

1. story-tree---autonomous-hierarchical-backlog-manager
2. managing-commits-skill
3. git-commit-assistant
4. git-workflow-manager-skill

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: viktorbezdek
• Source: viktorbezdek/skillstack
• License: MIT

Install and usage instructions live in the source repository linked above.