syspilot-branching

name	syspilot.branching
description	Git branching strategy and commit conventions for syspilot. Development branch with feature branches, main = releases only. Who may create/commit to which branches. USE FOR: any git operation, branch creation, committing, pushing, merging.

Skill: Git Branching Strategy & Commit Conventions

Instructions

HARD RULE

ONLY @syspilot.release may commit to, merge to, or push to main. No exceptions.

If you are on main and need to make any change, create feature/<name> from development first. Main always equals the latest release — any non-release commit on main is a violation.

Development Branch Strategy

syspilot uses a permanent development integration branch with short-lived feature branches:

gitGraph
   commit id: "v0.2.3" tag: "v0.2.3"
   branch development
   checkout development
   commit id: "dev-start"
   branch feature/CR7
   checkout feature/CR7
   commit id: "CR7: specs"
   commit id: "CR7: implement"
   commit id: "CR7: verify"
   checkout development
   merge feature/CR7 id: "squash CR7"
   branch feature/CR8
   checkout feature/CR8
   commit id: "CR8: specs"
   commit id: "CR8: implement"
   commit id: "CR8: verify"
   checkout development
   merge feature/CR8 id: "squash CR8"
   checkout main
   merge development id: "v0.2.4" tag: "v0.2.4"

Key Properties:

• One branch per change — isolates each change for independent review
• development as integration target — all features merge here
• Squash-merge everywhere — clean history on development and main
• Main = releases only — main always equals the latest release
• Tag on main — v{version} tags mark published releases
• Back-merge after release — git checkout development && git merge main prevents conflicts on next release
• Conflict guidance — squash-merge conflicts resolve with -X theirs (development wins)

Branch Permissions

Agent	May create	May commit to
@syspilot.release	(none)	main (squash merge from development + tag); development (prep + back-merge)
@syspilot.pm	feature/<name>	feature/<name> (the branch it created)
@syspilot.installer	(none)	pre-install and final commit on the branch that was checked out when invoked (no dedicated branch created)
@syspilot.implement	(none)	current feature branch
@syspilot.verify	(none)	current feature branch
@syspilot.docu	(none)	current feature branch
All other engineers	(none)	current feature branch

development is a permanent branch that all feature branches merge into. No agent creates development — it exists permanently.

Branch Naming Conventions

Pattern	Created by	Purpose
development	(permanent)	Integration branch, all features merge here
feature/<name>	@syspilot.pm	Feature work, fixes, refactors
main	(protected)	Release-only, always latest release

Feature Branch Retention

After a feature branch is squash-merged into development and the release that includes it completes, the default policy is to retain the branch (locally and on remote) rather than delete it.

A project MAY opt into automatic deletion of merged feature branches by stating so in tailoring.md, e.g.:

Delete feature branches after they are merged into development and released — do not retain them.

Absent such an override, branches are retained indefinitely; retaining them costs nothing and preserves forensic/bisect history.

The Release Engineer applies this policy during its branch-retention workflow step.

Commit Message Conventions

Format: <type>: <short description>

Type	When to use	Example
feat	New feature or specification	feat: add branching skill RST specs
fix	Bug fix or correction	fix: correct traceability link in REQ_123
docs	Documentation changes (non-spec)	docs: update PM context with CR5 status
chore	Maintenance, cleanup, tooling	chore: archive v0.2.2 change documents
refactor	Restructuring without behavior change	refactor: reorganize index.rst toctrees

Rules:

• Type is lowercase
• Description is lowercase, no period at end
• Keep description under 72 characters
• Reference spec IDs in description when relevant

Rules

• MUST NOT commit to, merge to, or push to main — only @syspilot.release may. No exceptions.
• Commit type MUST be lowercase.
• Commit description MUST be lowercase with no trailing period.
• Commit description MUST be ≤ 72 characters.
• Reference spec IDs in description when relevant.