name: platform-git-release-workflow description: Apply the platform blueprint git and release policy. Use when creating branches, preparing PRs, choosing merge strategy, planning releases or hotfixes, tagging versions, or handling contract-version compatibility across repos.

Platform Git And Release Workflow

Use this skill when work touches git flow, release policy, or versioning decisions.

Default Workflow

1. Work on a short-lived branch.
2. Merge into main only through a PR.
3. Keep main protected and never push to it directly.
4. Never create commits on local main; branch before the first commit.
5. Detect the repository's allowed merge methods before merging the PR.
6. Use an allowed merge method on main, preferring squash when the repo policy permits it.
7. Treat release tags as the production promotion boundary.

Branch Policy

• Protected branch:
  • main
• Local working rule:
  • main must stay aligned with origin/main
  • create or switch to a short-lived branch before making the first commit
• Short-lived branches:
  • feat/<short-description>
  • fix/<short-description>
  • chore/<short-description>
  • hotfix/<short-description>

PR Policy

• every change reaches main via PR
• PR must be human-reviewed and approved
• required checks must pass before merge
• do not merge the PR yourself unless the task explicitly requires merge handling

Baseline required checks:

• lint
• tests
• code quality gates
• security and secret scans
• contract checks where applicable

Merge Strategy

• Do not assume every repo allows the same merge method.
• Determine the allowed merge strategy before attempting merge.
  • Prefer repository metadata or existing repo policy docs when available.
  • If policy is not documented locally, inspect the PR or repo settings through the available GitHub tooling before choosing a merge command.
• Prefer squash merge on main when the repository allows it.
• If squash merge is not allowed, use another allowed strategy instead of retrying blindly with the same command.

Use this to keep history clean, make rollback easier by PR unit, and avoid failed merge attempts caused by repo-specific restrictions.

Versioning

• version independently per repository
• use SemVer: MAJOR.MINOR.PATCH
• use plain git tags:
  • vX.Y.Z

SemVer meaning:

• PATCH:
  • fixes and internal changes with no contract break
• MINOR:
  • backward-compatible additive behavior
• MAJOR:
  • breaking behavior or contract changes

Release Promotion

• merge to main:
  • auto-deploy to rc
• promote to prod:
  • create release tag vX.Y.Z
  • run prod promotion workflow with required approvals and smoke gates

Hotfix Flow

• use hotfix/*
• still require PR, checks, and human approval
• release a new patch tag after merge

Working Tree And Cleanup Rule

• leave the repository worktree clean when finished
• remove temporary files and generated scratch artifacts unless they are intended outputs
• do not leave abandoned local branches behind

After squash-merged work:

• switch to main
• pull latest origin/main
• delete the local feature branch if it still exists
• verify the worktree is clean

After any merged work:

• verify the PR is actually merged before cleaning up
• delete the remote branch when the hosting workflow allows it
• if local main was behind, fast-forward it before continuing more work

Contract Compatibility Rule

For platform-contracts:

• require buf lint
• require buf breaking
• do not make breaking changes in place
• create a new major namespace/package version for breaking changes
• keep generated TypeScript package version aligned to the release tag

Escalate to Planning Docs

Update platform planning docs or ADRs when the workflow or release policy itself changes, not just when you are following it.