agentleFS
Sign inStart free
martincjarvismartincjarvis/development-skills/skills/branching-strategy-and-conventions/SKILL.md

branching-strategy-and-conventions

Skill4 starsChanged 10 months agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Document squash merge SemVer preservation (Squash Merge Guide)

    line 34

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Announce skill (default for all repos)
  2. Define branching strategy (Trunk-Based, GitHub Flow, or Git Flow)
  3. Set default branch as main
  4. Define branch naming: feature/*, fix/*, docs/*, hotfix/*, release/*
  5. Configure Conventional Commits (Commit Conventions)
  6. Set up commitlint + pre-commit hooks
  7. Define merge strategy: disable merge commits, prefer --ff-only or squash
  8. Document squash merge SemVer preservation (Squash Merge Guide)
  9. Configure branch protection rules
  10. Document in CONTRIBUTING.md
  11. Brownfield: baseline existing history, enforce on new commits

Quick Reference

ElementStandardEnforcement
Default BranchmainRepository
Branch Namingfeature/*, fix/*, docs/*CI validation
Commit FormatConventional Commitscommitlint
Commit Typesfeat, fix, docs, chore, refactor, test, ciPre-commit + CI
Merge StrategySquash (multi-commit) or FF-only (single)Branch rules
Breaking Changefeat!: or BREAKING CHANGE footerSemVer 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

ExcuseReality
"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

  • Branching strategy defined (Trunk-Based, GitHub Flow, or Git Flow)
  • Default branch is main
  • Branch naming conventions documented
  • Conventional Commits configured (commitlint)
  • Pre-commit hooks configured
  • Merge strategy defined (squash or FF-only)
  • CONTRIBUTING.md updated

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free