End-to-end Git operator for any branching strategy. Auto-detects the project's strategy (solo-main, main+integration, enterprise multi-branch, trunk-based, GitFlow, GitHub Flow, GitLab Flow) from .git config, branches, and an CLAUDE.md marker, then adapts every commit, branch, push, PR, conflict-fix, and chained-PR action to that strategy. Use this skill whenever the user wants to: create a branch (`crear branch`, `new feature branch`, `start work on UPEX-123`), commit changes (`commit this`, `commitear esto`, `make a commit`, `commit and push`), push code (`push`, `push to main`, `push to staging`, `subir cambios`), open a pull request (`create PR`, `open PR`, `abrir PR`, `crear pull request`, `gh pr create`), fix merge conflicts (`fix conflict`, `resolver conflicto`, `merge conflict`, `rebase conflict`, `push rejected`), plan stacked or chained PRs (`stack of PRs`, `chained PRs`, `split this PR`, `PR demasiado grande`), or pick / change a branching strategy (`git flow`, `git strategy`, `branching strategy`,
End-to-end Git operator for any branching strategy. Auto-detects the project's strategy (solo-main, main+integration, enterprise multi-branch, trunk-based, GitFlow, GitHub Flow, GitLab Flow) from .git config, branches, and an CLAUDE.md marker, then adapts every commit, branch, push, PR, conflict-fix, and chained-PR action to that strategy. Use this skill whenever the user wants to: create a branch (`crear branch`, `new feature branch`, `start work on UPEX-123`), commit changes (`commit this`, `commitear esto`, `make a commit`, `commit and push`), push code (`push`, `push to main`, `push to staging`, `subir cambios`), open a pull request (`create PR`, `open PR`, `abrir PR`, `crear pull request`, `gh pr create`), fix merge conflicts (`fix conflict`, `resolver conflicto`, `merge conflict`, `rebase conflict`, `push rejected`), plan stacked or chained PRs (`stack of PRs`, `chained PRs`, `split this PR`, `PR demasiado grande`), or pick / change a branching strategy (`git flow`, `git strategy`, `branching strategy`, `which git flow do we use`). Trigger even when the user does not say `git-flow-master` literally — if the work is git-or-PR-shaped, this is the right tool. Do NOT use for: testing tickets (use /sprint-testing), authoring test cases in TMS (use /test-documentation), writing automated tests (use /test-automation), running regression suites (use /regression-testing), or general code editing — git-flow-master operates strictly on the version-control layer.
license
MIT
compatibility
["claude-code","opencode"]
phase
implementation
complementary_categories
["vcs"]
Git Flow Master — One Skill for Branches, Commits, Pushes, PRs, and Conflicts
This skill is the project's single entry point for everything that happens on the version-control layer: creating branches, writing commits, pushing safely, opening pull requests, resolving conflicts, and planning chained / stacked PRs when a change outgrows the review budget.
It does not assume one branching model. The project may run on main only, on main + staging, on a multi-branch enterprise layout, or on any of the well-known flows (trunk-based, GitFlow, GitHub Flow, GitLab Flow). The skill detects which one is active and adapts every command accordingly. The detection is sticky: once resolved, the strategy is recorded in CLAUDE.md so future invocations skip the prompt.
When to use
Trigger on any of these intents — even without literal keywords:
"I want to start work on UPEX-123" → branch creation
"commit and push", "subir cambios", "push to main" → commit + push flow
"abrí un PR contra staging" → PR creation
"tengo conflictos al hacer pull" → conflict resolution
"este PR va a quedar enorme" → chained-PR planning hand-off
"qué estrategia de git usamos en este repo" → strategy detection / persistence
"el push fue rechazado" → diagnostic + recovery flow
If the user is asking about testing a ticket, authoring test cases, writing automated tests, or running regression suites — that is not this skill. Hand back to /sprint-testing, /test-documentation, /test-automation, or /regression-testing.
The five operations
Every git-flow-master invocation maps to one (or a sequence) of these five operations. Operation choice is driven by the user's request; strategy resolution shapes how each operation runs.
Op
Trigger phrases (examples)
Skill behaviour
Branch
"create branch", "new feature branch", "start UPEX-123"
Resolve strategy → propose name with prefix + issue key → wait for OK → checkout
Commit
"commit this", "commit and push", "make atomic commits"
Group by responsibility → propose conventional commits → wait for OK → execute one-by-one
Push
"push", "push to main", "subir cambios"
Diagnose upstream → confirm if pushing to a protected branch → never --force without explicit user opt-in
PR
"create PR", "abrir PR", "gh pr create"
Pick base branch from strategy → render body inline → ask labels/reviewers → call gh pr create
Conflict
"fix conflict", "rebase failed", "push rejected"
Diagnose first (see references/conflict-resolution.md) → present options → guide resolution → verify clean state
When the operation is ambiguous (user just says "git-flow-master" or "let's do the git stuff"), report the current repo state (Step 1 below) and ask what they need.
Step 1 — Always: read the repo state
Run these silently every invocation. Do not act until the picture is clear:
git status
git branch --show-current
git branch -a
git diff --stat
git log --oneline -5
git fetch origin
git status -sb
git remote -v
Summarise to the user:
Current branch.
Dirty / clean working tree (staged / unstaged / untracked counts).
Upstream status (no upstream, up-to-date, diverged).
Remote name(s) — most repos have one (origin); some have a fork + upstream.
This summary is cheap, prevents 90% of mistakes, and is the input to every subsequent decision.
Step 2 — Resolve the branching strategy
The skill supports seven strategies (see references/branching-strategies.md for the full catalogue, detection signals, and trade-offs):
Strategy
One-line description
solo-main
Single long-lived branch (main). All work lands directly. Best for solo projects, scratch repos, prototypes.
main-integration
main (production) + a single integration branch (staging / dev / develop). Features merge to integration, release-promote to main.
enterprise
main + integration + many short-lived feature/*, fix/*, release/*, hotfix/* branches. Adds environment branches when needed.
trunk-based
Trunk (main) is the only long-lived branch. Short-lived feature branches (<1 day) merge fast, behind feature flags. CI gate is non-negotiable.
gitflow
Vincent Driessen's classic. main (releases) + develop (integration) + feature/* + release/* + hotfix/*. Heavyweight; mostly legacy.
github-flow
main always deployable. feature/* branches → PR → merge → deploy. No staging/develop branch.
gitlab-flow
GitHub Flow + environment branches (pre-production, production) to model deployment promotion.
Detection algorithm
Apply in order; stop at the first definitive answer:
Marker in CLAUDE.md — search for <!-- git-flow-master:strategy:VALUE --> where VALUE is one of the seven slugs. If found, use it. This is the persisted decision.
Single-branch heuristic — git branch -a shows only main (or master) and no integration branch in the remote → solo-main.
Two-branch heuristic — exactly main (or master) + one of {staging, dev, develop, integration} exists upstream → main-integration (record the integration branch name).
Multi-branch heuristic — main + integration + active feature/* or release/* branches in git branch -a → enterprise.
Project hints — look for .gitlab-ci.yml (suggests gitlab-flow), release/* and hotfix/* long-lived branches (suggests gitflow).
Fallback — ask the user. Show the seven options with one-line descriptions; mirror their language. Do NOT pick silently.
Persist the decision
Once resolved (whether by detection or by asking), write the marker to CLAUDE.md:
If a ## Git Strategy section exists, update the marker line in place.
If not, append a new section near the existing ## Git Workflow section:
## Git Strategy
<!-- git-flow-master:strategy:main-integration -->
<!-- git-flow-master:integration-branch:staging -->
This project uses the `main-integration` flow: feature branches merge to `staging`; `staging` merges to `main` only on release.
The marker is the source of truth. The prose is for humans. The user can edit either; the next invocation re-reads the marker.
If the strategy uses an integration branch with a non-default name (anything other than staging), record it as a second marker <!-- git-flow-master:integration-branch:NAME --> so commits don't have to re-detect.
Step 3 — Operation-specific runbooks
3.1 Branch creation
Decide the prefix from the dominant change. Use this fixed vocabulary (mixed-changes precedence: feat > fix > refactor > test > docs > chore):
Prefix
When the dominant change is…
feat/
new feature or capability
fix/
bug fix
test/
adding or updating automated tests (no product code)
docs/
docs only
refactor/
code change without behaviour change
chore/
tooling, deps, housekeeping
For enterprise and gitflow strategies, also consider release/X.Y.Z and hotfix/X.Y.Z when appropriate.
In a QA repo most work lands as test/, fix/, or chore/ branches. Feature branches (feat/) are rare here — a feat/ in this repo usually means a change to the test framework itself (new fixture, new Page component layer, new reporter).
Issue key extraction (in order):
Current branch name regex: (?:feat|feature|fix|test|docs|refactor|chore)/([A-Z]+-\d+)-.
$ARGUMENTS for [A-Z]+-\d+.
Ask the user once: "Is there an issue key for this work?" — accept "no" gracefully.
Branch name format:
With key: {prefix}/{ISSUE-KEY}-{kebab-slug} (e.g. test/UPEX-123-bulk-assign-coverage).
Without key: {prefix}/{kebab-slug} (e.g. refactor/split-kata-fixtures).
Test data and fixtures stay with the tests they support. If a test commit ships its own fixture, they belong in the same commit, not in a separate chore: commit.
Breaking changes: append ! after type/scope and add BREAKING CHANGE: footer.
Vocabulary: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert (full list in references/conventional-commits.md).
Hard rules (apply on every commit):
One commit = one responsibility. Never bundle unrelated changes.
Never git add -A or git add . — list explicit paths to avoid leaking secrets (.env, credentials) or unrelated work.
No AI attribution. No Generated with Claude Code, no Co-Authored-By: Claude, no equivalent line. Commits look human-authored. (Critical Reminder #3 in CLAUDE.md.)
If a pre-commit hook fails, stop, fix the underlying issue, create a NEW commit. Never --amend a commit the hook rejected — --amend operates on the previous commit, which destroys context.
Present all proposed commits as one block. Wait for OK / modify / reject before executing.
3.3 Push
Push command depends on Step 1 output:
No upstream → git push -u origin {branch}.
Upstream behind → git push.
Upstream diverged → stop. Do not force. Hand to conflict resolution (3.5).
Protected-branch confirmation — before pushing to any branch the strategy treats as protected, ask explicitly:
solo-main → main is protected.
main-integration → both main and the integration branch are protected.
gitflow → main and develop are protected.
github-flow / trunk-based → main is protected.
enterprise → main, integration, and any release/* are protected.
Ask: "You are about to push directly to the protected branch {branch} in a {strategy} flow. Confirm?" Wait for explicit yes.
Never pass --force, --force-with-lease, --no-verify, or any history-rewriting flag unless the user explicitly requests it AND the branch is unshared. Document the request in the conversation. (Critical Reminder #6 in CLAUDE.md: never rewrite pushed history.)
3.4 Pull request
Base branch picks itself from the strategy:
Strategy
Default PR base
solo-main, github-flow, trunk-based
main
main-integration, gitlab-flow
integration branch (e.g. staging)
enterprise
integration branch; hotfix/* → main
gitflow
feature/* → develop; hotfix/* → main; release/* → main (and back-merge to develop)
The user can override with --base X in arguments. If overridden, surface it in the confirmation: "PR will target {base} instead of the strategy default {default}."
Title format: {type}({ISSUE-KEY}): {description} — under 70 chars. Without a key: {type}: {description}.
Body — render inline (no template file to read) using the structure in references/pr-templating.md. Substitute placeholders the skill can fill (<<ISSUE_KEY>>, <<SUMMARY>>, <<CHANGES>>, <<TEST_PLAN>>, <<RISK>>). Leave any unfilled placeholder visible so the author can edit it before posting — do not silently drop sections.
For test/* branches in this repo, the PR body should use the structure in references/pr-test-automation.md (project-local template tuned for KATA test-automation PRs). For non-test/* branches use the generic structure in references/pr-templating.md.
Write the rendered body to a tempfile (e.g. $(mktemp)) and pass it via gh pr create --body-file to avoid escaping issues.
Reviewers, labels, draft — see references/pr-templating.md. Never hardcode labels the repo may not have configured; verify with gh label list if uncertain.
Stop at PR creation. Merging is the user's explicit next step. Never auto-merge. Surface: "Review the PR. Once approved, merge via the GitHub UI or run gh pr merge {number} --squash --delete-branch."
Optional pre-PR adversarial gate — when the diff exceeds the 400-line cognitive review budget OR touches shared scaffolding (KATA base classes, fixtures, OpenAPI schemas), surface /judgment-day as an optional pre-PR review: "Diff is large / touches shared scaffolding. Want to run /judgment-day before opening the PR?". Two blind judges review the diff in parallel; only approves when both agree. See .claude/skills/judgment-day/SKILL.md. Never invoked automatically — user opts in.
3.5 Conflict resolution
Conflicts are diagnosed before they are resolved. The user is rarely in a hurry; a wrong fix here costs hours.
Run git status, git diff --check, and inspect .git/MERGE_HEAD / REBASE_HEAD to classify the situation, then follow the matching playbook in references/conflict-resolution.md:
Merge conflict (content)
Merge conflict (rename / delete)
Rebase conflict
Push rejected (diverged)
Detached HEAD
Stash apply conflict
Unrelated histories
Pre-commit hook rejected the commit
For every type, the playbook follows the same shape:
Explain what happened (root cause, in the user's language).
Present options ranked by safety. Never pick destructive options (force push, hard reset, --abort of an unfinished merge with uncommitted work) silently.
Guide the resolution step by step.
Verify (git status, git log --oneline -3).
Teach prevention (one short note on how to avoid this next time).
When in doubt, abort safely (git merge --abort, git rebase --abort, git cherry-pick --abort) rather than push forward. Aborting always wins over guessing.
Step 4 — Chained / stacked PRs (when a change outgrows the budget)
When a planned change estimates > 400 changed lines (additions + deletions), the work should be split. The 400-line cognitive review budget is borrowed from industry research (SmartBear, Cisco code-review studies); above it, defect detection drops sharply.
There are three options:
stacked-to-main — 2 to 4 small PRs, each branched off the strategy's default base. PRs depend on previous merges. The base always works between merges. Best for linearly decomposable work.
feature-branch-chain — one long-lived integration branch; child PRs merge into it; one final PR merges it to the strategy's default base. Best for changes with shared scaffolding (new types, new schemas) that would break partial merges.
size-exception — for mechanical diffs (mass renames, formatter sweeps, generated code, vendor updates). Requires explicit user override and a Why size-exception: line in the PR body.
Walk the chained-PR decision tree inline (see references/branching-strategies.md § Chained-PR decision tree). The decision picks one of: single-pr, stacked-to-main, feature-branch-chain, size-exception. Once decided, execute the resulting branch plan from this skill.
The branch plan that comes out of the decision is the contract for execution. If the implementation diverges (the actual diff is larger than the estimate), re-invoke the decision — do not silently up-budget the existing strategy.
Variables consumed
{{PROJECT_KEY}} — issue prefix for branch naming (e.g. UPEX-123). Resolves from .agents/project.yaml.
{{ATLASSIAN_URL}} — base URL for the Traceability section in PR bodies. Resolves from .agents/project.yaml:atlassian_url.
Any project missing .agents/project.yaml will lack these. Fall back to a generic {prefix}/{slug} and surface a one-line warning: clone the full boilerplate (the foundation files ship with the repo).
Hand-offs to other skills
Situation
Hand off to
Strategic split of a large change
Step 4 (inline decision tree in this skill)
In-sprint manual QA per ticket
/sprint-testing
Test case authoring + ROI in TMS
/test-documentation
KATA-compliant automated test authoring
/test-automation
Regression suite execution + GO/NO-GO
/regression-testing
Atlassian (Jira) operations triggered by a commit / PR
/acli
First-time orientation
/agentic-qa-onboard
Critical rules — apply every invocation
Diagnose before acting. Step 1 always runs. Never assume repo state.
One commit = one responsibility. Never bundle unrelated changes.
No AI attribution in commits or PR bodies. Commits look human-authored. (Critical Reminder #3 in CLAUDE.md.)
Confirm before pushing to any protected branch. Strategy-driven; see Step 3.3. (Critical Reminder #5 in CLAUDE.md.)
Never force-push, never rewrite pushed history, never --no-verify unless the user explicitly authorises it AND the branch is unshared. (Critical Reminder #6 in CLAUDE.md.)
No git add -A / git add . — always list explicit paths.
Show proposed commits / branches / PR body and wait for OK before executing. The user can accept, modify, or reject any item.
gh CLI is the PR transport. If gh is missing or unauthenticated (gh auth status fails), stop and surface the blocker. Do not pretend a PR was opened.
PRs stop at creation. Merging is the user's explicit next step.
Strategy is sticky. Once resolved, persist in CLAUDE.md. The next invocation re-reads the marker rather than asking again.
Language: artifacts (commits, branches, PR bodies, CLAUDE.md sections) in English. Mirror the user's language only in conversation.
Pre-flight checklist (run before exiting any operation)
Step 1 ran and the repo state was reported.
Strategy resolved (detected from marker, inferred from layout, or asked) and persisted to CLAUDE.md if newly chosen.
Branch / commit / push / PR / conflict operation followed the runbook for that strategy.
Each commit is atomic, conventional, and free of AI attribution.
No git add -A / --force / --no-verify used unless explicitly authorised.
PR (if created) has Title <70 chars, body with Summary / Changes / Test Plan / Traceability / Risk, base branch matches strategy.
PR URL returned to the user; no merge attempted.
Conflicts (if any) are fully resolved AND verified (git status clean, git log sensible).
Reference files
File
When to read
references/branching-strategies.md
Full catalogue of the 7 strategies + detection signals + trade-offs + chained-PR decision tree. Read when resolving strategy or planning a chain.
references/conventional-commits.md
Full type vocabulary, scope rules, breaking-change syntax, mixed-changes precedence. Read when proposing commits.
references/pr-templating.md
PR body template, placeholder rules, label / reviewer / draft conventions, multi-strategy base-branch table. Read when opening a PR.
