Flujo De Trabajo

Cómo se mueve un cambio desde que lo empiezas hasta que está mergeado, y las convenciones de git/worktrees que usa el equipo.

De Ticket A Producción (Vista Rápida)

El detalle de la última etapa (la que más se olvida) está en Despliegue. Mergear no termina el trabajo si tocaste un frontend, la app de conductores o Zoho.

Git Y Branches

• Las ramas siguen el patrón tipo/<slug>-<ticket-id> (ej. fix/apphang-signature-photos-86e1y8cch).
• Los commits, pushes y merges son explícitos: no se pushea ni se mergea sin que lo pidas.
• Si trabajas en la rama por defecto, primero crea una rama.
• Mensajes de commit en español (consistente con el repo).

Worktrees

El equipo trabaja features en git worktrees dentro de .claude/worktrees/<slug>-<ticket-id>/.

Los worktrees NO tienen node_modules

No corras pnpm install, typecheck ni build dentro de un worktree:

• Instalar ahí es lento y satura la máquina al punto de romper el shell (todo comando devuelve exit 1 sin salida hasta matar el install).
• El flujo correcto es: desarrollar el cambio en el worktree y probarlo en el checkout principal, donde sí están las dependencias.

Limpieza después de mergear

Cuando el PR de una rama-en-worktree se mergea, quedan colgados tres artefactos (main local atrasado, el worktree y la branch local). Límpialos en este orden, desde la raíz del repo (no desde el worktree, que vas a borrar):

# 1. FF del main local (--ff-only falla limpio si hubiera divergencia)
git pull --ff-only

# 2. Remover el worktree (libera disco y el lock de la branch)
git worktree remove .claude/worktrees/<slug>-<ticket-id>

# 3. Borrar la branch local (-d valida que esté mergeada)
git branch -d worktree-<slug>-<ticket-id>

Errores típicos y antídotos:

• Unable to create '.../index.lock': File exists → revisa ps aux | grep git; si no hay proceso activo, rm .git/index.lock.
• branch -d dice "not fully merged" → el local nunca vio el merge commit; git branch -D lo fuerza (seguro porque el código ya está en origin/main).
• worktree remove "contains modified or untracked files" → --force solo tras confirmar que no pierdes trabajo.

ClickUp (slash commands)

No es regla fija — es un flujo propuesto

Esto no es obligatorio: cada dev puede tener su propio workflow. Lo que sigue es el flujo que propone y usa el autor de esta guía para orquestar el día a día contra ClickUp. Tómalo como referencia o punto de partida, no como norma del equipo.

El día a día contra ClickUp se orquesta con slash commands (.claude/commands/). No pushean código ni mergean PRs — solo cambian estado en ClickUp y postean comentarios.

Comando	Qué hace
/standup	Recap de ayer + plan de hoy desde tickets y git. No cambia estados.
/pick <id>	Mueve el ticket a en desarrollo y abre research del código.
/done <id>	Mueve a listo para revisión y comenta commits/branch/archivos/qué probar. Avisa si hay commits sin pushear.
/block <id>	Mueve a en espera de info con la pregunta abierta.
/eod	Cierre del día y snapshot del kanban.

Los tickets viven en la lista Tickets RednBlue en ClickUp.

Checks Y Deuda Conocida

Antes de abrir PR, lo razonable es correr los checks del workspace que tocaste. Pero hay deuda heredada que falla sin que tu cambio esté mal:

Check	Estado	Lectura
pnpm build (raíz)	✅ Debe pasar	Si rompe, tu cambio rompió algo.
drivers-backend typecheck	⚠️ Deuda estricta de TS	Falla aunque build y runtime estén OK. No lo tomes como bloqueante salvo que tu cambio agregue errores nuevos.
clients-backend lint	⚠️ Deuda de Biome/estilo	Falla aunque tests, typecheck y wrangler dry-run pasen.

Cómo validar de verdad cada tipo de app:

• Backends Node (core/drivers): vitest (pnpm --filter <app> test). core-backend además corre el mirror de schema en ... check.
• clients-backend: vitest (worker tests) + wrangler dry-run (su build es justamente wrangler deploy --dry-run).
• engine-backend: pytest (pnpm test:engine-backend) y mypy. Compila y prueba desde apps/engine-backend.
• Apps Expo (drivers-app, etc.): typecheck primero; para cambios de comportamiento nativo, build en simulador/dispositivo.
• Frontends (dash-web, client-tracking-view): tsc --noEmit (no tienen suite de tests).
• Cambios de Cloudflare: wrangler dry-run + worker tests antes de deploy.