https://github.com/qubernetic-org/git-workflow-agent-skill
Claude Code skill enforcing Gitflow, conventional commits, semantic versioning, and issue-driven branching.
https://github.com/qubernetic-org/git-workflow-agent-skill
ai-coding-assistant claude-code claude-code-skill conventional-commits developer-tools git-workflow gitflow semantic-versioning
Last synced: 26 days ago
JSON representation
Claude Code skill enforcing Gitflow, conventional commits, semantic versioning, and issue-driven branching.
- Host: GitHub
- URL: https://github.com/qubernetic-org/git-workflow-agent-skill
- Owner: qubernetic-org
- License: mit
- Created: 2026-03-18T20:43:41.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-27T23:34:54.000Z (about 1 month ago)
- Last Synced: 2026-03-28T04:12:53.407Z (about 1 month ago)
- Topics: ai-coding-assistant, claude-code, claude-code-skill, conventional-commits, developer-tools, git-workflow, gitflow, semantic-versioning
- Language: Shell
- Homepage:
- Size: 180 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Git Workflow — Claude Code Skill
[](https://github.com/qubernetic-org/git-workflow-agent-skill/actions/workflows/lint.yml)
[](CHANGELOG.md)
[](LICENSE)
[](https://claude.ai/code)
[](https://conventionalcommits.org)
[](https://nvie.com/posts/a-successful-git-branching-model/)
[](https://semver.org)
A Claude Code skill that enforces a disciplined Gitflow-based development workflow with conventional commits, semantic versioning, and issue-driven branching.
[Installation](#installation) · [Usage](#usage) · [What It Enforces](#what-it-enforces) · [Contributing](CONTRIBUTING.md) · [Onboarding](ONBOARDING.md)
---
## Installation
Clone the repo and run the install script for your platform. The script creates a **symlink**, so the skill stays in sync with the repo automatically.
### Linux
```bash
git clone https://github.com/qubernetic-org/git-workflow-agent-skill.git
cd git-workflow-agent-skill
./scripts/install_linux.sh
```
### macOS
```bash
git clone https://github.com/qubernetic-org/git-workflow-agent-skill.git
cd git-workflow-agent-skill
./scripts/install_macos.sh
```
### Windows (PowerShell)
```powershell
git clone https://github.com/qubernetic-org/git-workflow-agent-skill.git
cd git-workflow-agent-skill
.\scripts\install_windows.ps1
```
> **Note:** Windows symlinks require Developer Mode enabled or an elevated terminal. The script falls back to a file copy if symlinks are unavailable.
### Uninstall
```bash
# Linux
./scripts/install_linux.sh --uninstall
# macOS
./scripts/install_macos.sh --uninstall
```
```powershell
# Windows
.\scripts\install_windows.ps1 -Uninstall
```
### Manual Installation
If you prefer not to use the scripts:
```bash
mkdir -p ~/.claude/skills/git-workflow
ln -s "$(pwd)/SKILL.md" ~/.claude/skills/git-workflow/SKILL.md
```
The skill will be automatically discovered on the next Claude Code session.
## Usage
The skill activates automatically when you ask Claude Code to perform any git operation:
```
> Commit my changes
> Create a branch for this feature
> Prepare a release for version 1.2.0
> I need to hotfix a production bug
```
Or invoke directly:
```
/git-workflow
```
## What It Enforces
| Rule | Description |
|------|-------------|
| **Gitflow branching** | `main`, `develop`, `feature/*`, `fix/*`, `hotfix/*`, `release/*` |
| **Conventional Commits** | Structured messages — `feat:`, `fix:`, `docs:`, `chore:`, etc. |
| **Atomic commits** | One logical change per commit, no mixed concerns |
| **`--no-ff` merges** | All merges into protected branches preserve branch topology |
| **No AI signatures** | No "Co-Authored-By" or "Generated by" lines |
| **Semantic Versioning** | `MAJOR.MINOR.PATCH` with proper bump rules |
| **Issue-driven workflow** | Every branch starts from an issue and closes it via PR |
| **PR-only merges** | `main` and `develop` are never committed to directly |
| **Conventional PR titles** | PR titles follow Conventional Commits format |
## Branch Model
```mermaid
%%{init: { 'theme': 'base', 'themeVariables': { 'git0': '#0969da', 'git1': '#e8590c', 'git2': '#7c3aed', 'git3': '#2da44e', 'git4': '#fe5196', 'git5': '#2da44e', 'git6': '#cf222e', 'gitBranchLabel0': '#ffffff', 'gitBranchLabel1': '#ffffff', 'gitBranchLabel2': '#ffffff', 'gitBranchLabel3': '#ffffff', 'gitBranchLabel4': '#ffffff', 'gitBranchLabel5': '#ffffff', 'gitBranchLabel6': '#ffffff', 'commitLabelFontSize': '11px', 'tagLabelFontSize': '12px' }, 'gitGraph': { 'mainBranchName': 'main', 'rotateCommitLabel': true, 'showCommitLabel': true } } }%%
gitGraph
commit id: "init"
commit id: " " tag: "v0.1.0"
branch develop order: 1
commit id: "setup"
branch "feature/1-auth" order: 2
commit id: "login"
commit id: "logout"
checkout develop
merge "feature/1-auth" id: " merge-1"
branch "feature/2-search" order: 3
commit id: "index"
commit id: "query"
checkout develop
branch "fix/3-typo" order: 4
commit id: "typo"
checkout develop
merge "fix/3-typo" id: " merge-3"
merge "feature/2-search" id: " merge-2"
branch "release/1.0" order: 1
commit id: "bump"
commit id: "changelog"
checkout main
merge "release/1.0" id: " " tag: "v1.0.0"
checkout develop
merge main id: " back-merge"
checkout main
branch "hotfix/4-crash" order: 2
commit id: "crash-fix"
commit id: "patch"
checkout main
merge "hotfix/4-crash" id: " " tag: "v1.0.1"
checkout develop
merge main id: " hotfix-sync"
commit id: "next"
```
| Pattern | Base | Merges into | Purpose |
|---------|------|-------------|---------|
| `feature/-` | `develop` | `develop` | New features |
| `fix/-` | `develop` | `develop` | Bug fixes |
| `hotfix/-` | `main` | `main` + `develop` | Urgent production fixes |
| `release/` | `develop` | `main` + `develop` | Release preparation |
## Commit Format
```
():
```
```
feat(auth): add OAuth2 login flow
fix: resolve race condition in websocket reconnect
chore(release): prepare 1.2.0
feat!: drop support for Node 16
```
See [SKILL.md](SKILL.md) for the full specification including commit types, breaking change conventions, versioning rules, release processes, and the complete forbidden operations list.
## Why This Workflow?
| Aspect | This Skill (Gitflow) | GitHub Flow | Trunk-Based |
|--------|---------------------|-------------|-------------|
| **Branches** | `main` + `develop` + typed branches | `main` + feature branches | `main` only |
| **Releases** | Explicit release branches with version bump | Deploy from main on merge | Continuous deploy from main |
| **Commit style** | Conventional Commits (enforced) | Free-form | Free-form |
| **Merge strategy** | `--no-ff` merge commits (preserves topology) | Squash merge (flat history) | Squash or rebase |
| **Traceability** | Issue → branch → PR → changelog | PR-based | Commit-based |
| **Best for** | Versioned releases, libraries, skills, APIs | SaaS with continuous deploy | Small teams, rapid iteration |
### When to use Gitflow
- You ship **discrete versions** (v1.0, v1.1, v2.0) rather than continuous deploys
- You need a **clear audit trail** from issue to release
- Multiple features develop **in parallel** with different release timelines
- You want **hotfix capability** without disrupting in-progress work
### When NOT to use Gitflow
- You deploy to production on every merge (GitHub Flow is simpler)
- You have a single developer with no parallel work streams
- Your project doesn't use semantic versioning
## Integration with Git Hooks and CI Tools
The skill enforces workflow rules through Claude Code, but you can add mechanical enforcement for your team with these tools:
### Commit Message Validation (commitlint)
```bash
npm install --save-dev @commitlint/{cli,config-conventional}
```
```js
// commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', [
'feat', 'fix', 'docs', 'chore', 'refactor',
'test', 'style', 'perf', 'ci', 'build', 'revert'
]],
'subject-case': [2, 'always', 'lower-case'],
'subject-full-stop': [2, 'never', '.'],
'header-max-length': [2, 'always', 72],
},
};
```
### Git Hooks (husky)
```bash
npm install --save-dev husky
npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
```
### Branch Name Validation (CI)
Add to your GitHub Actions workflow:
```yaml
- name: Validate branch name
if: github.event_name == 'pull_request'
run: |
BRANCH="${{ github.head_ref }}"
PATTERN="^(feature|fix|docs|hotfix|release)/[a-z0-9-]+$"
if [[ ! "$BRANCH" =~ $PATTERN ]]; then
echo "::error::Branch '$BRANCH' doesn't match pattern: $PATTERN"
exit 1
fi
```
> **Note:** These tools complement the skill — they catch mechanical errors (typos in commit types, wrong branch names) while Claude Code handles the higher-level workflow logic (correct base branch, issue traceability, release process).
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [ONBOARDING.md](ONBOARDING.md) for a new contributor guide.
## License
[MIT](LICENSE) © [Qubernetic](https://github.com/qubernetic-org)