Branching Strategy and Conventions
Overview
P0 Foundational - Applies by default. Establishes branching model, commit conventions, and merge strategy.
REQUIRED: superpowers:verification-before-completion
When to Use
- Any repository (default)
- New repository creation
- Existing repo without documented branching policy
- User requests Git branching or commit conventions
- Release management or versioning strategy needed
Core Workflow
- Announce skill (default for all repos)
- Define branching strategy (Trunk-Based, GitHub Flow, or Git Flow)
- Set default branch as
main
- Define branch naming:
feature/*, fix/*, docs/*, hotfix/*, release/*
- Configure Conventional Commits (Commit Conventions)
- Set up commitlint + pre-commit hooks
- Define merge strategy: disable merge commits, prefer
--ff-only or squash
- Document squash merge SemVer preservation (Squash Merge Guide)
- Configure branch protection rules
- Document in CONTRIBUTING.md
- Brownfield: baseline existing history, enforce on new commits
Quick Reference
| Element |
Standard |
Enforcement |
| Default Branch |
main |
Repository |
| Branch Naming |
feature/*, fix/*, docs/* |
CI validation |
| Commit Format |
Conventional Commits |
commitlint |
| Commit Types |
feat, fix, docs, chore, refactor, test, ci |
Pre-commit + CI |
| Merge Strategy |
Squash (multi-commit) or FF-only (single) |
Branch rules |
| Breaking Change |
feat!: or BREAKING CHANGE footer |
SemVer MAJOR |
See Branching Models for strategy comparison.
Red Flags - STOP
- "Can define strategy later"
- "Just use main for now"
- "Team knows commits"
- "History is messy anyway"
- "Commit format not important"
- "Can parse freeform messages"
- "Too restrictive for developers"
All mean: Apply skill or document explicit opt-out in exclusions.md.
Rationalizations
| Excuse |
Reality |
| "Can define strategy later" |
Later never comes. Strategy takes 15 minutes, prevents project-long confusion. |
| "Just use main branch for now" |
No strategy = accidental commits to main, no review process, deployment chaos. |
| "Team knows how to write commits" |
Inconsistent messages break automation, make history unreadable, prevent SemVer. |
| "History is already messy" |
Enforce on new commits. Baseline existing history, don't rewrite it. |
| "Commit format not critical" |
Conventional Commits enable changelogs, SemVer, release notes. Critical for automation. |
Evidence Checklist
1---2name: branching-strategy-and-conventions3description: Use when creating any repository, defining Git workflows, or enforcing commit conventions. Establishes branching policy, commit message standards (Conventional Commits), and merge rules aligned to SemVer.4---56# Branching Strategy and Conventions78## Overview910**P0 Foundational** - Applies by default. Establishes branching model, commit conventions, and merge strategy.1112**REQUIRED:** superpowers:verification-before-completion1314## When to Use1516- Any repository (default)17- New repository creation18- Existing repo without documented branching policy19- User requests Git branching or commit conventions20- Release management or versioning strategy needed2122## Core Workflow23241. Announce skill (default for all repos)252. Define branching strategy (Trunk-Based, GitHub Flow, or Git Flow)263. Set default branch as `main`274. Define branch naming: `feature/*`, `fix/*`, `docs/*`, `hotfix/*`, `release/*`285. Configure Conventional Commits ([Commit Conventions](references/commit-conventions.md))296. Set up commitlint + pre-commit hooks307. Define merge strategy: disable merge commits, prefer `--ff-only` or squash318. Document squash merge SemVer preservation ([Squash Merge Guide](references/squash-merge-guide.md))329. Configure branch protection rules3310. Document in CONTRIBUTING.md3411. Brownfield: baseline existing history, enforce on new commits3536## Quick Reference3738| Element | Standard | Enforcement |39| --------------- | ------------------------------------------ | --------------- |40| Default Branch | `main` | Repository |41| Branch Naming | `feature/*`, `fix/*`, `docs/*` | CI validation |42| Commit Format | Conventional Commits | commitlint |43| Commit Types | feat, fix, docs, chore, refactor, test, ci | Pre-commit + CI |44| Merge Strategy | Squash (multi-commit) or FF-only (single) | Branch rules |45| Breaking Change | `feat!:` or `BREAKING CHANGE` footer | SemVer MAJOR |4647See [Branching Models](references/branching-models.md) for strategy comparison.4849## Red Flags - STOP5051- "Can define strategy later"52- "Just use main for now"53- "Team knows commits"54- "History is messy anyway"55- "Commit format not important"56- "Can parse freeform messages"57- "Too restrictive for developers"5859**All mean: Apply skill or document explicit opt-out in exclusions.md.**6061## Rationalizations6263| Excuse | Reality |64| --------------------------------- | --------------------------------------------------------------------------------------- |65| "Can define strategy later" | Later never comes. Strategy takes 15 minutes, prevents project-long confusion. |66| "Just use main branch for now" | No strategy = accidental commits to main, no review process, deployment chaos. |67| "Team knows how to write commits" | Inconsistent messages break automation, make history unreadable, prevent SemVer. |68| "History is already messy" | Enforce on new commits. Baseline existing history, don't rewrite it. |69| "Commit format not critical" | Conventional Commits enable changelogs, SemVer, release notes. Critical for automation. |7071## Evidence Checklist7273- [ ] Branching strategy defined (Trunk-Based, GitHub Flow, or Git Flow)74- [ ] Default branch is `main`75- [ ] Branch naming conventions documented76- [ ] Conventional Commits configured (commitlint)77- [ ] Pre-commit hooks configured78- [ ] Merge strategy defined (squash or FF-only)79- [ ] CONTRIBUTING.md updated
mcj-coder