/bax

BAX Dev Workflow

Framework de trabajo estándar para todos los proyectos BAX. Cubre el ciclo completo desde el inicio del trabajo hasta el PR listo para QA.

Uso

/bax            # Flujo interactivo — pregunta por el issue al inicio
/bax BAX-123   # Inicia directamente con el issue BAX-123

---

FASE 1 — Inicio (antes de codear)

Paso 1 — Asociar Issue de Linear

Validación de formato: El ID debe seguir el patrón BAX- + número (ej: BAX-123). Rechazar cualquier entrada que no cumpla este formato antes de llamar a Linear.

Si se ejecutó /bax BAX-123:

1. Buscar el issue con mcp__claude_ai_Linear__get_issue(id: "BAX-123")
2. Si no existe → informar al dev y detener el flujo
3. Si existe → mostrar: título, descripción, labels, estado actual, proyecto

Si se ejecutó /bax sin argumentos, preguntar al dev:

¿Estás trabajando con un issue de Linear existente?

• [1] Sí, tengo el ID → pedirlo, validar formato y existencia con get_issue
• [2] Sí, pero no sé el ID → buscar con mcp__claude_ai_Linear__list_issues (pedir keywords)
• [3] No, trabajo sin issue → continuar al Paso 2 (el issue se crea en la Fase 2)

Si la búsqueda devuelve múltiples resultados, mostrarlos numerados y pedir al dev que elija.

Validación de assignee: Una vez obtenido el issue, verificar quién está asignado:

1. Buscar en memoria (MEMORY.md del proyecto) si existe linear_email: <email> del dev actual
   • Si no existe: preguntar ¿Cuál es tu email de Linear?, guardar en MEMORY.md como linear_email: <email>
   • Si existe: usar ese email directamente sin preguntar
2. Llamar mcp__claude_ai_Linear__list_users y buscar el usuario con ese email
3. Comparar con el assignee del issue:
   • Sin assignee → ¿Querés asignarte este issue? [S/N]
   • Asignado a otra persona → Este issue está asignado a [nombre]. ¿Querés autoasignártelo? [S/N]
   • Ya asignado al dev actual → continuar sin preguntar
4. Si confirma → mcp__claude_ai_Linear__save_issue(id, assignee: "me")

Mover a In Progress: Una vez resuelto el assignee, preguntar:

¿Querés mover este issue a In Progress? [S/N]

• Si confirma → mcp__claude_ai_Linear__save_issue(id, state: "8a6cbd87-684c-4fe7-9708-bd9fbbd3ade2")
• Si no → continuar sin cambiar el estado

---

Paso 2 — Setup de Rama Git

Confirmar repo activo: Antes de ejecutar cualquier comando git, preguntar al dev:

¿En qué repo estás trabajando? (ej: bax-business-web, bax-business, bax-mobile)

Usar ese directorio para todos los comandos git siguientes.

Diagnóstico previo obligatorio:

git status
git branch --show-current
git stash list

1. Verificar si hay stash del issue actual:

• Revisar git stash list buscando entradas cuyo nombre de rama contenga el ID del issue (ej: bax-286)
• Si existe → informar: Tenés cambios guardados (stash) para BAX-XXX. ¿Querés recuperarlos? [S/N]
  • Si sí → git checkout {rama-del-issue} + git stash pop → saltear creación de rama
  • Si no → continuar con diagnóstico normal

2. Evaluar estado actual del repo:

Situación	Acción
En development, sin cambios	✓ Continuar normalmente
En development, con cambios sin commitear	⚠️ [1] Hacer stash y continuar [2] Cancelar
En rama del mismo issue, sin cambios	✓ Ya tenés esta rama abierta. ¿Continuás en ella? [S/N] — si sí, saltear creación
En rama del mismo issue, con cambios sin commitear	✓ Tenés cambios en progreso. ¿Continuás desde acá? [S/N] — si sí, saltear creación
En rama de otro issue, sin cambios (sin PR)	⚠️ Verificar con gh pr list si ya tiene PR. Si no tiene: [1] Cerrar este ciclo primero (PR + Linear) [2] Abrir nueva rama [3] Cancelar. Si ya tiene PR: [1] Abrir nueva rama [2] Cancelar
En rama de otro issue, con cambios sin commitear	⚠️ [1] Cerrar este ciclo (commit + PR + Linear) [2] Stash y nueva rama [3] Cancelar

• Cerrar ciclo → ejecutar Fase 2 completa para rama actual, luego retomar Fase 1 del nuevo issue
• Stash → git stash y continuar. Al llegar a la nueva rama, hacer git stash pop automáticamente si el stash era de config local
• Cancelar → detener el flujo

Crear la rama (solo si el diagnóstico lo permite):

git checkout development
git pull origin development
git checkout -b {username}/{issue-id}-{descripcion-corta}

Naming convention:

• Con issue: username/bax-267-balance-usd
• Sin issue: username/descripcion-corta
• Todo en minúscula, guiones, descripción de 2-4 palabras

Al terminar: informar al dev que el setup está listo y puede comenzar a codear. El flujo continúa en la Fase 2 cuando los cambios estén listos.

---

FASE 2 — Cierre (después de codear)

Paso 3 — Commits

Usar Conventional Commits. El tipo se elige según el label del issue de Linear:

Label Linear	Tipo de commit
Bug	fix
Feature	feat
Improvement	refactor o feat (preguntar al dev)
Sin label	preguntar al dev

Formato: tipo(BAX-XXX): descripción breve en minúscula

Archivos a NO commitear nunca:

• .env, .env.local, .env.* — variables de entorno locales
• Archivos de configuración con cambios solo para desarrollo local
• package-lock.json / yarn.lock si no hubo cambios reales de dependencias

---

Paso 4 — Crear Pull Request

Verificar si ya existe un PR para esta rama con gh pr list --head {rama}:

• Si ya existe → mostrar la URL existente, no crear uno nuevo, continuar al Paso 5

Magic word según label del issue:

Label Linear	Magic Word
Bug	Fixes
Feature	Closes
Improvement	Closes
Sin label	Closes

Título: mismo formato que el commit principal.

Body:

## Summary
- Bullet points concisos describiendo qué se cambió y por qué

## Linear
Fixes BAX-XXX

Comando:

gh pr create \
  --base development \
  --title "tipo(BAX-XXX): descripción" \
  --body "$(cat <<'EOF'
## Summary
- ...

## Linear
Fixes BAX-XXX
EOF
)"

Si el repo tiene CI obligatorio, el PR no se puede mergear hasta que pase. Avisar al dev si los checks están fallando.

---

Paso 5 — Actualizar Linear

5a — Si había issue existente

1. Leer primero la descripción actual con mcp__claude_ai_Linear__get_issue
2. Appendear al final (NUNCA reemplazar el contenido original):

---

## Solución implementada

[Descripción clara de qué se hizo y por qué]

**PR:** [URL del PR creado]

## Test Cases
- [ ] [caso de prueba 1]
- [ ] [caso de prueba 2]
- [ ] [agregar más según corresponda]

3. Actualizar con mcp__claude_ai_Linear__save_issue:
   • description: contenido original + sección nueva

5b — Si NO había issue (trabajo sin ticket)

Crear con mcp__claude_ai_Linear__save_issue:

• title: título descriptivo del cambio
• team: el team correspondiente
• description: qué se hizo + link al PR + test cases
• labels: según tipo de cambio (Bug / Feature / Improvement)

Linkear el PR al issue con links.

---

Paso 6 — Resumen final

Al completar la Fase 2, mostrar siempre un resumen:

✅ Ciclo cerrado para BAX-XXX

  Rama:    {nombre-de-rama}
  PR:      {url-del-pr}
  Linear:  {url-del-issue} → actualizado

---

Reglas Generales

Git

• Siempre partir de development para cada nueva rama
• Una rama por issue — nunca encadenar ramas
• PR siempre contra development

Linear

• Nunca reemplazar el contenido original de un issue
• Siempre leer antes de actualizar, appendear al final
• Un issue = un PR (idealmente)

Commits

• Seguir Conventional Commits estrictamente
• Un commit por cambio lógico
• Mensajes en el idioma predominante del repo

---

Tipos de Conventional Commits

Tipo	Cuándo usarlo
fix	Corrección de un bug
feat	Nueva funcionalidad
refactor	Mejora sin cambio de comportamiento
chore	Mantenimiento, dependencias, configuración
docs	Documentación
test	Agregar o modificar tests
style	Cambios de formato/estilo sin lógica
perf	Mejoras de performance

---

Flujo Resumido

/bax [BAX-XXX]
      │
      ▼
[FASE 1] Asociar issue ──► Assignee ──► In Progress ──► Setup de rama
      │
      │   (dev codea)
      │
      ▼
[FASE 2] Commits ──► PR ──► Linear (actualizado) ──► Resumen ✅