Git Branch Strategy

Guia de Estrategia de Branching Git

Version: 1.0.0 | Marzo 2026 Framework: AI Software Factory OS v7.7 Aplica a: El framework (baseline repo) + proyectos que lo consumen

---

A. Estrategia del Framework (baseline repo)

Branches

main (estable, tageada)               ← Proyectos consumen ESTO via subtree
  ↑
  │  merge --no-ff (requiere tests pass)
  │
develop (integracion)                  ← Trabajo diario se integra aqui
  ↑
  │  merge del worktree al terminar sesion
  │
claude/* (worktrees efimeros)          ← Sesiones de Claude Code (auto-creados)

Branch	Proposito	Proteccion	Merge policy
main	Release estable. Proyectos apuntan aqui.	Tags semver. Solo merge de develop.	--no-ff con commit descriptivo
develop	Integracion. Acumula features entre releases.	Tests deben pasar. Push directo OK.	Fast-forward desde claude/*
claude/*	Worktrees efimeros de sesiones Claude Code.	Ninguna. Se eliminan al cerrar.	Fast-forward a develop

Tags semver

v7.7.0        ← Release actual
v7.7.1        ← Patch (fixes, docs)
v7.8.0        ← Minor (features, scripts, guias nuevas)
v8.0.0        ← Major (cambios en core methodology, breaking changes)

Regla de versionado:

• Cambios en framework/core/ → version major
• Cambios en scripts/, guides/, reference/, accelerators/ → version minor
• Fixes, clarificaciones, doc sync → version patch

Proceso de release

# 1. En develop: verificar que tests pasan
git checkout develop
python tests/test_framework.py -v

# 2. Merge a main
git checkout main
git merge develop --no-ff -m "release: v7.8.0 — descripcion breve"

# 3. Tagear
git tag -a v7.8.0 -m "v7.8.0 — descripcion del release"

# 4. Push
git push origin main --tags

# 5. Volver a develop
git checkout develop
git merge main  # Sincronizar

Consumo desde proyectos

Los proyectos que usan el framework como subtree:

# Pinear a version estable (recomendado para produccion)
cd mi-proyecto/baseline
git fetch && git checkout v7.7.0

# Seguir latest (para early adopters)
cd mi-proyecto/baseline
git pull origin main

# Actualizar subtree
cd mi-proyecto
git add baseline && git commit -m "chore: update framework to v7.8.0"

Limpieza de branches

Las branches claude/* se limpian periodicamente:

# Listar branches locales claude/* ya mergeados
git branch --merged develop | grep "claude/"

# Eliminar branches mergeados
git branch --merged develop | grep "claude/" | xargs git branch -d

---

B. Estrategia por Track para Proyectos

Track Solo — Trunk-Based Simplificado

Para 1 persona con AI assistant. Minima ceremonia.

main
  ↑
  │  merge directo (squash)
  │
feat/nombre-feature        ← 1 branch por feature
fix/nombre-fix             ← 1 branch por fix

Reglas:

• main siempre desplegable
• 1 branch activa a la vez (secuencial)
• Squash merge al completar
• Tests deben pasar antes de merge
• No se necesita develop
• Gates: self-review (checklist en PR description)

Cuando un FAB trabaja:

main
  ↑
  │  PR con gate check
  │
fab/intent-001             ← FAB crea branch por intent

Track Lean — Main + Develop + Feature

Para equipo pequeno (2-5 personas) con FABs.

main (produccion)
  ↑
  │  PR + gate check + code review
  │
develop (integracion)
  ↑
  ├── feat/auth-module      ← Humano o FAB
  ├── feat/search-api       ← Humano o FAB
  ├── fix/latency-issue     ← Fix
  └── fab/intent-002        ← FAB autonomo

Reglas:

• main = produccion (protegido, solo PRs desde develop)
• develop = integracion (PRs desde feature branches)
• Feature branches: feat/, fix/, chore/, fab/
• Code review requerido para merge a develop
• Gate check automatico en PR a main
• FABs crean branches fab/intent-NNN con worktrees aislados

Conflict resolution: pr_per_agent (default)

Track Full — Main + Develop + Release + Swarming

Para equipos grandes (5+) con multiples FABs en paralelo.

main (produccion)
  ↑
  │  merge --no-ff + tag
  │
release/v1.2.0 (estabilizacion)
  ↑
  │  cherry-pick fixes
  │
develop (integracion)
  ↑
  ├── feat/auth ─────────── Agent-Auth (bounded context)
  ├── feat/core ─────────── Agent-Core (bounded context)
  ├── feat/ai ──────────── Agent-AI (bounded context)
  ├── fab/intent-003 ────── FAB autonomo
  │
  └── MERGE QUEUE ← serializado, 1 merge a la vez

Reglas:

• main = produccion (protegido, solo desde release branches)
• release/vX.Y.Z = estabilizacion pre-deploy (solo fixes, no features)
• develop = integracion diaria
• Feature branches por bounded context (swarming pattern)
• Merge queue obligatorio (GitHub Merge Queue o custom)
• Gate checks automaticos en cada PR
• FABs usan worktrees aislados via fab-workspace-setup.sh

Conflict resolution: lead_merges (lead FAB o Tech Lead controla merges)

Merge queue order:

1. Schema/migrations primero (DB)
2. Contratos/APIs segundo
3. Logica de negocio tercero
4. UI/frontend ultimo

Tabla resumen

Aspecto	Solo	Lean	Full
Branches principales	main	main + develop	main + develop + release
Feature branches	feat/, fix/	feat/, fix/, fab/	feat/, fix/, fab/ + bounded context
Merge policy	Squash directo	PR + review	PR + review + merge queue
Gate enforcement	Self-review	CI automatico	CI + merge queue + human gate
FAB isolation	Branch por intent	Worktree por FAB	Worktree + bounded context
Conflict strategy	N/A (1 persona)	pr_per_agent	lead_merges
Release process	Tag en main	develop → main + tag	develop → release → main + tag

---

C. FAB Branch Management

Creacion de workspace FAB

# fab-workspace-setup.sh crea:
fab-workspace-setup.sh --project mi-proyecto --intent INTENT-2026-001

# Resultado:
# ../fab-mi-proyecto/          ← Worktree aislado
#   └── branch: fab/intent-001  ← Branch dedicado

Ciclo de vida de branch FAB

1. CREAR     fab/intent-NNN     (fab-workspace-setup.sh)
2. EJECUTAR  F04 → F09          (FAB headless, checkpoints cada 60 min)
3. PR        fab/intent-NNN → develop  (al completar)
4. REVIEW    Gate check + code review
5. MERGE     Squash merge a develop
6. CLEANUP   Eliminar branch + worktree

Conflict resolution strategies

Configurar en .fab-config.yaml:

coordination:
  conflict_strategy: "pr_per_agent"  # Opciones:
  # pr_per_agent      — Cada FAB crea PR independiente (default)
  # sequential_rebase — FABs rebase en orden (linear history)
  # lead_merges       — Solo lead FAB mergea (control centralizado)

Estrategia	Cuando usar	Ventaja	Riesgo
pr_per_agent	Lean track, FABs independientes	Simple, cada FAB es autonomo	Merge conflicts si tocan mismos archivos
sequential_rebase	Lean track, historia lineal	Clean history	Lento si hay muchos FABs
lead_merges	Full track, swarming	Control total, sin conflictos	Bottleneck en el lead

Proteccion de archivos compartidos

Cuando multiples FABs trabajan en paralelo, proteger archivos compartidos:

.fab-coordination.yaml

shared_files:
  - "project/project-config.yaml"     # Solo lead modifica
  - "project/data_classification.yaml" # Solo data_steward modifica
  - "project/F05_contracts/.openspec/" # Solo spec_writer modifica

Usar fab-coordinator.py conflict-detect para verificar antes de merge:

python3 scripts/fab-coordinator.py --project-dir . conflict-detect

---

D. Integracion con Gates

Cada gate del ADLC corresponde a un punto de merge:

Gate	Trigger	Branch flow	Reviewer
Gate A (Strategy)	PR con F01 artifacts	feat/strategy → develop	Product Owner
Gate B (Domain)	PR con F02 artifacts	feat/domain → develop	Tech Lead
Gate C (Architecture)	PR con F04 artifacts	feat/architecture → develop	Architect (puede ser auto)
Gate D (Contracts)	PR con F05 artifacts	feat/contracts → develop	Tech Lead (puede ser auto)
Gate E (TEVV)	PR con F07 results	fab/intent → develop	QA (puede ser auto si confidence >= 0.9)
Gate F (Security)	PR con F08 artifacts	develop → main (o release)	Security + human required

CI automatico (.github/workflows/gates.yml):

• Corre compliance-linter.py, artifact-validator.py, fab-gate-check.py en cada PR
• Comenta el PR con resultado del gate
• Bloquea merge si gate falla

---

Companion del AI-First Engineering Framework v7.7 See: git_conventions.md, Swarming_Strategy_Merge_Wall_Guide.md, fab-workspace-setup.sh