Detect First
Before applying any convention, run:
git log --oneline -10
Look for the existing pattern in the project history:
- Conventional Commits:
feat:, fix:, chore:, docs: prefixes
- GitHub Flow: plain imperative sentences, no prefix
- GitFlow:
feature/, release/, hotfix/ branch names in merge commits
- Trunk-based: short-lived branches, frequent merges to main, feature flags
Always follow the project's established pattern. Only fall back to Conventional Commits if no pattern is detectable.
Branch Naming
| Prefix |
Purpose |
Lifetime |
Merge target |
feature/* |
New functionality |
Days to 1 sprint |
main / develop |
fix/* |
Non-urgent bug fix |
Hours to days |
main / develop |
hotfix/* |
Urgent production fix |
Hours |
Release tag + main |
release/* |
Release stabilization |
Days |
main + tag |
chore/* |
Tooling, deps, config |
Hours to days |
main / develop |
- Branch names: lowercase, hyphens only, no spaces (e.g.,
feature/user-auth-refresh).
- Keep names short but descriptive; include a ticket ID when the project uses one (e.g.,
fix/PROJ-123-null-pointer).
Commit Messages
Follow skills/shared/conventional-commits/SKILL.md for format details. Key rules:
- One logical change per commit — never mix a feature and a bug fix in the same commit.
- Subject line: ≤ 72 characters; imperative mood ("add", not "added" or "adds").
- Body (optional): explain why, not what — the diff already shows what changed.
- No AI attribution lines (
Co-Authored-By: Claude, Generated with …).
Pull Request Rules
- Title:
<type>: <what changed> (<why, if not obvious>) — mirrors the squash commit that will land on main.
- Description: include a short summary, test plan (checklist), and a link to the ticket or issue.
- No WIP PRs merged to main: use Draft PRs for work in progress; convert to ready only when CI is green.
- Self-review first: read your own diff before requesting review.
- Keep PRs small: prefer multiple focused PRs over one large one; large PRs get shallow reviews.
Merge Strategy
| Scenario |
Strategy |
Reason |
| Feature / fix branch → main |
Squash merge |
Clean, linear history; one commit per feature |
| Release branch → main |
Merge commit |
Preserves full release history |
| Hotfix → main |
Merge commit |
Traceability for post-incident review |
| Sync main → long-lived branch |
Rebase |
Avoids noisy merge commits mid-branch |
- Never force-push to
main or master.
- Delete the source branch after merge.
Release Tagging
- Format:
vMAJOR.MINOR.PATCH (semantic versioning).
- Tag only from
main after CI passes.
- Annotated tags preferred:
git tag -a v1.2.0 -m "Release v1.2.0".
- Push tag explicitly:
git push origin v1.2.0.
| Change type |
Bump |
| Breaking change |
MAJOR |
| New feature, backward-compatible |
MINOR |
| Bug fix, patch, docs |
PATCH |
Hotfix Flow
git checkout -b hotfix/v1.2.1 v1.2.0 — branch from the affected release tag, not from main.- Apply the minimal fix; commit.
- Tag:
v1.2.1.
- Merge back to
main with a merge commit.
- Delete the hotfix branch.
Protected Branch Requirements
main and master must enforce:
- Pull request required (no direct push).
- At least 1 approval from a reviewer who did not author the PR.
- All CI checks must pass before merge.
- No force-push.
- No deletion.
Source: Dev-Toolbelt/dev-team-agents — distributed by TomeVault.
1---2name: git-workflow-1543description: Git — branching, commits, PR workflow, merge, release tagging. Use when this capability is needed.4---56## Detect First78Before applying any convention, run:910```bash11git log --oneline -1012```1314Look for the existing pattern in the project history:15- **Conventional Commits**: `feat:`, `fix:`, `chore:`, `docs:` prefixes16- **GitHub Flow**: plain imperative sentences, no prefix17- **GitFlow**: `feature/`, `release/`, `hotfix/` branch names in merge commits18- **Trunk-based**: short-lived branches, frequent merges to main, feature flags1920Always follow the project's established pattern. Only fall back to Conventional Commits if no pattern is detectable.2122---2324## Branch Naming2526| Prefix | Purpose | Lifetime | Merge target |27|---|---|---|---|28| `feature/*` | New functionality | Days to 1 sprint | `main` / `develop` |29| `fix/*` | Non-urgent bug fix | Hours to days | `main` / `develop` |30| `hotfix/*` | Urgent production fix | Hours | Release tag + `main` |31| `release/*` | Release stabilization | Days | `main` + tag |32| `chore/*` | Tooling, deps, config | Hours to days | `main` / `develop` |3334- Branch names: lowercase, hyphens only, no spaces (e.g., `feature/user-auth-refresh`).35- Keep names short but descriptive; include a ticket ID when the project uses one (e.g., `fix/PROJ-123-null-pointer`).3637---3839## Commit Messages4041Follow `skills/shared/conventional-commits/SKILL.md` for format details. Key rules:4243- One logical change per commit — never mix a feature and a bug fix in the same commit.44- Subject line: ≤ 72 characters; imperative mood ("add", not "added" or "adds").45- Body (optional): explain *why*, not *what* — the diff already shows what changed.46- No AI attribution lines (`Co-Authored-By: Claude`, `Generated with …`).4748---4950## Pull Request Rules5152- **Title**: `<type>: <what changed> (<why, if not obvious>)` — mirrors the squash commit that will land on main.53- **Description**: include a short summary, test plan (checklist), and a link to the ticket or issue.54- **No WIP PRs merged to main**: use Draft PRs for work in progress; convert to ready only when CI is green.55- **Self-review first**: read your own diff before requesting review.56- **Keep PRs small**: prefer multiple focused PRs over one large one; large PRs get shallow reviews.5758---5960## Merge Strategy6162| Scenario | Strategy | Reason |63|---|---|---|64| Feature / fix branch → main | **Squash merge** | Clean, linear history; one commit per feature |65| Release branch → main | **Merge commit** | Preserves full release history |66| Hotfix → main | **Merge commit** | Traceability for post-incident review |67| Sync main → long-lived branch | **Rebase** | Avoids noisy merge commits mid-branch |6869- Never force-push to `main` or `master`.70- Delete the source branch after merge.7172---7374## Release Tagging7576- Format: `vMAJOR.MINOR.PATCH` (semantic versioning).77- Tag only from `main` after CI passes.78- Annotated tags preferred: `git tag -a v1.2.0 -m "Release v1.2.0"`.79- Push tag explicitly: `git push origin v1.2.0`.8081| Change type | Bump |82|---|---|83| Breaking change | MAJOR |84| New feature, backward-compatible | MINOR |85| Bug fix, patch, docs | PATCH |8687---8889## Hotfix Flow90911. `git checkout -b hotfix/v1.2.1 v1.2.0` — branch from the affected release tag, not from main.922. Apply the minimal fix; commit.933. Tag: `v1.2.1`.944. Merge back to `main` with a merge commit.955. Delete the hotfix branch.9697---9899## Protected Branch Requirements100101`main` and `master` must enforce:102- Pull request required (no direct push).103- At least 1 approval from a reviewer who did not author the PR.104- All CI checks must pass before merge.105- No force-push.106- No deletion.107108---109> Source: [Dev-Toolbelt/dev-team-agents](https://github.com/Dev-Toolbelt/dev-team-agents) — distributed by [TomeVault](https://tomevault.io).110<!-- tomevault:4.0:skill_md:2026-05-22 -->
tomevault-io