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 the git_strategy: block of .agents/project.yaml 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 six operations

Every git-flow-master invocation maps to one (or a sequence) of these six 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 1b — Reconcile the declared policy against the host (once per session)

git_strategy.policy.* in .agents/project.yaml records what the team DECIDED. The hosting platform records what is actually ENFORCED. These drift, and the drift only surfaces at the worst moment: a merge that stalls on an approval nobody expected, or a "protected" branch that was never protected.

Run this ONCE per session, at the first push / PR / merge intent (not on read-only operations), and cache the result for the rest of the session.

Run the tool; do not perform the queries by hand:

bun run git:policy verify          # read-only; exit 1 on drift
bun run git:policy verify --stamp  # same, and records the reconciliation when clean

It queries BOTH GitHub protection mechanisms for every branch in git_strategy.branches / protected, compares the union against the declared policy, and prints each divergence as declared vs enforced. The strategy-to-ruleset mapping and what the tool deliberately does not manage: references/ruleset-parity.md.

Why a tool rather than a checklist. This reconciliation existed only as prose in the sibling boilerplate and kept not happening — that repo shipped require_pr_reviews: 0 against a host demanding one approval plus a code-owner review, and it surfaced months later as a refused merge. This repo had the identical divergence. A script performs every query on every run; a procedure performs the ones the reader remembered.

Facts that still bind you when reading its output:

• A 404 from branches/{b}/protection does NOT mean the branch is unprotected. A repo governed by rulesets returns 404 there while enforcing PR requirements, approvals, signed commits and non-fast-forward bans through rules/branches/{b}. Stopping at the classic endpoint produces a confident "unprotected" reading on a branch that requires a reviewed pull request.
• A push that succeeds is not evidence of an absent rule. Org owners and anyone on the ruleset bypass list push through while the rule still binds everyone else. When a push prints Changes must be made through a pull request, that was a BYPASS: report it as one, never as permission. With git_strategy.policy.admin_bypass: true (or the divergence listed in git_strategy.policy.accepted_divergences), the Bypassed rule violations remote line is the DOCUMENTED norm — mention it in the report as expected, do NOT treat it as an anomaly, do NOT stall asking for confirmation, and NEVER open a PR to "satisfy" the rule.
• require_code_owner_review: true with no CODEOWNERS file is unsatisfiable, not strict. Nobody outside the bypass list can clear it, so every merge becomes a bypass.

On drift, report — never auto-correct. Three legitimate resolutions: update .agents/project.yaml to match the host, change the host (bun run git:policy apply, dry run until --yes), or accept the divergence and record WHY in this project's own AGENTS.md. Editing either side needs the user's choice.

Step 2 — Resolve the branching strategy

The skill supports eight 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. git_strategy: block in .agents/project.yaml — read it. If git_strategy.strategy is non-null (one of the eight slugs), it + git_strategy.branches (production / integration / ephemeral_pattern) + git_strategy.decisions (promote_method / feature_merge / hotfix_policy) ARE the persisted decision — use them. Each git_strategy.decisions.* field whose value is NOT n/a/empty means Strategy Setup SKIPS that question on re-run (idempotent — idempotency is keyed off the git_strategy.decisions.* fields, not markers). Inherited-template guard: the boilerplate ships the block FILLED (strategy: solo-main) and a scaffolded project INHERITS it verbatim (the scaffolder only patches project.project_name / project.project_key). So a non-null git_strategy.strategy is only authoritative when the project is actually onboarded. Read project.project_name in the SAME file: if git_strategy.strategy is non-null BUT project.project_name is null, the block was INHERITED from the template (not chosen for THIS project) — treat the strategy as UNCONFIRMED and route to the Bootstrap trigger's inherited case (it still operates under the inherited strategy if the offer is declined). If project.project_name is set, the block is confirmed → use it normally, no nudge.
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 options with one-line descriptions; mirror their language. Do NOT pick silently. On a test-automation repo (KATA / Playwright / /test-automation), surface sdet as the recommended option. sdet is opt-in only — never inferred silently from layout; a live test/<module>-suite trunk with test/{KEY}-* PRs targeting it confirms an already-active sdet suite.

Persist the decision

Once resolved (whether by detection or by asking), write/update the git_strategy: block in place inside .agents/project.yaml (preserve the rest of the file — it holds project identity, env config, etc.; create the block if it is missing). NEVER write a separate file. It is the single source of truth. At minimum the first five operations need git_strategy.strategy + git_strategy.branches; the full schema (with git_strategy.decisions, git_strategy.protected, git_strategy.policy, git_strategy.branch_prefixes, git_strategy.meta) is populated by Strategy Setup (3.6).

# .agents/project.yaml — git_strategy block (only the fields that apply shown)
git_strategy:
  strategy: main-integration
  branches:
    production: main
    integration: staging
    ephemeral_pattern: null

The block is the source of truth; its git_strategy.description field is the one-paragraph human summary. The user can edit it; the next invocation re-reads it.

AGENTS.md's ## Git Strategy section is just a pointer to .agents/project.yaml (git_strategy: block) — NEVER write strategy policy or branch decisions into AGENTS.md.

If the strategy uses an integration branch with a non-default name (anything other than staging), record it under git_strategy.branches.integration so commits don't have to re-detect.

Block fields and idempotent setup. git_strategy.strategy + git_strategy.branches are the minimum the first five operations need. Strategy Setup (3.6) additionally populates the three git_strategy.decisions.* fields (promote_method, feature_merge, hotfix_policy) plus the git_strategy.policy.* fields (Q4); these gate questionnaire skips. On any later invocation, detection reads the block and treats each git_strategy.decisions.* field that is NOT n/a/empty as an already-answered questionnaire question — Strategy Setup re-run only asks the questions whose git_strategy.decisions.* fields are still n/a, and never recreates a branch that already exists.

Bootstrap trigger — offer setup on a fresh repo (never auto-run)

At the top of any git intent, after Step 1 (repo state) and Step 2 detection have run, evaluate the gate — it fires on EITHER of two conditions:

(a) Unset — git_strategy.strategy in .agents/project.yaml is null (or the git_strategy: block is absent) AND the repo looks fresh — any of: only main/master exists locally and on the remote; fewer than ~3 commits; or a boilerplate sentinel file is present (e.g. .agents/project.yaml).

(b) Inherited — git_strategy.strategy is non-null BUT project.project_name (same file) is null. The block was INHERITED from the boilerplate template (this project has not been onboarded yet) — it was NOT chosen for THIS project. Treat it as UNCONFIRMED.

If EITHER condition is true, OFFER (do not auto-execute, do not silently pick a strategy), using the matching prompt:

(unset case (a)) "No git strategy is set up yet. Want me to run Strategy Setup — pick the flow, create the branches it needs, and write the git_strategy: block in .agents/project.yaml? (Y/N)"

(inherited case (b)) "This project's git_strategy looks inherited from the boilerplate (project not onboarded yet — project.project_name is null). Want to run Strategy Setup to define this project's own flow? (Y/N)"

Rules:

• Offer once per session, then cache the answer. Do not re-prompt every git intent in the same session.
• Never auto-run. A No proceeds with the requested operation under the detected (case a) or inherited (case b) strategy without writing the block.
• A Yes enters Strategy Setup (3.6) before continuing with the original git intent.
• The boilerplate ships .agents/project.yaml with the git_strategy: block FILLED (strategy: solo-main); a scaffolded project INHERITS it verbatim (the scaffolder patches only project.project_name / project.project_key, and the updater freezes the file via bootstrapOnlyPaths). So the unset case (a) and the inherited case (b) are the two ways a project reaches a real git intent without having confirmed its own flow → the offer fires on first real use — by design (template-trap guard). If project.project_name is set, the strategy is confirmed and NEITHER case fires.

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 — read git_strategy.branch_prefixes in .agents/project.yaml (naming_with_key / naming_without_key / precedence); the patterns below are the shipped defaults, used verbatim when the block is absent:

• 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.
• sdet → test/{KEY}-* ticket branches + Plus Branches (docs/*/chore/*/fix/*) branch off the ephemeral integration trunk test/<module>-suite; the trunk itself is cut from main on demand when a suite begins. Never stack a ticket on the previous ticket branch. See references/sdet-integration-trunk.md.

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 AGENTS.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 branches per strategy — the branches the policy gate below guards (union with git_strategy.protected):

• 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.
• sdet → main is protected (only the final suite PR lands, reviewed + green CI). The integration trunk is protected-by-convention but its ticket/Plus PRs are self-merged by the maintainer with no ruleset friction.

Policy gate (consult git_strategy.policy.direct_push_to_protected before any direct push to a protected branch):

For confirm, ask: "You are about to push directly to the protected branch {branch} in a {strategy} flow. Confirm?" Wait for explicit yes. Missing or null git_strategy block (fresh scaffold, project never onboarded) → behave as confirm: the safe default is to ask, never to assume standing authorization.

Admin bypass (only when contemplating skipping PR/protection for an urgent change): only when git_strategy.policy.admin_bypass: true may the skill OFFER a bypass — and it MUST re-confirm at runtime BOTH: (a) the operator actually holds admin rights on the repo (ASK — the skill cannot know the GitHub role; admin_bypass is a team POLICY intent, not a capability check), AND (b) the irreversible action itself. If git_strategy.policy.admin_bypass: false, NEVER offer a bypass regardless of the operator's role.

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 AGENTS.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 .agents/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.

3.6 Strategy Setup

The first five operations adapt to a strategy that already exists. Strategy Setup is the operation that establishes one: it resolves (or asks) the strategy, captures the merge + hotfix + protection-policy decisions the other operations depend on, materializes the long-lived branches the strategy needs, and writes the git_strategy: block in .agents/project.yaml. It is the only operation that creates branches and writes the strategy definition.

When it runs

• Explicit: the user asks — "set up our git strategy", "bootstrap branching", "configura el flujo de git", "materialize the flow".
• Bootstrap offer (see "Bootstrap trigger" below): a git intent arrives and EITHER git_strategy.strategy is null (or the block is absent) with a fresh-looking repo, OR git_strategy.strategy is non-null but project.project_name is null (inherited template — not onboarded). The skill OFFERS to run setup. It never auto-runs.

Six-step flow (mechanics live in references/strategy-setup.md — do not inline them here):

1. Read repo state — Step 1 (already always runs).
2. Resolve strategy — reuse Step 2 detection. If still undetermined, ask the 7-option question (one slug out).
3. Decision questionnaire — run Q1/Q2/Q3/Q4 below, capturing merge methods + hotfix policy + protection policy. SKIP any question that does not apply to the resolved strategy, and SKIP any question whose decision field is already populated (idempotent re-run — see Step 2 extension). Q4 applies to ALL strategies.
4. Materialize — conditional on the resolved strategy: create an integration branch ONLY if the strategy needs one and it is missing; ff-sync the integration/production pair if one is a pure ancestor of the other (NEVER --force); set up local tracking. Full materialization table + sync mechanics in references/strategy-setup.md.
5. Persist — write the git_strategy: block in .agents/project.yaml (the structured source of truth) with the fields that apply to the resolved strategy, preserving the rest of the file. NEVER write a separate file. Do NOT render a prose runbook anywhere — the operational HOW lives in this skill's references (branching-strategies.md catalogue + sdet-integration-trunk.md), read on demand. Per-strategy field values in references/branching-strategies.md → "git_strategy field rules (per strategy)".
6. Report — branches created/synced, decisions captured, block location.

Decision questionnaire (defaults first; each gated on the resolved strategy)

Q1/Q2/Q3 defaults are what the main-integration worked example chose; they are DEFAULTS, not hardcoded. The user can override any of them. Single-branch strategies (solo-main, github-flow, trunk-based) answer NONE of Q1/Q2/Q3 — they have no integration branch and no distinct production branch. Q4 applies to every strategy (even single-branch ones — a solo main is still protected) and writes git_strategy.policy.*; per-strategy Q4 defaults live in references/branching-strategies.md → "git_strategy field rules (per strategy)".

The git_strategy block fields (write only the ones that apply; leave decisions.* at n/a for any decision the strategy doesn't use):

git_strategy:
  strategy: VALUE                 # one of the eight slugs
  branches:
    integration: NAME             # or null
  decisions:
    promote_method: ff-only|merge-commit|squash|n/a
    feature_merge: merge-commit|squash|rebase-merge|n/a
    hotfix_policy: branch-off-prod-backmerge|via-integration|none|n/a
  policy:                                          # Q4 — applies to ALL strategies
    direct_push_to_protected: forbidden|confirm|allowed
    admin_bypass: true|false                       # team POLICY intent, not enforcement
    require_pr_reviews: null|0|N

Non-negotiables

• Never --force (not --force-with-lease either) during a setup sync. Sync only on a true fast-forward; if the integration/production pair has diverged both ways → STOP and hand to conflict resolution (3.5).
• Confirm before any push to a protected branch. A setup ff-sync push is still a push to a protected branch — ask first.
• Propose, don't auto-execute branch creation. Show the plan (which branch, off what, why) and wait for OK before git checkout -b / git branch.
• No AI attribution in any commit the setup makes (see this skill's "Critical rules" section and the project AGENTS.md).

Pointers (do not inline mechanics here)

• references/strategy-setup.md — full questionnaire detail (Q1-Q4), the per-strategy materialization table, sync mechanics, persist sequence, report format.
• references/branching-strategies.md → "git_strategy field rules (per strategy)" — the per-strategy field values written into the git_strategy: block of .agents/project.yaml (strategy / branches / decisions / policy).

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. 1b. policy: records INTENT, not enforcement. Reconcile it by RUNNING bun run git:policy verify (Step 1b) at the first push / PR / merge intent, then --stamp when clean. Never perform the protection queries by hand, and never state what the remote requires from a declared reading. git:policy apply is a dry run until --yes, and refuses to remove a guard, lower the approval bar, turn off code-owner review, or widen the merge methods unless --allow-loosening is passed for that specific give-up. 1c. strategy: solo-main is the shipped DEFAULT, not evidence of a decision. meta.strategy_source tells them apart: inherited means nobody chose. On a repo whose project.project_name is set and whose strategy_source is still inherited, OFFER Strategy Setup and say what the default costs (no integration branch, no promotion path, no review gate)

…(truncated)