Git Flow Master

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.

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).
• Unpushed / unpulled commits (ahead / behind upstream).
• 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):

Detection algorithm

Apply in order; stop at the first definitive answer:

1. 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.
2. Single-branch heuristic — git branch -a shows only main (or master) and no integration branch in the remote → solo-main.
3. Two-branch heuristic — exactly main (or master) + one of {staging, dev, develop, integration} exists upstream → main-integration (record the integration branch name).
4. Multi-branch heuristic — main + integration + active feature/* or release/* branches in git branch -a → enterprise.
5. Project hints — look for .gitlab-ci.yml (suggests gitlab-flow), release/* and hotfix/* long-lived branches (suggests gitflow).
6. 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):

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):

1. Current branch name regex: (?:feat|feature|fix|test|docs|refactor|chore)/([A-Z]+-\d+)-.
2. $ARGUMENTS for [A-Z]+-\d+.
3. 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).
• Keep slugs lowercase, hyphen-separated, ≤50 chars.

Strategy-specific source branch:

• solo-main, github-flow, trunk-based → branch off main.
• main-integration, gitlab-flow → branch off the integration branch (staging / dev / equivalent).
• enterprise → branch off the integration branch unless it is a hotfix/*, which branches off main.
• gitflow → feature/* branches off develop; hotfix/* off main; release/* off develop.

Always propose the name and ask for OK before git checkout -b. Never create silently.

3.2 Commits

Group changes by responsibility, not by file type:

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.

Conventional commit format:

• With issue key: {type}({ISSUE-KEY}): {description} (e.g. test(UPEX-123): cover bulk-assign empty states).
• Without key: {type}: {description}.
• 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:

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.

Final command shape:

gh pr create \
  --title "{title}" \
  --body-file {tmpfile} \
  --base {base} \
  [--reviewer {users}] \
  [--label {labels}] \
  [--draft]

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:

1. Explain what happened (root cause, in the user's language).
2. Present options ranked by safety. Never pick destructive options (force push, hard reset, --abort of an unfinished merge with uncommitted work) silently.
3. Guide the resolution step by step.
4. Verify (git status, git log --oneline -3).
5. 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:

1. 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.
2. 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.
3. 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

Critical rules — apply every invocation

1. Diagnose before acting. Step 1 always runs. Never assume repo state.
2. One commit = one responsibility. Never bundle unrelated changes.
3. No AI attribution in commits or PR bodies. Commits look human-authored. (Critical Reminder #3 in CLAUDE.md.)
4. Confirm before pushing to any protected branch. Strategy-driven; see Step 3.3. (Critical Reminder #5 in CLAUDE.md.)
5. 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.)
6. No git add -A / git add . — always list explicit paths.
7. Show proposed commits / branches / PR body and wait for OK before executing. The user can accept, modify, or reject any item.
8. 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.
9. PRs stop at creation. Merging is the user's explicit next step.
10. Strategy is sticky. Once resolved, persist in CLAUDE.md. The next invocation re-reads the marker rather than asking again.
11. 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

Read references on demand — do not load them all upfront. Each file is self-contained.