| 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
Implements: SYSP_SPEC_SKILL_BRANCHING_STRATEGY, SYSP_SPEC_SKILL_BRANCHING_PERMISSIONS, SYSP_SPEC_SKILL_BRANCHING_COMMIT_CONVENTIONS
Requirements: SYSP_REQ_SKILL_BRANCHING_CHAINED, SYSP_REQ_SKILL_BRANCHING_MAIN_PROTECTION, SYSP_REQ_SKILL_BRANCHING_NAMING
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> 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"
Workflow Sequence:
@syspilot.design creates feature/<name> from development@syspilot.implement commits code on the same branch@syspilot.verify commits validation report on the same branch@syspilot.docu commits documentation updates on the same branch- Completed feature branch is squash-merged into
development
@syspilot.release prepares on development (archive, version bump, release notes, validate, commit+push), then squash-merges development into main, tags, and back-merges main into development
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.design | feature/<name> | feature/<name> (the branch it created) |
@syspilot.setup | update/v{version} | update/v{version} (the branch it 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.design | Feature work, fixes, refactors |
update/v{version} | @syspilot.setup | Framework update branches |
main | (protected) | Release-only, always latest release |
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.
