git-workflow

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

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:**
```bash
# 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/               <- Main repository
project-root-worktrees/     <- Worktree parent
  feature/
    email-notifications/    <- feature/email-notifications
  fix/
    login-timeout/          <- fix/login-timeout
```

**Commands:**
```bash
# Create worktree
./scripts/create_worktree.sh feature email-notifications

# List worktrees
./scripts/list_worktrees.sh --detailed

# Cleanup merged worktrees
./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

```bash
python {baseDir}/scripts/changelog.py --version 2.0.0
```

**Output format:**
```markdown
## [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

```bash
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
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

```markdown
### [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

```bash
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 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`

• SKILL.md 14 KB
• assets/commit-templates.json 7 KB
• evals/evals.json 1 KB
• evals/trigger-evals.json 2 KB
• references/commit-patterns.md 5 KB
• references/common-mistakes.md 4 KB
• references/conventional-commits.md 2 KB
• references/epic-decomposition.md 1 KB
• references/examples.md 3 KB
• references/gitflow-conventions.md 3 KB
• references/orchestrator-workflow-complete.md 24 KB
• references/orchestrator-workflow-current.md 8 KB
• references/rationales.md 2 KB
• references/schema.sql 5 KB
• references/slash-commands.md 11 KB
• references/sql-queries.md 8 KB
• references/workflow-diagrams.md 13 KB
• scripts/analyze-diff.py 13 KB
• scripts/changelog.py 7 KB
• scripts/cleanup_worktrees.sh 6 KB
• scripts/commit-analyzer.py 12 KB
• scripts/conventional-commits.py 7 KB
• scripts/create_worktree.sh 3 KB
• scripts/group-files.py 9 KB
• scripts/init-environment.py 19 KB
• scripts/issue-tracker.py 24 KB
• scripts/list_worktrees.sh 3 KB
• scripts/tree-view.py 19 KB
• scripts/validate.py 2 KB
• scripts/version.py 7 KB