Git Flow Master: ramas, pushes y PRs

01 · cuándo usarla

Cada vez que el trabajo toca git

Se dispara aunque no la nombres: si el pedido tiene forma de rama, commit, push o PR, es esta skill. Las demás skills del repo le pasan la posta cuando llegan a esa capa.

Úsala cuando

Hay que mover código por git

Arrancas trabajo: "start work on PROJ-123", crear una rama.
Commitear y pushear: "commit and push", "subir cambios".
Abrir un pull request: "abre un PR contra staging".
Hay conflictos o el push fue rechazado.
Un cambio va a quedar enorme y hay que partirlo en varios PRs.
Quieres elegir o cambiar la estrategia de ramas del repo.

No la uses para

Lo que no es control de versiones

Implementar una feature: eso es /sprint-development, que llama a esta skill para el PR.
Escribir tests: eso es /unit-testing.
Refinar el backlog: eso es /product-management.
Editar código en general: la skill opera estrictamente sobre la capa de versiones.

Si el pedido es ambiguo ("hagamos lo de git"), la skill no adivina: reporta el estado del repo (Step 1) y te pregunta qué necesitas.

02 · el mapa

Dos chequeos fijos, una operación, una cadena si hace falta

El pedido elige la operación; la estrategia decide cómo corre. Los dos primeros pasos son los mismos para cualquier operación.

Siempre · antes de actuar

1Estado del repoRama actual, árbol sucio o limpio, adelante o atrás del upstream. 1bPolítica contra hostUna vez por sesión, al primer push, PR o merge. 2EstrategiaLeída de .agents/project.yaml en cada invocación.

La operación · según el pedido

BBranchPrefijo + key del issue, propuesto antes de crear. CCommitUna responsabilidad por commit, con trailers forenses. PPushCompuerta de rama protegida resuelta por variable. PRPull requestBase según la estrategia; se detiene al crearlo. XConflictDiagnóstico primero, opciones por seguridad. SStrategy SetupElegir el flujo y escribir el bloque.

Cuando el cambio crece

4PRs encadenadosÁrbol de decisión con traza; el que llama rechaza una etiqueta sola. WWorktreesTrabajo aislado o sesiones en paralelo, con su ciclo de vida.

03 · Step 2 · la estrategia de ramas

Un default no es una decisión

La estrategia se guarda en el bloque git_strategy de .agents/project.yaml y se lee en cada invocación. Nunca se infiere de un ejemplo de la skill ni de otro proyecto.

Estrategia	Forma	Rama de trabajo sale de	El PR apunta a
solo-main	Una sola rama larga, main. Todo aterriza directo.	main	main, cuando hay PR
main-integration	main + una rama de integración (staging o similar).	integración	integración
enterprise	Integración + muchas feature/, release/, hotfix/*.	integración (hotfix: main)	integración (hotfix: main)
trunk-based	Solo el trunk; ramas de menos de un día, detrás de feature flags.	main	main
gitflow	main + develop + release y hotfix.	develop (hotfix: main)	develop; release y hotfix: main
github-flow	main siempre desplegable; rama, PR, merge, deploy.	main	main
gitlab-flow	GitHub Flow + ramas de entorno (pre-production, production).	main, que es su integración	main; la promoción va por entorno

Cómo la encuentra

Primero el bloque: si git_strategy.strategy tiene valor, esa es la decisión. Si no, mira las ramas (solo main, main + una de integración, muchas feature/*) y las pistas del repo (.gitlab-ci.yml, ramas release/*). Si nada alcanza, te muestra el catálogo y eliges tú. Nunca elige en silencio.

Elegida o heredada

El boilerplate entrega el bloque lleno con solo-main. Lo que separa "este proyecto eligió solo-main" de "nadie eligió" es meta.strategy_source: inherited o chosen. Solo Strategy Setup estampa chosen.

La oferta, nunca la ejecución

Si el bloque falta en un repo nuevo, si el proyecto aún no se configuró (project.project_name vacío), o si el proyecto ya tiene nombre pero la estrategia sigue inherited, la skill ofrece Strategy Setup una vez por sesión y te dice qué cuesta el default: sin rama de integración, sin camino de promoción, sin compuerta de review propia. Un "no" sigue con la estrategia que hay, sin escribir nada.

04 · operación · Strategy Setup

Un cuestionario, ramas solo si hacen falta, un bloque escrito

Es la única operación que crea ramas largas y escribe el bloque git_strategy. Las demás operaciones se adaptan a lo que esta deja.

Pregunta	Aplica a	Opciones (default primero)	Se guarda en
Q1 · promoción integración → producción	estrategias con rama de integración	fast-forward only · merge commit · squash	decisions.promote_method
Q2 · merge de la rama de trabajo	estrategias de varias ramas	merge commit · squash · rebase + merge	decisions.feature_merge
Q3 · hotfixes	producción distinta de donde se trabaja	salir de producción + back-merge el mismo día · siempre por integración · sin política	decisions.hotfix_policy
Q4 · ramas protegidas	todas las estrategias	push directo, bypass de admin, reviews mínimas	policy.*

La IA hace

Resuelve la estrategia, salta las preguntas que no aplican o que ya tienen respuesta, propone cada rama a crear y sincroniza solo por fast-forward.

Tú decides

La estrategia, cada respuesta del cuestionario, cada rama propuesta y el push de sincronización a una rama protegida.

Sale

El bloque git_strategy escrito en su lugar dentro de .agents/project.yaml, con strategy_source: chosen y policy_source: declared.

Compuerta Nunca --force, tampoco --force-with-lease. Si integración y producción divergieron para los dos lados, la sincronización se detiene y pasa a resolución de conflictos.

El push de sincronización siempre pregunta. Setup corre antes de que ratifiques la nueva política, así que un allowed recién contestado no autoriza su propio push. Al final, Setup ofrece llevar la política al host con bun run git:policy: primero lectura, después un dry run, y la escritura solo con tu sí.

05 · operación · push

La variable decide si la IA pregunta

Antes de pushear a una rama protegida, la skill resuelve git_strategy.policy.direct_push_to_protected (AGENTS.md, Critical Rule #4). La respuesta nunca está escrita en la regla: está en el valor.

Valor	Qué hace la IA
allowed	Pushea sin preguntar. El valor guardado es la autorización permanente; preguntar igual convertiría allowed en confirm.
confirm	Pregunta antes de cada push y espera un sí explícito.
forbidden	No pushea a la rama protegida: abre una rama de trabajo, la pushea y manda el cambio por PR.
bloque ausente o null	Se comporta como confirm: lo seguro es preguntar.

Antes del push

El estado elige el comando

Sin upstream: git push -u origin <rama>.
Upstream atrás: git push.
Upstream divergido: se detiene y pasa a conflictos. No fuerza.

Bypass de admin

Solo se ofrece, y con doble chequeo

Solo si policy.admin_bypass: true.
Te pregunta si de verdad eres admin: la skill no puede saber tu rol.
Te confirma la acción irreversible concreta.
Con false, nunca lo ofrece.

Qué ramas cuentan como protegidas sale de la estrategia: main siempre, la rama de integración cuando existe, develop en gitflow y release/* en enterprise. Sobre cualquiera de ellas, nunca --force, --force-with-lease ni --no-verify sin un pedido explícito tuyo y una rama que nadie más usa.

06 · Step 1b · paridad con el host

Lo declarado es intención; lo que manda es el host

El bloque policy registra lo que el equipo decidió. GitHub registra lo que se impone. Se desalinean, y la sorpresa llega en el peor momento: un merge rechazado a mitad de camino. Por eso la reconciliación es un script, no un procedimiento.

Comando	Lee el host	Escribe	Para qué
bun run git:policy plan	no	nada	Ver qué ruleset deriva del bloque.
bun run git:policy verify	sí	nada	Al primer push, PR o merge de la sesión. Sale con 1 ante un desvío no aceptado.
… verify --stamp	sí	meta.policy_verified y policy_source	Registrar la reconciliación cuando está limpia.
bun run git:policy apply	sí	nada (dry run)	Mostrar el payload exacto antes de proponer la escritura.
… apply --yes	sí	el ruleset del host	Escribir, con tu elección. Nunca para tapar un desvío que no leíste.

Lo que el script sabe

Dos mecanismos, y un push no prueba nada

Consulta la protección clásica y los rulesets. Un 404 en la clásica no significa "sin protección".
Un push que pasa no prueba que no haya regla: los admins la saltean y la regla sigue valiendo para el resto. Si el remoto dice Changes must be made through a pull request, fue un bypass.
require_code_owner_review sin archivo CODEOWNERS no es estricto: es imposible de cumplir, y cada merge termina siendo un bypass.

Ante un desvío

Se reporta, nunca se corrige solo

(a) corregir .agents/project.yaml para que coincida con el host;
(b) cambiar la configuración del host;
(c) aceptar la diferencia y anotar por qué en policy.accepted_divergences.
Cualquiera de las tres necesita tu elección.

# una divergencia aceptada: un campo del verify, con su razón git_strategy: policy: accepted_divergences: - field: main.direct_push_to_protected enforced: blocked (pull_request rule) accepted: <fecha de la firma> reason: por qué los dos lados difieren a propósito

Aceptada no es silenciada. verify la lista como ACCEPTED con su razón y sale con 0; --stamp registra policy_source: accepted, distinto de verified.

Una excepción vieja aparece sola. Una divergencia aceptada que ya no coincide con ningún desvío se reporta como nota, para que la lista no junte excepciones muertas.

apply no afloja nada sin permiso. Quitar una guarda, bajar las aprobaciones, apagar code-owner review o ampliar los métodos de merge exige --allow-loosening para esa renuncia concreta.

Lo no verificado se dice así. Con policy_source: declared, la IA no te dice qué exige el remoto: dice "declarado, no verificado".

07 · operaciones · branch y commit

Ramas con nombre propuesto, commits con una sola razón

La IA propone el nombre de la rama y el bloque de commits completo, y espera tu OK antes de ejecutar. Puedes aceptar, cambiar o rechazar cada uno.

Branch

Prefijo + key + slug

Prefijo por el cambio dominante: feat, fix, refactor, test, docs, chore, en ese orden de precedencia.
Con key: feat/PROJ-123-bulk-assign. Sin key: refactor/split-auth-utils.
Sale de la rama base que fija la estrategia.

Commit

Conventional, atómico, explícito

Un commit, una responsabilidad. Los tests van con el comportamiento que prueban.
feat(PROJ-123): add bulk-assign action.
Nunca git add -A ni git add .: cada ruta, por nombre.
Si un hook rechaza el commit: se arregla la causa y se hace un commit nuevo, nunca --amend.

feat(PROJ-123): add bulk-assign action Cuerpo opcional: el resultado, no la lista de archivos. Worktree: <nombre|primary> Session: <label>

Los trailers son forenses, no atribución. Las dos últimas líneas de todo commit que escribe una sesión de agente dicen qué checkout y qué sesión lo produjeron, copiadas de la línea AGENT IDENTITY: que inyecta el hook del prompt (unknown si no se resuelve). No nombran ninguna herramienta. Prohibido: "Generated with…", un Co-Authored-By: de una IA o cualquier trailer con marca como Claude-Session:. .husky/commit-msg corre scripts/check-commit-trailers.ts y avisa, sin bloquear.

Un trailer más puede ir arriba de esos dos. Cuando el gate de contratos de documentación nombra una región LINT.IfChange, las páginas que cita no se tocaron y siguen describiendo bien el comportamiento, el commit lleva Docs-Checked: <label> <motivo> encima de Worktree: y Session:. Nunca por reflejo y nunca sin motivo: una etiqueta sola no cuenta, y el pre-push y el CI bloquean el push sin ese trailer o sin las ediciones de las páginas.

08 · operación · pull request

Se abre con contexto completo y se detiene ahí

La base sale de la estrategia, el cuerpo se arma en el momento, y el merge queda como tu próximo paso explícito.

Base y título

La base es la que fija la estrategia (tabla de la sección 03). Si la cambias con --base, la IA te lo marca contra el default. El título sigue el formato del commit, con menos de 70 caracteres.

Cuerpo

Summary, Changes, Test Plan, Traceability (issue, rama, base, estrategia, worktree y sesión), Evidence y Risk. Lo que la skill no puede completar queda visible para que lo edites: no se borra en silencio. Te muestra cuerpo y base antes de enviarlos con gh pr create --body-file.

Etiquetas, revisores, draft

Te los pregunta. No inventa etiquetas que el repo quizás no tiene: si duda, las confirma con gh label list.

Cuántas aprobaciones faltan, y según quién

Con la política verificada dice "el host exige N aprobaciones en la base". Con la política solo declarada dice "declarado require_pr_reviews: N, no verificado contra el host".

Compuerta La skill no mergea nunca. Te deja el PR y el comando para cuando esté aprobado.

09 · operación · conflictos

Diagnóstico antes que arreglo

Un arreglo equivocado aquí cuesta horas. La IA mira git status, git diff --check y los archivos de estado de .git/ para saber qué pasó antes de proponer nada.

explicar la causa→ opciones por seguridad→ guiar paso a paso→ verificar→ cómo evitarlo

Merge y rebase

Contenido, renombres, rebase

Conflictos de contenido, de renombre o borrado, y de rebase o cherry-pick.

Ramas

Push rechazado, HEAD suelto

Ramas divergidas, push rechazado, detached HEAD, historias sin relación.

Trabajo local

Stash y hooks

Conflicto al aplicar un stash, o un pre-commit que rechazó el commit.

Ante la duda

Abortar gana

git merge --abort, git rebase --abort: abortar siempre le gana a adivinar.

Las opciones destructivas nunca se eligen en silencio. Force push, reset duro o abortar un merge con trabajo sin commitear se te presentan como opción, con su riesgo, y esperan tu decisión.

10 · Step 4 · PRs encadenados

Más de 400 líneas: se parte, y la decisión viaja con su traza

Arriba de ese presupuesto de review la detección de defectos cae fuerte. Antes de abrir PRs, la skill recorre un árbol de tres preguntas y se detiene en la primera hoja.

Pregunta	Si es sí	Si es no
Q1 · es mayormente mecánico? (renombre, formateo, código generado)	size-exception: un PR, con tu override y una línea Why size-exception:	sigue a Q2
Q2 · se parte en 2 a 4 tajadas independientes, cada una segura sola en la base?	stacked-to-main: PRs chicos sobre la base	sigue a Q3
Q3 · hay andamiaje compartido que un merge parcial rompería?	feature-branch-chain: una rama de integración, PRs hijos, un PR final	volver a descomponer la historia: es un olor de planificación

Chain strategy: feature-branch-chain Decision trace: Q1=No (lógica de dominio nueva, no un renombre) · Q2=No (la tajada 2 no compila sin los tipos de la 1) · Q3=Yes (esquema compartido que usan las tajadas 2 a 4) → feature-branch-chain Decided by: /git-flow-master §Chained-PR decision tree (branching-strategies.md)

Una etiqueta sola no es una decisión. /sprint-development bloquea su Stage 2 sobre esta respuesta y rechaza un nombre de estrategia sin traza. Cada respuesta lleva la razón de este cambio, y esta skill es la única autoridad que puede completar esas líneas. Si el diff real supera la estimación, se vuelve a decidir: no se estira el presupuesto en silencio.

11 · trabajo aislado

Una sesión, un worktree, una rama

Un worktree es un segundo directorio de trabajo sobre el mismo .git, con su propia rama y su propio índice. Sirve para dos sesiones de IA en paralelo, un hotfix con una feature abierta, o trabajo riesgoso que no quieres mezclar.

crear→ bun run worktree:provision→ trabajar→ bun run worktree:audit <wt> --rescue→ remover

Crear: git es el canon, el harness es un atajo

git worktree add ../dir -b feat/x main funciona en cualquier host. La herramienta propia de un harness (en Claude Code EnterWorktree, o un worktree administrado por Codex) es un camino del harness, nunca el canon del repo, y necesita los mismos dos pasos alrededor. OpenCode no tiene equivalente: usa git.

Provisionar antes de trabajar

Un worktree nuevo trae solo los archivos versionados. worktree:provision copia los insumos ignorados que no se pueden reconstruir (.env, .vercel/, settings locales), instala dependencias y crea el alias .claude/skills. La lista vive en código: PROVISION_COPIES en cli/lib/worktree.ts.

.session/ nunca se copia

El estado durable (planes, progreso, locks, reportes) vive en <<PRIMARY_ROOT>>, el checkout principal, y se cita por ruta absoluta desde el worktree. Una copia diverge en silencio y muere con el worktree.

Auditar antes de remover

worktree:audit es de solo lectura y sale con 1 mientras haya estado que vive solo en el worktree; --rescue lo copia al principal sin pisar nada. Con Orca, el orca.yaml versionado corre los dos pasos como hooks de setup y archive, pero el CLI salta el hook de archive salvo con --run-hooks; sin hooks, se corre bun run worktree:audit <wt> --rescue a mano.

Lo no versionado no viaja. Un archivo nuevo sin git add se queda en el directorio original: se mueve, o se commitea antes de crear el worktree.

El stash es de todo el repo. No sirve para pasar trabajo entre sesiones: commitea en tu rama.

La procedencia está en el commit. Los trailers Worktree: y Session: dicen quién escribió una rama huérfana. Un worktree viejo se reporta, nunca se borra si es de otra sesión.

12 · rieles de seguridad

Lo que la skill nunca hace

La lista completa vive en SKILL.md (Compact Rules, Critical rules y antipatrones). Estos son los que más se notan desde afuera.

No reescribe historia pusheada. Ni force push a una rama compartida, ni --amend o rebase sobre commits ya publicados: se agrega un commit nuevo.

No descarta cambios globales. Nunca git restore ., git checkout -- ., git reset --hard, un git stash sin rutas ni git clean -f: otra sesión puede estar en el mismo árbol. Solo rutas que modificó esta sesión (Critical Rule #13).

No commitea secretos. .env, credenciales o tokens en git son para siempre; por eso cada ruta se agrega por nombre.

No mergea ni encadena PRs sin nombrar la dependencia en el cuerpo de cada uno.

No cita ejemplos como configuración. Los bloques de references/ son ilustraciones; la respuesta sobre un proyecto sale de su propio .agents/project.yaml, citado.

No finge un PR. Si gh falta o no está autenticado, se detiene y te lo dice.

13 · dónde vive cada cosa

Los archivos dueños, no copias

El deck no repite valores: cada uno se lee en su dueño, que es lo que la skill también hace.

Archivo o comando	Qué resuelve
.agents/project.yaml → git_strategy	Estrategia, ramas, protegidas, decisiones, política, divergencias aceptadas y la procedencia en meta.
package.json	Los scripts git:policy, worktree:provision y worktree:audit.
.husky/commit-msg	El aviso de trailers, vía scripts/check-commit-trailers.ts.
cli/lib/worktree.ts · orca.yaml	Qué copia el provisionado y los hooks de setup y archive en Orca.
.agents/README.md · "Checkout roots"	Qué es <<REPO_ROOT>> y qué es <<PRIMARY_ROOT>>.
.agents/instructions/agent-project.md · "Git Strategy"	Solo un puntero al bloque, más el contexto en prosa de una divergencia aceptada.
.agents/skills/REGISTRY.md	Las Compact Rules de la skill que viajan en el briefing de un subagente.

14 · qué le dices a la IA

Invocarla en las tres terminales

La skill no tiene modos con nombre: la operación sale de tu frase, en español o en inglés. Muchas veces ni hace falta nombrarla.

Claude Code

/git-flow-master abre un PR /git-flow-master configura el flujo de git

La barra carga la skill; el resto de la frase elige la operación.

OpenCode

carga la skill git-flow-master: commit and push

Sin barra: nombras la skill en la frase.

Codex

carga la skill git-flow-master: tengo conflictos al hacer pull

Mismo patrón que OpenCode, en CLI o Desktop.

Si dices algo como…	Corre
"start work on PROJ-123" · "crear branch"	Branch
"commit this" · "commitear esto" · "commit and push"	Commit, y Push si lo pediste
"create PR" · "abrir PR"	Pull request
"fix conflict" · "push rejected" · "resolver conflicto"	Conflict
"split this PR" · "PR demasiado grande"	Árbol de PRs encadenados
"set up our git strategy" · "configura el flujo de git"	Strategy Setup

15 · con quién trabaja

A quién le pasa la posta, y quién se la pasa

El loop de la historia

/sprint-development

Implementa y revisa; le pide a esta skill el PR, la cadena con su traza y la política de push. Ver el deck.

TDD dentro de una feature

/unit-testing

Rojo, verde, refactor; los tests van en el mismo commit que el comportamiento. Ver el deck.

Backlog y refinamiento

/product-management

Si el pedido es sobre historias y no sobre git, va ahí. Ver el deck.

Jira desde un commit o un PR

/acli

Las operaciones de Jira que dispara un commit o un PR.

Flotas de workers en worktrees

/orca-orchestration

Un conductor que lanza workers supervisados, cada uno en su worktree; Orca crea, provisiona y audita.

Para leer más: .agents/skills/git-flow-master/SKILL.md y su carpeta references/: el catálogo de estrategias, la mecánica de Strategy Setup, la paridad de rulesets, los commits, los PRs, los conflictos y los worktrees, una referencia por tema.